| Navigation: Language Reference > 13 - Built-in Functions >====== GET (read a record or entry) ====== |    |
| file , key | ||||
| GET( | file , filepointer [, length ] | ) | ||
| key , keypointer | ||||
| queue , pointer | ||||
| queue , [+]key,…,[-]key | ||||
| queue , name | ||||
| queue , function |
| GET | Retrieves a specific record from a FILE or entry from a QUEUE. |
| file | The label of a FILE declaration. |
| key | The label of a KEY or INDEX declaration. |
| filepointer | A numeric constant, variable, or expression for the value returned by the POINTER(file) procedure. |
| length | An integer constant, variable, or expression which contains the number of bytes to read from the file. The length must be greater than zero and not greater than the RECORD length. If omitted or out of range, length defaults to the length of the RECORD structure. |
| keypointer | A numeric constant, variable, or expression for the value returned by the POINTER(key) procedure. |
| queue | The label of a QUEUE structure. |
| pointer | A numeric constant, variable, or numeric expression. The pointer must be in the range from 1 to the number of entries in the memory queue. |
| + - | The leading plus or minus sign specifies the key is sorted in ascending or descending sequence. |
| key | The label of a field declared within the QUEUE structure. If the QUEUE has a PRE attribute, the key must include the prefix. |
| name | A string constant, variable, or expression containing the NAME attribute of QUEUE fields, separated by commas, and optional leading + or - signs for each attribute. This parameter is case sensitive. |
| function | The label of the function containing two parameters of a *GROUP or named GROUP passed by address, and having a SIGNED return value. Both parameters must use the same parameter type, and cannot be omitted. The RAW, C and PASCAL attributes are not permitted in the prototype declaration. See Additional Queue Considerations. |
The GET statement locates a specific record in a FILE or specific entry in a QUEUE and retrieves it.
FILE Usage
The GET statement locates a specific record in the data file and reads it into the RECORD structure data buffer. Direct access to the record is achieved by relative record position within the file, or by matching key values. If the GET is unsuccessful, the previous content of the RECORD buffer is not affected.
| GET(file,key) | Gets the first record from the file (as listed in the key) which contains values matching the values in the component fields of the key. |
| GET(file,filepointer [,length]) | Gets a record from the file based on the filepointer relative position within the file. If filepointer is zero, the current record pointer is cleared and no record is retrieved. |
| GET(key,keypointer) | Gets a record from the file based on the keypointer relative position within the key. |
The values for filepointer and keypointer are file driver dependent. They could be: record number; relative byte position within the file; or, some other kind of “seek position” within the file. If the filepointer or keypointer value is out of range, or there are no matching key values in the data file, the “Record Not Found” error is posted.
The DUPLICATE procedure assumes that the contents of the RECORD structure data buffer are duplicated at the current record pointer location. Therefore, when using DUPLICATE prior to ADDing a record, the record pointer should be cleared with: GET(file,0).
QUEUE Usage
GET reads an entry into the QUEUE structure data buffer for processing. If GET does not find a match, the “Entry Not Found” error is posted.
| GET(queue,pointer) | Retrieves the entry at the relative entry position specified by the pointer value in the order the QUEUE entries were added, or last SORTed. If pointer is zero, the value returned by the POINTER procedure is set to zero. |
| GET(queue,key) | Searches for the first QUEUE entry that matches the value in the key field(s). Multiple key parameters may be used (up to 16), separated by commas. If the QUEUE has not been SORTed on the field(s) used as the key parameter(s), the key indicates an “alternate sort order” which is then cached (making a subsequent SORT on those same fields very efficient). |
| GET(queue,name) | Searches for a QUEUE entry that matches the value in the name field(s). The name string must contain the NAME attributes of the fields, separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence. If the QUEUE has not been SORTed on the named field(s), the name indicates an “alternate sort order” which is then cached (making a subsequent SORT on those same fields very efficient). |
| GET(queue,function) | GET by FUNCTION will read from a positional value returned by the function. See Additional Queue Considerations. |
Errors Posted:
| 08 | Insufficient Memory |
| 30 | Entry Not Found |
| 35 | Record Not Found |
| 36 | File Not Open |
| 43 | Record Is Already Held |
| 75 | Invalid Field Type Descriptor |
Example:
NameQue QUEUE,PRE(Que)
Name STRING(20),NAME('FirstField')
Zip DECIMAL(5,0),NAME('SecondField')
END
Customer FILE,DRIVER('Clarion'),PRE(Cus)
NameKey KEY(Cus:Name),OPT
NbrKey KEY(Cus:Number),OPT
Rec RECORD
Name STRING(20)
Number SHORT
END
END
CODE
DO BuildQue !Call routine to build the queue
GET(NameQue,1) !Get the first entry
IF ERRORCODE() THEN STOP(ERROR()) END
Que:Name = 'Jones' !Initialize key field
GET(NameQue,Que:Name) !Get the matching record
IF ERRORCODE()
STOP(ERROR())
END
Que:Name = Fil:Name !Initialize to value in Fil:Name
GET(NameQue,Que:Name) !Get the matching record
IF ERRORCODE() THEN STOP(ERROR()) END
Que:Name = 'Smith' !Initialize the key fields
Que:Zip = 12345
GET(NameQue,'FirstField,SecondField') !Get the matching record
IF ERRORCODE() THEN STOP(ERROR()) END
LOOP X# = 1 TO RECORDS(NameQue)
GET(NameQue,X#) !Loop through every entry in the QUEUE
IF ERRORCODE() THEN STOP(ERROR()) END
!Process the entry
END
Cus:Name = 'Clarion' !Initialize key field
GET(Customer,Cus:NameKey) !get record with matching value
IF ERRORCODE() THEN STOP(ERROR()) END
GET(Customer,3) !Get 3rd rec in physical file order
IF ERRORCODE() THEN STOP(ERROR()) END
GET(Cus:NameKey,3) !Get 3rd rec in keyed order
IF ERRORCODE() THEN STOP(ERROR()) END
See Also: