LPR Command

Purpose

Use the LPR command to print files on remote printers.

Operands- Synchronous and Asynchronous

filename

Specifies the name of the file to print.

filetype

Specifies the type of the file to print.

filemode

Specifies the mode of the file to print. If filemode is specified as an asterisk (*), the first file found in the CMS search order is used. If filemode is omitted, a file mode of A is assumed. If a CMS file mode number is not specified, the default is 1.

Synchronous operations cannot be used to process files that have a file mode number of 3 or 4. For asynchronous operations, this restriction applies to only file mode number 3 files. See the z/VM: CMS User's Guide for information about file mode numbers and how they are used by CMS.

ASYNCHRONOUS

This option will send LPR requests to another server (RSCS) for later printing. As a result, this causes LPR operations to be deferred. When this option is in effect, subsequent LPR commands cause data to be queued to an intermediate print service machine (an RSCS server). As a result, interaction with a remote print daemon is handled by this service machine and ensures your file will be processed with no further action required by you. Messages and status information associated with a deferred transaction are returned to your console.

CC

Causes the remote system to interpret the first character of each data line as ASA carriage control; this is the default for files with a file type of either LISTING or LIST3800.

NOCC

Prevents the remote system from interpreting the first character of each data line as ASA carriage control; this is the default for all files except those with a file type of either LISTING or LIST3800.

COPIES nn

Specifies the number of copies to be printed; the default is 1. Note that some remote servers may not recognize or honor requests to produce multiple copies of a file. For asynchronous operations, a maximum of 255 can be specified.

CLASS data

Specifies the print job classification to be used by the remote system when the print file is processed. By default, the host name (combined with the domain name, if available) defined in the TCPIP DATA file is supplied as data for synchronous operations; A is the asynchronous default.

For synchronous operations, data is restricted to 31 characters. For print requests directed to a UNIX-like lpd, data will be printed on the burst (or, banner) page.

For asynchronous operations, data specifies a spool file class. For such operations, data must be a single alphanumeric value (A-Z or 0-9) or an asterisk (*).

FILTER code

Specifies the type of processing to be performed against print file data by the remote system. The filter code value must be a single letter. Both uppercase and lowercase letters are accepted, but uppercase letters are converted to lowercase since only lowercase filter values are recognized by remote print daemons.

Filter codes provide carriage control. When a filter code is specified, LPR changes several of its conventions. When a filter code of f, l, or r, is specified, LPR does not paginate the processed file. Instead, it sends the data within the file as plain lines. The list that follows provides a description of available filter codes:

Code

Description

f

Print data as a sequence of lines

l

Print, passing through all control characters

p

Print with pagination

r

Print, and interpret the first column as FORTRAN (ASA) carriage control. The following characters are interpreted as indicated:

Character

Printing Action

Space

Start a new line of output

+

Overprint this line on the previously printed line

-

Produce two blank lines, then begin a new line of output

0

Produce one blank line, then begin a new line of output

1

Start new page, and begin printing at first line

For filter codes c, d, g, n, t, or v, LPR transmits the data as a byte stream (as though the BINARY option has been specified).

HOST host

AT host

@ host

Specifies the name or internet address (in dotted-decimal form) of the printer host where the file is to be printed; host is restricted to 255 characters. H is accepted as the minimum abbreviation for the HOST keyword.

LANDSCAPE

For synchronous operations, this option causes PostScript information to be added to the print file so that it will be printed by the remote system in landscape (rotated) format — provided the remote printer can process PostScript.

For asynchronous operations, this option causes a form name of LA to be used when the file is processed. When used in this context, this option will override any FORM value specified as part of a CMS NAMES file entry.

NICKNAME name

Specifies a nickname (defined in your CMS NAMES file) that identifies the printer and host to which files are directed for printing. Printer-specific options can also be defined using such an entry.

PRINTER printer

Specifies the name of the printer on which the file is to be printed; printer is restricted to 255 characters. P is accepted as the minimum abbreviation for this option.

SYNCHRONOUS

Causes LPR operations to be processed immediately; this is the default. When this option is in effect, subsequent LPR commands are processed as immediate operations through the TCP/IP server and the chosen print daemon. Delays in command execution (caused by network congestion, for example) may be apparent, because synchronous processing is dependent upon the interaction between the TCP/IP service machine and the specified print daemon.

TAG usertag

Identifies a specific NAMES file tag from which printer and host destination information is to be retrieved. If such a tag is not identified, an attempt is made to retrieve printer and host values from a set of default tag definitions.

TRACE

Displays detailed command progress information. For synchronous operations, information about the interaction with the remote printer is also displayed.

TRANSLATE tablename

Identifies the file name of a translation table file to be used for EBCDIC to ASCII data translation; the file type for this file must be TCPXLBIN. The first tablename TCPXLBIN file found in the CMS search order is used. If this parameter is not specified, a default translation table is used (if one exists), which is defined by either a CMS NAMES file nickname entry or a CMS global variable; if neither exist, data translation is then performed as follows:

• For synchronous processing, LPR searches for and uses the LPR TCPXLBIN file first, and then the STANDARD TCPXLBIN file. If neither is found, an internal translation table is used.
• For asynchronous processing, default data translation processing is performed by the RSCS server to which files are directed, based on the configuration of that server.

For more information about creating and loading translation tables, see z/VM: TCP/IP Planning and Customization.

If your use of LPR requires specific translations to be performed, see Using translation tables.

TYPE

Displays abbreviated command progress information.

VERSION

Displays program version information.

Operands - Synchronous

ACK

Requests the remote printer host to send an acknowledgment to the LPR command when the connection to that host is closed; this is the default.

NOACK

Requests the remote printer host to not return a receipt acknowledgment to the LPR command. This option was previously required if the receiving system was AIX®; however, its use is no longer necessary.

BINARY

Causes print data to be sent without translation and without any indication of record boundaries. For example, use this option if the file is already in ASCII. At times a filter may also be required to achieve appropriate results; see the description of the FILTER operand in Operands- Synchronous and Asynchronous for more information about filter use. The BINARY option implies that the file to be printed is not PostScript.

NOBINARY

Causes print data to be converted from EBCDIC to ASCII when it is sent to the remote system; this is the default.

BURST

Causes a burst page to be printed on the remote printer; this is the default. This option controls whether burst (or, banner) page information is sent to the server. If a VM LPD server does not receive burst page information, it provides the best information available to a spool device, as CMS does not have an option to omit the burst page for print files.

NOBURST

Prevents a burst page from being printed on the remote printer.

HEADER

Causes a page header to be inserted by the LPR client at the beginning of every printed page — if the NOCC and NOBINARY options are in effect. HEADER is the default. To instead cause the remote printer to insert page headers, use the FILTER p and NOHEADER options.

NOHEADER

Prevents the LPR client from inserting page headers.

INDENT nn

Specifies the number of columns the remote printer indents output when the FILTER f or FILTER l options are in effect.

JOB data

Specifies a print job description, name, or other job information to be used by the remote system; a maximum of 99 characters can be specified. By default, the string filename.filetype is used for data.

For a UNIX-like lpd, this option causes job information to be printed on the banner page; for a VM LPD server, it can be used to pass additional job information for use by that LPD server.

JOBNUM nnn

JNUM    nnn

Specifies the job number used to construct the file names of protocol-specific files sent to the remote print server. The provided value must be a three-digit, numeric string. If a specific string is not specified using this option, a three-digit random number is used.

This option can be used to reduce the likelihood of problems caused by duplicate file names when many LPR jobs are initiated. To be effective toward this end, the files to be printed must be processed by a single VM user ID; as LPR commands are issued for each file, sequential job numbers should be specified using the JOBNUM option. However, collisions with jobs run by other virtual machines are still possible; a collision occurs when one of the print jobs fails.

LINECOUNT nn

Specifies the number of lines to be printed before a new heading is printed; the default is 55. This parameter has meaning only for files for which the CC option is not in effect (either explicitly or implicitly). A value of zero (0) can be used to prevent page ejects and page headers from being inserted in the print file.

MAIL

Causes mail to be sent to you when the printing operation ends that informs you about the success or failure of the print job. This option may not recognized by all remote printing servers.

NAME data

Specifies job name information to be provided by the remote system in response to a remote printer query (that is, an LPQ command). The supplied data is restricted to 131 characters. By default, the string filename.filetype is used for data. This option is not recognized by all remote printing servers.

POSTSCRIPT

Causes header information to be added to the print file so that it will be recognized as PostScript by the remote printer.

NOPOSTSCRIPT

Prevents a file from being recognized as PostScript.

RFCports

Enforces the use of RFC-compliant printer source ports when print requests are processed. Some printer host machines require the source port to be within either the 721-731 port range, or the alternative range of all "well-known" ports (1-1023).

Note: By default, TCP/IP for z/VM® restricts general use of well-known ports. To use the RFCPORTS operand, you may need to contact your local TCP/IP administrator to obtain authorization to use such ports.

TITLE title

Specifies the title assigned to a file printed with the FILTER p option. A maximum of 79 characters can be specified for title.

WIDTH nn

Specifies the line width to be used for a file printed with the FILTER f or FILTER l option. The value you provide may be decreased by the remote printer host.

Operands - Asynchronous

FORM formname

Specifies a spool file form name (used by RSCS) to control how data is printed at the destination printer. For PostScript data, formname can be specified as a character string of the form OrFnFsLs, to specify a default orientation, font name, font size, and additional leading size to be used by the destination printer. For OrFnFsLs the following can be specified:

Or

File Orientation

PO

Portrait (default)

LA

Landscape

Fn

Font

CB

Courier Bold

CI

Courier Oblique

CP

Courier (default)

CX

Courier BoldOblique

HB

Helvetica Bold

HP

Helvetica

HI

Helvetica Oblique

HX

Helvetica BoldOblique

SP

Symbol

TB

Times Bold

TI

Times Italic

TP

Times Roman

TX

Times BoldItalic

Fs

Font sizes, 04-99. The default is 11 for portrait (PO) and 10 for landscape (LA).

Ls

Additional leading size, 0.0-9.9 added to font size to give leading, specified as 00 thru 99. The portrait (PO) default is 09; that for landscape (LA) is 12.

Note:

1. The font specified via OrFnFsLs must be installed and used by the destination printer for correct results to be achieved.
2. For ASCII PostScript files, the default form name used is P+ASCII; for EBCDIC PostScript files, the default is P+SCRIPT. There is no default for non-PostScript files.
3. FORM cannot be used with the LANDSCAPE option.
4. The spool file form name (formname) is translated to uppercase prior to use.

PREFIX data

Specifies a data string to be passed to the remote printer device by the RSCS server; up to 500 characters can be specified. Prefix data is translated to uppercase and is inserted at the beginning of the data file by RSCS, and might be used to affect printer settings; for example, to select a paper tray.

RSCS linkid,nodeid

RSCS linkid@nodeid

RSCS linkid AT nodeid

Identifies the RSCS link that provides a connection to a target print daemon or device, where:

• linkid is the one- to eight-character link identifier of the RSCS link that provides the connection to the chosen print daemon or device.
• nodeid is the one- to eight-character node name of the remote VM system that provides the connection to a target chosen print daemon or device.

When specific link and node values are not defined, LPR is used as the default link identifier (linkid) for non-PostScript files, while LPRP is used for PostScript files; the local node (as returned by the CMS IDENTIFY command) is used for nodeid.

SERVER rscsid

Identifies an RSCS service virtual machine to which print data is to be spooled. By default, the RSCS server reported by the CMS IDENTIFY command is used.

SUFFIX data

Specifies a data string to be passed to the remote printer device by the RSCS server; up to 500 characters can be specified. Suffix data is translated to uppercase and is inserted at the end of the data file by RSCS. A suffix data string might be used to affect printer settings; for example, to reset the printer state.

Usage Notes

1. When LPR commands are issued and certain operands are omitted, LPR will attempt to use values defined by CMS global variables for the TCPIP group. Operands to which this applies are:
   • printer and host
   • RSCS linkid and nodeid
   • Mode of operation (SYNCHRONOUS or ASYNCHRONOUS)
   • NICKNAME name and TAG usertag
   • TRANSLATE tablename

   Values for these operands can be established and changed using the LPRSET command.

2. LPR command operands are selected, in order, from the following sources:
   1. the LPR command itself
   2. CMS NAMES file entries
   3. CMS global variables

   Values from different sources may be combined and used for a single LPR command.

3. CMS NAMES file tags recognized by the LPR command and the options to which they correspond follow:

   Tag

   Corresponding Option(s)

   :CSADDR

   PRINTER and HOST

   :FILTER

   FILTER

   :LPRADDR

   PRINTER and HOST

   :NODE

   HOST

   :TCPADDR

   PRINTER and HOST

   :USERID

   PRINTER

   :TRANSLATE

   TRANSLATE

    

    

   :LINKID

   RSCS

   :NODEID

   RSCS

   :PREFIX

   PREFIX

   :SERVER

   SERVER

   :SUFFIX

   SUFFIX

   :FORM

   FORM

   Tags listed in the first group are supported for both synchronous and asynchronous operations; those listed in the second group are applicable only to asynchronous use. For all tags, values should be specified in the same manner as for their corresponding options.
4. Print destination information (that is, the combination of a printer and host name) is obtained for NAMES file entries, in order, from the following tags:
   1. a user-specified tag, as identified by the TAG option
   2. an address tag, if the TAG option is not specified. Address tags are checked, when present, in this order:
      1. :LPRADDR
      2. :TCPADDR
      3. :CSADDR
   3. the :USERID and :NODE tags, if no information is defined by any of the previously listed tags. In the context of using TCP/IP remote printing commands, these tags are presumed to provide printer and host names, respectively, instead of conventional user ID and node ID information.
   Printer and host values for user-specific tags and the address tags previously listed can be specified using one of these formats:

   • linkid nodeid
   • linkid,nodeid
   • linkid@nodeid
   • linkid AT nodeid
5. Printer names may be case-sensitive, though this depends upon the host to which remote printing commands are directed. In many cases, the printer name you provide must match the printer definition used by the remote host. For example, on UNIX-like systems, prt1 and PRT1 can refer to different printers.
6. For certain operands, values can be specified as quoted strings, so that the content between the string delimiters — either single (') or double (") quotation marks — is preserved. Operands for which quoted values are accepted are: PRINTER, HOST, CLASS, JOB, NAME, and TITLE.
7. The LPR command can be used to print PostScript documents. When a file is processed by LPR, the file is checked to determine whether it is a PostScript file. If it is, additional checks are performed (for synchronous operations only) to verify that compatible options have been provided. If you want to override these checks when you print a PostScript file, use the NOPOSTSCRIPT option.

   Remote hosts usually examine the first few characters of a file to determine if that file is PostScript; this is usually indicated by the presence of the character string %! in the first line of the file. For synchronous operations, the POSTSCRIPT option can be used to ensure a file is recognized as PostScript.

8. Carriage control is interpreted line by line. A file can mix ASA and machine carriage control. Interpretation is done by converting the controls to the appropriate ASCII sequences before the file is sent to the remote system. Lines that have invalid carriage control are not printed.

   When a file is printed without carriage control, LPR adds a heading line to each page of output that shows the name of the printed file, the name of the system on which the LPR command originated, and a page number. You can specify the number of lines per page (not counting the three heading lines) with the LINECOUNT option.

9. The logical record length (LRECL) of files that can be processed is restricted for both synchronous and asynchronous operations.
   • For synchronous operations, LPR processes files using OS file routines. Thus for fixed-format files, the maximum LRECL is 32760; for variable-format files, the maximum LRECL is 32756.
   • For asynchronous operations, files are processed using RSCS services. For non-PostScript (or, flat) files, only those with an LRECL of 1280 or less can be processed in this manner; there is no restriction for PostScript files.
10. Some LPDs require the FILTER l option — in addition to the BINARY option — to ensure the data file is not changed during BINARY transfers. With such implementations, the receiving LPD converts the incoming line-end character of X'0A' to two characters, X'0D0A', if the FILTER l option is omitted. (This situation has been observed when files are processed by an LPD on some DOS and OS/2 based systems; however, this behavior may not occur in all such environments.)
11. Remote printer hosts determine whether sufficient space is available to receive a given file before it is processed. If sufficient space is not available, the file is discarded and the connection is terminated with a message that identifies this error condition.
12. In most environments, the system defaults for asynchronous processing (that is, the default SERVER and RSCS linkid and nodeid values) should provide satisfactory results. Before setting non-default values for asynchronous processing, consult your RSCS operations support staff.
13. For most operations, LPR issues messages only if errors are encountered. To monitor the progress of an LPR command or to obtain information for diagnostic purposes, use the TYPE or TRACE options.