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

NAME

6       dcmrecv - Simple DICOM storage SCP (receiver)
7
8

SYNOPSIS

10       dcmrecv [options] port
11

DESCRIPTION

13       The  dcmrecv  application implements a Service Class Provider (SCP) for
14       the Storage Service Class.  In  contrast  to  the  well-known  storescp
15       utility,  dcmrecv  has  less options and might, therefore, be easier to
16       use - this also explains the term  'simple'  in  the  title.  The  main
17       purpose  of  this  application  is  to  receive  a whole bunch of DICOM
18       datasets from a Storage Service Class User (SCU) and store  them  to  a
19       configurable directory and file structure.
20

PARAMETERS

22       port  tcp/ip port number to listen on
23

OPTIONS

25   general options
26         -h    --help
27                 print this help text and exit
28
29               --version
30                 print version information and exit
31
32               --arguments
33                 print expanded command line arguments
34
35         -q    --quiet
36                 quiet mode, print no warnings and errors
37
38         -v    --verbose
39                 verbose mode, print processing details
40
41         -d    --debug
42                 debug mode, print debug information
43
44         -ll   --log-level  [l]evel: string constant
45                 (fatal, error, warn, info, debug, trace)
46                 use level l for the logger
47
48         -lc   --log-config  [f]ilename: string
49                 use config file f for the logger
50
51         +v    --verbose-pc
52                 show presentation contexts in verbose mode
53
54   network options
55       association negotiation profile from configuration file:
56
57         -xf   --config-file  [f]ilename, [p]rofile: string
58                 use profile p from configuration file f
59
60       application entity title:
61
62         -aet  --aetitle  [a]etitle: string
63                 set my AE title (default: DCMRECV)
64
65         -uca  --use-called-aetitle
66                 always respond with called AE title
67
68       other network options:
69
70         -ta   --acse-timeout  [s]econds: integer (default: 30)
71                 timeout for ACSE messages
72
73         -td   --dimse-timeout  [s]econds: integer (default: unlimited)
74                 timeout for DIMSE messages
75
76         -pdu  --max-pdu  [n]umber of bytes: integer (4096..131072)
77                 set max receive pdu to n bytes (default: 16384)
78
79         -dhl  --disable-host-lookup  disable hostname lookup
80
81   output options
82       general:
83
84         -od   --output-directory  [d]irectory: string (default: ".")
85                 write received objects to existing directory d
86
87       subdirectory generation:
88
89         -s    --no-subdir
90                 do not generate any subdirectories (default)
91
92         +ssd  --series-date-subdir
93                 generate subdirectories from series date
94
95       filename generation:
96
97         +fd   --default-filenames
98                 generate filename from instance UID (default)
99
100         +fu   --unique-filenames
101                 generate unique filename based on new UID
102
103         +fsu  --short-unique-names
104                 generate short pseudo-random unique filename
105
106         +fst  --system-time-names
107                 generate filename from current system time
108
109         -fe   --filename-extension  [e]xtension: string (default: none)
110                 append e to all generated filenames
111
112       storage mode:
113
114         -B    --normal
115                 allow implicit format conversions (default)
116
117         +B    --bit-preserving
118                 write dataset exactly as received
119
120               --ignore
121                 ignore dataset, receive but do not store it
122

NOTES

124   Typical Usage
125       A typical use case of dcmrecv is to receive SOP instances that are sent
126       from a storage SCU and save them as DICOM files. The following  command
127       does exactly this:
128
129       dcmrecv --verbose <port> --config-file storescp.cfg default
130
131       If  you  prefer  some  automatically  created  subdirectory  structure,
132       shorter file names and the extension '.dcm' for all  DICOM  files,  use
133       the following command:
134
135       dcmrecv -v -xf storescp.cfg default <port> --series-date-subdir
136                                                  --short-unique-names
137                                                  --filename-extension .dcm
138
139       In case of very large SOP instances or if the dataset should be written
140       exactly as received (e.g. for debugging purposes), the 'bit  preserving
141       mode' could be used:
142
143       dcmrecv -v -xf storescp.cfg default <port> --bit-preserving
144
145       The  received  datasets  are always stored as DICOM files with the same
146       Transfer Syntax as used for the network transmission.
147
148   DICOM Conformance
149       Basically, the dcmrecv application supports all Storage SOP Classes  as
150       an  SCP,  including  private  ones.  This  requires,  however,  that  a
151       corresponding  association  negotiation  profile  is  loaded   from   a
152       configuration file. The format and semantics of this configuration file
153       are documented in asconfig.txt.
154
155       By default, that means if no association negotiation profile is loaded,
156       dcmrecv  only  supports  the  Verification  SOP  Class  as an SCP (with
157       default transfer syntax, i.e. Implicit VR Litte Endian).
158
159       In the future,  there  might  be  additional  options  that  allow  for
160       specifying   the   list   of   supported  Presentation  Contexts  (i.e.
161       combination of SOP Class and Transfer Syntaxes) directly, i.e.  without
162       loading a configuration file.
163
164   Subdirectory Generation
165       The  option  --series-date-subdir  allows for generating subdirectories
166       (below the specified output directory) based on the value of  the  data
167       element  Series  Date  (0008,0021)  from the received DICOM dataset. If
168       this value could be retrieved from  the  dataset  and  is  valid  (i.e.
169       consists of a valid DICOM date field), the subdirectory structure is as
170       follows:
171
172       <output-directory>/data/<year>/<month>/<day>/<filename>
173
174       If the Series Date (0008,0021) cannot be retrieved or is  invalid,  the
175       current system date is used for the following subdirectory structure:
176
177       <output-directory>/undef/<year><month><day>/<filename>
178
179       In  both cases, <year> consists of 4 decimal digits and <month> as well
180       as <day> of 2 decimal digits.
181
182   Filename Generation
183       By default, the filenames for storing the received DICOM  datasets  are
184       generated according to the following scheme:
185
186       <short-modality-prefix>.<sop-instance-uid><filename-extension>
187
188       If  the  same  SOP  instance  is  received  twice, a warning message is
189       reported and the existing file is overwritten.
190
191       The option --unique-filenames  makes  sure  that  each  received  DICOM
192       dataset  is  stored  as  a  separate file, i.e. no files should ever be
193       overwritten. This is done by using a newly  created  unique  identifier
194       (UID) for each generated filename (and the infix '.X' in order to avoid
195       conflicts with real SOP Instance UID values).  The  naming  scheme  for
196       this option is as follows:
197
198       <short-modality-prefix>.X.<unique-identifier><filename-extension>
199
200       When  option  --short-unique-names is used, the filenames are generated
201       by some pseudo-random name generator, which also makes sure that  there
202       are no conflicts (i.e. existing files are not overwritten). This is the
203       naming scheme:
204
205       <short-modality-prefix>_<pseudo-random-name><filename-extension>
206
207       With  <pseudo-random-name>  consisting  of  16  digits  in  hexadecimal
208       notation.
209
210       Finally,  option  --system-time-names  allows  for generating filenames
211       based on the current system time:
212
213       <date><time>.<short-modality-prefix><filename-extension>
214
215       With  <date>  consisting  of   '<year><month><day>'   and   <time>   of
216       '<hour><minute><second>.<micro-second>'.  Please  note that this scheme
217       could result in naming conflicts if the resolution of the  system  time
218       is not sufficiently high (i.e. does not support microseconds).
219
220   Limitations
221       Please  note  that option --bit-preserving cannot be used together with
222       option  --series-date-subdir  since  the  received  dataset  is  stored
223       directly  to  file  and  the  value  of the Series Date (0008,0021) is,
224       therefore, not available before the file has been created.
225

LOGGING

227       The level of logging output of  the  various  command  line  tools  and
228       underlying  libraries  can  be  specified by the user. By default, only
229       errors and warnings are written to the  standard  error  stream.  Using
230       option  --verbose  also  informational messages like processing details
231       are reported. Option --debug can be used to get  more  details  on  the
232       internal  activity,  e.g.  for debugging purposes. Other logging levels
233       can be selected using option --log-level. In --quiet  mode  only  fatal
234       errors  are reported. In such very severe error events, the application
235       will usually terminate. For  more  details  on  the  different  logging
236       levels, see documentation of module 'oflog'.
237
238       In  case  the logging output should be written to file (optionally with
239       logfile rotation), to syslog (Unix) or the event log  (Windows)  option
240       --log-config  can  be  used.  This  configuration  file also allows for
241       directing only certain messages to a particular output stream  and  for
242       filtering  certain  messages  based  on the module or application where
243       they are generated.  An  example  configuration  file  is  provided  in
244       <etcdir>/logger.cfg.
245

COMMAND LINE

247       All  command  line  tools  use  the  following notation for parameters:
248       square brackets enclose optional  values  (0-1),  three  trailing  dots
249       indicate  that multiple values are allowed (1-n), a combination of both
250       means 0 to n values.
251
252       Command line options are distinguished from parameters by a leading '+'
253       or  '-' sign, respectively. Usually, order and position of command line
254       options are arbitrary (i.e. they  can  appear  anywhere).  However,  if
255       options  are  mutually exclusive the rightmost appearance is used. This
256       behavior conforms to the  standard  evaluation  rules  of  common  Unix
257       shells.
258
259       In  addition,  one  or more command files can be specified using an '@'
260       sign as a prefix to the filename (e.g. @command.txt).  Such  a  command
261       argument  is  replaced  by  the  content of the corresponding text file
262       (multiple whitespaces are treated as a  single  separator  unless  they
263       appear  between  two  quotation marks) prior to any further evaluation.
264       Please note that a command file cannot contain  another  command  file.
265       This  simple  but  effective  approach  allows  one to summarize common
266       combinations of options/parameters and  avoids  longish  and  confusing
267       command lines (an example is provided in file <datadir>/dumppat.txt).
268

EXIT CODES

270       The  dcmrecv  utility  uses  the following exit codes when terminating.
271       This enables the user to check  for  the  reason  why  the  application
272       terminated.
273
274   general
275       EXITCODE_NO_ERROR                         0
276       EXITCODE_COMMANDLINE_SYNTAX_ERROR         1
277
278   input file errors
279       EXITCODE_CANNOT_READ_INPUT_FILE          20 (*)
280
281   output file errors
282       EXITCODE_CANNOT_WRITE_OUTPUT_FILE        40 (*)
283       EXITCODE_INVALID_OUTPUT_DIRECTORY        45
284
285   network errors
286       EXITCODE_CANNOT_INITIALIZE_NETWORK       60 (*)
287       EXITCODE_CANNOT_START_SCP_AND_LISTEN     64
288       EXITCODE_INVALID_ASSOCIATION_CONFIG      66
289
290       (*)  Actually,  these codes are currently not used by dcmrecv but serve
291       as a placeholder for the corresponding group of exit codes.
292

ENVIRONMENT

294       The dcmrecv utility  will  attempt  to  load  DICOM  data  dictionaries
295       specified  in the DCMDICTPATH environment variable. By default, i.e. if
296       the  DCMDICTPATH  environment   variable   is   not   set,   the   file
297       <datadir>/dicom.dic  will be loaded unless the dictionary is built into
298       the application (default for Windows).
299
300       The  default  behavior  should  be  preferred   and   the   DCMDICTPATH
301       environment  variable  only used when alternative data dictionaries are
302       required. The DCMDICTPATH environment variable has the same  format  as
303       the  Unix  shell PATH variable in that a colon (':') separates entries.
304       On Windows systems, a semicolon (';') is used as a separator. The  data
305       dictionary  code  will  attempt  to  load  each  file  specified in the
306       DCMDICTPATH environment variable. It is an error if no data  dictionary
307       can be loaded.
308

FILES

310       <docdir>/asconfig.txt - configuration file documentation
311       <etcdir>/storescp.cfg - example association negotiation profile
312

SEE ALSO

314       dcmsend(1), storescu(1), storescp(1)
315
317       Copyright  (C)  2013-2017  by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
318       Germany.
319
320
321
322Version 3.6.2                   Fri Jul 14 2017                     dcmrecv(1)
Impressum