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 ciphersuite:
179 +cs --cipher [c]iphersuite name: string
181 add ciphersuite to list of negotiated suites
182 +dp --dhparam [f]ilename: string
184 read DH parameters for DH/DSS ciphersuites
185 pseudo random generator:
187 +rs --seed [f]ilename: string
189 seed random generator with contents of f
190 +ws --write-seed
192 write back modified seed (only with --seed)
193 +wf --write-seed-file [f]ilename: string (only with --seed)
195 write modified seed to file f
196 peer authentication:
198 -rc --require-peer-cert
200 verify peer certificate, fail if absent (default)
201 -vc --verify-peer-cert
203 verify peer certificate if present
204 -ic --ignore-peer-cert
206 don't verify peer certificate
207 output options
209 general:
210 -od --output-directory [d]irectory: string (default: ".")
212 write output files to existing directory d
213 automatic data correction:
215 +dc --enable-correction
217 enable automatic data correction
218 -dc --disable-correction
220 disable automatic data correction (default)
221 C-FIND responses:
223 +sr --show-responses
225 always output responses to the logger
226 -sr --hide-responses
228 do not output responses to the logger
229 -X --extract
231 extract responses to file (rsp0001.dcm, ...)
232
234 Each file supplied on the command line will be sent to the SCP as part
235 of a C-FIND request. The query file must be a valid DICOM data set
236 containing the dataset part of a C-FIND-RQ message. The query file
237 could, for instance, be created with the dump2dcm utility from a script
238 like the following example:
239 # query patient names and IDs
241 (0008,0052) CS [PATIENT] # QueryRetrieveLevel
242 (0010,0010) PN [] # PatientName
243 (0010,0020) LO [] # PatientID
244 Individual attributes of each file sent can be modified or supplemented
246 using the -k option. For example the command:
247 findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
249 will, when sent to the SCP caesar at TCP/IP port 5678, cause any
251 PatientName attribute in patqry.dcm to have the value 'HEWETT*'. If
252 such an attribute is present it will be replaced, if absent it will be
253 inserted. The -k option can be present more than once. The value part
254 (after the '=') may be absent causing the attribute to be sent with
255 zero length.
256 In earlier versions of findscu, the tag keys were specified without
258 braces around group and element number, e. g. '0010,0010' instead of
259 '(0010,0010)'. It is recommended switching to the new syntax; however,
260 the old syntax is still working.
261 Also -k accepts dictionary names instead of element tags for specifying
263 DICOM elements. For example, the findscu call above then reads like
264 this:
265 findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
267 It is also possible to specify sequences, items and nested attributes
269 using the -k option. In these cases, a special 'path' notation has to
270 be used, e. g.
271 findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
273 This call queries a worklist server at host caesar for any planned
275 procedures for CT modalities by specifying tag (0040,0100) 'Scheduled
276 Procedure Step Sequence' and an attribute 'Modality' in the first item
277 of this sequence with value 'CT'. Details on this path notation can be
278 found in the documentation of dcmodify.
279 If no file is specified on the command line, the query must be
281 specified completely with one or more -k options. If multiple query
282 files are provided, findscu will send multiple C-FIND requests to the
283 SCP.
284 Each set of response identifiers received will be output to the logger
286 unless option --hide-responses, --extract, --quiet or an appropriate
287 logger configuration is used. Option --show-responses can be used to
288 force the output to the logger.
289 DICOM Conformance
291 The findscu application supports the following SOP Classes as an SCU:
292 FINDPatientRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.1.1
294 FINDStudyRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.2.1
295 FINDPatientStudyOnlyQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.3.1
296 FINDModalityWorklistInformationModel 1.2.840.10008.5.1.4.31
297 The findscu application will propose presentation contexts for one of
299 the abovementioned supported SOP Classes depending on command line
300 options (-P, -S, -O or -W). Basically, the following transfer syntaxes
301 are supported:
302 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
304 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
305 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
306 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
307 (*) if compiled with zlib support enabled (see --version output)
309 Which transfer syntaxes are actually proposed in what order, can be
311 specified with the --propose options.
312 The findscu application does not support extended negotiation.
314
316 The level of logging output of the various command line tools and
317 underlying libraries can be specified by the user. By default, only
318 errors and warnings are written to the standard error stream. Using
319 option --verbose also informational messages like processing details
320 are reported. Option --debug can be used to get more details on the
321 internal activity, e.g. for debugging purposes. Other logging levels
322 can be selected using option --log-level. In --quiet mode only fatal
323 errors are reported. In such very severe error events, the application
324 will usually terminate. For more details on the different logging
325 levels, see documentation of module 'oflog'.
326 In case the logging output should be written to file (optionally with
328 logfile rotation), to syslog (Unix) or the event log (Windows) option
329 --log-config can be used. This configuration file also allows for
330 directing only certain messages to a particular output stream and for
331 filtering certain messages based on the module or application where
332 they are generated. An example configuration file is provided in
333 <etcdir>/logger.cfg.
334
336 All command line tools use the following notation for parameters:
337 square brackets enclose optional values (0-1), three trailing dots
338 indicate that multiple values are allowed (1-n), a combination of both
339 means 0 to n values.
340 Command line options are distinguished from parameters by a leading '+'
342 or '-' sign, respectively. Usually, order and position of command line
343 options are arbitrary (i.e. they can appear anywhere). However, if
344 options are mutually exclusive the rightmost appearance is used. This
345 behavior conforms to the standard evaluation rules of common Unix
346 shells.
347 In addition, one or more command files can be specified using an '@'
349 sign as a prefix to the filename (e.g. @command.txt). Such a command
350 argument is replaced by the content of the corresponding text file
351 (multiple whitespaces are treated as a single separator unless they
352 appear between two quotation marks) prior to any further evaluation.
353 Please note that a command file cannot contain another command file.
354 This simple but effective approach allows one to summarize common
355 combinations of options/parameters and avoids longish and confusing
356 command lines (an example is provided in file <datadir>/dumppat.txt).
357
359 The findscu utility will attempt to load DICOM data dictionaries
360 specified in the DCMDICTPATH environment variable. By default, i.e. if
361 the DCMDICTPATH environment variable is not set, the file
362 <datadir>/dicom.dic will be loaded unless the dictionary is built into
363 the application (default for Windows).
364 The default behavior should be preferred and the DCMDICTPATH
366 environment variable only used when alternative data dictionaries are
367 required. The DCMDICTPATH environment variable has the same format as
368 the Unix shell PATH variable in that a colon (':') separates entries.
369 On Windows systems, a semicolon (';') is used as a separator. The data
370 dictionary code will attempt to load each file specified in the
371 DCMDICTPATH environment variable. It is an error if no data dictionary
372 can be loaded.
373
375 movescu(1), dump2dcm(1), dcmodify(1)
376
378 Copyright (C) 1994-2017 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
379 Germany.
380Version 3.6.2 Fri Jul 14 2017 findscu(1)