Managing Print Services

Introduction

This chapter describes how to manage the TCPware print services, which include 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.

PRINT

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.

Figure 14-1 shows how to use an LPR command with an LPS configuration.

Figure 14-1 Using a UNIX-Style LPR Command

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 Table 14-1) provide different kinds of print format support, configurable during the CNFNET procedure.

Table 14-1 LPS Print Symbionts

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 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 Table 14-2, as supported for each of the print symbionts:

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

Table 14-2 Supported DEFINE/FORM Qualifiers

DEFINE/FORM qualifier... Description

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

Example 14-1 shows a sample entry in the PRINTCAP. file.

Example 14-1

Remote Print Queue Names in the Local PRINTCAP. File

#

# LOCAL PRINTERS

#

test_printer:

  :lp=test_printer:

  :rm=alcor:

  :rp=eng2_printer:

In this example, the name of the local printer (lp) is test_printer. The remote machine (rm) is alcor, 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 ALCOR'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

Table 14-3 explains the purpose of each LPS client logical.

Table 14-3 LPS Client Logicals

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 Table 14-4.

Table 14-4 VMSLPRSMB Tuning Logicals

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 Table 14-4). 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>). (See Print Forms.)

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:
<ESC>]VMS;2<ESC>

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 Table 14-5. (It does not support other options and ignores print requests you issue with such options, without issuing an error message.)

Table 14-5 Options Supported by LPD Server

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 internet address. (Using the internet 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

See LPS System Logicals.

Table 14-6 explains the purpose of each LPD server logical.

Table 14-6 LPD Server Logicals

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 Example 14-2.
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 Example 14-2.

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.

Example 14-2 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.

Example 14-2 Using the LPD Logicals to Support a Printer

$ 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. Figure 14-2 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.

Figure 14-2 The OpenVMS PRINT Command and TSSYM

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 (see Table 14-7).

/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 in Table 14-7 to your printer startup commands or in your system startup file (SYSTARTUP_V5.COM or SYSTARTUP_VMS.COM).

Table 14-7 Printer Startup Commands

$ 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 (Table 14-8 shows some common port numbers)

options

Use the following /ON options singly or in the combinations given (each option separated by a comma):

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.

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

TRIMFFqname

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.

Table 14-8 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. The Compaq 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::,...])

Example 14-3 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.

Example 14-3 Command Sequence to Set Up an Autostart Queue

$ 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 Figure 14-3.

Figure 14-3 Sample TSSYM Configuration

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 Compaq'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 Table 14-9. See LPS System Logicals.

Table 14-9 TSSYM Tuning Logicals

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 default is 0::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.

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

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.

DEFINE/FORM qualifier...	Description
/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.)

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

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

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

*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 internet address. (Using the internet 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.

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 Example 14-2. 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 Example 14-2.
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.

/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 (see Table 14-7).
/AUTOSTART_ON	implements an autostart queue (if enabled) on one or more nodes if used together with the TCPWARE_TSSYM_qname logical.

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 (Table 14-8 shows some common port numbers)
options			Use the following /ON options singly or in the combinations given (each option separated by a comma):

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

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

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<

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 default is 0::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.