DBFIND(base,dset,mode,status,item,argument)

base

is the name of an 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 the base ID.)

dset

is the name of an array containing the left-justified name of the 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, a space or the NUL character.

mode

must be an integer equal to 1, 4, 10, 21, or 24. Please refer to the TPI Support documentation for additional DBFIND modes.

Mode	Method
1	Used for both B-Tree or non-B-Tree DBFIND. Perform a B-Tree DBFIND if ALL of the following conditions prevail: Item type is X or U (ASCII). DBFIND is for master and a B-Tree index exists on the key item or DBFIND is for detail and B-Tree index exists on the key item of the master to which the search item has a path. BTREEMODE1 flag is set ON. Argument contains a wildcard character. The chain count is accurate in halfword 5-6, and status halfwords 7-8 and 9-10 record the last entry in the last chain, and the first entry in the first chain of the super-chain for detail data sets. For master data sets, the status halfwords 5-6 (chain-count for detail) reflect the total number of entries qualified in the master data set. All other fields of the status array return zeros.
4	For B-Tree searches on numeric as well as ASCII types. For detail data sets, returns accurate chain (super-chain) counts and record numbers of last entry in last chain and first entry in first chain. For masters, returns the total number of qualified entries in status halfword 5-6. Other fields return zeros. Requires a structured argument format described under argument.
10	Allows you to simulate the current DBFIND mode 1, as in versions prior to B-Trees, as if there were no B-Tree index, even when the item has B-Tree index, BTREEMODE1 is on, and the argument contains a wildcard character. It returns accurate chain count. This is the same as TPI mode 10. Requires a simple argument.
21	Same as mode 1, except it is a faster version and does not return accurate chain count or record numbers of first entry and last entries. Requires a simple argument. For details, the chain count and status halfwords 7-8 and 9-10 will have 231-1. For master data sets, the status halfwords 5-6 (chain-count for detail) reflect the total number of entries qualified in the master data set. All other fields of the status array return zeros. A DBFIND mode 21 on a non-ASCII key returns an error.
24	Same as mode 4, except it is a faster version and does not return accurate chain counts and record numbers of last entry and first entry in super-chain. For detail data set, the halfwords 5-6, 7-8, and 9-10 will have 231-1. For master data set, the halfword 5-6 will have 231-1 and 7-8 and 9-10 will have zeros. The argument is in structured format described under argument.

Eloquence supports the TPI modes for database access. Please refer to the TPI Support documentation for additional DBFIND modes.

status

is the name of an array of 10 halfwords in which the database 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. Otherwise it provides a status code to describe the failure.
2	Zero.
3-4	Word record number set to zero (32 bit).
5-6	Word count of number of entries in chain or qualifier (32 bit). For modes 21 and 24 231-1 is returned.
7-8	If detail, word record number of last entry on current detail chain (32 bit). For modes 21 and 24 231-1 is returned.
9-10	If detail, word record number of first entry on current detail chain (32 bit). For modes 21 and 24 2^31-1 is returned.

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 specified search item defines the path to which the chain belongs. For a B-Tree DBFIND on a master, it is the key item name or a number. The name can be up to 16 characters long. If shorter, it must be terminated by a semicolon, a space or the NUL character.

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 for non-B-Tree index searches. This is referred to as a simple argument. For B-Tree index searches, there are two formats. One is for mode 1 wildcard searches on X and U types and allows a trailing wildcard character. The argument is scanned for the first occurrence of the wildcard character, for example, an @ character. Subsequent text in the item value is ignored.

The other is for modes 4 and 24, which requires a structured format.

Structured format argument

Bytes	Meaning
1-2	Type of generic search. An ASCII character pair is in this field: =_ search for key values equal to argument1 (similar to a DBFIND mode 1) <_ search for key values less than argument1 <= search for key values less than or equal to argument1 >_ search for key values greater than argument1 >= search for key values greater than or equal to argument1 [] search for key values greater than or equal to argument1 AND less than or equal to argument2 @c wildcard search when the wildcard character is c. Scan argument for the first wildcard character c. If a wildcard character is found in position n, 1-based, search for keys that match first n-1 characters of argument. If c is non-blank and non-null, then it is the wildcard character that will be used. Some examples are: @* and @@. If c is a blank or null, then the one set by DBCONTROL mode 15, if any, is used. Otherwise, the current default wildcard character is used. The wildcard character is changeable via the DBUTIL SET command or DBCONTROL mode 15. PK Partial Key search. Search for key values that match n characters in argument1 (n is length of argument1 provided in bytes 4 and 5 described later). Argument1 need not contain a wildcard. If it does within the n characters, it will be considered as one character part of the search value. For example, if n is 4, argument1 is ABC@, and the wildcard to be used is @, DBFIND will return records containing ABC@ as the first four characters in the key value. Note: _ indicates a space character.
3-4	version number. Must be numeric zero, or an error is returned.
5-6	The size (in bytes) of argument1 (not including these two bytes) for search types =, <, <=, >, >=, @c, PK.
7-8	The size (in bytes) of argument2 (not including these two bytes) for the search type []. Must be numeric zero for other search types, or an error is returned.
9... 9+n-1	Argument1. The n bytes of argument data (for example, for an X10 field, n = 10).
9+n... 9+n+m-1	Argument2. For search-type [] only. The m bytes of the second argument's data (for example, for an X10 field, m = 10, n must match m).

If a wildcard character is present in the argument(s), the wildcard will be considered as part of the value for these B-Tree search types: =, <, <=, >, >=, [ ], or PK on ASCII types.

Notes:

• Eloquence supports using the DBFIND 1,4,21 and 24 on TPI indexes.

• Eloquence supports the TPI modes for database access. Please refer to the TPI Support documentation for additional DBFIND modes.