Before a file can be processed, it must be opened using an OPEN macro. The following OPEN modes are permitted for ISAM files: OUTPUT, OUTIN, EXTEND, INOUT, INPUT. At the same time, it is necessary to check whether the file has already been opened by another job, in which ISAM pool it is to be processed, whether it is to be processed in locate or move mode, etc.
OUTPUT | A new file is created sequentially and only the PUT macro may be used. If an ISAM file with the specified name already exists, it is overwritten and the catalog entry is updated. |
OUTIN | As for OPEN OUTPUT, a new file is created and any existing file with the specified name is overwritten, but all ISAM actions are permitted. |
EXTEND | An existing file is extended sequentially; as for OPEN OUTPUT only write operations with PUT are permitted. |
INOUT | An existing file is to be updated: as for OUTIN, all ISAM actions (such as finding, reading, updating, inserting and deleting records) are permitted. |
INPUT | An existing file is to be read, i.e. only read operations are permitted. |
Operating modes
ISAM files are normally processed in move mode; locate mode can be used, but in NK-ISAM this is only still supported for reasons of compatibility.
Action macro | OPEN type | OPEN type | OPEN type | OPEN type | OPEN type |
GET | B | - | - | B | B |
GETR | B | - | - | B | B |
GETFL | B | - | - | B | B |
GETKY | B | - | - | B | B |
PUT | - | B | B | B | B |
PUTX | - | - | - | B | B |
INSRT | - | - | - | M | M |
STORE | - | - | - | M | M |
ELIM | - | - | - | x | x |
SETL | x | - | - | x | x |
where:
M | Move mode (locate mode only if a work area is supplied). |
B | Move mode or locate mode permitted. |
x | Action macro may be used. |
- | Action macro must not be used. |
OPEN errors when processing NK-ISAM files
NK-ISAM file on tape: an invalid data format was specified in the FILE or FCB macro when importing the tape file or writing it back to tape.
The ISAM pool in which an NK-ISAM file is to be opened is overloaded, OPEN processing is rejected with error message DMS0D9B.
On each SVC entry, the size of the NK-ISAM file in question is checked on the basis of the extent list present in the File Entry Table. If this check indicates that the file size is greater than 32 GB and if the caller has set the attribute LARGE_FILE=*FORBIDDEN in the FCB then processing is canceled. In this case, NK-ISAM issues the return code: X'00000A23' (FILE SIZE GREATER 32 GIGABYTES IS NOT ALLOWED).
Transferring file attributes to the FCB
The contents of FCB fields for file attributes may differ from the values specified for the corresponding operands in the FILE macro. This is true, for example, for KEYPOS, KEYLEN, PAD and BLKSIZE. If “n” is the value in field KEYPOS and “m” is the value of KEYLEN in the catalog entry or in the TFT or the FCB macro, the following applies to files which are open:
field KEYLEN in the TU FCB contains m-1
field KEYPOS in the TU FCB contains, for RECFORM=F, (n+4)-1 = n+3
The PAD value is taken into account only when a file is created sequentially by means of the PUT macro. The macros INSRT and STORE use all the available space of each data block. Block splitting may occur during creation of the file in both functions.
The contents of field BLKSIZE in the TU FCB may also differ from the value of the BLKSIZE operand in the FILE or FCB macro or the catalog entry: except for input files, the BLKSIZE is recalculated, taking the PAD value into account (BLKSIZE minus PAD) and placed in FCB field BLKSIZE.
Example
Catalog entry: BLKSIZE=(STD,3); PAD=15 (default value). The contents of BLKSIZE in the TU FCB are calculated as follows: (3 * 2048) * (1.0 – 0.15); during file processing, the field BLKSIZE contains the value X'1467'.
Dummy files
Dummy files can be used for test purposes, particularly for testing error routines in user programs. These dummy files are defined by *DUMMY in the FILE macro. No actual I/O operations are executed when these files are processed. Any attempt to read such a file causes control to be passed to an error routine and write attempts are ignored. In each case, a no-op (no operation) is executed.
The following table shows which events occur for the various ISAM read operations.
Read operation | Macro | Event | EXLST exit | Message |
Sequential read | GET/GETR | End of file | EOFADDR | DMS0AAE |
Read with key | GETKY | Key not found | NOFIND | DMS0AA8 |
Read with flags | GETFL | Key not found | NOFIND | DMS0AA8 |
LIMIT=END | End of file | EOFADDR | DMS0AAE |
Block usage: PAD value
During sequential creation of a file with PUT, the user can specify via the PAD operand in the FILE/FCB macro how much space is to be left free in each data block. This space is needed if the records in the file are subsequently updated and extended. The default value is PAD=15, i.e. 15% of the space in each data block is left free. If a PUT macro would result in less free space in an existing block, a new data block is created for the next record.
For NK-ISAM files, a new data block is requested as soon as this limit is exceeded; K-ISAM requests a new data block before the limit is exceeded.
For sequential creation with PUT, the size of a file increases if the PAD factor is increased. However, subsequent processing of the file (STORE/INSRT) can be optimized by selecting a suitable value for PAD: the free space left in the data blocks should be so large that block splitting does not occur when the file is subsequently extended. In order to select the correct PAD value, it is thus necessary to estimate how the file will grow.
If ISAM files are created using STORE, the PAD value has no effect on how the blocks are filled. STORE writes records into a block until it is full. If a further record is then written, block splitting occurs. The blocks are usually only 50% full.
Even if the file is created by means of PUT, but not via an I/O area in the program, the PAD has no effect (the I/O area is defined in the FCB with IOAREAn; see “Program buffer”, below). Each PUT macro initiates a write operation and DMS attempts to place the new record in the current data block. A new data block is created only when the current block is full.
Program buffer = I/O area in the user program
If a program uses its own I/O area, this must be at least as large as a data block (= n * 2048 bytes, where 1 <= n <= 16), as specified in BLKSIZE=(STD,n). By default, the system generates an I/O area in class 5 memory.
The existence of an I/O area defined by the user via IOAREA1/2 in his/her program is particularly advantageous for the sequential processing of ISAM files, since it reduces the number of SVCs:
sequential read operations (GET/GETR): in the first read operation, as many records as possible are transferred to the I/O area before the first record is returned to the program. For subsequent read operations, the records already in the I/O area are returned to the program and a new I/O operation is executed only when all of these records have been passed to the program.
sequential write operations (PUT): during the sequential creation or extension of a file, the records are collected in the I/O area until it is full (taking the PAD value into account) or until sequential processing is terminated by a call for another operation. Care should be taken that sequences of PUT operations are not interrupted by other actions, since each such interruption causes the contents of the I/O area to be written as a new data block and this can lead to blocks with relatively small amounts of data.
For NK-ISAM in move mode, the user can dispense with an I/O area (IOAREA1=NO in the FCB). In this case, each action macro call leads to an SVC.