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 output options
82 general:
83 -od --output-directory [d]irectory: string (default: ".")
85 write received objects to existing directory d
86 subdirectory generation:
88 -s --no-subdir
90 do not generate any subdirectories (default)
91 +ssd --series-date-subdir
93 generate subdirectories from series date
94 filename generation:
96 +fd --default-filenames
98 generate filename from instance UID (default)
99 +fu --unique-filenames
101 generate unique filename based on new UID
102 +fsu --short-unique-names
104 generate short pseudo-random unique filename
105 +fst --system-time-names
107 generate filename from current system time
108 -fe --filename-extension [e]xtension: string (default: none)
110 append e to all generated filenames
111 storage mode:
113 -B --normal
115 allow implicit format conversions (default)
116 +B --bit-preserving
118 write dataset exactly as received
119 --ignore
121 ignore dataset, receive but do not store it
122
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 dcmrecv --verbose <port> --config-file storescp.cfg default
130 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 dcmrecv -v -xf storescp.cfg default <port> --series-date-subdir
136 --short-unique-names
137 --filename-extension .dcm
138 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 dcmrecv -v -xf storescp.cfg default <port> --bit-preserving
144 The received datasets are always stored as DICOM files with the same
146 Transfer Syntax as used for the network transmission.
147 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 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 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 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 <output-directory>/data/<year>/<month>/<day>/<filename>
173 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 <output-directory>/undef/<year><month><day>/<filename>
178 In both cases, <year> consists of 4 decimal digits and <month> as well
180 as <day> of 2 decimal digits.
181 Filename Generation
183 By default, the filenames for storing the received DICOM datasets are
184 generated according to the following scheme:
185 <short-modality-prefix>.<sop-instance-uid><filename-extension>
187 If the same SOP instance is received twice, a warning message is
189 reported and the existing file is overwritten.
190 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 <short-modality-prefix>.X.<unique-identifier><filename-extension>
199 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 <short-modality-prefix>_<pseudo-random-name><filename-extension>
206 With <pseudo-random-name> consisting of 16 digits in hexadecimal
208 notation.
209 Finally, option --system-time-names allows for generating filenames
211 based on the current system time:
212 <date><time>.<short-modality-prefix><filename-extension>
214 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 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
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 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
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 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 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
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 general
275 EXITCODE_NO_ERROR 0
276 EXITCODE_COMMANDLINE_SYNTAX_ERROR 1
277 input file errors
279 EXITCODE_CANNOT_READ_INPUT_FILE 20 (*)
280 output file errors
282 EXITCODE_CANNOT_WRITE_OUTPUT_FILE 40 (*)
283 EXITCODE_INVALID_OUTPUT_DIRECTORY 45
284 network errors
286 EXITCODE_CANNOT_INITIALIZE_NETWORK 60 (*)
287 EXITCODE_CANNOT_START_SCP_AND_LISTEN 64
288 EXITCODE_INVALID_ASSOCIATION_CONFIG 66
289 (*) Actually, these codes are currently not used by dcmrecv but serve
291 as a placeholder for the corresponding group of exit codes.
292
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 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
310 <docdir>/asconfig.txt - configuration file documentation
311 <etcdir>/storescp.cfg - example association negotiation profile
312
314 dcmsend(1), storescu(1), storescp(1)
315
317 Copyright (C) 2013-2017 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
318 Germany.
319Version 3.6.2 Fri Jul 14 2017 dcmrecv(1)