The GET Function

D Eloquence Library

The GET Function

The GET funtion retrieves an entry from a data set. The syntax is as follows:

   idb_get(base,dset,mode,status,list,buffer,arg)

   int base;
   void *dset;
   int mode;
   void status[10]
   void *list;
   char *buffer;
   void *arg;

The parameters are:

base: Identifies the database. This must be the return value from the idb_open call.
dset: Identifies the data set in which the entries are to be located. Dset is one of the following:

* a pointer to an integer variable that specifies the data set number;

* a pointer to a character array containing up to 16 characters (bytes) that specifies the data set name. The data set name must be terminated with a semicolon, a blank or '\0' character if it is less than 16 characters.

mode: See access modes below.
status: A pointer to an array of a least 10 elements used to indicate the success or failure of the function call (see below).
list: Usually specifies the data items for which values are to be retrieved and stored in the buffer parameter. With idb_get, only @ is supported, i.e. a value for every data item in the entry will be returned (in the order defined in the data set). List must be a pointer to a character array.
buffer: A pointer to a character array used to return the values of the items specified in the list parameter. The values are returned in the order specified in the list.
arg: Ignored, except in mode 4 and mode 7. If the mode is 4, arg contains a pointer to the record number of the record to be retrieved.; If the mode is 7, arg is a pointer to the value of the key item selected for calculated access.

IDBGET Modes

Mode 1: Reread

idb_get retrieves the current record.

Mode 2: Serial read, forward

idb_get serially retrieves the record after the current record. The retrieved record becomes the current record.

Mode 3: Serial read, backward

idb_get serially retrieves the record before the current record. The retrieved record becomes the current record.

Mode 4: Directed read

idb_get retrieves the entry with the record number specified in the arg parameter.

Mode 5: Chained read, forward

idb_get serially retrieves the next entry in the current chain. Successive calls to idb_get can be executed to retrieve all the entries in the chain. A previous call to idb_find can be used to establish the current chain.

Indexed read, forward

idb_get retrieves the first or next entry in the index order. idb_find on index item is used to define current index. idb_get will fail with end-of-chain condition if no more entries with search value as specified by idb_find can be found.

Mode 6: Chained read, backward

idb_get serially retrieves the previous entry in the current chain.

Indexed read, backward

idb_get retrieves the last/previous entry in index order. idb_find on index item is used to define current index. idb_get will fail with end-of-chain condition if no more entries with search value as specified by idb_find can be found.

Mode 7: Calculated read

idb_get retrieves the entry with the key item value specified in the arg parameter. This mode is only allowed on manual or automatic data sets.

Mode 15: Indexed read forward, ignore "end-of-chain" condition

idb_get reads the first or next entry in current index order. idb_find on index item is used to establish current index. An "end-of-chain" condition will be ignored. idb_get will just retrieve the next entry (in index order) without displaying a message until end-of-file condition.

Mode 16: Indexed read backward, ignore "end-of-chain" condition

idb_get reads the last or previous entry in current index order. idb_find on index item is used to establish current index. An "end-of-chain" condition will be ignored. idb_get will just retrieve previous entry (in index order) without displaying a message until end-of-file condition.

Description

Idb_get retrieves an entry using the access methods specified by the mode parameter. Depending on the list parameter, all or part of the entry may be returned. The values of the data items are placed in the buffer in the same order as they appear in the list parameter. The data returned in the buffer is byte-aligned.

For idb_get to execute successfully, the security class must be in the read class list of the data set specified by dset and in the read class list of the requested items.

The record retrieved by idb_get is the current record for this data set. A data set does not have a current record in the following cases:

The data set has not yet been accessed by idb_get;
The data set was rewound using idb_close mode 3.

To obtain a record number for a directed read (mode 4), call idb_get in another mode and save the record number returned in the status array. The record number can be used for a subsequent directed read. Because each idb function reinitializes the status array, you must copy the record number from the status array into a variable, and then pass the record number back to the idb_get mode 4 later.

NOTE: Entries are not added sequentially, so the record number incremented by 1 is not necessarily the record number of the next entry.

Return value

Returns 0 if successful, or error code if an error was encountered.

Status codes

If idb-get was successfully executed, the status array will contain the following values:

Status codes
Element Meaning
0 S_OK
1 record length
2 0
3 record number
4 0
5 0 if detail set, 1 if master set
6 0
7 backward address (0 if retrieving in index order)
8 0
9 forward address (0 if retrieving in index order)

Status codes
Element	Meaning
0	S_OK
1	record length
2	0
3	record number
4	0
5	0 if detail set, 1 if master set
6	0
7	backward address (0 if retrieving in index order)
8	0
9	forward address (0 if retrieving in index order)

Example

   if(idb_get(dbid,"ORDER",5,status, "@", NULL))
      error_handler();

This will retrieve the next entry from current chain in the ORDER data set.

Eloquence Database Manual - 19 DEC 2002