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 -ts --socket-timeout [s]econds: integer (default: 60)
122 timeout for network socket (0 for none)
123 -ta --acse-timeout [s]econds: integer (default: 30)
125 timeout for ACSE messages
126 -td --dimse-timeout [s]econds: integer (default: unlimited)
128 timeout for DIMSE messages
129 -pdu --max-pdu [n]umber of bytes: integer (4096..131072)
131 set max receive pdu to n bytes (default: 16384)
132 --repeat [n]umber: integer
134 repeat n times
135 --abort
137 abort association instead of releasing it
138 --cancel [n]umber: integer
140 cancel after n responses (default: never)
141 transport layer security (TLS) options
143 transport protocol stack:
144 -tls --disable-tls
146 use normal TCP/IP connection (default)
147 +tls --enable-tls [p]rivate key file, [c]ertificate file: string
149 use authenticated secure TLS connection
150 +tla --anonymous-tls
152 use secure TLS connection without certificate
153 private key password (only with --enable-tls):
155 +ps --std-passwd
157 prompt user to type password on stdin (default)
158 +pw --use-passwd [p]assword: string
160 use specified password
161 -pw --null-passwd
163 use empty string as password
164 key and certificate file format:
166 -pem --pem-keys
168 read keys and certificates as PEM file (default)
169 -der --der-keys
171 read keys and certificates as DER file
172 certification authority:
174 +cf --add-cert-file [f]ilename: string
176 add certificate file to list of certificates
177 +cd --add-cert-dir [d]irectory: string
179 add certificates in d to list of certificates
180 +crl --add-crl-file [f]ilename: string
182 add certificate revocation list file
183 (implies --enable-crl-vfy)
184 +crv --enable-crl-vfy
186 enable leaf CRL verification
187 +cra --enable-crl-all
189 enable full chain CRL verification
190 security profile:
192 +py --profile-bcp195-nd
194 Non-downgrading BCP 195 TLS Profile (default)
195 +px --profile-bcp195
197 BCP 195 TLS Profile
198 +pz --profile-bcp195-ex
200 Extended BCP 195 TLS Profile
201 +pb --profile-basic
203 Basic TLS Secure Transport Connection Profile (retired)
204 +pa --profile-aes
206 AES TLS Secure Transport Connection Profile (retired)
207 +pn --profile-null
209 Authenticated unencrypted communication
210 (retired, was used in IHE ATNA)
211 ciphersuite:
213 +cc --list-ciphers
215 show list of supported TLS ciphersuites and exit
216 +cs --cipher [c]iphersuite name: string
218 add ciphersuite to list of negotiated suites
219 pseudo random generator:
221 +rs --seed [f]ilename: string
223 seed random generator with contents of f
224 +ws --write-seed
226 write back modified seed (only with --seed)
227 +wf --write-seed-file [f]ilename: string (only with --seed)
229 write modified seed to file f
230 peer authentication:
232 -rc --require-peer-cert
234 verify peer certificate, fail if absent (default)
235 -ic --ignore-peer-cert
237 don't verify peer certificate
238 output options
240 general:
241 -od --output-directory [d]irectory: string (default: ".")
243 write output files to existing directory d
244 automatic data correction:
246 +dc --enable-correction
248 enable automatic data correction
249 -dc --disable-correction
251 disable automatic data correction (default)
252 C-FIND responses:
254 +sr --show-responses
256 always output responses to the logger
257 -sr --hide-responses
259 do not output responses to the logger
260 -X --extract
262 extract responses to DICOM file (rsp0001.dcm...)
263 -Xx --extract-xml
265 extract responses to XML file (rsp0001.xml...)
266 -Xs --extract-xml-single [f]ilename: string
268 extract all responses to given XML file f
269 -Xlo --limit-output [n]umber: integer
271 limit number of responses extracted to file to n
272 (default: unlimited)
273
275 Each file supplied on the command line will be sent to the SCP as part
276 of a C-FIND request. The query file must be a valid DICOM data set
277 containing the dataset part of a C-FIND-RQ message. The query file
278 could, for instance, be created with the dump2dcm utility from a script
279 like the following example:
280 # query patient names and IDs
282 (0008,0052) CS [PATIENT] # QueryRetrieveLevel
283 (0010,0010) PN [] # PatientName
284 (0010,0020) LO [] # PatientID
285 Individual attributes of each file sent can be modified or supplemented
287 using the -k option. For example the command:
288 findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
290 will, when sent to the SCP caesar at TCP/IP port 5678, cause any
292 PatientName attribute in patqry.dcm to have the value 'HEWETT*'. If
293 such an attribute is present it will be replaced, if absent it will be
294 inserted. The -k option can be present more than once. The value part
295 (after the '=') may be absent causing the attribute to be sent with
296 zero length.
297 In earlier versions of findscu, the tag keys were specified without
299 braces around group and element number, e. g. '0010,0010' instead of
300 '(0010,0010)'. It is recommended switching to the new syntax; however,
301 the old syntax is still working.
302 Also -k accepts dictionary names instead of element tags for specifying
304 DICOM elements. For example, the findscu call above then reads like
305 this:
306 findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
308 It is also possible to specify sequences, items and nested attributes
310 using the -k option. In these cases, a special 'path' notation has to
311 be used, e. g.
312 findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
314 This call queries a worklist server at host caesar for any planned
316 procedures for CT modalities by specifying tag (0040,0100) 'Scheduled
317 Procedure Step Sequence' and an attribute 'Modality' in the first item
318 of this sequence with value 'CT'. Details on this path notation can be
319 found in the documentation of dcmodify.
320 If no file is specified on the command line, the query must be
322 specified completely with one or more -k options. If multiple query
323 files are provided, findscu will send multiple C-FIND requests to the
324 SCP.
325 Each set of response identifiers received will be output to the logger
327 unless option --hide-responses, any of the below --extract variants,
328 --quiet or an appropriate logger configuration is used. In such cases,
329 the output to the logger can be enforced with option --show-responses.
330 In addition, the response datasets can also be extracted as individual
332 DICOM files (using option --extract) or XML files (using option
333 --extract-xml). The output format of the latter is described by the
334 file dcm2xml.dtd (starting with top-level element 'data-set'). For XML
335 files, the Specific Character Set is mapped automatically to an
336 appropriate XML encoding. If this is not possible, e.g. in case of ISO
337 2022 character sets, non-ASCII characters and those below #32 are
338 stored as '&#nnn;' where 'nnn' refers to the numeric character code.
339 Please note that this might lead to invalid character entity references
340 (such as '' for ESC) and will cause most XML parsers to reject the
341 document.
342 Alternatively, all response datasets of an association can be extracted
344 to a single XML file using option --extract-xml-single. The top-level
345 element of the XML document is 'responses' (with a 'type' attribute of
346 'C-FIND'). The individual datasets are stored as described above. If
347 support for character set conversion is enabled, UTF-8 encoding is
348 used, i.e. all datasets are converted to UTF-8 encoding (which is
349 strongly recommended in order to avoid issues with non-ASCII characters
350 when different character sets are used).
351 DICOM Conformance
353 The findscu application supports the following SOP Classes as an SCU:
354 FINDPatientRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.1.1
356 FINDStudyRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.2.1
357 FINDPatientStudyOnlyQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.3.1
358 FINDModalityWorklistInformationModel 1.2.840.10008.5.1.4.31
359 The findscu application will propose presentation contexts for one of
361 the abovementioned supported SOP Classes depending on command line
362 options (-P, -S, -O or -W). Basically, the following transfer syntaxes
363 are supported:
364 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
366 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
367 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
368 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
369 (*) if compiled with zlib support enabled (see --version output)
371 Which transfer syntaxes are actually proposed in what order, can be
373 specified with the --propose options.
374 The findscu application does not support extended negotiation.
376
378 The level of logging output of the various command line tools and
379 underlying libraries can be specified by the user. By default, only
380 errors and warnings are written to the standard error stream. Using
381 option --verbose also informational messages like processing details
382 are reported. Option --debug can be used to get more details on the
383 internal activity, e.g. for debugging purposes. Other logging levels
384 can be selected using option --log-level. In --quiet mode only fatal
385 errors are reported. In such very severe error events, the application
386 will usually terminate. For more details on the different logging
387 levels, see documentation of module 'oflog'.
388 In case the logging output should be written to file (optionally with
390 logfile rotation), to syslog (Unix) or the event log (Windows) option
391 --log-config can be used. This configuration file also allows for
392 directing only certain messages to a particular output stream and for
393 filtering certain messages based on the module or application where
394 they are generated. An example configuration file is provided in
395 <etcdir>/logger.cfg.
396
398 All command line tools use the following notation for parameters:
399 square brackets enclose optional values (0-1), three trailing dots
400 indicate that multiple values are allowed (1-n), a combination of both
401 means 0 to n values.
402 Command line options are distinguished from parameters by a leading '+'
404 or '-' sign, respectively. Usually, order and position of command line
405 options are arbitrary (i.e. they can appear anywhere). However, if
406 options are mutually exclusive the rightmost appearance is used. This
407 behavior conforms to the standard evaluation rules of common Unix
408 shells.
409 In addition, one or more command files can be specified using an '@'
411 sign as a prefix to the filename (e.g. @command.txt). Such a command
412 argument is replaced by the content of the corresponding text file
413 (multiple whitespaces are treated as a single separator unless they
414 appear between two quotation marks) prior to any further evaluation.
415 Please note that a command file cannot contain another command file.
416 This simple but effective approach allows one to summarize common
417 combinations of options/parameters and avoids longish and confusing
418 command lines (an example is provided in file <datadir>/dumppat.txt).
419
421 The findscu utility will attempt to load DICOM data dictionaries
422 specified in the DCMDICTPATH environment variable. By default, i.e. if
423 the DCMDICTPATH environment variable is not set, the file
424 <datadir>/dicom.dic will be loaded unless the dictionary is built into
425 the application (default for Windows).
426 The default behavior should be preferred and the DCMDICTPATH
428 environment variable only used when alternative data dictionaries are
429 required. The DCMDICTPATH environment variable has the same format as
430 the Unix shell PATH variable in that a colon (':') separates entries.
431 On Windows systems, a semicolon (';') is used as a separator. The data
432 dictionary code will attempt to load each file specified in the
433 DCMDICTPATH environment variable. It is an error if no data dictionary
434 can be loaded.
435
437 <datadir>/dcm2xml.dtd - Document Type Definition (DTD) file
438
440 movescu(1), dump2dcm(1), dcmodify(1)
441
443 Copyright (C) 1994-2022 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
444 Germany.
445Version 3.6.7 Fri Apr 22 2022 findscu(1)