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:

<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.

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.

See also

InitCTree(), CreateDataFile(), CreateIndexFile(), OpenCtFile(), OpenCtFileXtd()

OpenCtFileXtd

Extended data or index file open.

Short Name

OPNFILX()

Type

Extended Low-Level file function

Declaration

COUNT OpenCtFileXtd(FILNO filno, cpTEXT filnam, COUNT filmod, cpTEXT fileword)

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

OpenCtFileXtd() is a variation of OpenCtFile() that permits the use of the FairCom Server’s security system. This section expands on the description of OpenCtFile().

fileword is an optional file password. Set fileword to NULL if there is no password for this file. If a password is established, every user will need to use the password to be able to open the file. For more information on file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

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

Return

The following error codes may be seen in addition to those for OpenCtFile():

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

See also

InitCTree(), CreateIndexFile(), OpenCtFile()

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.

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().

See also

EnableCtResource(), PutIFile(), OpenIFile(), InitISAM(), CreateIFile(), CloseISAM(), OpenFileWithResourceXtd() and ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide describing the ISAM parameters.

OpenFileWithResourceXtd

Incremental ISAM open, based on the IFIL Resource (extended).

Short Name

OPNRFILX()

Type

Extended ISAM function

Declaration

COUNT OpenFileWithResourceXtd(FILNO filno, cpTEXT filnam,
                              COUNT filmod, cpTEXT fileword)

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

OpenFileWithResourceXtd() is a variation of OpenFileWithResource() that permits the use of the FairCom Server’s security system. This section expands on the description of OpenFileWithResource().

fileword is an optional file password. Set fileword to NULL if there is no password for this file. If a password is established, every user will need to use the password to be able to open the file. For more information on file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

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

Return

OpenFileWithResourceXtd() 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. The following error codes may be seen in addition to those for OpenFileWithResource():

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

Return Relative File Number

In V11.5 and later, the OPNRFILX() function has been modified so that, when it is called with a negative data file number, if the open fails, isam_fil is returned as a relative file number:

isam_fil = 0 indicates the data file open failed.
isam_fil = 1 indicates the first index open failed, etc.

Note: This feature is a Compatibility Change.

Prior to this change, OPNRFILX() set isam_fil to the file number that was not possible to open. However, it did not return useful information when it was called with a negative data file number, such as OPNRFIL(-1).

See also

InitISAM(), CreateIFile(), OpenFileWithResource()

OpenIFile

Incremental ISAM open.

Short Name

OPNIFIL()

Type

ISAM function

Declaration

COUNT OpenIFile(pIFIL ifilptr) 

Description

OpenIFile() opens the data file and (optional) index file referenced by the IFIL structure pointed to by ifilptr. The file name pointed to by the IFIL structure, ifilptr->pfilnam, should NOT include an extension: .dat and .idx are automatically appended to the file name for the data file and index file, respectively. The extended version of this function, OpenIFileXtd(), can change the file extensions at run time.

If you desire the files to be opened in directories that are not specified until run-time, then ifilptr->pfilnam should not be finalized until run-time.

Consecutive file numbers are assigned to the data file and any (optional) indexes associated with the data file. The IFIL structure contains two file numbers: a permanent file number (dfilno), and a temporary file number (tfilno). If dfilno is less than zero, c-tree finds the first available block of sufficient consecutive file numbers. If such a block of numbers is found, then the first number in the block is assigned to the data file and to tfilno. If dfilno is greater than or equal to zero, then dfilno is assigned to the data file and to tfilno.

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

Return

Upon successful open, ifilptr->tfilno contains the file number assigned to the data file; and the associated indexes are assigned consecutive index numbers starting one (1) greater than the data file number.

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.

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

Example

extern IFIL     myfile;
       COUNT    retval;

if (retval = InitISAM(6,7,4))
    printf("\nCould not close files. Error %d.", retval);
else {
    if (CreateIFile(&myfile))
        printf( "\nCould not create %s (%d,%d)\n", 
               myfile.pfilnam, isam_err, isam_fil );
    else if (CloseIFile(&myfile))
        printf("\nCould not close files.");
   
    if (OpenIFile(&myfile))
        printf("\nCould not open files.");
    else if (CloseIFile(&myfile))
        printf("\nCould not close files.");

    if (CloseISAM())
        printf("\nCould not close ISAM.");
}

Limitations

The index files will be numbered consecutively following the data file. See “File numbering” in the index for additional information.

See also

InitISAM(), CreateIFile(), CloseISAM(), OpenIFileXtd(), OpenFileWithResource(), GetIFile() and ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide, which describes the ISAM parameters.

OpenIFileXtd

Extended Incremental ISAM open.

Short Name

OPNIFILX()

Type

Extended ISAM function

Declaration

COUNT OpenIFileXtd(pIFIL ifilptr, cpTEXT dataextn,
                   cpTEXT indxextn, cpTEXT fileword)

Description

OpenIFileXtd() is a variation of OpenIFile() that permits the use of the FairCom Server’s security system. This section expands on the description of OpenIFile().

dataextn and indxextn point to buffers specifying the data and index file name extensions, respectively. The extensions are 8-byte ASCIIZ (NULL terminated ASCII) strings. If the pointers are NULL, the default extension will be used: .dat for data files and .idx for index files. For files with no extension, pass a pointer to a buffer that contains only blanks terminated by a NULL character.

fileword is an optional file password. If fileword is null then there will be no password for this file. If a password is established, every user will need to use the password to be able to open the file.

For more information on permission masks, group id’s, and file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

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

Return

The following error codes may be seen in addition to those for OpenIFile():

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

See also

InitISAM(), OpenIFile(), CloseISAM()

OpenISAM

Open all the ISAM files.

Short Name

OPNISAM()

Type

ISAM function

Declaration

COUNT OpenISAM(pTEXT filnam) 

Description

OpenISAM() opens the parameter file, whose name is pointed to by filnam, and opens the data and index files specified in the parameter file. Application programs using the ISAM level functions must make a call to InitISAM() or OpenISAM() before any other c-tree functions are used. If any one of these three functions has been called, then CloseISAM() must be called before anyone of them can be invoked again. In part, this implies that no more than one ISAM parameter file may be active at one time. However, the incremental ISAM functions allow for more flexibility in file manipulations and are highly recommended.

Using virtual files, the parameter file may contain more files than available file descriptors. c-tree automatically manages the open and close of virtual files.

Although it is not recommended, it is possible to use incremental ISAM file opens and opens along with a parameter file. Increase the value of the second parameter in the parameter file, (idxs), by the total number of files used by the incremental routines. For example, if the incremental routines open two additional data files, each with five indexes, then the idxs parameter in the ISAM parameter file should be increased by 12.

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

Return

OpenISAM() 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.

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

Example

TEXT      isam_par[64];

printf("\nEnter ISAM parameter file name: ");
scanf("%63s",isam_par);
if (OpenISAM(isam_par))
    printf("\nCould not open ISAM.");
else   
    ProcessData()

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

Limitations

It is not possible to open some of the files specified in the parameter file and create others. They must all be created by CreateISAM(). However, the incremental ISAM functions permit on the fly opening and closing of ISAM files. If you are adding a new index file to an established set of ISAM files, you should:

• Update the parameter file to include the new index.
• Use the rebuild utility to create and build the new index file. Respond no when asked to force rebuild.
• Call OpenISAM() to actually use the files.

See also

CloseISAM(), InitISAM(), CreateISAM(), CreateIFile(), OpenIFile(), OpenISAMXtd() and ISAM Parameters in the c-tree Programmer’s Reference Guide, which describes the parameter file contents.

OpenISAMContext

Opens (creates) an ISAM context.

Short Name

OPNICON()

Type

ISAM function

Declaration

COUNT OpenISAMContext(FILNO datno, FILNO keyno, COUNT contextid)

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

OpenISAMContext() returns a 2-byte integer (COUNT) which serves as the context ID. The context is maintained for the data file specified by datno. keyno is either a key for the data file or -1. If keyno is -1, then the context saves key images (values) for all the indexes associated with datno. If a specific key is specified with keyno, then the context only maintains the key value for the given index, thereby conserving memory. Opening a context actually creates the context and then selects the context as the current context for the specified data file.

If contextid is passed in as “-1”, then the next available ID is assigned. If not passed as “-1”, then the value passed is taken as the desired context ID. Note that the context IDs do not have to be consecutive numbers, and both positive and negative values are allowed. However, -1 is not a legitimate value for a context ID. It is used to signify that c-tree should automatically assign the context number.

Note: FairCom DB has an internal hard limit of 65534 contexts.

To speed the location of contexts, a simple hashing scheme is used. The number of hash bins defaults to six (6) for each user. If a large number of contexts are to be maintained, then this default can be overridden as follows:

1. Server (non-BOUND) Applications: the configuration file can contain the keyword value pair:

   CONTEXT_HASH    <# of hash bins>

1. Bound Applications: Set the global unsigned integer ctconbins to a non-zero value before a call to initialize c-tree.

   UINT     ctconbins=12;

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

Return

If an error occurs, OpenISAMContext() returns -1 and isam_err is set; otherwise, OpenISAMContext() returns the context ID. If datno that does not correspond to an open data file, or keyno, (when not -1), does not correspond to an open index file associated with datno, isam_err is set to FMOD_ERR (48). If no IDs are available, or if the ID is already in use, isam_err is set to ECON_ERR (592).

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

Example

FILNO     datno1,datno2;              /* data file numbers   */
pVOID     bufptr1,bufptr2;            /* data buffer pointer */
COUNT     contextID_1,contextID_2,contextID_3,contextID_4; /* context ID's     */

OpenFileWithResource(datno1,"data1",ctSHARED);
OpenFileWithResource(datno2,"data2",ctSHARED);
FirstRecord(datno1 + 1,bufptr1);        /* move to first record for       *
                                         * datano1 using first key        */
contextID_1 = OpenISAMContext(datno1,-1,-1);
                    /* establish first context for datno1 at first record.  *
                     * keyno == -1 saves all key positions.                 */
FirstRecord(datno2 + 3,bufptr2);        /* move to first record for       *
                                         * datano2 using third key.       */
contextID_2 = OpenISAMContext(datno2, datno2 + 3,-1);
                        /* establish first context for datno2 at first record.  *
                         * keyno != -1 saves only key value for third key.      */
NextRecord(datno1 + 1,bufptr1);
NextRecord(datno1 + 1,bufptr1);          /* position datno1 at third       *
                                          * record by first key.           */
contextID_3 = OpenISAMContext(datno1,-1,-1);
       /* Third record by first key becomes the saved position for contextID_1 *
        * and contextID_3 becomes the active context for datno1.               */
NextRecord(datno1 + 2,bufptr1);  /* move from third record by first key,       *
                                  * to the  next record using the second key.  *
                                  * Call this record 4' (4 prime).             */
ChangeISAMContext(contextID_1); /* save record 4' as contextID_3. Make the     *
                                 * 3rd record the current position for datno1, *
                                 * and contextID_1 becomes the active  context *
                                 * for datno1. contextID_2 is still the active *
                                 * context for datno2.                         */
NextRecord(datno1 + 1,bufptr1); /* move to the 4th record by key 1 for datno1.*/
contextID_4 = OpenISAMContext(datno2,datno2 + 3,-1);
         /* saves 1st record by 3rd key as the contents of contextID_2 and     *
          * makes  contextID_4 the active context for datno2. Note that only   *
          * the third key image is stored for contextID_2 and contextID_4.     *
          * Therefore, when  selecting one of these contexts, it will not make *
          * sense to continue  traversing the file with a different key.       */  

See also

CloseISAMContext(), ChangeISAMContext()

OpenISAMXtd

Open all the ISAM files (extended version).

Short Name

OPNISAMX()

Type

Extended ISAM function

Declaration

COUNT OpenISAMXtd(pTEXT filnam, COUNT userprof, pTEXT userid,
                pTEXT userword, pTEXT servname, pTEXT fileword)

Description

OpenISAMXtd() is a variation of OpenISAM() that permits the use of the FairCom Server’s security system. This section expands on the description of OpenISAM().

• userprof is the user profile mask. It accepts the following values:
  • USERPRF_CLRCHK
    • Instructs single-user TRANPROC applications to remove S*.FCS and L*.FCS files upon a successful application shutdown. The c-tree checkpoint code determines at the time of a final checkpoint if there are no pending transactions or file opens, and if this user profile bit has been turned on. If so, the S*.FCS and L*.FCS files are deleted. However, if the application is causing log files to be saved (very unusual for a single-user application), then the files are not cleared. The USERPRF_CLRCHK option is off by default. See Single-User Transaction Processing in the c-tree Programmer’s Reference Guide for additional information.
  • USERPRF_LOCLIB
    • Specifies this instance of c-tree is to be directed to a local database. Applicable only to client/server when using “Local Library Support”.
  • USERPRF_NDATA
    • Enable the manual mode of UNIFRMAT support. Enabling the manual record transformation mode would only be desirable if you are performing your own record level byte flipping or your record structures contain no numeric data (i.e., LONG, FLOAT, . . .). A side benefit of enabling this manual mode is the virtual elimination of Server DODA requests, thereby reducing network traffic by one function call per file open.
  • USERPRF_NTKEY
    • Disables the automatic TransformKey() feature. See the TransformKey() function description for more information.
  • USERPRF_PTHTMP
    • Changes GetCtTempFileName() from its default operation of returning a temporary file name to specifying a directory name where temporary files are to reside.
  • USERPRF_SAVENV
    • Enable the automatic ctSAVENV feature. See the Begin() function description for more information.
  • To use more than one value, OR the values together. Leave userprof set to zero to accept the defaults.
• userid is a pointer to a buffer containing the user ID. If userid is null, the user is assigned the ID of GUEST
• userword is a pointer to a buffer containing the user password.
• servname is a pointer to a Server name if you are going to use a Server name other than the default.
• fileword is an optional file password. If fileword is NULL then there will be no password for this file. If a password is established, every user will need to use the password to be able to open the file.

For more information on user id’s, user passwords, server names, and file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

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

Return

The following error codes may be seen in addition to those for OpenISAM():

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

See also

InitISAM(), CreateISAM(), OpenISAM(), CloseISAM(), TransformKey(), GetCtTempFileName(), Begin()