F.34 CreateIndexFile

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 Section 3.2.1 "Alternative Key Types" on page 3-4 in the c-tree Plus Programmer's Reference Guide 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 indices 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 indices 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 indices, 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:

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.

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 8 "c-tree Plus Features" of the c-tree Plus Programmer's Reference Guide. 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 Appendix A "c-tree Plus Error Codes" of the c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.

EXAMPLE

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.