D Eloquence Library
idb_find(base,dset,mode,status,item,arg) int base; void *dset; int mode; int status[10] void *item; void *arg;The parameters are:
* 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.
* 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.
* 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.
* 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.
struct {
int len; /*number of bytes in value area */
char value[...]; /*the actual key value */
} arg;
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.
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.
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.
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.
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.
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.
| Element | Meaning |
|---|---|
| 0 | S_OK |
| 1 | 0 |
| 2 | 0 |
| 3 | 0 |
| 4 | 0 |
| 5 | number of entries (mode 1 only) |
| 6 | 0 |
| 7 | backward address (mode 1) |
| 8 | 0 |
| 9 | forward address (mode 1) |
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();