FairCom ISAM for C

CreateIndexFile

Create an index file.

Short Name

CREIDX()

Type

Low-Level index file function

Declaration

COUNT CreateIndexFile(FILNO keyno, cpTEXT filnam, COUNT keylen,

COUNT keytyp, COUNT keydup, COUNT nomemb,

UCOUNT xtdsiz, COUNT filmod)

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

CreateIndexFile() attempts to create a new index file with the name pointed to by filnam and with a key length of keylen bytes. If a file with the name pointed to by filnam already exists, CreateIndexFile() returns an error code, and the file is not opened.

keyno must be in the range 0 to fils - 1 where fils is the second parameter in the initialization routine InitCTree(). Subsequent calls to other Low-Level index file functions use keyno to reference this file.

keytyp determines whether keys are fixed length or use some form of compression. See Alternative Key Type for more information.

keydup of 0 indicates no duplicates allowed, and a value of 1 indicates duplicate keys are supported.

Note: Allowing duplicate records assumes the last 4 bytes of keylen is available for the record offset. Add 4 bytes to the length of the key segments making up a duplicate key.

nomemb specifies the number of additional indexes which will reside in this index file. Combining more than one index in one physical index file reduces the file descriptors used by an application. If nomemb is zero (0), no additional indexes are included. Each additional index has its own key length, key type and auto-duplication parameter. In order to set these parameters for the additional indexes, CreateIndexMember() should be called for each additional index immediately after the call to CreateIndexFile().

Once the index file and all its members have been created, a single call to OpenCtFile() activates all members of the index file. See OpenCtFile() for a more complete discussion. Each additional index is referenced by a file number equal to keyno plus the member number. For example, if keyno is three (3) and nomemb is five (5), the index created by CreateIndexFile() will be referenced by file number three (3). The first additional index will be referenced by key number four (4), the second by five (5), and so on through key number eight (8).

If xtdsiz is greater than zero, whenever it is necessary to extend the size of the index file, it will be extended by xtdsiz bytes and the directory will be updated. If xtdsiz is set too large, then disk space will be wasted. If xtdsiz is too small (but greater than zero), the time to extend the file and force a directory update will become excessive. A value of zero for xtdsiz causes the file to grow one B-Tree node at a time without the directory being updated until the file is closed.

filmod determines whether the index is shared or used exclusively, and whether it is opened permanently or virtually. The following list shows the values that can be used for filmod. You can combine the values by OR-ing them together, such as:

(ctVIRTUAL | ctEXCLUSIVE)

Some values must be used exclusively of others. For instance, you cannot use both ctSHARED and ctEXCLUSIVE. You cannot use more than one mode from any line in the listing below. In addition, you must use one of the modes from each of the first two groups.

ctPERMANENT ctVIRTUAL

ctEXCLUSIVE ctSHARED ctREADFIL

ctPREIMG ctTRNLOG

ctDUPCHANEL

ctWRITETHRU

Note: ctDUPCHANEL is available only if you are using the FairCom Server and only with limited platforms.

Except for ctPREIMG and ctTRNLOG, filmod is not permanently stored with the file. A file may be opened as a read only (ctREADFIL) one time, ctSHARED another and ctEXCLUSIVE yet another time.

The name referenced by filnam must conform to the operating system environment, and usually can include directory path names and/or disk drive identifiers. The file name should be null terminated.

Superfiles: An index file can be a member of a Superfile, as discussed in the Chapter 9 “FairCom DB Features”. The name of the member must be formed as follows:

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Index file successfully created.
16	KCRAT_ERR	Could not create index file. Possibly no disk or directory space, no more file descriptors, or an improper file name.
18	KOPN_ERR	Index file already exists. File is not opened.
20	KMIN_ERR	Key length too large for node size (determined by node sectors in call to InitCTree()). There must be room for at least four key values per node.
22	FNUM_ERR	keyno + nomemb is out of range.
23	KMEM_ERR	nomemb < 0 or nomemb > 31.
45	KLEN_ERR	Key length exceeds MAXLEN parameter in ctoptn.h.
46	FUSE_ERR	A file number in the range keyno to keyno + nomemb is already in use.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO keyno = 0;

COUNT retval, keylen,keytyp,keydup,nomemb;

UCOUNT xtdsiz = 1024;

TEXT filnam[15] = "sample.dat";

if (retval = InitCtree(6,7,4))

printf("\nCould not initialize. Error %d.", retval);

else {

if (CreateIndexFile(keyno, filnam, keylen, keytyp, keydup,

nomemb, 8192, (ctSHARED | ctVIRTUAL)))

printf("\nError %d creating file %.14s",uerr_cod,

filnam);

else if (CloseCtFile(keyno, 0))

printf("\nCould not close file.");

if (OpenCtFile(keyno, filnam, (ctSHARED | ctVIRTUAL | ctFIXED)))

printf("\nCould not open file.");

else if (CloseCtFile(keyno, 0))

printf("\nCould not close file.");

if (CloseISAM())

printf("\nCould not close ISAM.");

}

Limitations

While CreateIndexFile() allows a file to be marked for sharing, it does not actually create the index in the shared mode. For an index file to be shared by multiple users, it must be created, then closed (CloseCtFile()), then opened (OpenCtFile()) with a shared file mode. Most application programs use a separate module to create the files at installation time, so the main module will only open the files.

If using an alternate collating sequence, call SetAlternateSequence() immediately after creating the index file to assign an alternate collating sequence to the index file.