dcmrecv - Man Page

Simple DICOM storage SCP (receiver)

Synopsis

dcmrecv [options] port

Description

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

Parameters

port  tcp/ip port number to listen on

Options

general options

  -h    --help
          print this help text and exit

        --version
          print version information and exit

        --arguments
          print expanded command line arguments

  -q    --quiet
          quiet mode, print no warnings and errors

  -v    --verbose
          verbose mode, print processing details

  -d    --debug
          debug mode, print debug information

  -ll   --log-level  [l]evel: string constant
          (fatal, error, warn, info, debug, trace)
          use level l for the logger

  -lc   --log-config  [f]ilename: string
          use config file f for the logger

  +v    --verbose-pc
          show presentation contexts in verbose mode

network options

association negotiation profile from configuration file:

  -xf   --config-file  [f]ilename, [p]rofile: string
          use profile p from configuration file f

application entity title:

  -uca  --use-called-aetitle
          always respond with called AE title (default)

  -aet  --aetitle  [a]etitle: string
          set my AE title and check called AE title

other network options:

  -ta   --acse-timeout  [s]econds: integer (default: 30)
          timeout for ACSE messages

  -td   --dimse-timeout  [s]econds: integer (default: unlimited)
          timeout for DIMSE messages

  -pdu  --max-pdu  [n]umber of bytes: integer (4096..131072)
          set max receive pdu to n bytes (default: 16384)

  -dhl  --disable-host-lookup  disable hostname lookup

transport layer security (TLS) options

transport protocol stack:

  -tls  --disable-tls
          use normal TCP/IP connection (default)

  +tls  --enable-tls  [p]rivate key file, [c]ertificate file: string
          use authenticated secure TLS connection

private key password (only with --enable-tls):

  +ps   --std-passwd
          prompt user to type password on stdin (default)

  +pw   --use-passwd  [p]assword: string
          use specified password

  -pw   --null-passwd
          use empty string as password

key and certificate file format:

  -pem  --pem-keys
          read keys and certificates as PEM file (default)

  -der  --der-keys
          read keys and certificates as DER file

certification authority:

  +cf   --add-cert-file  [f]ilename: string
          add certificate file to list of certificates

  +cd   --add-cert-dir  [d]irectory: string
          add certificates in d to list of certificates

  +crl  --add-crl-file  [f]ilename: string
          add certificate revocation list file
          (implies --enable-crl-vfy)

  +crv  --enable-crl-vfy
          enable leaf CRL verification

  +cra  --enable-crl-all
          enable full chain CRL verification

security profile:

  +ph   --list-profiles
          list supported TLS profiles and exit

  +pg   --profile-8996
          BCP 195 RFC 8996 TLS Profile (default)

  +pm   --profile-8996-mod
          Modified BCP 195 RFC 8996 TLS Profile

          # only available if underlying TLS library supports
          # all TLS features required for this profile

  +py   --profile-bcp195-nd
          Non-downgrading BCP 195 TLS Profile (retired)

  +px   --profile-bcp195
          BCP 195 TLS Profile (retired)

  +pz   --profile-bcp195-ex
          Extended BCP 195 TLS Profile (retired)

  +pb   --profile-basic
          Basic TLS Secure Transport Connection Profile (retired)

          # only available if underlying TLS library supports 3DES

  +pa   --profile-aes
          AES TLS Secure Transport Connection Profile (retired)

  +pn   --profile-null
          Authenticated unencrypted communication
          (retired, was used in IHE ATNA)

ciphersuite:

  +cc   --list-ciphers
          list supported TLS ciphersuites and exit

  +cs   --cipher  [c]iphersuite name: string
          add ciphersuite to list of negotiated suites

  +dp   --dhparam  [f]ilename: string
          read DH parameters for DH/DSS ciphersuites

server name indication:

        --no-sni
          do not use SNI (default)

        --expect-sni  [s]erver name: string
          expect requests for server name s

pseudo random generator:

  +rs   --seed  [f]ilename: string
          seed random generator with contents of f

  +ws   --write-seed
          write back modified seed (only with --seed)

  +wf   --write-seed-file  [f]ilename: string (only with --seed)
          write modified seed to file f

peer authentication:

  -rc   --require-peer-cert
          verify peer certificate, fail if absent (default)

  -vc   --verify-peer-cert
          verify peer certificate if present

  -ic   --ignore-peer-cert
          don't verify peer certificate

output options

general:

  -od   --output-directory  [d]irectory: string (default: ".")
          write received objects to existing directory d

subdirectory generation:

  -s    --no-subdir
          do not generate any subdirectories (default)

  +ssd  --series-date-subdir
          generate subdirectories from series date

filename generation:

  +fd   --default-filenames
          generate filename from instance UID (default)

  +fu   --unique-filenames
          generate unique filename based on new UID

  +fsu  --short-unique-names
          generate short pseudo-random unique filename

  +fst  --system-time-names
          generate filename from current system time

  -fe   --filename-extension  [e]xtension: string (default: none)
          append e to all generated filenames

storage mode:

  -B    --normal
          allow implicit format conversions (default)

  +B    --bit-preserving
          write dataset exactly as received

        --ignore
          ignore dataset, receive but do not store it

Notes

Typical Usage

A typical use case of dcmrecv is to receive SOP instances that are sent from a storage SCU and save them as DICOM files​. The following command does exactly this:

dcmrecv --verbose <port> --config-file storescp.cfg default

If you prefer some automatically created subdirectory structure, shorter file names and the extension '​.dcm' for all DICOM files, use the following command:

dcmrecv -v -xf storescp.cfg default <port> --series-date-subdir
                                           --short-unique-names
                                           --filename-extension .dcm

In case of very large SOP instances or if the dataset should be written exactly as received (e​.g​. for debugging purposes), the 'bit preserving mode' could be used:

dcmrecv -v -xf storescp.cfg default <port> --bit-preserving

The received datasets are always stored as DICOM files with the same Transfer Syntax as used for the network transmission​.

DICOM Conformance

Basically, the dcmrecv application supports all Storage SOP Classes as an SCP, including private ones​. This requires, however, that a corresponding association negotiation profile is loaded from a configuration file​. The format and semantics of this configuration file are documented in asconfig​.txt​.

By default, that means if no association negotiation profile is loaded, dcmrecv only supports the Verification SOP Class as an SCP (with default transfer syntax, i​.e​. Implicit VR Little Endian)​.

In the future, there might be additional options that allow for specifying the list of supported Presentation Contexts (i​.e​. combination of SOP Class and Transfer Syntaxes) directly, i​.e​. without loading a configuration file​.

Subdirectory Generation

The option --series-date-subdir allows for generating subdirectories (below the specified output directory) based on the value of the data element Series Date (0008,0021) from the received DICOM dataset​. If this value could be retrieved from the dataset and is valid (i​.e​. consists of a valid DICOM date field), the subdirectory structure is as follows:

<output-directory>/data/<year>/<month>/<day>/<filename>

If the Series Date (0008,0021) cannot be retrieved or is invalid, the current system date is used for the following subdirectory structure:

<output-directory>/undef/<year><month><day>/<filename>

In both cases, <year> consists of 4 decimal digits and <month> as well as <day> of 2 decimal digits​.

Filename Generation

By default, the filenames for storing the received DICOM datasets are generated according to the following scheme:

<short-modality-prefix>.<sop-instance-uid><filename-extension>

If the same SOP instance is received twice, a warning message is reported and the existing file is overwritten​.

The option --unique-filenames makes sure that each received DICOM dataset is stored as a separate file, i​.e​. no files should ever be overwritten​. This is done by using a newly created unique identifier (UID) for each generated filename (and the infix '​.X' in order to avoid conflicts with real SOP Instance UID values)​. The naming scheme for this option is as follows:

<short-modality-prefix>.X.<unique-identifier><filename-extension>

When option --short-unique-names is used, the filenames are generated by some pseudo-random name generator, which also makes sure that there are no conflicts (i​.e​. existing files are not overwritten)​. This is the naming scheme:

<short-modality-prefix>_<pseudo-random-name><filename-extension>

With <pseudo-random-name> consisting of 16 digits in hexadecimal notation​.

Finally, option --system-time-names allows for generating filenames based on the current system time:

<date><time>.<short-modality-prefix><filename-extension>

With <date> consisting of '<year><month><day>' and <time> of '<hour><minute><second>​.<micro-second>'​. Please note that this scheme could result in naming conflicts if the resolution of the system time is not sufficiently high (i​.e​. does not support microseconds)​.

Limitations

Please note that option --bit-preserving cannot be used together with option --series-date-subdir since the received dataset is stored directly to file and the value of the Series Date (0008,0021) is, therefore, not available before the file has been created​.

Logging

The level of logging output of the various command line tools and underlying libraries can be specified by the user​. By default, only errors and warnings are written to the standard error stream​. Using option --verbose also informational messages like processing details are reported​. Option --debug can be used to get more details on the internal activity, e​.g​. for debugging purposes​. Other logging levels can be selected using option --log-level​. In --quiet mode only fatal errors are reported​. In such very severe error events, the application will usually terminate​. For more details on the different logging levels, see documentation of module 'oflog'​.

In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option --log-config can be used​. This configuration file also allows for directing only certain messages to a particular output stream and for filtering certain messages based on the module or application where they are generated​. An example configuration file is provided in <etcdir>/logger​.cfg​.

Command Line

All command line tools use the following notation for parameters: square brackets enclose optional values (0-1), three trailing dots indicate that multiple values are allowed (1-n), a combination of both means 0 to n values​.

Command line options are distinguished from parameters by a leading '+' or '-' sign, respectively​. Usually, order and position of command line options are arbitrary (i​.e​. they can appear anywhere)​. However, if options are mutually exclusive the rightmost appearance is used​. This behavior conforms to the standard evaluation rules of common Unix shells​.

In addition, one or more command files can be specified using an '@' sign as a prefix to the filename (e​.g​. @command​.txt)​. Such a command argument is replaced by the content of the corresponding text file (multiple whitespaces are treated as a single separator unless they appear between two quotation marks) prior to any further evaluation​. Please note that a command file cannot contain another command file​. This simple but effective approach allows one to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file <datadir>/dumppat​.txt)​.

Exit Codes

The dcmrecv utility uses the following exit codes when terminating​. This enables the user to check for the reason why the application terminated​.

general

EXITCODE_NO_ERROR                         0
EXITCODE_COMMANDLINE_SYNTAX_ERROR         1

input file errors

EXITCODE_CANNOT_READ_INPUT_FILE          20 (*)

output file errors

EXITCODE_CANNOT_WRITE_OUTPUT_FILE        40 (*)
EXITCODE_INVALID_OUTPUT_DIRECTORY        45

network errors

EXITCODE_CANNOT_INITIALIZE_NETWORK       60 (*)
EXITCODE_CANNOT_START_SCP_AND_LISTEN     64
EXITCODE_INVALID_ASSOCIATION_CONFIG      66
EXITCODE_CANNOT_CREATE_TRANSPORT_LAYER   71

(*) Actually, these codes are currently not used by dcmrecv but serve as a placeholder for the corresponding group of exit codes​.

Environment

The dcmrecv utility will attempt to load DICOM data dictionaries specified in the DCMDICTPATH environment variable​. By default, i​.e​. if the DCMDICTPATH environment variable is not set, the file <datadir>/dicom​.dic will be loaded unless the dictionary is built into the application (default for Windows)​.

The default behavior should be preferred and the DCMDICTPATH environment variable only used when alternative data dictionaries are required​. The DCMDICTPATH environment variable has the same format as the Unix shell PATH variable in that a colon (':') separates entries​. On Windows systems, a semicolon (';') is used as a separator​. The data dictionary code will attempt to load each file specified in the DCMDICTPATH environment variable​. It is an error if no data dictionary can be loaded​.

Files

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

See Also

dcmsend(1), storescu(1), storescp(1)

Info

Wed Dec 11 2024 Version 3.6.9 OFFIS DCMTK