User Tools

Site Tools


get_read_a_record_or_entry_.htm
Navigation:  Language Reference > 13 - Built-in Functions >====== GET (read a record or entry) ====== Previous pageReturn to chapter overviewNext page
file , key
GET( file , filepointer [, length ] )
key , keypointer
queue , pointer
queue , [+]key,…,[-]key
queue , name
queue , function

blk2blue.jpg

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

black.jpg

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

black.jpg

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:

SORT

ADD

APPEND

PUT

POINTER(queue)

POINTER

DELETE

DUPLICATE

HOLD

WATCH

get_read_a_record_or_entry_.htm.txt · Last modified: 2021/04/15 15:57 by 127.0.0.1