Functions

OAQUALIFY

oaqualify qualifies rows in a table by searching an OMNIDEX index specified in column, using the argument in criteria. Rows qualified by oaqualify can be merged with, intersected with or eliminated from previous OmniAccess qualifications. oaqualify can also find indexed keyword values through the KEYWD option.

If no rows satisfy the expression or contain the keyword passed in the criteria parameter, the search qualifies a null set of rows and is considered successful. Status word 1 ( status.error) and status word 4 ( status.count) both contain a zero.

The Qualified Subset

After every call to oaqualify, except those qualifying no rows and those using the COUNTONLY or KEYWD option, oaqualify stores the subset of currently qualified rows in memory. This is called the qualified subset.

When you progressively qualify rows by referencing the qualified subset in a keyword search using the leading operators (AND, OR or AND NOT) and the search qualifies no rows, oaqualify preserves the last qualified subset by default. This also happens when you use the AUTORESET option. For example, you may have qualified a subset of 100 CUSTOMER rows in previous keyword searches. If you tried to narrow this subset by using the criteria AND CA to search the STATE index of CUSTOMERS, but no rows qualified, the original qualified subset of 100 CUSTOMER rows would remain in memory. You could attempt another retrieval using another index (like ZIP_CODE) or a different argument (like AND CO).

This feature is useful for online applications, where users may try different sets of ad hoc criteria to qualify a desired subset of rows. Note, however, that for some applications, especially batch reports, it is desirable to abandon the retrieval if a search qualifies no rows. Such applications should call oaqualify with the NOAUTORESET option. This option sets the qualified subset to null if a search does not qualify any rows.

You can restore the qualified subset to contain the rows it had before the most recent keyword search by using the UNDO option. Note that you cannot perform more than one UNDO operation in succession. Also note that in an UNDO operation, you must supply a valid cursor and, of course, the UNDO option.

Syntax

oaqualify (cursor, options, status, owner, table, column, criteria)

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 for oaqualify to take. Separate multiple options with commas, and terminate the option list with a semicolon or a null character.

status -- Returns information about the success or failure of the oaqualify routine. A zero status.error means a successful call to oaqualify. The status structure is passed by reference and contains fourteen 32-bit signed integers, followed by a 36-character buffer.

domain_table -- Is the name of the domain to search as expressed by the domain’s parent table. This is only required when searching a child table that is prejoined (linked) to several domains. Owner is a character value passed by reference, not longer than 33 bytes including a semicolon or null terminator.

search_table -- Is the name of the table to search. Table is a character value passed by reference, not longer than 33 bytes including a semicolon or null terminator. The character value must reference a table defined in the catalog opened by oaconnect.

index -- Is the name of an OMNIDEX index or the value $ODXID. Column is a character value passed by reference, not longer than 33 bytes including a semicolon or null terminator.

criteria -- Is the search criteria for finding rows within table. Criteria is a character value passed by reference. It can be a maximum of 4096 bytes and must be terminated with a semicolon or null character.

ASCII (non-numeric) arguments passed in criteria can contain wildcard characters, as discussed in “Pattern-matched and generic arguments”. Numeric arguments do not support wildcards. In searches on sorted indexes, criteria can reference a single argument, a single relational expression, or a single range expression.

In searches on MDK indexes, criteria can reference a single argument, or a combination of search operations and operands (arguments). These operations are discussed next. Criteria can also reference a qualified subset previously established by oaqualify to further refine the subset.

Options

AUTORESET -- preserves the previous subset of qualified rows if the search doesn’t qualify any rows. This is the default.

COUNTONLY -- returns only a count of the qualified rows but does not accumulate OMNIDEX internal IDs. This is useful when only the number of rows is required, as it keeps internal IDs from needlessly using memory and improves performance. Because it does not accumulate internal IDs, subsequent calls to oaqualify using a leading AND or OR in criteria are not permitted.
COUNTONLY purges the qualified subset from memory and does not support progressive qualification.

DOMAIN -- permits progressive searches across prejoined sets (within the same domain) without an intermediate oajoin. Note: This restricts your application to use a fixed domain structure.

IMS -- specifies that a sorted search should be performed against the index referenced in column. This option is only required when the index referenced in column has both keyword and sorted access installed on it.
If the column has only an ASK index, you need not specify the IMS option. However, if you later add a keyword index, OMNIDEX defaults to a keyword search and your code may no longer perform as you expected. For this reason, you should always specify the IMS option for sorted searches.

INTERRUPT -- lets a user stop the search by pressing the operating system’s [Ctrl]- interrupt key combination.

[Ctrl]-Y for MPE, [Ctrl]-C for UNIX and OpenVMS.

KEYWD -- qualifies a keyword or range of keywords stored in the indexes. The number of qualified keywords is returned to the qualifying count (word 4) of the status structure. You can then return the qualified keywords using oafetchkeys

NOAUTORESET -- sets the subset of qualified rows to null if the search doesn’t qualify any rows.

NOCOUNT -- does not return a qualifying count to the status structure. NOCOUNT works well in batch applications or any application where a count is not useful.

NOTANDOR -- evaluates AND operations before OR operations in Boolean retrievals.

NOTORAND -- evaluates OR operations before AND operations in Boolean retrievals.

NOVERIFY -- disables certain levels of error checking to increase search speed.

ODX -- specifies a search using keyword indexes. This is the default.

SAMELIST -- causes oaqualify to reload the most recent list of qualified rows.

UNDO -- restores the qualified subset of rows to the way it was before the last successful oaqualify.

Example

Top