Reading the next record matching current search data¶
match[u] |
Read the next record matching current search data |
SYNTAX
match | matchu record_id [index = index_id] [nsr = label] [riu = label] [traps = label]
Unlocks any existing record in the file locked by the program, starts its search at the current file position and reads the next record in ascending key sequence whose key matches the key supplied in the previous find command on that file. The match command locks the record if the file is open in update mode and this program does not have a readlock on the file. The record is now selected, and may be written back or deleted. The matchu command does not lock the record, regardless of the file mode
No record is found by match if a find command on this file has not previously been performed. See find for full details of key matching.
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 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. If this clause is present, then match operates with respect to the previous find on this index. If no find has previously been performed on this index, the No such record condition is generated. |
[nsr = label] |
Traps the condition where no matching record exists, or where no previous find has been executed on the file. Control passes to the line indicated by label. Any existing locked record in the file is unlocked. The file position is unchanged. 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. If an untrapped riu condition occurs in a !report section, the match[u] command is ignored. |
[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 key data for the last find and match is not affected by the clear command or by other file access or update commands, although file access and update commands which update the file position change the starting position for the next match.
If batch read mode has been set for the file in client/server mode, a read-only match[u] command causes a batch of records to be obtained from the server. See Batch file read mode.
EXAMPLE
find Sales nsr = M_RETURN
while (1) {
ProcessRecord()
match Sales nsr = break
}
M_RETURN:
return
RELATED TOPICS |