TempIIndexXtd

Temporary Incremental Index creation.

Short Name

TMPIIDXX()

Type

Extended ISAM function

Declaration

COUNT TempIIndexXtd(pIFIL ifilptr, LONG permmask,

                    pTEXT groupid, pTEXT fileword)

Description

TempIIndexXtd() behaves the same as PermIIndex() except that the stored file definition is not updated, and you may be sharing the underlying Incremental data file. Each user can have separate and distinct temporary index files. Once the data file, ifilptr -> pfilnam, is closed the temporary index is no longer part of the Incremental ISAM structure. A single call:

Adds one or more additional indices to an existing Incremental ISAM definition.
Automatically loads the indices from the existing data (optional).
References the new indices with the standard ISAM level calls (e.g., the next AddRecord() call updates the new indices along with the original indices).

The next time the Incremental file is opened, the new indices will NOT be opened and used. However, the temporary file is not deleted. It should be deleted by the application using OpenCtFile() in ctEXCLUSIVE mode, followed by DeleteCtFile().

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 set to the first desired index number, or tfilno is -1 if you wish the index file number to be assigned, which is returned in tfilno.
dnumidx is the number of index files to create.

permmask is the permission mask assigned to this data file. It is formed by OR-ing the appropriate permission constants.

groupid is a pointer to a buffer that contains the group id that this file is to be assigned to. The group id must be valid for the user that is creating the file. If groupid is NULL, the file will be assigned to the default group for the user.

fileword is an optional file password. If fileword is NULL then there will be no password for this file. If a password is established, every user will need to use the password to be able to open the file. For more information on user id’s, user passwords, server names, permission masks, group id’s, and file passwords, review “Security and Encryption” in the c-tree Plus Programmer’s Reference Guide.

Note: There is the potential for ITIM_ERR errors (160, key value changed between index search and subsequent data record read) when using a temporary index in a multi-user environment. Temporary indexes are visible ONLY to the user who creates them, and therefore any record updates and/or deletions by other users are not applied to the temporary index.

The ability to suspend the addition of existing data records to the newly created index creates new indices without inserting keys for the existing records. This allows an application to have indices containing only new entries, speeding access to newer data. Consider the following pseudocode:

Call TempIIndexXtd() with ifilptr -> dxtdsiz == ctNO_IDX_BUILD.
Do NOT call RebuildIIndex().
Add new data records, but no deletes or rewrites.
Use the temporary indices to reference only the newly added data. The temporary indices will not have any of the data that existed prior to the TempIIndexXtd() call.

See the ctNO_IDX_BUILD description in PermIIndex() for details.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful creation of new temporary index.
107	IDRK_ERR	Too many index files for one data file. Increase MAX_DAT_KEY 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 Plus Error Codes for a complete listing of valid c-tree Plus error values.