4 \page findscu DICOM query (C-FIND) SCU
6 \page findscu findscu: DICOM query (C-FIND) SCU
9 \section synopsis SYNOPSIS
12 findscu [options] peer port [dcmfile-in...]
15 \section description DESCRIPTION
17 The \b findscu application implements an SCU for the Query/Retrieve Service
18 Class and the Basic Worklist Management Service Class. \b findscu only
19 supports query functionality using the C-FIND message. It sends query keys
20 to an SCP and awaits responses. The application can be used to test SCPs of
21 the Query/Retrieve and Basic Worklist Management Service Classes.
23 \section parameters PARAMETERS
26 peer hostname of DICOM peer
28 port tcp/ip port number of peer
30 dcmfile-in DICOM query file(s)
33 \section options OPTIONS
35 \subsection general_options general options
38 print this help text and exit
41 print version information and exit
44 print expanded command line arguments
47 quiet mode, print no warnings and errors
50 verbose mode, print processing details
53 debug mode, print debug information
55 -ll --log-level [l]evel: string constant
56 (fatal, error, warn, info, debug, trace)
57 use level l for the logger
59 -lc --log-config [f]ilename: string
60 use config file f for the logger
63 \subsection network_options network options
65 override matching keys:
67 -k --key [k]ey: gggg,eeee="str", path or dictionary name="str"
70 query information model:
73 use modality worklist information model (default)
76 use patient root information model
79 use study root information model
82 use patient/study only information model
84 application entity titles:
86 -aet --aetitle [a]etitle: string
87 set my calling AE title (default: FINDSCU)
89 -aec --call [a]etitle: string
90 set called AE title of peer (default: ANY-SCP)
92 post-1993 value representations:
95 enable support for new VRs (UN/UT) (default)
98 disable support for new VRs, convert to OB
100 proposed transmission transfer syntaxes:
102 -x= --propose-uncompr
103 propose all uncompressed TS, explicit VR
104 with local byte ordering first (default)
107 propose all uncompressed TS, explicit VR
111 propose all uncompressed TS, explicit VR
114 -xi --propose-implicit
115 propose implicit VR little endian TS only
117 other network options:
119 -to --timeout [s]econds: integer (default: unlimited)
120 timeout for connection requests
122 -ta --acse-timeout [s]econds: integer (default: 30)
123 timeout for ACSE messages
125 -td --dimse-timeout [s]econds: integer (default: unlimited)
126 timeout for DIMSE messages
128 -pdu --max-pdu [n]umber of bytes: integer (4096..131072)
129 set max receive pdu to n bytes (default: 16384)
131 --repeat [n]umber: integer
135 abort association instead of releasing it
137 --cancel [n]umber: integer
138 cancel after n responses (default: never)
141 extract responses to file (rsp0001.dcm, ...)
144 \subsection tls_options transport layer security (TLS) options
146 transport protocol stack:
149 use normal TCP/IP connection (default)
151 +tls --enable-tls [p]rivate key file, [c]ertificate file: string
152 use authenticated secure TLS connection
155 use secure TLS connection without certificate
157 private key password (only with --enable-tls):
160 prompt user to type password on stdin (default)
162 +pw --use-passwd [p]assword: string
163 use specified password
166 use empty string as password
168 key and certificate file format:
171 read keys and certificates as PEM file (default)
174 read keys and certificates as DER file
176 certification authority:
178 +cf --add-cert-file [c]ertificate filename: string
179 add certificate file to list of certificates
181 +cd --add-cert-dir [c]ertificate directory: string
182 add certificates in d to list of certificates
186 +cs --cipher [c]iphersuite name: string
187 add ciphersuite to list of negotiated suites
189 +dp --dhparam [f]ilename: string
190 read DH parameters for DH/DSS ciphersuites
192 pseudo random generator:
194 +rs --seed [f]ilename: string
195 seed random generator with contents of f
198 write back modified seed (only with --seed)
200 +wf --write-seed-file [f]ilename: string (only with --seed)
201 write modified seed to file f
205 -rc --require-peer-cert
206 verify peer certificate, fail if absent (default)
208 -vc --verify-peer-cert
209 verify peer certificate if present
211 -ic --ignore-peer-cert
212 don't verify peer certificate
217 Each file supplied on the command line will be sent to the SCP as part of a
218 C-FIND request. The query file must be a valid DICOM data set containing
219 the dataset part of a C-FIND-RQ message. The query file could, for instance,
220 be created with the \b dump2dcm utility from a script like the following
224 # query patient names and IDs
225 (0008,0052) CS [PATIENT] # QueryRetrieveLevel
226 (0010,0010) PN [] # PatientName
227 (0010,0020) LO [] # PatientID
230 Individual attributes of each file sent can be modified or supplemented
231 using the \e -k option. For example the command:
234 findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
237 will, when sent to the SCP caesar at TCP/IP port 5678, cause any PatientName
238 attribute in patqry.dcm to have the value "HEWETT*". If such an attribute is
239 present it will be replaced, if absent it will be inserted. The \e -k option
240 can be present more than once. The value part (after the '=') may be absent
241 causing the attribute to be sent with zero length.
243 In earlier versions of \b findscu, the tag keys were specified without braces
244 around group and element number, e. g. "0010,0010" instead of "(0010,0010)".
245 It is recommended switching to the new syntax; however, the old syntax is
248 Also \e -k accepts dictionary names instead of element tags for specifying
249 DICOM elements. For example, the \b findscu call above then reads like this:
252 findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
255 It is also possible to specify sequences, items and nested attributes using
256 the \e -k option. In these cases, a special "path" notation has to be used,
260 findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
263 This call queries a worklist server at host caesar for any planned procedures
264 for CT modalities by specifing tag (0040,0100) "Scheduled Procedure Step
265 Sequence" and an attribute "Modality" in the first item of this sequence with
266 value "CT". Details on this path notation can be found in the documentation
269 If no file is specified on the command line, the query must be specified
270 completely with one or more \e -k options.
272 Each set of response identifiers received will be printed to stdout unless
273 option \e --extract is used.
275 \subsection dicom_conformance DICOM Conformance
277 The \b findscu application supports the following SOP Classes as an SCU:
280 FINDPatientRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.1.1
281 FINDStudyRootQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.2.1
282 FINDPatientStudyOnlyQueryRetrieveInformationModel 1.2.840.10008.5.1.4.1.2.3.1
283 FINDModalityWorklistInformationModel 1.2.840.10008.5.1.4.31
286 The \b findscu application will propose presentation contexts for one of the
287 abovementioned supported SOP Classes depending on command line options (\e -P,
288 \e -S, \e -O or \e -W). Each proposed presentation context will propose the
292 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
293 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
294 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
297 The \b findscu application does not support extended negotiation.
299 \section logging LOGGING
301 The level of logging output of the various command line tools and underlying
302 libraries can be specified by the user. By default, only errors and warnings
303 are written to the standard error stream. Using option \e --verbose also
304 informational messages like processing details are reported. Option
305 \e --debug can be used to get more details on the internal activity, e.g. for
306 debugging purposes. Other logging levels can be selected using option
307 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
308 very severe error events, the application will usually terminate. For more
309 details on the different logging levels, see documentation of module "oflog".
311 In case the logging output should be written to file (optionally with logfile
312 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
313 can be used. This configuration file also allows for directing only certain
314 messages to a particular output stream and for filtering certain messages
315 based on the module or application where they are generated. An example
316 configuration file is provided in <em><etcdir>/logger.cfg</em>).
318 \section command_line COMMAND LINE
320 All command line tools use the following notation for parameters: square
321 brackets enclose optional values (0-1), three trailing dots indicate that
322 multiple values are allowed (1-n), a combination of both means 0 to n values.
324 Command line options are distinguished from parameters by a leading '+' or '-'
325 sign, respectively. Usually, order and position of command line options are
326 arbitrary (i.e. they can appear anywhere). However, if options are mutually
327 exclusive the rightmost appearance is used. This behaviour conforms to the
328 standard evaluation rules of common Unix shells.
330 In addition, one or more command files can be specified using an '@' sign as a
331 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
332 is replaced by the content of the corresponding text file (multiple
333 whitespaces are treated as a single separator unless they appear between two
334 quotation marks) prior to any further evaluation. Please note that a command
335 file cannot contain another command file. This simple but effective approach
336 allows to summarize common combinations of options/parameters and avoids
337 longish and confusing command lines (an example is provided in file
338 <em><datadir>/dumppat.txt</em>).
340 \section environment ENVIRONMENT
342 The \b findscu utility will attempt to load DICOM data dictionaries specified
343 in the \e DCMDICTPATH environment variable. By default, i.e. if the
344 \e DCMDICTPATH environment variable is not set, the file
345 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
346 into the application (default for Windows).
348 The default behaviour should be preferred and the \e DCMDICTPATH environment
349 variable only used when alternative data dictionaries are required. The
350 \e DCMDICTPATH environment variable has the same format as the Unix shell
351 \e PATH variable in that a colon (":") separates entries. On Windows systems,
352 a semicolon (";") is used as a separator. The data dictionary code will
353 attempt to load each file specified in the \e DCMDICTPATH environment variable.
354 It is an error if no data dictionary can be loaded.
356 \section see_also SEE ALSO
358 <b>movescu</b>(1), <b>dump2dcm</b>(1), <b>dcmodify</b>(1)
360 \section copyright COPYRIGHT
362 Copyright (C) 1994-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.