1dcmrecv(1) OFFIS DCMTK dcmrecv(1)
2
6 dcmrecv - Simple DICOM storage SCP (receiver)
7
10 dcmrecv [options] port
11
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
22 port tcp/ip port number to listen on
23
25 general options
26 -h --help
27 print this help text and exit
28 --version
30 print version information and exit
31 --arguments
33 print expanded command line arguments
34 -q --quiet
36 quiet mode, print no warnings and errors
37 -v --verbose
39 verbose mode, print processing details
40 -d --debug
42 debug mode, print debug information
43 -ll --log-level [l]evel: string constant
45 (fatal, error, warn, info, debug, trace)
46 use level l for the logger
47 -lc --log-config [f]ilename: string
49 use config file f for the logger
50 +v --verbose-pc
52 show presentation contexts in verbose mode
53 network options
55 association negotiation profile from configuration file:
56 -xf --config-file [f]ilename, [p]rofile: string
58 use profile p from configuration file f
59 application entity title:
61 -aet --aetitle [a]etitle: string
63 set my AE title (default: DCMRECV)
64 -uca --use-called-aetitle
66 always respond with called AE title
67 other network options:
69 -ta --acse-timeout [s]econds: integer (default: 30)
71 timeout for ACSE messages
72 -td --dimse-timeout [s]econds: integer (default: unlimited)
74 timeout for DIMSE messages
75 -pdu --max-pdu [n]umber of bytes: integer (4096..131072)
77 set max receive pdu to n bytes (default: 16384)
78 -dhl --disable-host-lookup disable hostname lookup
80 transport layer security (TLS) options
82 transport protocol stack:
83 -tls --disable-tls
85 use normal TCP/IP connection (default)
86 +tls --enable-tls [p]rivate key file, [c]ertificate file: string
88 use authenticated secure TLS connection
89 private key password (only with --enable-tls):
91 +ps --std-passwd
93 prompt user to type password on stdin (default)
94 +pw --use-passwd [p]assword: string
96 use specified password
97 -pw --null-passwd
99 use empty string as password
100 key and certificate file format:
102 -pem --pem-keys
104 read keys and certificates as PEM file (default)
105 -der --der-keys
107 read keys and certificates as DER file
108 certification authority:
110 +cf --add-cert-file [f]ilename: string
112 add certificate file to list of certificates
113 +cd --add-cert-dir [d]irectory: string
115 add certificates in d to list of certificates
116 +crl --add-crl-file [f]ilename: string
118 add certificate revocation list file
119 (implies --enable-crl-vfy)
120 +crv --enable-crl-vfy
122 enable leaf CRL verification
123 +cra --enable-crl-all
125 enable full chain CRL verification
126 security profile:
128 +py --profile-bcp195-nd
130 Non-downgrading BCP 195 TLS Profile (default)
131 +px --profile-bcp195
133 BCP 195 TLS Profile
134 +pz --profile-bcp195-ex
136 Extended BCP 195 TLS Profile
137 +pb --profile-basic
139 Basic TLS Secure Transport Connection Profile (retired)
140 +pa --profile-aes
142 AES TLS Secure Transport Connection Profile (retired)
143 +pn --profile-null
145 Authenticated unencrypted communication
146 (retired, was used in IHE ATNA)
147 ciphersuite:
149 +cc --list-ciphers
151 show list of supported TLS ciphersuites and exit
152 +cs --cipher [c]iphersuite name: string
154 add ciphersuite to list of negotiated suites
155 +dp --dhparam [f]ilename: string
157 read DH parameters for DH/DSS ciphersuites
158 pseudo random generator:
160 +rs --seed [f]ilename: string
162 seed random generator with contents of f
163 +ws --write-seed
165 write back modified seed (only with --seed)
166 +wf --write-seed-file [f]ilename: string (only with --seed)
168 write modified seed to file f
169 peer authentication:
171 -rc --require-peer-cert
173 verify peer certificate, fail if absent (default)
174 -vc --verify-peer-cert
176 verify peer certificate if present
177 -ic --ignore-peer-cert
179 don't verify peer certificate
180 output options
182 general:
183 -od --output-directory [d]irectory: string (default: ".")
185 write received objects to existing directory d
186 subdirectory generation:
188 -s --no-subdir
190 do not generate any subdirectories (default)
191 +ssd --series-date-subdir
193 generate subdirectories from series date
194 filename generation:
196 +fd --default-filenames
198 generate filename from instance UID (default)
199 +fu --unique-filenames
201 generate unique filename based on new UID
202 +fsu --short-unique-names
204 generate short pseudo-random unique filename
205 +fst --system-time-names
207 generate filename from current system time
208 -fe --filename-extension [e]xtension: string (default: none)
210 append e to all generated filenames
211 storage mode:
213 -B --normal
215 allow implicit format conversions (default)
216 +B --bit-preserving
218 write dataset exactly as received
219 --ignore
221 ignore dataset, receive but do not store it
222
224 Typical Usage
225 A typical use case of dcmrecv is to receive SOP instances that are sent
226 from a storage SCU and save them as DICOM files. The following command
227 does exactly this:
228 dcmrecv --verbose <port> --config-file storescp.cfg default
230 If you prefer some automatically created subdirectory structure,
232 shorter file names and the extension '.dcm' for all DICOM files, use
233 the following command:
234 dcmrecv -v -xf storescp.cfg default <port> --series-date-subdir
236 --short-unique-names
237 --filename-extension .dcm
238 In case of very large SOP instances or if the dataset should be written
240 exactly as received (e.g. for debugging purposes), the 'bit preserving
241 mode' could be used:
242 dcmrecv -v -xf storescp.cfg default <port> --bit-preserving
244 The received datasets are always stored as DICOM files with the same
246 Transfer Syntax as used for the network transmission.
247 DICOM Conformance
249 Basically, the dcmrecv application supports all Storage SOP Classes as
250 an SCP, including private ones. This requires, however, that a
251 corresponding association negotiation profile is loaded from a
252 configuration file. The format and semantics of this configuration file
253 are documented in asconfig.txt.
254 By default, that means if no association negotiation profile is loaded,
256 dcmrecv only supports the Verification SOP Class as an SCP (with
257 default transfer syntax, i.e. Implicit VR Litte Endian).
258 In the future, there might be additional options that allow for
260 specifying the list of supported Presentation Contexts (i.e.
261 combination of SOP Class and Transfer Syntaxes) directly, i.e. without
262 loading a configuration file.
263 Subdirectory Generation
265 The option --series-date-subdir allows for generating subdirectories
266 (below the specified output directory) based on the value of the data
267 element Series Date (0008,0021) from the received DICOM dataset. If
268 this value could be retrieved from the dataset and is valid (i.e.
269 consists of a valid DICOM date field), the subdirectory structure is as
270 follows:
271 <output-directory>/data/<year>/<month>/<day>/<filename>
273 If the Series Date (0008,0021) cannot be retrieved or is invalid, the
275 current system date is used for the following subdirectory structure:
276 <output-directory>/undef/<year><month><day>/<filename>
278 In both cases, <year> consists of 4 decimal digits and <month> as well
280 as <day> of 2 decimal digits.
281 Filename Generation
283 By default, the filenames for storing the received DICOM datasets are
284 generated according to the following scheme:
285 <short-modality-prefix>.<sop-instance-uid><filename-extension>
287 If the same SOP instance is received twice, a warning message is
289 reported and the existing file is overwritten.
290 The option --unique-filenames makes sure that each received DICOM
292 dataset is stored as a separate file, i.e. no files should ever be
293 overwritten. This is done by using a newly created unique identifier
294 (UID) for each generated filename (and the infix '.X' in order to avoid
295 conflicts with real SOP Instance UID values). The naming scheme for
296 this option is as follows:
297 <short-modality-prefix>.X.<unique-identifier><filename-extension>
299 When option --short-unique-names is used, the filenames are generated
301 by some pseudo-random name generator, which also makes sure that there
302 are no conflicts (i.e. existing files are not overwritten). This is the
303 naming scheme:
304 <short-modality-prefix>_<pseudo-random-name><filename-extension>
306 With <pseudo-random-name> consisting of 16 digits in hexadecimal
308 notation.
309 Finally, option --system-time-names allows for generating filenames
311 based on the current system time:
312 <date><time>.<short-modality-prefix><filename-extension>
314 With <date> consisting of '<year><month><day>' and <time> of
316 '<hour><minute><second>.<micro-second>'. Please note that this scheme
317 could result in naming conflicts if the resolution of the system time
318 is not sufficiently high (i.e. does not support microseconds).
319 Limitations
321 Please note that option --bit-preserving cannot be used together with
322 option --series-date-subdir since the received dataset is stored
323 directly to file and the value of the Series Date (0008,0021) is,
324 therefore, not available before the file has been created.
325
327 The level of logging output of the various command line tools and
328 underlying libraries can be specified by the user. By default, only
329 errors and warnings are written to the standard error stream. Using
330 option --verbose also informational messages like processing details
331 are reported. Option --debug can be used to get more details on the
332 internal activity, e.g. for debugging purposes. Other logging levels
333 can be selected using option --log-level. In --quiet mode only fatal
334 errors are reported. In such very severe error events, the application
335 will usually terminate. For more details on the different logging
336 levels, see documentation of module 'oflog'.
337 In case the logging output should be written to file (optionally with
339 logfile rotation), to syslog (Unix) or the event log (Windows) option
340 --log-config can be used. This configuration file also allows for
341 directing only certain messages to a particular output stream and for
342 filtering certain messages based on the module or application where
343 they are generated. An example configuration file is provided in
344 <etcdir>/logger.cfg.
345
347 All command line tools use the following notation for parameters:
348 square brackets enclose optional values (0-1), three trailing dots
349 indicate that multiple values are allowed (1-n), a combination of both
350 means 0 to n values.
351 Command line options are distinguished from parameters by a leading '+'
353 or '-' sign, respectively. Usually, order and position of command line
354 options are arbitrary (i.e. they can appear anywhere). However, if
355 options are mutually exclusive the rightmost appearance is used. This
356 behavior conforms to the standard evaluation rules of common Unix
357 shells.
358 In addition, one or more command files can be specified using an '@'
360 sign as a prefix to the filename (e.g. @command.txt). Such a command
361 argument is replaced by the content of the corresponding text file
362 (multiple whitespaces are treated as a single separator unless they
363 appear between two quotation marks) prior to any further evaluation.
364 Please note that a command file cannot contain another command file.
365 This simple but effective approach allows one to summarize common
366 combinations of options/parameters and avoids longish and confusing
367 command lines (an example is provided in file <datadir>/dumppat.txt).
368
370 The dcmrecv utility uses the following exit codes when terminating.
371 This enables the user to check for the reason why the application
372 terminated.
373 general
375 EXITCODE_NO_ERROR 0
376 EXITCODE_COMMANDLINE_SYNTAX_ERROR 1
377 input file errors
379 EXITCODE_CANNOT_READ_INPUT_FILE 20 (*)
380 output file errors
382 EXITCODE_CANNOT_WRITE_OUTPUT_FILE 40 (*)
383 EXITCODE_INVALID_OUTPUT_DIRECTORY 45
384 network errors
386 EXITCODE_CANNOT_INITIALIZE_NETWORK 60 (*)
387 EXITCODE_CANNOT_START_SCP_AND_LISTEN 64
388 EXITCODE_INVALID_ASSOCIATION_CONFIG 66
389 EXITCODE_CANNOT_CREATE_TRANSPORT_LAYER 71
390 (*) Actually, these codes are currently not used by dcmrecv but serve
392 as a placeholder for the corresponding group of exit codes.
393
395 The dcmrecv utility will attempt to load DICOM data dictionaries
396 specified in the DCMDICTPATH environment variable. By default, i.e. if
397 the DCMDICTPATH environment variable is not set, the file
398 <datadir>/dicom.dic will be loaded unless the dictionary is built into
399 the application (default for Windows).
400 The default behavior should be preferred and the DCMDICTPATH
402 environment variable only used when alternative data dictionaries are
403 required. The DCMDICTPATH environment variable has the same format as
404 the Unix shell PATH variable in that a colon (':') separates entries.
405 On Windows systems, a semicolon (';') is used as a separator. The data
406 dictionary code will attempt to load each file specified in the
407 DCMDICTPATH environment variable. It is an error if no data dictionary
408 can be loaded.
409
411 <docdir>/asconfig.txt - configuration file documentation
412 <etcdir>/storescp.cfg - example association negotiation profile
413
415 dcmsend(1), storescu(1), storescp(1)
416
418 Copyright (C) 2013-2022 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
419 Germany.
420Version 3.6.7 Fri Apr 22 2022 dcmrecv(1)