Version 4.2.6 for Mainframes (Update)
 —  Statements  —

DEFINE PRINTER

DEFINE PRINTER ([logical-printer-name=]n)  
    [OUTPUT operand1]              

PROFILE operand2
CODEPAGE operand2
FORMS operand2
NAME operand2
DISP operand2
CLASS operand2
COPIES operand3
PRTY operand4

8

This document covers the following topics:

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statements: AT END OF PAGE | AT TOP OF PAGE | CLOSE PRINTER | DISPLAY | EJECT | FORMAT | NEWPAGE | PRINT | SKIP | SUSPEND IDENTICAL SUPPRESS | WRITE | WRITE TITLE | WRITE TRAILER

Belongs to Function Group: Creation of Output Reports


Function

The DEFINE PRINTER statement is used to assign a symbolic name to a report number and to control the allocation of a report to a logical destination. This provides you with additional flexibility when creating output for various logical print queues.

When this statement is executed and the specified printer is already open, the statement will implicitly cause that printer to be closed. To explicitly close a printer, however, you should use the CLOSE PRINTER statement.

For further information on the DEFINE PRINTER statement, see Unicode and Code Page Support in the Natural Programming Language, section Statements.

Top of page

Syntax Description

Operand Definition Table:

Operand Possible Structure Possible Formats Referencing Permitted Dynamic Definition
operand1 C S       A U                       yes no
operand2 C S       A U                       yes no
operand3 C S           N                     yes no
operand4 C S           N P I                 yes no

Syntax Element Description:

(n)
Printer Number:

All print files to be used during a session must be preassigned to an access method by means of subparameter AM (Type of Access Method) of profile parameter PRINT or automatically by definition in the JCL (AM=STD only).

The printer number n may be a value in the range of 0 - 31. This is the number also to be used in a DISPLAY / WRITE or CLOSE PRINTER statement.

Printer number 0 indicates the hardcopy printer. Some access methods do not support the hardcopy printer, e.g. AM=PC.

logical-printer-name
Logical Printer Name:

Optionally you can assign a logical name logical-printer-name to printer n. This name can be used for the rep notation in a DISPLAY / WRITE statement.

Naming conventions for logical-printer-name are the same as for user-defined variables. Multiple logical names may be assigned to the same printer number. Unlike the value of the OUTPUT operand (see below), logical-printer-name is evaluated at compilation time and therefore independent of the program control flow.

OUTPUT operand1
Printer Name:

As operand1 you can specify the printer name within the online spooling system or the print file name to be assigned to the printer number or the name of an additional printer, see Printer Name for Additional Reports below. The 8-byte logical printer name can be defined initially by subparameter DEST of profile parameter PRINT. Its default value depends on the access method type and may be overwritten by operand1.

operand1 can be 1 to 253 characters long. If operand1 is a variable, its length must be at least 8 bytes. You can specify either a printer or a logical or physical dataset name. The possible format depends on the operating system environment and the access method defined by subparameter AM of profile parameter PRINT for this printer number.

If the specified name is already defined for a different printer number and this printer is unused; that is, in closed state, the print output will be routed to this printer if subparameter ROUTE=ON of profile parameter PRINT was specified for the specified printer number. If no printer name matches with operand1, the unused printer with the highest number is used and its name will be overwritten by operand1. Print routing is not visible to the user by means of the SYSFILE command.

Information on operating-system- or TP-monitor-dependent printer naming conventions is included in the following sections:

With the following clauses, you can provide printing control information to be interpreted by the spooling system of the TP monitor or operating system respectively. You can specify one or more of these clauses, but each of them only once.

PROFILE operand2
Name of Printer Control Characters Table:

With the PROFILE clause, you specify as operand2 the name of a printer control characters table. The maximum length allowed for operand2 is 8 bytes.

You define the printer control characters table by the profile parameter CCTAB (Printer Escape Sequence Definition).

Note:
With Natural Advanced Facilities, the printer control characters table table can be maintained online (as described in the Natural Advanced Facilities documentation).

CODEPAGE operand2
Name of Codepage:

CODEPAGE denotes the name (format/length: A64) of a codepage as specified in the NATCONFG module.

CODEPAGE is ignored if it does not apply to the respective OUTPUT destination.

Spooling System Parameters

With the following clauses, you can provide values for parameters of the TP monitor's spooling system. The default value of these clauses can be set with the corresponding subparameters of profile parameter PRINT (see PRINT Keyword Subparameters for DEFINE PRINTER Statement).

When a printer is closed, all options are reset to their default values. If the definitions are not clear in a Natural environment, Software AG recommends to set them in each module using DEFINE PRINTER statement.

FORMS operand2
Form:

Maximum length of operand: 8 bytes. The default value of this clause can be set with subparameter FORMS of profile parameter PRINT.

NAME operand2
Listname:

Maximum length of operand: 8 bytes. The default value of this clause can be set with subparameter NAME of profile parameter PRINT.

DISP operand2
Disposition:

Maximum length of operand: 4 bytes.

For the DISP clause, the possible values for operand2 are DEL, HOLD, KEEP and LEAV. The default value of this clause can be set with subparameter DISP of profile parameter PRINT. If the DISP clause is omitted (or incorrectly specified), DEL applies by default.

CLASS operand2
Spool Class:

Maximum length of operand: 1 byte. The default value of this clause can be set with subparameter CLASS of profile parameter PRINT.

COPIES operand3
Number of Copies:

operand3 must be an integer value. The default value of this clause can be set with subparameter COPIES of profile parameter PRINT.

PRTY operand4
Listing Priority:

Possible values: 1 - 255. operand4 must be an integer value. The default value of this clause can be set with subparameter PRTY of profile parameter PRINT.

Top of page

Printer Name under z/OS Batch, TSO and Server

This section covers the following topics:

For a printer number that is defined with access method AM=STD, you can use operand1 to specify a logical or a physical dataset name to be assigned to that printer number.

operand1 can be 1 to 253 characters long and can be one of the following:

Logical Dataset Names

For example:

DEFINE PRINTER (21) OUTPUT 'SYSPRINT'

The specified dataset with DD-name SYSPRINT must have been allocated before the DEFINE PRINTER statement is executed. For more information, see Allocation and De-Allocation of Datasets below.

The allocation can be done via JCL, CLIST (TSO) or dynamic allocation (SVC 99). For dynamic allocation you can use the application programming interface USR2021N in library SYSEXT.

The dataset name specified in the DEFINE PRINTER statement overrides the name specified with the subparameter DEST of profile parameter PRINT.

Optionally, the dataset name may be prefixed by DDN= to indicate that it is a DD-name and to avoid name conflicts with additional reports. For example:

DEFINE PRINTER (22) OUTPUT 'DDN=SOURCE'

Physical Dataset Names

For example:

DEFINE PRINTER (23) OUTPUT 'TEST.PRINT.FILE'

The specified dataset must exist in cataloged form. When the DEFINE PRINTER statement is executed, the dataset is allocated dynamically by SVC 99 with the current DD-name and option DISP=SHR. For more information, see Allocation and De-Allocation of Datasets below.

If the dataset name is 8 characters or shorter and does not contain a period (.), it might be misinterpreted as a DD-name. To avoid this, prefix the name with DSN=. For example:

DEFINE PRINTER (22) OUTPUT 'DSN=PRINTXYZ'

If the dataset is a PDS member, you specify the PDS member name (1 to 8 characters) in parentheses after the dataset name (1 to 44 characters). For example:

DEFINE PRINTER (4) OUTPUT 'TEST.PRINT.PDS(TEST1)'

If the specified member does not exist, a new member of that name will be created.

HFS File

For example:

DEFINE PRINTER (14) OUTPUT '/u/nat/rec/test.txt'

The specified path name must exist. When the DEFINE PRINTER statement is executed, the HFS file is allocated dynamically. If the specified member does not exist, a new member of that name will be created.

For the dynamic allocation of the dataset, the following z/OS path options are used:

PATHOPTS=(OCREAT,OTRUNC,ORDWR)
PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)
FILEDATA=TEXT

When an HFS file is closed, it is automatically de-allocated by z/OS (regardless of the setting of the subparameter FREE of profile parameter PRINT).

JES Spool File Class

To create a JES spool dataset, you specify SYSOUT=x (where x is the desired spool file class). For the default spool file class, you specify SYSOUT=*.

Examples:

DEFINE PRINTER (10) OUTPUT 'SYSOUT=A'
DEFINE PRINTER (12) OUTPUT 'SYSOUT=*'

To specify additional parameters for the dynamic allocation, use application programming interface USR2021N in library SYSEXT instead of the DEFINE PRINTER statement.

NULLFILE

To allocate a dummy dataset, you specify NULLFILE as operand1:

DEFINE PRINTER (n) OUTPUT 'NULLFILE

This corresponds to the JCL definition:

// DD-name DD DUMMY

Allocation and De-Allocation of Datasets

When the DEFINE PRINTER statement is executed and a physical dataset name, HFS file, spool file class or dummy dataset has been specified, the corresponding dataset is allocated dynamically. If the logical print file is already open, it will be closed automatically, except when the subparameter CLOSE=FIN (Time of Closure) of profile parameter PRINT has been specified, in which case an error will be issued. Moreover, an existing dataset allocated with the same current DD-name is automatically de-allocated before the new dataset is allocated.

To avoid unnecessary overhead by unsuccessful premature opening of print files not yet allocated at the start of the program, print files should be defined with the subparameter OPEN=ACC (open at first access) of profile parameter PRINT.

In the case of an HFS file, or a print file defined with the subparameter FREE=ON of profile parameter PRINT, the print file is automatically de-allocated as soon as it has been closed.

As an alternative for the dynamic allocation and de-allocation of datasets, the application programming interface USR2021N in library SYSEXT is provided. This API also allows you to specify additional parameters for dynamic allocation.

Print Files in Server Environments

In server environments, errors may occur if multiple Natural sessions attempt to allocate or open a dataset with the same DD-name. To avoid this, you either specify the print file with subparameter DEST=* of profile parameter PRINT, or you specify OUTPUT '*' in the DEFINE PRINTER statement; Natural then generates a unique DD-name at the physical dataset allocation when the first DEFINE PRINTER statement for that print file is executed.

All print files whose DD-names begin with CM are shared by all sessions in a server environment. A shared print file is opened by the first session, and is physically closed when the server is terminated. For further information, see the section Natural as a Server in the Operations documentation.

Top of page

Printer Name under z/VSE Batch

For a printer number that is defined with the access method AM=STD, operand1 can be:

Logical Dataset Names

Example:

DEFINE PRINTER (2) OUTPUT 'SYSOUT1'

The specified dataset SYSOUT1 must have been defined in the JCL or in the z/VSE standard or partition labels.

The dataset name specified in the DEFINE PRINTER statement overrides the name specified with the subparameter DEST of the PRINT profile parameter.

Optionally, the dataset name may be prefixed by DDN= to indicate that it is a DD-name. For example:

DEFINE PRINTER (5) OUTPUT 'DDN=MYPRINT'

NULLFILE

To allocate a dummy dataset, you specify NULLFILE as operand1:

DEFINE PRINTER (n) OUTPUT 'NULLFILE

Top of page

Printer Name under VM/CMS

For a printer number that is defined with the access method AM=STD, you can use operand1 to specify a logical or a physical dataset name to be assigned to that printer number.

For this, the same applies as under z/OS (see Printer Name under z/OS Batch, TSO and Server), but with the following differences:

Top of page

Printer Name under BS2000/OSD Batch and TIAM

For a printer number that is defined with the access method AM=STD, you can use operand1 to specify a file name, link name or system file that is allocated to this printer number.

In this case, operand1 can have a length of from 1 to 253 characters and one of the following meanings:

The following rules apply:

  1. File name and link name can be specified as positional parameters or keyword parameters. The corresponding keywords are FILE= and LINK=. Mixing positional and keyword parameters is allowed but not recommended.

  2. A string with a length of 1 to 8 characters without commas is interpreted as a link name. This notation is compatible with earlier versions of Natural. Example:

    DEFINE PRINTER (1) OUTPUT 'P01'

    The corresponding definition with a keyword parameter is:

    DEFINE PRINTER (1) OUTPUT 'LINK=P01'
  3. A string of of 9 to 54 characters without commas is interpreted as a file name. Example:

    DEFINE PRINTER (2) OUTPUT 'NATURAL31.TEST.PRINTER02'

    The corresponding definition with a keyword parameter is:

    DEFINE PRINTER (2) OUTPUT 'FILE=NATURAL31.TEST.PRINTER02
  4. The following input is interpreted without considering the length and therefore forms exceptions to Rules 2 and 3:

    Example: DEFINE PRINTER (7) OUTPUT 'FILE=Y' is a valid file allocation and not a link name, although the string of characters contains fewer than 9 characters.

  5. Generic file names are formed as follows:

    pnn.userid.tsn.date.time.number

    where

    nn is a report number
    userid is a Natural user-ID, 8 characters
    tsn is the BS2000/OSD TSN of the current task, 4 digits
    date is DDMMYYYY
    time is HHIISS
    number is a sequential number, 5 digits
  6. Generic link names are formed as follows:

    NPFnnnnn

    where nnnnn is a 5-digit number that is increased by one after every generation of a dynamic link name.

  7. Changing the file allocation for a printer number causes an implicit CLOSE of the print file allocated so far.

You are strongly recommended, in all cases except when you only specify a link name (for example: P01), to work with keyword parameters. This avoids conflicts of names with additional reports and is essential for file names with fewer than 9 characters.

Examples:

DEFINE PRINTER (1) OUTPUT 'LINK=SOURCE'
DEFINE PRINTER (1) OUTPUT 'FILE=SOURCE'
DEFINE PRINTER (1) OUTPUT 'SOURCE'

Link Name

Example:

DEFINE PRINTER (1) OUTPUT 'LINKP01'

means the same as

DEFINE PRINTER (1) OUTPUT 'LINK=LINKP01'

A file with the LINK LINKP01 must exist at runtime. This can be created either using JCL before starting Natural or by dynamic allocation from the current application. For dynamic allocation, the application programming interface USR2029 in the library can be used. If, before execution, the link was active as a destination to another file, for example: P01, this will be released or retained depending on the value of the subparameter FREE of profile parameter PRINT (possible values are ON and OFF). Release is done via an explicit RELEASE call to the BS2000/OSD command processor.

File Name

Example:

DEFINE PRINTER (2) OUTPUT 'NATURAL31.TEST.PRINTER02'

means the same as

DEFINE PRINTER (2) OUTPUT 'FILE=NATURAL31.TEST.PRINTER02'

The file specified in operand1 is set up using a FILE macro call and inherits the link name that was valid for the corresponding print file before execution of the DEFINE PRINTER statement.

Generic File Name

Example:

DEFINE PRINTER (21) OUTPUT '*'

means the same as

DEFINE PRINTER (21) OUTPUT 'FILE=*'

A file with a name created according to Rule 4 is set up using a FILE macro call and inherits the link name that was valid for the corresponding print file before execution of the DEFINE PRINTER statement.

DEFINE PRINTER (22) OUTPUT 'FILE=*,LINK=GENFLK22'

A file with a name created according to Rule 4 is set up with the specified link name using a FILE macro call.

File Name and Link Name

Example:

DEFINE PRINTER (11) OUTPUT 'NATURAL31.TEST.PRINTER11,LNKP11'

means the same as

DEFINE PRINTER (11) OUTPUT 'FILE=NATURAL31.TEST.PRINTER11,LINK=LNKP11'

which means the same as

DEFINE PRINTER (11) OUTPUT 'FILE=NATURAL31.TEST.PRINTER11,LNKP11'

The file specified in operand1 is set up with the specified link name using a FILE macro call and allocated to the corresponding printer number.

Generic File Name and Link Name

Example:

DEFINE PRINTER (27) OUTPUT '*,*'

means the same as

DEFINE PRINTER (27) OUTPUT 'FILE=*,LINK=*'

A file with a file name and link name created according to Rule 4 and Rule 5 is set up using a FILE macro call and allocated to the specified printer number (27).

Note:
When file name and link name are specified, the previous link name is not released, regardless of the value of subparameter FREE of profile parameter PRINT.

System File SYSOUT

Example:

DEFINE PRINTER (14) OUTPUT 'SYSOUT'

Report 14 is written to SYSOUT.

Under TIAM: SYSOUT is by default output on the screen.

System File SYSLST

Example:

DEFINE PRINTER (15) OUTPUT 'SYSLST'

Report 15 is written to the system file SYSLST.

System File SYSLSTnn - nn=01,...,99

Example:

DEFINE PRINTER (16) OUTPUT 'SYSLST16'

Report 16 is written to the system file SYSLST16.

System File SYSLSTnn with Implicit Allocation

Examples:

DEFINE PRINTER (11) OUTPUT 'SYSLST=LST.PRINTER11'

The system file SYSLST is allocated to the file LST.PRINTER11; Report 11 is written to the system file SYSLST.

DEFINE PRINTER (13) OUTPUT 'SYSLST13=LST.PRINTER13'

The system file SYSLST13 is allocated to the file LST.PRINTER13; Report 13 is written to the system file SYSLST13.

DEFINE PRINTER (19) OUTPUT 'SYSLST19=*'

The system file SYSLST19 is allocated to a file with a name generated according to Rule 4; Report 19 is written to the system file SYSLST19.

Top of page

Printer Name under CICS

For a printer number defined with the access method AM=CICS, operand1 can be a transient data or temporary storage queue name (1 to 8 characters), depending on subparameter TYPE of profile parameter PRINT for the printer. For TYPE=TD (transient data), only the first 4 characters of operand1 are honoured and the transient data destination must be predefined to CICS.

For further information, see also Natural Print and Work Files under CICS (in the TP Monitor Interfaces documentation).

Top of page

Printer Name under Com-plete

With AM=COMP, a valid printer number (TID) or a logical printer name can be assigned. For example:

DEFINE PRINTER (1) OUTPUT '11'
DEFINE PRINTER (2) OUTPUT 'P102'

Top of page

Printer Name under Com-plete/SMARTS

With AM=SMARTS, any printer name can be assigned. For example:

DEFINE PRINTER (14) OUTPUT '/nat/path/printer'
DEFINE PRINTER (14) OUTPUT '/nat/path/printer/file/'
DEFINE PRINTER (14) OUTPUT 'printer'

It depends on the MOUNT_FS parameter of SMARTS whether the file is located on a SMARTS portable file system or on the native file system. The first element of the path (/nat/) determines the target file system.

If the string is terminated with a slash (/), the last element is taken as the name of the print file. Otherwise, the name of the file is generated from the UserID and a sequence number. If the string does not start with a slash, the path of the file is taken from the environment variable $NAT_PRINT_ROOT.

The specified path name must exist. When the DEFINE PRINTER statement is executed, the file is allocated dynamically. If the specified member does not exist, a new member of that name will be created.

Top of page

Printer Names under Natural Advanced Facilities

For Natural Advanced Facilities users, the name of any predefined logical printer profile can be specified. This logical printer profile need not belong to the currently active user profile. It may be any logical printer profile defined on the NATSPOOL file. It will be active only for the duration of the Natural program which contains the DEFINE PRINTER statement. For more information, see the Natural Advanced Facilities documentation.

Top of page

Printer Name for Additional Reports

Additional reports can be assigned for default with the following names:

Report Function
BROADCST Output message line to a TP monitor terminal. Same function as MESSAGE (see below), except that under Com-plete, the message is not sent to the desired terminal until no transactions are active on that terminal.
CCONTROL CCONTROL is the name of a special printer control table associated to the printer n-1; it must not be modified. For further information, refer to Printer-Advance Control Characters (in the Operations documentation).
CONNECT Output into a Con-nect folder.

Note for Natural installation: The NATPCNT module of Natural must be linked to the Natural nucleus.

DUMMY Output to be deleted.
HARDCOPY Output to the current hardcopy device.
INCORE Output into the NSPF incore database.
INFOLINE Output to the Natural infoline. For details on the infoline, see the Natural terminal command %X.
MESSAGE Output message line to a TP monitor terminal. The first 8 bytes of a message must contain the target terminal ID. TSO and CMS require the user ID instead of the terminal ID. An example program MSGSW is supplied in the library SYSEXTP.
SOURCE Output to the Natural source area.
WORKPOOL Output into the Natural ISPF workpool.

Top of page

Examples

Example 1 - Printer Name Definition for Com-plete

/* PRINTER NAME DEFINITION FOR COM-PLETE
*
DEFINE PRINTER (1) OUTPUT 'TID100'
WRITE (1) 'PRINTED ON PRINTER TID100'  
END

Example 2 - Printer Name Definition for Batch Environment

/* OUTPUT ON 'SYSPRINT' (FOR BATCH ENVIRONMENTS)
*
DEFINE PRINTER (REPORT1 = 1) OUTPUT 'SYSPRINT'
WRITE (REPORT1) 'REPORT 1 PRINTED ON PRINTER SYSPRINT'  
*
/* OUTPUT TO DEFAULT PRINTER DESTINATION
/* DEFINED WITH PROFILE PARAMETER 'PRINT', SUBPARAMETER 'DEST'
*
DEFINE PRINTER (REPORT2 = 2)
WRITE (REPORT2) 'REPORT PRINTED TO DESTINATION'

Example 3 - Print Output to Infoline

** Example 'DPIEX1': DEFINE PRINTER                                     
************************************************************************
*                                                                       
SET CONTROL 'XI+'        /* SWITCH INFOLINE MODE ON                     
SET CONTROL 'XT'         /* INFOLINE TOP                                
*                                                                       
DEFINE PRINTER (1) OUTPUT 'INFOLINE'                                   
WRITE (1) 'EXECUTING' *PROGRAM 'BY' *INIT-USER                          
WRITE 'TEST OUTPUT'                                                     
EJECT                    /* FORCE PHYSICAL I/O                          
*                                                                       
SET CONTROL 'X'          /* SWITCH BACK TO NORMAL                       
*                                                                       
END

Output of Program DPIEX1:

EXECUTING DPIEX1   BY HTR                                                      
Page      1                                                  05-01-13  14:54:33                                                                           
TEST OUTPUT                                                                   

Example 4 - Using a Session with Predefined Printer

** Example 'DPREX1': DEFINE PRINTER                                     
************************************************************************
DEFINE DATA LOCAL                                                       
1 EMPL-VIEW VIEW OF EMPLOYEES                                           
  2 NAME                                                                
END-DEFINE                                                              
*                                                                       
*  USE SESSION WITH DEFINED PRINTER 1                                   
*                                                                       
DEFINE PRINTER (INVOICE-LIST=1) OUTPUT 'OUTQ1'                         
LIMIT 5                                                                 
READ EMPL-VIEW BY NAME                                                  
  WRITE (INVOICE-LIST) NAME                                             
END-READ                                                                
*                                                                       
END                                                                    

Top of page