Read a record from a file using exact key data¶
read[u] |
Read a record from a file using exact key data |
SYNTAX
Unlocks any existing locked record in the file and then reads into the record buffer the record whose key exactly matches the key supplied. The read command locks the record if the file is open in update mode and this program does not have a read lock on the file. The record is now selected, and may be written back or deleted. The readu command does not lock the record, regardless of the file mode.
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).
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:
|
[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. Unlike the main index, a secondary index can have a key that is not unique. When read[u] 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 read[u] 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 read leaves the record buffer unaltered, but the file position is moved to the key provided. 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 requested record exists, but 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. If this 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).
The readkey command can be used to read the index file only.
The find[u] command can be used to find records with a partial key match.
EXAMPLE
read Stock nsr = NO_STOCK riu = WAIT traps = IGNORE
RELATED TOPICS |