GET, GET’LOCKED, GET’READ’ONLY
Reviewed and revised October 2024
GET #channel, {wait’record,} isam’key(knum) rel kval, varlist
GET'LOCKED #channel, {wait'record,} isam'key(knum) rel kval, varlist
GET'READ'ONLY #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 or an instance of DEFSTRUCT. 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
if .FSTAT(CUS'CHANNEL) # ISAM_OK and .FSTAT(CUS'CHANNEL) # ISAM_GT goto ISAM'ERROR
The above statements will search the primary index for the record whose key is greater than or equal to "BIG". On failure it jumps to the ISAM'ERROR label, where your code should respond appropriately. Otherwise, it will lock and return the record in the CUS'REC variable and set the fstatvar variable (from the OPEN statement) accordingly. Here we are using the .FSTAT function to test the status; if in same scope, we could have alternately tested the fstatvar variable directly. To remove the record lock, you will need to perform a RELEASE'RECORD or DELETE'RECORD. If the record is found, but is currently locked, then WAIT'RECORD clause will cause the program to 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: Support for dynamic X (X0) record variables added, whether pre-initialized or not.
