Testing for a record with a specified key¶

testkey

Test for a record with a specified key

SYNTAX

testkey record_id [index = index_id] [key = expr_list] \

[nsr = label] [traps = label]

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, or moving the current file position, or unlocking any currently locked record.

Every key field must match precisely. Duplicate keys are not permitted, so if a record is successfully read it will be unique. This does not apply if a secondary index was used (by means of the index = clause).

The file position remains for the purpose of next and prev type commands. If the key = clause was used, the key fields of the record buffer are not updated with the key values. Any existing locked record in the file is not unlocked.

No attempt is made to read the data record, so a Record in use status cannot occur. Any values currently existing in the data fields of the record buffer remain unchanged.

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]	The index = 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. This use of testkey would enable the programmer to check whether a secondary index key field was unique, without altering the record buffer.
[key = expr_list]	Key field values of the record to be found. If this clause is used, the key fields in the record buffer are unaltered, whether or not a matching record is found. See The key = clause.
[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. The current file position remains unchanged for the purpose of next, prev and similar commands. 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).

EXAMPLE

!function InsertRec() {
     InputKey()
     testkey Invoices nsr = IN20
     info "Invoice already recorded"
     return ERROR

IN20:
     InputData()
     insert Invoices traps = INERR
     info "New invoice recorded"
     return OKAY

INERR:
     error "Unable to create new invoice"
     return ERROR
}

RELATED TOPICS