FairCom ISAM for C

UpdateConditionalIndex

Update the Conditional Index Resource in a data file.

Short Name

UPDCIDX()

Type

ISAM level function

Declaration

COUNT UpdateConditionalIndex(FILNO keyno, pTEXT condexpr)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

UpdateConditionalIndex() can add, delete, or change the conditional expression associated with the index. This function assumes an ISAM mapping exists between keyno and an associated data file. The NULL-terminated ASCII string pointed to by condexpr defines the conditions that must be true for an index entry to be made. The expression is stored as a resource in the associated data file.

If condexpr is NULL or points to an empty string (""), the existing conditional expression is deleted. Each index can have at most one conditional expression. If keyno already has an expression, the new expression replaces the old expression.

For existing, non-empty files, it is ordinarily necessary to call a rebuild after updating the conditional expressions.

UpdateConditionalIndex() checks the syntax of the expression before adding it to the data file resource. The syntax can fail because a name used in the expression is not found in the DODA, or because of an illegal expression.

A special case exists with indexes created by PermIIndex() and TempIIndexXtd(). By default, both functions create and fill index files in one action without allowing a condition to be set. The ability to separate the index creation from the index build permits UpdateConditionalIndex() to set conditional expressions for the new indexes. If PermIIndex() is involved, the data file has its conditional index resource updated. If TempIIndexXtd() is involved, no permanent storage of the conditional index expression is made. The proper steps are:

Call PermIIndex() or TempIIndexXtd() with ifilptr -> dxtdsiz == ctNO_IDX_BUILD.
Call UpdateConditionalIndex() for each new index with a conditional expression.
Call RebuildIIndex() for the new indexes.

Note: Do not close the newly created indexes between a call to PermIIndex() or TempIIndexXtd() and a call to RebuildIIndex().

UpdateConditionalIndex() creates a temporary conditional index if called for a temporary index. The data file conditional index resource is not updated. Once the temporary index closes, the conditional expression goes with it. To accomplish this:

Execute TempIIndexXtd() with the dxtdsiz parameter of the IFIL structure set to ctNO_IDX_BUILD to create an empty index file.
Call UpdateConditionalIndex() to add the condition.
Call RebuildIIndex() to fill the index.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful update of condition expression resource.
401	RNON_ERR	Resources not enabled.
597	CINI_ERR	Failed syntax check.
614	HMAP_ERR	No map to a data file exists for keyno.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

UpdateMyIndex(pIFIL ifilptr, FILNO keyno, pTEXT condexpr)

{

/* This function updates the conditional expression of a given

index and rebuilds the index. Requirements include proper

c-tree ISAM initialization and IFIL file open. */

keyno = ifilptr->tfilno;

if (UpdateConditionalIndex(keyno, condexpr))

return(isam_err);

if (RebuildIIndex(ifilptr)) {

printf("Rebuild failed after conditional index update.");

return(isam_err);

}

printf("Condition changed for index %d to %s.", keyno, condexpr);

return();

}