Reading the previous record in a file¶

prev[u]

Read the previous record in a file

SYNTAX

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

Unlocks any existing locked record in the file and reads the previous record in descending key sequence. The prev 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 prevu 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 previous record is the one whose key immediately precedes the last key value supplied, and this is the record that is read by prev[u].

Note that the prev[u] command never returns the last record in a file if its key contains the maximum possible value (i.e. all the key fields contain the highest possible value for their key type).

record_id	The record 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 beginning 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 previous 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 prev will try to read the same record. Alternatively, the prevkey 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 prev[u] commands cause a batch of records to be obtained from the server.
The prevkey command is similar to prev[u] except that it does not read the data file.
The next[u] command reads the next record in ascending key sequence.

EXAMPLE

!function Previous() {
!temp ExitStat,,i4

     prev Invoices nsr = PREV_NSR riu = PREV_RIU
     DisplayInv()
     ExitStat = OK
     goto PREV_RETURN

PREV_NSR:
     error "Beginning of file reached"
     ExitStat = ERROR
     goto PREV_RETURN

PREV_RIU:
     error "Previous record is locked"
     ExitStat = ERROR
     goto PREV_RETURN

PREV_RETURN:
     return ExitStat
}

RELATED TOPICS