Reading key data only from previous record in a file

prevkey

Read key data only from the previous record in a file


SYNTAX

prevkey record_id [index = index_id] [nsr = label] [traps = label]

Reads the key data only for the previous record in descending key sequence in the file whose record buffer is specified, without attempting to read the data record. This command is very useful for the following purposes:

1

Skipping locked records when reading through the file sequentially in descending key sequence. The Record in use condition can be trapped on a prev[u] command, and prevkey executed instead, passing by the locked record before returning to the main search.

2

Speeding up a sequential search where only key data is required. The prevkey command is faster than prev[u].

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 whose key is read by prevkey.

Note that the prevkey command never returns the last key in a file if that 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.

[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).

  • The prev[u] command is similar to prevkey except that the data record is read as well as the key.

  • The nextkey command produces the previous key.


EXAMPLE

prevkey Stock index = StockLevel nsr = PR_NSR traps = PR_TRAPS

RELATED TOPICS

Keyed files

Traps

prev[u]

nextkey