Accessing Files/Positioning the Pointer

PRO/5 maintains a pointer, or position, within every OPEN file from which the read will retrieve data or the next write will place data. This position is the current file index or key. Indices exist in all files that are accessed by number, keys for SORT, DIRECT, and MKEYED files. The position in a file is set on OPENing a file to either index 0 for indexed files, or the first logical key for a keyed file.

When you access a file by index, the index is specified by placing the IND= option in the READ/WRITE command. The following causes PRO/5 to place the file pointer to index 20 prior to the read:

>READ(1,IND=20)A$

After the read, the index is incremented to the next record. In the case of a file not containing records, the index is placed to the character following the last character read or written.

If the file type is SORT, DIRECT, CISAM, or MKEYED, the positioning may be performed using the KEY= option. If the file type is MKEYED or CISAM and the key is extracted from the record data, the KEY= option many not be used on a WRITE. This option places the pointer to the record identified by the key following the KEY= option. This key is a string from 0 to 64 characters in length for DIRECT and SORT files, 120 characters for MKEYED files. The following would cause PRO/5 to attempt to place the pointer to the key equal to "AAA":

>READ(1,KEY="AAA")A$

If the key did not exist, PRO/5 would place the pointer to the first position logically following the key "AAA" and return to you an !ERROR=11 (missing or duplicate key). The error is commonly trapped using the DOM= option which takes a line number to continue program execution if an !ERROR=11 occurs. As an example, the following program would read all of the records in a file (yet do nothing with them):

10 READ (1,KEY="",DOM=20)
20 K$=KEY(1,END=30); READ (1); GOTO 20
30 END

In this example, the line 10 simply places the file pointer to the first record (there can't be a key less than nothing) and continues at line 20 whether the read succeeds or not. Line 20 then uses the KEY() function to return the current key, reads to advance the file pointer, and loops back to itself. The END= branch will be taken when the KEY() function returns an !ERROR=2 because there are no more keys in the file. The read has no END= branch as the KEY() function will return the error first.

Additional KEY() functions are provided to return keys around the current position in the file. These functions are documented with the KEY() function in the Commands Manual.

The WRITE command accesses file records in the same manner as the READ command. The WRITE command also increments the record pointer in the same manner as the READ command.

The EXTRACT command is similar to the READ command in positioning to a record and reading the contents of a record except the EXTRACT does not increment to the next record in the file. In addition, the EXTRACT will "lock" the record so that other users of the file may not read or write the EXTRACTed record (see Locking Records).

The FIND command is similar to the READ command with the exception that the FIND will not position to a record following a non-existent key. If the key requested exists, FIND operates in exactly the same manner as READ. The FIND command will generally be faster than a READ if you do not know if the key exists and you do not care about the resulting pointer in the file after the FIND operation.