GET
Get a record in a database.

Format
 Get [expr] | from DATABASE | [/Qualifiers ...]
 | in DATABASE |
 exprKey, record number, or record ID of the record to get, or the limit if the /LIMIT qualifier is specified without a limit expression.
 If the current record for this database has been modified, it is written back to the record stream before any other record operation takes place. If an error occurs during this write-back operation (e.g. duplicate key, record not locked for write, etc.), and error is generated for this statement. The record remains current, but is now considered to be unchanged so that the next record operation will not attempt another write-back.
 NOTE
 Keep in mind the effect this statement has on other users. If the record is locked, no one else can get the same record unless they specify READ_REGARDLESS. If you are not specific with locking modes, UserBase uses the database opening options to get the record. It then attempts to promote locks upward so that record operations can occur. Note that this may cause two record I/O's (instead of one) to get the record back with the right lock mode. It is much better to be specific. The default opening mode for RMS databases is to LOCK FOR WRITE access (lock it when getting it so that it can be written to). If the record is not going to be modified, specify /LOCK=none so that the record is not tied up. Otherwise, UNLOCK it if it may be some time before the record is modified.
 Another option is to oopen the database with "LOCK=NONE". However, remember that if the record is written to, unless you were specific with a /LOCK=write, the record must be retrieved again and this will destroy any record context (getting a series of records by key).

Qualifiers
/Fail=LABELLabel to which to branch if the statement fails.
If LABEL is %EXIT, exit the routine or loop.
If in a loop, and LABEL is %CONTINUE, continue the loop. If not in a loop, and LABEL is %CONTINUE, an error message displays.
 /Succeed=LABELLabel to which to branch if the statement succeeds.
If LABEL is %EXIT, exit the routine or loop. If in a loop, and LABEL is %CONTINUE, continue the loop. If not in a loop, and LABEL is %CONTINUE, an error message displays.
 /NofailDo not signal an error. Instead, set the
internal variable %FAIL.
 /FlushFlush the record stream so that the record is physically on disk.
 /LoadUse the load factor of the RMS datafile if specified.
 /Lock=(lock_options, ... )Use the following lock options to lock the record if it is automatically retrieved (by accessing a field in that record).
 exclusiveLock against all other record streams except READ_REGARDLESS.
 manualRecords remain locked until explicitly unlocked.
 noneRecords are not to be locked.
 nonexistentProceed with the operation even if the record does not exist (RMS relative files only).
 nowaitDo not wait if the record is locked (return an error).
 readLock the record for reading while allowing other record streams to read but not modify (ignored if write also specified).
 read_regardlessRead records even if another record stream has them locked.
 wait=nWait n seconds before returning an error if the record is locked.
 writeLock the record for writing while allowing other record streams to read but not modify.
 /GenericThe key is generic; to not pad to full key size (RMS indexed files only). this qualifier is used to get a range of records starting with a particular value. Note that it does not make any sense to use this with fields that are right justified, or zero filled (among others).
 /Limit [= limit_expr]Get the next sequential record up to a specified limit. If the limit expression is omitted then the expression specified after GET is taken to be the limit. It is also usually used with the /GENERIC qualifier to get a particular range of records starting with a particular value. Note that you must first to a GET without a /LIMIT or a REWIND to initialize the record context.
 /NextGet the key "after" the specified expression.
Example:
! are there any salaries 15,001 - 15,999
Get 15000 in RMS /Key=RMS(SALARY) &
/Next &
/Fail:NONE
If RMS(SALARY) = 16000 then Goto NONE
 /Eqnext
/Nexteq
Get the key equal to or "after" the specified expression. This qualifier is useful when a range of records is required, and the starting value may not exist.
Example:
! are there any salaries 15,000 - 15,999
Get 15000 in RMS /Key=RMS(SALARY) &
/Nexteq &
/Fail:NONE
If RMS(SALARY) = 16000 then Goto NONE
 /Key=DATABASE(#expr)
/Key=DATABASE(FIELD)
The key field on which to perform the operation. This qualifier can be omitted if the operation is on the primary key.
 /RidDo the operation by record ID.
This qualifier is used to retrieve a record that has previously been found, and the record ID has been saved from the database internal variable
DB(%RID). This is the fastest way of retrieving a record (rather than doing a lookup by key).
 /RecordDo the operation by record number.
The expression is a number that corresponds to the record's relative position in the datafile.

Examples
 Below are examples of the different ways to get a series of records. The first is the older syntax requiring two GETs. The second is the newer (more preferred method) requiring only a REWIND. The REWIND is there so that the first time the GET is executed it does a get-by-key (because there is no current record), and subsequently it does a get-with-limit.
 Example 1
 Get "SMITH" in RMS /Generic /Key=RMS(SURNAME)
 ! Get the first surname starting with "SMITH"
 Loop
 Gosub PROCESS_RECORD
 Get "SM" in RMS /Generic &
/Limit &
/Key=RMS(SURNAME) &
/Fail=%EXIT
 ! Get all subsequent records starting with "SM"
 End_loop
 
 Example 2
 Rewind/Key=RMS(SURNAME)
 ! Initialize the record context
 Loop
 Get "SMITH" in RMS /Generic &
/Limit="SM" &
/Key=RMS(SURNAME) &
/Fail=%EXIT
 ! Get records between "SMITH" and "SM??????..."
 Gosub PROCESS_RECORD
 End_loop