Eloquence B.07.00 Release Notes

Eloquence B.07.00 Release Notes

Eloquence B.07.00 - Database

Database functions

[ Main document | Back ]

Contents:

DBOPEN status codes
DBFIND mode 6 and 7
DBINFO mode 303
DBINFO mode 505

DBOPEN status codes

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

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

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.

Database functions

DBOPEN status codes

DBFIND mode 6 and 7

DBINFO mode 303

DBINFO mode 505