|
This document describes the changes in the image3k library incorporated in
B.08.20. The Eloquence image3k library provides TurboIMAGE compatible
database calls.
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:
changed status codes
Three new status codes were added to Eloquence.
-
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
DBCONTROL(base,qualifier,mode,status)
The DBCONTROL call supports two additional modes to define the
DBFIND behavior when a subsequent FTS search does not qualify
any records.
-
Mode 800 specifies to retain the previous result.
-
Mode 801 specifies to NOT retain the previous result.
The default is to not retain a previous result (mode 801).
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
DBFIND was enhanced to support keyword search.
DBFIND(base,dset,mode,status,item,argument)
An FTS index field may be specified by the FTS field name or item number.
- 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
DBFIND modes 12 and 23 support keyword searches on FTS indexes.
Keyword searches can use wildcard characters, ranges, relation and
Boolean operations.
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
When performing keyword searches on aggregated FTS fields in a detail
set, entire chains rather than individual detail records qualify.
The qualifying count returned reflects the combined number of detail entries
in the chains that qualified.
As the chain heads need to be read to obtain the count of qualifying records
this imposes additional overhead.
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
DBGET was enhanced to support keyword search.
DBGET(base,dset,mode,status,list,buffer,argument)
DBGET mode 5 or 6 may be used to obtain records qualified by a
FTS search (DBFIND mode 1, 12, 13, 21 or 23 on an FTS index).
In addition, DBGET supports modes specific to FTS indexes
that allow additional functionality.
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.
dbinfo
The DBINFO TPI modes were enhanced to support FTS indexes.
| 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).
dbinfo mode 811
DBINFO mode 811 describes the access available for a data item
or TPI item.
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 |
------------------------------------------------------
DBINFO mode 811 returns the item number if the qualifier describes a
data item. Otherwise a TPI item number is returned.
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).
dbinfo mode 812
DBINFO mode 812 describes the referenced data item or index.
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 |
------------------------------------------------------
For composite FTS and index items the item type is returned as
spaces (element 9) and elements 10 and 11 return zeros.
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.
dbinfo mode 813
DBINFO mode 813 lists all items in the database (including any FTS and index
items) and the type of access.
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 |
------------------------------------------------------
A negative item number indicates that the item is write accessible
in at least one set.
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.
dbinfo mode 814
DBINFO mode 814 lists all items in the specified data set (including
any index and FTS items) and the type of access.
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 |
------------------------------------------------------
A negative item number indicates that the item is write accessible
in at least one set.
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).
dbinfo mode 821
DBINFO mode 821 identifies all data sets available which contain the
specified item (or TPI item) and indicates the type of access allowed.
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 |
------------------------------------------------------
A negative set number indicates that the set is write accessible.
The data sets are listed in data set number order.
dbinfo mode 831
DBINFO mode 831 identifies any sorted index for the specified data set.
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 |
------------------------------------------------------
Notes:
- TPI items use an offset of 5000 (or 10000 on HP-UX for full
compatibility with TurboIMAGE).
dbinfo mode 832
DBINFO mode 832 identifies any FTS index for the specified data set.
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 |
------------------------------------------------------
Notes:
- TPI items use an offset of 5000 (or 10000 on HP-UX for full
compatibility with TurboIMAGE).
dbinfo mode 833
DBINFO mode 833 describes a specific index.
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 1 returns the TPI item number that identifies this index.
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
For an index item the key type "G" is returned.
The elements 8-27 describing the keyword index are used as below:
[ 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
Element 28 and subsequent identify the number of
index segments and the IMAGE items.
dbinfo mode 834
DBINFO mode 834 describes all items grouped with the specified key.
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 |
------------------------------------------------------
| : | : |
------------------------------------------------------
|
