GET (read a record or entry)

Top  Previous  Next

 

 

 

| 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:

SORT

PUT

POINTER(queue)

POINTER

DUPLICATE

HOLD

WATCH