1findscu(1)                        OFFIS DCMTK                       findscu(1)
2
3
4

NAME

6       findscu - DICOM query (C-FIND) SCU
7
8

SYNOPSIS

10       findscu [options] peer port [dcmfile-in...]
11

DESCRIPTION

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

PARAMETERS

21       peer        hostname of DICOM peer
22
23       port        tcp/ip port number of peer
24
25       dcmfile-in  DICOM query file(s)
26

OPTIONS

28   general options
29         -h    --help
30                 print this help text and exit
31
32               --version
33                 print version information and exit
34
35               --arguments
36                 print expanded command line arguments
37
38         -q    --quiet
39                 quiet mode, print no warnings and errors
40
41         -v    --verbose
42                 verbose mode, print processing details
43
44         -d    --debug
45                 debug mode, print debug information
46
47         -ll   --log-level  [l]evel: string constant
48                 (fatal, error, warn, info, debug, trace)
49                 use level l for the logger
50
51         -lc   --log-config  [f]ilename: string
52                 use config file f for the logger
53
54   network options
55       override matching keys:
56
57         -k    --key  [k]ey: gggg,eeee="str", path or dictionary name="str"
58                 override matching key
59
60       query information model:
61
62         -W    --worklist
63                 use modality worklist information model (default)
64
65         -P    --patient
66                 use patient root information model
67
68         -S    --study
69                 use study root information model
70
71         -O    --psonly
72                 use patient/study only information model
73
74       application entity titles:
75
76         -aet  --aetitle  [a]etitle: string
77                 set my calling AE title (default: FINDSCU)
78
79         -aec  --call  [a]etitle: string
80                 set called AE title of peer (default: ANY-SCP)
81
82       post-1993 value representations:
83
84         +u    --enable-new-vr
85                 enable support for new VRs (UN/UT) (default)
86
87         -u    --disable-new-vr
88                 disable support for new VRs, convert to OB
89
90       proposed transmission transfer syntaxes:
91
92         -x=   --propose-uncompr
93                 propose all uncompressed TS, explicit VR
94                 with local byte ordering first (default)
95
96         -xe   --propose-little
97                 propose all uncompressed TS, explicit VR
98                 little endian first
99
100         -xb   --propose-big
101                 propose all uncompressed TS, explicit VR
102                 big endian first
103
104         -xd   --propose-deflated
105                 propose deflated explicit VR little endian TS
106                 and all uncompressed transfer syntaxes
107
108         -xi   --propose-implicit
109                 propose implicit VR little endian TS only
110
111       deflate compression level (only with --propose-deflated):
112
113         +cl   --compression-level  [l]evel: integer (default: 6)
114                 0=uncompressed, 1=fastest, 9=best compression
115
116       other network options:
117
118         -to   --timeout  [s]econds: integer (default: unlimited)
119                 timeout for connection requests
120
121         -ta   --acse-timeout  [s]econds: integer (default: 30)
122                 timeout for ACSE messages
123
124         -td   --dimse-timeout  [s]econds: integer (default: unlimited)
125                 timeout for DIMSE messages
126
127         -pdu  --max-pdu  [n]umber of bytes: integer (4096..131072)
128                 set max receive pdu to n bytes (default: 16384)
129
130               --repeat  [n]umber: integer
131                 repeat n times
132
133               --abort
134                 abort association instead of releasing it
135
136               --cancel  [n]umber: integer
137                 cancel after n responses (default: never)
138
139   transport layer security (TLS) options
140       transport protocol stack:
141
142         -tls  --disable-tls
143                 use normal TCP/IP connection (default)
144
145         +tls  --enable-tls  [p]rivate key file, [c]ertificate file: string
146                 use authenticated secure TLS connection
147
148         +tla  --anonymous-tls
149                 use secure TLS connection without certificate
150
151       private key password (only with --enable-tls):
152
153         +ps   --std-passwd
154                 prompt user to type password on stdin (default)
155
156         +pw   --use-passwd  [p]assword: string
157                 use specified password
158
159         -pw   --null-passwd
160                 use empty string as password
161
162       key and certificate file format:
163
164         -pem  --pem-keys
165                 read keys and certificates as PEM file (default)
166
167         -der  --der-keys
168                 read keys and certificates as DER file
169
170       certification authority:
171
172         +cf   --add-cert-file  [c]ertificate filename: string
173                 add certificate file to list of certificates
174
175         +cd   --add-cert-dir  [c]ertificate directory: string
176                 add certificates in d to list of certificates
177
178       ciphersuite:
179
180         +cs   --cipher  [c]iphersuite name: string
181                 add ciphersuite to list of negotiated suites
182
183         +dp   --dhparam  [f]ilename: string
184                 read DH parameters for DH/DSS ciphersuites
185
186       pseudo random generator:
187
188         +rs   --seed  [f]ilename: string
189                 seed random generator with contents of f
190
191         +ws   --write-seed
192                 write back modified seed (only with --seed)
193
194         +wf   --write-seed-file  [f]ilename: string (only with --seed)
195                 write modified seed to file f
196
197       peer authentication:
198
199         -rc   --require-peer-cert
200                 verify peer certificate, fail if absent (default)
201
202         -vc   --verify-peer-cert
203                 verify peer certificate if present
204
205         -ic   --ignore-peer-cert
206                 don't verify peer certificate
207
208   output options
209       general:
210
211         -od   --output-directory  [d]irectory: string (default: ".")
212                 write output files to existing directory d
213
214       automatic data correction:
215
216         +dc   --enable-correction
217                 enable automatic data correction
218
219         -dc   --disable-correction
220                 disable automatic data correction (default)
221
222       C-FIND responses:
223
224         +sr   --show-responses
225                 always output responses to the logger
226
227         -sr   --hide-responses
228                 do not output responses to the logger
229
230         -X    --extract
231                 extract responses to file (rsp0001.dcm, ...)
232

NOTES

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
240       # query patient names and IDs
241       (0008,0052) CS [PATIENT]     # QueryRetrieveLevel
242       (0010,0010) PN []            # PatientName
243       (0010,0020) LO []            # PatientID
244
245       Individual attributes of each file sent can be modified or supplemented
246       using the -k option. For example the command:
247
248       findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
249
250       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
257       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
262       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
266       findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
267
268       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
272       findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
273
274       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
280       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
285       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
290   DICOM Conformance
291       The findscu application supports the following SOP Classes as an SCU:
292
293       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
298       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
303       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
308       (*) if compiled with zlib support enabled (see --version output)
309
310       Which transfer syntaxes are actually proposed in  what  order,  can  be
311       specified with the --propose options.
312
313       The findscu application does not support extended negotiation.
314

LOGGING

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
327       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

COMMAND LINE

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
341       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
348       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

ENVIRONMENT

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
365       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

SEE ALSO

375       movescu(1), dump2dcm(1), dcmodify(1)
376
378       Copyright  (C)  1994-2017  by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
379       Germany.
380
381
382
383Version 3.6.2                   Fri Jul 14 2017                     findscu(1)
Impressum