1findscu(1) OFFIS DCMTK findscu(1)
2
6 findscu - DICOM query (C-FIND) SCU
7
10 findscu [options] peer port [dcmfile-in...]
11
13 The findscu application implements an SCU for the Query/Retrieve
14 Service Class and the Basic Worklist Management Service Class. findscu
15 only supports query functionality using the C-FIND message. It sends
16 query keys to an SCP and awaits responses. The application can be used
17 to test SCPs of the Query/Retrieve and Basic Worklist Management
18 Service Classes.
19
21 peer hostname of DICOM peer
22 port tcp/ip port number of peer
24 dcmfile-in DICOM query file(s)
26
28 general options
29 -h --help
30 print this help text and exit
31 --version
33 print version information and exit
34 --arguments
36 print expanded command line arguments
37 -q --quiet
39 quiet mode, print no warnings and errors
40 -v --verbose
42 verbose mode, print processing details
43 -d --debug
45 debug mode, print debug information
46 -ll --log-level [l]evel: string constant
48 (fatal, error, warn, info, debug, trace)
49 use level l for the logger
50 -lc --log-config [f]ilename: string
52 use config file f for the logger
53 network options
55 override matching keys:
56 -k --key [k]ey: gggg,eeee="str", path or dictionary name="str"
58 override matching key
59 query information model:
61 -W --worklist
63 use modality worklist information model (default)
64 -P --patient
66 use patient root information model
67 -S --study
69 use study root information model
70 -O --psonly
72 use patient/study only information model
73 application entity titles:
75 -aet --aetitle [a]etitle: string
77 set my calling AE title (default: FINDSCU)
78 -aec --call [a]etitle: string
80 set called AE title of peer (default: ANY-SCP)
81 post-1993 value representations:
83 +u --enable-new-vr
85 enable support for new VRs (UN/UT) (default)
86 -u --disable-new-vr
88 disable support for new VRs, convert to OB
89 proposed transmission transfer syntaxes:
91 -x= --propose-uncompr
93 propose all uncompressed TS, explicit VR
94 with local byte ordering first (default)
95 -xe --propose-little
97 propose all uncompressed TS, explicit VR
98 little endian first
99 -xb --propose-big
101 propose all uncompressed TS, explicit VR
102 big endian first
103 -xd --propose-deflated
105 propose deflated explicit VR little endian TS
106 and all uncompressed transfer syntaxes
107 -xi --propose-implicit
109 propose implicit VR little endian TS only
110 deflate compression level (only with --propose-deflated):
112 +cl --compression-level [l]evel: integer (default: 6)
114 0=uncompressed, 1=fastest, 9=best compression
115 other network options:
117 -to --timeout [s]econds: integer (default: unlimited)
119 timeout for connection requests
120 -ta --acse-timeout [s]econds: integer (default: 30)
122 timeout for ACSE messages
123 -td --dimse-timeout [s]econds: integer (default: unlimited)
125 timeout for DIMSE messages
126 -pdu --max-pdu [n]umber of bytes: integer (4096..131072)
128 set max receive pdu to n bytes (default: 16384)
129 --repeat [n]umber: integer
131 repeat n times
132 --abort
134 abort association instead of releasing it
135 --cancel [n]umber: integer
137 cancel after n responses (default: never)
138 transport layer security (TLS) options
140 transport protocol stack:
141 -tls --disable-tls
143 use normal TCP/IP connection (default)
144 +tls --enable-tls [p]rivate key file, [c]ertificate file: string
146 use authenticated secure TLS connection
147 +tla --anonymous-tls
149 use secure TLS connection without certificate
150 private key password (only with --enable-tls):
152 +ps --std-passwd
154 prompt user to type password on stdin (default)
155 +pw --use-passwd [p]assword: string
157 use specified password
158 -pw --null-passwd
160 use empty string as password
161 key and certificate file format:
163 -pem --pem-keys
165 read keys and certificates as PEM file (default)
166 -der --der-keys
168 read keys and certificates as DER file
169 certification authority:
171 +cf --add-cert-file [c]ertificate filename: string
173 add certificate file to list of certificates
174 +cd --add-cert-dir [c]ertificate directory: string
176 add certificates in d to list of certificates
177 security profile:
179 +px --profile-bcp195
181 BCP 195 TLS Profile (default)
182 +py --profile-bcp195-nd
184 Non-downgrading BCP 195 TLS Profile
185 +pb --profile-basic
187 Basic TLS Secure Transport Connection Profile (retired)
188 +pa --profile-aes
190 AES TLS Secure Transport Connection Profile (retired)
191 +pn --profile-null
193 Authenticated unencrypted communication
194 (retired, was used in IHE ATNA)
195 ciphersuite:
197 +cc --list-ciphers
199 show list of supported TLS ciphersuites and exit
200 +cs --cipher [c]iphersuite name: string
202 add ciphersuite to list of negotiated suites
203 pseudo random generator:
205 +rs --seed [f]ilename: string
207 seed random generator with contents of f
208 +ws --write-seed
210 write back modified seed (only with --seed)
211 +wf --write-seed-file [f]ilename: string (only with --seed)
213 write modified seed to file f
214 peer authentication:
216 -rc --require-peer-cert
218 verify peer certificate, fail if absent (default)
219 -ic --ignore-peer-cert
221 don't verify peer certificate
222 output options
224 general:
225 -od --output-directory [d]irectory: string (default: ".")
227 write output files to existing directory d
228 automatic data correction:
230 +dc --enable-correction
232 enable automatic data correction
233 -dc --disable-correction
235 disable automatic data correction (default)
236 C-FIND responses:
238 +sr --show-responses
240 always output responses to the logger
241 -sr --hide-responses
243 do not output responses to the logger
244 -X --extract
246 extract responses to DICOM file (rsp0001.dcm...)
247 -Xx --extract-xml
249 extract responses to XML file (rsp0001.xml...)
250 -Xs --extract-xml-single [f]ilename: string
252 extract all responses to given XML file f
253
255 Each file supplied on the command line will be sent to the SCP as part
256 of a C-FIND request. The query file must be a valid DICOM data set
257 containing the dataset part of a C-FIND-RQ message. The query file
258 could, for instance, be created with the dump2dcm utility from a script
259 like the following example:
260 # query patient names and IDs
262 (0008,0052) CS [PATIENT] # QueryRetrieveLevel
263 (0010,0010) PN [] # PatientName
264 (0010,0020) LO [] # PatientID
265 Individual attributes of each file sent can be modified or supplemented
267 using the -k option. For example the command:
268 findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
270 will, when sent to the SCP caesar at TCP/IP port 5678, cause any
272 PatientName attribute in patqry.dcm to have the value 'HEWETT*'. If
273 such an attribute is present it will be replaced, if absent it will be
274 inserted. The -k option can be present more than once. The value part
275 (after the '=') may be absent causing the attribute to be sent with
276 zero length.
277 In earlier versions of findscu, the tag keys were specified without
279 braces around group and element number, e. g. '0010,0010' instead of
280 '(0010,0010)'. It is recommended switching to the new syntax; however,
281 the old syntax is still working.
282 Also -k accepts dictionary names instead of element tags for specifying
284 DICOM elements. For example, the findscu call above then reads like
285 this:
286 findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
288 It is also possible to specify sequences, items and nested attributes
290 using the -k option. In these cases, a special 'path' notation has to
291 be used, e. g.
292 findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
294 This call queries a worklist server at host caesar for any planned
296 procedures for CT modalities by specifying tag (0040,0100) 'Scheduled
297 Procedure Step Sequence' and an attribute 'Modality' in the first item
298 of this sequence with value 'CT'. Details on this path notation can be
299 found in the documentation of dcmodify.
300 If no file is specified on the command line, the query must be
302 specified completely with one or more -k options. If multiple query
303 files are provided, findscu will send multiple C-FIND requests to the
304 SCP.
305 Each set of response identifiers received will be output to the logger
307 unless option --hide-responses, any of the below --extract variants,
308 --quiet or an appropriate logger configuration is used. In such cases,
309 the output to the logger can be enforced with option --show-responses.
310 In addition, the response datasets can also be extracted as individual
312 DICOM files (using option --extract) or XML files (using option
313 --extract-xml). The output format of the latter is described by the
314 file dcm2xml.dtd (starting with top-level element 'data-set').
315 Alternatively, all response datasets of an association can be extracted
317 to a single XML file using option --extract-xml-single. The top-level
318 element of the XML document is 'responses' (with a 'type' attribute of
319 'C-FIND'). The individual datasets are stored as described above. If
320 support for character set conversion is enabled, UTF-8 encoding is
321 used, i.e. all datasets are converted to UTF-8 encoding (which is
322 strongly recommended in order to avoid issues with non-ASCII characters
323 when different character sets are used).
324 DICOM Conformance
326 The findscu application supports the following SOP Classes as an SCU:
327 FINDPatientRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.1.1
329 FINDStudyRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.2.1
330 FINDPatientStudyOnlyQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.3.1
331 FINDModalityWorklistInformationModel 1.2.840.10008.5.1.4.31
332 The findscu application will propose presentation contexts for one of
334 the abovementioned supported SOP Classes depending on command line
335 options (-P, -S, -O or -W). Basically, the following transfer syntaxes
336 are supported:
337 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
339 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
340 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
341 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
342 (*) if compiled with zlib support enabled (see --version output)
344 Which transfer syntaxes are actually proposed in what order, can be
346 specified with the --propose options.
347 The findscu application does not support extended negotiation.
349
351 The level of logging output of the various command line tools and
352 underlying libraries can be specified by the user. By default, only
353 errors and warnings are written to the standard error stream. Using
354 option --verbose also informational messages like processing details
355 are reported. Option --debug can be used to get more details on the
356 internal activity, e.g. for debugging purposes. Other logging levels
357 can be selected using option --log-level. In --quiet mode only fatal
358 errors are reported. In such very severe error events, the application
359 will usually terminate. For more details on the different logging
360 levels, see documentation of module 'oflog'.
361 In case the logging output should be written to file (optionally with
363 logfile rotation), to syslog (Unix) or the event log (Windows) option
364 --log-config can be used. This configuration file also allows for
365 directing only certain messages to a particular output stream and for
366 filtering certain messages based on the module or application where
367 they are generated. An example configuration file is provided in
368 <etcdir>/logger.cfg.
369
371 All command line tools use the following notation for parameters:
372 square brackets enclose optional values (0-1), three trailing dots
373 indicate that multiple values are allowed (1-n), a combination of both
374 means 0 to n values.
375 Command line options are distinguished from parameters by a leading '+'
377 or '-' sign, respectively. Usually, order and position of command line
378 options are arbitrary (i.e. they can appear anywhere). However, if
379 options are mutually exclusive the rightmost appearance is used. This
380 behavior conforms to the standard evaluation rules of common Unix
381 shells.
382 In addition, one or more command files can be specified using an '@'
384 sign as a prefix to the filename (e.g. @command.txt). Such a command
385 argument is replaced by the content of the corresponding text file
386 (multiple whitespaces are treated as a single separator unless they
387 appear between two quotation marks) prior to any further evaluation.
388 Please note that a command file cannot contain another command file.
389 This simple but effective approach allows one to summarize common
390 combinations of options/parameters and avoids longish and confusing
391 command lines (an example is provided in file <datadir>/dumppat.txt).
392
394 The findscu utility will attempt to load DICOM data dictionaries
395 specified in the DCMDICTPATH environment variable. By default, i.e. if
396 the DCMDICTPATH environment variable is not set, the file
397 <datadir>/dicom.dic will be loaded unless the dictionary is built into
398 the application (default for Windows).
399 The default behavior should be preferred and the DCMDICTPATH
401 environment variable only used when alternative data dictionaries are
402 required. The DCMDICTPATH environment variable has the same format as
403 the Unix shell PATH variable in that a colon (':') separates entries.
404 On Windows systems, a semicolon (';') is used as a separator. The data
405 dictionary code will attempt to load each file specified in the
406 DCMDICTPATH environment variable. It is an error if no data dictionary
407 can be loaded.
408
410 <datadir>/dcm2xml.dtd - Document Type Definition (DTD) file
411
413 movescu(1), dump2dcm(1), dcmodify(1)
414
416 Copyright (C) 1994-2018 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
417 Germany.
418Version 3.6.4 Thu Nov 29 2018 findscu(1)