1findscu(1) OFFIS DCMTK findscu(1)
2
6 findscu - DICOM query (C-FIND) SCU
7
9 findscu [options] peer port [dcmfile-in...]
10
12 The findscu application implements an SCU for the Query/Retrieve
13 Service Class and the Basic Worklist Management Service Class. findscu
14 only supports query functionality using the C-FIND message. It sends
15 query keys to an SCP and awaits responses. The application can be used
16 to test SCPs of the Query/Retrieve and Basic Worklist Management
17 Service Classes.
18
20 peer hostname of DICOM peer
21 port tcp/ip port number of peer
23 dcmfile-in DICOM query file(s)
25
27 general options
28 -h --help
29 print this help text and exit
30 --version
32 print version information and exit
33 --arguments
35 print expanded command line arguments
36 -q --quiet
38 quiet mode, print no warnings and errors
39 -v --verbose
41 verbose mode, print processing details
42 -d --debug
44 debug mode, print debug information
45 -ll --log-level [l]evel: string constant
47 (fatal, error, warn, info, debug, trace)
48 use level l for the logger
49 -lc --log-config [f]ilename: string
51 use config file f for the logger
52 network options
54 override matching keys:
55 -k --key [k]ey: gggg,eeee="str", path or dictionary name="str"
57 override matching key
58 query information model:
60 -W --worklist
62 use modality worklist information model (default)
63 -P --patient
65 use patient root information model
66 -S --study
68 use study root information model
69 -O --psonly
71 use patient/study only information model
72 application entity titles:
74 -aet --aetitle [a]etitle: string
76 set my calling AE title (default: FINDSCU)
77 -aec --call [a]etitle: string
79 set called AE title of peer (default: ANY-SCP)
80 post-1993 value representations:
82 +u --enable-new-vr
84 enable support for new VRs (UN/UT) (default)
85 -u --disable-new-vr
87 disable support for new VRs, convert to OB
88 proposed transmission transfer syntaxes:
90 -x= --propose-uncompr
92 propose all uncompressed TS, explicit VR
93 with local byte ordering first (default)
94 -xe --propose-little
96 propose all uncompressed TS, explicit VR
97 little endian first
98 -xb --propose-big
100 propose all uncompressed TS, explicit VR
101 big endian first
102 -xi --propose-implicit
104 propose implicit VR little endian TS only
105 other network options:
107 -to --timeout [s]econds: integer (default: unlimited)
109 timeout for connection requests
110 -ta --acse-timeout [s]econds: integer (default: 30)
112 timeout for ACSE messages
113 -td --dimse-timeout [s]econds: integer (default: unlimited)
115 timeout for DIMSE messages
116 -pdu --max-pdu [n]umber of bytes: integer (4096..131072)
118 set max receive pdu to n bytes (default: 16384)
119 --repeat [n]umber: integer
121 repeat n times
122 --abort
124 abort association instead of releasing it
125 --cancel [n]umber: integer
127 cancel after n responses (default: never)
128 -X --extract
130 extract responses to file (rsp0001.dcm, ...)
131 transport layer security (TLS) options
133 transport protocol stack:
134 -tls --disable-tls
136 use normal TCP/IP connection (default)
137 +tls --enable-tls [p]rivate key file, [c]ertificate file: string
139 use authenticated secure TLS connection
140 +tla --anonymous-tls
142 use secure TLS connection without certificate
143 private key password (only with --enable-tls):
145 +ps --std-passwd
147 prompt user to type password on stdin (default)
148 +pw --use-passwd [p]assword: string
150 use specified password
151 -pw --null-passwd
153 use empty string as password
154 key and certificate file format:
156 -pem --pem-keys
158 read keys and certificates as PEM file (default)
159 -der --der-keys
161 read keys and certificates as DER file
162 certification authority:
164 +cf --add-cert-file [c]ertificate filename: string
166 add certificate file to list of certificates
167 +cd --add-cert-dir [c]ertificate directory: string
169 add certificates in d to list of certificates
170 ciphersuite:
172 +cs --cipher [c]iphersuite name: string
174 add ciphersuite to list of negotiated suites
175 +dp --dhparam [f]ilename: string
177 read DH parameters for DH/DSS ciphersuites
178 pseudo random generator:
180 +rs --seed [f]ilename: string
182 seed random generator with contents of f
183 +ws --write-seed
185 write back modified seed (only with --seed)
186 +wf --write-seed-file [f]ilename: string (only with --seed)
188 write modified seed to file f
189 peer authentication:
191 -rc --require-peer-cert
193 verify peer certificate, fail if absent (default)
194 -vc --verify-peer-cert
196 verify peer certificate if present
197 -ic --ignore-peer-cert
199 don't verify peer certificate
200
202 Each file supplied on the command line will be sent to the SCP as part
203 of a C-FIND request. The query file must be a valid DICOM data set
204 containing the dataset part of a C-FIND-RQ message. The query file
205 could, for instance, be created with the dump2dcm utility from a script
206 like the following example:
207 # query patient names and IDs
209 (0008,0052) CS [PATIENT] # QueryRetrieveLevel
210 (0010,0010) PN [] # PatientName
211 (0010,0020) LO [] # PatientID
212 Individual attributes of each file sent can be modified or supplemented
214 using the -k option. For example the command:
215 findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
217 will, when sent to the SCP caesar at TCP/IP port 5678, cause any
219 PatientName attribute in patqry.dcm to have the value 'HEWETT*'. If
220 such an attribute is present it will be replaced, if absent it will be
221 inserted. The -k option can be present more than once. The value part
222 (after the '=') may be absent causing the attribute to be sent with
223 zero length.
224 In earlier versions of findscu, the tag keys were specified without
226 braces around group and element number, e. g. '0010,0010' instead of
227 '(0010,0010)'. It is recommended switching to the new syntax; however,
228 the old syntax is still working.
229 Also -k accepts dictionary names instead of element tags for specifying
231 DICOM elements. For example, the findscu call above then reads like
232 this:
233 findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
235 It is also possible to specify sequences, items and nested attributes
237 using the -k option. In these cases, a special 'path' notation has to
238 be used, e. g.
239 findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
241 This call queries a worklist server at host caesar for any planned
243 procedures for CT modalities by specifing tag (0040,0100) 'Scheduled
244 Procedure Step Sequence' and an attribute 'Modality' in the first item
245 of this sequence with value 'CT'. Details on this path notation can be
246 found in the documentation of dcmodify.
247 If no file is specified on the command line, the query must be
249 specified completely with one or more -k options.
250 Each set of response identifiers received will be printed to stdout
252 unless option --extract is used.
253 DICOM Conformance
255 The findscu application supports the following SOP Classes as an SCU:
256 FINDPatientRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.1.1
258 FINDStudyRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.2.1
259 FINDPatientStudyOnlyQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.3.1
260 FINDModalityWorklistInformationModel 1.2.840.10008.5.1.4.31
261 The findscu application will propose presentation contexts for one of
263 the abovementioned supported SOP Classes depending on command line
264 options (-P, -S, -O or -W). Each proposed presentation context will
265 propose the transfer syntaxes:
266 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
268 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
269 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
270 The findscu application does not support extended negotiation.
272
274 The level of logging output of the various command line tools and
275 underlying libraries can be specified by the user. By default, only
276 errors and warnings are written to the standard error stream. Using
277 option --verbose also informational messages like processing details
278 are reported. Option --debug can be used to get more details on the
279 internal activity, e.g. for debugging purposes. Other logging levels
280 can be selected using option --log-level. In --quiet mode only fatal
281 errors are reported. In such very severe error events, the application
282 will usually terminate. For more details on the different logging
283 levels, see documentation of module 'oflog'.
284 In case the logging output should be written to file (optionally with
286 logfile rotation), to syslog (Unix) or the event log (Windows) option
287 --log-config can be used. This configuration file also allows for
288 directing only certain messages to a particular output stream and for
289 filtering certain messages based on the module or application where
290 they are generated. An example configuration file is provided in
291 <etcdir>/logger.cfg).
292
294 All command line tools use the following notation for parameters:
295 square brackets enclose optional values (0-1), three trailing dots
296 indicate that multiple values are allowed (1-n), a combination of both
297 means 0 to n values.
298 Command line options are distinguished from parameters by a leading '+'
300 or '-' sign, respectively. Usually, order and position of command line
301 options are arbitrary (i.e. they can appear anywhere). However, if
302 options are mutually exclusive the rightmost appearance is used. This
303 behaviour conforms to the standard evaluation rules of common Unix
304 shells.
305 In addition, one or more command files can be specified using an '@'
307 sign as a prefix to the filename (e.g. @command.txt). Such a command
308 argument is replaced by the content of the corresponding text file
309 (multiple whitespaces are treated as a single separator unless they
310 appear between two quotation marks) prior to any further evaluation.
311 Please note that a command file cannot contain another command file.
312 This simple but effective approach allows to summarize common
313 combinations of options/parameters and avoids longish and confusing
314 command lines (an example is provided in file <datadir>/dumppat.txt).
315
317 The findscu utility will attempt to load DICOM data dictionaries
318 specified in the DCMDICTPATH environment variable. By default, i.e. if
319 the DCMDICTPATH environment variable is not set, the file
320 <datadir>/dicom.dic will be loaded unless the dictionary is built into
321 the application (default for Windows).
322 The default behaviour should be preferred and the DCMDICTPATH
324 environment variable only used when alternative data dictionaries are
325 required. The DCMDICTPATH environment variable has the same format as
326 the Unix shell PATH variable in that a colon (':') separates entries.
327 On Windows systems, a semicolon (';') is used as a separator. The data
328 dictionary code will attempt to load each file specified in the
329 DCMDICTPATH environment variable. It is an error if no data dictionary
330 can be loaded.
331
333 movescu(1), dump2dcm(1), dcmodify(1)
334
336 Copyright (C) 1994-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
337 Germany.
338Version 3.6.0 6 Jan 2011 findscu(1)