Most changes are related to supporting FTS indexes in the image3k library. We follow the IMAGE "TPI" conventions for keyword indexes to support FTS functionality.

The basic use of keyword indexes does not require an additional license option. Some advanced use requires an additional "FTS" (enhanced FTS) or "FTC" (FTS compatibility) license option to be available.

The following image3k calls were changed:

• dbcontrol
• dbfind
• dbget
• dbinfo

changed status codes

• The status -813 indicates an internal failure in the FTS subsystem. The secondary status (as indicated by dberror or dbexplain) should provide a hint on the failure cause.

• The status -54 returned by DBFIND indicates an invalid FTS search condition. This typically indicates an invalid search condition for the specified FTS field (for example, a syntax error, a bad range or searching for a partial word on a numeric FTS field). The secondary status (as indicated by dberror or dbexplain) should provide a hint on the failure cause.

• The status -55 returned by DBFIND or DBGET indicates invalid previous results. Either no results exist (DBFIND was not called at all) or the previous results are not applicable.

• Eloquence does not use the 3xxx status codes reserved in TurboIMAGE for third party indexing.

DBCONTROL(base,qualifier,mode,status)

• Mode 800 specifies to retain the previous result.
• Mode 801 specifies to NOT retain the previous result.

The qualifier argument is ignored for mode 800 and 801.

The default may be customized with the HP3K_TPI_COMPAT database property or using the DBCONTROL mode 1015.

Bit 3 (+8) of the value specifies the default behavior. If bit 3 is set, the default is set to retain previous FTS DBFIND results (same as DBCONTROL mode 800).

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

DBFIND mode 1

A DBFIND mode 1 on an FTS index performs a keyword search, a record pointer is set, and a chain count is returned. To avoid ambiguities an FTS search is only performed if there is no conflicting search or index item.

DBFIND mode 10

A DBFIND mode 10 performs a standard TurboIMAGE DBFIND on a detail search item passed through the item parameter. This is useful if the item name or number is ambiguous.

DBFIND mode 12 - keyword search, returns result count

A DBFIND mode 12 performs a keyword search and returns a count of the number of records that qualified.

DBFIND mode 13 - undo

A DBFIND mode 13 undoes the last keyword search and restores the previous FTS result.

DBFIND mode 21 - keyword search, does not return record count

A DBFIND mode 21 is the same as mode 1, but does not return the number of qualified records. Instead, the number of FTS results is returned which may differ from the number of qualified records for aggregated FTS fields.

DBFIND mode 23 - keyword search, does not return record count

A DBFIND mode 23 is the same as mode 12, but does not return the number of qualified records. Instead, the number of FTS results is returned which is different to the number of qualified records for aggregated FTS fields.

Keyword searches

The search argument for a keyword search must be ASCII (even when searching for an FTS field on a numeric field) and must be terminated with a semicolon (;).

Boolean operations are used to establish a relation among search values using a given FTS index. When the search involves several FTS indexes in successive calls to DBFIND, they can establish a relation between the current list of qualified records and the records that qualified for a previous search.

Keyword searches on aggregated FTS fields

Progressively qualifying detail records using aggregated FTS fields can produce unexpected results. As aggregated FTS fields qualify entire detail chains (in possibly more than a single data set), it is possible to qualify chains where no single record contains the keywords specified.

Notes:

• With DBFIND mode 1 and 21 the item argument may ambiguous. It may refer to a search item or an index item in addition to an FTS item. To avoid introducing behaviour changes an FTS search is only performed with DBFIND mode 1 and 21 if the item is not ambiguous. Otherwise, use a keyword search mode (12 or 23) or define a unique name for the FTS field.

• When performing keyword searches on aggregated FTS fields in a detail set, returning the qualified number of records may add noticeable overhead as the chain heads needs to be read. Using DBFIND mode 23 instead of mode 12 avoids this overhead and instead returns the number of chain heads.

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

The first DBGET mode 21, 22, 23, 25 or 26 after a DBFIND on an FTS index defines the "retrieval" data set, which could be different from the last data set a DBFIND was used on. DBGET supports using database chains to apply FTS search results to a related master or detail set.

DBGET mode 21, 22 and 23 affect the position in the FTS search results. No data is read.

DBGET mode 25 and 26 obtain the next or previous FTS result (similar to DBGET mode 5 or 6). However, DBGET mode 25 and 26 are specific to FTS searches and are not affected by subsequent DBFINDs that are not FTS specific.

DBGET mode 21 - reset result pointer

DBGET mode 21 resets the result pointer to the beginning of the list of records qualified by keyword search (DBFIND mode 12 or 23).

DBGET mode 22 - move forward

DBGET mode 22 moves pointer forward n entries in the list of records qualified by a keyword search, without actually retrieving a record. n is passed in argument.

DBGET mode 23 - move backward

DBGET mode 23 moves pointer backward n entries in the list of records qualified by a keyword search, without actually retrieving a record. n is passed in argument.

DBGET mode 25 - retrieve next record

DBGET mode 25 retrieves the next record from those qualified by an FTS search.

DBGET mode 26 - retrieve previous record

DBGET mode 26 retrieves the previous record from those qualified by an FTS search.

811	-		Returns the type of access available for an item or index
812	-		Returns description of data item or index
813	-		Identifies all items available in database and type of access supported
814	-		Identifies all items available in data set and type of access supported
821	-		Identifies all data sets which contain the specified index
831	-		Identifies any sorted index for the specified data set
832	-		Identifies any FTS index for the specified data set
833	-		Describes a specific index
834	-		Describes all items grouped with the specified key

Notes:

• FTS and index items return a TPI item number for any composite index fields. Otherwise the data item number is returned.

• TPI items use an offset of 5000 (or 10000 on HP-UX for full compatibility with TurboIMAGE).

• 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).

• 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).

Qualifier identifies an item name or number and (optionally) a data set name or number starting at word 9. If a data set is specified DBINFO mode 811 verifies the item is valid for the given data set.

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

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

A negative item number indicates that the item is write accessible in at least one set.

Notes:

• TPI items are not considered "writable" and always return a positive item number (indexes are changed implicitly with the underlying data item).

• When passing an item name that is not a data item FTS items take precedence over index items.

• TPI items use an offset of 5000 (or 10000 on HP-UX for full compatibility with TurboIMAGE).

Qualifier identifies an item name or number and (optionally) a data set name or number starting at word 9. If a data set is specified DBINFO mode 812 verifies the item is valid for the given data set.

When passing an item name, FTS items take precedence over index items and data items (in this order).

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

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|   1-8     | Item name                              |
------------------------------------------------------
|    9      | Item type followed by a blank          |
|           | I, J, K, E, R, U, X, Z, P              |
------------------------------------------------------
|   10      | Sub-item length                        |
------------------------------------------------------
|   11      | Sub-item count                         |
------------------------------------------------------
|   12      | Key type                               |
------------------------------------------------------
|   13      | Zero                                   |
------------------------------------------------------

Element 12 returns 0 for a data item, 1 for a TPI item or 2 if the item is both a data and TPI item.

Notes:

• When passing an item name that is not a data item FTS items take precedence over index items.

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:

• TPI items are listed after the data items.

• TPI items are not considered "writable" and always return a positive item number (indexes are changed implicitly with the underlying data item).

• TPI items use an offset of 5000 (or 10000 on HP-UX for full compatibility with TurboIMAGE).

• Since all data items and indexes in the data base are returned you need to be careful to avoid a buffer overflow as the number items with Eloquence may exceed the IMAGE limits.

The qualifier specifies a data set name or number.

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:

• TPI items are listed after the data items.

• TPI items are not considered "writable" and always return a positive item number (indexes are changed implicitly with the underlying data item).

• TPI items use an offset of 5000 (or 10000 on HP-UX for full compatibility with TurboIMAGE).

The qualifier specifies an item name or number.

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                  |
------------------------------------------------------

The qualifier specifies a data set name or number.

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                          |
------------------------------------------------------

• TPI items use an offset of 5000 (or 10000 on HP-UX for full compatibility with TurboIMAGE).

The qualifier specifies a data set name or number.

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                          |
------------------------------------------------------

• TPI items use an offset of 5000 (or 10000 on HP-UX for full compatibility with TurboIMAGE).

Qualifier specifies both a data set name or number and an item name or number at word 9. The item must be a TPI item.

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

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|      1    | TPI Item number                        |
------------------------------------------------------
|      2    | TPI index type followed by a space     |
|           | G (generic sorted key), sorted index   |
|           | M (multiple key), FTS index            |
|           | B (both)                               |
------------------------------------------------------
|      3    | external key length (in bytes)         |
------------------------------------------------------
|      4    | Data set number of first item in       |
|           | keyword group or 0 if not member of a  |
|           | keyword group                          |
------------------------------------------------------
|      5    | Item number of first item in           |
|           | keyword group or 0 if not member of a  |
|           | keyword group                          |
------------------------------------------------------
|      6    | IMAGE item number of master set search |
|           | item or 0                              |
------------------------------------------------------
|      7    | length of item in element 6 above      |
|           | (in bytes)                             |
------------------------------------------------------
|    8-27   | an integer array describing this key's |
|           | use of the standardized installation   |
|           | options, as discussed below            |
------------------------------------------------------
|     28    | n = number of key components           |
------------------------------------------------------
| 6(n-1)+29 | IMAGE item number of component         |
------------------------------------------------------
| 6(n-1)+30 | byte offset of item (zero relative)    |
------------------------------------------------------
| 6(n-1)+31 | length of component in bytes           |
------------------------------------------------------
| 6(n-1)+32 | Data type of data in component:        |
|           | (I, J, K, E, R, U, X, Z, P)            |
|           | followed by a space                    |
------------------------------------------------------
| 6(n-1)+33 | IMAGE sub-item length of component     |
------------------------------------------------------
| 6(n-1)+34 | IMAGE sub-item count of component      |
------------------------------------------------------

Element 2 returns the TPI item type. "G" identifies a sorted index (index item), "M" indicates a keyword index (FTS index), "B" indicates an item is both an a sorted and a keyword index.

Element 3 returns the sum of the index segment lengths in bytes.

Elements 4 and 5 are only relevant for a keyword index that is member of a field group. They indicate the IMAGE data set and the first item in the group.

Elements 6 and 7 are only relevant for a keyword index. For a linked FTS field returns the master set search item and its length, or zero for an unlinked FTS field in a detail set.

For an FTS item the key type "M" (or "B") is returned. The elements 8-27 describing the keyword index are used as below:

[ 8]  No Translate (FTS NT option)?  
      1=yes, 0=no

[ 9]  Parsing enabled (FTS NP option)? 
      1=yes, 0=no

[10]  Any excluded words (FTS NE option)? 
      0=no, 1=default exclude list, 2=field specific

[12]  Soundex (FTS SX option)? 
      1=yes, 0=no

[13]  Set specific results
      1=yes, 0=no

[ 8]  Case sensitivity (index CI option)
      0 = Case insensitive
      1 = Case sensitive

[11]  Values: blanks, nulls, zeros (index EMPTY option)
      0 = Not indexed
      1 = Indexed

Qualifier specifies both a data set name or number and an item name or number starting at word 9. The item must be an FTS item.

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

------------------------------------------------------
|  Element  |              Content                   |
------------------------------------------------------
|      1    | n = number of keys in this group       |
------------------------------------------------------
| 2*(n-1)+2 | Set number of grouped key              |
------------------------------------------------------
| 2*(n-1)+3 | IMAGE item number of grouped key       |
------------------------------------------------------
|      :    | :                                      |
------------------------------------------------------