4 Database Manipulation

The DBFIND Statement

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:

base name

The string variable used when opening the database.

data set

Either a string variable containing a left-justified data set name or a numeric variable 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.

status

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

item

A string expression containing a left-justified search item or index item name, or a numeric expression containing a search item or index item number. The search item number represents the relative position in the (index item part) schema definition starting with the number of defined items plus 1; search item or index item numbers are integers ranging from 1 to 1024.

argument

Contains a value for the search item or index item to be used.

DBFIND Modes

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.

Chained Access

Indexed Access

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/DBGET modes with indexed access

Mode 1 v. Mode 2

NOTE: Do not use DBFIND mode 1 on index items if you are expecting a large number of data set entries.

DBFIND Status Array

Array Element	Value	Description
1	0	CW.
2	0
3	0
4	0
5	0
6	Chain Length	Integer count of entries in the current chain.
7	0
8	End of Chain Address	Integer address of the last record in the chain.
9	0
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.

Regular Expressions

[

starting delimiter of character class expression

]

ending delimiter of character class expression

!

negation expression (only as 1st character of character class)

-

range expression (only inside a character class)

?

any character

*

any string (including the empty string)

#

numeric character (same as [0-9])

\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:

A[BCD]

Index value starts with A, followed by either a B, C or D.

BOB?*

Index value starts with BOB, followed by at least one character.