SYNOPSIS

tcpsrv [options]

DESCRIPTION

The tcpsrv application implements a Service Class Provider (SCP) for the DICOM Basic Grayscale and/or Basic Color Print Management Service Class, depending on the configuration. It listens on a specific TCP/IP port for incoming association requests from a Print SCU and can receive print jobs according to the SOP classes negotiated. The tcpsrv application creates PostScript code from the incoming print jobs that may be spooled to a PostScript printer.

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

multi-process options

  -s    --single-process
          single process mode

        --fork
          fork child process for each association (default)

processing options

  -c    --config  [f]ilename: string (default: tcpsrv.cfg)
          process using settings from configuration file
          (this option can be specified multiple times)

  +s    --save
          save all DIMSE messages to file

        --save-config  [f]ilename: string
          write active configuration to file f

  -s    --single-process
          single process mode

  -sp   --stored-print  [f]ilename: string
          read and process stored print file

stored print forwarding

(only with --stored-print):

  -f    --forward  [s]erver address and port number: string
          forward stored print to given Print SCP
          (e.g. localhost:104)

  -aec  --call  [a]etitle: string
          set called AE title of peer (default: PS Print Server)

        --noprint
          do not create print-out (no n-action-rq)

        --session-print
          send n-action rq on film session level

basic film session options

(only with --forward):

        --copies  [v]alue: integer (1..100, default: 1)
          set number of copies to v

        --medium-type  [v]alue: string
          set medium type to v

        --destination  [v]alue: string
          set film destination to v

        --label  [v]alue: string
          set film session label to v

        --priority  [v]alue: string
          set print priority to v

        --owner  [v]alue: string
          set film session owner ID to v

network options

  -p    --port  [n]umber: integer
          accept associations on port n

  -mp   --message-port  [n]umber: integer
          accept messages on port n (default: 10000)

  -ai   --auto-increment
          automatically increment message port
          if selected port is not available

  -aet  --aetitle  [a]etitle: string
          set my AE title (default: PS Print Server)

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

DICOM CONFORMANCE

Depending on the configuration, the tcpsrv application supports the following SOP Classes as an SCP:

VerificationSOPClass                       1.2.840.10008.1.1
BasicGrayscalePrintManagementMetaSOPClass  1.2.840.10008.5.1.1.9
BasicColorPrintManagementMetaSOPClass      1.2.840.10008.5.1.1.18
PrintJobSOPClass                           1.2.840.10008.5.1.1.14
BasicAnnotationBoxSOPClass                 1.2.840.10008.5.1.1.15
PresentationLUTSOPClass                    1.2.840.10008.5.1.1.23

The tcpsrv application will accept presentation contexts for all of the abovementioned supported SOP Classes using any of the transfer syntaxes:

LittleEndianImplicitTransferSyntax         1.2.840.10008.1.2
LittleEndianExplicitTransferSyntax         1.2.840.10008.1.2.1
BigEndianExplicitTransferSyntax            1.2.840.10008.1.2.2

The default behaviour of the tcpsrv application is to prefer transfer syntaxes having an explicit encoding over the default implicit transfer syntax. If tcpsrv is running on big-endian hardware it will prefer BigEndianExplicit to LittleEndianExplicit transfer syntax (and vice versa). This behaviour can be changed in the configuration file.

The tcpsrv application does not support extended negotiation.

When used with the –forward command line option, the tcpsrv application supports the following SOP Classes as an SCU:

BasicGrayscalePrintManagementMetaSOPClass  1.2.840.10008.5.1.1.9
BasicColorPrintManagementMetaSOPClass      1.2.840.10008.5.1.1.18
BasicAnnotationBoxSOPClass                 1.2.840.10008.5.1.1.15
PresentationLUTSOPClass                    1.2.840.10008.5.1.1.23

The default behaviour of tcpsrv is to propose one presentation context for each supported SOP class (abstract syntax) with the abovementioned three uncompressed transfer syntaxes. The first proposed transfer syntax is the explicit VR transfer syntax with local byte order, followed by the explicit VR transfer syntax with opposite byte order, followed by the default implicit VR transfer syntax. This behaviour can be changed in the configuration file.

GETTING STARTED

The tcpsrv applications comes with a sample configuration file named tcpsrv.cfg. This is a text file that contains a lot of documentation, but will require a basic understanding of the DICOM print protocol and, for the configuration of printer-specific features such as output to specific printer trays or the selection of paper sizes, some knowledge of the PostScript language.

As a first starting point, run tcpsrv in a directory where it has write permission (needed e.g. to create PostScript files) and where both the configuration file tcpsrv.cfg (from <etcdir>) and the printer.dat file (from <datadir>) are present, by calling

  tcpsrv --debug --config tcpsrv.cfg

Now the print server is running, and will accept incoming DICOM network connections on port 3100. The print server will by default accept any DICOM AE title. Furthermore, the print server will print a very detailed log of the network communication to the console.

Now you need to configure the print client (Print Management SCU) to expect a DICOM printer under the IP address of the machine where tcpsrv is running, and under port 3100. The configuration mechanism to configure a printer will be different for each DICOM device, so this depends entirely on the print client. Many print clients allow you to select from a list of known DICOM printers. OFFIS DCMPRINT will most likely not be in that list. Choose another printer - Kodak/Imation may be a good starting point. Depending on the printer you choose here, some modifications may be neccessary in the tcpsrv.cfg file to make the print process work (i.e., to make tcpsrv emulate the behavior of the real printer expected by the print client).

Now you should try to print on the newly configured printer and see what happens. If everything goes well, you should see a log of the DICOM network protocol on the console, and a PostScript file should have been generated. If there is no PS file, check the log for any message containing a status code that is not 0x0000. This always means that the print server has rejected a message because it contained some unknown/unsupported value. In most cases this can be "fixed" by appropriately adjusting the configuration file.

If you have successfully generated a PostScript file, you then need to change the command line in the configuration file that forwards the PostScript file to the real PostScript printer. Look for the line starting with "Command =" in the config file. A typical command for a Linux system would look like this

  lpr -Pprinter_name -r -s \\f

This will call the "lpr" command with appropriate options to print on the printer "printer_name" and afterwards remove the PostScript file. For a Windows machine, this may be something like

  copy \\f lpt1:

After each change of the configuration file, you need to stop and restart the print server. You can use the tcpshut tool to properly shut down the print server, or just press CTRL-C if the print server is running in a console.

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 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).

ENVIRONMENT

The tcpsrv 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.

FILES

<etcdir>/tcpsrv.cfg - example configuration file
<datadir>/printer.dat - sample printer characteristic curve file