4 Database Manipulation
DBFIND is used with indexed access and establishes current index and locates matching value in index table.
DBFIND (base name, data set, mode, status, item, argument)
The parameters are:
Mode 1: Find chain head. If the item refers to a search item (an item linked to a master set in schema definition), DBFIND will set up the current chain and locate the chain head. The specified search item defines the path to which the chain belongs. The data set parameter must reference a detail data set. DBFIND uses the argument value to locate the desired chain head in the master data set (using calculated access). The argument and the search item data types must match. DBFIND converts numeric arguments to the search item numeric data type during execution.
First matching record. If an item refers to an index item, DBFIND will set up the current index and locate the first matching value in the index. If the argument is an empty string, the first record (in index order) will be located. (See discussion below on comparison between modes 1 and 2.)
Mode 2: First matching record. The item parameter must refer to an index item. DBFIND will set up the current index and locate the first matching value in the index. If the argument is an empty string, the first record (in index order) will be located.
Mode 3: Last matching record. The item parameter must refer to an index item. DBFIND will set up the current index and locate the last matching value in the index. If the argument is an empty string, the last record (in index order) will be located.
Mode 4: Find first matching record with matching regular expression. The item parameter must refer to an index item. DBFIND will set up the current index and locate the first matching value in the index. The index item must contain at least one leading string segment.
The given expression must describe the leading string segments exactly. There is no implicit '*' at the end (as in DBFIND Modes 2/3). If you store "AAA " (trailing space), in an entry, you won't find it using a value of "AAA", but you will find it if you use "AAA*" or "AAA?".
The entries will be retrieved using DBGET Mode 5/6 in index order.
Mode 5: Find last record with matching regular expression. Same as Mode 4, but locates the last entry.
NOTE: Access time depends on the regular expression given. We do not recommend specifying a character class or a wildcard character at the beginning of the regular expression, as this would result in a serial access to specified data set.
NOTE: Status may return to 0 in the first status array element, although there is no matching entry in the dataset. A subsequent DBGET will return 15 (end-of-chain) in the first status array element.
The numeric argument may be given as a string value independent of index item definition. String value must be set up by PACK USING statement. It is valid to give a shorter search value for a string item. DBFIND will locate the first (or last) entry with matching value. If numeric items are truncated they will be ignored in locating index position.
If the first part of the index item referenced by the item parameter is numeric then the argument parameter may be numeric. DBFIND converts numeric arguments to the item numeric data type during execution. Only the first item is significant in locating index position.
|DBFIND mode||DBGET mode||Relation||Comment|
|2||5||equal||first record with matching index value|
|2||16||less||last record before matching index volume|
|3||6||equal||last record with matching index value|
|3||15||greater||first record after matching index value|
NOTE: Do not use DBFIND mode 1 on index items if you are expecting a large number of data set entries.
|6||Chain Length||Integer count of entries in the current chain.|
|8||End of Chain Address||Integer address of the last record in the chain.|
|10||Chain Head Address||Integer address of the first record in the chain.|
Status array elements 6, 8, 10 are zero in DBFIND modes 2 and 3.
\b - becomes backspace
\t - becomes tab
\r - becomes cr
\n - becomes lf
\f - becomes ff
\s - becomes space
The above combinations conform to the HP-UX standard, and are extremely practical.
Evaluation An evaluation is only possible with index items, and then only for leading string segments. Index items without leading string segments cannot be accessed.
A regular expression must exactly describe the contents of the leading string segments. There is no implicit "*" at the end (as in DBFIND 2/3). For example, the value "AAA "(trailing space) does not match the search expression "AAA".
Examples of regular expressions: