DEFINE PRINTER |
([logical-printer-name=]n) | |
[OUTPUT
operand1]
|
||
|
|
|
 |
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
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.
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:
| 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 The printer number n may be a value in the range of
0 - 31. This is the number also to be used in a Printer number 0 indicates the hardcopy printer. Some access methods do not
support the hardcopy printer, for example, |
logical-printer-name
|
Logical Printer Name:
Optionally you can assign a logical name
Naming conventions for
|
OUTPUT
operand1
|
Printer Name:
As
See also Printer Name for Additional Reports and Remote Destinations The 8-byte logical printer name can be defined initially by keyword
subparameter
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 keyword subparameter 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 You define the printer control characters table by the profile parameter
Note |
CODEPAGE operand2
|
Name of Codepage:
|
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
keyword subparameters of profile parameter PRINT. See PRINT
Keyword Subparameters for DEFINE PRINTER Statement in the
Parameter Reference.
When a printer is closed, all options are reset to their default values. If the
definitions are not clear in a Natural environment, it is recommended to set them in
each module using DEFINE PRINTER statement.
Syntax Element Description:
| Syntax Element | Description |
|---|---|
FORMS operand2
|
Form:
Maximum length of operand: 8 bytes. The default value of this clause can be set with subparameter |
NAME
operand2
|
Listname:
Maximum length of operand: 8 bytes. The default value of this clause can be set with subparameter |
DISP
operand2
|
Disposition:
Maximum length of operand: 4 bytes. For the The default value of this clause can be set with keyword subparameter
|
CLASS
operand2
|
Spool Class:
Maximum length of operand: 1 byte. The default value of this clause can be set with keyword subparameter
|
COPIES
operand3
|
Number of Copies:
The default value of this clause can be set with keyword subparameter
|
PRTY
operand4
|
Listing Priority:
Possible values: 1 - 255. The default value of this clause can be set with keyword subparameter
|
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
data set name to be assigned to that printer number.
operand1 can be 1 to 253 characters
long and can be one of the following:
a logical data set name (DD name, 1 to 8 characters);
a physical data set name of a cataloged data set (1 to 44 characters), or a physical data set member name (1 to 44 characters for the data set name, plus 1 to 8 characters in parentheses for the member name);
a path name and member name of an HFS file (1 to 253 characters) in an MVS Linux Services environment;
a JES spool file class;
NULLFILE (to indicate a dummy data set).
For example:
DEFINE PRINTER (21) OUTPUT 'SYSPRINT'
The specified data set with DD-name SYSPRINT must have been allocated
before the DEFINE PRINTER statement is executed. For further information,
see Allocation and De-Allocation of Data Sets.
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 data set name specified in the DEFINE PRINTER statement overrides the
name specified with the keyword subparameter DEST of profile
parameter PRINT.
Optionally, the data set 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'
For example:
DEFINE PRINTER (23) OUTPUT 'TEST.PRINT.FILE'
The specified data set must exist in cataloged form. When the DEFINE
PRINTER statement is executed, the data set is allocated dynamically by SVC 99
with the current DD-name and JCL option DISP=SHR. For further information,
see Allocation and De-Allocation of Data Sets.
If the data set 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 data set is a PDS member, you specify the PDS member name (1 to 8 characters) in parentheses after the data set 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.
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 data set, 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 keyword subparameter FREE of profile parameter PRINT).
To create a JES spool data set, 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.
To allocate a dummy data set, you specify NULLFILE as
operand1:
DEFINE PRINTER (n) OUTPUT 'NULLFILE
This corresponds to the JCL definition:
// DD-name DD DUMMY
When the DEFINE PRINTER statement is executed and a physical data set
name, HFS file, spool file class or dummy data set has been specified, the corresponding
data set is allocated dynamically. If the logical print file is already open, it will be
closed automatically, except when the keyword subparameter CLOSE=FIN (Time of
Closure) of profile parameter PRINT has been specified, in which case an error
will be issued. Moreover, an existing data set allocated with the same current DD-name
is automatically de-allocated before the new data set 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 keyword
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 keyword 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 data sets, the
application programming interface USR2021N in library SYSEXT
is provided. This API also allows you to specify additional parameters for dynamic
allocation.
In server environments, errors may occur if multiple Natural sessions attempt to
allocate or open a data set with the same DD-name. To avoid this, you either specify the
print file with keyword 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 data set 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.
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 keyword subparameter
TYPE of profile parameter PRINT for the printer. For
TYPE=TD (transient data), only the first 4 characters of
operand1 are honored 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).
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'
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.
For Natural Advanced Facilities users, the name of any predefined logical printer profile
can be specified. This logical printer profile needs 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 further information, see the Natural Advanced
Facilities documentation.
Additional reports and remote print destinations can be assigned by 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
|
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 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. |
You can use the write-to-spool file feature (see the Operations documentation) to route data through a remote JES node and send it to a user or print it on a device defined in the remote JES environment.
/* PRINTER NAME DEFINITION FOR COM-PLETE * DEFINE PRINTER (1) OUTPUT 'TID100' WRITE (1) 'PRINTED ON PRINTER TID100' END
/* 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 '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
EXECUTING DPIEX1 BY HTR Page 1 05-01-13 14:54:33 TEST OUTPUT
** 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
