FairCom ISAM for C

OpenFileWithResource

Incremental ISAM open, based on the IFIL Resource.

Short Name

OPNRFIL()

Type

ISAM function

Declaration

COUNT OpenFileWithResource(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

OpenFileWithResource() opens the data file with the name pointed to by filnam and optional index files referenced by the IFIL resource information stored in that file. This resource was automatically added to the file when the file was created with CreateIFile() unless Resources have been disabled for this file. All subsequent references to the file are made via the filno value. filno must be less than fils - 1, where fils is the second parameter in the initialization routine InitISAM().

The name referenced by filnam must conform to the operating system environment, and usually can include directory path names and/or disk drive identifiers. If you are trying to open a file in a subdirectory of the data folder, your path must start with "." as in ./subdir/MyFile.dat.

If OpenFileWithResource() is called with a different path than the original IFIL definition holds, an attempt is made to automatically update alternative index names with the same path modification. The file name should be null terminated. If filnam references an index file with additional index members, OpenFileWithResource() opens all indexes included in the file.

Consecutive file numbers are assigned to the data file and any associated indexes. If filno is less than zero, c-tree finds the first available block of consecutive file numbers that can accommodate the data file and its indexes. If a block of numbers is found, the first number in the block is assigned to the data file and returned. If filno is greater than or equal to zero, filno is assigned to the data file and returned provided enough consecutive file numbers are available.

filmod is limited to the values shown below. Modes not listed are reserved for file creation and cannot change for an existing file. For example, ctFIXED or ctVLENGTH are not specified when opening the file, as they are 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.

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

Return

OpenFileWithResource() returns the file number assigned to the data file. If an error occurs, the function returns a -1 and isam_err contains an error code. 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. FNOP_ERR will be returned in a multi-user system if the file has been locked by another process. Check isam_fil for the specific file number.
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.
45	KLEN_ERR	Key length exceeds MAXLEN in ctoptn.h.
46	FUSE_ERR	File number is already in use.
107	IDRK_ERR	Too many index files for one data file. Increase MAX_DAT_KEY parameter in ctoptn.h.
109	IKRS_ERR	Too many key segments. Increase MAX_KEY_SEG parameter in ctoptn.h.

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 = InitISAM(6,7,4))

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

else {

if (OpenFileWithResource(filno, filnam, ctSHARED) < 0)

printf("\nCould not open file (%d,%d).", isam_err, sysiocod);

else if (CloseRFile(filno))

printf("\nCould not close file (%d,%d).", isam_err, sysiocod);

if (CloseISAM())

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

}

Limitations

The data file must contain a resource record with the appropriate Incremental ISAM Structures (IFIL, etc.). CreateIFile() inserts a resource record and adds Incremental ISAM Structures. However, if the file was created without resource records, by either removing #define RESOURCE from ctoptn.h or by using ctDISABLERES as a file mode, resources can be enabled dynamically using EnableCtResource(). The Incremental ISAM Structures can be inserted by calling PutIFile().