Database functions
[ Main document |
Back ]
Contents:
DBOPEN has been changed to return a more specific status when it fails
to open a database.
- Status -21 is returned if the user has no access to the database.
When the user is a member of an administrative group for the database
(as the database creator is by default), opening the database
succeeds although no access to any data set may be possible.
- Status -92 is returned, when the database is not created.
When the current user is a member of an administrative group (as
the database creator is by default), opening the database succeeds
although it has not been created.
- Status -3 or -4 is returned if the user is either unknown to
the server process or the wrong password was provided.
- Status -2 is returned when the database cannot be opened
in the specified mode (due to a concurrent open).
The tenth status element returns additional information:
- 1 - The database is opened concurrently in an exclusive mode
- 2 - The database cannot be opened in an exclusive mode because
it is in concurrent use
- 3 - The database can only be opened in readonly mode (concurrent
open in mode 8)
- 4 - The database cannot be opened in read exclusive mode (mode 8)
because it is opened concurrently in read/write mode
This status is
returned as -1 in the Eloquence language for compatibility reasons.
- Status -1 is returned otherwise.
The new DBFIND modes 6 and 7 have been introduced. Mode 6 and 7
are used to implement the TurboIMAGE TPI functionality (in the
TurboIMAGE compatibility extension).
This document describes the native Eloquence C language API.
int idb_find( dbid, qset, mode, status, qitem, key )
Arguments:
dbid - database id
qset - dataset name or number
mode - see below
status - status array (to receive status words
qitem - item or iitem name or number
key - pointer to key value
Returns:
completion code (same as status[0])
Modes:
1 - find chain head / subset
2 - find first record
3 - find last record
4 - find first record based on RE
5 - find last record based on RE
6 - find entries based on search list
7 - find first record based on search list
Mode 6 returns the number of matching entries in status element 6.
Mode 7 only locates the first entry which satisfies the condition.
Evaluating the number of matching entires requires additional
work to read part of the index, so mode 7 should be used
preferably when possible.
With modes 6 and 7 the item argument must reference an index item.
Either the index item number or name can be passed.
With modes 6 and 7 the key argument points to a list of conditions
to qualify the results. The argument must be 32 bit aligned.
---------------------
| size (in bytes) | total size (not including this field)
---------------------
| key op | struct key_op
- - - - - - - - - - -
| length | key length in bytes
- - - - - - - - - - -
| key | key data (padded to 4 byte boundary)
| padded to 4 bytes |
---------------------
| ... | padding of last block is optional
---------------------
A single condition is expressed by the structure below:
struct KeyOp {
int8_t start_seg; // expression starts at this key segment
int8_t op; // operator (see below)
uint8_t flags; // flags (see below)
int8_t reserved; // not used yet
int32_t length;
char data[1];
}
The following operators are supported
KEY_OP_NONE 0 invalid
KEY_OP_EQ 1 ==
KEY_OP_NE 2 !=
KEY_OP_GE 3 >=
KEY_OP_LE 4 <=
KEY_OP_GT 5 >
KEY_OP_LT 6 <
The following flags are supported:
KEY_OP_FLAGS_RE 0x01 // flag: regular expression
In case a regular expression is used it needs to follow the
rules described for DBFIND mode 4 and 5.
DBINFO mode 303 has been introduced to return information on sort
items while keeping backwards compatibility with mode 301.
The following information is returned:
struct info_303 {
int count; // list entries
struct { // for each path
int set; // related set
int ditem; // detail item no
int sort_item; // sort item or 0
} path[1];
};
Please note: With the TurboIMAGE compatibility API this information
is returned with mode 301. DBINFO mode 303 is not available.
Please note: With the Eloquence programming language this
information is returned with DBINFO mode 301.
The sort item is returned in the previously reserved field of the
path information.
DBINFO mode 505 has been introduced to return a list of all data sets
which contain a specific index item.
The following information is returned:
struct info_list { // 103, 104, 203, 204, 505
int count; // list entries
int no[1]; // list data
};
Please note: With the TurboIMAGE compatibility API this information
is returned with mode 705.
|
