EnableCtResource

Enable Resources in a file created without resources enabled.

Short Name

ENARES()

Type

Low-Level file function

Declaration

COUNT EnableCtResource(FILNO filno) 

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

When creating a file with CreateISAM(), CreateIFile(), CreateIndexFile(), or CreateDataFile(), resources can be disabled for that file using the ctDISABLERES file mode. To later use resources with that file, call EnableCtResource() to enable that feature before calling AddCtResource(), PutIFIL(), or PutDODA().

The file must already be open, and it must be opened with a file lock mode of ctEXCLUSIVE. Otherwise, you will receive an error. filno is the file number for the affected file.

Return

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

Example

pIFIL     ifilptr;

if (OpenIFile(ifilptr))
    printf("\nCannot open file, error %d",isam_err):
else {
    if (EnableCtResource(ifilptr->tfilno))
        printf("\nCannot enable resource,err%d", uerr_cod);
    else (PutIFIL(ifilptr))
        printf("\nCannot add resource,err%d", isam_err);
    CloseFile(ifilptr->tfilno,0);
}

See also

AddCtResource(), CreateISAM(), CreateIFile(), CreateIndexFile(), CreateDataFile(), PutDODA(), PutIFile()

EstimateKeySpan

Find the approximate number of entries between two key values.

Short Name

ESTKEY()

Type

Low-Level index file function

Declaration

LONG EstimateKeySpan(FILNO keyno, pVOID target1, pVOID target2)

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

EstimateKeySpan() finds the approximate number of entries between the two key values pointed to by target1 and target2. EstimateKeySpan() does not traverse the index to compute the values. Instead, it makes about ten calls to KeyAtPercentile() to determine the relative location of the target values. EstimateKeySpan() does not require target1 and target2 to be in ascending order.

EstimateKeySpan() can be used to select among alternate search paths when a retrieval request may be satisfied by more than one index.

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

If EstimateKeySpan() is successful, it returns the approximate number of key value entries located between target1 and target2. If an error occurs or the index is empty, EstimateKeySpan() returns a zero. When EstimateKeySpan() returns zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, the index is empty. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

LONG     retval;
FILNO    keyno;
TEXT     t1[24],t2[24];

scanf("%23s %23s",t1,t2);
if (retval = EstimateKeySpan(keyno,t1,t2))
    printf("\n %ld entries between %.23s and %.23s", retval,t1,t2);
else if (uerr_cod)
    printf("\n error %d occurred",uerr_cod);
else
    printf("\n the index is empty");

Limitations

The number of index entries must be maintained by the index header record, which is the default when FairCom DB is shipped. EstimateKeySpan() should not be used in situations requiring precise results, since it is based on an approximate method.

See also

KeyAtPercentile()

EstimateRange

Find the approximate number of entries between two key values.

Short Name

ESTRNG()

Type

ISAM function

Declaration

LONG ESTRNG(FILNO keyno, NINT segcount, pVOID lrange, pVOID urange, pNINT operators, pLONG segconsec)

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

ALCRNG() is used to define a range request on a specified index. A range request consists of a set of Boolean operators defined for each segment of the key value. ESTRNG(), takes almost the same arguments as ALCRNG(), and returns an estimate of how many key values satisfy the range.

ESTRNG() has an additional argument compared to ALCRNG(), segconsec, which points to a 4-byte integer set to the "number of consecutive segments". lrange and urange must be non-NULL and point to full-length key values. segcount and operators are ignored.

ESTRNG() returns a measure of accuracy of the result in the form of a count of how many of the leading segments have consecutive key values that satisfy the range request. If all the segments have consecutive values that satisfy the range, then the result should be very accurate.

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

If EstimateRange is successful, it returns the approximate number of entries between the two key values. If an error occurs or the index is empty, EstimateRange returns a zero. When EstimateRange returns zero, check isam_err for an error condition, if any.

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

See also

AllocateRange(), FreeRange(), FirstInRange(), FirstInVRange(), LastInRange(), LastInVRange(), NextInRange(), NextInVRange(), PreviousInRange(), PreviousInVRange()

EvaluateFilter

Function prototype for the filter callback function.

Declaration

NINT EvaluateFilter(pCBDLL pcbdll, FILNO datno, pVOID Recptr,
pConvMap Schema, VRLEN fixlen, VRLEN datlen);

Description

This function is defined in the ctuserx.c module used to build a filter callback function.

Where:

• pcbdll is a pointer to a CBDLL structure (see definition below) that contains the callback filter state variables.
• datno is the data file number by which that connection has opened the data file that is being read. 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
• Recptr is the record image of the record for which the filter is being evaluated.
• Schema is the record schema.
• fixlen is the size of the fixed-length portion of the record.
• datlen is the length of the available data. For variable length records it may be smaller than the length entire record if the buffer is smaller than the complete record length.

CBDLL Structure

typedef struct cbdll_t {
NINT cbinst; /* callback instance count */
pTEXT cbdll; /* name of callback DLL */
pTEXT cbfnc; /* name of callback function */
pTEXT cbprm; /* callback function parameters */
pVOID cbdllhnd; /* handle to callback DLL */
pCBFNC cbfncptr; /* pointer to callback function */
pCBFNCload cbload; /* ctfiltercbLoadLib ptr */
pCBFNCunload cbunload; /* ctfiltercbUnloadLib ptr */
pVOID cbfilterhandle; /* user-defined library handle */
TEXT cbfilnam[MAX_NAME]; /* data file name */
} CBDLL;

SetDataFilter() can register a data record filter callback function that resides in a DLL or shared library. Calling SetDataFilter() with a filter expression of the form:

@#mycallback.dll#mycallback_function#my_params

then libname is “mycallback.dll”, funcname is “mycallback_function”, and params is “my_params”.

You can use c-tree API functions to open other c-tree files on that FairCom Server and you can read and write the files. All operations are done in the context of the database connection in which you called the record read operation that called the filter function.

Building a Filter Callback DLL

A simple way to build a data record filter callback DLL is to use the mtmake utility to create a makefile that builds a CTUSER DLL. The CTUSER DLL exports the functions EvaluateFilter(), LoadFilter(), and UnloadFilter(). The source code for these functions is located in the file ctuserx.c.

Additional Callback Functions

In addition to the data record filter callback function, a data record filter callback DLL can optionally implement the following functions. These functions are optional and included for extended capabilities within the callback.

• LoadFilter()
• UnloadFilter()

Errors logged to CTSTATUS.FCS when failing to load a filter callback DLL begin with the text

"FILTER_CALLBACK_LOAD: ".

A callback DLL that is loaded by a call to SETFLTR() is unloaded when the filter is disabled, which is done either by a call to SETFLTR() to establish a different filter (or with an empty string to disable the filter), or when the file it closed.

A callback DLL can also be specified in an expression that is passed to UPDCIDX(). In that case, the DLL is loaded when the file is physically opened, and the DLL remains loaded until the file is physically closed. Note that if the expression passed to UPDCIDX() specifies the name of a filter callback DLL, then every time the data file is opened the DLL must be able to be loaded and the callback function must exist in the DLL. Otherwise the attempt to open the data file will fail with error 867 or 868.

Return Values

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

Example

/* 
Example Code
*/

See also

ctfiltercbAddFilter(), LoadFilter(), ctfiltercbRemoveFilter(), UnloadFilter(), SetDataFilter()