DTFIS (Define the File for Indexed Sequential Access) Macro

Format

Requirements for the caller

RMODE:

24

Parameters

CYLOFL=n

This operand must be included if cylinder overflow areas are reserved for a file. Do not include this entry if no overflow areas are reserved.

When a file is loaded or when records are added, this operand is required to reserve the areas for cylinder overflow. It specifies the number of tracks to be reserved on each cylinder. The maximum number of tracks that can be reserved on each cylinder is:

8

For an IBM® 2311

18

For an IBM 2314 or 2319

17

For an IBM 3330 or 3333

10

For an IBM 3340

DEVICE=2311 | 2314 | 3330 | 3340

This operand specifies the unit that contains the prime data area and overflow areas for the logical file. For ISAM the prime data area and the overflow areas must be on the same device type, and, for a 3340, the data modules must be of the same size (35 or 70 MB).

DSKXTNT=n

This operand must be included to specify the maximum number of extents for this file. The number must include all the data area extents if more than one disk area is used for the data records, and all the index area and independent overflow area extents that are specified by EXTENT job control statements. Thus the minimum number that is specified by this entry is 2: one extent for one prime data area, and one for a cylinder index. Each area that is assigned to an ISAM file is considered an extent.

Note: Master and cylinder indexes are treated as one area. When there is one master index extent, one cylinder index extent, and one prime data area extent, DSKXTNT=2 could be specified.

ERREXT=YES

This operand is required for IOCS to supply your program with detailed information about irrecoverable I/O errors occurring before a data transfer takes place, and for your program to be able to use the ERET imperative macro to return to IOCS specifying an action to be taken for an error condition.

Some error information is available for testing by your program after each imperative macro is executed, even if ERREXT=YES is not specified, by referencing field filenameC. For filename, give the name that you specified in the name field of the DTFIS macro for the file. One or more of the bits in the filenameC byte can be set to 1 by IOCS. The meaning of the bits varies depending on what was specified in the IOROUT operand; Table 1 shows the meaning if IOROUT=ADD, RETRVE, or ADDRTR was specified; Table 2 shows the meaning if IOROUT=LOAD was specified.

If ERREXT=YES is not specified, IOCS returns the address of the DTF table in register 1, as well as any data-transfer error information in filenameC, after each imperative macro is executed; non-data-transfer error information is not given. After testing filenameC, return to IOCS by issuing any imperative macro except ERET; no special action is taken by IOCS to correct or check an error.

If ERREXT=YES is specified, IOCS returns the address of an ERREXT parameter list in register 1 after each imperative macro is executed, and information about both data-transfer and non-data-transfer errors in filenameC. The format of the ERREXT parameter list is shown in Table 3. After testing filenameC and finding an error, return to IOCS using the ERET imperative macro; IOCS takes the action indicated by the ERET operand. If HOLD=YES (and ERREXT=YES), ERET must be used to return to IOCS to free any held track.

In your program, check bit 7 of DTF byte 16 (counting from 0) for a block size compatibility error when adding to, or extending a file. If the block size specified in your program is not equal to the block size of the previously built file, this bit is set to 1.

Table 1. FilenameC-Status Byte if IOROUT Specifies ADD, RETRVE, or ADDRTR

Bit	Meaning if Set to 1
0	Disk error – An irrecoverable disk error has occurred (except wrong-length record.)
1	Wrong-length record – A wrong length record has been detected during an I/O operation.
2	End of file – End of file has been encountered during sequential retrieval.
3	No record found – The record to be retrieved has not been found in the file. This applies to RANDOM (RANSEQ) and to SETL in SEQNTL (RANSEQ) when KEY is specified, or after GKEY. This might also be a hardware error.
4	Invalid ID specified – The ID specified to the SETL in SEQNTL (RANSEQ) is outside the prime file limits.
5	Duplicate record – The record to be added to the file has a duplicate record key of another record in the file.
6	Overflow area full – An overflow area in a cylinder is full, and no independent overflow area has been specified; or an independent overflow area is full, and the addition cannot be made. You should assign an independent overflow area or extend the limit.
7	Overflow – The record being processed in one of the retrieval functions (RANDOM/SEQNTL) is an overflow record.

Table 2. FilenameC-Status Byte if IOROUT=LOAD

Bit	Meaning if Set to 1
0	Disk error – An irrecoverable disk error has occurred (except wrong-length record.)
2	Prime area full – The next to the last track of the prime data area has been filled during the load or extension of the file. Issue the ENDFL macro, then do a load extend on the file with next extents given.
3	Cylinder-index area full – The cylinder-index area is not large enough to contain all entries needed to index each cylinder specified for the prime data area. This condition can occur during the execution of the SETFL. Extend the upper limit of the cylinder index using a new EXTENT statement.
4	Master index full – The master index area is not large enough to contain all the entries needed to index each track of the cylinder index. This condition can occur during SETFL. Extend the upper limit, if you are creating the file, using an EXTENT statement; or reorganize the file and assign a larger area.
5	Duplicate record – The record to be added to the file has a duplicate record key of another record in the file.
6	Sequence check – The record being loaded is not in sequential order.
7	Prime data area overflow – There is not enough space in the prime data area to write an EOF record. This condition can occur during the execution of the ENDFL macro.

Table 3. ERREXT Parameter List

Bytes	Contents
0-3	Address of the DTF block
4-7	Virtual storage address of the record in error.
8-15	Disk address (mbbcchhr) of the error, where: m = Extent sequence number r = A record number which can be inaccurate, if a read error occurred during a read of the index of the highest level.
16	Record identification: Bit Meaning if 1 1 Data record 2 Track-index record. 3 Cylinder- or master-index record. 4-5 Reserved. 6 Read operation. 7 Write operation
17	Command code of failing CCW.

HINDEX=2311 | 2314 | 3330 | 3340

This operand specifies the type of the disk unit that contains the highest index.

Placing the highest index on a separate unit is recommended only if that unit is physically separate from the units holding the track indexes and the data of the file, and if it has its own access mechanism. If this operand is omitted, 2311 is assumed.

HOLD=YES

This operand provides for the track hold option for both data and index records. If the HOLD operand is omitted, the track hold function is not performed. Because track hold cannot be performed on a LOAD file, HOLD=YES cannot be specified when IOROUT=LOAD.

If HOLD=YES and ERREXT=YES, your program must issue the ERET macro to return to the ISAM module to free any held tracks.

INDAREA=name

This operand specifies the name of the area that is assigned to the cylinder index. If specified, all or part of the cylinder index resides in virtual storage thereby increasing throughput. If this operand is included, INDSIZE must be included.

If the area assigned to INDAREA is large enough for all the index entries to be read into virtual storage at one time and the index skip feature (INDSKIP) is not specified, no presorting of records need be done. If the area assigned to INDAREA is not large enough, the records processed should be presorted to fully utilize the resident cylinder index.

INDSKIP=YES

When cylinder index entries reside in virtual storage, this operand specifies the index skip feature. This feature allows ISAM to skip any index entries preceding those needed to process a given key. If the index skip operand is omitted, the cylinder indexes are processed sequentially.

This operand can be specified only with the INDAREA and INDSIZE operands and increases throughput only when:

• The records are presorted.
• The allocated virtual storage is insufficient for storing all of the cylinder index.
• One or more large segments of the file are not referenced.

INDSIZE=n

This operand specifies the length (in bytes) of the index area that is assigned in virtual storage to the cylinder index by INDAREA. The minimum you can specify is:

  n = (m + 3) (keylength + 6)

where

m =

The number of entries to be read into virtual storage at a time.

3 =

The number of dummy entries.

6 =

A pointer to the cylinder.

If m is set equal to the number of prime data cylinders+1, the entire cylinder index is read into virtual storage at one time. The maximum value for n = 32767.

The resident index facility is suppressed if this operand is omitted, the minimum requirement is not met at assembly time, or an irrecoverable read error is encountered while reading the index.

IOAREAL=name

This operand must be included when a file is created (loaded) or when records are added to a file. It specifies the name of the output area that is used for loading or adding records to the file. The specified name must be the same as the name used in the DS instruction that reserves the area of storage. The ISAM routines construct the contents of this area and transfer records to disk.

This output area must be large enough to contain the count, key, and data areas of records. Furthermore, the data-area portion must provide enough space for the sequence-link field of overflow records whenever records are added to a file (see Table 4).

If IOAREAL is increased to permit the reading and writing of more than one physical record on disk concurrently, the IOSIZE operand must be included when records are added to the file. In this case, the IOAREAL area must be at least as large as the number of bytes specified in the IOSIZE operand.

When simultaneously building two ISAM files using two DTFs, do not use a common IOAREAL. Also, do not use a common area for IOAREAL, IOAREAR, and IOAREAS in multiple DTFs.

IOAREAR=name

This operand must be included whenever records are processed in random order. It specifies the name of the input/output area for random retrieval (and updating). The specified name must be the same as that used in the DS instruction that reserves this area of storage.

The I/O area must be large enough to contain the data area for records. Furthermore, the data-area portion must provide enough space for the sequence-link field of overflow records (see Table 5).

IOAREAS=name

This operand must be included whenever records are processed in sequential order by key. It specifies the name of the input/output area that is used for sequential retrieval (and updating). The specified name must be the same as that used in the DS instruction that reserves this area of storage.

This I/O area must be large enough to contain the key and data areas of unblocked records and the data area for blocked records. Furthermore, the data-area portion must provide enough space for the sequence-link field of overflow records (see Table 5).

Table 4. Output Area Requirements (in No. of Bytes) for Loading or Adding Records to a File by ISAM

Function	Count	Key	Seq. Link	Data
Load unblocked records	8	+ key length	+ 0	+ R
Load blocked records	8	+ key length	+ 0	+ R x B
Add unblocked records	8	+ key length	+ 10	+ R
Add blocked records	8 8	+ key length + key length	+ 0 + 0	+ R x B + R
B = Blocking factor R = Record length

IOAREA2=name

This operand permits overlapping of I/O with indexed sequential processing for either the load (creation) or sequential retrieval functions. Specify the name of an I/O area to be used when loading or sequentially retrieving records. The I/O area must be at least the length of the area that is specified by either the IOAREAL operand for the load function or the IOAREAS operand for the sequential retrieval function. If the operand is omitted, one I/O area is assumed. If TYPEFLE=RANSEQ, this operand must not be specified.

IOREG=(r)

This operand must be included whenever records are retrieved and processed directly in the I/O area. It specifies the register that ISAM uses to indicate which individual record is available for processing. ISAM puts the address of the current record in the designated register (any of 2 through 12) each time a READ, WRITE, GET, or PUT is executed.

IOROUT=LOAD | ADD | RETRVE | ADDRTR

This entry must be included to specify the type of function to be performed. The specifications have the following meanings:

IOROUT=LOAD

To build a logical file on a disk or to extend a file beyond the highest record presently in a file.

IOROUT=ADD

To insert new records into a file.

IOROUT=RETRVE

To retrieve records from a file for either random or sequential processing and updating.

IOROUT=ADDRTR

To both insert new records into a file (ADD) and retrieve records for processing and updating (RTR).

Note: The disk device must be in READ/WRITE mode for all functions.

Table 5. Output Area Requirements (in No. of Bytes) for Random or Sequential Retrieval by ISAM

Function	Count	Key	Seq. Link	Data
Retrieve unblocked records	8	+ key length*	+ 10	+ R
Retrieve blocked records	0 0	+ 0 + 0	+ 0 + 10	+ R x B** + R
B = Blocking factor R = Record length		* Only for sequential retrieval ** Including keys

IOSIZE=n

This operand specifies the decimal number of bytes in the virtual-storage area that is assigned for the add function using IOAREAL. The number n can be computed with the following formula:

  n = m (keylength + blocksize + 40) + 24
 
  Where m = The maximum number of physical records that can
            be read into virtual storage at one time.

The number n must be at least equal to

  (keylength + blocksize + 74)

This formula accounts for a needed sequence link field for unblocked records or short blocks (see Table 4 and Table 5).

If the operand is omitted, or if the minimum requirement is not met, no increase in throughput is realized.

The number n should not exceed the track capacity because throughput cannot be increased by specifying a number larger than the capacity of a track.

KEYARG=name

This operand must be included for random READ/WRITE operations and sequential retrieval that is initiated by key. It specifies the symbolic name of the key field in which you must supply the record key to ISAM.

KEYLEN=n

This operand must be included to specify the number of bytes in the record key.

KEYLOC=n

This operand must always be specified if RECFORM=FIXBLK. It supplies ISAM with the high-order position of the key field within the data record. That is, if the key is recorded in positions 21-25 of each record in the file, this operand should specify 21.

ISAM uses this specification to locate (by key) a specified record within a block. The key area of a block of records contains the key of the highest record in the block. To search for any other records, ISAM locates the proper block and then examines the key field within each record in the block.

MODNAME=name

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, the MODNAME in the DTF must specify the same name as the ISMOD macro. If this entry 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.

MSTIND=YES

This operand is included whenever a master index is used or is to be built for a file. The location of the master index is specified by an EXTENT job control statement.

NRECDS=n

This operand specifies the number of logical records in a block (called the blocking factor). It is required only if RECFORM=FIXBLK. For FIXBLK, n must be greater than 1; for FIXUNB, n must be =1.

RDONLY=YES

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. Each task should have its own uniquely defined save area. Register 13 must contain the address of the save area that is associated with the task each time an imperative macro (except OPEN, OPENR, LBRET, SETL, or SETFL) is issued. The fact that the save areas are unique for each task makes the module reentrant (that is, capable of being used concurrently by several tasks).

RECFORM=FIXUNB | FIXBLK

This operand specifies whether records are blocked or unblocked. FIXUNB is used for unblocked records, and FIXBLK for blocked records. If FIXBLK is specified, the key of the highest record in the block becomes the key for the block and must be recorded in the key area.

The specification that is included when the logical file is loaded onto a disk must also be included whenever the file is processed.

Records in the overflow areas are always unblocked, but this has no effect on this operand. RECFORM refers to records in the prime data area only.

RECSIZE=n

This operand must be included to specify the number of characters in the data area of each individual record. This operand should specify the same number for additions and retrieval as indicated when the file was created.

SEPASMB=YES

Include this operand only if your DTFIS 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 DTFIS macro is assembled with your program.

TYPEFLE=RANDOM | SEQNTL | RANSEQ

This operand must be included when IOROUT=RETRVE or IOROUT=ADDRTR. The operand specifies the types of processing performed by your program for the file.

RANDOM is used for random processing. Records are retrieved in random order that is specified by key.

SEQNTL is used for sequential processing. Your program specifies the first record that is retrieved, and thereafter ISAM retrieves records in sequential order by key. The first record is specified by key, ID, or the beginning of the logical file (see SETL (Set Limits) Macro).

RANSEQ is used if both random and sequential processing are to be performed for the same file. If RANSEQ is specified, the IOAREA2 operand must not be specified.

TYPEFLE is not required for loading or adding functions.

VERIFY=YES

Use this operand 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.

WORKL=name

This operand must be included whenever a file is created (loaded) or records are added to a file. It specifies the name of the work area in which you must supply the data records to ISAM for loading or adding to the file. The specified name must be the same as the name used in the DS instruction that reserves this area of storage.

This work area must provide space for one logical record when a file is created (for blocked records: data; for unblocked records: key and data).

The original contents of WORKL are changed due to record shifting in the ADD function.

WORKR=name

When records are processed in random order, this operand must be included if the individual records are to be processed in a work area rather than in the I/O area. It specifies the name of the work area. This name must be the same as the name used in the DS instruction that reserves this area of storage. This area must provide space for one logical record (data area). When this entry is included and a READ (or WRITE) macro is executed, ISAM moves the individual record to (or from) this area.

WORKS=YES

When records are processed in sequential order, this operand must be included if the individual records are processed in work areas rather than in the I/O area. Each GET and PUT macro must specify the name of the work area to or from which ISAM is to move the record. When processing unblocked records, the area must be large enough for one record (data area) and the record key (key area). For blocked records, the area must be large enough for one logical record (data area) only. Table 6 displays the work area requirements.