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 security profile:
118 +px --profile-bcp195
120 BCP 195 TLS Profile (default)
121 +py --profile-bcp195-nd
123 Non-downgrading BCP 195 TLS Profile
124 +pz --profile-bcp195-ex
126 Extended BCP 195 TLS Profile
127 +pb --profile-basic
129 Basic TLS Secure Transport Connection Profile (retired)
130 +pa --profile-aes
132 AES TLS Secure Transport Connection Profile (retired)
133 +pn --profile-null
135 Authenticated unencrypted communication
136 (retired, was used in IHE ATNA)
137 ciphersuite:
139 +cc --list-ciphers
141 show list of supported TLS ciphersuites and exit
142 +cs --cipher [c]iphersuite name: string
144 add ciphersuite to list of negotiated suites
145 +dp --dhparam [f]ilename: string
147 read DH parameters for DH/DSS ciphersuites
148 pseudo random generator:
150 +rs --seed [f]ilename: string
152 seed random generator with contents of f
153 +ws --write-seed
155 write back modified seed (only with --seed)
156 +wf --write-seed-file [f]ilename: string (only with --seed)
158 write modified seed to file f
159 peer authentication:
161 -rc --require-peer-cert
163 verify peer certificate, fail if absent (default)
164 -vc --verify-peer-cert
166 verify peer certificate if present
167 -ic --ignore-peer-cert
169 don't verify peer certificate
170 output options
172 general:
173 -od --output-directory [d]irectory: string (default: ".")
175 write received objects to existing directory d
176 subdirectory generation:
178 -s --no-subdir
180 do not generate any subdirectories (default)
181 +ssd --series-date-subdir
183 generate subdirectories from series date
184 filename generation:
186 +fd --default-filenames
188 generate filename from instance UID (default)
189 +fu --unique-filenames
191 generate unique filename based on new UID
192 +fsu --short-unique-names
194 generate short pseudo-random unique filename
195 +fst --system-time-names
197 generate filename from current system time
198 -fe --filename-extension [e]xtension: string (default: none)
200 append e to all generated filenames
201 storage mode:
203 -B --normal
205 allow implicit format conversions (default)
206 +B --bit-preserving
208 write dataset exactly as received
209 --ignore
211 ignore dataset, receive but do not store it
212
214 Typical Usage
215 A typical use case of dcmrecv is to receive SOP instances that are sent
216 from a storage SCU and save them as DICOM files. The following command
217 does exactly this:
218 dcmrecv --verbose <port> --config-file storescp.cfg default
220 If you prefer some automatically created subdirectory structure,
222 shorter file names and the extension '.dcm' for all DICOM files, use
223 the following command:
224 dcmrecv -v -xf storescp.cfg default <port> --series-date-subdir
226 --short-unique-names
227 --filename-extension .dcm
228 In case of very large SOP instances or if the dataset should be written
230 exactly as received (e.g. for debugging purposes), the 'bit preserving
231 mode' could be used:
232 dcmrecv -v -xf storescp.cfg default <port> --bit-preserving
234 The received datasets are always stored as DICOM files with the same
236 Transfer Syntax as used for the network transmission.
237 DICOM Conformance
239 Basically, the dcmrecv application supports all Storage SOP Classes as
240 an SCP, including private ones. This requires, however, that a
241 corresponding association negotiation profile is loaded from a
242 configuration file. The format and semantics of this configuration file
243 are documented in asconfig.txt.
244 By default, that means if no association negotiation profile is loaded,
246 dcmrecv only supports the Verification SOP Class as an SCP (with
247 default transfer syntax, i.e. Implicit VR Litte Endian).
248 In the future, there might be additional options that allow for
250 specifying the list of supported Presentation Contexts (i.e.
251 combination of SOP Class and Transfer Syntaxes) directly, i.e. without
252 loading a configuration file.
253 Subdirectory Generation
255 The option --series-date-subdir allows for generating subdirectories
256 (below the specified output directory) based on the value of the data
257 element Series Date (0008,0021) from the received DICOM dataset. If
258 this value could be retrieved from the dataset and is valid (i.e.
259 consists of a valid DICOM date field), the subdirectory structure is as
260 follows:
261 <output-directory>/data/<year>/<month>/<day>/<filename>
263 If the Series Date (0008,0021) cannot be retrieved or is invalid, the
265 current system date is used for the following subdirectory structure:
266 <output-directory>/undef/<year><month><day>/<filename>
268 In both cases, <year> consists of 4 decimal digits and <month> as well
270 as <day> of 2 decimal digits.
271 Filename Generation
273 By default, the filenames for storing the received DICOM datasets are
274 generated according to the following scheme:
275 <short-modality-prefix>.<sop-instance-uid><filename-extension>
277 If the same SOP instance is received twice, a warning message is
279 reported and the existing file is overwritten.
280 The option --unique-filenames makes sure that each received DICOM
282 dataset is stored as a separate file, i.e. no files should ever be
283 overwritten. This is done by using a newly created unique identifier
284 (UID) for each generated filename (and the infix '.X' in order to avoid
285 conflicts with real SOP Instance UID values). The naming scheme for
286 this option is as follows:
287 <short-modality-prefix>.X.<unique-identifier><filename-extension>
289 When option --short-unique-names is used, the filenames are generated
291 by some pseudo-random name generator, which also makes sure that there
292 are no conflicts (i.e. existing files are not overwritten). This is the
293 naming scheme:
294 <short-modality-prefix>_<pseudo-random-name><filename-extension>
296 With <pseudo-random-name> consisting of 16 digits in hexadecimal
298 notation.
299 Finally, option --system-time-names allows for generating filenames
301 based on the current system time:
302 <date><time>.<short-modality-prefix><filename-extension>
304 With <date> consisting of '<year><month><day>' and <time> of
306 '<hour><minute><second>.<micro-second>'. Please note that this scheme
307 could result in naming conflicts if the resolution of the system time
308 is not sufficiently high (i.e. does not support microseconds).
309 Limitations
311 Please note that option --bit-preserving cannot be used together with
312 option --series-date-subdir since the received dataset is stored
313 directly to file and the value of the Series Date (0008,0021) is,
314 therefore, not available before the file has been created.
315
317 The level of logging output of the various command line tools and
318 underlying libraries can be specified by the user. By default, only
319 errors and warnings are written to the standard error stream. Using
320 option --verbose also informational messages like processing details
321 are reported. Option --debug can be used to get more details on the
322 internal activity, e.g. for debugging purposes. Other logging levels
323 can be selected using option --log-level. In --quiet mode only fatal
324 errors are reported. In such very severe error events, the application
325 will usually terminate. For more details on the different logging
326 levels, see documentation of module 'oflog'.
327 In case the logging output should be written to file (optionally with
329 logfile rotation), to syslog (Unix) or the event log (Windows) option
330 --log-config can be used. This configuration file also allows for
331 directing only certain messages to a particular output stream and for
332 filtering certain messages based on the module or application where
333 they are generated. An example configuration file is provided in
334 <etcdir>/logger.cfg.
335
337 All command line tools use the following notation for parameters:
338 square brackets enclose optional values (0-1), three trailing dots
339 indicate that multiple values are allowed (1-n), a combination of both
340 means 0 to n values.
341 Command line options are distinguished from parameters by a leading '+'
343 or '-' sign, respectively. Usually, order and position of command line
344 options are arbitrary (i.e. they can appear anywhere). However, if
345 options are mutually exclusive the rightmost appearance is used. This
346 behavior conforms to the standard evaluation rules of common Unix
347 shells.
348 In addition, one or more command files can be specified using an '@'
350 sign as a prefix to the filename (e.g. @command.txt). Such a command
351 argument is replaced by the content of the corresponding text file
352 (multiple whitespaces are treated as a single separator unless they
353 appear between two quotation marks) prior to any further evaluation.
354 Please note that a command file cannot contain another command file.
355 This simple but effective approach allows one to summarize common
356 combinations of options/parameters and avoids longish and confusing
357 command lines (an example is provided in file <datadir>/dumppat.txt).
358
360 The dcmrecv utility uses the following exit codes when terminating.
361 This enables the user to check for the reason why the application
362 terminated.
363 general
365 EXITCODE_NO_ERROR 0
366 EXITCODE_COMMANDLINE_SYNTAX_ERROR 1
367 input file errors
369 EXITCODE_CANNOT_READ_INPUT_FILE 20 (*)
370 output file errors
372 EXITCODE_CANNOT_WRITE_OUTPUT_FILE 40 (*)
373 EXITCODE_INVALID_OUTPUT_DIRECTORY 45
374 network errors
376 EXITCODE_CANNOT_INITIALIZE_NETWORK 60 (*)
377 EXITCODE_CANNOT_START_SCP_AND_LISTEN 64
378 EXITCODE_INVALID_ASSOCIATION_CONFIG 66
379 EXITCODE_CANNOT_CREATE_TRANSPORT_LAYER 71
380 (*) Actually, these codes are currently not used by dcmrecv but serve
382 as a placeholder for the corresponding group of exit codes.
383
385 The dcmrecv utility will attempt to load DICOM data dictionaries
386 specified in the DCMDICTPATH environment variable. By default, i.e. if
387 the DCMDICTPATH environment variable is not set, the file
388 <datadir>/dicom.dic will be loaded unless the dictionary is built into
389 the application (default for Windows).
390 The default behavior should be preferred and the DCMDICTPATH
392 environment variable only used when alternative data dictionaries are
393 required. The DCMDICTPATH environment variable has the same format as
394 the Unix shell PATH variable in that a colon (':') separates entries.
395 On Windows systems, a semicolon (';') is used as a separator. The data
396 dictionary code will attempt to load each file specified in the
397 DCMDICTPATH environment variable. It is an error if no data dictionary
398 can be loaded.
399
401 <docdir>/asconfig.txt - configuration file documentation
402 <etcdir>/storescp.cfg - example association negotiation profile
403
405 dcmsend(1), storescu(1), storescp(1)
406
408 Copyright (C) 2013-2021 e.V., Escherweg 2, 26121 Oldenburg, Germany.
409Version 3.6.6 Thu Jan 14 2021 dcmrecv(1)