14. Managing Print Services

Introduction

This chapter describes how to manage the TCPware print services, which include an Internet Printing Protocol (IPP) client, the Line Printer Services (LPS) client and server, and the Terminal Server Print Services (TSSYM).

Line Printer Services Client

You can configure an OpenVMS host with both an LPS client and a server. The LPS client lets users send print jobs to printers attached to remote hosts. It supports the UNIX-like LPR commands and the OpenVMS PRINT command. You can configure the LPS client to use:

UNIX-style LPR commands (lpr, lpq, and lprm)

During configuration, enter information about the default remote host and printer when you use an LPR command.

Command used with one or more OpenVMS print queues on the client. TCPware creates and starts these queues during STARTNET. These queues can use:

· OpenVMS /FORM features on the local or remote print queues.

· The /PARAMETERS qualifier to achieve minimal formatting on remote print queues.

You can set up the print queues during TCPware configuration, or base the settings on entries in a local PRINTCAP (printer capability) database. The PRINT command supports two different print symbionts:

TCPWARE_VMSLPRSMB	Provides local print queue formatting.
TCPWARE_LPRSMB	Provides remote print queue formatting.

LPS Client Commands

The LPS client supports the following commands:

Command	Description	Command	Description
LPQ	Displays the remote print job status	LPRM	Removes a job from a remote print queue.
LPR	Sends a job to the default remote printer designated during configuration	PRINT	Places a job in the designated print queue; then sends the job to the printer associated with that queue.

The below figure shows how to use an LPR command with an LPS configuration.

OpenVMS Print Queues

The LPS client uses LPS print symbionts to control where document formatting and device control occurs: locally or remotely. The two symbionts (shown in the below table) provide different kinds of print format support, configurable during the CNFNET procedure.

Symbiont...	Supports the command...	And forms definition...
TCPWARE_VMSLPRSMB (provides local print formatting control)	PRINT/FORM	All DEFINE/FORM qualifiers
TCPWARE_LPRSMB (provides remote print formatting control)	PRINT/PARAMETERS and some PRINT/FORM	DEFINE/FORM /SETUP /STOCK /DESCRIPTION only

See the TCPware User's Guide, Chapter 5, Network Printing, and your OpenVMS documentation for information about the PRINT command and its qualifiers.

You can also configure the OpenVMS print queues to support additional qualifiers available with the OpenVMS INITIALIZE /QUEUE command. Use the /LIBRARY=LN03DEVCTL qualifier to enable the device control library. The device control library contains device control modules and resides in SYS$LIBRARY.

Print Forms

You must configure the print forms specifically for LPS to control the local or remote printer's setup for each print job. Use the OpenVMS DEFINE /FORM command format, with the qualifiers listed in the below table, as supported for each of the print symbionts:

$ DEFINE/FORM form-name form-number qualifier...

Qualifiers

/LENGTH=n
/MARGIN=(BOTTOM=n,LEFT=n,RIGHT=n,TOP=n)
/PAGE_SETUP=module
/SHEET_FEED,
/TRUNCATE,
/WIDTH=n,
/WRAP

Sets various page setup print parameters. (Use with TCPWARE_VMSLPRSMB only.)

/SETUP=module

Device control module or modules (separated by commas) that contain the print control sequences for the remote printer. (Use with TCPWARE_VMSLPRSMB or TCPWARE_LPRSMB.)

/STOCK=string

Type of paper stock to associate with the form (if not the same as the form-name); string can be up to 31 characters. (Use with TCPWARE_VMSLPRSMB or TCPWARE_LPRSMB.)

/DESCRIPTION=string

Operator information about the form (the default is the form-name) that appears when you issue the SHOW QUEUE/FORM command; use quotes to preserve case or if using spaces; string can be up to 255 characters. (Use with TCPWARE_VMSLPRSMB or TCPWARE_LPRSMB.)

PRINTCAP Database

During TCPware configuration, you can select whether to use the PRINTCAP (printer capability) database, if it exists, to start your local OpenVMS queues for the PRINT command. (Make any subsequent queue definitions during the usual LPS configuration.) The PRINTCAP database is the equivalent of the UNIX /etc/printcap file and resides locally in the TCPWARE:PRINTCAP file. If you do not have or opt not to use the PRINTCAP database to define local print queues, you must define these queues one by one during configuration.

The PRINTCAP database requires a special syntax. Each entry in the database describes one printer. According to the UNIX convention, each entry in the file is one or more lines consisting of fields separated by colon (:) characters. The first entry for each printer gives the name or names under which the printer is known, separated by vertical bar (|) characters. Entries can continue onto multiple lines by adding a backslash (\) after the last character of a line. You can include empty fields for readability.

You can use a number of Boolean, numeric, and string type options (or capabilities) with each database entry, although TCPware only supports three string type capabilities:

lp	Local printer's device name
rm	Remote machine name
rp	Remote printer name

An equal sign (=) separates the capability code from its value.

The below example shows a sample entry in the PRINTCAP. file.

#
# LOCAL PRINTERS
#
test_printer:\
:lp=test_printer:\
:rm=test1_printer:\
:rp=eng2_printer:

In this example, the name of the local printer (lp) is test_printer. The remote machine (rm) is test1_printer, and the remote printer (rp) is eng2_printer. Lines starting with the pound sign (#) and blank lines are ignored.

To print to TEST_PRINTER, users specify:

$ PRINT/QUEUE=TEST_PRINTER filespec

The output appears on node EXAMPLE's ENG2_PRINTER printer.

Note: The PRINTCAP database is not dynamic. To institute any changes you make to it, you must reconfigure the OpenVMS print queue using the configuration procedure.

LPS System Logicals

LPS uses several system logicals. TCPware defines only those LPS logicals required for features that you enable during CNFNET in the TCPWARE_SPECIFIC:TCPWARE_CONFIGURE.COM file. STARTNET uses the information in this file to create the logicals when you start the network. For example, TCPware defines logicals related to the LPD server only if you enable the server during CNFNET. Change features that you enable by rerunning CNFNET.

After you start the network, use the SHOW LOGICAL command in OpenVMS to examine the logical definitions. To set up a generic LPS client queue to print to a machine, set up the TCPWARE_LPR_qname_PRINTER logical for both the generic and server queues. The server queue automatically sets up the logical after you define it.

Client Logicals

The below table explains the purpose of each LPS client logical.

LPS logical	Description
TCPWARE_LPR_QUEUES	Lists the names of all TCPware print symbiont queues. Defined only if you defined one or more print queue.
TCPWARE_LPR_qname_PRINTER	Defines the absolute printer for the PRINT command. You cannot override this logical when submitting a print job. Use to restrict printing to one printer per queue.
TCPWARE_LPR_qname_PRINTER_DEFAULT	Defines a default remote printer for the PRINT command. Used if neither TCPWARE_LPR_qname_PRINTER nor the PRINT command specify a remote printer. You must define either TCPWARE_LPR_qname_PRINTER or TCPWARE_LPR_qname_PRINTER_ DEFAULT for each queue for the PRINT command.
TCPWARE_LPR_SPOOL	Points to the work directory for the PRINT command. This directory holds temporary files.
TCPWARE_LPR_PRINTER	Defines the default remote printer for the LPR, LPRM, and LPQ commands. You can define your own TCPWARE_LPR_PRINTER logical in a LOGIN.COM file.

VMSLPRSMB Tuning Logicals

The TCPWARE_VMSLPRSMB print symbiont provides the retry interval and timeout tuning logicals (all are executive mode system logicals) listed in the below table.

VMSLPRSMB logical...	Description
TCPWARE_VMSLPRSMB_*_RETRY_INTERVAL	Defines the interval at which the symbiont retries to make a connection to a printer after an attempt fails. The connection can fail either by the remote printer rejecting it due to a busy state, or by the network timing out. The default value for a retry interval is 2 minutes (:2 in delta time). Note that a connection failure can take 1.5 minutes to time out, which is not included in this interval value.
TCPWARE_VMSLPRSMB_qname_RETRY_INTERVAL	Same as TCPWARE_VMSLPRSMB__RETRY_INTERVAL, but for a specific queue only, and overrides TCPWARE_VMSLPRSMB__RETRY_INTERVAL.
TCPWARE_VMSLPRSMB_*_TIMEOUT	Defines the time it takes for a print job to abort if the connection to the printer is never established. The default timeout is infinite (it never times out).
TCPWARE_VMSLPRSMB_qname_TIMEOUT	Same as TCPWARE_VMSLPRSMB__TIMEOUT, but for a specific queue only, and overrides TCPWARE_VMSLPRSMB__TIMEOUT.
TCPWARE_VMSLPRSMB_qname_PRECONN	Makes the connection to the printer before processing the file. Normal behavior is to make the connection to the printer after processing the file.

LPRSMB Tuning Logicals

The TCPWARE_LPRSMB print symbiont provides similar retry interval and timeout tuning logicals as those for TCPWARE_VMSLPRSMB (see the descriptions in the previous section). The TCPWARE_LPRSMB logicals are:

· TCPWARE_LPRSMB_*_RETRY_INTERVAL

· TCPWARE_LPRSMB_qname_RETRY_INTERVAL

· TCPWARE_LPRSMB_*_TIMEOUT

· TCPWARE_LPRSMB_qname_TIMEOUT

· TCPWARE_LPRSM_qname_PRECONN

Troubleshooting LPS

You may have a SETUP module in your LPS print queues (TCPWARE_VMSLPRSMB or TCPWARE_TSSYM) that causes the OpenVMS print symbiont to insert unexpected form feeds (<FF>).

You can remove these form feeds by adding an undocumented escape sequence to the SETUP module, as follows:

1. Start the SETUP module with the special escape sequence:

2. Enclose the setup text with:

<ESC>Pstring<ESC>

For example, if you want to send the setup text setup to the printer, the SETUP module could look like this (or you could have two setup modules, one with the <ESC>]VMS;2<ESC>F0> text and the other with the <ESC>Psetup<ESC>F0> text):

<ESC>]VMS;2<ESC>Psetup<ESC>F0>

LPD Server

The LPD server on the local host accepts print requests from remote users. It then places the remote files in local OpenVMS print queues. You must define and initialize these OpenVMS print queues before you configure the TCPware LPD server.

Sending files from remote UNIX systems to a local OpenVMS printer requires the UNIX system to have an entry in an /etc/printcap file. Some UNIX systems do not have this file and rely on another method. (See your UNIX documentation for more information.) Here is a sample entry in an /etc/printcap file:

rpl | remote printer:
:lp=:
:sd=/usr/spool/lpd:
:rm=daisy:
:rp=ln03r$print

The following UNIX command puts myfile in the ln03r$print queue on daisy:

> lpr -Prpl myfile

Server Supported Options

The LPD server supports the options listed in the below table. (It does not support other options and ignores print requests you issue with such options, without issuing an error message.)

For command...	This option...	Does...
LPQ	-l	Displays the status of each job on more than one line
LPR	-C	Prints the job classification on the burst page (like the PRINT/NOTE command in OpenVMS)
	-f	Interprets the first character of each line as a standard FORTRAN carriage control character
	-h	Prevents the burst page from printing (like the PRINT/NOFLAG command in OpenVMS)
	-J	Prints the job name on the burst page (like the PRINT/NAME command in OpenVMS)
	-l	Prints control characters and suppresses page breaks (like the PRINT/PASSALL/NOFEED/NOHEADER command in OpenVMS)
	-m	Notifies the OpenVMS user when printing has completed for the job (like the PRINT/NOTIFY command in OpenVMS)
	-o	Indicates the file contains PostScript input
	-p	Prints the file with page headers (like the PRINT/HEADER command in OpenVMS)
	-v	Prints the Sun raster format file as a binary file with no formatting
	-x	Specifies not to require filtering before printing (like the PRINT/PASSALL/NOFEED/HEADER command in OpenVMS)
	-#	Prints multiple copies (like the PRINT/COPIES command in OpenVMS)
LPRM	-	Removes all jobs that only you own

Data and Control Files

The LPD server accepts only data files and control files from clients. Data files contain copies of the data you want printed or executed. Control files store the commands that specify how you want the data printed.

LPD receives the data and control files in STREAM-LF format unless you use lpr -l to send the print job to the printer. It stores the files in the spooling directory until the job ends. The TCPWARE_LPD_SPOOL logical points to the spooling directory.

LPD Access File

The LPD server requires an LPD access file. It checks this file before accepting any requests from remote clients. This file:

· Determines which remote hosts can access the local LPD server.

· Maps remote users to OpenVMS usernames.

You can create the LPD access file during or after TCPware configuration. Use any text editor to enter data in the file. If you create the file after configuring TCPware, give it the name TCPWARE_COMMON:[TCPWARE]LPD_USERS.DAT. Use the following format:

vms-username remote-host remote-user

vms-username	Username defined in the OpenVMS User Authorization File. Upper- or lowercase characters are acceptable. You can enter an asterisk () as a wildcard to designate the incoming user as the vms-username*. Use a hyphen (-) to specifically disallow access to printing services.
remote-host	Host on which the remote user resides. Enter the full or partial domain name, or the IP address. (Using the IP address improves performance.) Upper or lowercase characters are acceptable. You can enter an asterisk (*) as a wildcard to designate all remote hosts. Do not partially wildcard the host name.
remote-user	Username on the remote host. Enter the username in the same case (upper- or lowercase) as the remote host uses to define it. You can enter an asterisk () as a wildcard. The wildcard maps all remote users to this vms-username* account entry.

CAUTION! Use wildcards cautiously. They can cause severe security problems.

Use the exclamation point (!) or pound sign (#) as the first character of a line to indicate a comment line.

Include at least one space or tab between each item.

When the remote user tries to access the LPD server, LPD looks at LPD_USERS.DAT for valid username mapping. If a valid username mapping is not found, LPD checks the system logical TCPWARE_LPD_DEFAULT_USER to determine the OpenVMS username. If this system logical is not found, the LPD server discards and never prints the file. You define the OpenVMS username for this logical during network configuration.

When LPD receives a job from a remote system, the format of the print job's NOTE is:

remote-ID: user@host - note

· user - Remote username

· host - Remote hostname

· note - Note as specified on the LPR command, or the default (often the hostname)

Here is a sample LPD access file:

!vms-username    remote-host     remote-user
!-------------------------------------------
smith            daisy           smith
jones            daisy           jones
jones            rose            jones
harrington       192.168.95.1    harrington
harrington       tulip           harrington
wallace          *               wallace
harrington       iris            *

It is recommended you place wildcard entries later in the file, as the first acceptable mapping will be used.

The following example illustrates an access file which provides a specific mapping for remote user gertrude. It allows access to all users with matching names on both systems, and provides a default mapping for all other users on node daisy.

!vms-username   remote-host   remote-user
!----------------------------------------
-               daisy         thorn
rose            daisy         gertrude
*               daisy         *
daisy_default   daisy         *

In the first line, user thorn on system daisy is denied access to printing services.

In the second line, the remote user gertrude on daisy is mapped to the OpenVMS username rose.

In the third line, the LPD server is instructed to map, as is, usernames having corresponding OpenVMS accounts.

In the fourth line, if the remote user on daisy does not have a corresponding OpenVMS account on the local system, it is mapped to account DAISY_DEFAULT.

Batch Queues

The LPD server can place jobs in batch queues for execution. You enable this feature during network configuration. To send a job to a batch queue, specify the batch queue name instead of the print queue name when you enter the PRINT or LPR command.

The LPD server does not support qualifiers or options that are analogous to the following OpenVMS SUBMIT command qualifiers: /CLI, /CPUTIME, /LOG_FILE, /PRINTER, /WSDEFAULT, /WSSEXTENT, and /WSQUOTA.

LPD Logicals

The below table explains the purpose of each LPD server logical.

LPD logical...	Description
TCPWARE_LPD_DEFAULT_USER	Defines a default OpenVMS username for remote users connecting to the local LPD server. Used only when you define a remote host in the LPD access file and the remote username is not mapped to a specific OpenVMS username.
TCPWARE_LPD_OPTIONS	Determines if the server handles batch queues.
TCPWARE_LPD_qname_FORM*	Defines the form used for print jobs. This logical is similar to TCPWARE_LPD_qname_PARAMETER. Use the TCPWARE_LPD_*_FORM logical to define the form for all queues. Note that a specific queue setting overrides the global setting for that queue.
TCPWARE_LPD_qname_OPTION	Specifies additional PRINT command qualifiers to pass to the specified print queue: /BURST, /FEED, /FLAG, /FORM, /HEADER, /LOWERCASE, /PASSALL, /PRIORITY, /RESTART, /SPACE, /TRAILER Use the TCPWARE_LPD_*_OPTION logical to define the option for all queues. Note that a specific queue setting overrides the global setting for that queue.
TCPWARE_LPD_qname_PARAMETER*	Defines the specified parameters when the remote user submits a print request to the OpenVMS print system (qname is the queue name). The first equivalence string for the logical (if defined) is the first parameter; the second is the second parameter; and so on, for up to eight parameters. See Using the LPD Logicals to Support a Printer. Use the TCPWARE_LPD_*_PARAMETER logical to define the parameter for all queues. Note that a specific queue setting overrides the global setting for that queue.
TCPWARE_LPD_qname_QUEUE*	Defines the print queues for an alias queue name (qname). Typically supports clients that may not allow standard OpenVMS queue names as the remote printer (such as IBM's AIX, which restricts remote printer names to seven characters). See Using the LPD Logicals to Support a Printer.
TCPWARE_LPD_SPOOL	Points to the work directory for the LPD server. This directory holds temporary files.
^* STARTNET does not define the TCPWARE_LPD_qname_QUEUE logical. Define this system logical in the system startup file.

Be aware of security when you define the TCPWARE_LPD_DEFAULT_USER logical. Remote users can submit batch jobs to your local OpenVMS host. To prevent unauthorized users from submitting batch jobs, do not define a username belonging to a privileged account (such as the SYSTEM username). Use AUTHORIZE instead to create a special user account with restricted access.

The below example shows how to use the TCPWARE_LPD_qname_PARAMETER and TCPWARE_LPD_qname_QUEUE logicals to support an LN03R PostScript printer. These logical definitions define two alias queues (LP0 and PS0) for the LN03R printer queue, $LN03R1, and define the parameters for these queues. The LP0 queue prints jobs submitted as ASCII files. The PS0 queue prints jobs submitted as PostScript files.

$ DEFINE/SYSTEM/EXEC TCPWARE_LPD_LP0_QUEUE $LN03R1
$ DEFINE/SYSTEM/EXEC TCPWARE_LPD_PS0_QUEUE $LN03R1
$ DEFINE/SYSTEM/EXEC TCPWARE_LPD_LP0_PARAMETER "DATA=ANSI"
$ DEFINE/SYSTEM/EXEC TCPWARE_LPD_PS0_PARAMETER "DATA=POST"

Troubleshooting LPD

Facilities to aid in resolving problems you may encounter with LPD include:

· OPCOM error messages (OPCOM)

· LPD log files

LPD sends messages to OPCOM under some error conditions.

Access error messages help by entering HELP TCPWARE MESSAGES.

LPD also writes the OPCOM messages and several other informational messages to the following LPD log file, shared by all LPD servers: TCPWARE:LPDSERVER.LOG. It is often useful to review the messages in this log file.

You can also obtain more details about LPD processing by using the Network Control Utility (NETCU) to specify an output file for SYS$OUTPUT for the LPD server. Normally, LPD's output goes to NLA0: (the null device) and is, therefore, lost. By redirecting the output to a log file, you can examine a detailed trace of LPD's execution:

$ NETCU MODIFY SERVICE printer TCP /OUTPUT=file

Terminal Server Print Services

Terminal Server Print Services (TSSYM) provide an efficient way for OpenVMS users to send print requests to printers attached to TCP/IP-based terminal servers. Users on the host can easily access printers attached to a terminal server as if they were any other OpenVMS printer.

You can configure the print queues to the remote printer using standard OpenVMS print operations. Users can initiate print jobs with the usual OpenVMS commands. The below diagram shows using the PRINT command with a TSSYM configuration.

A special print symbiont sends the print request over the network instead of writing it to a local printer. The symbiont performs all the necessary device-related functions on the remote terminal server. These include allocating the device, assigning a channel to it, obtaining its device characteristics, and determining its device class.

For further information on setting up print queues and initiating print commands on the OpenVMS host, see your OpenVMS documentation.

The symbiont processes the data so that the terminal server can pass the job to the printer. Unless you keep the connection open, the symbiont also closes the TCP connection to the terminal server after every print job and opens a connection with a new terminal server.

TSSYM Print Queue

Initializing the terminal server print queue requires OPER privileges. Starting the queue requires OPER privileges or execute (E) access to the queue.

You can set up the terminal server print queue as you would any other OpenVMS printer queue, using standard OpenVMS queue commands. If you want to modify the terminal server printer queue, specify any standard printer queue commands and options the INITIALIZE/QUEUE, START/QUEUE, and SET QUEUE commands support. When you set up the queues, the terminal server queues must specify:

/PROCESSOR=TCPWARE_TSSYM	TCPWARE_TSSYM identifies the special print symbiont.
/ON=string	string specifies the terminal server information using the host, port, options, and qname parameters.
/AUTOSTART_ON	implements an autostart queue (if enabled) on one or more nodes if used together with the TCPWARE_TSSYM_qname logical.

Initialize the print queue and then start it. Add the command lines shown below to your printer startup commands or in your system startup file (SYSTARTUP_V5.COM or SYSTARTUP_VMS.COM).

$ INIT/QUEUE/PROCESSOR=TCPWARE_TSSYM/ON="host,port[,options]" qname
$ START/QUEUE qname

host	With /ON, Internet address or host name (if in the HOSTS. file or resolvable using DNS) of the terminal server
port	With /ON, port number on which the terminal server accepts incoming connections for the printer port (A below table shows some common port numbers)
options	Specify the /ON options listed in the below table singly or in the combinations given (each option separated by a comma).

/ON options:

Option	Description
EXPNTAB	Expands <TAB> characters to be the equivalent number of <SPACE> characters in print files. TSSYM normally ignores <TAB> characters.
KEEP	Keeps the connection open between jobs and closes it only on errors or when exiting. Prevents several systems from sharing the printer. This eliminates opening and closing the TCP connection with every print job, thereby not tying up network resources. Do not combine with NOFF.
LOWER	Marks the queue as supporting lowercase printing.
NOCRNUL	The TELNET standard (RFC 856) requires that a carriage return character (<CR>) not followed by a line feed character (<LF>) be converted to <CR><NULL>. TCPware supports this standard. Use the NOCRNUL option to disable the character sequence conversion for printers that do not support the TELNET standard.
NOFF	Does not send a form feed to the printer for each new connection. However, NOFF still sends both a form feed and a carriage return for the first file printed after you initialize the queue. Do not combine with KEEP.
NOINIFF	Suppresses an initial form feed before the very first job after queue startup. Uses the sequence <CR><CR> instead of <CR><FF>.
NOOPCOM	Suppresses OPCOM messages the terminal server print symbiont may produce.
RAW	Makes the connection a raw, binary connection, not a TELNET connection. TCPWARE_TSSYM does not double IAC characters (ASCII 255) in the data stream. Also, <CR> is not converted to <CR><NULL>.
TRIMFF qname	A print job normally ends with a carriage return (<CR>) and form feed (<FF>). Using the TRIMFF option, you can prevent the symbiont from adding these to the end of the print job. TRIMFF also replaces <CR> and <FF> with <CR><CR> at the beginning of the print job. Name of the print queue.

Common printer port numbers:

Printer or server...	Is given port number...
Emulex NetQue Print Server	2501
Emulex NetQue Serial Card	2502
HP Jet Direct Card	9100
Lantronics	20nn, where nn is the port number
Racal	100n, where n is the port number
Xylogic	70nn, where nn is the physical port on the terminal server
Xyplex 720 Terminal Server	2000 + (100 nn), where nn is port number; for example, port 14 would be 3400 for the TCP/IP listener port

Here is a typical command sequence to set up a standard ANSI printer:

$ INIT/QUEUE/PROCESSOR=TCPWARE_TSSYM/ON="192.168.25.50,2005" PR1
$ START/QUEUE PR1

If you use more than 31 characters for /ON qualifier parameters (including the quotes), the message %QUEMAN-F-INVQUAVAL, value '"host,port,options"' invalid for /ON qualifier appears. If you need to use more than 31 characters, define the TCPWARE_TSSYM_qname logical, described in Autostart Queue.

The standard OpenVMS qualifiers for the INITIALIZE and START commands are available. You can also set up a generic print queue where you can move print jobs to compatible execution queues, so that you can print to the first available printer on a SYS$PRINT request.

You need to start TCPware to print to the printer connected to the terminal server. If you do not start TCPware, the printer is down, or the system does not recognize the domain name, the print symbiont waits until you resolve the problem. This puts the print queue into a "stalled" state. In this case, you can either correct the problem while the queue is up, or stop and restart the queue using STOP/QUEUE/RESET and START/QUEUE.

Spool Device

You can set up a spool device so that you can use TSSYM to associate the device with a print queue and then perform operations such as copying a file to the device. HP DATATRIEVE is an application that could use this functionality:

1. Set up a print queue, such as with the typical command sequence shown earlier.

2. Use SYSGEN to set up the spool device. Select a new device (such as QPA0:) and use it in the CONNECT command with the /DRIVER=FTDRIVER and /NOADAPTER qualifiers. Then specify the queue name from step 1 in the SET DEVICE /SPOOLED command, as in the following example:

$ RUN SYS$SYSTEM:SYSGEN
SYSGEN>CONNECT QPA0: /DRIVER=FTDRIVER /NOADAPTER
SYSGEN>EXIT
$ SET DEVICE QPA0: /SPOOLED=PR1

3. Copy a file to the device, or define the system output to be the device and run a program whose output goes to it, such as the following:

$ COPY FOOBAR QPA0:
$ DEFINE SYS$OUTPUT QPA0:
$ RUN PROGRAM1 !output from PROGRAM1 goes to the device

Autostart Queue

You can set up an autostart queue on a node that automatically starts up again after it stops. You can also set up such a queue to autostart on other failover nodes.

Starting an autostart queue requires the /AUTOSTART_ON qualifier for the INITIALIZE/QUEUE command. Since you cannot use /AUTOSTART_ON together with the /ON qualifier to initialize a terminal server print queue, you need to define the TCPWARE_TSSYM_qname logical for this purpose. This logical defines the parameters normally set with the /ON qualifier.

The format of the logical definition is:

$ DEFINE/SYSTEM TCPWARE_TSSYM_qname "host,port[,option...]"

The format of the /AUTOSTART_ON qualifier (use the parentheses when specifying multiple nodes):

/AUTOSTART_ON=(node::[,node::,...])

The below example shows a typical command sequence to define the TCPWARE_TSSYM_qname logical, initialize and start up an autostart queue (QUEUE1) on two nodes, and enable autostart on these nodes. You can also add the commands to your startup command procedure. Note that there are two nodes: NODE2 can be a failover node in case NODE1 goes down.

$ DEFINE/SYSTEM TCPWARE_TSSYM_QUEUE1 "192.168.25.50,2005,KEEP"
$ INIT/QUEUE /START /PROCESSOR=TCPWARE_TSSYM -
_$ /AUTOSTART_ON=(NODE1::,NODE2::) QUEUE1
$ ENABLE AUTOSTART /QUEUES /ON=NODE1
$ ENABLE AUTOSTART /QUEUES /ON=NODE2

Sample TSSYM Configuration

A sample configuration includes a host connected to a DECserver 300 terminal server, as shown in the below diagram.

The following example shows how to configure the OpenVMS host to process print requests to the PR1 printer on the DECserver 300. The procedure then shows how to set up the queue and execute a print request.

For details on configuring a TELNET port and the recommended settings for access through a TELNET listener for a specific printer, see HP's DECserver 300 Management guide.

The setup values in the next example are for the DECserver 300 terminal server only. For setup values specific to your terminal server, see your server documentation.

The steps in the sample configuration and startup are as follows:

1. Initialize the DECserver 300 terminal server.

2. At the Local> prompt, enable privileged status to access all terminal server commands.

3. Configure the terminal server port for the printer. For example, if printer PR1 is connected to port 5:

Local>define port 5 access remote autobaud disabled
Local>define port 5 break disabled
Local>define port 5 character size 8 dedicated none
Local>define port 5 dsrlogout disabled
Local>define port 5 flow control xon inactivity logout enabled
Local>define port 5 parity none
Local>define port 5 password disabled preferred none
Local>define port 5 signal check enabled
Local>define port 5 signal control disabled speed 9600
Local>define port 5 type hardcopy
Local>logout port 5

4. Configure the TELNET server characteristics of the terminal server port for the printer. For example, to set up TELNET server carriage control handling:

Local>define port 5 telnet server newline to host <CRLF>
Local>set port 5 telnet server newline to host <CRLF>

5. Configure the TELNET listener port to associate the listener with the printer port. The valid TCP listener port numbers for the DECserver 300 are 2001 through 2016. For example:

Local>define telnet listener 2005 ports 5 enabled
Local>set telnet listener 2005 ports 5 enabled
Local>define telnet listener 2005 identification "PR1"
Local>set telnet listener 2005 identification "PR1"
Local>define telnet listener 2005 connection enabled
Local>set telnet listener 2005 connection enabled

6. On the OpenVMS host, initialize and start up the print queue, as follows:

$ INIT/QUEUE/PROCESS=TCPWARE_TSSYM/ON="192.168.95.100,2005" PR1
$ START/QUEUE PR1

OpenVMS users can now issue print commands to the printer, such as:

$ PRINT/HEADER/QUEUE=PR1/COPIES=10 TEST1, TEST2, TEST3

TSSYM Tuning Logicals

TSSYM provides the retry interval and timeout tuning logicals (all are executive mode system logicals) listed in the below table.

TSSYM logical...	Description
TCPWARE_TSSYM_*_RETRY_INTERVAL	Defines the interval at which the symbiont retries to make a connection to a printer after an attempt fails. The format must be D h:mm:ss. The default is 0 0:00:15 (15 seconds delta time).
TCPWARE_TSSYM_qname_RETRY_INTERVAL	Same as TCPWARE_TSSYM__RETRY_INTERVAL but for a specific queue only, and overrides TCPWARE_TSSYM__RETRY_INTERVAL
TCPWARE_TSSYM_*_TIMEOUT	Defines the time it takes for a print job to abort if the connection to the printer is never established. The default timeout is infinite (it never times out).
TCPWARE_TSSYM_qname_TIMEOUT	Same as TCPWARE_TSSYM__TIMEOUT, but for a specific queue only, and overrides TCPWARE_TSSYM__TIMEOUT.

Troubleshooting TSSYM

OPCOM can send a number of status messages that can help you troubleshoot TSSYM.

Access error messages help by entering HELP TCPWARE MESSAGES.

Internet Printing Protocol (IPP)

The IPP print symbiont is an OpenVMS print symbiont working with the OpenVMS printing subsystem to implement an IPP client. It allows printing over a network to printers and servers that support the IPP v1.0 network printing protocol. The user interface is similar to other print symbionts in that it uses PRINT commands or system library calls to submit jobs to print queues. The IPP protocol has specific qualifier values and queue settings that must be present to allow the symbiont to function. This section describes both the configuration of IPP print queues and the use of the PRINT command. For information on submitting jobs to print queues using system library calls, see the appropriate OpenVMS documentation.

IPP Protocol Background

The Internet Printing Protocol solves a number of problems in existing network printing protocols; the most common is the LPD protocol, originally implemented on UNIX operating systems.

From RFC 2568:

"The Internet Printing Protocol (IPP) is an application level protocol that can be used for distributed printing on the Internet. This protocol defines interactions between a client and a server. The protocol allows a client to inquire about capabilities of a printer, to submit print jobs and to inquire about and cancel print jobs. The server for these requests is the Printer; the Printer is an abstraction of a generic document output device and/or a print service provider. Thus, the Printer could be a real printing device, such as a computer printer or fax output device, or it could be a service that interfaced with output devices."

IPP has a better error reporting capability than LPD or TELNET. It supports multi-sided printing, landscape/portrait layouts, and multiple pages per physical sheet ("number-up") printing. Because not all printer models that support IPP will support all capabilities, the IPP protocol includes a way for the symbiont to query the printer as to its capabilities before a job is sent. If the printer cannot handle a given request, the job is aborted with an error status. The error status appears in the system accounting log.

IPP uses the HTTP 1.1 protocol as its transport layer; however, it has its own reserved port number, port 631. You can use the IPP Symbiont to print to other port numbers, including the standard HTTP port (80), but you need to specify the port number as part of the printer URL if the port number is not the default IPP port number. If you are printing through a firewall this could be a factor to consider. For a full description of the IPP protocol, see the relevant RFCs listed below.

Relevant RFCs

The RFCs related to IPP v1.0 are:

Design Goals for an Internet Printing Protocol	RFC 2567
Rationale for the Structure and Model and Protocol for the Internet Printing Protocol	RFC 2568
Internet Printing Protocol/1.0: Model and Semantics	RFC 2566
Internet Printing Protocol/1.0: Encoding and Transport	RFC 2565
Internet Printing Protocol/1.0: Implementer's Guide	RFC 2639
Mapping between LPD and IPP Protocols	RFC 2569

Additional RFCs are referenced by these, such as the ones describing HTTP v1.1, MIME Media Types, etc. The specific RFCs are called out in the above documents.

Limitations of this Implementation

The IPP symbiont implements a subset of the IPP v1.0 protocol consisting of all required portions and several selected optional features. Note that not all features are available on all printers; most printers implement a subset of the available protocol capabilities.

Not all printers claiming to support IPP implement IPP correctly. Some use supersets of HTTP 1.0, rather than the required HTTP 1.1. Some do unusual things with TCP/IP connections, such as having extremely short timeouts. The symbiont has been adapted to support as many of these inconsistencies as possible (see the EXPECT_LINK_CLOSURES option for an example). The symbiont may or may not behave as expected with such printers depending on your particular network characteristics and exactly what the printer manufacturer has done differently from what is specified in the RFCs. The symbiont should work with any fully compliant IPP v1.0 printer or server.

Configuration

The IPP symbiont has a flexible configuration. You can supply the information in the queue setup itself, as the /DESCRIPTION string which is supported by OpenVMS as part of the INITIALIZE/QUEUE command. You can supply the information in a "configuration" system logical name that the symbiont checks. You can use both, putting some information on one place, and some in the other. You can also put configuration information in one or more files and reference those files from the /DESCRIPTION string and/or "configuration" logical name (see the /INCLUDE option), or even from other such files. If you have large numbers of queues making up complicated groupings with similar requirements, this flexibility can help reduce the time required to set up and maintain queues.

In addition to the basic configuration information, there are several optional logical names used to control specific behaviors. Note that the default behaviors may be adequate to your needs.

The following sections describe the various logical names, queue settings, and PRINT command options available with the IPP symbiont. In many cases there is a global version, that affects all IPP symbiont queues on the system, as well as a queue-specific version that affects only a specified queue. PRINT command options affect only the job being submitted.

Global Settings

These logical names establish configuration values for all queues on the system, not on a queue-by-queue basis. Where there are queue-specific settings related to these, these become the default values, overriding any built-in defaults.

TCPWARE_IPP_CONFIG

Specifies one or more of the qualifiers described in the Queue-specific Settings section. These qualifiers are not case sensitive. Underscores (_) in the qualifier names are optional. Each may be abbreviated as long as the result is not ambiguous. There is no default. This logical provides defaults that may be overridden by the queue-specific configuration logical, TCPWARE_IPP_queuename_CONFIG, for a given queue.

TCPWARE_IPP_DEFAULT_DOCUMENT_FORMAT

Specifies a string to use as the document format, unless specified differently for a given queue or print job. The actual document format used on a given job must be a valid MIME media type, supported by the printer to which the job is sent. The default is text/plain.

TCPWARE_IPP_DOCALIAS_FILE

Specifies document format name aliasing. Rather than having to specify long mime-media-type names for document formats, you can define local names that are equivalent, and the symbiont will do the replacement. For example, you can define PS as equivalent to application/postscript, and use it in print commands as /DOCUMENT_FORMAT=PS. There is an escape mechanism in case a local name is ever made into a different MIME-media-type. Prefixing the document format name with % prevents alias translation. %PS means just send it as PS, do not translate PS into APPLICATION/POSTSCRIPT in the request.

To use aliasing, define the system logical name TCPWARE_IPP_DOCALIAS_FILE with the filename of the alias file as the equivalence string. The format of the alias file is:

MIME_media-type: alias, alias, alias...

Blank lines are ignored. Lines starting with # are treated as comments and are ignored.

TCPWARE_IPP_IGNORE_DESCRIPTION
TCPWARE_IPP_queuename_IGNORE_DESCRIPTION

If this logical is defined, the symbiont ignores the /DESCRIPTION strings for all IPP queues. This allows use of /DESCRIPTION for other information without affecting the symbiont. Configuration of the symbiont must be done through use of the TCPWARE_IPP_CONFIG logical, or the queue-specific logical, TCPWARE_IPP_queuename_CONFIG if TCPWARE_IPP_IGNORE_DESCRIPTION is defined. The value of the equivalence string for TCPWARE_IPP_IGNORE_DESCRIPTION is not important. The existence or non-existence of the logical is all that is checked. This logical provides defaults that may be overridden by the queue-specific configuration logical, TCPWARE_IPP_queuename_IGNORE_DESCRIPTION, for a given queue.

TCPWARE_IPP_JOB_RETRY_DELAY

Specifies, as an OpenVMS delta time specification, the length of time to hold a job when it is re-queued due to a temporary problem. The default value is "0 00:10:00.00" (10 minutes).

TCPWARE_IPP_MAX_LOG_BYTES

Specifies how many bytes of data will be logged by the send and receive routines when running with logging level set to DETAILED_TRACE. The value is an integer. A negative value sets the limit to infinite (all data will be logged). A value of zero turns off inclusion of data to the log file. A positive value sets the actual number of bytes logged, and any additional data is ignored. The default action is to log all data.

TCPWARE_IPP_MAX_STREAMS

Specifies the number of streams (queues) that each IPP symbiont process can handle. This is an integer from 1 to 16. The default is 16.

TCPWARE_IPP_LOG_LEVEL

Specifies one of the logging levels values listed in Logging Levels, and is used to determine how serious a message must be before it is written to the log file. Only those messages marked as this level, or as a more serious level, are logged. The default is JOB_TRACE.

TCPWARE_IPP_LOGFILE

Specifies the name of the log file. All queues for a given symbiont process will share this file unless there are individual queue overrides. The default is to create the log file in the default spool directory, with the name IPP_SYMBIONT_pid.LOG.

TCPWARE_IPP_OPCOM_LEVEL

Specifies one of the logging levels values listed in Logging Levels, and is used to determine how serious a message must be before it is sent to OPCOM. Only those messages marked as this level, or as a more serious level, are sent. The default is INFO.

TCPWARE_IPP_OPCOM_TERMINAL

Specifies the OPCOM operator "terminal" to send OPCOM messages to. Permissible values are listed later in this section. The default is the PRINT operator.

Queue-specific Settings

These items are specified as qualifiers in the queue's /DESCRIPTION string, and/or in the TCPWARE_IPP_queuename_CONFIG logical equivalence string. The two are concatenated before being processed. These qualifiers are not case sensitive. The underscores in the qualifier names are optional. Each may be abbreviated as long as the result is not ambiguous. The two sections below contain the complete list of qualifiers.

Queue-specific Required Qualifier

/PRINTER_URI

A valid URI, or list of URIs, for the printer or printers to be sent to from this queue. Wildcards are allowed ("*" to match one or more characters, "?" for a single character). The individual URIs in the list are separated from each other with the vertical bar ("|") character. The first URI in the list that does not include any wildcards is the default printer for the queue. If there are no default printer URIs and you have not specified a particular printer URI with the PRINT command, the job is aborted. Any printer URI specified with the PRINT command must match at least one of the URIs listed for the queue or the job will be aborted.

Queue-specific Optional Qualifiers

/COMMENT=quoted string

Allows inclusion of a quoted string of text that the symbiont will ignore, other than to write to the log file and/or OPCOM if the logging level is set to SYMBIONT or a more detailed setting.

/COPIES_DEFAULT=number

Specifies the number of copies of each document to print unless specified otherwise on the PRINT command. The default value is 1.

/DEBUG

Causes the symbiont to retain all spool files and to force DETAILED_TRACE logging to the log file, regardless of what other settings might be specified. Note that /DEBUG forces the setting for MAX_LOG_BYTES to a minimum of 512 bytes. You can set it higher, but any setting lower than 512 bytes will be ignored when /DEBUG is used.

/DEFAULT_DOCUMENT_FORMAT=formatspec
/DOCUMENT_FORMAT_DEFAULT=formatspec

Specifies the default document format for the queue. This value will be a MIME media type that is supported for the printer or printers served by this queue. It could also be the string ***printer_default***, which will result in whatever the target printer defines as its default when no document format is specified on the PRINT command.

/EXPECT_LINK_CLOSURES

Specifies that the printer is not fully HTTP 1.1 compliant because it does not support persistent connections, and does not send a "Connection: Close" header line in its last response. Therefore, the symbiont should assume that such a line was sent in every response, using a new link for each request, closing the old one, and not treating it as an error if the other end closes the link after sending a response.

/FINISHINGS_DEFAULT=keyword

Specifies finishing operations to be performed on the printed documents. May or may not be supported by a given IPP server. Any or all of the four available finishings may be specified. Case is ignored. Keywords are:

· NONE

· STAPLE

· PUNCH

· COVER

· BIND

/[NO]FLAG_DEFAULT

Specifies whether a “job-sheets” attribute will be specified for jobs by default. If
/FLAG_DEFAULT is used, job-sheets will be requested as “standard”. If /NOFLAG_DEFAULT is used, job-sheets will be requested as “none”.

/INCLUDE=filename

Specifies a sequential access text file containing additional qualifiers from this list. These qualifiers are read and processed at the point where the /INCLUDE qualifier is encountered, and share the precedence of that point.

/JOB_PRIORITY_DEFAULT=integer

Specifies the priority of the print job. 1 is the lowest, 100 is the highest.

/JOB_RETRY_DELAY=deltatime

Specifies, as an OpenVMS delta time specification, the length of time to hold a job when it is re-queued due to a temporary problem. The default value is "0 00:10:00.00" (10 minutes).

/LOG_FILE=filename

Specifies the name of the queue log file to write messages to for this queue. The default is in TCPware’s default spool directory, unless overridden by a global setting, as described in Global Settings. The default filename is IPP_SYMBIONT_Process_PID.LOG.

/LOG_LEVEL=logging_level

Specifies one of the logging levels values listed in Logging Levels and is used to determine the severity of a message before it is written to the queue log file. Only those messages marked as this level, or a more serious one, are logged. The default is JOB_TRACE unless overridden by a global TCPWARE_IPP_OPCOM_LEVEL logical.

/MAX_LOG_BYTES=number

/MEDIA_DEFAULT=name

This attribute identifies the medium that the printer uses for all pages of the job.

The values for "media" include medium-names, medium-sizes, input-trays and electronic forms. See your printer documentation for details concerning what values are supported for your printer.

Standard keyword values are taken from ISO DPA and the Printer MIB and are listed in Section 14 of RFC 2566. Some servers may support definition of locally created names as well. See the Input Tray Names table below for standard values for input trays. The below table contains examples of standard names. These names include, but are not limited to the following:

Name	Description
default	The default medium for the output device
iso-a4-white	Specifies the ISO A4 white medium
iso-a4-colored	Specifies the ISO A4 colored medium
iso-a4-transparent	Specifies the ISO A4 transparent medium
na-letter-white	Specifies the North American letter white medium
na-letter-colored	Specifies the North American letter colored medium
na-letter-transparent	Specifies the North American letter transparent medium
na-legal-white	Specifies the North American legal white medium
na-legal-colored	Specifies the North American legal colored medium
na-9x12-envelope	Specifies the North American 9x12 envelope medium
monarch-envelope	Specifies the Monarch envelope
na-number-10-envelope	Specifies the North American number 10 business envelope medium
na-7x9-envelope	Specifies the North American 7x9 inch envelope
na-9x11-envelope	Specifies the North American 9x11 inch envelope
na-10x14-envelope	Specifies the North American 10x14 inch envelope
na-number-9-envelope	Specifies the North American number 9 business envelope
na-6x9-envelope	Specifies the North American 6x9 inch envelope
na-10x15-envelope	Specifies the North American 10x15 inch envelope
executive-white	Specifies the white executive medium
folio-white	Specifies the folio white medium
invoice-white	Specifies the white invoice medium
ledger-white	Specifies the white ledger medium
quarto-white	Specified the white quarto medium
iso-a0-white	Specifies the ISO A0 white medium
iso-a1-white	Specifies the ISO A1 white medium
a	Specifies the engineering A size medium
b	Specifies the engineering B size medium
c	Specifies the engineering C size medium
d	Specifies the engineering D size medium
e	Specifies the engineering E size medium

The following standard values are defined for input-trays:

Name	Description
top	The top input tray in the printer.
middle	The middle input tray in the printer.
bottom	The bottom input tray in the printer.
envelope	The envelope input tray in the printer.
manual	The manual feed input tray in the printer.
large-capacity	The large capacity input tray in the printer.
main	The main input tray
side	The side input tray

/MULTIPLE_DOCUMENT_HANDLING_DEFAULT=keyword

This qualifier is relevant only for jobs consisting of two or more documents, and when the IPP server supports jobs with multiple documents. The qualifier controls finishing operations and the placement of one or more pages onto media sheets. When printing multiple copies, it also controls the order in which the copies that result are produced. Standard keyword values are listed in the below table.

single-document

If a job has multiple documents, say, the documents are called A and B, then the result printing the data (A and then B) will be treated as a single sequence of media sheets for finishing operations; that is, finishing would be performed on the concatenation of the two documents. The printer will not force the data in each document to start on a new page.

If more than one copy is requested, the ordering of the pages resulting from printing will be A, B, A, B, ..., and the printer will force each copy (A, B) to start on a new media sheet.

separate-documents-uncollated-copies

If a job has multiple documents, say, the documents are called A and B, then the result of printing each document will be treated as a single sequence of media sheets for finishing operations; that is, the documents A and B would each be finished separately. The printer will force each copy of the data in a single document to start on a new sheet.

If more than one copy is made, the ordering of the pages will be A, A, ..., B, B ... .

separate-documents-collated-copies

If a job has multiple documents, say, A and B, then the result will be that each document will be treated as a single sequence of media sheets for finishing operations; that is, A and B would each be finished separately. The printer will force each copy of the result of processing the data in a single document to start on a new sheet.

If more than one copy is made, the ordering of the documents will be A, B, A, B,... .

single-document-new-sheet

Same as single-document, except that the printer will ensure that the first page of each document in the job is placed on a new media sheet.

The single-document value is the same as separate-documents-collated-copies with respect to ordering of print-stream pages, but not media sheet generation, since single-document will put the first page of the next document on the back side of a sheet if an odd number of pages have been produced so far for the job, while separate-documents-collated-copies always forces the next document or document copy on to a new sheet. In addition, if the finishings attribute specifies staple, then with single-document, documents A and B are stapled together as a single document with no regard to new sheets, with single-document-new-sheet, documents A and B are stapled together as a single document, but document B starts on a new sheet, but with separate-documents-uncollated-copies and separate-documents-collated-copies, documents A and B are stapled separately.

Note: None of these values provide means to produce uncollated sheets within a document, i.e., where multiple copies of sheet n are produced before sheet n+1 of the same document.

/NUMBER_UP_DEFAULT=number

Specifies the number of page images to be placed on each side of each sheet of paper. The number must be an integer that is acceptable to the IPP server. If the number specified is not a value supported by the server, the job aborts.

/OPCOM_LEVEL=logging_level

Specifies one of the logging levels value listed in Logging Levels, and is used to determine the severity of a message before it is sent to OPCOM. Only those messages marked as this level, or at a more serious level, are sent. The default is INFO unless overridden by a global TCPWARE_IPP_OPCOM_LEVEL logical.

/OPCOM_TERMINAL=opcom_term

Specifies which OPCOM operator terminal to send OPCOM messages to. The default is the PRINT operator. See the OpenVMS documentation for the REPLY/ENABLE command for more information on OPCOM terminals.

/ORIENTATION_DEFAULT=keyword

Specifies the default page orientation. Case is ignored. Supported values are:

· PORTRAIT

· REVERSE_PORTRAIT

· LANDSCAPE

· REVERSE_LANDSCAPE

/PAGE_RANGE_DEFAULT="range[,range]..."

Specifies the page numbers to print. range is either a single integer page number, or a pair of page numbers, separated by a hyphen. Multiple range specifications are separated by commas. For example:

$ PRINT/QUEUE=IPP_QUEUE/PARAM=(PAGE_RANGES="1,3-6,9,12-14") TEST.TXT

The example specifies the pages: 1, 3, 4, 5, 6, 9, 12, 13, and 14. Note that embedded spaces are allowed, and ignored.

/QUALITY_DEFAULT=keyword

Specifies the quality of the printed material. Case is ignored. The keywords are:

· DRAFT

· NORMAL

· HIGH

/SIDES_DEFAULT=keyword

Specifies how the printing is to be placed on the paper.

· ONE-SIDED: prints each consecutive page upon one side of consecutive media sheets.

· TWO-SIDED-LONG-EDGE: prints each consecutive pair of pages upon the front and back sides of consecutive media sheets, with the orientation of each pair of pages on the long edge. This positioning is called duplex or head-to-head also.

· TWO-SIDED-SHORT-EDGE: prints each consecutive pair of pages upon front and back sides of consecutive media sheets, with the orientation of each pair of print-stream pages on the short edge. This positioning is called tumble or head-to-toe also.

/SPOOL_DIRECTORY=dirspec

Specifies the directory to use for storing temporary files used while processing print jobs for the queue. The default is TCPware's default spool directory.

Order of Processing

The various logicals and qualifiers described in the previous two sections sometimes define the same configuration item. The operation has been defined, but the precedence has not. The order, from lowest precedence to highest, is:

1. Built-in hard coded default values.

2. Global logicals, as described in the first section.

3. Queue-specific qualifiers found in the /DESCRIPTION string of the queue.

4. Queue-specific qualifiers found in the queue-specific CONFIG logical.

The queue-specific qualifiers are parsed second, allowing for an override of the global settings on a queue-by-queue basis when that behavior is desired.

PRINT Command Options

Print command options are specified using the OpenVMS standard /PARAMETERS qualifier. The list of options is enclosed in parenthesis. For example,

$ PRINT /QUEUE=IPP_PRINTER_1 /PARAMETER=(COPIES=3, ORIENTATION=LANDSCAPE) FILE.TXT

These options are not case sensitive. The underscores in the option names are optional. Each may be abbreviated as long as the result is not ambiguous.

The available print command options are:

PRINTER=printer_uri

Specifies the target printer when the queue default is not desired, or when there is no queue default. The printer URI specified must match at least one of the defined printer URI's for the print queue.

Wildcards cannot be used in the printer URI.

COPIES=number

Specifies the number of copies of each document to print. The default value is 1.

SIDES=keyword

Specifies how the printing is to be placed on the paper. The keyword must be one of the following:

· ONE-SIDED or 1sided: prints each consecutive page upon one side of consecutive media sheets.

· TWO-SIDED-LONG-EDGE or two-long-edge or 2long_side: prints each consecutive pair of pages upon the front and back sides of consecutive media sheets, with the orientation of each pair of pages on the long edge. This positioning is called duplex or head-to-head also.

· TWO-SIDED-SHORT-EDGE or two-short-edge or 2short_side: prints each consecutive pair of pages upon front and back sides of consecutive media sheets, with the orientation of each pair of print-stream pages on the short edge. This positioning is called tumble or head-to-toe also.

ORIENTATION=keyword

Specifies the page orientation. The keyword must be one of:

· PORTRAIT

· REVERSE_PORTRAIT

· LANDSCAPE

· REVERSE_LANDSCAPE

These can be abbreviated to any non-ambiguous prefix. Case is ignored.

[NO]FLAG

Requests, or suppresses, the printing of an IPP flag page for the job. The printer may, or may not, respond to this request. The exact format of this flag page is up to the IPP Server (printer) implementation.

NUMBER_UP=number

DOCUMENT_FORMAT=MIME-media-type

DOCUMENT_FORMAT=***printer_default***

Specifies the document format of the files in the job, or specifies use of the printer's built-in default. The default for this qualifier is the default for the queue. Also, if the queue configuration does not specify a default document format, the hard coded default is text/plain.

JOB_PRIORITY=integer

Specifies the priority of the print job at the IPP server (not to be confused with the OpenVMS queue priority). 1 is the lowest, 100 is the highest.

FINISHINGS=“keyword[,keyword]...”

· BIND

· COVER

· PUNCH

· STAPLE

MULTIPLE_DOCUMENT_HANDLING=keyword

Specifies how you want the printer to print your job. The keyword is one of the following:

· Single_Document or 1Document

· Separate_Documents_Uncollated_Copies or UncollatedSeparate

· Separate_Documents_Collated_Copies or CollatedSeparate

· Single_Document_New_Sheet or NewSheet

Case is ignored. See /MULTIPLE_DOCUMENT_HANDLING_DEFAULT in this chapter for information on single document, separate-documents-uncollated-copies, separate-documents-collated-copies, and single-document-new-sheet handling.

PAGE_RANGES="range[,range]..."

Specifies the page numbers to print. range is either a single integer page number, or a pair of page numbers, separated by a hyphen. Multiple range specifications are separated by commas and enclosed in double quotes.

For example:

$ PRINT/QUEUE=IPP_QUEUE/PARAM=(PAGE_RANGES="1,3-6,9,12-14") FILE.TXT

Note that embedded spaces are allowed, and ignored. The example specifies the pages: 1, 3, 4, 5, 6, 9, 12, 13, and 14.

MEDIA=name

This attribute identifies the medium that the printer uses for all pages of the Job.

The values for name include medium-names, medium-sizes, input-trays and electronic forms. See your printer documentation for details concerning what values are supported for your printer.

Standard keyword values are taken from ISO DPA and the Printer MIB and are listed in section 14 of RFC 2566. Some servers may support definition of locally created names as well.

See Standard Media Names and Input Tray Names for the standard media names.

QUALITY=keyword

Specifies the quality of the printed material. Case is ignored. The keyword choices are:

· DRAFT

· HIGH

· NORMAL

Using Logicals to Define Queue Configurations

This section provides examples of using logicals to define queue configuration prior to queue initialization. This method can be used both as an alternative to and in addition to the
/DESCRIPTION string shown in the previous examples. See the Configuration section for a complete description of all available qualifiers.

Setting Up IPP Symbiont Queues

Creating an IPP symbiont queue is done using the OpenVMS INITIALIZE/QUEUE command. All standard qualifiers are allowed, but the /DESCRIPTION qualifier has special use with the IPP symbiont. See the Configuration section.

Setting up IPP Symbiont Queues Using Queue-Specific Logicals

Set up an IPP symbiont queue named ENG_PRINTER to obtain its configuration information from a queue specific configuration file and to print a flag page with each job.

$ DEFINE/SYSTEM TCPWARE_IPP_ENG_PRINTER_CONFIG -
_$ "/INCLUDE=SYS$SYSTEM:ENG_PRINTER.SETUP/FLAG_DEFAULT"
$ INITIALIZE/QUEUE/PROCESSOR=TCPWARE_IPP_SYMB ENG_PRINTER

The file SYS$SYSTEM:ENG_PRINTER.SETUP contains:

/printer="ipp://engprinter.mynet.com:631/ipp"

Setting Up an IPP Symbiont Queue to Print Only to a Specific Printer

Set up the IPP symbiont queues named IPP_PRINT_QUEUE and IPP_PRINT_2 to print only to the iprinter.example.com printer on port 631. Additionally, IPP_PRINT_2 will always print two copies of each submitted file if copies are supported by the printer.

$ DEFINE/SYSTEM TCPWARE_IPP_CONFIG -
_$ "/PRINTER_URI=""ipp://iprinter.example.com:631/ipp"""
$ INITIALIZE/QUEUE /PROCESSOR=TCPWARE_IPP_SYMB IPP_PRINT_QUEUE
$ INITIALIZE/QUEUE /PROCESSOR=TCPWARE_IPP_SYMB -
_$ /DESCRIPTION="/copies_default=2" IPP_PRINT_2

Setting Up to Print to Multiple Printers Using Wildcards

Set up an IPP symbiont queue to print to any IPP printer in the exmaple.com domain, with the default printer being iprinter.example.com:

$ INITIALIZE/QUEUE /PROCESSOR=TCPWARE_IPP_SYMB –

_$ /DESCRIPTION="/printer=
""http://iprinter.example.com:631/ipp|*.example.com""" IPP_PRINT_QUEUE

Setting Up Two Queues Using a Disk File for Queue Settings

Set up two IPP symbiont queues to print to any printer in the example.com domain, with the default printer being iprinter.example.com for one queue, and oprinter.example.com for the other. Log all possible messages to the log file, but send only messages more severe than FILE_TRACE to OPCOM. Use a 5 minute retry delay, and make the document format default the same as the printer's default. Use a disk file for the configuration information common to both queues:

$ INITIALIZE/QUEUE /PROCESSOR=TCPWARE_IPP_SYMB -
_$ /DESCRIPTION="/printer=
""http://iprinter.example.com:631/ipp|*.example.com""
/include=SYS$SYSTEM:IPP_QUEUE.SETUP" IPRINTER_QUEUE

$ INITIALIZE/QUEUE /PROCESSOR=TCPWARE_IPP_SYMB -
_$ /DESCRIPTION="/printer=
""http://oprinter.example.com:631/ipp|*.example.com""
/include=SYS$SYSTEM:IPP_QUEUE.SETUP" OPRINTER_QUEUE

The file SYS$SYSTEM:IPP_QUEUE.SETUP contains:

/log_level=DETAILED_TRACE
/opcom_level=FILE_TRACE
/job_retry_delay="0 00:05:00.00"
/default_document_format=***printer_default***

Setting Up Two Queues with no Configuration Values in the INITIALIZE Command

Do the same as the prior example, but put as much of the configurations in disk files as possible to allow changes to queue characteristics without having to re-initialize the queues:

$ INITIALIZE/QUEUE /PROCESSOR=TCPWARE_IPP_SYMB -
_$ /DESCRIPTION="/INCLUDE=SYS$SYSTEM:IPP_IPRINTER.SETUP" IPRINTER_QUEUE

$ INITIALIZE/QUEUE /PROCESSOR=TCPWARE_IPP_SYMB -
_$ /DESCRIPTION="/INCLUDE=SYS$SYSTEM:IPP_OPRINTER.SETUP" OPRINTER_QUEUE

The file SYS$SYSTEM:IPP_IPRINTER.SETUP contains:

/printer="http://iprinter.example.com:631/ipp|*.example.com"
/include=SYS$SYSTEM:IPP_QUEUE.SETUP

The file SYS$SYSTEM:IPP_OPRINTER.SETUP contains:

/printer="http://oprinter.example.com:631/ipp|*.example.com"
/include=SYS$SYSTEM:IPP_QUEUE.SETUP

The file SYS$SYSTEM:IPP_QUEUE.SETUP contains:

/log_level=DETAILED_TRACE
/opcom_level=FILE_TRACE
/job_retry_delay="0 00:05:00.00"
/default_document_format=***printer_default***

Submitting Jobs to IPP Symbiont Print Queues

This section describes how to submit jobs to the IPP symbiont print queues.

Printing a Single Text File to an IPP Queue

Print the file FOO.TXT to the IPRINTER (default destination printer) set up in the prior examples:

$ PRINT/QUEUE=IPRINTER_QUEUE foo.txt

Specifying the Destination Printer on the Print Command

Print a single text file to a non-default printer on a queue with a wild carded printer URL:

$ PRINT /QUEUE=iprinter_queue -
_$ /PARAM=(printer="ipp://another.example.com/ipp/port1") foo.txt

Note: The above will fail unless the queue specifies another.example.com as a legal URL, either explicitly or by using wildcards.

Using Other Print Qualifiers

Print a text file to a default printer on a queue but specify the document format and additional copies:

$ PRINT /QUEUE=iprinter_queue -
_$ /PARAM=(document="text/plain" copies=3) foo.txt

IPP SHOW Command

The IPP SHOW utility allows a user to learn the capabilities supported by an IPP server. This utility queries the server and displays the supported attributes. The program can be used to see what a given server supports, by a program to gather information about a number of printers, or by a DCL or other program to check the capabilities of a given server before submitting a print job to a queue. The command syntax is:

$ TCPWARE IPP SHOW server_URI /qualifiers...

Qualifiers

/ATTRIBUTE=attribute

Puts the program into a mode suitable for use from a DCL command procedure. Not compatible with the /FORMAT or /OUTPUT qualifiers or those associated with them. It causes the program to return the value of a single attribute as a character string in a DCL symbol. This is for a procedure to check to see if, for example, a given server supports color printing before submitting a job to a queue that requires color output. Allowable values for attribute are:

Charset_Configured
Charset_Supported
Color_Supported
Compression_Supported
Copies_Default
Copies_Supported
Document_Format_Default
Document_Format_Supported
Finishings_Default
Finishings_Supported
Gen_Natural_Language_Supported
Job_Hold_Until_Default
Job_Hold_Until_Supported
Job_Impressions_Supported
Job_K_Octets_Supported
Job_Media_Sheets_Supported
Job_Priority_Default
Job_Priority_Supported
Job_Sheets_Default
Job_Sheets_Supported
Media_Default
Media_Supported
Multiple_Doc_Handling_Default
Multiple_Doc_Handling_Supported
Multiple_Operation_Timeout
Natural_Language_Configured
Number_Up_Default
Number_Up_Supported
Operations_Supported

Orientation_Requested_Default
Orientation_Requested_Supported
Page_Ranges_Default
Page_Ranges_Supported
PDL_Override_Supported
Print_Quality_Default
Print_Quality_Supported
Printer_Current_Time
Printer_Driver_Installer
Printer_Info
Printer_Is_Accepting_Jobs
Printer_Location
Printer_Make_and_Model
Printer_Message_From_Operator
Printer_More_Info
Printer_More_Info_Manufacturer
Printer_Name
Printer_Resolution_Default
Printer_Resolution_Supported
Printer_State
Printer_State_Message
Printer_State_Reasons
Printer_Uptime
Printer_URI_Supported
Queued_Job_Count
Reference_URI_Schemes_Supported
Sides_Default
Sides_Supported
URI_Security_Supported

/[NO]APPEND

Specifies that output should be appended to an existing output file if possible. /NOAPPEND is the default.

/FORMAT=style

Specifies what print style to use. style is either

· SCREEN (default) which writes in a human-friendly screen-formatted mode, or

· LIST which writes an easy to parse, name=value format, one name/value pair per line.

/[NO]FULL

Causes all IPP attributes to be included in the display, whether the server supports them or not. Those not supported are marked as such. /NOFULL is the default.

/[NO]GLOBAL

Specifies whether the named symbol should be created as a DCL global symbol. Used only with
/ATTRIBUTE. If specified as /NOGLOBAL, the symbol will be local to the calling procedure level. /GLOBAL is the default.

/OUTPUT=file

Specifies a file to write output to. SYS$OUTPUT: is the default.

/SYMBOL=symbolname

Specifies a DCL symbol name that should be set to the value of the specified attribute. Used only with /ATTRIBUTE. The default is IPP SHOW_RESULT if /SYMBOL is not specified.

EXAMPLES of IPP SHOW Use and Output

1. Basic operation with all defaults:

$ TCPWARE IPP SHOW LILLIES.EXAMPLE.COM

LILLIES.EXAMPLE.COM as of Tue Aug 10 16:08:43 2020

CURRENT INFO:
    Printer State:       Idle
    State Reasons:       none
    Accepting Jobs?:     Yes
    Queued Job Count:    0

PRINTER INFO:
    Name:                Lexmark Optra T610
    Make & Model:        Lexmark Optra T610

DEFAULTS:
    Document Format:     application/octet-stream
    Orientation:         Portrait
    Number-Up:           1
    Copies:              1
    Job Media Sheets:    none
    Character Set:       utf-8
    Natural Language:    en-us

SUPPORTED FEATURES AND ALLOWED VALUES:
    Color?:              No
    Orientation:         Portrait, Landscape
    Document Formats:    application/octet-stream, application/postscript,
                         application/vnd.hp-PCL, text/plain
    Job Sheets:          none, standard
    Number-Up:           1:16
    Copies:              1:999
    PDL Override:        not-attempted
    Character Sets:      utf-8, us-ascii
    Natural Languages:   en-us
    Operations:          Print_Job, Validate-Job, Cancel-Job,
                         Get-Job_Attributes, Get-Jobs,
                         Get-Printer_Atrributes, Unknown: 18

URIs Supported and associated security options:
        URI:      http://192.168.50.2/
        Security: none

        URI:      http://192.168.50.2:631/
       Security: none

2. Operation with /FULL and output to a file (note that the "/" character in the URI requires use of quotes around the server URI parameter):

$ TCPWARE IPP SHOW "LILLIES.EXAMPLE.COM/IPP" /FULL /OUTPUT=FOO.BAR

FOO.BAR contains:

LILLIES.EXAMPLE.COM/IPP as of Tue Aug 10 16:11:54 2020

CURRENT INFO:
    Printer State:       Idle
    State Reasons:       none
    State Message:       <not supported>
    Accepting Jobs?:     Yes
    Queued Job Count:    <not supported>
    Uptime (seconds):    <not supported>
    Printer Time:        <not supported>

PRINTER INFO:
    Name:                LILLIES
    Printer Location:    <not supported>
    Printer Info:        MANUFACTURER:Hewlett-Packard;COMMAND SET:PJL,ML -
                           C,PCL,PCLXL,POSTSCRIPT;MODEL:HP LaserJet 2100 -
                           Series;CLASS:PRINTER;DESCRIPTION:H
    URL for more info:   <not supported>
    URL for driver:      <not supported>
    Make & Model:        <not supported>
    URL for Maker:       <not supported>

DEFAULTS:
    Document Format:    application/octet-stream
    Orientation:         <not supported>
    Number-Up:           <not supported>
    Sides:               <not supported>
    Copies:              <not supported>
    Mult. Doc. Handling: <not supported>
    Media:               <not supported>
    Job Media Sheets:    <not supported>
    Finishings:          <not supported>
    Job Priority:        <not supported>
    Job Hold Until:      <not supported>
    Print Quality:       <not supported>
    Printer Resolution: <not supported>
    Character Set:       us-ascii
    Natural Language:    en-us
    Mult. Op. Timout:    <not supported>

SUPPORTED FEATURES AND ALLOWED VALUES:
    Color?:              <not supported>
    Orientation:         <not supported>
    Document Formats:    text/plain, text/plain; charset=US-ASCII,
                           application/postscript, application/vnd.hp-PCL,
                           application/octet-stream
    Job Sheets:          <not supported>
    Number-Up:           <not supported>
    Sides:               <not supported>
    Copies:              <not supported>
    Mult. Doc. Handling: <not supported>
    Media Names:         <not supported>
    Job Media Sheets:    <not supported>
    Finishings:          <not supported>
    Job Priority:        <not supported>
    Job Hold Until:      <not supported>
    Page Ranges?:        <not supported>
    Print Qualities:     <not supported>
    Resolutions:         <not supported>
    Compression Modes:   <not supported>
    Job K-octets:        <not supported>
    Job Impressions:     <not supported>
    PDL Override:        not-attempted
    Character Sets:      us-ascii, utf-8
    Natural Languages:   en-us
    URI Schemes:         <not supported>
    Operations:          Print_Job, Validate-Job, Cancel-Job,
                           Get-Job_Attributes, Get-Jobs,
                           Get-Printer_Atrributes

URIs Supported and associated security options:

        URI:      /ipp
        Security: none

        URI:      /ipp/port1
        Security: none

MESSAGE FROM OPERATOR:

<no Message>

3. Operation with /ATTRIBUTE and /SYMBOL and /GLOBAL to get a single attribute into a DCL symbol:

$ TCPWARE IPP SHOW LEXIM /ATTRIB=NUMBER_UP_SUPPORTED /SYMBOL=NUMUP /GLOBAL
$ SHO SYM NUMUP
NUMUP == "1:16"
$