.
contact contact

Eloquence B.07.00 Release Notes

 
.
 

TPI Support

[ Main document | Back ]

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

With Eloquence, indexes are defined in the schema (index items). Index items are defined in terms of one or more data items or a substring of them. Index items are associated with data sets and are maintained automatically. They can be used with master and detail data sets. An index item may use the same name as a data item.

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.

The following functionality is currently not supported:
  • Keyword search
  • Relational access.
  • Independend indexing (index not attached to a data set)



TPI Introduction

The Eloquence TurboIMAGE compatibility library translates TPI calls to use the builtin indexing functionality. A commonly used subset of TPI functionality is implemented.

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

In DBFIND modes 1 and 21 only ASCII arguments are valid. A numeric value may be specified as ASCII and is then converted by DBFIND.

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)
An alphanumeric index segment may use wildcard tokens (?, #, and @) to search 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 << >>).

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: X12
mode argument description
1 GOLDENBURG exact match on "GOLDENBURG"
21 GOLDENBURG same, but does not return the number of qualifying entries in the status array
102 GOLD all values that start with "GOLD"
1 GOLD@ same
1 G?LD values such as "GELD" or "GOLD"
1 G?LD@ values such as "GELD", "GOLD", "GOLDEN" and "GOLDBURG"
1 ?OLD the values "BOLD", "COLD", "FOLD" and "GOLD"
1 FX??8800@ all entries that start with "FX", followed by any two characters, followed by 8800, followed by anything
1 FX??88@ all entries that start with "FX", followed by any two characters, followed by 88, followed by anything
1 >=A@<=B@ all values in the range between "A" and "B", inclusive
1 <>87@ all values except those that begin with "87"
100 (ignored) the first alphabetical value in the dataset on the specified index
500 (ignored) the last alphabetical value in the dataset on the specified index

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

DBFIND mode 1 and 21 can search for entries using a partial key value, with the @ character. The @ is treated as a wildcard that stands for any number of any characters.

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

   argument: COMMON@
The partial key value specified is compared with the entries.

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>>
The @ can also be used as the first character in an argument. For example, <<@OWN>> will return BROWN and CROWN.

Finding entries using a generic key

The ? and # characters facilitate generic searches. The ? represents a single alphanumeric character and the # a single numeric character. They may occur multiple times anywhere in the value, for example:
   argument: STR?NG
would locate "STRING", "STRONG", and "STRUNG".

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

   argument: AX?J#@
would additionally find "AXBJ3826", "AX7J8AH", and "AXZJ277". In this example, the @ acts as the terminator because the argument is not surrounded with << >>.

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
would locate "BARTON", "BURTON", "MARTIN", and "MORTON".

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

Greater-than-or-equal-to searches are accomplished using the >= operator to prefix the value. For example, to find all entries greater than or equal to 1000:
   argument: >=1000
A greater-than operator is currently not supported. Greater-than searches can be simulated by one of the following:
   argument: >=1001
   argument: >=1000<>1000

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

Less-than-or-equal-to searches are accomplished using the <= operator to prefix the value. For example, to find all entries less than or equal to 500:
   argument: <=500
A less-than operator is currently not supported. Less-than searches can be simulated by one of the following:
   argument: <=499
   argument: <=500<>500

Finding entries not equal to a specified value

To find entries not equal to a particular value, use the <> operator. For example, to find all unpaid orders:
   argument: <>PAID
The <> operator may also be embedded within an argument to perform a Boolean AND NOT retrieval. For example, to find all the entries with ZIP-CODES (an X6 item) beginning with "900" except "90039":
   argument: 900@<>90039

Finding entries in a range of values

The >= and <= operators may be used in combination to specify a range. For example, to find all the entries that start with letters between "A" and "D" inclusive:
   argument: >=A@<=D@
Pattern-matching and/or exclusion may optionally be performed within a range, allowing entries to be qualified that not only fall between two values but also conform to a specific pattern. For example:
   argument: ####AA>=8910@<=8912@
The argument following >=, <= and <> may contain embedded ? or # characters.

Performance implications

Specifying a wildcard character at the begin or near the begin of an argument requires scanning either all entries or possibly a big number of entries for matching results unless other conditions are present which allow to narrow the results.

For example:

   argument: ####AA>=8910@<=8912@
This argument allows to narrow the key scanning to the range of 8910 to 8912 and then compare the result against the wildcard for each matching key.



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

After a DFIND on an index item, DBGET is used to retrieve the results in index order.

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

The DBTPIINFO call supplies information about the third party indexing products installed on the system as well as the external and internal index files created for a database, without the need for the caller to open the database.

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:
Element Contents
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.

 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2003-07-31  
  Copyright © 1995-2003 Marxmeier Software AG