DEFINE PRINTER ([logical-printer-name=]n)
|
||||||
[OUTPUT
operand1]
|
||||||
|
|
|
|
|
|
 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
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:
| (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, e.g.
|
|---|---|
| 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
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 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
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
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
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 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
|
|---|---|
| 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 |
| CLASS operand2 |
Spool Class:
Maximum length of operand: 1 byte. The default value of this
clause can be set with subparameter
|
| COPIES operand3 |
Number of Copies:
operand3 must be an integer value. The
default value of this clause can be set with subparameter
|
| 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 |
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:
a logical dataset name (DD name, 1 to 8 characters);
a physical dataset name of a cataloged dataset (1 to 44 characters), or a physical dataset member name (1 to 44 characters for the dataset 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 UNIX Services environment;
a JES spool file class;
NULLFILE (to indicate a dummy dataset).
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'
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.
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).
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.
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
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.
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.
For a printer number that is defined with the access method
AM=STD,
operand1 can be:
a logical dataset name (DD-name, 1 to 7 characters);
NULLFILE (to indicate a dummy dataset).
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'
To allocate a dummy dataset, you specify NULLFILE as
operand1:
DEFINE PRINTER (n) OUTPUT 'NULLFILE
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:
Instead of dynamic allocation via MVS SVC 99, the CMS command
FILEDEF is used to define a dataset.
HFS files are not supported.
JES spool classes are not supported.
In addition, the following syntax is used:
DEFINE PRINTER (n) OUTPUT ('fname ftype fmode(options)')
This generates the CMS command:
FILEDEF ddname-n DISK fname ftype fmode (options)
Moreover, the following syntax is allowed:
DEFINE PRINTER (n) OUTPUT ('FILEDEF=filedef-parameters')
This generates the CMS command:
FILEDEF ddname-n =filedef-parameters
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:
*DUMMY
The following rules apply:
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.
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'
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
The following input is interpreted without considering the length and therefore forms exceptions to Rules 2 and 3:
keyword input: LINK=, FILE=
*DUMMY
NULLFILE (equivalent to *DUMMY)
*
*,*
SYSOUT
SYSLST or SYSLST(nn)
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.
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 |
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.
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'
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.
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.
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.
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.
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.
Example:
DEFINE PRINTER (14) OUTPUT 'SYSOUT'
Report 14 is written to SYSOUT.
Under TIAM: SYSOUT is by default output on the screen.
Example:
DEFINE PRINTER (15) OUTPUT 'SYSLST'
Report 15 is written to the system file SYSLST.
Example:
DEFINE PRINTER (16) OUTPUT 'SYSLST16'
Report 16 is written to the system file SYSLST16.
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.
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).
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 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.
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. |
/* 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