Reading the next unsorted record in a file¶
nextseq[u] |
Read the next record in a file in undefined order |
Version >= 6.0.4 |
SYNTAX
nextseq[u] record_id [nsr = label] [riu = label] [traps = label]
Unlocks any existing locked record in the file and reads the next record in undefined order. The nextseq 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 nextsequ command does not lock the record, regardless of the file mode.
Because they don’t use an index, these commands are faster than next and nextu and are paricularly suitable for reading through an entire file when the order of the records is not important. The commands are implemented for Sculptor Keyed Files and for ODBC databases. The rewind command resets the file position to the beginning for nextseq and nextsequ.
Every successful file access command except testkey moves the current file position to that indicated by the key values supplied for the command. This is not the case even if a record with the supplied key did not or does not exist; in this case the file is positioned (regarding the nextseq[u] commnad) in the last completely accessed record.
If the file has not yet been accessed in the program, the first record in the file is selected. Note however that the nextseq[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:
|
[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 nextseq will try to read the same 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 nextseq[u] commands cause a batch of records to be obtained from the server.
EXAMPLE
!function NextSeq() {
nextseq Orders traps = N_ERR
DisplayOrder()
return OKAY
N_ERR:
return ERROR
}
RELATED TOPICS |