FairCom ISAM for C

PermIIndex

Permanent Incremental Index creation.

Short Name

PRMIIDX()

Type

ISAM function

Declaration

COUNT PermIIndex(pIFIL ifilptr)

Description

In a single call to PermIIndex(), your application program will:

Add one or more additional indexes to an existing Incremental ISAM definition.
Automatically load the indexes from the existing data (optional).
Reference the new indexes with the standard ISAM level calls (e.g., the next AddRecord() call updates the new indexes along with the original indexes).
If resources are enabled, automatically update the stored file definition to include the new indexes.

Note: This command requires an exclusive open of the file. c-tree attempts to open the file in exclusive mode while allowing other connections read access. If the file is already open, c-tree flushes updates to disk and sets the update flag to zero to indicate that the file is in a clean, consistent state. If c-tree cannot open the file in exclusive mode, this operation fails.

When the Incremental file is closed via CloseIFile(), CloseISAM(), or CloseRFile(), the new indexes are automatically closed. The next Incremental open automatically includes the new indexes if OpenFileWithResource() is used, or if you have updated your Incremental structures and use OpenIFile().

The key values from the existing records will be added automatically. The additional indexes created and loaded by PermIIndex() reside in a separate index file, distinct from the index file(s) already in existence for the data file. There is no extended form of this function because the new indexes are automatically assigned the security information assigned to the existing indexes.

To disable the automatic load feature, set the dxtdsiz parameter of ifilptr to ctNO_IDX_BUILD. This creates the new index without loading key values into it. This feature allows PermIIndex() to be followed by UpdateConditionalIndex(), limiting the keys the index loads to those that meet the specified condition. Once the condition is in place, call RebuildIIndex() to fill the index. Do not close the files between PermIIndex() and RebuildIIndex().

ifilptr points to a new IFIL structure in which:

dfilno contains the file number of the underlying Incremental data file.
ix points to the new index definitions.
tfilno is -1 if you wish the index file number to be assigned, or tfilno is set to the first desired index number.
dnumidx is the number of index files to create.

Note: The underlying data file is not determined by the pfilnam member of the new IFIL structure. dfilno specifies the data file involved.

The IFIL file name and location enhancement automatically locates index files created by PermIIndex() or TempIIndexXtd() in the same directory as the associated data file. With PermIIndex() only, it also allows the IFIL entry for the index file to have the same directory as the associated data file, even if the data file is not in its original directory. To activate this feature, the index file name in the aidxnam parameter of ifilptr should be in the form:

+index_name

By placing a plus sign,‘+’s the first character of the index name, the new index automatically “follows” the data file, i.e., it is created in the same directory as the data file. c-tree can open files via OpenFileWithResource() in a directory different from the directory in the file’s internal IFIL resource. When this happens, OpenFileWithResource() expects any index that had the same directory as the data file to be in the new directory.

The plus sign is not part of the actual file name used to create the index. Mirrored file name components use this option independently. Only the name components beginning with the plus sign invoke this feature. For example, the following would all be “legal” for aidxnam entries:

+primary_index|+mirror_index

+primary_index|mirror_index

primary_index|+mirror_index

Adding an Index to an Existing File

FairCom has always supported adding an additional index to an existing file if the index is placed in a new physical file. If you need to add an additional index to an existing file and want to store the new index in the same physical file, PermIIndex() is the preferred method. This support is available starting in V11.2.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful creation of new permanent index.
62	LERR_ERR	Underlying data file must be opened ctEXCLUSIVE.
107	IDRK_ERR	Too many index files for one data file. Increase MAX_DAT_KEY parameter in ctoptn.h or keyword in ctsrvr.cfg.
197	IMEM_ERR	Not enough memory.
465	IINI_ERR	ifilptr->dnumidx < 1.
466	IIDT_ERR	ifilptr->dfilno does not reference an ISAM data file.
467	IINM_ERR	ifilptr->ix->aidxnam must point to a new index file name.
468	IITR_ERR	Incremental index cannot be built inside a transaction.

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

Example

pIFIL newindex;

FILNO filno;

VRLEN bufsiz;

filno = OpenFileWithResource(-1,"test", (ctEXCLUSIVE | ctPERMANENT));

if (filno < 0) {

printf("\nOpen failed");

exit(1);

}

bufsiz = GetIFile(filno, 0, newindex);

newindex = (pIFIL) mballc(1, bufsiz);

GetIFile(filno, bufsiz, newindex);

newindex->dfilno = filno;

newindex->tfilno = -1;

newindex->dnumidx = 1;

newindex->aidxnam = "testnew";

if (PermIIndex(newindex))

printf("\nAdding Index failed (%d %d)",isam_err,isam_fil);

Limitations

The Incremental ISAM files must be opened ctEXCLUSIVE.