D Eloquence Library

The FIND Function

The FIND function establishes the current chain or index in preparation for access. The syntax is as follows:

   idb_find(base,dset,mode,status,item,arg)

   int base;
   void *dset;
   int mode;
   int status[10]
   void *item;
   void *arg;
The parameters are:

base
Identifies the database. This must be the return value from the idb_open call.
dset
Identifies the data set in which the entries are to be located. Dset is one of the following:
* a pointer to an integer variable that specifies the data set number;

* a pointer to an character array containing up to 16 characters (bytes) that specifies the data set name. The data set name must be terminated with a semicolon, a blank or 0 character if it is less than 16 characters.

mode
One of the access modes. See below.
status
A pointer to an array of a least 10 elements used to indicate the success or failure of the function call.
item
If the mode is 1, item identifies the search item to be used. It can be one of the following:
* a pointer to an integer variable that specifies the search item number;

* a pointer to a character array containing up to 16 characters (bytes) that specifies the search item name. The search item name must be terminated with a semicolon, a blank or 0 character if it is less than 16 characters.

If the mode is 2 or 3, item identifies the index to be used. It can be one of the following:
* a pointer to an integer variable that specifies the index item number;

* a pointer to a character array containing up to 16 characters (bytes) that specifies the index item name. The index item name must be terminated with a semicolon, a blank or 0 character if it is less than 16 characters.

If the mode is 4 or 5, item identifies the index to be used. It can be one of the following:
* a pointer to an integer variable that specifies the index item number;

* a pointer to a character array containing up to 16 characters (bytes) that specifies the index item name. The index item name must be terminated with a semicolon, a blank or 0 character if it is less than 16 characters.

arg
If the mode is 1 and item specifies a search item, arg contains a pointer to search for the item value to be used to identify the chain.
If mode is 1 and item specifies an index, or the mode is 2 or 3, arg contains a pointer to index lookup value.
If mode is 4 or 5, arg contains a pointer to a regular expression. This is set up in the same way as index lookup values (Modes 2, 3).
Example:
                struct {
                   int len;         /*number of bytes in value area */
                   char value[...]; /*the actual key value          */
                } arg;
             

IDBFIND Modes

Mode 1: Find chain head/match subset

Idb_find will locate chain head or match subset depending on the item parameter. The item parameter may be either a search item or an index item.

If the item parameter specifies a search item:

The arg parameter is a pointer to search for the item value to be used to identify the chain. The length and type of the buffer specified by the arg parameter must match the specified item.

If the item parameter specifies an index item:

The arg parameter is a pointer to the index value to be used to identify the subset. The type of buffer specified by the arg parameter must match the specified index in the given length.

NOTE: For performance considerations, accessing indexes using mode 1 is not recommended. In order to return first/last record pointer and number of records, all matching records are read.

Mode 2: Find first entry

Locates the first matching entry in a given index.

The item parameter specifies which index to use. The arg parameter is a pointer to the index value to be used to identify the subset. The type of buffer specified by the arg parameter must match the specified index in given length.

Mode 3: Find last entry

Locates the last matching entry in given index.

The item parameter specifies which index to use. The arg parameter is a pointer to the index value to be used to identify the subset. The type of buffer specified by the arg parameter must match the specified index in given length.

Mode 4: Find first entry with matching regular expression

Locates the first entry matching the regular expression in index order.

The index parameter must refer to an index item. The index item must contain at least one leading string segment.

The arg parameter is a pointer to the regular expression to be used to identify the subset.

The given regular expression must exactly describe the leading string segments. There is no implicit '*' at the end (as DBFIND Modes 2/3). If you store "AAA " (trailing space) in an entry, you won't find it using a search value of "AAA", but you will find it using "AAA?" or "AAA*".

The entries will be retrieved using DBGET Modes 5/6 in index order.

Mode 5: Find last entry with matching regular expression

Locates the last entry matching the regular expression in index order.

DBFND Mode 5 operates in the same way as Mode 4, except that it 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 because this would result in a serial access to the dataset specified.

NOTE: Status may return a 0 in the first status array element although there is no matching entry in the dataset specified. A subsequent DBGET will return 15 (end-of-chain) in the first status array element.

Description

idb_find is used with detail data sets to establish a current chain for the specified data set. This is done in preparation for using idb_get with mode 5 or 6, which retrieve entries that belong to the current chain. The current chain is determined by the search item specified in the item parameter. Each current chain is associated with a specific data set in the database and is also associated with the relationship defined by the base parameter.

idb_find tries to locate the corresponding entry in the parent set (identified by search item). There may not actually be any entries in the specified data set with a matching search item value. In this case, the idb_find call will execute successfully, but the subsequent idb_get call will return an "end-of-chain" status code.

idb_find is used with indexed access to locate the first or last entry with a matching index value. This is done in preparation for using idb_get with modes 5,6,15 or 16, which retrieve entries in index order. The current index is determined by the index item specified in the item parameter.

idb_find verifies that the item parameter references an index item for the specified data set. It then locates the argument value in the appropriate index. If the argument paramater has a length value of zero, this is simply the first or last record (in index order). If a matching value cannot be found, the record pointer will be located at the position in the index where the requested value would be inserted.

If the index item segment is of type character ('X') you can just use a part of it in the index access. However if the index item segment is a numeric one, you have to specify the whole segment or it will be ignored (what's the first byte of 123.456E-2 ?).

Beware of alignment trap. For example: if you specify a construction like the following:

            {
               char x[2];
               long d;
            }
there will be a 2 byte gap between the character array and the long value (longs must be 4 byte aligned). Idb_find will assume that there is no gap between data.

For idb_find to execute successfully, the security class must have at least read access to the data set specified by dset and to the search item specified by item. It is not necessary to have read access to the parent of that data set. Idb_find does not retrieve any data.

Return value

Returns 0 if successful, or error code if an error was encountered.

Status codes

If idb-find was successfully executed, the status array will contain the following values:

Status codes
ElementMeaning
0S_OK
10
20
30
40
5number of entries (mode 1 only)
60
7backward address (mode 1)
80
9forward address (mode 1)

Example

   int itemno;
   int product_no;

   itemno = 5;           /* PRODUCT-NO item */
   product_no = 4711;    /* product number   */

   if(idb_find(dbid,"ORDER",1,status,&itemno, &product_no))
      error_handler();
This will find the chain head for PRODUCT-NO in ORDER data set.

The following example assumes that an index has been defined for the data set "SAMPLE-SET", consisting of the following items:

   ITEM:
      CODE, X2;
      GROUP, I;

   IITEM:
      SAMPLE-INDEX = CODE,GROUP;
Now let's try to locate all entries with a code starting with 'A' in ascending order.

   struct {
      int len;
      char code[2];
   } sample_key;

   sample_key.len = 1;
   sample_key.code[0] = 'A';

   if(idb_find(dbid,"SAMPLE-SET",2,status,"SAMPLE-INDEX", &sample_key))
   {
      if(status[0] == S_NOREC) {
         printf("No entry with selected type code");
         ...
      }
      else error_handler();
   }

   while(idb_get(dbid, "SAMPLE-SET, 5, status, "@", buffer, 0) == S_OK) {
      /* ... got the next entry ... */
   }
   if(status[0] != S_ENDCHAIN)
      error_handler();

Eloquence Database Manual - 19 DEC 2002