DEFINE PRINTER

#### Search Results

Search

# 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 |

This document covers the following topics:

- Function

- Syntax Description

- Printer Name under z/OS Batch, TSO and Server

- Printer Name under CICS

- Printer Name under Com-plete

- Printer Name under Com-plete/SMARTS

- Printer Names under Natural Advanced Facilities

- Printer Name for Additional Reports and Remote Destinations

- Examples

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.

## 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:

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 (with `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, for example, `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 compile time and therefore independent of the program control flow.
`OUTPUT operand1` | Printer Name: As `operand1` you can specify one of the following: the printer name within the online spooling system, the print file name to be assigned to the printer number, the name of an additional printer, or a remote JES printer. See also Printer Name for Additional Reports and Remote Destinations The 8-byte logical printer name can be defined initially by keyword 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 data set name. The possible format depends on the operating system environment and the access method defined by keyword 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 keyword 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: Printer Name under z/OS Batch, TSO and Server Printer Name under CICS Printer Name under Com-plete Printer Name under Com-plete/SMARTS Printer Name under Natural Advanced Facilities Printer Name for Additional Reports and Remote Destinations
| 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 the name of a printer control characters table as `operand2`. The maximum length 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 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 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, Software AG recommends 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 `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 keyword 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 keyword 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 keyword 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 keyword subparameter `PRTY` of profile parameter `PRINT`.

## Printer Name under z/OS Batch, TSO and Server

This section covers the following topics:

- Logical Data Set Names

- Physical Data Set Names

- HFS File

- JES Spool File Class

- NULLFILE

- Allocation and De-Allocation of Data Sets

- Print Files in Server Environments

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).

### Logical Data Set Names

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'

### Physical Data Set Names

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.

### 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 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`).

### JES Spool File Class

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.

### NULLFILE

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

### Allocation and De-Allocation of Data Sets

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.

### Print Files in Server Environments

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.

## 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 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).

## 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'

## 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.

## 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 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.

## Printer Name for Additional Reports and Remote Destinations

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 `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 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.

#### Printing Data in a Remote JES Environment

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.

## Examples

- Example 1 - Printer Name Definition for Com-plete

- Example 2 - Printer Name Definition for Batch Environment

- Example 3 - Print Output to Infoline

- Example 4 - Using a Session with Predefined Printer

### 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

### On this page

- Function
- Syntax Description
- Printer Name under z/OS Batch, TSO and Server
- Printer Name under CICS
- Printer Name under Com-plete
- Printer Name under Com-plete/SMARTS
- Printer Names under Natural Advanced Facilities
- Printer Name for Additional Reports and Remote Destinations
- Examples