Reviewed and revised July 2020
GET #channel, {wait’record,} isam’key(knum) rel kval, varlist
The various forms of the GET statement are used to directly locate and read a record based on a key value. Logically this may be considered a combination of two operations: one to lookup the key and the other to read the record.
channel
the integer expression whose value matches that specified in the OPEN statement.
The optional wait’record clause causes the operation to wait until the record is available (just as if wait'record was specified in the OPEN statement.)
knum
integer expression indicating which logical index to search in. The primary index is 0, the first secondary index is 1, etc.
rel
is one of the following logical comparison operators, relating the key to be found with the key specified:
Relation |
Meaning |
|---|---|
< |
less than |
<= |
less than or equal |
= |
equal |
> |
greater than |
>= |
greater than or equal |
kval
an expression indicating the key to start for in the specified index.
varlist
a list of variables to receive the data. Although it is technically legal to list several variables, the recommended approach is to specify a single unformatted record variable which is broken into fields by means of lower level MAP statements.It may also be a Dynamically Sized Variables (X,0), in which case you would subsequently need to copy it to a structure in order to break out the individual fields. See History.
The fstatvar variable, from the OPEN statement (if within the current scope) or from .fstat(channel), will be set according to the key found (or not found). If the key is found, the recnovar variable will also be set to the record number (although as mentioned before, you don't need to do anything with this information).
For example:
GET'LOCKED #CUS'CHANNEL, WAIT’RECORD, KEY(0) >= "BIG", CUS'REC
The above statement will search the primary index for the record whose key is greater than or equal to "BIG", and if successful, will lock and return the record in the CUS'REC variable and set the fstatvar variable (from the OPEN statement) accordingly. To remove the lock, you will need to perform a RELEASE'RECORD or DELETE'RECORD. If the record is found, but is currently locked, then the program will wait.
Comments
If you just want to read the current record (perhaps to lock it after a GET'NEXT'READ'ONLY), without having to re-locate it in the index, you can use one of the READ for ISAM-A variants. Do not, however, attempt to use a WRITE statement on an ISAM-A file! Always use UPDATE'RECORD instead.
History
2020 June, A-Shell 6.5.1684: READ, XREAD and ISAMA GET operations now work with dynamic X (X0) record variables, regardless of whether they are pre-initialized. Previously this only worked if the variable was pre-initialized to the size of the record.
