4 Database Manipulation

The DBGET Statement

DBGET (base name, data set, mode, status, list, buffer, argument)

The parameters are:

base name

The same string variable used when opening the database.

data set

Either a string expression containing a left-justified data set name or a numeric expression containing a data set number corresponding to the data set's position in the schema definition.

mode

A numeric expression equal to 1, 2, 3, 4, 5, 6, 7, 15, 16.

status

An integer array variable that returns status information after DBGET is executed. The array contains at least ten elements in its right-most dimension.

list

A string expression containing @$\triangle$ or @; or @ ($\triangle$ represents a space). This value means that only the entire entry can be accessed and is referred to as the full record mode.

buffer

A simple string variable in which DBGET returns the specified record entry. The maximum buffer length must equal or exceed the data-set entry length.

argument

Direct access (mode 4)--A numeric expression representing a record number. Calculated access (mode 7)--An expression of the same data type as the master data set's search item.

DBGET Modes

Mode 1: Reread. DBGET retrieves the current record. The value of the argument parameter is ignored for this mode.

Mode 2: Serial read, forward. DBGET serially retrieves the record after the current record. The retrieved record becomes the current record. The value of the argument parameter is ignored for this mode.

Mode 3: Serial read backwards. DBGET serially retrieves the record before the current record. The retrieved record becomes the current record. The value of the argument parameter is ignored for this mode.

Mode 4: Directed read. DBGET examines the record located at the address contained in the argument parameter. If the record is not empty, the entry is copied into the buffer. An error condition is returned in the first word of the status array if the record is empty.

Mode 5: Chained read, forward. The first or next entry of the current chain of the specified detail set is read. DBFIND is used to set the current chain pointer for a detail data set. Indexed read, forward. DBGET retrieves the first or next entry in index order. DBFIND on index item is used to define current index. DBGET will fail with end-of-chain condition if no more entries with search value as given by DBFIND could be found.

The value of the argument parameter is ignored for this mode.

Mode 6: Chained read, backward. The last or previous entry of the current chain of the specified detail set is retrieved. DBFIND is used to set the current chain pointer for a detail data set. Indexed read, backward. DBGET retrieves the last or previous entry in index order. DBFIND on index item is used to define current index. DBGET will fail with end-of-chain condition if no more entries with search value as given by DBFIND could be found.

The value of the argument parameter is ignored for this mode.

Mode 7: Calculated read. This mode is used with master data sets only. The entry with a search item value matching the argument parameter is copied into the buffer. If the search item is numeric, the numeric argument will be converted to the proper type (integer, dinteger, short, or real) before the calculated read is performed.

Mode 15: Next entry in index order. DBGET reads the first or next entry in current index order. DBFIND on index item is used to establish the current index. The value of the argument parameter is ignored for this mode.

Mode 16: Previous entry in index order. DBGET reads the last or previous entry in current index order. DBFIND on index item is used to establish current index. The value of the argument parameter is ignored for this mode.

Eloquence DBMS supports the full record mode of data transfer (list equals @; @). Thus, in all modes, the data items read are those which represent the entire data entry.

DBGET Status Array

Array Element	Value	Description
1	0	CW.
2	Buffer Length	Number of words transferred to the buffer.
3	0
4	Record Number	Integer number of accessed record.
5	0
6	0 or 1	0 for a detail data set. 1 for a master data set.
7	0
8	Backward Address	Integer address of the previous record in a chain.
9	0
10	Forward Address	Integer address of the next record in a chain.

For a detail data set, the forward and backward addresses are always updated relative to the path established by the previous DBFIND applied to the data set.

Array element 8 and 10 will be zero if retrieving in index order.

Record numbers, chain lengths, and forward and backward record addresses fall into the range of 1 through 229-1.