|
DCMTK
Version 3.6.9
OFFIS DICOM Toolkit
|
mppsscu [options] peer port [dcmfile-in]
The mppsscu utility implements a client for the Modality Performed Procedure Step SOP class and, therefore, allows for sending N-CREATE and N-SET status messages to an MPPS SCP. After negotiating the association, the tools issues a single MPPS request on that connection and then closes the association, i.e. sending multiple requests (e.g. N-CREATE and associated N-SET requests) on a single association is not supported at the moment. However, this behaviour is fully conformant with existing DICOM and IHE specifications, i.e. every server must support receiving N-CREATE and N-SET on different associations.
The request message is either read from file, or assembled from attributes given with the –key option. It is also possible to use a request file together with the –key option. In that case, the latter will overwrite values within the request file.
peer hostname of DICOM peer
port tcp/ip port number of peer
dcmfile-in N-CREATE or N-SET dataset to be sent
(optional, "-" 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
request type:
-na --nauto
auto-detect N-CREATE or N-SET (default)
-nc --ncreate
send N-CREATE message
-ns --nset
send N-SET message
compatibility:
--allow-unknown
accept unknown attributes and treat as type 3
--allow-illegal
ignore forbidden N-SET attributes (DANGEROUS)
--ignore-missing
ignore missing N-CREATE attributes (DANGEROUS)
-dc --disable-checks
disable all validity checks (DANGEROUS)
character set:
-cs1 --charset-latin1
accept ISO_IR 100 only (default)
-csa --charset-any
accept any character set
other mpps options:
-sf --status-file [f]ilename: string
MPPS object file (default: status.dcm)
input file format:
+f --read-file
read file format or data set (default)
+fo --read-file-only
read file format only
-f --read-dataset
read data set without file meta information
automatic data correction:
+dc --enable-correction
enable automatic data correction (default)
-dc --disable-correction
disable automatic data correction
override keys:
-k --key [k]ey: gggg,eeee="str", path or dictionary name="str"
override key
IP protocol version:
-i4 --ipv4
use IPv4 only (default)
-i6 --ipv6
use IPv6 only
-i0 --ip-auto
use DNS lookup to determine IP protocol
application entity titles:
-aet --aetitle [a]etitle: string
set my calling AE title (default: MPPSSCU)
-aec --call [a]etitle: string
set called AE title of peer (default: ANY-SCP)
proposed transmission transfer syntaxes:
-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
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
-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
--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
+tla --anonymous-tls
use secure TLS connection without certificate
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
server name indication:
--no-sni
do not use SNI (default)
--request-sni [s]erver name: string
request 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)
-ic --ignore-peer-cert
don't verify peer certificate
-md --message-dir [d]irectory: string (default: no logging)
set directory to log messages
-ad --archive-dir [d]irectory: string (default: no archiving)
set MPPS archive directory
-zip --zip-archive
store archived MPPS objects in deflated transfer syntax
+cl --compression-level [l]evel: integer (default: 6)
0=uncompressed, 1=fastest, 9=best compression
The mppsscu utility supports the following SOP Class as an SCU:
ModalityPerformedProcedureStepSOPClass 1.2.840.10008.3.1.2.3.3
The default behaviour of mppsscu 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 mppsscu 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 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
The mppsscu utility does not support extended negotiation.
The attributes supported by the tool can be found in a separate file, see section FILES in this manual. This means, that the checking mechanism integrated into mppsscu will remove any unsupported attributes from the request message, or in case of mis-used attributes, reject the request before sending it to the SCP. This behaviour can be influenced by different compatibility options (next section).
There are a few commandline options which permit to gracefully ignore errors discovered while checking the request attributes. With option –allow-unknown attributes can be permitted that are not accepted in mppsscu's standard configuration. This is useful if some special attributes should be sent which are normally not common to be sent via MPPS. Also, it is possible to send N-SET attributes that were not created via N-CREATE by setting option –allow-illegal. However, this behaviour is not DICOM-conformant but may be needed for buggy SCP implementations. As a third compatibility option, –ignore-missing permits to ignore missing N-CREATE attributes. Finally, option –disable-checks permits to disable all validity checks that are performed on the request datasets. All these options should only be enabled if required by the server since they may lead to behaviour violating the DICOM standard.
Per default, option –nauto is enabled which permits automatic detection whether the request to be sent is an N-CREATE or an N-SET message. However, it is possible to force mppsscu to send either N-CREATE or N-SET. In that case, the application prints out a warning in case the automatically detected message type differs from the one forced via commandline.
As a general rule, all attributes that are sent in an N-SET request must be created before with an N-CREATE message. Not all attributes/values are permitted in every request message. Also, some so-called final state conditions must be met in case the N-SET sets the MPPS object to its final state ("DISCONTINUED" or "COMPLETED"). For a complete list of all rules, read section F.7 in part 4 of the DICOM standard.
mppsscu checks the validity of MPPS message before actually sending them. In the current version, N-CREATE requests are checked before the association is built and N-SET message are checked before sending them on an existing association. If attributes are found in the request which are not provisioned in the DICOM standard, they are removed from the request before sending. Final state conditions are checked as far as this is possible.
Checking can be disabled by specifying option –disable-checks (should be used with care!).
In DICOM, every MPPS status object is identified by a unique identifier, the so-called Instance UID. This attribute is sent with each N-CREATE and N-SET message to the MPPS server. For N-CREATE, the attribute is optional. If it is left empty, the server provides the Instance UID of the status object in its N-CREATE response message.
mppsscu permits proposing an Instance UID with N-CREATE to the server. If this is desired, the attribute must be provided either as part of the N-CREATE request dataset read from disk or as one of the override keys defined by using the –key option. If no Instance UID is provided, mppsscu will not send it and will receive one from the MPPS server. Therefore, latest after receiving a successful MPPS response message, mppscu knows the Instance UID of the status object currently worked on and stores it internally for later N-SET requests. Thus, in N-SET messages, an Instance UID is not expected to be specified by the user. If one is specified anyway, then it is ignored if it differs from the one internally stored by mppsscu.
mppsscu keeps track of the current MPPS object state during the object's lifetime (i.e. from first N-CREATE to final N-SET message). Therefore, it writes the object to disk and updates it according to each successfully sent request message. By default, this file will reside in the working directory and is called status.dcm. This location can be changed by specifying a different filename using option –status-file. The given filename must reside in a directory which is readable and writable for mppsscu.
By default, mppsscu does no logging besides the standard logging provided using DCMTK's built-in logging facilities (see LOGGING notes). However, for debugging or archiving purposes, it is possible to enable two further logging features.
With option –message-dir a directory can be specified where each message sent or received is stored as a separate file. The filename denotes the time the message was processed, its type (N-CREATE versus N-SET) and its outcome (e.g. Success). The messages are stored in text format to permit fast content lookup. Without specifying a message directory, messages are not stored at all.
With option –archive-dir a directory can be specified where finalized (i.e. COMPLETED or DISCONTINUED) status objects are stored to. These files are stored in DICOM format and optionally can be zipped by utilizing DICOM's Deflated Transfer Syntax. If this is desired, option –zip-archive must be provided. Additionally, the ZIP compression level can be set with option –compression-level.
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.
The mppsscu 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_INVALID_STATUS_FILE 20 EXITCODE_INVALID_ARCHIVE_DIRECTORY 21 EXITCODE_INVALID_MESSAGE_DIRECTORY 22 EXITCODE_INVALID_DATABASE 23 EXITCODE_INVALID_REQUEST_DATA 24 EXITCODE_INVALID_REQUEST_DATASET 25 EXITCODE_COULD_NOT_SEND_REQUEST 26 EXITCODE_FINAL_STATE_CONDITIONS_NOT_MET 27
EXITCODE_SCP_GENERAL_ERROR 30 EXITCODE_SCP_CLASS_INSTANCE_CONFLICT 31 EXITCODE_SCP_DUPLICATE_INVOCATION 32 EXITCODE_SCP_DUPLICATE_SOP_INSTANCE 33 EXITCODE_SCP_MISSING_ATTRIBUTE 34 EXITCODE_SCP_MISSING_ATTRIBUTE_VALUE 35 EXITCODE_SCP_MISTYPED_ARGUMENT 36 EXITCODE_SCP_NO_SUCH_ATTRIBUTE 37 EXITCODE_SCP_NO_SUCH_SOP_CLASS 38 EXITCODE_SCP_NO_SUCH_SOP_INSTANCE 39 EXITCODE_SCP_PROCESSING_FAILURE 40 EXITCODE_SCP_RESOURCE_LIMITATION 41 EXITCODE_SCP_UNRECOGNIZED_OPERATION 42
EXITCODE_CANNOT_INITIALIZE_NETWORK 60 EXITCODE_CANNOT_NEGOTIATE_ASSOCIATION 61
The mppsscu 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.
<docdir>/mppstags.txt - MPPS attributes supported by mppsscu
Copyright (C) 2007-2024 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.