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 security profile:
182 +px --profile-bcp195
184 BCP 195 TLS Profile (default)
185 +py --profile-bcp195-nd
187 Non-downgrading BCP 195 TLS Profile
188 +pz --profile-bcp195-ex
190 Extended BCP 195 TLS Profile
191 +pb --profile-basic
193 Basic TLS Secure Transport Connection Profile (retired)
194 +pa --profile-aes
196 AES TLS Secure Transport Connection Profile (retired)
197 +pn --profile-null
199 Authenticated unencrypted communication
200 (retired, was used in IHE ATNA)
201 ciphersuite:
203 +cc --list-ciphers
205 show list of supported TLS ciphersuites and exit
206 +cs --cipher [c]iphersuite name: string
208 add ciphersuite to list of negotiated suites
209 pseudo random generator:
211 +rs --seed [f]ilename: string
213 seed random generator with contents of f
214 +ws --write-seed
216 write back modified seed (only with --seed)
217 +wf --write-seed-file [f]ilename: string (only with --seed)
219 write modified seed to file f
220 peer authentication:
222 -rc --require-peer-cert
224 verify peer certificate, fail if absent (default)
225 -ic --ignore-peer-cert
227 don't verify peer certificate
228 output options
230 general:
231 -od --output-directory [d]irectory: string (default: ".")
233 write output files to existing directory d
234 automatic data correction:
236 +dc --enable-correction
238 enable automatic data correction
239 -dc --disable-correction
241 disable automatic data correction (default)
242 C-FIND responses:
244 +sr --show-responses
246 always output responses to the logger
247 -sr --hide-responses
249 do not output responses to the logger
250 -X --extract
252 extract responses to DICOM file (rsp0001.dcm...)
253 -Xx --extract-xml
255 extract responses to XML file (rsp0001.xml...)
256 -Xs --extract-xml-single [f]ilename: string
258 extract all responses to given XML file f
259 -Xlo --limit-output [n]umber: integer
261 limit number of responses extracted to file to n
262 (default: unlimited)
263
265 Each file supplied on the command line will be sent to the SCP as part
266 of a C-FIND request. The query file must be a valid DICOM data set
267 containing the dataset part of a C-FIND-RQ message. The query file
268 could, for instance, be created with the dump2dcm utility from a script
269 like the following example:
270 # query patient names and IDs
272 (0008,0052) CS [PATIENT] # QueryRetrieveLevel
273 (0010,0010) PN [] # PatientName
274 (0010,0020) LO [] # PatientID
275 Individual attributes of each file sent can be modified or supplemented
277 using the -k option. For example the command:
278 findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
280 will, when sent to the SCP caesar at TCP/IP port 5678, cause any
282 PatientName attribute in patqry.dcm to have the value 'HEWETT*'. If
283 such an attribute is present it will be replaced, if absent it will be
284 inserted. The -k option can be present more than once. The value part
285 (after the '=') may be absent causing the attribute to be sent with
286 zero length.
287 In earlier versions of findscu, the tag keys were specified without
289 braces around group and element number, e. g. '0010,0010' instead of
290 '(0010,0010)'. It is recommended switching to the new syntax; however,
291 the old syntax is still working.
292 Also -k accepts dictionary names instead of element tags for specifying
294 DICOM elements. For example, the findscu call above then reads like
295 this:
296 findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
298 It is also possible to specify sequences, items and nested attributes
300 using the -k option. In these cases, a special 'path' notation has to
301 be used, e. g.
302 findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
304 This call queries a worklist server at host caesar for any planned
306 procedures for CT modalities by specifying tag (0040,0100) 'Scheduled
307 Procedure Step Sequence' and an attribute 'Modality' in the first item
308 of this sequence with value 'CT'. Details on this path notation can be
309 found in the documentation of dcmodify.
310 If no file is specified on the command line, the query must be
312 specified completely with one or more -k options. If multiple query
313 files are provided, findscu will send multiple C-FIND requests to the
314 SCP.
315 Each set of response identifiers received will be output to the logger
317 unless option --hide-responses, any of the below --extract variants,
318 --quiet or an appropriate logger configuration is used. In such cases,
319 the output to the logger can be enforced with option --show-responses.
320 In addition, the response datasets can also be extracted as individual
322 DICOM files (using option --extract) or XML files (using option
323 --extract-xml). The output format of the latter is described by the
324 file dcm2xml.dtd (starting with top-level element 'data-set'). For XML
325 files, the Specific Character Set is mapped automatically to an
326 appropriate XML encoding. If this is not possible, e.g. in case of ISO
327 2022 character sets, non-ASCII characters and those below #32 are
328 stored as '&#nnn;' where 'nnn' refers to the numeric character code.
329 Please note that this might lead to invalid character entity references
330 (such as '' for ESC) and will cause most XML parsers to reject the
331 document.
332 Alternatively, all response datasets of an association can be extracted
334 to a single XML file using option --extract-xml-single. The top-level
335 element of the XML document is 'responses' (with a 'type' attribute of
336 'C-FIND'). The individual datasets are stored as described above. If
337 support for character set conversion is enabled, UTF-8 encoding is
338 used, i.e. all datasets are converted to UTF-8 encoding (which is
339 strongly recommended in order to avoid issues with non-ASCII characters
340 when different character sets are used).
341 DICOM Conformance
343 The findscu application supports the following SOP Classes as an SCU:
344 FINDPatientRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.1.1
346 FINDStudyRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.2.1
347 FINDPatientStudyOnlyQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.3.1
348 FINDModalityWorklistInformationModel 1.2.840.10008.5.1.4.31
349 The findscu application will propose presentation contexts for one of
351 the abovementioned supported SOP Classes depending on command line
352 options (-P, -S, -O or -W). Basically, the following transfer syntaxes
353 are supported:
354 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
356 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
357 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
358 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
359 (*) if compiled with zlib support enabled (see --version output)
361 Which transfer syntaxes are actually proposed in what order, can be
363 specified with the --propose options.
364 The findscu application does not support extended negotiation.
366
368 The level of logging output of the various command line tools and
369 underlying libraries can be specified by the user. By default, only
370 errors and warnings are written to the standard error stream. Using
371 option --verbose also informational messages like processing details
372 are reported. Option --debug can be used to get more details on the
373 internal activity, e.g. for debugging purposes. Other logging levels
374 can be selected using option --log-level. In --quiet mode only fatal
375 errors are reported. In such very severe error events, the application
376 will usually terminate. For more details on the different logging
377 levels, see documentation of module 'oflog'.
378 In case the logging output should be written to file (optionally with
380 logfile rotation), to syslog (Unix) or the event log (Windows) option
381 --log-config can be used. This configuration file also allows for
382 directing only certain messages to a particular output stream and for
383 filtering certain messages based on the module or application where
384 they are generated. An example configuration file is provided in
385 <etcdir>/logger.cfg.
386
388 All command line tools use the following notation for parameters:
389 square brackets enclose optional values (0-1), three trailing dots
390 indicate that multiple values are allowed (1-n), a combination of both
391 means 0 to n values.
392 Command line options are distinguished from parameters by a leading '+'
394 or '-' sign, respectively. Usually, order and position of command line
395 options are arbitrary (i.e. they can appear anywhere). However, if
396 options are mutually exclusive the rightmost appearance is used. This
397 behavior conforms to the standard evaluation rules of common Unix
398 shells.
399 In addition, one or more command files can be specified using an '@'
401 sign as a prefix to the filename (e.g. @command.txt). Such a command
402 argument is replaced by the content of the corresponding text file
403 (multiple whitespaces are treated as a single separator unless they
404 appear between two quotation marks) prior to any further evaluation.
405 Please note that a command file cannot contain another command file.
406 This simple but effective approach allows one to summarize common
407 combinations of options/parameters and avoids longish and confusing
408 command lines (an example is provided in file <datadir>/dumppat.txt).
409
411 The findscu utility will attempt to load DICOM data dictionaries
412 specified in the DCMDICTPATH environment variable. By default, i.e. if
413 the DCMDICTPATH environment variable is not set, the file
414 <datadir>/dicom.dic will be loaded unless the dictionary is built into
415 the application (default for Windows).
416 The default behavior should be preferred and the DCMDICTPATH
418 environment variable only used when alternative data dictionaries are
419 required. The DCMDICTPATH environment variable has the same format as
420 the Unix shell PATH variable in that a colon (':') separates entries.
421 On Windows systems, a semicolon (';') is used as a separator. The data
422 dictionary code will attempt to load each file specified in the
423 DCMDICTPATH environment variable. It is an error if no data dictionary
424 can be loaded.
425
427 <datadir>/dcm2xml.dtd - Document Type Definition (DTD) file
428
430 movescu(1), dump2dcm(1), dcmodify(1)
431
433 Copyright (C) 1994-2021 e.V., Escherweg 2, 26121 Oldenburg, Germany.
434Version 3.6.6 Thu Jan 14 2021 findscu(1)