ISAM pointers

Macros which refer to a record that was processed by a preceding macro use internal “pointers” to determine the current position within the file.

A separate pointer is maintained for the primary key and for each secondary key defined for the file. A successful positioning or read operation via a secondary key (using SETL, GET, GETKY or GETR) first modifies the pointer for the secondary key and then, with the aid of the updated secondary key value, sets the pointer for the primary key to the appropriate record.

Macros which evaluate the ISAM pointers are all sequential macros or, for example, PUTX, which writes a previously read record back to the file.

If a macro cannot be executed completely, e.g. because an error or a PGLOCK condition occurs, then the pointer is reset, for NK-ISAM, to the value it had before the macro was called. The only exception to this is the error “NOFIND”: since the desired record could not be found, it is not possible to position the pointer to this key.

ISAM pointers are generally updated before the macro is executed. However, for sequential read operations (GET, GETR), the preceding macro must be taken into account: if a sequential read operation is preceded by a SETL macro, then this SETL acts as a “positioning macro”.

The ISAM actions OSTAT (Open STATus) and ISREQ have no effect on the pointer position since they do not initiate any actions in the file.

When a file is opened, a “SETL B” is initiated internally as the first action for an ISAM file, i.e. the pointer is positioned to the first record in the file.

Rules for ISAM pointers

Action macro	Pointer	Action	Comments
ELIM	KEY not specified: Pointer is not moved. KEY specified: Pointer is moved to the first record with the specified key.	Eliminates a record from the file.	ELIM can be regarded as a “left-shift” operation on that portion of the file to the right of the defined record. Thus, if ELIM is successful, the pointer does not have to be updated.
GET	The pointer for the primary or secondary key specified in the macro is moved one record towards the end of the file.	Retrieves the record referenced by the pointer.	If the pointer points to a record outside the file, the user is given control at the EOFADDR exit. If the preceding macro was a SETL or ELIM (with KEY), the pointer is not updated until the record is retrieved.
GETFL	The pointer is moved to the record retrieved, or to the last record in the defined area.	Retrieves the next sequential record which satisfies the flag criteria.	The record which would have been retrieved by a corresponding GET or GETR macro is the first record examined for the flag criteria.
GETKY	The pointer is set to the record with the specified primary or secondary key or to the position in the file where this record should be.	Retrieves the record pointed to by the pointer, assuming the record with the specified key exists.	A GETKY for a key without a corresponding record is equivalent to a GETKY for a record of zero length that is assumed to be located between two existing records. Thus, a subsequent GET or GETR will work correctly (see GET).
GETR	The pointer for the primary or secondary key specified in the macro is moved one record towards the beginning of the file.	Retrieves the record referenced by the pointer (see reverse read)	If the pointer points to a record situated before the beginning of the file, the user is given control at the EOFADDR exit (see GET).
INSRT	The pointer is moved to the position specified by the record key.	Inserts the record at the location indicated by the pointer.	The record is not inserted if a record with the same key already exists. However, the pointer still points to the position in the file at which the record was to be inserted. A GET macro issued after an unsuccessful INSRT retrieves the duplicate record.
OPEN	The pointer is positioned before the first record in the file.		See "OPEN - Open file"
PUT	The pointer is positioned immediately after the current end of the file.	Places the record in the file at the position indicated by the pointer.
PUTX	The pointer does not change its position.	Places the record in the file at the position indicated by the pointer.	A check is made to verify that a GET, GETR, GETFL or GETKY macro was called immediately prior to PUTX. This ensures that no errors occur even though the pointer was not updated.
RETRY	Contingent on the operation to be repeated, or on the positioning operation.	Repeats the last action macro for the file or positions the pointer to the origin or places the program in a queue.	RETRY itself does not affect the pointer except when it results in the execution of an action macro which does move the pointer.
SETL	SETL B: The pointer is positioned in front of the first record in the file. SETL E: The pointer is positioned after the last record in the file. SETL KEY: The pointer is set to the first record with the specified primary or secondary key or to the record with the next-higher key value.	No action	Inhibits the pointer update by a following GET or GETR macro. Under the pointer concept, a SETL for a non-existent record can, when followed by a GET or GETR macro, be interpreted as a SETL for a record of zero length at the correct position. In this case the SETL does not cancel updating of the pointer by the following GET or GETR macro.
STORE	The pointer is moved to the position specified by the key. DUPEKY=YES: If a duplicate key is encountered, the pointer is positioned after the existing record.	Writes the record at the desired location.	If a record with the same key already exists in the file, it is overwritten (unless DUPEKY=YES was specified). If DUPEKY=YES applies, the new record is written after the “old” record.