CreateDataFile

Create a data file.

Short Name

CREDAT()

Type

Low level data file function

Declaration

COUNT CreateDataFile(COUNT 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 c-tree Server. See filmod in the index for additional information.

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” in the c-tree Plus Programmer’s Reference Guide 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 c-tree Concepts chapter in the c-tree Plus Features” of the c-tree Plus Programmer’s Reference Guide, 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:

<name of superfile>!<name of member>

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 c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

COUNT     datno = 0, 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.