Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

ctFILELIST

Manage file-specific cache features.

Short Name

ctFILELIST()

Type

Utility Function

Declaration

NINT ctFILELIST(pTEXT filnam, pLONG pvalue, pLONG pmember, pNINT pscale,
NINT list, NINT action);

Description

ctFILELIST() manages the advanced file-specific cache capabilities (limited to standalone and bound server applications prior to V11.8) ctFILELIST() must be called prior to the creation or opening of filnam for the cache capabilities to take effect. If multi-byte file names are supported (e.g., Unicode), the configuration information (or direct call to ctFILELIST()) must have the file names in UTF‑8 form (i.e., a NULL terminated string).

pscale was added in V11.8 as an optional scaling factor. NULL sets scale to zero.

When called in client/server mode,

  1. can only be called by a member of the ADMIN group; and,
  2. limited to operate on the ctKEEPOPENlist type, with supported actions "add entry to list" and "remove entry from list". The add option returns error KDUP_ERR if an entry with the same filename already exists. The remove option only succeeds if the specified file name exactly matches a list entry.

ctclosefile (ctclosefile - Close Files on KEEPOPEN List, Close File Utility) utility was updated for easier KEEPOPEN list file references with this functionality.

The state parameter determines which cache capability is invoked, with pvalue and pmember providing supplemental information, as shown in the table below (which assumes the action ctADDfilelist):

state

Description

ctSPLCACHElist

Assign pvalue bytes of dedicated cache to filnam.

ctPRICACHElist

Loads pvalue bytes from the beginning filnam into cache.

ctNO_CACHElist

Prevents filnam from using cache.

ctPRIINDEXlist

Loads pvalue bytes from the beginning of index member pmember in index file filnam into cache. A negative value for pmember indicates the entire index.

ctNO_FLUSHlist

Sets filnam to not flush cache at file close.

ctKEEPOPENlist

Upon file creation or physical open, (1) if the file name matches a <file spec> and (2) if the file is a data file and (3) if the data file creation/open is part of an ISAM creation or open, then the KEEPOPEN attribute is attached to the data file and its indexes. Not available with standalone models.

ctREPLICATElist

Specifies which file(s) to enable transaction log information for replication. Not available with standalone models.

ctCOMPRESSlist

Forces FairCom DB to create data files whose names match the specified name with data compression enabled.

The action parameter can be used to add a file to a list, check or change the values associated with a file on a list, or to remove a file from a list. Changes made to an open file have no effect until the next time the file is opened.

action

Description

ctADDfilelist

Add a file to the list.

ctSRCfilelist

Return current values for file.

ctCHGfilelist

Change values for listed file.

ctREMfilelist

Remove file from list.

Return

Value

Symbolic Constant

Explanation

0

NO_ERROR

Successful function.

101

INOT_ERR

filnam is not a member of the state list.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

TEXT filnam = "custmast.dat";

LONG bytes = 4000000;

NINT rcN = 0;

COUNT rc2 = 0;


/* Set the file to use 4000000 bytes dedicated cache. */

if (rcN = ctFILELIST(&filnam, &bytes, NULL, ctSPLCACHElist,

ctADDfilelist))

errorReturn(rcN, "Error on SPLCACHE assignment");


/* Set the file to load 4000000 bytes to cache at open. */

if (rcN = ctFILELIST(filnam, &bytes, NULL, ctPRICACHElist,

ctADDfilelist))

errorReturn(rcN, "Error on SPLCACHE assignment"));


/* Open the file and load 4000000 bytes to dedicated cache */

if (rc2 = OpenFileWithResource(-1, &filnam, ctSHARED))

errorReturn(rc2, "Error opening file.");

Limitations

The ctFILELIST() processing, used to store and retrieve cache parameters, ignores the mirrored portion of a file name. Only the primary file is cached.

History

Declaration prior to V11.8

NINT ctFILELIST(pTEXT filnam, pLONG pvalue, pLONG pmember,

NINT state, NINT action)

See also

TOCIndex