Reading the next record in a file¶

next[u]

Read the next record in a file

SYNTAX

next[u] record_id [index = index_id] [nsr = label] [riu = label] [traps = label]

Unlocks any existing locked record in the file and reads the next record in ascending key sequence. The next command locks the record if the file is open in update mode and this program does not have a readlock on the file. The record is now selected, and may be written back or deleted. The nextu command does not lock the record, regardless of the file mode.

Every file access command except testkey moves the current file position to that indicated by the key values supplied for the command. This is the case even if a record with the supplied key did not or does not exist; in this case the file is positioned between two records (or at the beginning or end of the file). The next record is the one whose key immediately follows the last key value supplied, and this is the record that is read by next[u].

If the file has not yet been accessed in the program, the first record in the file is selected. Note however that the next[u] command never returns the first key in the file if that key is completely null (all bytes set to binary zero).

record_id	The buffer into which the record is to be read. The record buffer is frequently, though not necessarily, the default record buffer that is automatically created for each file opened within a program. This default buffer bears the same name as the file’s file_id. However, record_id may also be an additional buffer declared for the file by means of the declaration !record , as follows: !record record_id = file_id
[index = index_id]	This clause can be used to specify a secondary index to be used to access the file. The index_id must be the name of a secondary index specified for the file by the ddeditor program. The access sequence for each index is independent, both of other indexes and of the main file index. If a record is accessed from the main file index, or if a file update command is executed, the file position of the secondary indexes is not changed unless the sync_indexes command is used. The main index is always repositioned when a record is read. Therefore accesses by a secondary index reposition that index and the main index, but have no effect on other secondary indexes.
[nsr = label]	Traps the condition where the end of the file (or index) has been reached. Control passes to the line indicated by label. Any existing locked record in the file is unlocked. If this condition is not trapped, the error No such record is displayed and control passes to the active menu, if any. If no menu is active the program exits. In a !report section, an untrapped nsr condition returns a null record. There is no default error message.
[riu = label]	Traps the condition where the next record is currently locked by another user. Control passes to the line indicated by label. On most systems the Record in use status can only occur if the file is open in update mode. The file position is not changed, so another next will try to read the same record. Alternatively, the nextkey command, which cannot incur the riu status, can be used to skip the record. On most systems the Record in use status can only occur if the file is open in update mode. If the condition is not trapped, the message Waiting… is displayed, and the read is retried every three seconds until successful. In a !report section, no message is issued if an untrapped riu is encountered. The program simply waits for the record to become available.
[traps = label]	General purpose trap clause that traps any condition not explicitly trapped, passing control to the line indicated by label. It has the lowest priority, and is only invoked if a trappable condition has not been more explicitly trapped.

NOTES

If the file is closed Sculptor automatically opens it, using the mode in which it was last open (defaulting to the mode in the file declaration).
If batch read mode has been set for the file in client/server mode, two consecutive read-only next[u] commands cause a batch of records to be obtained from the server.
The nextkey command is similar to next[u] except that it does not read the data file.
The prev[u] command reads the previous record in descending key sequence.
The next command is used for a different purpose under ODBC.

EXAMPLE

!function Next() {
     next Orders traps = N_ERR
     DisplayOrder()
     return OKAY

N_ERR:
     return ERROR
}

RELATED TOPICS