| Format |
| | Get [expr] | from DATABASE | [/Qualifiers ...] | |
| |  | in DATABASE | | |
| | expr | Key, 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=LABEL | Label 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=LABEL | Label 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. | | |
| | /Nofail | Do not signal an error. Instead, set the
internal variable %FAIL. | | |
| | /Flush | Flush the record stream so that the record is physically on disk. |
| | /Load | Use 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). |
| | exclusive | | Lock against all other record streams except READ_REGARDLESS. |
| | manual | | Records remain locked until explicitly unlocked. |
| | none | | Records are not to be locked. |
| | nonexistent | | Proceed with the operation even if the record does not exist (RMS relative files only). |
| | nowait | | Do not wait if the record is locked (return an error). |
| | read | | Lock the record for reading while allowing other record streams to read but not modify (ignored if write also specified). |
| | read_regardless | | Read records even if another record stream has them locked. |
| | wait=n | | Wait n seconds before returning an error if the record is locked. |
| | write | | Lock the record for writing while allowing other record streams to read but not modify. |
| | /Generic | The 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. |
| | /Next | Get 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. |
| | /Rid | Do 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). |
| | /Record | Do 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 |
| | |