Finding and read a record by full or partial key value¶

find[u]

Find and read a record by full or partial key value

SYNTAX

find | findu record_id [index = index_id] [key = expr_list] [nsr = label] [riu = label] [traps = label]

Matching key data

Speed of search

Unlocks any existing record locked by the program and then searches for the first record in the specified file whose key matches the key supplied. The find command locks the record if the file is open in update mode and the program does not have a read lock on the file. The record is now selected, and may be written back or deleted. The findu command does not lock the record, regardless of the file mode.

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: !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.
[key = expr_list]	Key field values of the record to be found. See The key = clause.
[nsr = label]	Traps the condition where no record exists with a matching key. Control passes to the line indicated by label. An unsuccessful find 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.

Matching key data¶

The find command differs from read because it does not require a full key to be supplied. Key fields may be blank, and alphanumeric key fields may be provided in part. The full rules are as follows:

1

If the key field is alphanumeric, then trailing spaces in the data supplied are ignored. The remaining characters must match the corresponding characters in the key field. For example, “Smith” would find “Smithson” but not “Smythe”. If the supplied data is blank, any value in the key field is considered a match. Embedded spaces are not wild card characters; there must also be a space in the corresponding position in the key field. So “turi” will not find “turnip”.

2

If the key field is numeric (including date and time fields) and the supplied data is non-zero, then the supplied data must match exactly. If the supplied data is zero, any value in the key field is considered a match.

These rules are applied to each key field in turn. For a record to be selected, the data supplied for each key field must match the key data in the record. Be sure that any keys that are not to be taken into account in the search are blank.

If every key is blank, the first record in the file is selected.

Speed of search¶

The first key field is the most significant. Data is primarily sorted in order of this field; therefore the search is fastest when this is provided. If the first key field is blank the whole index file must be searched from the beginning for data matching the secondary key values. The retrieval time depends on the size of the key and on the number of keys checked, but it is considerably faster than a sequential record by record search using next.

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 match[u] command can be used to find the next matching record.
The related read[u] command requires an exact match on all keys.

EXAMPLE

!function OKFind() {
     findu Address nsr = FIND_NSR riu = FIND_RIU traps = FIND_TRAPS
     Found = TRUE
     Display()
     setfocus FindBut
     return

FIND_NSR:
     info "No record found"
     SetFocusKey1()
     return

FIND_RIU:
     info "Record is locked by another user"
     SetFocusKey1()
     return

FIND_TRAPS:
     info "Cannot find record (unknown error)"
     SetFocusKey1()
     return
}

RELATED TOPICS