DTFDA (Define the File for Direct Access) Macro

Format

Requirements for the caller

RMODE:

24

Parameters

AFTER=YES

This operand must be included for output files if any records (or an additional record) are written in a file by a formatting WRITE (count, key, and data) following the last record that is previously written on a track. The remainder of the track is erased. That is, whenever either of the macros

• WRITE filename,AFTER
• WRITE filename,RZERO

is used in a program, this operand is required.

BLKSIZE=n

This operand indicates the size of the I/O area by specifying the maximum number of characters that are transferred to or from the area at any one time. When undefined, variable length or spanned records are read or written, the area must be large enough to accommodate the largest record. The Using z/VSE Macro Support describes how to compute the size of an I/O area.

IOCS uses this specification to set up the count field of the CCW for reading or writing records.

CONTROL=YES

Include this operand if a CNTRL macro is issued for this file. The CNTRL macro for seeking on a disk allows you to specify a track address on which access movement should begin for the next READ or WRITE macro. While the arm is moving, you can process data and request I/O operations on other devices.

DEVADDR=SYSnnn

This operand must specify the symbolic unit (SYSnnn) associated with a file if the symbolic unit is not provided via an EXTENT job control statement. If such a unit is provided, its specification overrides the DEVADDR specification. This specification, or symbolic 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 the file.

Note: EXTENT job control statements that are provided for DAM must be supplied in ascending order, and the symbolic units for multi-volume files must be assigned in consecutive order.

DSKXTNT=n

This operand indicates the maximum number of extents (up to 256) that are specified for a file. When this operand is used together with FIXUNB, VARUNB, or UNDEF specified in the RECFORM operand, it indicates that a relative ID is used in the SEEKADR and IDLOC locations. If DSKXTNT=n is omitted, a physical ID is assumed in the SEEKADR and IDLOC locations.

If RECFORM=SPNUNB is specified, DSKXTNT is required. If relative addressing is used, the RELTYPE operand must also be specified.

ERRBYTE=name

This operand is required. It specifies the name of a 2-byte field in which IOCS stores an error-condition or status code. For description of these codes, refer to the z/VSE System Macros User's GuideUsing z/VSE Macro Support .

ERREXT=YES

This operand enables irrecoverable I/O errors (occurring before a data transfer takes place) to be indicated to your program. This error information is indicated in the bytes named in the ERRBYTE operand and is available after the WAITF macro has been issued.

FEOVD=YES

This operand is specified if code is generated to handle end-of-volume records. It should be specified only when reading a file, which was built using DTFSD and the FEOVD macro.

HOLD=YES

This operand provides for the track hold function, which is to be specified at system generation time. If the operand is omitted, the track hold function is not performed. For details, refer to the z/VSE System Macros User's GuideUsing z/VSE Macro Support.

IDLOC=name

Include this operand if you want IOCS to supply the ID of a record after each READ or WRITE (ID or KEY) is completed. Specify the name of a record reference field in which IOCS is to store the ID. WAITF should be used before referencing this field. Do not specify the same field for IDLOC and SEEKADR.

Note: If the record to be read or written is the last record of the cylinder, an end-of-cylinder indication is posted in ERRBYTE1, bit 2, but the address that is returned is that of the first record of the next cylinder. If, in addition, the end-of-volume indication is posted, the address that is returned in IDLOC is all 1 bits.

IOAREA1=name

This operand must be included. It specifies the name of the input/output area that is used for the file. IOCS routines transfer records to or from this area. The specified name must be the same as the name used in the DS instruction that reserves this area of storage.

KEYARG=name

This operand must be included if records are identified by key; that is, if either of the macros

• READ filename,KEY
• WRITE filename,KEY

is used in a program, this entry, and the corresponding KEYLEN operand are required. KEYARG specifies the name of the key field in which you supply the record key to IOCS.

The KEYARG operand is required for formatting WRITE (WRITE filename,AFTER) operations for files containing keys, if RECFORM=VARUNB or SPNUNB. It is required also when the macro

  READ filename,ID

is specified and if KEYLEN is not zero. When record reference is by key, IOCS uses this specification at assembly time to set up the data address field of the CCW for search commands.

KEYLEN=n

This operand must be included if record reference is by key or if keys are read or written. It specifies the number of bytes in each key. All keys must have the same length. If this operand is omitted, IOCS assumes a key length of zero.

If there are keys that are recorded on disk and this entry is absent, a WRITE ID or READ ID writes or reads the data portion of the record.

When the record reference is by key, IOCS uses this specification and your IOAREA1 specification to locate the data field in the I/O area.

LABADDR=name

You might require one or more user-standard labels in addition to the standard file label. If so, you must include your own routine to check (or write) the labels. The name of this routine is specified in this operand. IOCS branches to the routine after processing the standard label. For more information about the handling of user-standard labels, see the section Processing of User Labels.

The routine always gets control in 24-bit addressing mode.

READID=YES

This operand must be included for an input file if, in your program, the macro 'READ filename,ID' is used.

READKEY=YES

This operand must be included for an input file if, in your program, the macro 'READ filename,KEY' is used.

RECFORM=FIXUNB | SPNUNB | UNDEF | VARUNB

This operand specifies the type of records in the input or output file. The specifications are:

FIXUNB

For fixed-length records. All records are considered unblocked. If you want blocked records, you must provide your own blocking and deblocking.

SPNUNB

For spanned records. This specification is for unblocked variable-length logical records of less than 32,768 bytes per record.

UNDEF

For undefined records. This specification is required only if the records are of undefined format.

VARUNB

For variable-length records. This specification is for unblocked variable-length records.

For a description of record formats, refer to the z/VSE System Macros User's GuideUsing z/VSE Macro Support.

RECSIZE=(r)

This operand must be included if undefined records are specified (RECFORM=UNDEF). It specifies the number of the general-purpose register (any of 2 through 12) that contains the length of each individual input or output record.

Whenever an undefined record is read, IOCS supplies the length of the data area for that record in the specified register.

When an undefined record is written, you must load the length of the data area of the record (in bytes) into this register, before you issue the WRITE macro for the record. IOCS adds the length of the key when required.

When records are written (AFTER specified in the WRITE macro), IOCS uses the length to set up the count area that is written on disk. IOCS adds the length of both the count and the key when required.

RELTYPE=DEC | HEX

This operand specifies whether the zoned decimal (DEC) or hexadecimal (HEX) form of the relative ID is to be used. When FIXUNB, VARUNB, or UNDEF is specified in the RECFORM operand, RELTYPE should be supplied only if the DSKXTNT operand (relative ID) is specified.

If the operand is omitted, a hexadecimal relative ID is assumed. However, if DSKXTNT is also omitted, a physical ID is assumed in the SEEKADR and IDLOC addresses.

If RECFORM=SPNUNB is specified, the RELTYPE operand is required when relative addressing is used. If RELTYPE is omitted, a physical ID is assumed in the SEEKADR and IDLOC addresses.

SEEKADR=name

This operand must be included to specify the name of your track-reference field. In this field, you store the track location of the particular record read or written. IOCS refers to this field to determine which volume and which track contains the wanted record. Whenever records are to be located by searching for a specified ID, the track-reference field must also contain the number of the record on the track.

SEPASMB=YES

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

SRCHM=YES

If records are identified by key, this operand can be included to cause IOCS to search multiple tracks for each specified record. The macros

• READ filename,KEY
• WRITE filename,KEY

cause IOCS to search the track that is specified in the track-reference field and all following tracks in the cylinder, until the record is found or the end of the cylinder is reached. If the file ends before the end of the cylinder and the record is not found, the search continues into the next file, if any, on the cylinder. EOC, instead of NRF, is indicated. Without SRCHM=YES, each search is confined to the specified track.

TRLBL=YES

This operand, if specified with the LABADDR operand, indicates that user standard trailer labels are to be read or written following the user standard header labels on the user label track. Both operands must be specified for trailer label processing.

TYPEFLE=INPUT | OUTPUT

This operand must be included to indicate how standard volume and file labels are to be processed. INPUT indicates that standard labels are to be read; OUTPUT indicates that standard labels are to be written.

VERIFY=YES

This operand is included if you want to check the parity of disk records after they are written. If this operand is omitted, any records that are written on a disk are not verified.

WRITEID=YES

This operand must be included if the disk location for writing an output record or updating an input file is specified by a record identifier; that is, whenever the macro

  WRITE filename,ID

is used in the program, this operand is required.

WRITEKY=YES

This operand must be included if the disk location for writing any output record or updating an input file is specified by record key, that is, whenever

  WRITE filename,KEY

is used.

XTNTXIT=name

This operand is included if you want to process label extent information. It specifies the name of your extent exit routine. The routine always gets control in 24-bit addressing mode.

During an OPEN, IOCS branches to your routine after each specified extent is checked. Upon entering your routine, IOCS stores, in register 1, the address of a 14-byte field that contains the label extent information (in binary form) retrieved from the format 1 and format 3 labels. If user labels are present, the user label track is returned as a separate extent and the lower limit of the first normal extent is increased by one track. The format of this field is shown in Table 1.

Return to IOCS by use of the LBRET macro. Registers 2 through 13 are available in the XTNTXIT routine. Within the routine, you cannot issue a macro that calls a transient routine (such as OPEN, CLOSE, DUMP, PDUMP, CANCEL, CHKPT, etc.).