DTFPH (Define the File for Physical I/O) Macro

Format

Requirements for the caller

RMODE:

24

Parameters

Table 1 shows, which of the DTFPH entries can or must be coded to define a checkpoint file on disk.

ASCII=YES

This operand is required to process ASCII tape files (see American National Standard Code for Information Interchange). If this operand is omitted, EBCDIC processing is assumed.

CCWADDR=name

This operand allows you to use the CCB generated within the first 16 bytes of the DTFPH table. CCWADDR specifies the symbolic name of the first CCW used with the CCB generated within the DTFPH macro. This name must be the same as the name specified in the assembler CCW statement that defines the CCW.

If you omit the operand, the location counter value of the CCB-CCW table address constant is substituted for the CCW address.

CISIZE=n

This operand specifies the FBA control-interval size. The value n must be an integral multiple of the FBA physical block size and, if greater than 8 K, must be a multiple of 2 K. The maximum value is 32 768 (32 K) except when assigned to SYSLST or SYSPCH, when the maximum is 30 720 (30 K).

If CISIZE is omitted, CISIZE=0 is assumed. For an output file on an FBA device, the control-interval size can be overridden at the time of program execution. You do this by specifying the CISIZE operand of the DLBL job control statement. For an input file, the CISIZE value in the format-1 label is used.

DEVADDR=SYSxxx

This operand must specify the logical unit (SYSxxx) associated with the file if a logical unit is not provided via an EXTENT job control statement. If a logical unit is provided, its specification overrides a DEVADDR specification. This specification, or logical unit, represents an actual I/O address, and is used in the ASSGN job control statement to assign the actual I/O device address to this file.

If SYSLST or SYSPCH are used as output tape units and alternate tape switching is wanted upon detecting a reflective spot, the SEOV macro must be used (see SEOV (System End-of-Volume) Macro). When processing ASCII tape files, the only valid specification is a programmer logical unit (that is, SYSnnn).

DEVICE=TAPE | xxxx

Code the proper device identification, which can be one of the following:

TAPE

If the file resides on a tape that is mounted on an IBM® tape drive that is supported by z/VSE. For an ASCII file, TAPE is the only valid specification in this operand. TAPE is the default if you omit the operand.

DISK

If the file can reside on a disk of any type, CKD or FBA. If you specify DISK, IOCS determines the disk device type when the file is opened.

nnnn

Which is a disk device-type code.

There is no need for you to specify a disk device type code; specify DEVICE=DISK instead. The assembler accepts the following type specification:

  3380

EOXPTR=pointer

This operand is valid only if TYPEFLE=OUTPUT and MOUNTED=SINGLE is specified.

The operand points to a 4-byte field that contains the address of your end-of-extent exit routine. The routine receives control if, during OPEN processing for an output file, IOCS cannot find an additional extent. The routine always gets control in 24-bit addressing mode.

On entry to the exit routine, register 15 is set to zero.

HDRINFO=YES

This operand causes IOCS to print standard header label information (fields 3-10) on SYSLOG each time a file with standard labels is opened. Likewise, the file name, symbolic unit, and device address are printed each time an end-of-volume condition is detected. If HDRINFO=YES is omitted, no header or end-of-volume information is printed.

LABADDR=name

You might require one or more disk or tape labels in addition to the standard file labels. If so, you must include your own routine to check (on input) or build (on output) your labels. Specify the symbolic name of your routine in this operand. IOCS branches to this routine after the standard label is processed. The routine always gets control in 24-bit addressing mode.

LABADDR can be included to specify a routine for your header or trailer labels as follows:

• Disk input or output: header labels only.
• Tape input or output: header and trailer labels.

Thus, if LABADDR is specified, your header labels can be processed for an input/output disk or tape file, and your trailer labels can be built for a tape output file. Physical IOCS reads input labels and makes them available to you for checking; it writes output labels after they are built. This is similar to the functions performed by logical IOCS.

If physical IOCS macros are used for a tape file, an OPEN must be issued for the new volume. This causes IOCS to check the HDR1 label and provides for your checking of user standard labels, if any.

When physical IOCS macros are used and DTFPH is specified for standard tape label processing, FEOV must not be issued for an input file.

For more information about the handling of user labels, see the section Processing of User Labels.

MOUNTED=ALL | SINGLE

This operand must be included to specify how many extents (areas) of the file are available for processing when the file is initially opened. This operand must not be specified for tape.

Specify ALL if all extents are available for processing. When a file is opened, IOCS checks all labels on each disk pack and makes available all extents that are specified by your control statements. Only one OPEN is required for the file. ALL should be specified whenever you plan to process records in a manner similar to the direct access method.

After an OPEN is performed, you must be aware that the symbolic unit address of the first volume containing the file is in bytes 30 and 31 of the DTFPH table rather than in the CCB. Therefore, place this symbolic address into bytes 6 and 7 of the associated CCB before you issue an EXCP against this CCB in your program.

Specify SINGLE if only the first extent on the first volume is available for processing. SINGLE should be specified when you plan to process records in sequential order. IOCS checks the labels on the first pack and makes the first extent that is specified by your control statements available for processing. You must keep track of the extents and issue a subsequent OPEN whenever another extent is required for processing. The information in the DTFPH table is helpful in keeping track of the extents.

The contents of the table are:

Bytes

Contents

0-15

CCB (symbolic unit has been initialized in the CCB).

54-57

Upper extent limits (cchh).

For an FBA disk, the extent upper limit is the number of the first block of the last CI. If the number of blocks per CI is greater than 1, the upper extent limit can differ from the format-1 label and your specification in the DTFPH macro.

58-59

Seek address. For a disk it must be zero.

60-63

Lower extent limit (cchh for CKD).

On each OPEN after the first, IOCS makes available the next extent that is specified by the control cards. When you issue a CLOSE for an output file, the volume on which you are currently writing records is indicated, in the file label, as the last volume for the file.

TYPEFLE=INPUT | OUTPUT

This operand must be included to specify the type of file: input or output.

XTNTXIT=name

Include this operand, if you want to process label extent information. It specifies the symbolic name of your extent routine. The DTFPH operand MOUNTED=ALL must also be specified for the file. The routine always gets control in 24-bit addressing mode.

Whenever XTNTXIT is included, IOCS branches to your routine during the initial OPEN for the file. It branches after each specified extent is completely checked and after conflicts, if any, have been resolved.

When your routine receives control, register 1 contains the address of a 14-byte area from which you can retrieve label extent information (in binary form). The layout of this area is:

Bytes

Contents

0

Extent type code.

1

Extent sequence number.

2-5

Lower limit of the extent.

6-9

Upper limit of the extent.

10-11

Symbolic unit.

12

Set to zero.

13

Reserved.

Return to IOCS using the LBRET macro.