| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions >====== GET (read a record or entry) ====== | [[freeze suspend control redrawing .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[getexitcode query program exit code .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

|  |  | |// file //,// key//| |
|  | **GET(** | |// file //,// filepointer// [,// length //]| **)** |
|  |  | |// key //,// keypointer//| |
|  |  | |// queue// ,// pointer//| |
|  |  | |// queue// , [**+**]//key//,...,[**-**]//key//| |
|  |  | |// queue// ,// name//| |
|  |  | |// queue// ,// function//| |

{{blk2blue.jpg|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.htm#queuekeyparameter|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|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|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.htm#queuekeyparameter|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  sort queue entries .htm|SORT]]

[[add  add an entry .htm|ADD]]

[[append  add a new file record .htm|APPEND]]

[[put  re write record .htm|PUT]]

[[pointer  return last queue entry position .htm|POINTER(queue)]]

[[pointer  return relative record position .htm|POINTER]]

[[delete  delete a record .htm|DELETE]]

[[duplicate  check for duplicate key entries .htm|DUPLICATE]]

[[hold  exclusive record access .htm|HOLD]]

__[[watch  automatic concurrency check .htm|WATCH]]__