Reading key data only from record exactly matching supplied key¶
readkey |
Read key data only from a record using exact key data |
SYNTAX
Tests the file whose record buffer is specified for a record whose key exactly matches the key supplied, without attempting to read the data record. This command can be used to speed file access when only the key data of a record is required.
Every key field must match precisely. Duplicate keys are not permitted, so if a record is successfully read it is unique. This does not apply if a secondary index was used (by means of the index = clause).
The file position is changed to the new key value for the purpose of next and prev type commands. If the key = clause was used, the key fields of the record buffer are updated with the key values. Any existing locked record in the file is unlocked.
No attempt is made to read the data record, so a Record in use status cannot occur. The record whose key has been found cannot be locked, nor can any updates to it be made. Any values currently existing in the data fields of the record buffer remain unchanged.
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:
|
[index = index_id] |
This clause is 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. Unlike the main index, a secondary index can have a key that is not unique. When readkey is used on a secondary index, the record that is read is always the first record that has the supplied secondary index key values. The current values in the main key fields are not taken into account. If the secondary index key values are not unique, the record that is read may therefore not be the expected record. Therefore, if the purpose of a readkey command is to update the file position of the specified index for the purpose of subsequent next and prev commands, it may be preferable to use the sync_indexes command instead. |
[key = expr_list] |
Key field values of the record to be found. |
[nsr = label] |
Traps the condition where no record exists with an exactly matching key. Control passes to the line indicated by label. An unsuccessful readkey leaves the record buffer unaltered, but the file position is moved to the key provided. Even though the search was unsuccessful, the current file position is changed to the new key value for the purpose of next, prev and similar commands. 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 read[u] command should be used to access the data record.
The testkey command performs the same function as readkey except that it does not change the current file position, whether or not a matching record is found.
EXAMPLE
Position file at item with key beginning “WX”:
st.code = "WX"
readkey StockFile traps = IGNORE
next StockFile
RELATED TOPICS |