OAFETCHKEYS
oafetchkeys returns up to 2048 key values (row IDs or unique keys) for
the rows qualified with oaqualify. It also can return keywords qualified
using the KEYWD option of oaqualify from OMNIDEX indexes. All key values
associated with rows qualified for the specified cursor are accessible.
Calls to oaselect do not affect the current qualified subset and do not
affect the results of calls to oafetchkeys.
oafetchkeys lets you optimize how you retrieve data qualified by calling
oaqualify. When used alone, it lets you perform index-only reads, which
return key values directly from the Omnidex indexes. You can also use
it to move the row pointer before calling oafetch, which gives you more
flexibility when reading through a list of qualified rows.
Index-Only Reads
Index-only reads offer the best retrieval performance because they return
data (key values) directly from an OMNIDEX index, without having to fetch
rows. The option you use to perform an index-only read depends on the
type of index you are reading.
If you used oaqualify to search a keyword index using the KEYWD option,
use the KEYWD option of oafetchkeys to return qualified keyword values.
A keyword retrieval is useful for users who may not know what values to
enter for a given column. You can also use keyword retrievals to check
the spelling and the consistency of keyword values.
If you used oaqualify to search a sorted index, use the IAKEY option
to return qualified sorted key values directly from the indexes. This
is useful after searching composite sorted indexes that combine several
columns. If the combined columns represent all the data that the application
needs, an index-only search can provide efficient, high speed access to
data. See “Composite indexes” for more information about creating
composite sorted indexes.
You can also use the KEY or ROWID options to return the unique key values
(for parent rows) or row IDs (for child rows) after searches on sorted
indexes.
In addition to OMNIDEX-indexed keywords or sorted key values, you can
fetch the primary key values of parent rows using the KEY option. Or you
can return the native row IDs of qualified rows using the ROWID option.
On child tables that are linked to a parent, and not installed with the
Record Complex option, you can return both the parent’s unique key
values and the children’s row IDs.
Syntax
oafetchkeys (cursor, options, status, num_keys, keys)
cursor -- Is a 32-bit signed integer
passed by value. This is the value returned by a successful call to oaopencursor.
options -- Is a 256-byte character string,
passed by reference, that indicates the action(s) for oafetchkeys to take.
Separate multiple options with commas, and terminate the option list with
a semicolon or a null character. If options contains only a semicolon
or null character, oafetchkeys defaults to the N and KEY options.
status -- Returns information about the
success or failure of the oafetchkeys routine. A zero status.error means
a successful call to oafetchkeys. The status structure is passed by reference
and contains fourteen 32-bit signed integers, followed by a 36-character
buffer.
num_keys -- Contains the number of row
IDs or key values (up to 2048) to retrieve or skip with oafetchkeys. Num_keys
is a 32-bit signed integer passed by value.
buffer -- Is an array, passed by reference,
that receives row IDs or key values from the list established by oaqualify.
The area referenced by buffer must be large enough to hold an array of
key values with as many elements as specified in num_keys. Binary data
may require conversion when rows are transferred from the server to a
client. For more information about byte-ordering, see byte ordering and
byte boundaries.
Options
CHAR=n -- returns binary values in character
format, where n is the byte length of the input number. The default is
32 bytes. The alphanumeric representation of the values is right-justified,
space filled to length n. For more information, see “The CHAR=n
option”.
The CHAR option is valid only with the ROWID option.
IAKEY -- returns all values in composite
keys, including row IDs, without fetching rows. If the composite key contains
all the data you want, this offers the best performance for retrieving
data after calling oaqualify. IAKEY is useful after searching sorted composite
indexes that combine several columns.
NEXT -- moves to the next key value .
Immediately after a successful call to oaqualify, oafetchkeys returns
the first num_key key values in the list. The N option works with the
IAKEY, KEY, KEYWD and ROWID options.
PREVIOUS -- moves to the previous key
value . Immediately after a successful call to oaqualify, returns the
last num_keyrow identifiers in the list. The P option only works on MDK
indexes and row IDs, but not with the KEYWD option.
The P option only works on MDK indexes. You cannot perform a backward
read on ASK indexes.
SKIPNEXT -- skips forward n key values
in the list, where n is the value passed in num_keys, but does not return
key values or row IDs. Call oafetchkeys using the N or P option to return
keys or row IDs.
The SKIPNEXT option does not support keyword lookup retrievals that use
the KEYWD option, nor does it support sorted key retrievals.
SKIPPREV -- skips backward n key values
in the list, where n is the value passed in num_keys, but does not return
key values or row IDs. Call oafetchkeys using the N or P option to return
keys or row IDs.
The
SKIPPREV option does not support keyword lookup retrievals that use the
KEYWD option, nor does it support sorted key retrievals. SKIPPREV only
works on MDK indexes. You cannot perform a backward read on ASK indexes.
REWIND -- rewinds the list pointer to
the beginning of the list. The R option restores the list to its original
state immediately after the last execution of oaqualify. The R option
does not work with the KEYWD option.
KEY -- returns the next n unique keys
as defined in the OMNIDEX environment catalog. This is typically the primary
key value in an indexed file.
ROWID -- returns the next n row IDs.
Use this option after qualifying rows in child tables to get a unique
identifier for the child row.
You
can use both the KEY and ROWID options on child tables that are linked
to a parent, and not installed with the Record Complex option, to return
both the parent’s unique key values and the children’s row
IDs.
KEYWD -- returns the next n keywords
qualified in an oaqualify keyword lookup search, where n is the value
contained in num_keys.See the KEYWD option under oaqualify for more information
on keyword lookup searches.
KWCOUNT -- returns the number of rows
or row complexes that contain the keyword. Used with the KEYWD option.
Example
Top
|
