|
DCMTK
Version 3.6.9
OFFIS DICOM Toolkit
|
stcomscu [options] [peer] [port] [dcmfile-in...]
The stcomscu utility implements a Service Class User (SCU) for the Storage Commitment Service Class, i.e. it allows for sending a storage commitment request to a Service Class Provider (SCP) using an N-ACTION message and for receiving the related response using an N-EVENT-REPORT message. The datasets sent and received with the messages are typically stored as DICOM files in order to allow for further analysis, e.g. using the dcmdump utility.
In addition to a client mode, where the N-EVENT-REPORT request is expected on the same association as the one used for the N-ACTION request, there is also a server mode, where a different association is used for the N-EVENT-REPORT request. There is also a combined client/server mode where the stcomscu waits a particular period of time for the N-EVENT-REPORT message and then switches to server mode if the timeout elapsed without receiving such message.
peer hostname of DICOM peer
port tcp/ip port number of peer
dcmfile-in DICOM file or directory to be committed
("-" for stdin)
-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
input file format:
+f --read-file
read file format or data set
+fo --read-file-only
read file format only (default)
-f --read-dataset
read data set without file meta information
input files:
+sd --scan-directories
scan directories for input files (dcmfile-in)
+sp --scan-pattern [p]attern: string (only with --scan-directories)
pattern for filename matching (wildcards)
# possibly not available on all systems
-r --no-recurse
do not recurse within directories (default)
+r --recurse
recurse within specified directories
deflate compression level:
+cl --compression-level [l]evel: integer (default: 6)
0=uncompressed, 1=fastest, 9=best compression
other processing options:
-nh --no-halt
do not halt on first invalid input file
-nuc --no-uid-checks
do not check UID values of input files
application entity titles:
-aet --aetitle [a]etitle: string
set my calling AE title (default: STCOMSCU)
-aec --call [a]etitle: string
set called AE title of peer (default: ANY-SCP)
preferred transmission transfer syntaxes (incoming associations):
+x= --prefer-uncompr
prefer explicit VR local byte ordering (default)
+xe --prefer-little
prefer explicit VR little endian transfer syntax
+xb --prefer-big
prefer explicit VR big endian transfer syntax
+xd --prefer-deflated
prefer deflated explicit VR little endian transfer syntax
+xi --implicit
accept implicit VR little endian transfer syntax only
proposed transmission transfer syntaxes (outgoing associations):
-x= --propose-uncompr
propose all uncompressed transfer syntaxes,
explicit VR with local byte ordering first (default)
-xe --propose-little
propose all uncompressed transfer syntaxes,
explicit VR little endian first
-xb --propose-big
propose all uncompressed transfer syntaxes,
explicit VR big endian first
-xd --propose-deflated
propose deflated explicit VR little endian transfer syntax
and all uncompressed transfer syntaxes
-xi --propose-implicit
propose implicit VR little endian transfer syntax only
network host access control (tcp wrapper):
-ac --access-full
accept connections from any host (default)
+ac --access-control
enforce host access control rules
incoming network associations:
--no-port
no port for incoming associations (default)
+P --port [n]umber: integer
port number for incoming associations
--wait-for-event
wait for N-EVENT-REPORT request on the same association
(default for "client mode")
-nwe --no-wait-for-event
do not wait for N-EVENT-REPORT request on the same association
(not in "server mode")
--role-reject
reject presentation contexts in case of unsuccessful
SCP/SCU role selection (default)
-nrr --no-role-reject
do not reject presentation contexts in case of
unsuccessful SCP/SCU role selection
other network options:
-to --timeout [s]econds: integer (default: unlimited)
timeout for connection requests
-ta --acse-timeout [s]econds: integer (default: 30)
timeout for ACSE messages
-td --dimse-timeout [s]econds: integer (default: unlimited)
timeout for DIMSE messages
-te --event-timeout [s]econds: integer (default: same as for -td)
timeout for N-EVENT-REPORT request messages
-pdu --max-pdu [n]umber of bytes: integer (4096..131072)
set max receive pdu to n bytes (default: 16384)
--max-send-pdu [n]umber of bytes: integer (4096..131072)
restrict max send pdu to n bytes
-dhl --disable-host-lookup
disable hostname lookup
--abort
abort association instead of releasing it
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 certs 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]directory: 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)
--request-sni [s]erver name: string
request server name s
--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 cert, fail if absent (default)
-vc --verify-peer-cert
verify peer certificate if present
-ic --ignore-peer-cert
don't verify peer certificate
general:
-od --output-directory [d]irectory: string (default: ".")
write message and report files to directory d
--message-files
create DICOM files for request (N-ACTION) and
response (N-EVENT-REPORT) messages (default)
-nmf --no-message-files
do not create any DICOM message files
+tuf --transaction-uid-file [f]ilename: string
write transaction UID to text file f
+crf --create-report-file
create a detailed report on each successful
transaction and write it to a text file
output transfer syntax:
+t= --write-xfer-local
write with explicit VR local byte ordering (default)
+te --write-xfer-little
write with explicit VR little endian transfer syntax
+tb --write-xfer-big
write with explicit VR big endian transfer syntax
+ti --write-xfer-implicit
write with implicit VR little endian transfer syntax
+td --write-xfer-deflated
write with deflated explicit VR little endian transfer syntax
Note that adding directories as arguments to the commandline only makes sense if option –scan-directories is also given. If the files in the provided directories should be selected according to a specific file pattern, the option –scan-pattern has to be used. The file pattern specified here only applies to the files within the directories, and, if any other patterns are specified on the commandline outside the –scan-pattern option (e.g. in order to select further files), these do not apply to the scanned directories.
The stcomscu utility supports the following SOP Class as an SCU:
StorageCommitmentPushModelSOPClass 1.2.840.10008.1.20.1
The default behaviour of stcomscu is to propose two presentation contexts for each supported SOP class (abstract syntax) - one with the preferred transfer syntax and one with all other uncompressed transfer syntaxes. The default preferred transfer syntax is explicit VR with byte ordering corresponding to the local byte ordering of the machine on which stcomscu is running. This behaviour can be changed with the –propose options (see above). Depending on these options, the following transfer syntaxes are supported:
LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*) BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
(*) if compiled with zlib support enabled (see –version output)
In server mode, the stcomscu utility also supports the following SOP Class as an SCP:
VerificationSOPClass 1.2.840.10008.1.1
The default behaviour of the stcomscu utility is to prefer transfer syntaxes having an explicit encoding over the default implicit transfer syntax. If stcomscu is running on big-endian hardware, it will prefer BigEndianExplicit to LittleEndianExplicit transfer syntax (and vice versa). This behaviour can be changed with the –prefer options (see above). Depending on these options, the following transfer syntaxes are supported:
LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*) BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
(*) if compiled with zlib support enabled (see –version output)
In server mode, stcomscu also supports the SCP/SCU role selection since the N-EVENT-REPORT request is by definition sent by the SCP and received by the SCU.
In that context stcomscu only accepts such an incoming Storage Commitment association request, if the proposal uses DICOM Role Selection with role being set to SCP, as required by the standard. Some faulty servers, though, try to connect with Default role, i.e. without any use of Role Selection. In order to support those servers the option –no-role-reject can be used. If enabled, a proposed Default role for the incoming Storage Commitment Connection will be accepted.
The stcomscu utility does not support extended negotiation.
Please note that the optional attributes Storage Media File-Set ID (0088,0130) and Storage Media File-Set UID (0088,0140) are currently not supported.
When compiled on Unix platforms with TCP wrapper support, host-based access control can be enabled with the –access-control command line option. In this case the access control rules defined in the system's host access control tables for stcomscu are enforced (for incoming associations). The default locations of the host access control tables are /etc/hosts.allow and /etc/hosts.deny. Further details are described in hosts_access(5).
The stcomscu utility supports three different operating modes:
In server mode, the stcomscu utility runs forever, i.e. until it is terminated. Therefore, it allows for receiving multiple N-EVENT-REPORT messages. When running in one of the other two modes, stcomscu will terminate after the first N-EVENT-REPORT has been received (or directly after the N-ACTION message has been sent, when using option –no-wait-for-event).
The stcomscu utility allows for creating various output files. By default, all datasets sent with the N-ACTION and received with the N-EVENT-REPORT messages are stored to the specified output directory (option –output-directory).
For the request datasets, the following file naming scheme is used:
The "OK" in the filename indicates that the request has been sent successfully to the storage commitment SCP, and "ERR" indicates an error.
For the response datasets, the following file naming scheme is used:
The "OK" in the filename indicates that the N-EVENT-REPORT message was received with an Event Type ID value of 1 (which means "success"), and "ERR" indicates an Event Type ID value of 2 (which means "failures exist").
The storage of the datasets can be disabled with the –no-message-files option. However, this should be avoided when using a separate stcomscu running in server mode, since the response datasets can then not be compared with the related request datasets.
Option –transaction-uid-file allows for creating a text file with the value of the transaction UID directly after the N-ACTION request has been sent successfully to the SCP. This enables the user of stcomscu to check for the corresponding request dataset and later for the related response dataset, knowing the above described file naming schemes.
Finally, a detailed report on each successful transaction can be created and written to a text file using option –create-report-file. For the report file, the following naming scheme is used:
In addition to the text file, the list of SOP instances in the request and response dataset is also checked and any abnormality is reported to the log output (on various levels).
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).
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 behaviour 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 to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file <datadir>/dumppat.txt).
The stcomscu utility uses the following exit codes when terminating. This enables the user to check for the reason why the application terminated.
EXITCODE_NO_ERROR 0 EXITCODE_COMMANDLINE_SYNTAX_ERROR 1
EXITCODE_CANNOT_READ_INPUT_FILE 20 (*) EXITCODE_NO_INPUT_FILES 21 EXITCODE_INVALID_INPUT_FILE 22 EXITCODE_NO_VALID_INPUT_FILES 23
EXITCODE_CANNOT_WRITE_OUTPUT_FILE 40 (*) EXITCODE_CANNOT_WRITE_REQUEST_FILE 41 EXITCODE_CANNOT_WRITE_RESPONSE_FILE 42 EXITCODE_CANNOT_WRITE_REPORT_FILE 43 EXITCODE_CANNOT_WRITE_TRANSACTION_FILE 44 EXITCODE_INVALID_OUTPUT_DIRECTORY 45
EXITCODE_CANNOT_INITIALIZE_NETWORK 60 EXITCODE_CANNOT_NEGOTIATE_ASSOCIATION 61 EXITCODE_CANNOT_SEND_REQUEST 62 EXITCODE_CANNOT_WAIT_FOR_RESPONSE 63 EXITCODE_CANNOT_START_SCP_AND_LISTEN 64 EXITCODE_CANNOT_CREATE_TRANSPORT_LAYER 71
(*) Actually, these codes are currently not used by stcomscu but serve as a placeholder for the corresponding group of exit codes.
The stcomscu 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 behaviour 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.
dcmdump(1)
Copyright (C) 2010-2024 by OFFIS e.V. and ICSMED AG, Escherweg 2, 26121 Oldenburg, Germany.