FairCom ISAM for C

InitCTree

Initialize file structures and index buffer area.

Short Name

INTREE()

Type

Low-Level file function

Declaration

COUNT InitCTree(COUNT bufs, FILNO fils, COUNT sect)

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

InitCTree() acquires the memory space necessary for the data and index file structures as well as the space for the index file buffers. Finally, it initializes this memory area. Call CloseISAM() or StopUser() to free these resources.

The InitCTree() parameters are defined as follows:

Parameter	Interpretation
bufs	The number of index file buffers. Minimum of three required.
fils	An initial block of file structures. Whenever the number of files required by your application exceeds this initial amount, c-tree automatically allocates another block of file structures using this number. Each index, whether it is a member of an index file or in a file by itself counts toward the fils parameter.
sect	The number of node sectors. Minimum of one required. sect multiplied by 128 equals the index node size.

In a single user system, increasing bufs reduces the number of disk accesses necessary to retrieve a key value. The buffers are shared across all index files via a “least recently used” scheme.

In Standalone Multi-user systems, the need to force updates back to the disk implies that local buffering is of little value. Rather, the shared hard disk should be cached in order to achieve global buffering of the index file. In a Standalone Multi-user system, bufs should be set around three, regardless of the number of index files in use.

sect * 128 determines how many bytes are available in each B-Tree node. When an index file is created, the node size is permanent. When an index file is opened, a check is made to be sure that the current node size is at least as large as when the index was created. That is, an index file can be opened if sect has been increased since file was created, but not if it has been reduced. Superfiles must be opened with the exact node size as when they were created.

Originally, the most common value used for sect is four, yielding a node size of 512 bytes. For efficiency, set the sect value to create nodes equal to the page size for the platform. Most common would be 32, yielding a node size of 4K.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful call to InitCTree().
10	SPAC_ERR	Too much space required. Reduce bufs.
11	SPRM_ERR	Illegal InitCTree() parameters.
125	IINT_ERR	c-tree already initialized. Call CloseISAM() before recalling InitCTree().

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

Example

COUNT retval;

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

printf("\nCould not initialize c-tree: Error %d.", retval);

else {

printf("\nc-tree initialized.");

StopUser()

}