FairCom ISAM for C

CreateDataFile

Create a data file.

Short Name

CREDAT()

Type

Low-Level data file function

Declaration

COUNT CreateDataFile(FILNO datno, pTEXT filnam, UCOUNT datlen,

UCOUNT xtdsiz, COUNT filmod)

Description

CreateDataFile() attempts to create a new data file with the name pointed to by filnam and with a record length of datlen. Subsequent calls to other Low-Level data file functions use datno to reference this file. datno must be in the range 0 to fils - 1, where fils is the second parameter in the initialization routine InitCTree().

If a file with the name pointed to by filnam already exists, CreateDataFile() returns an error code, and the file is not opened.

filmod determines if the file contains fixed- or variable-length records, whether it 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:

(ctVIRTUAL | ctEXCLUSIVE | ctFIXED)

Some values must be used exclusively. 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 three groups.

ctPERMANENT ctVIRTUAL

ctEXCLUSIVE ctSHARED ctREADFIL

ctFIXED ctVLENGTH

ctCHECKLOCK

ctCHECKREAD

ctPREIMG ctTRNLOG

ctDUPCHANEL

ctWRITETHRU

ctSUPERFILE

ctDISABLERES

ctCHECKREAD and ctDUPCHANEL are available only if you are using the FairCom Server. See filmod in the index for additional information.

Note: ctCHECKLOCK and ctCHECKREAD are intended as debugging aids to help developers to identify code locations where locks are not being acquired.

ctCHECKREAD is not compatible with ctSUSPEND by definition because ctSUSPEND will disable record lock acquisition without releasing existing locks, so any record read would then trigger the ctCHECKREAD error condition.

ctCHECKLOCK and ctCHECKREAD should not be applied to index files.

If the file is created with a fixed record length, then datlen must be greater than 4. If the file is created with a variable record length, then datlen is interpreted as the fixed portion of the record for the file and may be greater than or equal to zero. See Fixed versus Variable-length Records for more information.

If xtdsiz is greater than zero, then whenever it is necessary to extend the size of the data 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), then 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 data record at a time without the directory being updated until the file is closed.

When a fixed record length data file is extended by xtdsiz bytes, delete flags are written into the beginning of each logical record in the newly allocated space. This may cause a noticeable delay for large values of xtdsiz.

Except for ctFIXED versus ctVLENGTH, and ctPREIMG versus 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.

ctSUPERFILES: Superfiles and superfile members, discussed in “Advanced FairCom DB Concepts", must be handled differently than standard files. When creating a superfile, the file mode ctSUPERFILE must be OR-ed. Set xtdsiz and datlen to 0. Superfiles consume two consecutive file numbers, datno and datno + 1. Superfile members can be a mixture of data and index files. The name of the member must be formed as follows:

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Data file successfully created.
17	DCRAT_ERR	Could not create data file.
19	DOPN_ERR	Data file already exists. File is not opened.
21	DREC_ERR	Record length is too small. File is not created.
22	FNUM_ERR	File number is out of range.
46	FUSE_ERR	File number is already in use.
413	SDIR_ERR	Host superfile is not open.
414	SNST_ERR	Cannot nest superfiles.

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

Example

FILNO datno = 0;

COUNT retval, reclen = 64;

UCOUNT xtdsiz = 1024;

TEXT filnam[15] = "sample.dat";

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

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

else {

if (CreateDataFile(datno, filnam, reclen, xtdsiz,

(ctSHARED | ctVIRTUAL | ctFIXED)))

printf("\nError %d creating file %.14s", uerr_cod, filnam);

else if (CloseCtFile(datno, 0))

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

if (OpenCtFile(datno, filnam, (ctSHARED | ctVIRTUAL | ctFIXED)))

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

else if (CloseCtFile(datno, 0))

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

if (CloseISAM())

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

}

Limitations

While CreateDataFile() can mark a file for shared use, it is not created in the shared mode. In order to use a data file in the shared mode, it must first be created, then closed (CloseCtFile()), then opened (OpenCtFile()) with a shared file mode.