FairCom ISAM for C

InitISAM

Initialize file structures and index buffer area.

Short Name

INTISAM()

Type

ISAM function

Declaration

COUNT InitISAM(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

InitISAM() 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, and prepares for incremental ISAM creates and opens.

Before any other ISAM functions can be used, InitISAM(), OpenISAM(), or CreateISAM() must be called. Further, these are mutually exclusive; only one of these routines can be called at a time. Once one of these has been called, you must call CloseISAM() before invoking one of these three functions again.

The InitISAM() 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 the index files via a “least recently used” scheme.

In Standalone Multi-user applications, 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 application, 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 fixed permanently. 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 InitISAM().
10	SPAC_ERR	Too much space required. Reduce bufs.
11	SPRM_ERR	Illegal InitISAM() parameters.
104	IFIL_ERR	Too many files specified. Increase MAXFIL in ctoptn.h and rebuild library.
125	IINT_ERR	c-tree already initialized. Call CloseISAM() before recalling InitISAM().
182	IKSR_ERR	No room for r-tree temporary files. Increase ctMAXFIL in ctoptn.h or disable RTREE, and rebuild library.

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

Example

COUNT retval;

if (retval = InitISAM(6,7,4)) {

printf("\nCould not initialize c-tree. Error #%d\n",

retval);

exit(2);

}