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,
- can only be called by a member of the ADMIN group; and,
- 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
- FairCom Server Cache Subsystem (FairCom Server Cache Subsystem, Server cache subsystem)
- ctclosefile