Eloquence B.07.00 - TurboIMAGE compatibility

TPI Support

TPI (Third Party Indexing) is a specification of a common application interface to use indexing products with TurboIMAGE. TurboIMAGE does not implement indexing functionality but allows to integrate third party indexing products.

Please note that this is different than the btree access to master data sets available with TurboIMAGE (specified with the schema /INDEXED option) while TPI is implemented through 3rd party indexing products.

Eloquence maps the TPI modes to the builtin indexing functions while considering compatibility with commonly expected behavior. Please be aware that only a subset of functionality as offered by 3rd party indexing products is currently available.

TPI Support

The following functionality is supported:

• The DBFIND modes 1, 11, 21, 22 and 100..599 have been implemented.

• DBFIND mode 10 is supported to enforce a standard DBFIND mode 1 on detail search items in case an index with the same name has been defined in the schema.

• The DBGET modes 5,6,15,16 are supported.

• The DBINFO modes 8xx are supported.

• Keyword search
• Relational access.
• Independend indexing (index not attached to a data set)

• Sort items and TPI modes currently do not compare string values based on a collating sequence. This will lead to wrong order with non-ASCII characters.

• In DBFIND mode 1 and 21 with concatenated keys (multiple segment index items) the argument parser may try to guestimate values for additional index segments. It should only consider the first index segment (#1197).

  This could cause a problem with index items which have a leading numeric segment and a subsequent string segment. In such cases the DBFIND argument parser may submit any additional buffer contents as part of the search condition. As a workaround you can specify a @ for any subsequent string segment.

TPI Introduction

The following index access methods are available:

generic key search

Allows wildcard values to be entered as part of a key. In response, all records matching that wildcard value will be available. The records will be returned in sorted order by key value, eliminating the need for sorting in many situations.

composite keys

Are comprised of components from several fields in a data set .

DBFIND is used to specify a search condition and establishes a working set of records which fulfill the search condition. DBGET is then used to retrieve matching records in index order. This is similar to using pathes where DBFIND locates the chain head and DBGET is used to fetch the linked records.
For example, the argument ">=JONES<=SMITH" qualifies the records of JONES through SMITH. Similarly, the argument ">=SMITH" qualifies the records of SMITH through the end of the file.

DBGET is used to retrieve the entries of the working set qualified by DBFIND. A current record pointer is maintained to read forward and backward within the working set of records. DBGET will return a status 14, or status 15, when a boundary of the working set is reached. Additional modes of DBGET are available to continue reading beyond the bounds of the working set and these modes return a status of 10 or 11 when the beginning or end of the file is encountered.

DBFIND arguments used for indexed access

If the index starts with an alphanumeric index segment (data type X, U or B) DBFIND combines all leading index segments into a single one which is described by the argument. A string must either be provided entirely (possibly padded with spaces) or the buffer must be terminated by:

• a single blank followed by a single @
• a single @ (used for partial-key retrieval)

If the index starts with a numeric data item (data types I, J, K, P, R, E, and Z) the search value is also specified in ASCII form and converted to a binary value. A numeric value should be terminated by a space character.

For data types P and Z, DBFIND treats unsigned and positive values equivalently. Floating point numbers (items of data type R or E) may include embedded decimal points (.), exponential signs (E), and positive (+) and negative (-) signs.

A retrieval operator (==, >=, <=, or <>) may prepend the specified value. If not present then the equity operator (==) is assumed. Multiple search values may be specified (eg. to specify a range) and must be separated by a retrieval operator.

DBFIND mode 11 or 22 (binary range modes) can also be used to qualify entries based on binary values. It is important to remember that the range must be entered in the argument. If only one value is to be qualified, the start and stop values are the same. For example, if the selected records should have values of less than 0, the first value of argument must be the lowest possible value for the data type, not 0. If the first value in the argument is 0, then no negative values will qualify.

DBFIND mode/argument examples

Simple index item: E2

mode	argument	description
1	>=1000	greater than or equal to 1000
1	>=12.34E5	greater than or equal to the specified number
1	<=100	less than or equal to 100
1	>=100<=1000	all in the range between 100 and 1000, inclusive

Simple index item: Z4

mode	argument	description
1	1234	exact match on the value 1234
102	1234	same
-103	123	exact match on 123
1	>=1234	all greater than or equal to 1234
1	>=23<=24	all in the range between 23 and 24 inclusive

Concatenated index item: X4 + X4

mode	argument	description
1	ABCD@	"ABCD" in the first index segment, any value in the second index segment
1	ABCD1234	exact match on both index segments: "ABCD" and "1234"
104	ABCD1234	Same
-108	ABCD1234	Same
1	????1234	"1234" in the second index segment, any value in the first index segment
21	????1234	same, but does not return the number of qualifying entries in the status array
-111	ABCD123456	condition word -31 ("BAD MODE"), because the index item length was exceeded

Concatenated index item: X4 + I1 (underlined values are specified in binary)

mode	argument	description
-106	ABCD1234	exact match on "ABCD" in the firstindex segment and 1234 in the second index segment (where 1234 is specified in binary)
-105	ABCD1234	condition word -31 ("BAD MODE"), because I1 requires 2 bytes and therefore mode 103 or mode -106 should be used
1	ABCDE	all with "ABCD" in the first index segment, and any value in the second index segment (the extra character is ignored)
21	ABCDE	same, but does not return the qualifying number of entries in the status array

Concatenated index item: I1 + X4 (underlined values are specified in binary)

mode	argument	description
103	1234ABCD	exact match on the value 1234 in the first index segment and "ABCD" in the second index segment (where 1234 is specified in binary)
-103	1234A	all with 1234 in the first index segment and "A" leading the second index segment (truncated value)
1	1234A	undefined result, binary values are not valid with mode 1
1	>=1234	all greater than or equal to 1234
1	<=2999	all less than or equal to 2999
1	>=-100<=100	all greater than or equal to -100 (negative 100) and less than or equal to 100 (positive 100)
-101	spaces	condition word -31 ("BAD MODE"), because the mode does not match the argument length
1	1234@	all equal to 1234. The subsequent string segment does not matter due to the terminating @. Otherwise the remaining buffer contents would be considered a string value.

Concatenated index item: Z4 + X4 (underlined values are specified in binary)

mode	argument	description
104	1234ABCD	exact match on the value 1234 in the first index segment and "ABCD" in the second index segment
-106	1234AB	exact match on the value 1234 in the first index segment and "AB" in the second index segment
1	1234	exact match on the value 1234 in the first index segment
1	1234ABCD	same, extra characters are ignored
1	12345678	undefined; value cannot be converted to the item type
1	>=1234	all entries with first index segment greater than or equal to 1234
1	>=1234<=2345	all entries with first index segment between 1234 and 2345 inclusive

Finding entries using a partial key

For example, to find all entries that begin with "COMMON":

   argument: COMMON@

The @ character can be used up to two times within an argument. This is accomplished by surrounding the requested argument with << >>. The format is <<A@B@C>>. This means that this argument will qualify records that begin with an A, having a B anywhere in the middle, and ends with a C. If only one @ is provided, there is an implied @ at the end of the argument (e.g. <<A@B>> is identical to <<A@B@>>).

For example, to find all entries that begin with "GE" and contain "ON":

   argument: <<GE@ON>>

Finding entries using a generic key

   argument: STR?NG

Both matchcodes may be used in combination with each other, along with the @ wildcard, for example:

   argument: AX?J#@

The matchcodes may also be used to locate entries in which the desired value does not begin in the first position, for example:

   argument: ??RT?N

This technique is especially useful for generic searches on concatenated index items, by specifying wildcard conditional operators for the unspecified index segments. These three examples perform generic searches on the first, second, and third index segments, respectively, of a concatenated index item consisting of an X2, X4 and X4 field with the value "PH1234ABCD":

   argument: PH@
   argument: ??1234@
   argument: ??????ABCD

Finding entries greater than or equal to a specified value

   argument: >=1000

   argument: >=1001
   argument: >=1000<>1000

Finding entries less-than or equal-to a specified value

   argument: <=500

   argument: <=499
   argument: <=500<>500

Finding entries not equal to a specified value

   argument: <>PAID

   argument: 900@<>90039

Finding entries in a range of values

   argument: >=A@<=D@

   argument: ####AA>=8910@<=8912@

Performance implications

For example:

   argument: ####AA>=8910@<=8912@

DBFIND

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

base

Same as TurboIMAGE.

dset

Specifies a master or a detail data set.

mode

1	If item specifies a search item a DBFIND on a detail data set is performed. If item specifies an index item, the argument is used to locate matching entries in the specified index (see below).
10	Performs a standard TurboIMAGE DBFIND on a detail search item. This is used when a search item and an index item with the same name are present.
11	Provides range retrieval for binary data items (I, J, K, P, Z, R, E). With mode 11, the argument buffer will contain both the start and stop values. The size and data type of each sub-argument is the exact size and data type of the item. DBFIND mode 11 returns the number of qualifying entries in words 5-6 of the status array.
21	Same as mode 1, but does not return the number of qualifying entries in the status array and is therefore more efficient. In mode 1 the index is read to locate all qualifiying entries while in mode 21 only the first qualifying entry is located. The argument rules for mode 21 are identical to mode 1.
22	Same as mode 11, but does not return the number of qualifying entries in the status array and is therefore more efficient. In mode 11 the index is read to locate all qualifiying entries while in mode 21 only the first qualifying entry is located. The argument rules for mode 22 are identical to mode 11.

The modes 1nn-5nn represent programmatic methods of enforcing the relational operators. It is also possible to apply the relational operators in a DBFIND mode 1 by using their corresponding tokens directly in the argument. Modes 1nn-5nn will not return a chain count.

1nn	Sets record pointer before the first record which matches the first nn words of the argument and qualifies a working set which matches the first nn words of the argument. If a negative number, then evaluates the first nn bytes. If 100, then sets the record pointer to record with lowest key value and qualifies all entries in the data set. If 199, then the full key value is evaluated, regardless of size. If a key value matching the argument is not found, a status condition of 17 is returned.
2nn	Sets record pointer before the first record greater than (>) the argument, evaluating the first nn words and qualifies a working set of all records which have a value greater than the argument. If a negative number, then evaluates the first nn bytes. If 200, then sets the record pointer to record with lowest key value and qualifies all entries in the data set. If 299, then the full key value is evaluated, regardless of size. If a key value matching the argument is not found, a status condition of 17 is returned.
3nn	Sets record pointer before the first record greater than or equal to (>=) the argument by evaluating the first nn words and qualifies a working set of all records which have a value greater than or equal to the argument. If a negative number, then evaluates the first nn bytes. If 300, then sets the record pointer to record with lowest key value and qualifies all entries in the data set. If 399, then the full key value is evaluated, regardless of size. If a key value matching the argument is not found, a status condition of 17 is returned.
4nn	Sets record pointer after the first record less than (<) the argument by reading from the end of the file, evaluating the first nn words and qualifies a working set of all records which are less than the argument. If a negative number, then evaluates the first nn bytes. If 400, then sets the record pointer to record with highest key value and qualifies all entries in the data set. If 499, then the full key value is evaluated, regardless of size. If a key value matching the argument is not found, a status condition of 17 is returned.
5nn	Sets record pointer after the first record less than or equal to (<=) the argument by reading from the end of the file, evaluating the first nn words and qualifies a working set of all records which are less than the argument. If a negative number, then evaluates the first nn bytes. If 500, then sets the record pointer to record with highest key value and qualifies all entries in the data set. If 599, then the full key value is evaluated, regardless of size. If a key value matching the argument is not found, a status condition of 17 is returned.

status

Same as TurboIMAGE. Please note that the chain count is not returned by all modes.

item

Specifies a search item or an index item. If both a search item and an index item with the same name exist in the same dataset and DBFIND is called in mode 1, Eloquence will use index item instead of the search item.

argument

The data type of the argument parameter depends on the mode used. The table below shows the expected data type for each mode:

1	ASCII for ASCII and Binary items.
10	ASCII for ASCII items; Binary for Binary items.
11	Binary for Binary items.
21	ASCII for ASCII and Binary items.
22	Binary for Binary items.
1nn	ASCII, Binary, or a combination of ASCII and Binary
2nn	ASCII, Binary, or a combination of ASCII and Binary
3nn	ASCII, Binary, or a combination of ASCII and Binary
4nn	ASCII, Binary, or a combination of ASCII and Binary
5nn	ASCII, Binary, or a combination of ASCII and Binary

In DBFIND modes 1 and 21 only ASCII arguments are valid. The following rules apply:

• If the index starts with a string segment (data type X, U and B) then DBFIND combines all leading index segments into a single one which is described by the argument. A string must either be provided entirely (possibly padded with spaces) or a terminating @ character must be present.

• If the index starts with a string segment wildcard tokens (?, #, and @) provide methods of searching for data without knowing all of the characters of a key. The wildcard token ? represents any single alphanumeric character. The wildcard token # represents any single digit. The wildcard token @ represents any number of alphanumeric characters, including no characters. The tokens ? and # may exist anywhere in a key while the @ may only appear at the end of a key (unless enclosed with << >>). Wildcard tokens are not supported for binary items.

• If the index item starts with a leading numeric segment (data types I, J, K, P, R, E, and Z) DBFIND will convert the argument into a binary representation. A numeric specification is terminated by a space character.

• The first value may be prepended with an operator (==, <=, >= or <>) which describes the desired operation. If not present, a == (equal) is assumed. Additional search conditions can be specified by appending an operator and additional search values. This performs an implied AND condition.

• More than one relational operator may be used in an argument to represent a range. For example, "5 to 10" could be represented as ">=05<=10". This can also be combined with wildcards. An argument of >=ABC@<=XYZ@" can be used to locate all records starting with ABC to XYZ, inclusive.

DBGET

DBGET mode 5 and 6 retrieve the next or previous result in index order which fulfills the search condition. When no more results are available, a status 15 (end of chain) is returned.

DBGET mode 5 and 6 retrieve the next or previous result. in index order which fulfill the search condition. When no more results are available, a status 15 (end of chain) is returned.

Mode 15 and 16 return entries in index order until the end of file is encountered.

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

base

Same as TurboIMAGE

dset

Same as TurboIMAGE

mode

1	Same as TurboIMAGE mode: Re-read
2	Same as TurboIMAGE mode: Forward serial read
3	Same as TurboIMAGE mode: Backward serial read
4	Same as TurboIMAGE mode: Directed read
5	If following a standard DBFIND along a TurboIMAGE search item, then performs a standard forward chained read. If following a generic key search, read next record in the chain using third party indexing product. At the end of the index chain, a status 15 (end of chain) is return.
6	If following a standard DBFIND along a TurboIMAGE search item, then performs a standard backward chained read. If following a generic key search, read previous record in the chain using third party indexing product. At the beginning of the index chain, a status 14 (begin of chain) is return.
7	Same as TurboIMAGE mode: Calculated read
8	Same as TurboIMAGE mode: Primary calculated read. (With Eloquence this is the same as mode 7)
15	Same as DBGET mode 5, but is not inhibited by an end of chain status. DBGET mode 15 will return a status 10 when the end of file is encountered.
16	Same as DBGET mode 6, but is not inhibited by a beginning of chain status. DBGET mode 16 will return a status 11 when the beginning of file is encountered.

status

Same as TurboIMAGE

list

Same as TurboIMAGE

buffer

Same as TurboIMAGE

argument

Same as TurboIMAGE

TPIINFO

DBTPIINFO (Base, Qualifier, Mode, Status, Buffer)

base:

Same as TurboIMAGE. Ignored for mode 1. Mode 2 requires database name.

qualifier:

See specific information for each mode

mode and buffer:

Mode 1

Returns information on third party indexing products installed and available for third party indexing.

Qualifier is ignored.

Buffer returns the following (note that each element is a halfword or two bytes):

-----------------------------------------------------
|   Element    |              Contents              |
-----------------------------------------------------
|      1       | Number of Products Installed.      |
|              | Zero if none installed.            |
-----------------------------------------------------
|  25(n-1)+2   |  Product name                      |
-----------------------------------------------------
|  25(n-1)+22  |  Version number                    |
-----------------------------------------------------

Notes:

• Eloquence returns 1 for element 1.
• Product number and version are the same as described with DBINFO mode 801.

Mode 2

Identifies third party index files configured for a database.

Qualifier is ignored.

Buffer returns the following (note that each element is a halfword or two bytes):

-----------------------------------------------------
|   Element    |              Contents              |
-----------------------------------------------------
|      1       | Number of external files.          |
|              | Zero, if none.                     |
-----------------------------------------------------
|      2       | Number of internal files.          |
|              | Zero, if none.                     |
-----------------------------------------------------
|     3-10     | Reserved for future use.           |
|              | Blanks for now.                    |
-----------------------------------------------------

Notes:

• Eloquence returns 0 for element 1 and 2 as this information does not apply.

Status:

Same as current TurboIMAGE status array.

The status array elements will have the following values:

1	Zero when successful, even when no TPI product is installed on the system for mode 1, or when the database is not enabled for indexing for mode 2. In these cases, interrogate the appropriate elements of the buffer parameter for a value of zero. Non-zero status values of 3nnn and -3nnn are reserved for non-standard errors from DBTPIINFO.
2	Length of the buffer in half-words. For mode 1, common values are 26 and 51, however, it will be 1 when no third party product is installed on the system. For mode 2, it will always be 10.
3-5	Will be zeroes.
6	Intrinsic id of DBTPIINFO (480).
7,8	For mode 2, address of base parameter. Zeroes with Eloquence.
9	Mode.
10	Zero.