OFFIS DCMTK  Version 3.6.0
findscu.man
1 /*!
2 
3 \if MANPAGES
4 \page findscu DICOM query (C-FIND) SCU
5 \else
6 \page findscu findscu: DICOM query (C-FIND) SCU
7 \endif
8 
9 \section synopsis SYNOPSIS
10 
11 \verbatim
12 findscu [options] peer port [dcmfile-in...]
13 \endverbatim
14 
15 \section description DESCRIPTION
16 
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.
22 
23 \section parameters PARAMETERS
24 
25 \verbatim
26 peer hostname of DICOM peer
27 
28 port tcp/ip port number of peer
29 
30 dcmfile-in DICOM query file(s)
31 \endverbatim
32 
33 \section options OPTIONS
34 
35 \subsection general_options general options
36 \verbatim
37  -h --help
38  print this help text and exit
39 
40  --version
41  print version information and exit
42 
43  --arguments
44  print expanded command line arguments
45 
46  -q --quiet
47  quiet mode, print no warnings and errors
48 
49  -v --verbose
50  verbose mode, print processing details
51 
52  -d --debug
53  debug mode, print debug information
54 
55  -ll --log-level [l]evel: string constant
56  (fatal, error, warn, info, debug, trace)
57  use level l for the logger
58 
59  -lc --log-config [f]ilename: string
60  use config file f for the logger
61 \endverbatim
62 
63 \subsection network_options network options
64 \verbatim
65 override matching keys:
66 
67  -k --key [k]ey: gggg,eeee="str", path or dictionary name="str"
68  override matching key
69 
70 query information model:
71 
72  -W --worklist
73  use modality worklist information model (default)
74 
75  -P --patient
76  use patient root information model
77 
78  -S --study
79  use study root information model
80 
81  -O --psonly
82  use patient/study only information model
83 
84 application entity titles:
85 
86  -aet --aetitle [a]etitle: string
87  set my calling AE title (default: FINDSCU)
88 
89  -aec --call [a]etitle: string
90  set called AE title of peer (default: ANY-SCP)
91 
92 post-1993 value representations:
93 
94  +u --enable-new-vr
95  enable support for new VRs (UN/UT) (default)
96 
97  -u --disable-new-vr
98  disable support for new VRs, convert to OB
99 
100 proposed transmission transfer syntaxes:
101 
102  -x= --propose-uncompr
103  propose all uncompressed TS, explicit VR
104  with local byte ordering first (default)
105 
106  -xe --propose-little
107  propose all uncompressed TS, explicit VR
108  little endian first
109 
110  -xb --propose-big
111  propose all uncompressed TS, explicit VR
112  big endian first
113 
114  -xi --propose-implicit
115  propose implicit VR little endian TS only
116 
117 other network options:
118 
119  -to --timeout [s]econds: integer (default: unlimited)
120  timeout for connection requests
121 
122  -ta --acse-timeout [s]econds: integer (default: 30)
123  timeout for ACSE messages
124 
125  -td --dimse-timeout [s]econds: integer (default: unlimited)
126  timeout for DIMSE messages
127 
128  -pdu --max-pdu [n]umber of bytes: integer (4096..131072)
129  set max receive pdu to n bytes (default: 16384)
130 
131  --repeat [n]umber: integer
132  repeat n times
133 
134  --abort
135  abort association instead of releasing it
136 
137  --cancel [n]umber: integer
138  cancel after n responses (default: never)
139 
140  -X --extract
141  extract responses to file (rsp0001.dcm, ...)
142 \endverbatim
143 
144 \subsection tls_options transport layer security (TLS) options
145 \verbatim
146 transport protocol stack:
147 
148  -tls --disable-tls
149  use normal TCP/IP connection (default)
150 
151  +tls --enable-tls [p]rivate key file, [c]ertificate file: string
152  use authenticated secure TLS connection
153 
154  +tla --anonymous-tls
155  use secure TLS connection without certificate
156 
157 private key password (only with --enable-tls):
158 
159  +ps --std-passwd
160  prompt user to type password on stdin (default)
161 
162  +pw --use-passwd [p]assword: string
163  use specified password
164 
165  -pw --null-passwd
166  use empty string as password
167 
168 key and certificate file format:
169 
170  -pem --pem-keys
171  read keys and certificates as PEM file (default)
172 
173  -der --der-keys
174  read keys and certificates as DER file
175 
176 certification authority:
177 
178  +cf --add-cert-file [c]ertificate filename: string
179  add certificate file to list of certificates
180 
181  +cd --add-cert-dir [c]ertificate directory: string
182  add certificates in d to list of certificates
183 
184 ciphersuite:
185 
186  +cs --cipher [c]iphersuite name: string
187  add ciphersuite to list of negotiated suites
188 
189  +dp --dhparam [f]ilename: string
190  read DH parameters for DH/DSS ciphersuites
191 
192 pseudo random generator:
193 
194  +rs --seed [f]ilename: string
195  seed random generator with contents of f
196 
197  +ws --write-seed
198  write back modified seed (only with --seed)
199 
200  +wf --write-seed-file [f]ilename: string (only with --seed)
201  write modified seed to file f
202 
203 peer authentication:
204 
205  -rc --require-peer-cert
206  verify peer certificate, fail if absent (default)
207 
208  -vc --verify-peer-cert
209  verify peer certificate if present
210 
211  -ic --ignore-peer-cert
212  don't verify peer certificate
213 \endverbatim
214 
215 \section notes NOTES
216 
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
221 example:
222 
223 \verbatim
224 # query patient names and IDs
225 (0008,0052) CS [PATIENT] # QueryRetrieveLevel
226 (0010,0010) PN [] # PatientName
227 (0010,0020) LO [] # PatientID
228 \endverbatim
229 
230 Individual attributes of each file sent can be modified or supplemented
231 using the \e -k option. For example the command:
232 
233 \verbatim
234 findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
235 \endverbatim
236 
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.
242 
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
246 still working.
247 
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:
250 
251 \verbatim
252 findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
253 \endverbatim
254 
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,
257 e. g.
258 
259 \verbatim
260 findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
261 \endverbatim
262 
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
267 of \b dcmodify.
268 
269 If no file is specified on the command line, the query must be specified
270 completely with one or more \e -k options.
271 
272 Each set of response identifiers received will be printed to stdout unless
273 option \e --extract is used.
274 
275 \subsection dicom_conformance DICOM Conformance
276 
277 The \b findscu application supports the following SOP Classes as an SCU:
278 
279 \verbatim
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
284 \endverbatim
285 
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
289 transfer syntaxes:
290 
291 \verbatim
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
295 \endverbatim
296 
297 The \b findscu application does not support extended negotiation.
298 
299 \section logging LOGGING
300 
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".
310 
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>).
317 
318 \section command_line COMMAND LINE
319 
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.
323 
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.
329 
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>).
339 
340 \section environment ENVIRONMENT
341 
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).
347 
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.
355 
356 \section see_also SEE ALSO
357 
358 <b>movescu</b>(1), <b>dump2dcm</b>(1), <b>dcmodify</b>(1)
359 
360 \section copyright COPYRIGHT
361 
362 Copyright (C) 1994-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
363 
364 */


Generated on Thu Aug 27 2015 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.8.9.1