D Eloquence Library
The GET Function
The GET funtion retrieves an entry from a data set. The syntax is as follows:
The parameters are:
* a pointer to an integer variable that specifies the data set number;
- Identifies the database. This must be the return value from the idb_open call.
- Identifies the data set in which the entries are to be located. Dset is one of the following:
* 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.
- See access modes below.
- A pointer to an array of a least 10 elements used to indicate the success or failure of the function call (see below).
- 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.
- 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.
- 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.
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.
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:
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.
- The data set has not yet been accessed by idb_get;
- The data set was rewound using idb_close mode 3.
NOTE: Entries are not added sequentially, so the record number incremented by 1 is not necessarily the record number of the next entry.
Returns 0 if successful, or error code if an error was encountered.
If idb-get was successfully executed, the status array will contain the following values:
|5||0 if detail set, 1 if master set|
|7||backward address (0 if retrieving in index order)|
|9||forward address (0 if retrieving in index order)|
if(idb_get(dbid,"ORDER",5,status, "@", NULL))
This will retrieve the next entry from current chain in the ORDER data set.
Eloquence Database Manual - 19 DEC 2002