DTFPR (Define the File for Printer) Macro

This operand is used together with the FUNC operand to define associated files for the IBM® 3525. For a discussion of associated files, refer to the z/VSE System Macros User's Guide Using z/VSE Macro Support.

The operand specifies the file name of an associated read and punch file, or both. The specification enables macro sequence checking by the logic module of each associated file. One file name is required per DTF for associated files.

Table 1 shows which file name is to be specified by the ASOCFLE operand for each of the associated DTFs.

This operand specifies the length of IOAREA1. The maximum values, which can be specified in this operand and the lengths assumed when it is omitted are given for the different devices in Table 1.

The actual size of the block might exceed the maximum length given in Table 1, if the following is true:

Your DTFPR includes CTLCHR=YES or ASA.
The control character of your record is X'5A' to indicate that this is a composed page data stream (CPDS) record.
The specified record format is VARUNB (for variable unblocked) or UNDEF (for undefined).

Data with a control character of X'5A' can have a length of up to 32 767 bytes.

Table 1. Maximum and Assumed Lengths for IOAREA1 in Number of Bytes
IBM Device	Maximum Length (See Note 1)	Assumed Length (See Note 2)
PRT1	512	121
1403-2	132	121
1403-3	132	121
1403-6	120	121
1403-7	120	121
1403-8	132	121
1403-9	132	121
3203	132	121
3525	64	64
3800/3200 with TRC=NO	384	136
3800 with TRC=YES	385	137

Note:

RECFORM is FIXUNB or UNDEF and operand CTLCHR is not specified. If the CTLCHR operand is specified, add 1 byte to the maximum value. Add 4 bytes to the maximum value if RECFORM=VARUNB is specified.
The operand BLKSIZE=n is omitted.

This operand should be specified, if the CNTRL macro is issued for the file. You can omit this operand if:

Your CNTRL macros request immediate printer operations only, and
The device being used is a PRT1 printer or an IBM 4248.

Examples of immediate printer operations are: immediate space or skip; enable or disable horizontal copying.

Specify this operand if first-character control is used. CTLCHR=YES specifies the S/370 character set (see Control Character Codes for a list of codes).

CTLCHR=ASA specifies the American National Standards Institute, Inc. character set. As an addition to the ASA character set, X'5A' indicating a 'composed page data stream' (CPDS) record is accepted as a valid ASA character.

If this operand is specified, omit CONTROL.

If CTLCHR=ASA is specified for a file on the IBM 3525, the + character is not allowed. To print on the first line of a card, you must issue either a space 1 command or a skip to channel 1 command. For a print associated file on the IBM 3525, you must issue a space 1 command to print on the first line of a card.

This operand specifies the symbolic unit to be associated with the printer. SYSLOG and SYSLST must not be specified for the IBM 3525.

This operand specifies the type of IBM device that is used for the file. Specify one of the following type codes:

PRT1
1403
1443
3203
3211
3525
3800

PRT1 refers to a 3211 or 3211-compatible IBM printer as listed in the device type codes table in Using Commands; it refers also to an IBM 4248 printer operating in native mode. Change your specification (in an existing program) to PRT1 if you want your program to:

Direct its print output to an IBM 4248.
Make use of certain IBM 4248 specific functions.

Reassemble and relink the program after this change.

This operand specifies the action to be taken in the case of an equipment error. The actions that you can specify are described below:

ERROPT=RETRY

Applies only, if you also specify DEVICE=PRT1.

RETRY indicates that, if an equipment check with command retry is encountered, the command is retried once. If the retry is unsuccessful, a message is issued and the job is canceled.

ERROPT=IGNORE

Can be specified only for the 3525. IGNORE indicates that the error is to be ignored. The address of the record in error is put in register 1 and made available for processing. Byte 3, bit 3 of the CCB is also set on (see CB Byte 3 Bit 3); you can check this bit and take the appropriate action to recover from the error. IGNORE must not be specified for files with two I/O areas or a work area.

ERROPT=name

Applies only, if you also specify DEVICE=PRT1.

If an equipment check with command retry is encountered, the command is retried once. If the retry is unsuccessful a message is issued and the job canceled.

For other types of errors (for these, see CCB Communication Bytes), IOCS:

Issues an error message.
Places error information into the CCB.
Returns control to your error routine.

In your routine, you can perform whatever actions are wanted, but you should not issue any imperative macro instruction for the file invoking the error exit. The routine always gets control in 24-bit addressing mode.

To continue processing at the end of the routine, return to IOCS by branching to the address in register 14.

This operand specifies the type of file to be processed by the IBM 3525.

W indicates print, R indicates read, P indicates punch, and T (for the 3525 only) indicates an optional 2-line printer.

RW|RWT|RPW|RPWT, and PW|PWT are used, together with the ASOCFLE operand, to specify associated files; when one of these specifications (without T) is used for a printer file, it must be specified also for the associated files.

Note: Do not use T for associated files, it is valid only for printer files.

If a 2-line printer is not specified for the 3525, multi-line print is assumed. T is ignored if CONTROL or CTLCHR is specified.

This operand specifies the name of the output area.

This operand specifies the name of a second output area.

If two output areas and no work areas are used, this operand specifies the register into which IOCS places the address of the area where you can build a record. For (r) specify one of the registers 2 to 12.

This operand can be used to specify the name of the logic module that is used with the DTF table to process the file. If the logic module is assembled with the program, MODNAME must specify the same name as the PRMOD macro. If this operand is omitted, standard names are generated for calling the logic module. If two DTF macros call for different functions that can be handled by a single module, only one module is called.

The module that is specified by this operand is ignored if the actual IBM device is one of the following:

PRT1 printer
4248 printer operating in native mode
3800 printer

OPEN always provides an IBM-supplied logic module for these devices.

This operand is specified if the PRTOV macro is included in your program.

This operand is specified if the DTF is used with a read-only module. Each time a read-only module is entered, register 13 must contain the address of a 72-byte doubleword-aligned save area. Every task requires its own uniquely defined save area. Each time an imperative macro (except OPEN or OPENR) is issued, register 13 must contain the address of the save area that is associated with the task. Because the save area is unique for each task, the module is reentrant; that is, capable of being used concurrently by several tasks.

If an ERROPT routine issues I/O macros, which use the same read-only module that caused control to pass to either error routine, your program must provide another save area. One save area is used for the normal I/O, and the second for I/O operations in the ERROPT routine. Before returning to the module that entered the ERROPT routine, register 13 must be set to the save area address that is originally specified for the task.

If this operand is omitted, the module that is generated is not reenterable and no save area need be established.

The operand RECFORM=FIXUNB is specified whenever the record format is fixed. When the record format is FIXUNB, this entry can be omitted.

The entry RECFORM=UNDEF is specified whenever the record format is undefined. If the output is variable and unblocked, enter VARUNB.

This operand specifies the general register (any one of 2 to 12) that contains the length of an output record of undefined format. The length of every record must be loaded into the register before issuing the PUT macro.

Include this operand only if the DTFPR macro is to be assembled separately. This produces an object module ready to be cataloged into a suitable sublibrary by the name you used as file name. The name is used as the module 's transfer address. If you omit the operand, the assembler assumes that the DTFPR macro is assembled with your program.

Include this operand if the selective tape listing feature (IBM 1403 only) is used. If this entry is specified, the CONTROL, CTLCHR, and PRINTOV entries are not valid and are ignored if specified. If you specify this operand, you must specify also RECFORM=FIXUNB.

This operand applies if DEVICE=3800 is specified. Specify TRC=YES if each output data line includes a table reference character following the optional print control character. The printer uses the table reference character to select the character arrangement table corresponding to the order in which the table names were specified (in the CHAR operand of the SETPRT job control statement or a SETPRT macro).

If a device code other than a 3800 is specified in the DEVICE operand, any table reference character sent to that printer is treated as data.

For a printer with the universal character set feature, or for a 3800, this operand determines whether data checks occurring in case of unprintable characters are indicated to the operator or printed as blanks. The operand is especially useful if you are using first-character forms control and have modules that cannot process the CNTRL macro. If the operand is omitted, OFF is the default.

ON: Data checks are processed with an operator indication.
OFF: Data checks are ignored and blanks are printed for the unprintable character.

If output records are processed in work areas instead of in the I/O areas, specify this operand. You must set up the work area in storage. The address of the work area, or a general-purpose register, which contains the address, must be specified in each PUT macro.

DTFPR (Define the File for Printer) Macro

Format

Requirements for the caller

Parameters