FairCom ISAM for C

OpenCtFile

Open a data file.

Short Name

OPNFIL()

Type

Low-Level file function

Declaration

COUNT OpenCtFile(FILNO filno, cpTEXT filnam, COUNT filmod)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

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 indexes included in the file. The indexes 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 FairCom 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 the chapter titled “c-tree Features” of the c-tree Programmer’s Reference Guide, must be handled differently than standard files. Form the name of the member as follows:

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 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.
775	UNQK_ERR	No UNQKEY support for REPLICATION. If a Low-Level file open call that requests write access to a c-tree data file fails with this error, it is because the data file has replication enabled. A c-tree data file that has replication enabled can only be opened for write access at the ISAM level. A read-only Low-Level call is allowed: use the ctREADFIL \| ctSHARED filemodes when opening the file in addition to the other filemode options that you are using.

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

Example

FILNO filno = 0;

COUNT retval=0;

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

if (retval = InitCTree(100, 10, 64))

printf("\nCould not initialize c-tree connection. Error %d.", retval);

else {

if (retval = OpenCtFile(filno, filnam, (ctSHARED | ctFIXED)))

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

else if (CloseCtFile(filno, 0))

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

if (retval = StopUser())

printf("\nCould not close c-tree connection. Error %d.", retval);

}

Limitations

In Standalone Multi-user implementations of c-tree, 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.