OpenCtFile

Open a data file.

Short Name

OPNFIL()

Type

Low level file function

Declaration

COUNT OpenCtFile(COUNT filno, pTEXT filnam, COUNT filmod)

Description

OpenCtFile() opens the file with the name pointed to by filnam in the mode specified by filmod. Subsequent calls to other low-level data file functions use filno to reference this file. filno must be in the range 0 to fils - 1, where fils is the second parameter in the initialization routine InitCTree().

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. If filnam references an index file with additional index members, OpenCtFile() opens all indices included in the file. The indices are assigned file numbers equal to filno in OpenCtFile() plus their member number.

Before a file can be opened, it must be created with either CreateDataFile() or CreateIndexFile().

filmod is limited to the values shown below. Modes not listed below are reserved for creating files, and cannot be changed for an existing file. For example, you need not specify ctFIXED or ctVLENGTH when opening the file, as that is set when the file is created.

ctPERMANENT ctVIRTUAL

ctEXCLUSIVE ctSHARED ctREADFIL

ctCHECKLOCK ctCHECKREAD

ctDUPCHANEL

ctWRITETHRU

ctOPENCRPT

ctCHECKREAD and ctDUPCHANEL are available only with the c-tree Server. See filmod in the index for additional information. Some values must be used exclusively. For instance, you cannot use both ctSHARED and ctEXCLUSIVE.

SUPERFILES: Superfiles and superfile members, discussed in Chapter 9 “c-tree Plus Features” of the c-tree Plus Programmer’s Reference Guide, must be handled differently than standard files. Form the name of the member as follows:

<name of superfile>!<name of member>

Note: This function supports EXCLUSIVE file opens. For more information, please refer to “Multi-user File Mode”.

Return

OpenCtFile() returns an error code from the table below. On a successful open when a differently named file matches the file ID of an open file, the error return will be NO_ERROR(0) but sysiocod will be set to MFID_COD (-586). If the files are detected to actually be different, then the file ID is changed as discussed above and sysiocod is not set to MFID_COD.

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful open.
12	FNOP_ERR	Could not open file. Most likely cause is that file does not exist. Check that filnam points to correct name. Also, FNOP_ERR will be returned in a multi-user system if the file has been locked by another process.
13	FUNK_ERR	Type of file is unknown. Header record is clobbered.
14	FCRP_ERR	File found corrupt at open.
20	KMIN_ERR	Key length too large for node size.
22	FNUM_ERR	File number is out of range.
40	KSIZ_ERR	sect parameter was larger when index was created.
43	FVER_ERR	Current c-tree Plus configuration specified in ctoptn.h is incompatible with file.
45	KLEN_ERR	Key length exceeds MAXLEN in ctoptn.h.
46	FUSE_ERR	File number is already in use.

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

Example

COUNT     filno = 0, retval;

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


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

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

else {

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

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

    else if (CloseCtFile(filno, 0))

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

    if (CloseISAM())

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

Limitations

In Standalone Multi-user implementations of c-tree Plus, the locking routines depend on the operating system, and possibly the compiler. If your operating system or compiler does not support locks, you may have to code your own locking routines. The ctclib.c files provided in each sub-directory contain locking routines and shared file opening facilities for the popular multi-user and network systems.