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         -ts   --socket-timeout  [s]econds: integer (default: 60)
122                 timeout for network socket (0 for none)
123
124         -ta   --acse-timeout  [s]econds: integer (default: 30)
125                 timeout for ACSE messages
126
127         -td   --dimse-timeout  [s]econds: integer (default: unlimited)
128                 timeout for DIMSE messages
129
130         -pdu  --max-pdu  [n]umber of bytes: integer (4096..131072)
131                 set max receive pdu to n bytes (default: 16384)
132
133               --repeat  [n]umber: integer
134                 repeat n times
135
136               --abort
137                 abort association instead of releasing it
138
139               --cancel  [n]umber: integer
140                 cancel after n responses (default: never)
141
142   transport layer security (TLS) options
143       transport protocol stack:
144
145         -tls  --disable-tls
146                 use normal TCP/IP connection (default)
147
148         +tls  --enable-tls  [p]rivate key file, [c]ertificate file: string
149                 use authenticated secure TLS connection
150
151         +tla  --anonymous-tls
152                 use secure TLS connection without certificate
153
154       private key password (only with --enable-tls):
155
156         +ps   --std-passwd
157                 prompt user to type password on stdin (default)
158
159         +pw   --use-passwd  [p]assword: string
160                 use specified password
161
162         -pw   --null-passwd
163                 use empty string as password
164
165       key and certificate file format:
166
167         -pem  --pem-keys
168                 read keys and certificates as PEM file (default)
169
170         -der  --der-keys
171                 read keys and certificates as DER file
172
173       certification authority:
174
175         +cf   --add-cert-file  [f]ilename: string
176                 add certificate file to list of certificates
177
178         +cd   --add-cert-dir  [d]irectory: string
179                 add certificates in d to list of certificates
180
181         +crl  --add-crl-file  [f]ilename: string
182                 add certificate revocation list file
183                 (implies --enable-crl-vfy)
184
185         +crv  --enable-crl-vfy
186                 enable leaf CRL verification
187
188         +cra  --enable-crl-all
189                 enable full chain CRL verification
190
191       security profile:
192
193         +py   --profile-bcp195-nd
194                 Non-downgrading BCP 195 TLS Profile (default)
195
196         +px   --profile-bcp195
197                 BCP 195 TLS Profile
198
199         +pz   --profile-bcp195-ex
200                 Extended BCP 195 TLS Profile
201
202         +pb   --profile-basic
203                 Basic TLS Secure Transport Connection Profile (retired)
204
205         +pa   --profile-aes
206                 AES TLS Secure Transport Connection Profile (retired)
207
208         +pn   --profile-null
209                 Authenticated unencrypted communication
210                 (retired, was used in IHE ATNA)
211
212       ciphersuite:
213
214         +cc   --list-ciphers
215                 show list of supported TLS ciphersuites and exit
216
217         +cs   --cipher  [c]iphersuite name: string
218                 add ciphersuite to list of negotiated suites
219
220       pseudo random generator:
221
222         +rs   --seed  [f]ilename: string
223                 seed random generator with contents of f
224
225         +ws   --write-seed
226                 write back modified seed (only with --seed)
227
228         +wf   --write-seed-file  [f]ilename: string (only with --seed)
229                 write modified seed to file f
230
231       peer authentication:
232
233         -rc   --require-peer-cert
234                 verify peer certificate, fail if absent (default)
235
236         -ic   --ignore-peer-cert
237                 don't verify peer certificate
238
239   output options
240       general:
241
242         -od   --output-directory  [d]irectory: string (default: ".")
243                 write output files to existing directory d
244
245       automatic data correction:
246
247         +dc   --enable-correction
248                 enable automatic data correction
249
250         -dc   --disable-correction
251                 disable automatic data correction (default)
252
253       C-FIND responses:
254
255         +sr   --show-responses
256                 always output responses to the logger
257
258         -sr   --hide-responses
259                 do not output responses to the logger
260
261         -X    --extract
262                 extract responses to DICOM file (rsp0001.dcm...)
263
264         -Xx   --extract-xml
265                 extract responses to XML file (rsp0001.xml...)
266
267         -Xs   --extract-xml-single  [f]ilename: string
268                 extract all responses to given XML file f
269
270         -Xlo  --limit-output  [n]umber: integer
271                 limit number of responses extracted to file to n
272                 (default: unlimited)
273

NOTES

275       Each file supplied on the command line will be sent to the SCP as  part
276       of  a  C-FIND  request.  The  query file must be a valid DICOM data set
277       containing the dataset part of a  C-FIND-RQ  message.  The  query  file
278       could, for instance, be created with the dump2dcm utility from a script
279       like the following example:
280
281       # query patient names and IDs
282       (0008,0052) CS [PATIENT]     # QueryRetrieveLevel
283       (0010,0010) PN []            # PatientName
284       (0010,0020) LO []            # PatientID
285
286       Individual attributes of each file sent can be modified or supplemented
287       using the -k option. For example the command:
288
289       findscu -P -k "(0010,0010)=HEWETT*" caesar 5678 patqry.dcm
290
291       will,  when  sent  to  the  SCP  caesar  at TCP/IP port 5678, cause any
292       PatientName attribute in patqry.dcm to have  the  value  'HEWETT*'.  If
293       such  an attribute is present it will be replaced, if absent it will be
294       inserted. The -k option can be present more than once. The  value  part
295       (after  the  '=')  may  be absent causing the attribute to be sent with
296       zero length.
297
298       In earlier versions of findscu, the tag  keys  were  specified  without
299       braces  around  group  and element number, e. g. '0010,0010' instead of
300       '(0010,0010)'. It is recommended switching to the new syntax;  however,
301       the old syntax is still working.
302
303       Also -k accepts dictionary names instead of element tags for specifying
304       DICOM elements. For example, the findscu call  above  then  reads  like
305       this:
306
307       findscu -P -k PatientName="HEWETT*" caesar 5678 patqry.dcm
308
309       It  is  also possible to specify sequences, items and nested attributes
310       using the -k option. In these cases, a special 'path' notation  has  to
311       be used, e. g.
312
313       findscu -W -k "(0040,0100)[0].Modality=CT" caesar 5678
314
315       This  call  queries  a  worklist  server at host caesar for any planned
316       procedures for CT modalities by specifying tag  (0040,0100)  'Scheduled
317       Procedure  Step Sequence' and an attribute 'Modality' in the first item
318       of this sequence with value 'CT'. Details on this path notation can  be
319       found in the documentation of dcmodify.
320
321       If  no  file  is  specified  on  the  command  line,  the query must be
322       specified completely with one or more -k  options.  If  multiple  query
323       files  are  provided, findscu will send multiple C-FIND requests to the
324       SCP.
325
326       Each set of response identifiers received will be output to the  logger
327       unless  option  --hide-responses,  any of the below --extract variants,
328       --quiet or an appropriate logger configuration is used. In such  cases,
329       the output to the logger can be enforced with option --show-responses.
330
331       In  addition, the response datasets can also be extracted as individual
332       DICOM files  (using  option  --extract)  or  XML  files  (using  option
333       --extract-xml).  The  output  format  of the latter is described by the
334       file dcm2xml.dtd (starting with top-level element 'data-set'). For  XML
335       files,  the  Specific  Character  Set  is  mapped  automatically  to an
336       appropriate XML encoding. If this is not possible, e.g. in case of  ISO
337       2022  character  sets,  non-ASCII  characters  and  those below #32 are
338       stored as '&#nnn;' where 'nnn' refers to the  numeric  character  code.
339       Please note that this might lead to invalid character entity references
340       (such as '' for ESC) and will cause most XML parsers to reject the
341       document.
342
343       Alternatively, all response datasets of an association can be extracted
344       to a single XML file using option --extract-xml-single.  The  top-level
345       element  of the XML document is 'responses' (with a 'type' attribute of
346       'C-FIND'). The individual datasets are stored as  described  above.  If
347       support  for  character  set  conversion  is enabled, UTF-8 encoding is
348       used, i.e. all datasets are  converted  to  UTF-8  encoding  (which  is
349       strongly recommended in order to avoid issues with non-ASCII characters
350       when different character sets are used).
351
352   DICOM Conformance
353       The findscu application supports the following SOP Classes as an SCU:
354
355       FINDPatientRootQueryRetrieveInformationModel       1.2.840.10008.5.1.4.1.2.1.1
356       FINDStudyRootQueryRetrieveInformationModel         1.2.840.10008.5.1.4.1.2.2.1
357       FINDPatientStudyOnlyQueryRetrieveInformationModel  1.2.840.10008.5.1.4.1.2.3.1
358       FINDModalityWorklistInformationModel               1.2.840.10008.5.1.4.31
359
360       The findscu application will propose presentation contexts for  one  of
361       the  abovementioned  supported  SOP  Classes  depending on command line
362       options (-P, -S, -O or -W). Basically, the following transfer  syntaxes
363       are supported:
364
365       LittleEndianImplicitTransferSyntax                 1.2.840.10008.1.2
366       LittleEndianExplicitTransferSyntax                 1.2.840.10008.1.2.1
367       DeflatedExplicitVRLittleEndianTransferSyntax       1.2.840.10008.1.2.1.99 (*)
368       BigEndianExplicitTransferSyntax                    1.2.840.10008.1.2.2
369
370       (*) if compiled with zlib support enabled (see --version output)
371
372       Which  transfer  syntaxes  are  actually proposed in what order, can be
373       specified with the --propose options.
374
375       The findscu application does not support extended negotiation.
376

LOGGING

378       The level of logging output of  the  various  command  line  tools  and
379       underlying  libraries  can  be  specified by the user. By default, only
380       errors and warnings are written to the  standard  error  stream.  Using
381       option  --verbose  also  informational messages like processing details
382       are reported. Option --debug can be used to get  more  details  on  the
383       internal  activity,  e.g.  for debugging purposes. Other logging levels
384       can be selected using option --log-level. In --quiet  mode  only  fatal
385       errors  are reported. In such very severe error events, the application
386       will usually terminate. For  more  details  on  the  different  logging
387       levels, see documentation of module 'oflog'.
388
389       In  case  the logging output should be written to file (optionally with
390       logfile rotation), to syslog (Unix) or the event log  (Windows)  option
391       --log-config  can  be  used.  This  configuration  file also allows for
392       directing only certain messages to a particular output stream  and  for
393       filtering  certain  messages  based  on the module or application where
394       they are generated.  An  example  configuration  file  is  provided  in
395       <etcdir>/logger.cfg.
396

COMMAND LINE

398       All  command  line  tools  use  the  following notation for parameters:
399       square brackets enclose optional  values  (0-1),  three  trailing  dots
400       indicate  that multiple values are allowed (1-n), a combination of both
401       means 0 to n values.
402
403       Command line options are distinguished from parameters by a leading '+'
404       or  '-' sign, respectively. Usually, order and position of command line
405       options are arbitrary (i.e. they  can  appear  anywhere).  However,  if
406       options  are  mutually exclusive the rightmost appearance is used. This
407       behavior conforms to the  standard  evaluation  rules  of  common  Unix
408       shells.
409
410       In  addition,  one  or more command files can be specified using an '@'
411       sign as a prefix to the filename (e.g. @command.txt).  Such  a  command
412       argument  is  replaced  by  the  content of the corresponding text file
413       (multiple whitespaces are treated as a  single  separator  unless  they
414       appear  between  two  quotation marks) prior to any further evaluation.
415       Please note that a command file cannot contain  another  command  file.
416       This  simple  but  effective  approach  allows  one to summarize common
417       combinations of options/parameters and  avoids  longish  and  confusing
418       command lines (an example is provided in file <datadir>/dumppat.txt).
419

ENVIRONMENT

421       The  findscu  utility  will  attempt  to  load  DICOM data dictionaries
422       specified in the DCMDICTPATH environment variable. By default, i.e.  if
423       the   DCMDICTPATH   environment   variable   is   not   set,  the  file
424       <datadir>/dicom.dic will be loaded unless the dictionary is built  into
425       the application (default for Windows).
426
427       The   default   behavior   should  be  preferred  and  the  DCMDICTPATH
428       environment variable only used when alternative data  dictionaries  are
429       required.  The  DCMDICTPATH environment variable has the same format as
430       the Unix shell PATH variable in that a colon (':')  separates  entries.
431       On  Windows systems, a semicolon (';') is used as a separator. The data
432       dictionary code will  attempt  to  load  each  file  specified  in  the
433       DCMDICTPATH  environment variable. It is an error if no data dictionary
434       can be loaded.
435

FILES

437       <datadir>/dcm2xml.dtd - Document Type Definition (DTD) file
438

SEE ALSO

440       movescu(1), dump2dcm(1), dcmodify(1)
441
443       Copyright (C) 1994-2022 by OFFIS e.V., Escherweg  2,  26121  Oldenburg,
444       Germany.
445
446
447
448Version 3.6.7                   Fri Apr 22 2022                     findscu(1)
Impressum