SERVICE statement

Use the SERVICE statement to specify the name and Type of Service for the printers and punches used by the LPD server. This service name is used in the LPR command.

Requirement: The parameters shown on separate lines must be coded on separate lines. Follow the example in the sample configuration data set shown in Sample LPD server configuration data set (LPDDATA).

Syntax


>>-SERVICE--name--+-PRINTER-+--+-LOCAL--local_options-----+----->
                  +-RECFMU--+  +-NJE--nje_options---------+   
                  +-RECFMUA-+  '-REMOTE--+-printer@host-+-'   
                  +-PUNCH---+            '-EPORT--------'     
                  '-NONE----'                                 

   .---------------------------------------------------------------.   
   V                                                               |   
>----+-----------------------------------------------------------+-+-><
     +-EXIT--+-START-+--program----------------------------------+     
     |       '-END---'                                           |     
     +-FAILEDJOB--+-MAIL----+------------------------------------+     
     |            '-DISCARD-'                                    |     
     |          .----------.                                     |     
     |          V          |                                     |     
     +-FILTERS----+-f----+-+-------------------------------------+     
     |            +-l----+                                       |     
     |            +-lASf-+                                       |     
     |            +-p----+                                       |     
     |            '-r----'                                       |     
     | .-LINESIZE 132------.                                     |     
     +-+-------------------+-------------------------------------+     
     | '-LINESIZE --length-'                                     |     
     +-NLSTRANSLATE--... see separate diagram ...----------------+     
     | .-PAGESIZE 60------.                                      |     
     +-+------------------+--------------------------------------+     
     | '-PAGESIZE --lines-'                                      |     
     +-RACF------------------------------------------------------+     
     | .-SMTP SMTP---------------------------------------------. |     
     +-+-------------------------------------------------------+-+     
     | '-SMTP--server_name--+---------------+--+-------------+-' |     
     |                      '-CLASS=--class-'  '-DEST=--node-'   |     
     +-TRANSLATETABLE--name--------------------------------------+     
     '-XLATETABLE--name------------------------------------------'     

local_options

   .-CLASS=A or B--.                        
|--+---------------+--+-----------------+-----------------------|
   '-CLASS=--class-'  '-+-------------+-'   
                        '-OUTPUT=name-'     

nje_options

   .-CLASS=A or B--.  .-DEST=--local_node-.   
|--+---------------+--+-------------------+--------------------->
   '-CLASS=--class-'  '-DEST=--node-------'   

   .-IDENTIFIER=SYSTEM----.  .-PRIORITY=50---------.   
>--+----------------------+--+---------------------+------------>
   '-IDENTIFIER=--user_id-'  '-PRIORITY=--priority-'   

>--+-----------------+------------------------------------------|
   '-+-------------+-'   
     '-OUTPUT=name-'

Syntax


>>-NLSTRANSLATE--+-BIG5--+-------------------------+------+----><
                 |       '-(--+------------------+-'      |   
                 |            |       .-ASCII--. |        |   
                 |            '-SOSI--+--------+-'        |   
                 |                    +-EBCDIC-+          |   
                 |                    '-SPACE--'          |   
                 +-EUckanji--+-------------------------+--+   
                 |           '-(--+------------------+-'  |   
                 |                |       .-ASCII--. |    |   
                 |                '-SOSI--+--------+-'    |   
                 |                        +-EBCDIC-+      |   
                 |                        '-SPACE--'      |   
                 +-HAngeul--+-------------------------+---+   
                 |          '-(--+------------------+-'   |   
                 |               |       .-ASCII--. |     |   
                 |               '-SOSI--+--------+-'     |   
                 |                       +-EBCDIC-+       |   
                 |                       '-SPACE--'       |   
                 +-Ibmkanji-------------------------------+   
                 +-JIS78kj--+---------------------+-------+   
                 |          '-(--+--------------+-'       |   
                 |               | .-ASCII----. |         |   
                 |               '-+----------+-'         |   
                 |                 '-JISROMAN-'           |   
                 +-JIS83kj--+---------------------+-------+   
                 |          '-(--+--------------+-'       |   
                 |               | .-ASCII----. |         |   
                 |               '-+----------+-'         |   
                 |                 '-JISROMAN-'           |   
                 +-Ksc5601--+-------------------------+---+   
                 |          '-(--+------------------+-'   |   
                 |               |       .-ASCII--. |     |   
                 |               '-SOSI--+--------+-'     |   
                 |                       +-EBCDIC-+       |   
                 |                       '-SPACE--'       |   
                 +-SChinese--+-------------------------+--+   
                 |           '-(--+------------------+-'  |   
                 |                |       .-ASCII--. |    |   
                 |                '-SOSI--+--------+-'    |   
                 |                        +-EBCDIC-+      |   
                 |                        '-SPACE--'      |   
                 +-SJiskanji--+-------------------------+-+   
                 |            '-(--+------------------+-' |   
                 |                 |       .-ASCII--. |   |   
                 |                 '-SOSI--+--------+-'   |   
                 |                         +-EBCDIC-+     |   
                 |                         '-SPACE--'     |   
                 '-TChinese--+-------------------------+--'   
                             '-(--+------------------+-'      
                                  |       .-ASCII--. |        
                                  '-SOSI--+--------+-'        
                                          +-EBCDIC-+          
                                          '-SPACE--'

Parameters

name

The service name must be one to eight characters in length. This value is case sensitive.

Restriction: Only characters permitted in MVS™ data set names are valid.

PRINTER

Specifies the service is to a printer. For LOCAL or NJE devices, the JES spool file created is allocated with RECFM=UM and machine carriage control is written in column 1 of the file. For filter 1, this is always a single space ('09'X). For other filters, it is determined from the data received.

RECFMU

Specifies the service is to a printer. For LOCAL or NJE devices, the JES spool file created is allocated with RECFM=U and carriage control characters are not added to the beginning of each line. The JES spool file is like PRINTER, but carriage control is not added.

RECFMUA

Specifies the service is to a printer. For LOCAL or NJE devices, the JES spool file created is allocated with RECFM=UA. The carriage control (CC) character is taken from the first column of user data after any LPD processing.

Restriction: Only filter 1 should be allowed with this device type.

Specify filters 1 in the SERVICE statement so LPD does not print jobs requesting other filter options. The LPD trace would show message EZA0801I for these aborted jobs.

PUNCH

Specifies the service is to a punch device. For LOCAL or NJE devices, the JES spool file created is allocated with RECFM=UM and machine carriage control is written in column 1 of the file.

NONE

Specifies that the service is not currently in use.

LOCAL

Specifies that the data sets sent to a service are written to the local MVS printer or punch.

CLASS=class: The SYSOUT class. The default is A for printers and B for punches.
OUTPUT=name: Specifies the name of an OUTPUT DD statement that contains additional spool parameters.

NJE

Specifies that the data sets sent to a service are delivered to the NJE system.

CLASS=class: The SYSOUT class. The default is A for printers and B for punches.
DEST=node: The name of the NJE node. The default is the local node.
IDENTIFIER=user_id: The device user ID. The default is SYSTEM.
PRIORITY=priority: Specifies the transmission priority. The default is 50.
OUTPUT=name: Specifies the name of an OUTPUT DD statement that contains additional spool parameters.

REMOTE

Specifies that data sets (jobs) sent to this service queue are forwarded immediately to the specified remote printer. If the remote printer is not available, the job is discarded.

Guideline: If discarded jobs are a problem, consider sending the jobs directly to the final LPD with LPR, instead of using the MVS LPD as an intermediate router.

printer@host: The destination printer at a specified Internet host. This can be an Internet name or an IP address.
EPORT: For the Remote service, when LPR ports 721-731 are in use, LPD tries to use non-reserved ports in the 732 - 1 023 range. The default action, when EPORT is not specified, is to only use the ports 721 - 731 defined by RFC 1179.

EXIT

Specifies any program to be executed before closing, but after allocating and opening, an output data set.

START: Specifies that the program is invoked after allocating and opening the output data set, but before anything is written to the data set. This parameter is mutually exclusive of the END parameter.
END: Specifies that the program is invoked just before closing the output data set. This parameter is mutually exclusive of the START parameter.
program: Name of the program to be invoked. See z/OS Communications Server: IP Configuration Guide for information about using the default LPBANNER or creating your own banner program. The library containing the program should be in the system’s link list (LNKLSTxx), or a STEPLIB definition can be used if the library is APF authorized.

FAILEDJOB

Specifies whether a notice of failed jobs should be mailed to users or a job is discarded without notice.

MAIL: Specifies that notices of failed jobs are mailed to users.
Requirement: To use the MAIL parameter, you must also specify the SMTP parameter. Messages are logged in the LPD joblog, showing the information sent to SMTP.
DISCARD: Specifies that failed jobs are discarded without notice.

FILTERS

The control file received by LPD specifies the filter actually used. LPD formatting for each possible filter is described here. When lASf is specified, any filter l received is treated as filter f, described as follows:

f

Print formatted file paginates the data set at the size of the page given. It also truncates lines if they exceed a maximum length.

This filter causes the data file to be printed as a plain text file, providing page breaks as necessary.

Restriction: Only the following ASCII control characters are honored:

They are removed from the data stream (not printed) and changed into equivalent spacing and machine carriage control. Any ASCII code that translates to an EBCDIC NL is also honored. However, standard ASCII tables do not have an NL (new line) control character.

JES writers start each job on a new page. Therefore, LPD suppresses any FF (form feed) at the beginning of the data to avoid an extra page eject before the user's data set is printed.

l

Print file leaving control characters does not insert pagination but does truncate lines. All lines are single spaced.

This filter causes the specified data file to be printed without filtering out control characters (except LF, which is sed to determine line endings when converting to a JES record oriented spool file). Other ASCII control characters are translated to EBCDIC and printed as text. They arenot converted to equivalent machine carriage control. Use filter f to ontrol codes like FF and HT to be honored.

Filter l can behave like filter lASf if you specify lASf instead of l. See lASf below.

lASf

p - Print file with 'pr' format

Paginates data set, adding titles, the date, and page numbers as well as providing line truncation.

This filter causes the data file to be printed with a heading, page numbers, and pagination. Page breaks are determined by the PAGESIZE configuration on the SERVICE statement, or by ASCII FF (form feed) control characters in the data stream. PAGESIZE includes the title lines printed.

JES writers start each job on a new page. Therefore, LPD suppresses any FF (form feed) at the beginning of the data to avoid an extra page eject before the user's data set is printed.

r - File to print with FORTRAN carriage control

Prints the data set, interpreting the first column of each line as a FORTRAN carriage control. The FORTRAN controls are removed from the data stream and translated into equivalent machine carriage control. LPD honors " ", "1", "0", "+", and "-". Other values in column 1 cause single spacing. LPD also truncates lines if they exceed LINESIZE. Page breaks are determined by the PAGESIZE configuration as well as the Fortran controls in column 1.

LINESIZE

Specifies the line length used by the filters when they truncate lines. This statement only applies to services that are designated as either LOCAL or NJE on PAGESIZE (for example, 100 000).

length: The number of characters in a line on a page. Lines longer than this number are truncated. The default is 132.

PAGESIZE

Specifies the page length used by the filters when they paginate.

This statement only applies to services that are designated as either LOCAL or NJE.

lines: The number of lines on a page. The default is 60.

RACF®

Controls which users print data sets on this service.

SMTP

Specifies the SMTP server name, CLASS, and DEST options for sending failed jobs notices. For additional information, see the description of the FAILEDJOB MAIL parameter.

server_name: Specifies the name of the SMTP server. If this statement is omitted, the default is SMTP.
CLASS=class: The SYSOUT class. The default is A for printers and B for punches.
DEST=node: The NJE node to which SMTP messages should be sent.

TRANSLATETABLE

Specifies the translation table in the name.TCPXLBIN data set to be used by the client. XLATETABLE is a synonym for this parameter.

name

Specifies the SBCS translate table to be used when a client selects this SERVICE. The name parameter is preceded by either the job name or the hlq and followed by TCPXLBIN to form the data set name of the translate table (jobname.name.TCPXLBIN or hlq.name.TCPXLBIN). If both data sets exist, which one to use is determined by a search order hierarchy.

See z/OS Communications Server: IP Configuration Guide for more information about search order hierarchy, loading, and customizing of SBCS translation tables.

Tip: XLatetable is a synonym for this option.

XLATETABLE

Specifies the translation table in the name.TCPXLBIN data set to be used by the client. TRANSLATETABLE is a synonym for this parameter.

name

See z/OS Communications Server: IP Configuration Guide for more information about search order hierarchy, loading, and customizing of SBCS translation tables.

Tip: TRANslatetable is a synonym for this option.

NLSTRANSLATE

Specifies the DBCS translation type to be used when a client selects the named SERVICE.

BIG5: Select the translation type from Big-5 P-C DBCS codes to Traditional Chinese host codes.
EUckanji: Select the translation type from Japanese EUC DBCS codes to Japanese host codes.
HAngeul: Select the translation type from Korean PC DBCS codes to Korean host codes.
Ibmkanji: This option causes no conversion to be performed; in other words, data is sent to a printer without translation. Ibmkanji can be used for sending data in EBCDIC. If you select this option, be sure other printers on the same network are all configured with Ibmkanji.
JIS78kj: Select the translation type from JIS 1978 DBCS codes to Japanese host codes. The Escape Sequence, ESC 2/4 4/0, is used to express JIS X0208 1978.
JIS83kj: Select the translation type from JIS 1983 DBCS codes to Japanese host codes. The Escape Sequence, ESC 2/4 4/2, is used to express JIS X0208 1983.
Ksc5601: Select the translation type from IBM® KS DBCS codes to Korean host codes.
SChinese: Select the translation type from Simplified PC Chinese DBCS codes to Simplified Chinese host codes.
SJiskanji: Select the translation type from Shift JIS DBCS codes to Japanese host codes.
TChinese: Select the translation type from Traditional Chinese 5550 PC DBCS codes to Traditional Chinese host codes.
SOSI: Shift-Out and Shift-In characters X'1E' and X'1F' are used in data to delimit DBCS strings.
SOSI ASCII: Shift-Out and Shift-In characters X'1E' and X'1F' are used in data to delimit DBCS strings.
SOSI EBCDIC: Shift-Out and Shift-In characters X'0E' and X'0F' are used in data to delimit DBCS strings.
SOSI SPACE: Shift-Out and Shift-In characters X'20' and X'20' are used in data to delimit DBCS strings.
ASCII (with JIS78KJ and JIS83KJ only): The ASCII Escape Sequence, ESC 2/8 4/2, is used in data to express SBCS strings.
JISROMAN (with JIS78KJ and JIS83KJ only): The JISROMAN Escape Sequence, ESC 2/8 4/10, is used in data to express SBCS strings.

Examples

PRINTER and PUNCH definitions
The sample configuration data set SEZAINST(LPDDATA) provides examples of SERVICE statements for LOCAL, REMOTE, and NJE printers and a LOCAL punch.
EXIT Parameter
To make the LPBANNER program print a page at the beginning of the printed output, use the EXIT START parameter within a SERVICE statement, as shown here:
```
SERVICE locprt1 PRINTER
    LOCAL
    FILTERS f l p r
    LINESIZE 132
    PAGESIZE 60
    EXIT START LPBANNER
```
To make the LPBANNER program print a page at the end of the printed output, use the EXIT END parameter within a SERVICE statement, as shown here:
```
SERVICE locprt1 PRINTER
    LOCAL
    FILTERS f l p r
    LINESIZE 132
    PAGESIZE 60
    EXIT END LPBANNER
```
See RFC 1179, Section 7.5 Line Printer Daemon Protocol, for more information about the LPD user exit.

Usage notes

For remote printers, observe these guidelines:
Remote printers do not require specifications for EXIT, FAILEDJOB, FILTERS, LINESIZE, PAGESIZE, RACF, SMTP, and translation tables. These are defined on the remote system.
The LPR command must be specified with the printer name as it is specified on the SERVICE statement. The HOST parameter can HOSTNAME or the IP address of the host the LPD is running on, not the printer name and IP address of the remote printer.
```
LPR fn (p pebprt h LPDSrvHostName
```
This is required if you want to send data to the remote printer using this LPD.
With RACF, observe these guidelines:
In order to print data sets on a printer that has RACF specified, the user must use the JOB option with a valid password on the LPR command.

If the RACF keyword is specified for the service and a valid password is not supplied, the job sent to that service fails.

If a printer is defined as RACF for a local service on one system and as an NJE service on other systems, then you must specify the RACF keyword on the SERVICE statement on each of the systems where this service is defined.
For SMTP, observe these guidelines:
- SMTP is used in conjunction with the FAILEDJOB statement. If the MAIL keyword is used on the FAILEDJOB statement, then the SMTP server_name should be set to the name of the SMTP server and an optional CLASS and Destination NJE node.
- When an attempted print job fails and the MAIL keyword is used on the FAILEDJOB statement, then the LPD server sends a notice of the failure to the SMTP server. This notice is then forwarded to the user ID that submitted the print request.
For FAILEDJOB, observe these guidelines:
If the MAIL parameter is specified for any service, then the SMTP statement must be included in the LPD configuration data set.
For EXIT, observe these guidelines:
- If the job name is not specified on the corresponding LPR operation, JOB is the data set name that was printed by LPD.
- If CLASS is omitted on the LPR operation, it contains the sending system's host name.
- The following parameters are passed to the program but not defined in the EXIT statement.
  param1
  
  A pointer to a full word return code.
  
  param2
  
  A Pascal string containing the DD name of the spool file, the data set name of the control file, the printer name, and the total number of bytes in the print job. The first two bytes of the Pascal string are the number of bytes of character data starting at byte 3.
  
  param3
  
  A pointer to an open DCB for the JES spool file. The DCB is (DSORG=PS, MACRF=PL, RECFM=UM) for SERVICE printer or SERVICE PUNCH devices. THE DCB is (DSORG=PS, MACRF=PL, RECFM=U) for SERVICE RECFMU devices.