Reading key data only from next record in a file¶

nextkey

Read key data only from the next record in a file

SYNTAX

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

Reads the key data only for the next record in ascending 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 ascending key sequence. The Record in use condition can be trapped on a next[u] command, and nextkey 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 nextkey command is faster than next[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 next record is the one whose key immediately follows the last key value supplied, and this is the record that is read by nextkey.

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

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 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.
[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 nextkey commands cause a batch of records to be obtained from the server. See Batch file read mode.
The next[u] command is similar to nextkey except that the data record is read as well as the key.
The prevkey command produces the previous key.

EXAMPLE

caption "Enter part of name for search"
input Namebox traps = END
rewind Customers
caption "Searching..."

while (TRUE) {
     nextkey Customers nsr = BREAK
     if (c_name ct tmp.Namebit) {
          DisplayName()
          break
     }
}

RELATED TOPICS