FairCom ISAM for C

CreateIFile

Incremental ISAM create.

Short Name

CREIFIL()

Type

ISAM function

Declaration

COUNT CreateIFile(pIFIL ifilptr)

Description

CreateIFile() creates the data file and (optional) index file referenced by the IFIL structure pointed to by ifilptr. The file name pointed to by the IFIL structure, ifilptr- >pfilnam, should NOT include an extension: “.dat” and “.idx” are automatically appended to the file name for the data file and index file, respectively. The extended version of this function, CreateIFileXtd(), can change the file extensions at runtime.

If you desire the files to be created in directories that are not specified until runtime, then ifilptr- >pfilnam should not be finalized until runtime.

Consecutive file numbers are assigned to the data file and any (optional) indexes associated with the data file. The IFIL structure contains two file numbers: a permanent file number (dfilno), and a temporary file number (tfilno). If dfilno is less than zero, FairCom DB finds the first available block of sufficient consecutive file numbers. If such a block of numbers is found, then the first number in the block is assigned to the data file and to tfilno. If dfilno is greater than or equal to zero, then dfilno is assigned to the data file and to tfilno.

Unless Resources are disabled for this file, CreateIFile() automatically stores the IFIL definition in the file as a resource. This permits OpenFileWithResource() to open the entire IFIL set simply by file name.

Prevent ISAM Index Key Value Updates

Beginning with V11, it is possible to create an index that does not allow an ISAM update to change the key values. On such an index, an ISAM record add can add a new key value and an ISAM record delete can delete a key value, but an ISAM record update cannot change a key value. (Note the special case for a variable-length record: if an ISAM update causes the record to move, the key is allowed to change its record offset from the old offset to the new offset; but the key value itself is not allowed to change.)

To create an index with this feature enabled, OR KTYP_NOISMUPD into the key type (ikeytyp) field of the IIDX structure for that index file before calling CREIFIL() to create the index.

PUTIFIL() can be used to turn this bit on or off. Changes take effect immediately.

An ISAM record update that attempts to change a key value for an index with this property enabled fails with error UKEY_ERR (1001).

Return

Upon successful create, ifilptr->tfilno contains the file number assigned to the data file; and the associated indexes are assigned consecutive index numbers starting one (1) greater than the data file number.

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful open of ISAM files.
16	KCRAT_ERR	Could not create index file.
17	DCRAT_ERR	Could not create data file.
18	KOPN_ERR	Index file already exists. File is not opened.
19	DOPN_ERR	Data file already exists. File is not opened.
20	KMIN_ERR	Key length too large for node size.
21	DREC_ERR	Record length is too small. File is not created.
22	FNUM_ERR	File number is out of range.
45	KLEN_ERR	Key length exceeds MAXLEN parameter in ctoptn.h.
46	FUSE_ERR	File number is already in use.
47	FINT_ERR	FairCom DB has not been initialized. Call InitISAM before the first call to CreateIFile().
107	IDRK_ERR	Too many index files for one data file. Increase MAX_DAT_KEY parameter in ctoptn.h or keyword in ctsrvr.cfg.
109	IKRS_ERR	Too many key segments. Increase MAX_KEY_SEG parameter in ctoptn.h.
115	ISLN_ERR	Key segments do not equal key length.

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

Example

extern IFIL myfile;

COUNT retval;

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

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

else {

if (CreateIFile(&myfile))

printf( "\nCould not create %s (%d,%d)\n",

myfile.pfilnam, isam_err, isam_fil );

else if (CloseIFile(&myfile))

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

if (OpenIFile(&myfile))

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

else if (CloseIFile(&myfile))

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

if (CloseISAM())

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

}

Limitations

The index files will be numbered consecutively following the data file. See “File numbering” in the index for additional information.

While CreateIFile() can mark files for shared use, they is not created in the shared mode. In order to use files in the shared mode, they must first be created, then closed, then opened with a shared file mode.