The DBI compatibility is implemented in the libftc library. This library must be loaded to enable DBI calls. The libftc library internally makes use of the image3k library (implementing the TurboIMAGE compatibility) and the eqdb library (Eloquence database client library).

A separate "FTC" license key is required to enable DBI compatibility.

Overview

Subsequently, the IMAGE "TPI" convention incorporated a major subset of the indexing functionality in the IMAGE calls and allowed third parties to provide indexing functionality. Eventually some limited index support was added to IMAGE.

As Eloquence supports indexing natively the DBI calls (as well as the image3k TPI modes) make use of the Eloquence indexing and do not add additional functionality. DBI calls are intended to provide backwards compatibility for existing applications.

The DBI calls in the libftc are integrated with the image3k library (Eloquence TurboIMAGE compatibility) and you may mix and match calls from either family. For example, it is valid to open the database with an IMAGE dbopen and use DBI calls subsequently. Or one may use dberror instead of dbierror to decode the status array.

An important difference to IMAGE conventions is that the DBI calls use a 21 element status array of 16-bit words (rather than 10 elements with IMAGE). Also, the DBI calls uses two status codes: If the first element of status array is set to 999 then the 11th status element holds a separate DBI status code. Otherwise status reflects an IMAGE status.

The main DBI calls are:

• dbifind
• dbiget
• dbiinfo

• dbiclose
• dbidelete
• dbierror
• dbiexplain
• dbilock
• dbiopen
• dbiput
• dbiunlock
• dbiupdate

Implementation notes

• Using dbifind in index sequential mode or index search mode will affect the current record number of the associated master set. Conversely changing the current record in the associated master will affect the index sequential mode.
  Eloquence currently does not maintain a separate current record of the associated master for use in dbifind.

• Eloquence does not define a separate numeric range for composite FTS fields and index items.
  As Eloquence supports more than 1024 IMAGE items the original range for composite FTS fields (larger than 1024) or composite index items (larger than 2000) would be conflicting.
  In the Eloquence DBI calls, composite FTS and index items use distinctive item numbers but not in a specific number range.

• An index item is considered "composite" if it refers to more than one item (multiple segments), has a different name or its definition differs from the underlying data item (e.g. uses an offset or a deviating length). Composite index items use a different item number than the underlying data item.

• An FTS field is considered "composite" if it refers to more than one item (has multiple segments), defines its own name or its definition differs from the underlying data item (e.g. uses an offset or a deviating length). Composite FTS indexes use a different item number than the underlying data item.

• IMAGE only or Index only DBI modes are not supported.

• As Eloquence already uses indexes for its master sets (rather than hashing), creating an index on a search item is redundant. Instead, the master index may be used with DBI calls.

• DBI calls are not required to use ODX calls. ODX calls may be used with any database opened through the image3k library. dbexplain and dberror are aware of ODX or DBI specific status codes.

dbifind sets up pointers in preparation for dbiget (or DBGET) chained access. A chain consists of detail entries that share the same value for the search item specified in item. The first detail record whose search item values matches the argument value is the first chain head. You can locate the chain head by full key value in mode 1, or by partial key value in sorted-key sequence, using modes 100-500. The argument parameter contains the full or partial-key value that is used to locate the chain head.

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

base

Base is the name of an array used as the base parameter when opening the database.

dset

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. The set must be a detail data set.

mode

Mode is a 16-bit word integer, used to pass any of the following values:

IMAGE modes

1	same as IMAGE DBFIND mode 10. Locates the chain head that matches the full key value in argument.

Index search modes

To search the master set index for a matching key and relation add one of the mode values below to the key length of the value passed in the argument parameter.

100	= operation. Locates the first chain head in ascending key order whose key value equals the value in argument to the precision specified.
200	> operation. Locates the first chain head in ascending key order whose key value is greater than the specified argument.
300	>= operation. Locates the first chain head in ascending key order whose key value is greater than or equal to the specified argument.
400	< operation. Locates the first chain head in descending key order whose key value is less than the specified argument.
500	<= operation. Locates the first chain head in descending key order whose key value is less than or equal to the specified argument.

Index sequential modes

After a call to dbifind using an index search mode the index sequential modes may be used to read through key values. The argument parameter is ignored for these modes.

90	locates the next higher search item value.
91	locates the next lower search item value.
92	locates the current chain head. Resets the pointer to the beginning of the chain.

status

Status is the name of an array of 21 elements, each 16-bit words in which the dbifind call returns status information. If the call completed successfully, the first element is zero. If the first element is 999 then element 11 holds the DBI condition word.

Element	Contents
1	If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2-4	Unused
5-6	Number of entries in chain
7-8	Record number of last entry in chain
9-10	Record number of first entry in chain
11	DBI condition word is zero
12	Call id
13	Mode
14-21	Not used

item

Item is the name of an 8 16-bit word (16 byte) array containing the left-justified name or 16-bit integer item number of an IMAGE search item.

argument

Argument passes the full or partial key value used to locate the chain head for index search retrieval modes.

Index search mode values and argument length

For the index search modes (100-500) the argument parameter may contain a partial key value. The length of argument is expressed in mode along with the relational condition.

For example, if a partial key argument of 5 bytes is passed dbifind will compare the first five characters of the indexed key values against the partial key passed in argument. The chain head found is the first key value that satisfies the relation as specified by the index search mode value.

When using a full key argument value (using the defined length of the sorted key), add nothing to the index search mode value. For example, to specify a "greater than" relational operation using a full key argument, the mode would be 200.

When using a partial key value in argument, the argument length is added to the index search mode value.

• To specify the argument length in words, add the number of words to the index search mode value and use a positive mode value.

• To specify the argument length in bytes, add the number of bytes to the index search mode value and use a negative mode value.

Please note: An argument length of 100 bytes or more can not be specified in bytes as this would otherwise overflow the index search mode mode. Use a word length or the full key instead (the search argument may need padding). For item types other than text (X/U) a partial key may not be specified.

The relation specified in the index search mode is only evaluated for the argument length. Any key value contents beyond the argument length are ignored.

dbifind condition codes

Notes

• dbifind may affect the current record number of the related master set specified by the item argument.

• Index-only modes (mode option 1000) are not supported and return a DBI status -200.

• If the specified item is either invalid or does not specify a search item DBI status -204 is returned.

• A negative mode value indicates a key length in bytes.

• A zero key length specified in mode indicates a "full key", the argument length must match the item size. Please note that this differs from the image3k dbfind TPI mode conventions.

• If a key is present in the master set search item but has no records in the detail set an empty chain head is returned. Use dbifind in index sequential modes to read the next or previous chain head.

• For indexes on binary items (numeric fields) a partial key may not specify a partial index segment. A partial index segment is ignored. At least the first index segment must be present, otherwise DBI status -202 is returned.

dbiget(base,dset,mode,status,list,buffer,argument)

base

Base is the name of an array used as the base parameter when opening the database.

dset

Dset is the name of an array that specifies both the data set name and optionally the index item or master set key item. Please note that this differs from the standard IMAGE dset parameter.

The data set name must be in the first 8 words (16 bytes), and the index item name or master set key item must begin in word 9 (byte 17). If the data set name is shorter than 16 bytes it must be terminated by a semicolon ( ; ), a space or a NUL character.

If a master set search item is the only index defined in the set the last 8 words (16 bytes) are ignored and the master set search item is assumed.

If an IMAGE mode is used, the last 8 words (16 bytes) are ignored.

mode

Mode is a 16-bit word integer, that contains any of the following values:

IMAGE modes

1	reread current record, same as IMAGE DBGET mode 1
2	serial read, same as IMAGE DBGET mode 2
3	backward serial read, same as IMAGE DBGET mode 3
4	directed read, same as IMAGE DBGET mode 4
5	chained read, same as IMAGE DBGET mode 5
6	backward chained read, same as IMAGE DBGET mode 6
7	calculated read, same as IMAGE DBGET mode 7
8	primary calculated read, same as IMAGE DBGET mode 8

Index search modes

To search the specified index for a matching key and relation add one of the mode values below to the key length of the value passed in the argument parameter.

100	= operation. Retrieves the first entry in ascending key order whose key value equals the value in argument to the precision specified.
200	> operation. Retrieves the first entry in ascending key order whose key value is greater than the specified argument.
300	>= operation. Retrieves the first entry in ascending key order whose key value is greater than or equal to the specified argument.
400	< operation. Retrieves the first entry in descending key order whose key value is less than the specified argument.
500	<= operation. Retrieves the first entry in descending key order whose key value is less than or equal to the specified argument.

Index sequential modes

After a call to dbiget using a an index search mode the index sequential modes may be used to read through key values. The argument parameter is ignored for these modes.

90	retrieves the next entry in ascending key sequence.
91	retrieves the previous entry in ascending key sequence (the first entry in descending order).
92	rereads the current entry.

status

Status is the name of an array of 21 elements, each 16-bit words in which the dbiget call returns status information. If the call completes successfully the first element is zero. If the first element is 999 then element 11 holds the DBI condition word.

Element	Contents
1	If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2	Length of the logical entry read into the buffer array in 16-bit words.
3-4	Record number of the data entry read.
5-6	Zero for a detail set, One for a master set.
7-8	Record number of the preceding entry in the chain of the current path (see notes)
9-10	Record number of the next entry in the chain of the current path (see notes)
11	DBI condition word is zero
12	Call id
13	Mode
14-21	Not used

list

List is the name of an array that contains either an ordered set of data item names or numbers, an at sign (@) to specify all items in the database, or an asterisk (*) to re-specify items passed in the last list.

buffer

Buffer is the name of the array to which the values of data items specified in the list array are moved. The defined array must be large enough to hold the values from the fields that correspond to the items in list. If the buffer array is to small, memory corruption will result.

argument

Argument contains the full or partial key value used to locate the master or detail record for all index search modes.

Index search mode values and argument length

For example, if a partial key argument of 5 bytes is passed dbiget will compare the first five characters of the indexed key values against the partial key passed in argument. The first key value that satisfies the relation as specified by the index search mode value is returned.

When using a full key argument value (using the defined length of the sorted key), add nothing to the index seach mode value. For example, to specify a "greater than" relational operation using a full key argument, the mode would be 200.

When using a partial key value in argument, the argument length is added to the index search mode value.

• To specify the argument length in words, add the number of words to the index search mode value and use a positive mode value.

• To specify the argument length in bytes, add the number of bytes to the index search mode value and use a negative mode value.

Please note: An argument length of 100 bytes or more can not be specified in bytes as this would otherwise overflow the index search mode. Use a word length or the full key instead (the search argument may need padding). For item types other than text (X/U) a partial key may not be specified.

The relation specified in the index search mode is only evaluated for the argument length. Any key values values beyond the argument length are ignored.

dbiget condition codes

Notes

• A dbiget may affaect the current path of the specified data set. A dbiget in index search or index sequential mode changes the path of the specified data set.

• Index-only modes (mode option 1000) are not supported and return a DBI status -300.

• If the specified item is either invalid or does not specify an index item or master set key item DBI status -304 is returned.

• A negative mode value indicates a key length in bytes.

• A zero key length specified in mode indicates a "full key", the argument length must match the item size. Please note that this differs from the image3k dbfind TPI mode conventions.

• For indexes on binary items (numeric fields) a partial key may not specify a partial index segment. A partial index segment is ignored. At least the first index segment must be present, otherwise DBI status -302 is returned.

dbiinfo(base,qualifier,mode,status,buffer)

base

Base is the name of an array used as the base parameter when opening the database.

qualifier

qualifier is the name of an array containing an argument to the respective dbiinfo mode. Its value depends on the value of the mode parameter.

mode

mode is an integer indicating the type of information desired.

101	-		Returns the type of access available for an item
102	-		Returns description of data item
103	-		Identifies all items available in database and type of access supported
104	-		Identifies all items available in data set and type of access supported
201	-		Same as IMAGE dbinfo 201
202	-		Describes referenced data set
203	-		Same as IMAGE dbinfo 203
204	-		identifies all data sets that contain the referenced item
301	-		Same as IMAGE dbinfo 301
302	-		Same as IMAGE dbinfo 302
310			All sets with index items in the database
311	-		Index item in given set
312	-		Information on sorted key
313	-		Identifies sorted keys
320	-		Number of index items in database
321	-		Version information
401	-		Same as IMAGE dbinfo 401
402	-		Same as IMAGE dbinfo 402
501	-		Same as IMAGE dbinfo 501
424	-		information on passive error handling
427	-		information on passive error handling
901	-		Same as IMAGE dbinfo 901

status

Status is the name of an array of 21 elements, each 16-bit words in which the dbiinfo call returns status information. If the call completed successfully, the first element is zero. If the first element is 999 then element 11 holds the DBI condition word.

Element	Contents
1	If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2	Length of the buffer array in 16-bit words.
3-10	Unused.
11	DBI condition word is zero
12	Call id
13	Mode
14-21	Not used

buffer

Buffer is the name of an array in which the requested information is returned. The contents of the buffer array depends on the mode parameter used.

dbiinfo condition codes

dbiinfo mode 101 is identical to DBINFO mode 101 for data items but extends it to cover index items and FTS fields as well.

Qualifier identifies the item name or number for which the information is requested and may describe a data item, index item or an FTS field.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|    1      | +/- Item number                        |
------------------------------------------------------

Notes:

• Composite FTS and index items are not considered "writable" and always return a positive item number.

• Eloquence does not define a separate numeric range for composite FTS fields and index items.

dbiinfo mode 102 is identical to DBINFO mode 102 for data items but extends it to cover index items and FTS fields as well.

Qualifier identifies the item name or number for which the information is requested and may describe a data item, index item or an FTS field.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|   1-8     | Item name                              |
------------------------------------------------------
|    9      | Item type                              |
|           | CO for composite FTS field             |
|           | CI for composite index item            |
------------------------------------------------------
|   10      | Sub-item length                        |
------------------------------------------------------
|   11      | Sub-item count                         |
------------------------------------------------------
|  12-13    | Zero                                   |
------------------------------------------------------

dbiinfo mode 103 is identical to DBINFO mode 103 for data items but extends it to cover index items and FTS fields as well. Composite FTS fields and index items are added to the item list.

Qualifier is ignored.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Contents                  |
------------------------------------------------------
|      1    | Item count x                           |
------------------------------------------------------
|      2    | +/- Item number 1                      |
------------------------------------------------------
|      :    | :                                      |
------------------------------------------------------
|    n + 1  | +/- Item number n                      |
------------------------------------------------------

Notes:

• Composite FTS and index items are not considered "writable" and always return a positive item number.

• Eloquence does not define a separate numeric range for composite FTS fields and index items.

dbiinfo mode 104 is identical to DBINFO mode 104 for data items but extends it to cover index items and FTS fields as well. Composite FTS fields and index items are added to the item list.

Qualifier identifies the data set name or number for which the information is requested.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Contents                  |
------------------------------------------------------
|      1    | Item count x                           |
------------------------------------------------------
|      2    | +/- Item number 1                      |
------------------------------------------------------
|      :    | :                                      |
------------------------------------------------------
|    n + 1  | +/- Item number n                      |
------------------------------------------------------

Information returned by item numbers is the same as for mode 103.

dbiinfo mode 202 is similar to DBINFO mode 202 but in addition returns information on available indexes for the set.

Qualifier identifies the data set name or number for which the information is requested.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|   1-8     | Data set name                          |
------------------------------------------------------
|     9     | Set type                               |
------------------------------------------------------
|    10     | Entry word length                      |
------------------------------------------------------
|    11     | Blocking factor                        |
------------------------------------------------------
|    12     | Sorted key information followed by     |
|           | a space                                |
|           | I means sorted keys on data items.     |
|           | M means master with sorted key on      |
|           |   search item.                         |
------------------------------------------------------
|    13     | Zero                                   |
------------------------------------------------------
|   14-15   | Number of entries in set               |
------------------------------------------------------
|   16-17   | Capacity of set                        |
------------------------------------------------------

Element 12 returns an "M" for a master set if an index on the search item exists. An "I" is returned if an index is defined for a set (other than master set key item) or a detail set has a path related to a set that has an index for its search item. If no index is available a space is returned.

Notes:

• Element 11 always returns 0 as blocking factor does not apply to Eloquence.

• As Eloquence uses btree indexes for its master sets, master and any detail set with paths will always indicate an available index on search items. Consequently, for a master set and most detail sets element 12 will always indicate type "M".

• Capacity in Eloquence returns the highest record number ever used for the data set. The EQ3K_MINCAPACITY environment variable may be used to specify a minimum value.

dbiinfo mode 204 is identical to DBINFO mode 204 for data items but extends it to cover index items and FTS fields as well.

Qualifier identifies the item name or number for which the information is requested.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|      1    | Set count x                            |
------------------------------------------------------
|      2    | +/- Data set number 1                  |
------------------------------------------------------
|      :    | :                                      |
------------------------------------------------------
|    n + 1  | +/- Data set number n                  |
------------------------------------------------------

If the data set number is positive, the application has only read access to the data set. If the number is negative, the application has both read and write access. The data sets are listed in data set number order.

Qualifier is ignored.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|      1    | Set count x                            |
------------------------------------------------------
|      2    | +/- Data set number 1                  |
------------------------------------------------------
|      :    | :                                      |
------------------------------------------------------
|    n + 1  | +/- Data set number n                  |
------------------------------------------------------

If the data set number is positive, the application has only read access to the data set. If the number is negative, the application has both read and write access. The data sets are listed in data set number order.

Notes:

• Mode 310 will list any master sets and detail sets with paths or indexes. As Eloquence uses btree indexes for its master sets, most data sets will support indexed access.

Qualifier identifies the data set name or number for which the information is requested.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|      1    | Item count x                           |
------------------------------------------------------
|      2    | Item number 1                          |
------------------------------------------------------
|      :    | :                                      |
------------------------------------------------------
|    n + 1  | Item number n                          |
------------------------------------------------------

Notes:

• Mode 311 will list any search items and index items. As Eloquence uses btree indexes for its master sets, most data sets will support indexed access.

• Eloquence does not define a separate numeric range for composite FTS fields and index items.

Qualifier identifies the data set name or number for which the information is requested followed by an item name or number starting at word 9.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|    1      | Item number of key                     |
------------------------------------------------------
|    2      | Byte 1: index type                     |
|           | I means sorted key on data items       |
|           | M means sorted key on master           |
|           | search item.                           |
|           | A means sorted key on auto master      |
|           | search item.                           |
|           | Byte 2: bit encoded options            |
|           | 8:1  (0x80) Batch indexing             |
|           | 9:1  (0x40) No Translate               |
|           | 10:1 (0x20) No Exclude                 |
|           | 14:1 (0x02) Master key item            |
------------------------------------------------------
|    3      | Length in bytes                        |
|           | For compound items this value          |
|           | represents the sub-item length.        |
------------------------------------------------------
|    4      | Number of components in composite key  |
------------------------------------------------------
|    5..    | Record byte offset of component        |
------------------------------------------------------
|    6..    | Length of component                    |
------------------------------------------------------

For an index item in a master set the last key component contains the byte offset and length of the search item. For an index item in a detail set the last key component contains two zeros.

Element 2 returns the index type and its options.

• Index type "M" for a master set indicates a master set key item.
• Index type "A" or "M" for a detail set indicates a search item related to an automatic or manual master set with an indexed key item.
• Index type "I" indicates an index on a data item.

• Option bit 10:1 indicates if an index is configured to exclude empty fields. If the index is configured to exclude empty fields option bit 10:1 is zero (not set).
• Option bit 9:1 indicates if an index is case insensitive. If the index is case insensitive option bit 9:1 is zero (not set).
• Option bit 14:1 indicates an index on a master set key item.

• As Eloquence uses btree indexes for its master sets any master set key item and any detail search item may be used for indexed access.

• As Eloquence does not support batch index updates the option bit 8:1 is always zero.

Qualifier identifies the item name or number for which the information is requested.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|   1-8     | Item name                              |
------------------------------------------------------
|    9      | Item type                              |
|           | CO for composite FTS field             |
|           | CI for composite index item            |
------------------------------------------------------

Notes:

• IMAGE items take precedence over index items and FTS fields in case a conflicting name was specified.

• The item must either identify an index or FTS field or a search item. Otherwise mode 313 will fail with DBI status -502.

• The Item type is only returned if the item identifies a composite index item (CI) or a composite FTS item (CO). It is initilized to spaces otherwise.

Qualifier is ignored.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|    1      | Number of index items                  |
------------------------------------------------------

Qualifier is ignored.

Buffer returns the following (each element is a 16-bit word or two bytes):

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|    1-2    | Version code                           |
------------------------------------------------------

• Eloquence returns a version code of 82000 to indicate Eloquence release B.08.20 or later.

Qualifier is ignored.

Buffer is ignored.

A zero status is returned, indicating that passive error handling is not used.

Notes:

• This mode is not supported by Eloquence and constant value is returned.

dbiclose(base,dset,mode,status) 

dbidelete(base,dset,mode,status)

Notes:

• Index-only or IMAGE-only modes (mode option 100 and 200) are not supported and return a DBI status -400.

dbierror(status,buffer,length)

dbiexplain(status,parm)

parm

parm is a 16-bit word integer. The value of parm determines what happens when there is an error, as listed below.

=0		Suppresses the Program Error # message. Only the error message is displayed. This is identical to dbexplain.
<0		Aborts the user process immediately after displaying the Program Error # and error messages.
>0		Displays the Program Error # and error messages, but does not abort the program.

Notes:

• The parm argument is passed as a reference. However, Eloquence also accepts a NULL pointer which has the same effect as a zero parm value.

• Eloquence uses exit(1) to terminate the application with a exit code one.

dbilock(base,qualifier,mode,status)

dbiopen(base,password,mode,status)

dbiput(base,dset,mode,status,list,buffer)

Notes:

• Index-only or IMAGE-only modes (mode option 100 and 200) are not supported and return a DBI status -100.

dbiunlock(base,qualifier,mode,status)

dbiupdate(base,dset,mode,status,list,buffer)

Notes:

• IMAGE-only mode (mode option 100) is not supported and returns a DBI status -600.