FairCom ISAM for C

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 indexes to an existing Incremental ISAM definition.
Automatically loads the indexes from the existing data (optional).
References the new indexes with the standard ISAM level calls (e.g., the next AddRecord() call updates the new indexes along with the original indexes).

The next time the Incremental file is opened, the new indexes 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 (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

Note: There is the potential for index/data inconsistency errors, such as RVHD_ERR (123), ITIM_ERR (160), etc., 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.

When a multiuser error occurs on a temporary index, the default server behavior is to skip the offending record and treat it as deleted. If another record satisfies the search request, that record will be returned. sysiocod is set to ITMP_COD (-832) to indicate the skipped record. This record skipping behavior can be disabled with server keyword COMPATIBILITY TEMP_INDEX_ERROR.

The ability to suspend the addition of existing data records to the newly created index creates new indexes without inserting keys for the existing records. This allows an application to have indexes 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 indexes to reference only the newly added data. The temporary indexes 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 Error Codes for a complete listing of valid c-tree error values.