HP 3000 Manuals HP 3000 Manuals
DBFIND
INTRINSIC NUMBER 404
Locates master set key item entry that matches the specified search item
value and sets up pointers to the first and last entries of a detail data
set chain in preparation for chained access to the data entries which are
members of the chain. The path is determined and the chain pointers are
located on the basis of a specified search item and its value.
Syntax
DBFIND,base,dset,mode,status,item,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 detail data set to be
accessed, 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 must be an integer equal to 1.
If your database is enabled for third-party
indexing (TPI), refer to your vendor documentation
for additional DBFIND modes. The section on DBUTIL
in chapter 8 of this book has a brief description
of the TPI option.
status is the name of an array of 10 halfwords 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-12 describes
the contents of element 1 when the
procedure does not succeed.
2 Zero.
3-4 Word current record number set to zero.
5-6 Word count of number of entries in
chain.
7-8 Word record number of last entry in
chain.
9-10 Word record number of first entry in
chain.
item is the name of an array containing a left-justified
name of the detail data set search item or is an
integer referencing the search item number that
defines the path containing the desired chain. The
name can be up to 16 characters long. If shorter,
it must be terminated by a semicolon or a blank.
The specified search item defines the path to which
the chain belongs.
argument contains a value for the key item to be used in
calculated access to locate the desired chain head
in the master data set.
If your database is enabled for third-party
indexing (TPI), refer to your vendor documentation
for information on DBFIND arguments. The section
on DBUTIL in chapter 8 of this book has a brief
description of the TPI option.
Discussion
The current values of chain count, backward pointer, and forward pointer
for the detail data set referenced in dset are replaced by the
corresponding value from the chain head. A current path number, which is
maintained internally, is set to the new path number and the current
record number for the data set is set to zero. Refer to chapter 10 for
further information about chain heads and internally maintained data set
information.
Although a master set entry with the specified key item value exists, the
data set chain may be empty.
Note also that a call to DBOPEN does not open individual data sets.
Thus, a call to DBFIND (or DBGET) 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-12. DBFIND 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. |
| | -52 | Bad item. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
| | -258 | Invalid argument for index. |
| | -259 | Invalid mode for index. |
| | -260 | No previous list of qualified data entries. |
----------------------------------------------------------------------------------------------
| Communications Errors: | -102 | DSWRITE failure. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
----------------------------------------------------------------------------------------------
| Exceptional Conditions: | -193 | DBU control block is full. |
| | -3nn | Internal error. |
| | 17 | No master entry. |
| | 63 | DBG disabled; potential damage; only DBCLOSE |
| | | allowed. |
----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.