Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic


In general, after you have created/opened a superfile member you do not have to change how you process the files. There are, however, some restrictions and/or considerations when using superfiles.

Nested Superfiles

A superfile cannot contain another superfile.

Physical Order

Since multiple data and index files are stored in a superfile, the concept of processing a file in physical order no longer applies. Records from different files may be intermixed.

When using LastRecord() and PreviousRecord() with a data file number, they return an error code. FirstRecord() and NextRecord() traverse all of the records, but are not guaranteed to be visited in increasing record offset order.

All of these functions continue to work as expected with an index file number.

Node Size

When a superfile is created, the current size of index nodes is a critical parameter.

An index node is equivalent to a record of the index file. On non-server systems, the index node size is controlled by the sect parameter in calls to InitCTree() and InitISAM(), or by the third parameter in an ISAM parameter file. On Server systems, the node size is controlled by the Server configuration, which defaults to 64 (8192 bytes).

When a superfile is opened, the index node size currently in effect must be the same as the index node size at the time the superfile was created. This is not usually a problem unless one wishes to move the file between different environments. Error SPAG_ERR (417) results if the node size does not match. By contrast, an ordinary index file can be opened as long as the current node size is not smaller than the node size at the time the index file was created.

Detect if Superfile Member Names are too Long

The length of a FairCom DB Superfile name is restricted because the Superfile directory index has a restricted key length. A new default behavior checks when the Superfile member name is restricted due to small page sizes: if the Superfile name is truncated in the Superfile member directory index, then the create of the member will fail with SNAM_ERR (418). Without this new behavior, member names that would be truncated to the same string would cause DOPN_ERR (19) and/or KOPN_ERR (18) errors.

To address the situation where names may have been truncated but no conflicts arose and would now get error SNAM_ERR at create time, a provision has been made to revert to the original behavior. A configuration option for standalone applications, ctBEHAV_CHKMBRNAMLEN is on by default. It can be turned off at compile time by defining NO_ctBEHAV_CHKMBRNAMLEN.

When using FairCom DB the configuration keyword, COMPATIBILITY NO_CHKMBRNAMLEN, has been introduced to revert to the original behavior.

Temporary Files

You should not use superfile members for temporary files or any other files that are frequently deleted. Repeated file creations and deletions will adversely affect the superfile space management since the space from a deleted file cannot be reused.


Rebuilding of superfiles when c-tree is linked with the Standalone Multi-user FPUTFGET library is not supported and is reinforced in ctsbld by SBLF_ERR (512).

Be sure all files are closed prior to attempting to rebuild a superfile. The superfile pre-pass utility and function, CTSBLD and SuperfilePrepassXtd, and the rebuild function RebuildIFIle() open the files in exclusive mode and close the files upon completion.

The ctscmp utility can be used to compact a superfile and rebuild the indices in a single operation. However, you must have disk space for a copy of the superfile in order to do this.

Single System File Descriptor

You may see reduced file I/O performance because all the I/O for all the members are funneled through a single system file descriptor.


An embedded index is used to locate the individual members in a superfile. If a single superfile is damaged, you may have a higher risk of damage because it contains multiple data and index files. Superfiles are useful in the proper circumstances (i.e., if insufficient file descriptors are available, or if it is important to have just one physical file), however, file recovery is more difficult. This should be factored into the decision of whether or not to use superfiles.

In addition, because superfile members jump over one another as they expand, superfiles can become fragmented, and therefore may experience a higher risk of performance decrease and file size increase.