HP 3000 Manuals HP 3000 Manuals
DBGET
INTRINSIC NUMBER 405
Provides eight different methods for accessing the entries of a data set.
Syntax
DBGET,base,dset,mode,status,list,buffer,argument
Parameters
base is the name of the array used as the base parameter
when opening the database. The first element of
the array must contain the base ID returned by
DBOPEN. (Refer to DBOPEN for more information about
base ID.)
dset is the name of an array containing the
left-justified name of the data set to be read, or
is an integer referencing the data set by number.
The data set name can be up to 16 characters long.
If shorter, it must be terminated by a semicolon or
a blank.
mode contains an integer between 1 and 8, inclusive,
which indicates the reading method. The methods
are:
Mode Method
1 Re-read. Read the entry at the
internally maintained current record
number (argument parameter is ignored).
2 Serial Read. Read the first entry whose
record number is greater than the
internally maintained current number
(argument parameter is ignored).
3 Backward Serial Read. Read the first
entry whose record number is less than
the internally maintained current number
(argument parameter is ignored).
4 Directed Read. Read the entry, if it
exists, at the record number specified
in the argument parameter (argument is
treated as a 32-bit record number).
5 Chained Read. (Detail data sets only.)
Read the next entry in the current
chain, the entry referenced by the
internally maintained forward pointer
(argument parameter is ignored). If
your database is enabled for third-party
indexing (TPI), refer to your vendor
documentation for additional
information.
6 Backward Chained Read. (Detail data
sets only.) Read the previous entry in
the current chain, the entry referenced
by the internally maintained backward
pointer (argument parameter is ignored).
If your database is enabled for
third-party indexing (TPI), refer to
your vendor documentation for additional
information.
7 Calculated Read. (Master data sets
only.) Read the entry with a key item
value that matches the value specified
in argument. The entry is in the master
data set specified by dset.
8 Primary Calculated Read. (Master data
sets only.) Read the entry occupying
the primary address of a synonym chain
using the key item value specified in
argument to locate the entry. The key
item value returned is always that of
the primary entry and might not match
the value specified in argument. (Refer
to chapter 10 for synonym chain
description.)
If your database is enabled for third-party
indexing (TPI), refer to your vendor documentation
for additional DBGET modes. The section on DBUTIL
in chapter 8 of this book has a brief description
of the TPI option.
status is the name of a 10-halfword array in which
TurboIMAGE/XL returns status information about the
procedure. If the procedure executes successfully,
the status array contents are:
Element Contents
1 If the procedure succeeds, the return
status is 0. Table 5-13 describes
the contents of element 1 when the
procedure does not succeed.
2 Length of the logical entry read into
the buffer array in halfwords.
3-4 Word record number of the data entry
read.
5-6 Word zero, unless the entry read is a
primary entry in which case it is the
number of entries in the synonym chain.
7-8 Word record number of the preceding
entry in the chain of the current path.
9-10 Word record number of the next entry in
the chain of the current path.
list is the name of an array containing an ordered set
of data item identifiers, either names or numbers.
The values for these data items are placed in the
array specified by the buffer parameter in the same
order as they appear in the list array.
The list array can contain a left-justified set of
data item names, separated by commas and terminated
by a semicolon or blank. No embedded blanks are
allowed and no name can appear more than once.
When referencing by number, the first element of
the list array is an integer n which is followed by
n unique data item numbers (one-halfword positive
integers).
The list not only specifies the data items to be
retrieved immediately but is saved internally by
TurboIMAGE/XL as the current list for this data
set. The current list is unchanged until a
different list is specified in a subsequent call to
DBGET, DBPUT, or DBUPDATE for the same access path
and data set.
Some special list constructs are allowed. These
are described in Table 5-20 with the DBPUT
procedure. List processing is a relatively high
overhead operation which can be shortened in
subsequent calls by using the asterisk construct to
specify that the current list is to be used. Use
of this construct can save considerable processing
time. However, be sure a current list exists
before using the asterisk or TurboIMAGE/XL will
assume a null list. If a DBCLOSE mode 2 is used
after DBGET, using the asterisk construct,
TurboIMAGE/XL uses the previously defined item
list.
buffer is the name of the array to which the values of
data items specified in the list array are moved.
The values are placed in the same order as
specified in the list array. The number of
elements occupied by each value corresponds to the
number required for each data type multiplied by
the sub-item count.
argument is ignored except when mode equals 4, 7, or 8.
If mode is 4, argument contains a word record
number of the entry to be read.
If mode is 7 or 8, argument contains a key item
value for the master data set referenced by dset.
Discussion
The internal backward and forward pointers for the data set are replaced
by the current path's chain pointers from the entry just read. If the
data set is a master, they are synonym chain pointers (refer to chapter
10). If it is a detail with at least one path, the current path is the
one established by the last successful call to DBFIND; or, if no call has
been made, it is the primary path. If there are no paths defined, the
internal pointers are set to zeros.
The location of the entry just read becomes the current record for the
data set. DBGET mode 5 or 6 will reread the current record and will try
to continue the chain read if it encounters a broken chain.
NOTE A call to DBOPEN does not open individual data sets. Thus, a call
to DBGET (or DBFIND) that accesses a data set for the first time
(or after the data set has been closed), must open the data set.
This causes extra overhead not incurred by subsequent calls to the
same data set by DBFIND or DBGET.
Table 5-13. DBGET Return Status Values
-----------------------------------------------------------------------------------------------
| File System, Memory | -1 | FOPEN failure. |
| Management, and | -3 | FREADDIR failure. |
| Transaction Management | -4 | FREADLABEL failure. |
| Failures: | -168 | Cannot attach n to MPE XL XM: file system error nn. |
| | -169 | Invalid mode for XM attach options. |
| | -175 | Cannot attach n to MPE XL XM: XM error nn. |
| | -176 | Cannot detach n from MPE XL XM: XM error nn. |
| | -178 | Cannot detach n from MPE XL XM: file system error |
| | -209 | nn. |
| | | Invalid mode for XM detach options. |
-----------------------------------------------------------------------------------------------
| Calling Errors: | -11 | Bad database reference. |
| | -21 | Bad data set reference. |
| | -31 | Bad mode. |
| | -51 | Bad list length. |
| | -52 | Bad list or bad item. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
-----------------------------------------------------------------------------------------------
| Communications Errors: | -102 | DSWRITE failure. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
-----------------------------------------------------------------------------------------------
| Exceptional Conditions: | | DBGET Modes |
| | 10 | Beginning of file. (3) |
| | 11 | End of file. (2) |
| | 12 | Directed beginning of file. (4) |
| | 13 | Directed end of file. (4) |
| | 14 | Beginning of chain. (6) |
| | 15 | End of chain. (5) |
| | 17 | No entry. (1,4,7,8) |
| | 18 | Broken chain. (5,6) |
| | 49 | Illegal buffer address. |
| | 50 | Buffer is too small (will only be |
| | | returned if buffer is too small |
| | | and the data transfer would write |
| | | over stack markers in the user's |
| | 62 | stack). |
| | 63 | DBG full. |
| | | DBG disabled; potential damage; |
| | -193 | only DBCLOSE allowed. |
| | -3nn | DBU control block is full. |
| | | Internal error. |
-----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.