FairCom DB Function Descriptions D-K

delChangeIDfield

Delete the change ID field from the specified data file.

Declaration

ctCONV NINT ctDECL delChangeIDfield (FILNO datno);

Description

[IN] datno- Data file number.

Return Values

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

DeleteCtFile

Delete FairCom DB file.

Short Name

DELFIL()

Type

Low-Level function

Declaration

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

DeleteCtFile() deletes the file opened with file number filno, if and only if the file has been opened in the ctEXCLUSIVE mode. The file is closed by FairCom DB before it is deleted.

Any FairCom DB file may be deleted with DeleteCtFile(), whether it has been opened or created with a Low-Level function, an ISAM parameter file, or with incremental ISAM structures; provided the file has been opened in ctEXCLUSIVE file mode.

Return

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

Example

FILNO        tempno;

if (CreateDataFile(tempno = 5,"temp.dat",1004,0,ctEXCLUSIVE))

{

    printf("\nCould not create temporary file (%d)\n", uerr_cod);

temporary_processing(tempno);

if (DeleteCtFile(tempno)) {

    printf("\nCould not delete temporary file (%d)\n", uerr_cod);

Limitations

DeleteCtFile() first closes the file before deletion. This permits another process to have a small window of opportunity to gain control of the file in which case the delete will fail and result in an error DLTF_ERR (55).

DeleteCtResource

Delete Resource from file.

Short Name

DELRES()

Type

Low-Level file function

Declaration

COUNT DeleteCtResource(FILNO filno, pVOID resptr)

Description

DeleteCtResource() is used to delete a Resource from data file filno. If there is a record lock on this Resource, the lock is automatically freed. Obtain a lock with GetCtResource() using RES_LOCK mode.

resptr points to a Resource Data Block as shown below. This is the same structure as used in the other Resource functions.

Return

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

Example

structure {                   /* Resource Data Block */

   ULONG  resource_type;

   ULONG  resource_number;

   TEXT   resource_name[80];

} my_resource;

my_resource.resource_type    = 0x10001L;    /* 65537 */

my_resource.resource_number  = 100;

if ("DeleteCtResource(datno,&my_resource,) == 0 )

    printf("\nThe resource has been deleted");

else

    printf("\nCould not delete resource. Error #%d", uerr_cod);

Limitations

The resource_name field of the Resource Data Block is ignored.

See also

AddCtResource, UpdateCtResource, GetCtResource

DeleteIFile

Delete ISAM file and associated indexes.

Short Name

DELIFIL()

Type

ISAM function

Declaration

COUNT DeleteIFile(pIFIL ifilptr)

Description

DeleteIFile() deletes the file and indexes referenced by the incremental ISAM structure pointed to by ifilptr if and only if the file and indexes have been opened in exclusive mode.

The file is closed following a successful call to DeleteIFile(). After a successful call to DeleteIFile(), the tfilno member of the IFIL structure is set to -1.

Return

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

Example

pIFIL   ifilptr;

if (OpenIFile(ifilptr)

     printf("\nCould not open data file or index, error = %d,

            file = %d",isam_err,isam_fil);

else if (DeleteIFile(ifilptr)

     printf("\nCould not delete data file or index, error = %d,

            file = %d",isam_err,isam_fil);

Limitations

DeleteIFile() calls the Low-Level DeleteCtFile() function, which first closes the file before deletion.

This permits another process to have a small window of opportunity to gain control of the file in which case the delete will fail and result in an error DLTF_ERR (55).

See also

DeleteRFile, DeleteCtFile

DeleteKey

Delete key value verifying associated data record position.

Short Name

DELCHK()

Type

Low-Level index file function

Declaration

COUNT DeleteKey(FILNO keyno, pVOID target, LONG recbyt)

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

DeleteKey() deletes the key value matching target from index file keyno if such a key value exists and the associated data record position in the index matches recbyt.

Return

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

Example

LONG         recbyt;

FILNO        keyno;

TEXT         target[24];

keyno = 1;

printf("\nEnter key value: ");

scanf("%23s",target);

if (DeleteKey(keyno, target, recbyt))

    printf("\nUnsuccessful deletion (code = %d).",uerr_cod);

else

    printf("\n%s deleted (data record position = %ld).", target,recbyt);

Limitations

The following limitation applies only to the Standalone Multi-user model, FPUTFGET: In order to support simultaneous, multi-user updates with guaranteed deadlock free node locks, FairCom DB does not merge “under flowed” nodes (i.e., nodes which are less than half-full). The B-Tree stays balanced in the essential sense that each key value is the same distance from the root as any other key value, but there is no guarantee that each node is at least half full. However, the deleted space can be re-used by new key values.

This limitation is most serious when the key values are systematically deleted from one end of the key value range and systematically added to the other end of the range. Over time, this will lead to a significant amount of wasted disk space.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

DeleteKeyBlind, ctSETHGH, ctGETHGH

DeleteKeyBlind

Delete key value when associated data record position is not known.

Short Name

DELBLD()

Type

Low-Level index file function

Declaration

LONG DeleteKeyBlind(FILNO keyno, pVOID target)

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

DeleteKeyBlind() deletes the key value pointed to by target from index file keyno, if such a key value exists. DeleteKeyBlind() cannot be used when the index file supports duplicate keys.

Return

If the key value is found in the index, it is deleted and DeleteKeyBlind() returns the associated data record position. If it is not found, or some error is detected, DeleteKeyBlind() returns a zero (which is never a legal data record position), and uerr_cod is set as follows:

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

Example

LONG         recbyt;

FILNO        keyno;

TEXT         target[24];

keyno = 1;

printf("\nEnter key value: ");

scanf("%23s",target);

if (recbyt = DeleteKeyBlind(keyno,target))

    printf("\n%s deleted (data record position = %ld).", target,recbyt);

else

    printf("\nUnsuccessful deletion (code = %d).",uerr_cod);

Limitations

Cannot be used with an index supporting duplicate key values. Without knowledge of the associated data record position, there is no way to distinguish among identical key values.

See also

DeleteKey

DeleteRecord

Delete current fixed-length ISAM record.

Short Name

DELREC()

Type

ISAM fixed-length record function

Declaration

COUNT DeleteRecord(FILNO datno)

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

DeleteRecord() deletes the current fixed-length ISAM record for data file datno. If the data record is successfully deleted, DeleteRecord() updates all associated index files and returns the data record to the pool of available records for data file datno. After the deletion, the current ISAM record information stays unchanged! That is, even though the current record has just been deleted, the information in the current ISAM buffer is not disturbed so that you can scan in either direction through the data via the NextRecord() or PreviousRecord() routines.

In multi-user systems, invoke LockISAM(ctENABLE) before the ISAM routine which reads the record to be deleted. Call LockISAM(ctFREE) after DeleteRecord() to release the locks. See the example below.

DeleteRecord() does not shrink the files. FairCom DB tracks and reuses deleted space before expanding the files. To remove all deleted space, compact the file using CompactIFile().

Return

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

Example

FILNO        invfil, part_no_idx;

LONG         part_key;

struct invd  {

   TEXT      delflg[4];

   LONG      part_no;

   TEXT      part_name[60];

} recbuf;

printf("\nEnter part number to delete: ");

scanf("%ld",&part_key);

if (LockISAM(ctENABLE))

    printf("\nCould not enable locks.");

else if (GetRecord(part_no_idx, &part_key, &recbuf))

    printf("\nCould not get PART #%ld (%d %d).",

           part_key, isam_err, isam_fil);

else if (DeleteRecord(invfil))

    printf("\nCould not delete PART #%ld (%d %d).",

           part_key, isam_err, isam_fil);

LockISAM(ctFREE);

Limitations

DeleteRecord() causes the first byte of the data record to be set to FF (hex) as a delete flag. This flag is tested by all ISAM functions which read a data record. If the first byte is equal to FF (hex), an IRED_ERR (114) error is returned. The delete flag is also used by the rebuild utility to determine if a record is deleted. When you define your data record structure, the most straightforward approach is to reserve the first byte of the data record for the delete flag. You may store data in the first byte as long as the data will never be equal to FF (hex).

Fixed-length data files with RESOURCES enabled use the first byte to indicate the presence of a resource record. A byte value of FE (hex) at the beginning of the record indicates a resource record.

See also

DeleteVRecord(), NextRecord, PreviousRecord, CompactIFile, LockISAM and Fixed Length Data Record Delete Flag.

DeleteRFile

Delete ISAM file and associated indexes.

Short Name

DELRFIL()

Type

ISAM function

Declaration

COUNT DeleteRFile(FILNO datno)

Description

DeleteRFile() deletes the file and indexes referenced by the ISAM data file with file number datno, if and only if the file and indexes have been opened in exclusive mode.

Return

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

Example

FILNO    datno = 5;

TEXT     filnam[15];

printf("\nEnter file name to delete:")

scanf("%14s", filnam);

if (OpenFileWithResource(datno, filnam, ctEXCLUSIVE))

     printf("\nCould not open data file or index, error = %d,

            file = %d",isam_err,isam_fil);

else if (DeleteRFile(datno))

     printf("\nCould not delete data file or index, error = %d,

            file = %d",isam_err,isam_fil);

Limitations

DeleteRFile() calls the Low-Level DeleteCtFile() function, which first closes the file before deletion.

In a non-server model, this permits another process to have a small window of opportunity to gain control of the file in which case the delete will fail and result in an error DLTF_ERR (55).

See also

DeleteIFile which deletes files based on incremental ISAM structures and DeleteCtFile

DeleteVRecord

Delete current variable-length ISAM record.

Short Name

DELVREC()

Type

ISAM variable-length record function

Declaration

COUNT DeleteVRecord(FILNO datno)

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

DeleteVRecord() deletes the current variable-length ISAM record for data file datno. If the data record is successfully deleted, DeleteVRecord() updates all associated index files and returns the data record to the pool of available records for data file datno. After the deletion, the current ISAM record information stays unchanged! That is, even though the current record has just been deleted, the information in the current ISAM buffer is not disturbed so that you can scan in either direction through the data via the NextRecord() or PreviousRecord() routines. If key values reside in the variable-length portion of the record, the entire record must be retrieved, usually with ReReadVRecord().

In multi-user systems, invoke LockISAM(ctENABLE) before the ISAM routine which reads the record to be deleted. Delete frees Low-Level locks, but LockISAM(ctFREE) should be called after DeleteVRecord() to clear the LockISAM() state. See the example below.

DeleteVRecord() does not shrink the files. FairCom DB tracks and reuses deleted space before expanding the files. To remove all deleted space, compact the file using CompactIFile().

Return

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

Example

FILNO        invfil, part_no_idx;

LONG         part_key, plen;

struct invd  {

   LONG      part_no;

   TEXT      part_name[120];

} recbuf;

plen = sizeof(recbuf);

printf("\nEnter part number to delete: ");

scanf("%ld",&part_key);

if (LockISAM(ctENABLE)

    printf("\nError enabling locks = %d",isam_err);

else if GetVRecord(part_no_idx, &part_key, &recbuf, plen)

    printf("\nError on GetRecord = %d",isam_err);

else if DeleteVRecord(invfil))

    printf("\nCould not delete PART #%ld (%d %d).",

           part_key, isam_err, isam_fil);

}

LockISAM(ctFREE);

See also

DeleteRecord, NextRecord, PreviousRecord, ReReadVRecord, LockISAM,
CompactIFile

DELFILX

Delete FairCom DB file to the recycle bin.

Type

Low-Level function

Declaration

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

DELFILX() deletes the file opened with file number filno to a recycle bin, if and only if the file has been opened in the ctEXCLUSIVE mode. The file is closed by FairCom DB before it is deleted.

optionBits bit field values:

typedef enum ctDeleteFileOptionsBits_t { 

  ctDELETE_TO_RECYCLE_BIN = 0x00000001 /* move files to recycle bin instead of deleting */ 

} ctDELETE_FILE_OPTIONS_BITS; 

typedef struct ctDeleteFileOptions_t {

  UCOUNT structVersion; /* [IN] version of this structure */

  UCOUNT pad; /* unused padding */

  ULONG optionBits; /* [IN] option bits */

 } ctDELETE_FILE_XTD_OPTIONS, *pctDELETE_FILE_XTD_OPTIONS;

Any FairCom DB file may be deleted with DELFILX(), whether it has been opened or created with a Low-Level function, an ISAM parameter file, or with incremental ISAM structures; provided the file has been opened in ctEXCLUSIVE file mode.

Return

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

Example

FILNO        tempno;

if (CreateDataFile(tempno = 5,"temp.dat",1004,0,ctEXCLUSIVE))

{

    printf("\nCould not create temporary file (%d)\n", uerr_cod);

temporary_processing(tempno);

if (DELFILX(tempno)) {

    printf("\nCould not delete temporary file (%d)\n", uerr_cod);

Limitations

DELFILX() first closes the file before deletion. This permits another process to have a small window of opportunity to gain control of the file in which case the delete will fail and result in an error DLTF_ERR (55).

See also

DeleteCtFile, DeleteIFile, DeleteRFile, DELIFILX, and DELRFILX

delIDfield

Removes the IDENTITY attribute from a DODA field

Declaration

  delIDfield(FILNO datno)

Type

ISAM function

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

delIDfield() removes an IDfield (IDENTITY) auto-numbering attribute from a numeric field in a record.

Where:

• datno is the data file number

IDfield requires a DAR resource (Direct Access Resource) embedded in the file. The DAR is a specialized high-speed resource.

Return

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

Example

retval = delIDfield(fileno);

if (retval) {

printf("\tERROR: Failed to remove ID field with error %d\n", retval);

}

Override IDENTITY Values

PUTHDR() using the ctIDfieldOverRide mode can turn on and off the ability to override the automatic IDfield values. The override is on a per user, per file basis. A nonzero hdrval turns on the override, and a zero hdrval restores the standard operation. When the override is on for a data file that supports an IDfield, then an add record operation does not fill-in the IDfield value. Whatever is passed in the record buffer is used for the IDfield. And a rewrite permits the IDfield value to change instead of generating the IDFL_CHG error. When the override is enabled, add record operations do not consume IDfield values.

See also

addIDfield, getIDfield, wchIDfield, resetIDfield, IDfields - Extended support

DELIFILX

Delete ISAM file and associated indexes to the recycle bin.

Type

ISAM function

Declaration

COUNT DELIFILX(pIFIL ifilptr)

Description

DELIFILX() deletes the file and indexes referenced by the incremental ISAM structure pointed to by ifilptr to a recycle bin, if and only if the file and indexes have been opened in exclusive mode.

The file is closed following a successful call to DELIFILX(). After a successful call to DELIFILX(), the tfilno member of the IFIL structure is set to -1.

Return

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

Example

pIFIL   ifilptr;

if (OpenIFile(ifilptr)

     printf("\nCould not open data file or index, error = %d,

            file = %d",isam_err,isam_fil);

else if (DELIFILX(ifilptr)

     printf("\nCould not delete data file or index, error = %d,

            file = %d",isam_err,isam_fil);

Limitations

DELIFILX() calls the Low-Level DELFILX() function, which first closes the file before deletion.

This permits another process to have a small window of opportunity to gain control of the file in which case the delete will fail and result in an error DLTF_ERR (55).

See also

DeleteRFile, DeleteCtFile, DeleteIFile, DELFILX, and DELRFILX

DELRFILX

Delete ISAM file and associated indexes to the recycle bin.

Type

ISAM function

Declaration

COUNT DELRFILX(FILNO datno)

Description

DELRFILX() deletes the file and indexes referenced by the ISAM data file with file number datno to the recycle bin, if and only if the file and indexes have been opened in exclusive mode.

Return

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

Example

FILNO    datno = 5;

TEXT     filnam[15];

printf("\nEnter file name to delete:")

scanf("%14s", filnam);

if (OpenFileWithResource(datno, filnam, ctEXCLUSIVE))

     printf("\nCould not open data file or index, error = %d,

            file = %d",isam_err,isam_fil);

else if (DELRFILX(datno))

     printf("\nCould not delete data file or index, error = %d,

            file = %d",isam_err,isam_fil);

Limitations

DELRFILX() calls the Low-Level DELFILX() function, which first closes the file before deletion.

In a non-server model, this permits another process to have a small window of opportunity to gain control of the file in which case the delete will fail and result in an error DLTF_ERR (55).

See also

DeleteIFile which deletes files based on incremental ISAM structures, DeleteCtFile, DeleteRFile, DELFILX, and DELIFILX

DoBatch

Perform operations on one or more groups of records.

Short Name

BATSET()

Type

ISAM function.

Declaration

COUNT DoBatch(FILNO filno, pVOID request, pVOID bufptr,

              VRLEN bufsiz, UCOUNT mode)

Parameters:

• filno - Specifies the index file used to retrieve the related records.
• bufptr - A pointer to a region into which the group of related records will be retrieved, if specified.
• mode - Specifies the type of action to be taken.
• request - points to a Partial Key Request (PKEYREQ) structure defining the set of records to be acted on. This is defined as:

typedef struct pkeyreq {

    LONG  btotal;                /* total entries in set     */

    LONG  bavail;                /* # of entries locked      */

    LONG  breturn;               /* # of objects in buffer   */

    COUNT siglen;                /* significant length       */

    TEXT  target[MAXLEN];        /* partial key target       */

    }  PKEYREQ;

Unless otherwise specified, the only fields that must be initialized are target and siglen. target contains the portion of a properly formed key to match. siglen specifies the number of bytes of target considered significant. All keys in the appropriate index matching the first siglen bytes of target will be processed. Some modes require a modified request format.

Description

DoBatch() attempts to perform a specified function on a group of records with keys matching a partial key value. By using ChangeBatch, more than one batch can be active at a time.

In the first call to DoBatch(), specify the action to be taken with the mode of BAT_GET or BAT_DEL. When processing more records than fit in the buffer pointed to by bufptr, retrieve the rest with additional calls to DoBatch() with a mode of BAT_NXT.

When finished with a batch, if not all records have been processed through DoBatch() calls, call DoBatch() with a mode of BAT_CAN. This closes the batch, frees all locks, and allows another batch. A call to DoBatch() that processes all the records that remain in the batch automatically closes the batch, so there is no need to call DoBatch() again with a mode of BAT_CAN in that case. To check if a call to DoBatch() has closed the batch, check the value of sysiocod. After a call to DoBatch() that closes the batch, sysiocod will have the value BTNO_COD.

A call to DoBatch() with mode BAT_CAN fails with error BTNO_ERR (426) if the batch has been closed. That error can be ignored. Note that if the batch is not closed, BTIP_ERR (425) or BTST_ERR (427) error may occur when attempting to open the next batch.

After the DoBatch() call, check the values in the PKEYREQ structure for the results. btotal reports how many records match the partial key target. If locks on the records were requested, bavail tells how many of the records were locked. breturn specifies the number of records or record positions passed back in the buffer region.

If neither BAT_RET_REC nor BAT_RET_POS was specified, DoBatch() does not return any values to the buffer at bufptr. The values in the PKEYREQ structure are updated. If BAT_RET_POS is specified, the buffer region contains an array of 4-byte integers, each specifying the byte position of a record in the partial key set. If BAT_RET_REC is specified, the buffer region contains a series of entries comprised of the 4-byte record position followed by the actual record. If the file contains variable-length records, the 4-byte record position is followed by a 4-byte record length and the variable-length record.

Note: When using HUGE Files, BAT_RET_REC mode returns an 8-byte record offset preceding the record body for each record returned in the batch buffer. For non-Huge Files, a 4-byte record offset is returned instead.

When mode includes BAT_GKEY the number of matches is not readily available. To signify there are more records to process, bavail is set to one greater than return.

The values that can be used for the mode parameter are:

Table 1: DoBatch - Initial Mode

Table 2: DoBatch - Modifiers to Initial Mode

Table 3: DoBatch - Continuing Mode

Table 4: DoBatch - Finishing Mode

Return

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

Example 1

FILNO    keyfil;

PKEYREQ  batsamp;           /* Partial Key Request structure */

TEXT     recbuf[1024];                 /* buffer for records */

batsamp.siglen = 4;             /* first 4 bytes significant */

sprintf(batsamp.target,"DISK");         /* partial key value */

if (DoBatch(keyfil,&batsamp,recbuf,1024,

         BAT_GET | BAT_RET_REC | BAT_COMPLETE | BAT_LOK_WRT)) {

    printf("\nBatch error %d",isam_err);

    return;

}

printf("\n%ld entries match",batsamp.btotal);

process_batch();                        /* process the batch */

DoBatch(keyfil,NULL,NULL,0L,BAT_CAN);     /* close the batch */

Example 2

To delete a list of key values passed to the function, use the BAT_DEL | BAT_KEYS mode. Set the batch request buffer (the second DoBatch parameter) to the following values in the order listed below:

1. A 4-byte integer indicating the number of key values you are passing to the function.
2. A 4-byte integer set to zero.
3. A 4-byte integer set to zero.
4. The key values (full key length number of bytes for each value). If the index allows duplicates, also include the 4- or 8- byte record offset in high/low (most significant byte first) order.

See also

• Please refer to Batched Operations (Batched Operations, Batches) for a detailed explanation of batch operations.
• See ChangeBatch for information about using multiple batches.
• DoBatchXtd.
• Treat fixed-length compressed data files consistently across batch record returns, inserts, and updates

Treat fixed-length compressed data files consistently across batch record returns, inserts, and updates

Prior to FairCom DB V10.3, a fixed-length data file that had record compression turned on was implemented internally as a variable-length file with the ctAugmentedFxd file attribute. The ctAugmentedFxd attribute enforced the constraint that all the records are of the specified fixed length. After compression, the records may be of different lengths. To determine if your file is behaving in this manner, you can execute the ctinfo utility over the data file and look for the presence of the ctAugmentedFxd file mode in the c-tree extended header block.

ctBEHAV_BAT_FXDCMP changes the behavior of the batch retrieval and insertion code so that compressed, fixed-length data file records are now treated as fixed-length records, not variable-length. This new behavior is consistent with other c-tree API calls and the BAT_UPD option. ctBEHAV_BAT_FXDCMP is on by default, but COMPATIBILITY NO_BAT_FXDCMP placed in the ctsrvr.cfg file will turn off the new behavior at runtime.

The new behavior affects BAT_RET_REC and BAT_RET_BLK retrieval operations by removing the record size field that precedes each record image.

BAT_RET_FIX is mutually exclusive with BAT_RET_REC, and designed to be used with variable-length files, and not used in conjunction with BAT_RET_BLK.

Before the new behavior, BAT_RET_FIX would have resulted in compressed, fixed-length data file records being returned like variable-length records. Now they will be returned like fixed-length records.

The new behavior affects the BAT_INS option by expecting the input buffer to be in fixed-record length format for compressed fixed-length data file records.

DoBatchXtd

Perform operations on one or more groups of records (extended version).

Short Name

BATSETX()

Type

ISAM function

Declaration

COUNT ctDECL DoBatchXtd(FILNO keyno, pVOID request, pVOID bufptr, VRLEN bufsiz, ULONG mode);

Description

The DoBatchXtd() function expands batch processing functionality. It supports the same parameters as the DoBatch function, however, the mode parameter is of type ULONG instead of UCOUNT. With this function, the following additional capabilities are defined for the mode parameter:

• BAT_LKEY - Batch read in key decreasing order
• BAT_LOK_ONE - Only locks the record during the record read. In V12 and later, BAT_LOK_ONE is active when BAT_PHYS and/or BAT_RET_REC or BAT_RET_FIX are part of the batch request mode. Other retrieval strategies, such as BAT_RET_POS, cannot be used with BAT_LOK_ONE (the batch request will fail with BTRQ_ERR, 430).
• BAT_LOK_BLK - Converts BAT_LOK_RED and BAT_LOK_WRT to blocking read and write locks, respectively
• BAT_PHYS - Batch read in physical order (e.g., read records in the physical order stored within the data file). This mode does not require an index.
• BAT_RET_BLK - Return a contiguous block of records
• BAT_RET_RAW - Turns off the conversion of record images, key values, and record positions returned by a batch retrieval call
• BAT_RNGE - Batch read under control of range definition from ALCRNG()
• BAT_INS - Batch record insertion into the target file. See Batch Record Insertion.
• BAT_INP_RAW - Turns off the conversion of record images, key values, and record positions passed to a batch function
• BAT_CLSE - When a BAT_PKEY, BAT_RNGE, BAT_GKEY, BAT_LKEY or BAT_PHYS request exhausts all the entries, either in the first call to BATSETX() or in subsequent calls, the batch will be closed immediately, and sysiocod will be set to BTNO_COD
• BAT_UPD - The batch update call sends a series of record images and the filno parameter corresponds to a unique key index. See Batch Update Operations.
• BAT_UPD_KEY - The record images are preceded by the key value that uniquely identifies the record to be rewritten or added. See Batch Update Operations.
• BAT_EXTENSIONS - Use batch extended capabilities. It is available only for BAT_GET requests. If used, it must be the value of mode. Additional “modes” can be defined in the PKEYREQ2 as required.
• BAT_UPD_KEPSRL: The batch update call preserves the original record serial number.
• BAT_BTBZ_ERR - On BTBZ_ERR return the minimum buffer size in the bavail member of PKEYREQ.
• BAT_REVERSE - The batch retrieval call returns results in reverse order.
• BAT_AUGFIX - Do not specify record length in the batch buffer for variable length files having the ctAugmentedFixed mode active since all records have the same fixed size.
• BAT_PKEY_INCREMENTAL - Use with the BAT_PKEY mode to perform an incremental retrieval like BAT_GKEY does: only those records that fit into the output buffer are read on the first BATSETX() call, and bavail is set to 1 more than breturn if there are additional records to retrieve.
• BAT_RNGE_INCREMENTAL - Use with the BAT_RNGE mode to perform an incremental retrieval like BAT_GKEY does: only those records that fit into the output buffer are read on the first BATSETX() call, and bavail is set to 1 more than breturn if there are additional records to retrieve.

Before calling DoBatchXtd() with a request value of BAT_RNGE, a call must be made to ALCRNG() to establish the range criteria. After this, calls to DoBatchXtd() behave just as they would for BAT_PKEY except that the records selected satisfy the range criteria established by the call to ALCRNG(). The siglen and target members of the PKEYREQ structure are ignored by the BAT_RNGE option.

Calls to DoBatchXtd() with BAT_PHYS use a request block comprised of 5 LONG integers. The first three are the standard btotal, bavail and breturn from the PKEYREQ structure. The last two are the high-order and low-order 4-byte record positions. For the first call to DoBatchXtd(), these last two LONG integers specify the starting position for the physical retrieval. On return from the first and subsequent calls to DoBatchXtd(), these last two LONG integers specify the next record location (i.e., the physical record position following the last record included in the output buffer).

Note: This next record position is returned for informational purposes. It is not used on a subsequent call (BAT_NXT) to retrieve additional records. The starting point for the next batch is maintained internally within the batch structure.

BAT_LOK_ONE only holds a record lock while the record is read. The behavior of BAT_LOK_ONE is not explicitly controlled by BAT_PHYS but rather implicitly upon the batch strategy requested. BAT_LOK_ONE is active when BAT_PHYS and/or BAT_RET_REC or BAT_RET_FIX are part of the batch request mode. Other retrieval strategies such as BAT_RET_POS cannot be used with BAT_LOK_ONE, and the batch request will fail with FairCom DB error BTRQ_ERR (430), request is a NULL pointer.

BAT_RET_BLK can only be used with a retrieval request using BAT_PHYS or with BAT_INS. When used with retrieval, the records are returned as a contiguous block, as if they had been cut out of the data file. Fixed length records run uninterrupted, and each variable-length record is preceded by a 10-byte record header.

Calls to DoBatchXtd() with BAT_EXTENSIONS can be used to perform record filtering, column filtering, range operation, partial key requests and other features without preliminary calls that may require client/server interaction. It also resets any filters and ranges once the batch is closed. It uses a request block in the form of a PKEYREQ2 structure which has the following members:

Available batchmode2:

• BAT_EXT_CHANGEBAT - on first call bavail member of the pKEYREQ2 request contains the batch number for automatic changebatch. This support added in V12.6 prevents an additional call to the Server to obtain the batch number when used with the following functions:
  • ctdbSetBatchFilter
  • ctdbSetBatchRangeOn
  • ctdbAddToFieldMask
• BAT_EXT_FLTR_OUT - return the number of records filtered out by record filter in the first 4 bytes of the batch buffer. The returned value is the number of records filtered out in composing the batch buffer returned with the current call.

The parameters for a BAT_INS call are treated differently than for other DoBatchXtd() calls. The request parameter points to an array of 5 LONG integers (just as in a call to retrieve records using BAT_RET_BLK) and BAT_INS assumes that these five LONGs are immediately followed by a buffer containing the records to be inserted, where bufsiz specifies the size of this additional buffer in bytes. Ordinarily, bufsiz specifies the size of the output buffer pointed to by bufptr. bufptr is ignored in calls for BAT_INS. Also, only the 3rd of the 5 LONG integers (breturn) is used on input: it specifies the number of records in the buffer following the 5 LONG integers. On return from a BAT_INS call, only the DoBatchXtd() return value is significant.

Exactly one of BAT_RET_REC or BAT_RET_BLK must be OR-ed with BAT_INS to specify how the records are organized. Presumably, one would use BAT_RET_BLK if the records were retrieved using BAT_RET_BLK, and BAT_RET_REC if they were retrieved with BAT_RET_REC. When BAT_RET_REC is in use, each record is preceded by its 4 or 8-byte record location (that is ignored by BAT_INS) and then its (4-byte) length.

For transaction controlled files, the batch insertion operation is treated as all-or-nothing operation. If no explicit transaction is started, each BAT_INS call with start and end its own transaction.

Note: Even if an explicit transaction is started, each call to BAT_INS is treated independently through save points. One failed BAT_INS call does not invalidate prior or subsequent BAT_INS calls.

BATSETX Handling of Undersized Buffer Improved in V11

Calls to BATSETX did not return expected results with a small buffer. In some cases an application that used a buffer too small to hold the first record to be returned would not have an error indication. Logic has been modified to correct this situation.

Note: It is not unusual for a buffer to be too small to hold all the records being requested by the batch. However, when the first record does not fit, no record will be returned and no progress will be made on the batch request. Another call to BATSETX will need to be made with a larger buffer.

In V11 and later, a new mechanism has been provided to return the buffer size required to avoid the BTBZ_ERR. This new behavior only occurs if the BATSETX call that failed with BTBZ_ERR has BAT_BTBZ_ERR OR-ed into the BATSETX mode parameter. For example, the following BATSETX call would behave as usual if no BTBZ_ERR was returned, but the second LONG integer return value (request[1]) would have the minimum buffer size requirement for the subsequent BATSETX call to succeed (instead of bavail):

LONG request[5] = {0};

pVOID buffer[8192];

NINT rc;

rc = BATSETX(datno,request,buffer,8192,BAT_GET | BAT_PHYS |

BAT_RET_REC | BAT_BTBZ_ERR);

Return

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

Example Use of DoBatchXtd()

The following pseudo-code shows a strategy for using DoBatchXtd retrievals from one file to load into another file with the same record format.

ULONG     batmode;

LONG      irq[8192];

pPKEYREQ  pirq = (pPKEYREQ) irq;

COUNT     retval;

CHGBAT(0);

batmode= BAT_GET | BAT_PHYS | BAT_RET_BLK | BAT_LOK_RED |

         BAT_LOK_BLK | BAT_LOK_ONE;

/*

** start batch retrieval at current ISAM position. [Can start at any

** legitimate record offset.]

*/

irq[4] = GETCURP(src_datno);/* low order word  */

irq[3] = ctGETHGH();/* high order word */

/*

** first batch [0] retrieval

*/

retval = BATSETX(src_datno,pirq,irq+5,

            (VRLEN) sizeof(irq) - 5 * sizeof(LONG),batmode);

/*

** prepare batmode for subsequent retrievals

*/

batmode &= ~BAT_GET;

batmode |=  BAT_NXT;

TRANBEG(ctTRANLOG);

do {

        printf("\nstatus=%d tot=%ld avl=%ld ret=%ld nxthw=%lx nxtlw=%lx",

            retval,irq[0],irq[1],irq[2],irq[3],irq[4]);

        }

        if (retval)

                break;

        /*

        ** switch to batch [1] for insertion

        */

        CHGBAT(1);

        if (BATSETX(dest_datno,pirq,0x1,

            sizeof(irq) - 5 * sizeof(LONG),

            BAT_INS | (batmode & (BAT_RET_REC | BAT_RET_BLK))))

        {

                printf("\nBATSETX BAT_INS: %d\n",isam_err);

                break;

        } else

                printf("\nBATSETX BAT_INS: success");

        CHGBAT(0);

        retval = BATSETX(src_datno,pirq,irq + 5,

                  (VRLEN) sizeof(irq) - 5 * sizeof(LONG),

                  BAT_NXT /*batmode*/);

} while (1);

TRANEND(ctFREE);

CHGBAT(0);

BATSETX(src_datno,NULL,NULL,0,BAT_CAN);

CHGBAT(1);

BATSETX(dest_datno,NULL,NULL,0,BAT_CAN);

See also:

• Please refer to Batched Operations (Batched Operations, Batches) for a detailed explanation of batch operations.
• See ChangeBatch for information about using multiple batches.
• See also DoBatch.

DropIndex

Permanent Incremental Index deletion.

Short Name

ctDROPIDX()

Type

ISAM Function

Declaration

COUNT DropIndex(FILNO keyno)

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

DropIndex() permanently removes the index file referenced by keyno, which must be associated with a host index, not a member index. All the indexes contained in the index file are dropped and the IFIL resource in the data file is updated.

If the keyno index is transaction dependent, TRANDEP, DropIndex() must be performed under transaction control and can be undone by an abort or save point restore, but they are marked so that no ISAM update will touch these indexes.

Note: The key numbers associated with the data file may have a gap until the files are closed and reopened. For example, if a data file has key numbers 3, 4, 5, 6, 7, and 8 associated, and key 5 is its own file with one member, then after DropIndex(5) completes the key numbers associated with the data file will be: 3, 4, 7, and 8. After the data file is closed and reopened (at the ISAM level), the key numbers will be consecutive again: 3, 4, 5, and 6.

DropIndex() marks a transaction-controlled index for deletion by setting keylen to -keylen until the drop is committed. A GetIFile() call after the DropIndex() call, but before the Commit() or Abort() will return this interim setting.

Return

Limitations

DropIndex() cannot be called for indexes created by TempIIndexXtd() or for member indexes. Specify a permanent host index to be dropped.

Both PermIIndex() and DropIndex() are only undoable if they are performed on TRANDEP files.

If there are pending DropIndex() calls, then no calls can be made to UpdateConditionalIndex() for any of the indexes associated with the underlying data file.

See also

PermIIndex, GetIFile, Commit, Abort, TempIIndexXtd, UpdateConditionalIndex

dyndmp and dyndumpsetopt

The Dynamic Dump can send a script to the server and receive a dump stream and/or status messages from the server. The following capabilities are available for scripting a dynamic dump:

1. When scheduling a dynamic dump, the client can send the dump script to the server.
2. When running a dynamic dump, the client can request that status messages be sent to it while the dump is performed and/or the dump stream file can also be sent to the client process.

To use these options, call the function dyndmpsetopt() before calling dyndmp():

extern NINT dyndmpsetopt(NINT option,pVOID value);
 

The following are the supported options. All options are disabled by default.

• DDOPT_SENDSCRIPT - Send dump script to server. Set value to the script name, or set it to NULL to disable this option. Example:

dyndmpsetopt(DDOPT_SENDSCRIPT, "script.txt");

• DDOPT_RECVSTREAM - Receive dump stream from server. Set value to YES to enable this option or NO to disable this option. Example:

dyndmpsetopt(DDOPT_RECVSTREAM, (pVOID) YES);

• DDOPT_RECVSTATUS - Receive status messages from server. Set value to YES to enable this option or NO to disable this option. Example:

dyndmpsetopt(DDOPT_RECVSTATUS, (pVOID) YES);

• DDOPT_SETCALLBK - Set callback function. Set value to the callback function pointer, or set it to NULL to disable the use of the callback function. Example:

extern ctCONV NINT mycallback(pVOID pctx,pVOID pdata,NINT datalen,NINT opcode);

dyndmpsetopt(DDOPT_SETCALLBK , &mycallback);

• DDOPT_SETCONTEXT - Set callback function context pointer. Set value to the context pointer that will be passed to the callback function. Example:

mystruct mycontext;

dyndmpsetopt(DDOPT_SETCONTEXT, &mycontext);

• DDOPT_SETBUFSIZ - Set communication buffer size. Set value to the buffer size to use. Example:

dyndmpsetopt(DDOPT_SETBUFSIZ, (pVOID) 100000);

Notes:

1) The dump options remain in effect for all dynamic dumps performed by the current connection until they are changed.

2) When the DDOPT_RECVSTREAM or DDOPT_RECVSTATUS options are used, the following dynamic dump script options are ignored:

COPY_NONCTREE - Non-ctree files cannot be copied.

DATE and TIME - No scheduling of dump for later time.

EXT_SIZE - Only one dump extent is created.

FREQ - No repeat of dump.

SEGMENT - No segmenting of dump stream.

The ctdump utility supports these features through command-line options:

usage: ctdump  [-s svn] [-u uid] [-p upw] [-t script] [-b bufsiz] [-n] [-c] [-o backup]

Options:

• -s svn - c-tree Server name
• -u uid - User name
• -p upw - User password
• -t - Dump script name
• -b bufsiz - Use buffer size of bufsiz bytes
• -c - Send dump script from client
• -m - Minimize progress notifications
• -n - Send progress notifications to the client
• -o backup_filename - Write dump stream from server to file on client

Example:

# ctdump -u ADMIN -p ADMIN -o backup.fcd -c -t script.txt -s FAIRCOMS -n

Results:

c-tree(tm) Version 11.1.0.46197(Build-150826) Dynamic Backup Utility

Copyright (C) 1992 - 2015 FairCom Corporation

ALL RIGHTS RESERVED.

Reading dump stream from server with buffer size of 100000

 Start dump. Estimated dump size:      2691072

FAIRCOM.FCS

 86% 100% [     2328576 of      2326528 bytes]

SYSLOGDT.FCS

 89% 100% [       86016 of        81920 bytes]

SYSLOGIX.FCS

 99% 100% [      266240 of       262144 bytes]

S0000000.FCS

100% 100% [        4096 of          128 bytes]

S0000001.FCS

100% 100% [        4096 of          128 bytes]

L0000001.FCS

100% 100% [        2048 of          679 bytes]

   End dump.    Actual dump size:      2705408

Dynamic Dump has been successfully written to the file backup.fcd.

See Also:

• Dynamic Dump Script File

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

FindFileByName

Finds a file in the file system given a name.

Declaration

NINT ctDECL FindFileByName(pTEXT infilnam,NINT opcode,pTEXT outfilnam,pVRLEN poutfillen);

Short Name

ctFILWCD()

Description

This function allows file searches using the wildcard characters ‘?’ and ‘*’. The ‘?’ identifies a single character wildcard position while a ‘*’ specifies any number of characters.

• infilnam is the wildcard filename
• opcode is one of the following:

• outfilnam is the buffer to hold the found filename
• poutfillen points to the output buffer size

Note: The wildcard logic finds all files matching the wildcard specification — there is no check that the file is a c-tree data or index file. The wildcard logic also finds memory files whose names match the specified filename.

Note: If an error occurs during a search, the search should be closed and restarted.

Result

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

Example pseudocode

#define MAX_SIZE 1024 /* 1K buffer size */

...

int ListLength = MAX_SIZE

pText pFilelist;

pFileList = (pText) malloc (sizeOf(pText) * MAX_SIZE);

...

memset(pFileList, 0, MAX_SIZE);

if ((rc = ctFILWCD ("jrnl*.dat", ctFILWDfindfirst, pFilelist, ListLength)) != 0 ) {

printf("ctFILWCD did not execute successfully (%d).\n, rc");

}

...

Limitations

ctFILWCD() does not translate path separators between client and server and does not provide a way to re-read the name of a file if the specified buffer is too small to hold the entire filename.

FirstInRange

Read the first data record in a range

Short Name

FRSRNG()

Type

ISAM function

Declaration

COUNT FirstInRange(FILNO keyno, pVOID recptr); 

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

Read the first data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful FirstInRange() defines a current key value set, and subsequent calls to NextInRange() or PreviousInRange() will read the other records in the range.

If the data file has variable-length records, only the fixed-length portion of the record is actually read. You can use ReReadVRecord() to retrieve the whole record, including the variable-length portion. You can use FirstInVRange() to read the whole variable-length record with one function call.

Return

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

See also

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

FirstInSet

Read the first data record in the set defined by target.

Short Name

FRSSET()

Type

ISAM function

Declaration

COUNT FirstInSet(FILNO keyno, pVOID target, pVOID recptr, COUNT siglen)

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

FirstInSet() reads the first data record in the set of data records whose keys match the target key in the first siglen bytes. If successful, this record becomes the current ISAM record for the associated data file. A successful FirstInSet() defines a current key value set, and subsequent calls to NextInSet() and PreviousInSet() will read the other records in the set (i.e., those records whose keys also match the first siglen bytes of target). If an error occurs or no key value matches the target, the current ISAM record is not updated, and no key value set is defined.

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to FirstInSet(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

• In a 'bound' model (either standalone or if using the server DLL in your process), the TFRMKEY() call operates on the buffer that you pass to FirstInSet(), so the target buffer must be initialized to the full length of the key to avoid memory corruption when the target is transformed to match the key.
• In client/server mode the FairCom Server will perform the TFRMKEY on the Server side using a buffer sized for the key value.

FirstInSet() can be used to perform an equality search for duplicate keys. Set target to the key value and siglen to the key length less the 4 bytes of the suffix.

You do not directly identify the data file number involved. The ISAM parameter file described in ISAM Functions contains the correspondence between the index file number and the associated data file.

Return

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

Example

FILNo        keyfil;

TEXT         target[24],recbuf[320];

printf("\nEnter set value:");

scanf("%23s",target);

FirstInSet(keyfil,target,recbuf,strlen(target));

while (isam_err == NO_ERROR) {

   process_data();

   NextInSet(keyfil,recbuf);

}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

NextInSet(), PreviousInSet(), LastInSet(), CreateIFile(), ReReadVRecord(), PositionSet(), ChangeSet(), TransformKey()

FirstInVRange

Read the first data record in a range.

Short Name

FRSVRNG()

Type

ISAM function

Declaration

COUNT FirstInVRange(FILNO keyno, pVOID recptr, pVRLEN plen); 

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

Read the first data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful FirstInVRange() defines a current key value set, and subsequent calls to NextInVRange() or PreviousInVRange() will read the other records in the range.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Return

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

See also

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

FirstInVSet

Read the first variable-length data record in the set defined by target.

Short Name

FRSVSET()

Type

ISAM function

Declaration

COUNT FirstInVSet(FILNO keyno, pVOID target, pVOID recptr,

                  COUNT siglen, pVRLEN plen)

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

FirstInVSet() is identical to it’s fixed-length counterpart, FirstInSet(), except that it reads the first variable-length data record in the set of data records whose keys match the target key in the first siglen bytes. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for FirstInSet() for additional important information.

Return

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

Example

FILNO        keyfil;

COUNT        siglen;

TEXT         target[24],recbuf[320];

printf("\nEnter set value:");

scanf("%23s",target);

printf("\nEnter the significant length:");

getnumber(&siglen);

FirstInVSet(keyfil,target,recbuf,siglen,strlen(target));

while (isam_err == NO_ERROR) {

   process_data();

   NextInVSet(keyfil,recbuf);

}

See also

FirstInSet(), NextInVSet(), PreviousInVSet(), LastInVSet(), PositionVSet(), ChangeSet(), TransformKey().

FirstKey

Find the first entry in an index file.

Short Name

FRSKEY()

Type

Low-Level index file function

Declaration

LONG FirstKey(FILNO keyno, pVOID idxval) 

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

FirstKey() searches index file keyno for the first entry in the index. If successful, it copies the first index entry into the space pointed to by idxval.

Return

FirstKey() returns the data record position associated with the first entry in the index file. If the index is empty or an error is detected, FirstKey() returns zero. If FirstKey() returns zero, check uerr_cod to see if an error occurred: if uerr_cod is also zero, then the index is empty; otherwise, an error condition was detected. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

TEXT         idxval[10];

FILNO        keyno;
s

if (FirstKey(keyno,idxval))

   printf("\nFirst index entry = %.10s", idxval);

else {

   printf("\nEither index is empty or an error occurred.");

   if (uerr_cod)

      printf("\Error = %d",uerr_cod);

   else

      printf("\Index is empty.);

}

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered. Use GetCtFileInfo to determine the key length.

The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments. The Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) topic contains suggestions for manipulating the key value.

See also

GetCtFileInfo(), LastKey(), NextKey()

FirstRecord

Read the first data record.

Short Name

FRSREC()

Type

ISAM function

Declaration

COUNT FirstRecord(FILNO filno, pVOID recptr)

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

FirstRecord() retrieves the first data record found. If filno designates an index file, FirstRecord() reads the first data record based on the key sequential order of entries in index file number filno. If filno designates a data file, FirstRecord() reads the first active data record, in physical sequential order. If successful, the first record becomes the current ISAM record for the associated data file. If an error occurs or there are no entries, the current ISAM record is not updated.

If filno designates a data file that is a member of a Superfile, FirstRecord() may not reliably return the FIRST physical active data record, though it will retrieve a record.

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to FirstRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

If FirstRecord() is called with an index number, the data file number involved is not directly described. The ISAM parameters described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contain the correspondence between the index number and the associated data file.

Return

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

Example

FILNO     keyfil, datfil;

TEXT      recbuf[320];

if (FirstRecord(keyfil,recbuf)

    printf("\nError %d retrieving first record.", isam_err);

else if (ReReadVRecord(datfil,recbuf,320))

    printf("\nError %d retrieving variable portion.", isam_err);

else

    printf("\nSuccessful FirstRecord.");

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered. When reading in physical sequential order, FirstRecord() may not retrieve the first possible record position if records have been deleted and the space is currently unused.

See also

CreateIFile(), ReReadVRecord(), NextRecord(), PreviousRecord(), LastRecord()

FirstVRecord

Read the first variable-length data record.

Short Name

FRSVREC()

Type

ISAM function

Declaration

COUNT FirstVRecord(FILNO filno, pVOID recptr, pVRLEN plen)

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

FirstVRecord() is identical to it’s fixed-length counterpart, FirstRecord(), except that it reads the first variable-length data record in the data file. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for FirstRecord() for additional important information.

Return

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

See also

FirstRecord(), NextVRecord(), PreviousVRecord(), TransformKey()

FreeBatch

Free space allocated for multiple batches (groups of records).

Short Name

FREBAT()

Type

ISAM function

Declaration

  COUNT FreeBatch() 

Description

FreeBatch() should be called when it is desired to free the space allocated by AllocateBatch() for multiple, simultaneous batches.

Ordinarily, the only time it is necessary to call FreeBatch() is when you desire to increase the number of simultaneous batches from a previous optional AllocateBatch(). In this case, you call FreeBatch() to free the buffers and then AllocateBatch() with the new upper limit on batches.

CloseISAM() will free multiple batch buffers if they have not already been freed via FreeBatch().

Return

FreeBatch() should always returns NO_ERROR (0) value. Even if FreeBatch() is called when no buffers are allocated, it will simply return a zero without attempting to free any space. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

if (AllocateBatch(3) == 0)

          printf("Room for 3 batches\n");

          FreeBatch();

          if (AllocateBatch(7) == 0)

               printf("Room for 7 batches\n");

See also

AllocateBatch(), CloseISAM()

FreeBatchNbr

Free space allocated for a specific batch.

Short Name

FREBATN()

Type

Low-Level function

Declaration

COUNT FreeBatchNbr(COUNT batnum)

Description

FreeBatchNbr() frees batch number batnum. This routine permits flexible use of a large number of batches within particular code segments responsible for the creation and clean up of the particular batches. Instead of freeing all batches any time one batch needs to be freed, this function frees batches one at a time.

Return

This routine returns an error code, but should return NO_ERROR (0) even if the batnum given does not exist. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO    keyfil;

PKEYREQ  batsamp;           /* Partial Key Request structure */

TEXT     recbuf(1024), retbuf(1024);  /* buffers for records */ 

batsamp.siglen = 4;             /* first 4 bytes significant */

sprintf(batsamp.target,"DISK");         /* partial key value */ 

ChangeBatch(PRIMARY);

if (DoBatch(keyfil,&batsamp,recbuf,1024,

          BAT_GET | BAT_RET_REC | BAT_COMPLETE | BAT_LOK_WRT)) {

     printf("\nBatch error %d",isam_err);

     return;

}

printf("\n%ld entries match",batsamp.btotal);

/* find info in batch */

if ((retbuf = find_in_batch(&recbuf, 1024)) != NULL) {

    ChangeBatch(SECONDARY)

    if (DoBatch(keyfil,&batsamp,retbuf,1024,

           BAT_GET | BAT_RET_REC | BAT_COMPLETE | BAT_LOK_WRT))

    {

         printf("\nSecondary batch error %d",isam_err);

         return;

    }

    printf("\n%ld entries match",batsamp.btotal);

    DoBatch(keyfil,NULL,NULL,0L,BAT_CAN); /* close the batch */

    FreeBatchNbr(SECONDARY);

    ChangeBatch(PRIMARY);

}

DoBatch(keyfil,NULL,NULL,0L,BAT_CAN);     /* close the batch */

FreeBatch();

See also

DoBatch(), FreeBatch(), ChangeBatch()

FreeHistory

Free space allocated for multiple history buffers.

Short Name

FREHST()

Type

ISAM function

Declaration

COUNT FreeHistory() 

Description

FreeHistory() frees the space allocated for multiple, simultaneous history buffers.

Return

FreeHistory() should always return a zero NO_ERROR (0) value. Even if FreeHistory() is called when no buffers are allocated, it will simply return a zero without attempting to free any space. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO     filno;

pVOID     target, bufptr;

LONG      recbyt;

VRLEN     bufsiz;

UCOUNT    mode;

TransactionHistory(filno,target,bufptr,recbyt,bufsiz,mode);

FreeHistory();

See also

TransactionHistory(), ChangeHistory()

FreeHistoryNbr

Free space allocated for a transaction history.

Short Name

FREHSTN()

Type

Low-Level function

Declaration

COUNT FreeHistoryNbr(COUNT hstnum) 

Description

FreeHistoryNbr() frees history number hstnum. This routine permits flexible use of a large number of histories within particular code segments responsible for the creation and clean up of the particular histories. Instead of freeing all histories any time one history needs to be freed, this function frees histories one at a time.

Return

This routine returns an error code, but should return NO_ERROR (0) even if the hstnum given does not exist. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

ChangeHistory(0);

if ((retval = TransactionHistory(CUSTIDX, target, &bufptr, 0L,

              (VRLEN) INPBUFSIZ+40,

              ctHISTfirst | ctHISTkey | ctHISTdata)) > 0) {

    printf("\nError in first call : %d", retval);

    isam_error();                                                        

    return;

}

displayhistorybuffer(bufptr, INPBUFSIZ);

repeat("\n\nGet next match? ", choice);

while ((choice[0] == 'Y') || (choice[0] == 'y'))  {

    if ((retval = TransactionHistory(-1, (pVOID) 0, &bufptr,

                  0L, (VRLEN) INPBUFSIZ+40, ctHISTnext)) > 0) {

        if (retval == HENT_ERR) {

            printf("\nEnd of logs or bad logs.");

        } else {

            printf("\nError in subsequent call : %d", retval);

            isam_error();                         

        }

        return;

    } else {

        displayhistorybuffer(bufptr, INPBUFSIZ);

        repeat("\n\nGet more data? ", &choice);

    }

}

TransactionHistory(-1,(pVOID) 0, (pVOID) 0, -1L, (VRLEN) 0, ctHISTlog);

   /* Default terminating call */

FreeHistoryNbr(0);

See also

TransactionHistory(), FreeHistory(), ChangeHistory()

FreeRange

Reset and free allocated buffers for range operation

Short Name

FRERNG()

Type

ISAM function

Declaration

COUNT FreeRange(FILNO keyno)  

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

FreeRange() should be called when a range associated with an index is no longer needed.

Return

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

Example

if (FreeRange(1))

    printf("\nFreeRange error = %d",uerr_cod);

See also

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

FreeSet

Free space allocated for multiple sets.

Short Name

FRESET()

Type

ISAM function

Declaration

COUNT FreeSet() 

Description

FreeSet() should be called when it is desired to free the space allocated by AllocateSet() for multiple, simultaneous sets.

Ordinarily, the only time it is necessary to call FreeSet() is when you desire to increase the number of simultaneous sets from a previous optional call to AllocateSet(). In this case, you call FreeSet() to free the buffers and then AllocateSet() with the new upper limit on sets.

CloseISAM() frees all set buffers if they have not already been freed via FreeSet().

Return

FreeSet() should always returns NO_ERROR (0) value. Even if FreeSet() is called when no buffers are allocated, it will simply return a zero without attempting to free any space. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

if (AllocateSet(5) == 0)

    printf("\nRoom for 5 sets\n");

FreeSet();

if (AllocateSet(10) == 0)

    printf("\nRoom for 10 sets\n");

See also

AllocateSet(), CloseISAM()

FreeSetNbr

Free space allocated for a specific set.

Short Name

FRESETN()

Type

Low-Level function

Declaration

COUNT FreeSetNbr(COUNT setnum) 

Description

FreeSetNbr() frees set number setnum. This routine permits flexible use of a large number of sets within particular code segments responsible for the creation and clean up of the particular sets. Instead of freeing all sets any time one needs to be freed, this function frees sets one at a time.

Return

This routine returns an error code, but should return NO_ERROR even if the setnum given does not exist. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

COUNT     i;

FILNO     keyno0, keyno1;

struct DATAREC datrec0, datrec1;

if (ChangeSet(0))

    printf("\nCould not change set. Error=%d\n", isam_err);

if (FirstInSet(keyno0, &datrec0))

    printf("\nCould not get FirstInSet. Error=%d\n", isam_err);

if (ChangeSet(1))

    printf("\nCould not change set. Error=%d\n", isam_err);

if (LastInSet(keyno1, &datrec1))

    printf("\nCould not get LastInSet. Error=%d\n", isam_err);

FreeSetNbr(0);

See also

FreeSet(), FirstInSet(), ChangeSet()

GetAltSequence

Retrieve information from a data file relating to an alternate collating sequence that has been stored as a Resource.

Short Name

GETALTSEQ()

Type

Low-Level index file resource function

Declaration

COUNT GetAltSequence(FILNO keyno, pCOUNT altseq)

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

GetAltSequence() returns the alternative collating sequence into the array of 256 short integers pointed to by altseq.

Return

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

See also

SetAlternateSequence()

getcndxmem

Get memory required to process and store conditional index expressions (allows the proper memory allocation routines to be used on the client and server sides).

Declaration

pTEXT getcndxmem( UINT sizobj );

Description

The macros getcndxmem() and putcndxmem(), used to get and put memory required to process and store conditional index expressions, allow the proper memory allocation routines to be used on the client and server sides. (These substitute for the internal mballc() and mbfree() calls.)

Return Values

getcndxmem() returns a pointer to the newly allocated object on success. A NULL pointer is returned if memory could not be allocated.

Example

/* Allocate a run-time stack for the expression analyzer (first time only). */

if (!ctcidxStk)  {

    ctcidxStk = (pVOID) getcndxmem(CNDX_MAX_STACK * ctSIZE(PLEAF));

    if (!ctcidxStk)  {

        printf("Unable to allocate memory for run-time stack.\n");

        ctrt_exit(1);

    }

}

if (ctcidxStk)

putcndxmem(ctcidxStk);

See also

cndxeval(), cndxfree(), cndxparse(), ctparsedoda(), cndxrun(), putcndxmem()

getChangeIDfieldNumber

Get the relative field number of the specified data file's change id field.

Declaration

ctCONV NINT ctDECL getChangeIDfieldNumber (FILNO datno, pNINT pFieldNumber); 

Description

[IN] datno- Data file number.

[OUT] pFieldNumber- On success, the zero-based field number in the DODA for the change ID field is returned here. If the data file has no change id field, -1 is returned.

Return Values

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

getChangeIDheaderValue

Get the value of the specified data file's change id header field.

Declaration

ctCONV NINT ctDECL getChangeIDheaderValue(FILNO datno, ctCHGID *pChangeIdValue);

CTREE

Description

[IN] datno- Data file number.

[OUT] pChangeIdValue- On success, the change id header value is returned here.

Return Values

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

GetConditionalIndex

Get the conditional index resource from a data file.

Short Name

GETCIDX()

Type

ISAM function

Declaration

VRLEN GetConditionalIndex(FILNO keyno, LONG bufsiz, pVOID idxcnd)

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

GetConditionalIndex() returns the length of the NULL terminated ASCII string, including the NULL byte, containing the symbolic conditional expression for index keyno. This assumes an ISAM mapping exists between keyno and a data file.

Return

If idxcnd is non-NULL and bufsiz is greater than or equal to the length returned, the string is returned to the address specified by idxcnd. If idxcnd is NULL or bufsiz is too small, the length is returned by GetConditionalIndex(), no error is raised, and no string is returned. A zero return indicates no conditional expression or an error condition returned in isam_err, as follows:

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

Example

LONG      i;

FILNO     keyno;

LONG      bufsiz = INPBUFSIZ;

VRLEN     returnvalue;

pTEXT     tempbuffer;

TEXT      inpbuf[INPBUFSIZ];

printf(

"\nEdit condition for (1) Name or (2) Customer Number index: "

);

ctsfill(inpbuf,0,INPBUFSIZ);   /* Select an index */

gets(inpbuf);

if (inpbuf[0] != '\0') {

    sscanf(inpbuf,"%d",&i);

    keyno = (FILNO) i;

    printf("\n\nEnter a conditional expression, such as ");

    if (keyno == 1)

        printf("strncmp(LastName, \"S\", 1) == 0." );

    else

        printf("Customer >= 50." );

    ctsfill(inpbuf, 0, INPBUFSIZ);

    if ((returnvalue =

         GetConditionalIndex(keyno, bufsiz, inpbuf)) == 0) {

               /* Retrieve the current condition */

        if (isam_err) {              

            printf("Error %d getting conditional expression.", isam_err);

            return;

        }

    }

    else if (returnvalue > (VRLEN) bufsiz) {

                                      /* If buffer too small */

        bufsiz = (LONG) returnvalue + 1;

                                      /* Set a new size      */

        mbfree(inpbuf);

        tempbuffer = (pTEXT) mballc(1, (UINT)bufsiz);

                                      /* Allocate space      */

        inpbuf = (pTEXT) mballc(1, (UINT)bufsiz);

        if (!tempbuffer || !inpbuf) {  

            printf("Error allocating space for buffers\n");

            return;

        }

        GetConditionalIndex(keyno, bufsiz, tempbuffer);

                                   /* Retrieve the condition */

        cpybuf(inpbuf, tempbuffer, bufsiz);

        mbfree(tempbuffer);

    }

    printf("\nThe conditional expression is %s.", inpbuf);

}   

See also

UpdateConditionalIndex()

GetCtFileInfo

Retrieve information from a file header.

Short Name

GETFIL()

Type

Low-Level function

Declaration

LONG GetCtFileInfo(FILNO filno, COUNT mode)

Description

A variety of information about a file is stored in the file header. In FairCom DB the header is accessible only by using GetCtFileInfo() to access certain items of information from the header of file filno. Use mode to specify the type of information to be returned. The following values can be used for mode:

Return

The return value depends on the mode used in the function call. The value returned is based on the mode selected. A value of -1L means that uerr_cod contains an error.

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

Example

FILNO datfil;

printf("\nThe record length is %ld",

       GetCtFileInfo(datfil,RECLEN));

See also

GetSymbolicNames()

GetCtreePointer

Return a pointer to a FairCom DB state variable structure (CTGVAR).

Short Name

GETCTREE()

Type

Low-Level function

Declaration

pVOID GetCtreePointer(pTEXT regid)  

Description

GetCtreePointer() returns a pointer to the FairCom DB state variable structure, CTGVAR, based on the name used in a call to RegisterCtree(). The function declaration returns a pVOID, which should be cast by the application to a pCTGVAR.

This function is useful for obtaining the error variables when ctNOGLOBALS is defined, or when utilizing FairCom DB as a DLL (Dynamic Loadable Library). The most commonly accessed variables from the CTGVAR structure are:

COUNT    suerr_cod;      /* user error cod, uerr_cod   */

COUNT    ssysiocod;      /* system error cod, errno    */

COUNT    sisam_err;      /* isam error, isam_err       */

FILNO    sisam_fil;      /* isam file number, isam_fil */

The complete global structure, CTGVAR, is located in ctgvar.h.

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

Return

If the name used in the call to GetCtreePointer() does not exist, then a NULL is returned, otherwise the pointer to the files CTGVAR structure is returned. No error code is set (or reset) by this call whether successful or not. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

pCTGVAR     ctWNGV;

ctWNGV = GetCtreePointer(WhichCtree());

isam_err = ctWNGV->sisam_err

See also

NextCtree(), SwitchCtree(), RegisterCtree(), WhichCtree(), UnRegisterCtree()

GetCtResource

Get Resource record from data file.

Short Name

GETRES()

Type

Low-Level data file resource function

Declaration

LONG GetCtResource(FILNO datno, pVOID resptr, pVOID bufptr,

                   VRLEN bufsiz, COUNT resmode)

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

GetCtResource() retrieves a Resource from data file datno, returns a long integer corresponding to the byte offset of the Resource, and places the value of the Resource in the buffer pointed to by bufptr. bufsiz is the size of the buffer area. The buffer will contain the entire Resource Data Block. See AddCtResource() for information.

resmode specifies the method of searching for the Resource. resptr points to the identifying information used in the search. The resmode choices are:

See also Record Offsets Under Huge File Support.

Return

If no error occurs, GetCtResource() returns the byte offset for the Resource record. On RBUF_ERR (404), GetCtResource() returns the resource offset and sets uerr_cod to 404. Otherwise, GetCtResource() returns a zero and uerr_cod is set as follows:

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

Example: 1 RES_NAME

struct {                    /* Resource Data Block structure */

    ULONG     resource_type;

    ULONG     resource_number;

    TEXT      variable_info[1016]; /* This holds the         */

} my_resource;                     /* Resource Name and Data */

my_resource.resource_type    = 0x10001L;            /* 65537 */

my_resource.resource_number  = 0xffffffffL;         /* FairCom DB assigns number*/

strcpy(my_resource.variable_info,"MY!resource");

strcpy(my_resource.variable_info+12,"Actual Resource Data");

if (AddCtResource(datno,&my_resource,

   (VRLEN)(8 + 12 + strlen(my_resource.variable_info+12))) == 0)

{

    printf("\nThe resource has been assigned number %ld",

           my_resource.resource_number);

    printf("\nThe resource is located at byte offset %ld.",

           GetCtResource(datno, "MY!resource", &my_resource,

                         1024L, RES_NAME));

} else

    printf("\nCould not add resource. Error #%d",uerr_cod);

Example 2: RES_LENGTH

struct {

    ULONG     resource_type;

    ULONG     resource_number;

    TEXT      variable_info[504];

} sample;

LONG     ret;          /* length returned from GetCtResource */

sample.resource_type = 0x10001L;                    /* 65537 */

sample.resource_number = 0xffffffffL;               /* FairCom DB assigned number  */

strcpy(sample.variable_info,"SAMPLE1!resource");    /* assign resource name */

strcpy(sample.variable_info+18,

       "This is the first resource record.");

if (AddCtResource(datno, &sample,

    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)

    printf("\nError adding first resource!, error = %d", uerr_cod);

else

    printf("\nSuccessful addition of first Resource Record");

strcpy(sample.variable_info,"SAMPLE2!resource"); 

                                     /* assign resource name */        

strcpy(sample.variable_info+18,

       "This is the second resource record.");

if (AddCtResource(datno,&sample,

    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)

    printf("\nError adding second resource!, error = %d", uerr_cod);

else

    printf("\nSuccessful addition of second Resource Record");

strcpy(sample.variable_info,"SAMPLE3!resource");

 /* assign resource name */         strcpy(sample.variable_info+18,

       "This is the third resource record.");

if (AddCtResource(datno, &sample,

    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)

    printf("\nError adding third resource!, error = %d", uerr_cod);

else

    printf("\nSuccessful addition of third Resource Record");

if ((ret=GetCtResource(datno, "SAMPLE1!resource", &sample, 512,

                       RES_NAME | RES_LENGTH)) != 0)

{

    cpybuf(&ret,sample.variable_info, sizeof(LONG));

    printf("\nFirst resource name is %ld bytes long",ret);

}

else

    printf("\n\nError on First resource length = %d",uerr_cod);

Example 3: RES_NEXT

    if ((ret = GetCtResource(datno, "SAMPLE1!resource", &sample,

                         512, RES_NAME)) !=0)

    printf("\nFirst resource is %s",sample.variable_info);

else

    printf("\n\nError on First resource = %d",uerr_cod);

if ((ret = GetCtResource(datno, &sample, &sample, 512, RES_NEXT)) !=0)

    printf("\nNext resource is %s",sample.variable_info);

else

    printf("\n\nError on Next resource = %d",uerr_cod);

See also

LockCtData(), LockISAM(), ctSETHGH(), ctGETHGH(), UpdateCtResource(), AddCtResource(), DeleteCtResource()

GetCtTempFileName

Create a file name that is guaranteed to be unique. Can also specify the path for the creation of temporary files.

Short Name

TMPNAME()

Type

Low-level function

Declaration

COUNT GetCtTempFileName(pVOID bufptr, VRLEN bufsiz)

Description

GetCtTempFileName() by default returns a unique file name in the parameter bufptr. Set bufsiz to the length of the buffer at bufptr, minimum 10 bytes.

Three c-tree configuration settings influence how GetCtTempFileName() functions:

• ct_tmppth -- A c-tree global variable to set the temporary files directory path in standalone operation.
• TMPNAME_PATH -- A FairCom Server configuration keyword specifying a directory name to use for the temporary files.
• USERPRF_PTHTMP -- An initialization parameter to InitCTreeXtd() toggling the functionality of the GetCtTempFileName() operation. When specified, bufptr specifies the temporary file directory, and must be nul terminated.

The usage of this function varies by c-tree model and how you configure these three c-tree operational values.

Standalone Usage

To specify a directory name where temporary files are to reside in the standalone model set the global variable, ct_tmppth, to the path desired.

Previously, the user profile mask, USERPRF_PTHTMP, was documented for use in the InitCTreeXtd() call. This use of USERPRF_PTHTMP in standalone mode should be considered legacy support. Setting the path with ct_tmppth is the FairCom recommended approach in standalone mode.

Client Server Usage

The client-server model becomes more complicated as there are two values to consider. The FairCom Server allows specifying a directory name with the TMPNAME_PATH server configuration keyword. In addition, the user profile mask, USERPRF_PTHTMP, will change the behavior of the GetCtTempFileName() function to allow setting the temp path directory location.

In the client-server model, the user profile mask takes precedence over the TMPNAME_PATH server configuration setting. Together, the combination of these two settings determine the action taken by the FairCom Server.

The following table summarizes the behavior of GetCtTempFileName():

Table 6-5:

Return

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

Example Standalone Usage

#define  MAX_SIZE 255

TEXT     temp_path[MAX_NAME] = "/usr/fairtemp/";

pTEXT    path_buffer;

if (InitISAMXtd(32, /* index buffers       */

                12, /* files               */

                 8, /* # 128 bytes sectors */

                32, /* data cache pages    */

                 0, NULL,NULL,NULL)) {

    printf("\nCould not initialize FairCom DB\n");

    exit(2);

}

/* Allocate buffer for temporary file path. */

if (!(ct_tmppth = mballc(1, MAX_SIZE)))

     printf("Error: Failed to allocate %d bytes for temp path buffer\n",

          MAX_SIZE);

/* Allocate buffer for temporary file buffer. */

if (!(path_buffer = mballc(1, MAX_SIZE)))

     printf("Error: Failed to allocate %d bytes for temp path buffer\n",

          MAX_SIZE);

/* Specify the path /usr/fairtemp/ for temporary files */

strncpy(ct_tmppth, temp_path, MAX_SIZE);

/* Request a temporary file name */

if(GetCtTempFileName(path_buffer,200L)) {

    printf("\nError on GetCtTempFileName, uerr_cod =%d", uerr_cod);

    exit(2);

}

printf("\nUsing temporary pathname: %s\n", path_buffer);

/* Done with temp path buffers, so free them. */

if (ct_tmppth) {

     mbfree(ct_tmppth);

     ct_tmppth = NULL;

}

if (path_buffer) {

     mbfree(path_buffer);

     path_buffer = NULL;

}

CLISAM();

Client Server Usage with USERPRF_PTHTMP

#define  MAX_SIZE 255

TEXT     temp_path[MAX_NAME] = "/usr/fairtemp/";

pTEXT    path_buffer;

if (InitISAMXtd(32, /* index buffers       */

                12, /* files               */

                 8, /* # 128 bytes sectors */

                32, /* data cache pages    */

                USRPRF_PTHTMP, /* GetCtTempFileName sets path */

                "ADMIN","ADMIN","FAIRCOMS")) {

    printf("\nCould not initialize FairCom DB\n");

    exit(2);

}

/* Allocate buffer for temporary file path. */

if (!(path_buffer = mballc(1, MAX_SIZE)))

     printf("Error: Failed to allocate %d bytes for temp path buffer\n",

          MAX_SIZE);

/* Specify the path /usr/fairtemp/ for temporary files */

strncpy(path_buffer, temp_path, MAX_SIZE);

/* Set the temporary file name */

if(GetCtTempFileName(path_buffer, MAX_SIZE)) {

    printf("\nError on GetCtTempFileName, uerr_cod =%d", uerr_cod);

    exit(2);

}

printf("\nUsing temporary pathname: %s\n", path_buffer);

/* Done with temp path buffer, so free it. */

if (path_buffer) {

     mbfree(path_buffer);

     path_buffer = NULL;

}

CLISAM();

Limitations

If a client process on a heterogeneous network sends a GetCtTempFileName() path with an improper directory separator, GetCtTempFileName() returns an error, since the name will not be well defined, instead of automatically changing the separators to match the Server conventions.

See also

TMPNAME_PATH configuration keyword in the FairCom Server Administrator’s Guide.

InitCTreeXtd()

GetDODA

Retrieve information from a record schema stored as a resource.

Short Name

GETDODA()

Type

Low-Level data file resource function

Declaration

VRLEN GetDODA(FILNO datno, LONG bufsiz, pVOID bufptr, COUNT mode)

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

GetDODA() returns various forms of the records schema, if any are included in the data file as a resource, into the buffer pointed to by bufptr.

bufsiz specifies the length of the buffer. The value returned by GetDODA() is the actual length of the information requested. If bufsiz is too small, GetDODA() still returns the actual size, but no data is transferred into the buffer. Another call to GetDODA() with a proper size buffer is required.

mode indicates the form of the return information. mode may take on one of the following values.

If SCHEMA_MAP is requested, a map, as described in Record Schemas, is returned in the buffer.

If SCHEMA_NAMES is requested only the names, in the form described in Record Schemas, are returned in the buffer.

If SCHEMA_MAPandNAMES is requested the buffer contains the schema map followed immediately by the schema name. The maplen member of the schema map is the offset from the beginning of the buffer to the names. See Record Schemas.

If SCHEMA_DODA is requested, the map and names are converted to the form of a DODA where the fadr member of the DATOBJ structure is filled with the offset of the field from the beginning of the record.

Return

In the event of an error, GetDODA() returns a zero value and uerr_cod is typically set to one of the following values:

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

See also

PutDODA()

GetFileRegions

Calculates offsets and lengths of a specified number of regions in a data file, accounting for resource locations, such that starting region offsets correspond to an active or deleted record at the time this function is called. A region is defined by a starting data file offset and the region length in bytes. (V11.8 and later)

Type

ISAM Function

NINT ctDECL GetFileRegions (pFILE_REGION_REQUEST pFileRegionRequest);

Description

• [INOUT] pFileRegionRequest - Data structure used to pass information in and out of the function, defined below.

Description

Structure Definitions

typedef struct fileRegionRequest_t {

    COUNT structVersion;  

    FILNO dataFileNumber; 

    LONG numberOfRegions; 

    pFILE_REGION fileRegions; 

} FILE_REGION_REQUEST, *pFILE_REGION_REQUEST;

• [IN] structVersion - Structure version (consult ctport.h for current versions).
• [IN] dataFileNumber - c-tree data file number
• [IN] numberOfRegions - Number of FILE_REGION structures in the array, which is the number of regions you desire.

fileRegions must have enough memory for that number of FILE_REGION structures.

• [OUT] fileRegions - Array of FILE_REGION structures.

Offset and length values are set on successful output.

Note: Your code is responsible for allocating before calling the function and deallocating afterwards.

typedef struct fileRegion_t {

 ULONG8 offset; 

 ULONG8 length; 

} FILE_REGION, *pFILE_REGION;

• [OUT] offset - starting record offset for region in the data file
• [OUT] length - size of this region in bytes

Region Definition

FairCom DB calculates the starting offset of each region by dividing the data file into equally sized regions corresponding to the number of regions specified by numberOfRegions in the fileRegionRequest_t structure. It aligns the offset of each region in fileRegion_t to the record offset of the first record in the region. It aligns the length to the offset of the last byte of the last record in the region.

Because the data file may contain resources, FairCom DB determines the locations of resource records in the data file. If any region offset lands on or within a resource record, FairCom DB adjusts the offset to start on the first record after the resource.

If the adjusted starting offset is no longer inside the specified region (which is only likely for small files), the offset and length of the region are returned as zero. Thus, you must ignore regions with zero length.

Example

NINT numberOfRegions = 10;               /* specify number of regions */

pFILE_REGION fileRegions = NULL;         /* array returned with region information */

FILNO datno;                             /* data file number */

/* structure used to request and receive region information */

FILE_REGION_REQUEST fileRegionRequest; 

NINT i, rc;

/* Allocate memory for the array of regions that GetFileRegions() will populate */

if (!(fileRegions = (pFILE_REGION) mballc(numberOfRegions, sizeof(FILE_REGION)))) {

    printf("Error: Failed to allocate memory for the region array.\n");

    return -1;

}

/* Open the data file */

if ((datno = OPNRFIL(-1, "MyDataFile.dat", ctSHARED)) < 0) {

    rc = isam_err;

    printf("Error: failed to open file: %d\n", rc);

    if (fileRegions)

        mbfree(fileRegions);

    return -1;

}

/* Prepare structure returning file regions */

fileRegionRequest.structVersion = FILE_REGION_REQUEST_VERS_V01;

fileRegionRequest.dataFileNumber = datno;            /* The data file */

fileRegionRequest.numberOfRegions = numberOfRegions; /* Requested regions */

fileRegionRequest.fileRegions = fileRegions;         /* Allocated array */

if ((rc = GetFileRegions(&fileRegionRequest))) {

    printf("Error: failed to get region information: %d\n", rc);

    if (fileRegions)

        mbfree(fileRegions);

    return -1;

}

/* Now print the region information */

printf("offset      length\n");

for (i=0; i<numberOfRegions; i++) {

    printf(ctLLnd(10) " " ctLLnd(10) "\n",fileRegions[i].offset,fileRegions[i].length);

}

if (fileRegions)

    mbfree(fileRegions); /* Free region array */

return(0);

Limitations

• This function is not supported for variable-length record data files.
• This function is not supported for memory files.
• This function is not supported for superfiles (superfile hosts or members).
• This function is not available for Multi-user Multi-threaded Standalone model. It is available for Multi-user and Single-user Standalone.

Coding Considerations

• The number of records in one region may be less than another region because the function does not take into consideration deleted records when it divides the data into regions. For this reason, it is unlikely, but possible, that a region could be occupied solely by records that were previously deleted.
• In data files containing few records that are divided into many regions, it is possible for a region to contain no records. This will cause FILE_REGION.length and FILE_REGION.offset to be zero.
• Multiple threads can speed data processing as long as the storage system has enough I/O bandwidth and the CPU has enough processing power. When data processing becomes I/O or CPU bound, adding more threads can slow data processing.
• Batch record processing, such as DoBatch(), does NOT stay within the current region. Instead, batch functions stop when the end of file is reached or the batch buffer is full. This means batch functions can return records that are past the end of a region, and this can cause the same record to be processed by more than one thread. To prevent this, use the BAT_RET_REC option instead of BAT_RET_BLK to return the record offset with each record. You can write threads to stop processing records as soon as they find a record whose offset is outside of that thread’s region.
• When adding resources to a data file while using this function, the application should first acquire a table lock. Otherwise, if a resource is added, deleted, or updated after the function has determined resource offsets, the function can return an offset that corresponds to a resource or to a location within a resource.
• The GetFileRegions() function does not automatically provide read isolation to a region. It does not protect a region from being updated by other processes. This is because the function does not acquire locks on the records in a region. If you require read consistency for an entire region, the safest way is to lock the entire table. Alternatively, you can lock individual records in a region with the possibility that another process may lock some of them first.

Return

• Success: NO_ERROR(0)
• Failure: Non-zero c-tree error code:

Programming Errors

• 10 - SPAC_ERR - Out of space. Parameters require too much space. Check the parameters passed in to make sure they are correct.
• 43 - FVER_ERR - Check the versions specified in the structures passed in to the function. They must match the versions in use in the data file as set at file creation or last version update. structVersion must be FILE_REGION_REQUEST_VERS_V01
• 47 - FINT_ERR - c-tree has not been initialized. You need to call InitISAM() first.
• 48 - FMOD_ERR - File mode error. Make sure the data file type is compatible with this function. File types such as superfile host, superfile member, memory file, or variable-length record data file are incompatible with this function.
• 78 - TABN_ERR - Transaction has become too large. Re-try in smaller pieces.
• 82 - UALC_ERR - User allocation error. Check the parameters, our memory allocation based on the parameters failed.
• 540 - PNUL_ERR - Null parameter error. One or more required parameters passed to the function is null.
• 634 - NLEN_ERR - Negative length specified. Check the lengths you passed into the function.
• 22 - FNUM_ERR - filno out of range. You may be attempting to open more files than the server is configured for. Increase the file limit of the server and try again. This error may also occur if c-tree has not been initialized.
• 26 - FACS_ERR - File number is not in use. This occurs when you specify an invalid data file number or the file has been closed.
• 643 - DPND_ERR - File is being deleted.
• 798 - FBLK_ERR - File is blocked, retry later.
• 799 - FBLK_RDO - File block cleared: close/reopen file.

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

Compatibility Note: This new functionality involves changes to both the client library and the server, so, in addition to installing a new server executable, the client program must be re-linked.

GetFilterVersion

Returns the version of the filter callback API that the DLL uses.

Declaration

LONG GetFilterVersion (VOID)

Description

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

When loading a filter callback DLL, FairCom DB calls this function and fails to load the DLL with error CBKV_ERR (870) if the filter callback API version returned by the DLL doesn't match the filter callback DLL API version that FairCom DB is using.

Return Values

Filter version found in the SDK.

See also

ctfiltercbAddFilter(), EvaluateFilter(), ctfiltercbRemoveFilter(), UnloadFilter(), SetDataFilter()

GetGTEKey

Search index file for entry equal to or greater than target.

Short Name

GTEKEY()

Type

Low-Level index file function

Declaration

LONG GetGTEKey(FILNO keyno, pVOID target, pVOID idxval) 

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

GetGTEKey searches index file keyno for the first entry which is equal to, or greater than, the key value pointed to by target. If such an entry exists, it is copied into the area pointed to by idxval.

GetGTEKey() is frequently used to start searching an index file that accepts duplicate keys. GetKey() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure the entry with the smallest suffix is found.

Return

If GetGTEKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty or the target key value exceeds all entries in the index), GetGTEKey() returns a zero. When GetGTEKey() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO        keyno;

TEXT         target[24],*idxval;

pLONG        suffix;

/* Key length = 23. Assuming duplicates are allowed, the last

 * four bytes are for the suffix.                            */

scanf("%19s",target);

suffix = target + 20;      /* pointer to the last four bytes */

*suffix = 0L;              /* set suffix to zero.            */

    /* Assumes no alignment restrictions.  */

idxval = "12345678901234567890123";/*reserve space for idxval*/

if (GetGTEKey(keyno,target,idxval))

    printf("\nthe key value >= %.19s is %.19s",target,idxval);

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered.

Note: The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

GetKey(), GetGTKey(), GetLTEKey(), GetLTKey()

GetGTERecord

Read the record with key greater than or equal to target.

Short Name

GTEREC()

Type

ISAM function

Declaration

COUNT GetGTERecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetGTERecord() reads the first data record whose key value in keyno is equal to, or greater than, the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetGTERecord() is frequently used to start searching a file via an index file that accepts duplicate keys. GetRecord() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

An alternative to GetGTERecord() is FirstInSet(), which reads the first data record whose key value matches the significant bytes in a target key; it is not necessary to pad the target when using FirstInSet(). The main difference between GetGTERecord() and FirstInSet() is that GetGTERecord() does not require any match with the target.

If the associated data file has variable-length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetGTERecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contains the relationship between the index file number and the associated data file.

Return

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

Example

LONG      cust_number;

FILNO     keyno;

pTEXT     recptr;

scanf("%ld",cust_number);

if (GetGTERecord(keyno,&cust_number,recptr))

    printf("\nUnsuccessful search. Code = %d on file %d.", isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

GetRecord(), FirstInSet(), TransformKey(), CreateIFile(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetGTEVRecord

Read the variable-length record with key greater than or equal to target.

Short Name

GTEVREC()

Type

ISAM function

Declaration

COUNT GetGTEVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetGTEVRecord() is the same as its fixed-length counterpart, GetGTERecord(), except one new argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

See the GetGTERecord() function description for additional important information.

Return

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

See also

GetGTVRecord(), GetLTEVRecord(), GetLTVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

GetGTKey

Search index file for entry greater than target.

Short Name

GTKEY()

Type

Low-Level index file function

Declaration

LONG GetGTKey(FILNO keyno, pVOID target, pVOID idxval) 

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

GetGTKey() searches index file keyno for the first entry that is strictly greater than the key value pointed to by target. If such an entry exists, then it is copied into the area pointed to by idxval.

Return

If GetGTKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty, or the target key value exceeds all entries in the index), then GetGTKey() returns a zero. When GetGTKey() returns a zero check the value of uerr_cod: if uerr_cod is non-zero, an error was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO   keyno;

TEXT    target[24],idxval[23];

LONG    recbyt;

ctsfill(target,0,24);

ctsfill(idxval,0,23);

scanf("%23s",target);

recbyt = GetGTEKey(keyno,target,idxval);

while (recbyt) {

    printf("\nIndex entry = %23s Record # = %ld",

           idxval,recbyt);

    cpybuf(target,idxval,23);

    recbyt = GetGTKey(keyno,target,idxval);

}

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered.

The key value returned will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

GetGTEKey(), GetKey(), GetLTEKey(), GetLTKey()

GetGTRecord

Read the record with key greater than target.

Short Name

GTREC()

Type

ISAM function

Declaration

COUNT GetGTRecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetGTRecord() reads the first data record whose key value in keyno is greater than the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetGTRecord() is frequently used to search for the next value greater than target. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

If the associated data file has variable-length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetGTRecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contains the relationship between the index file number and the associated data file.

Return

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

Example

LONG      cust_number;

FILNO     keyno;

pTEXT     recptr;

scanf("%ld",cust_number);

if (GetGTRecord(keyno,&cust_number,recptr))

    printf("\nUnsuccessful search. Code = %d on file %d.",

           isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

GetGTEKey(), GetRecord(), FirstInSet(), CreateIFile(), TransformKey(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetGTVRecord

Read the variable-length record with key greater than target.

Short Name

GTVREC()

Type

ISAM function

Declaration

COUNT GetGTVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetGTVRecord() is the same as its fixed-length counterpart, GetGTRecord(), except one new argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for GetGTRecord() for additional important information.

Return

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

See also

GetGTEVRecord(), GetLTEVRecord(), GetLTVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

getIDfield

Return IDENTITY attribute information from a file.

Declaration

NINT getIDfield(FILNO datno, NINT mode, pLONG8 retval)

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

getIDfield() returns information about an IDfield (IDENTITY) value.

Where:

• datno is the data file number
• mode is the next value to be assigned to the field on add.
• retval is the value to increment each addition.

mode can take one of the following values:

• updateValue - return is set to the next IDfield value, and the IDfield is updated
• reportValue - return is set to the next IDfield value, but the IDfield remains unchanged
• startingValue - return is set to the starting value for the IDfield
• deltaValue - return is set to the IDfield change value (delta in IDfield)

IDfield requires a DAR resource (Direct Access Resource) embedded in the file. The DAR is a specialized high-speed resource.

Return

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

Example

retval = getIDfield(fileno, reportValue, &idval);

if (retval) {

printf("\tERROR: Failed to retrieve ID information with error %d\n", retval);

}

  else

         printf("Next IDENTITY value is %d\n", idval);

Override IDENTITY Values

PUTHDR() using the ctIDfieldOverRide mode can turn on and off the ability to override the automatic IDfield values. The override is on a per user, per file basis. A nonzero hdrval turns on the override, and a zero hdrval restores the standard operation. When the override is on for a data file that supports an IDfield, then an add record operation does not fill-in the IDfield value. Whatever is passed in the record buffer is used for the IDfield. And a rewrite permits the IDfield value to change instead of generating the IDFL_CHG error. When the override is enabled, add record operations do not consume IDfield values.

See also

addIDfield(), delIDfield(), wchIDfield(), resetIDfield(), IDfields - Extended support

GetIFile

Retrieve an IFIL structure from a data file

Short Name

GETIFIL()

Type

ISAM resource function

Declaration

VRLEN GetIFile(FILNO datno, LONG bufsiz, pVOID bufptr) 

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

GetIFile() returns a complete IFIL structure into the buffer pointed to by bufptr. bufsiz contains the size of the buffer. If bufsiz is too small, GetIFile() returns a required buffer size, but no IFIL information is returned. Call GetIFile() again with the required buffer size. If bufsiz is sufficiently large, the value returned by GetIFile() is the actual length of the IFIL structure and its subsidiary IIDX and ISEG structures, which are included in the buffer. In some cases the actual size may be less than the required buffer size.

It is permissible to cast the buffer pointer to a pointer of type pIFIL.

Return

GetIFile() returns either the required or the actual size of the IFIL structure (including associated IIDX and ISEG structures) from the data file referred by datno.

In case of error, GetIFile() returns a zero value. The error code can be found in isam_err. Possible errors are described in the following table.

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

Refer to the following sections for additional details regarding IFIL structures.

IFIL Structure

IIDX Structure

ISEG Structure

Limitations

Resources are required.

See also

OpenFileWithResource(), PutIFile()

GetKey

Search index file for entry equal to target value.

Short Name

EQLKEY()

Type

Low-Level index file function

Declaration

LONG GetKey(FILNO keyno, pVOID target) 

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

GetKey() searches index file number keyno for an entry equal to the key value pointed to by target.

See also Record Offsets Under Huge File Support.

Return

If GetKey() finds an exact match for target, then it returns the data record position associated with the entry. If an exact match is not found, or if an error occurs, then GetKey() returns a zero, and the global variable uerr_cod is set to the appropriate value. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

LONG      recbyt;

FILNO     keyno;

TEXT      target[11];

scanf("%10s %d",target,&keyno);

if (!(recbyt = GetKey(keyno,target))) {

    if (uerr_cod)

        printf("\nError while searching.");

    else

        printf("\nKey value not found.");

}

else

    printf("\nKey value is in record at position %ld.", recbyt);

Limitations

FairCom DB will not pad the target key value. Ensure that target points to a properly formed key value. This function is not appropriate for indexes allowing duplicates. Use a function from below in that case.

See also

GetGTEKey(), GetGTKey(), GetLTEKey(), GetLTKey()

GetLTEKey

Search index file for entry equal to or less than target.

Short Name

LTEKEY()

Type

Low-Level index file function

Declaration

LONG GetLTEKey(FILNO keyno, pVOID target, pVOID idxval) 

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

GetLTEKey() searches index file keyno for the last entry which is equal to, or less than, the key value pointed to by target. If such an entry exists, it is copied into the area pointed to by idxval.

Return

If GetLTEKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty or the target key value exceeds all entries in the index), GetLTEKey() returns a zero. When GetLTEKey() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO        keyno;

TEXT         target[24], idxval[24];

pTEXT        suffix;

/* Key length = 23. Assuming duplicates are allowed, the     *

 * last four bytes are for the suffix.                       */

memset(target, NULL, 24);

scanf("%19s",target);

suffix = target + 20;      /* pointer to the last four bytes */

for (i = 0;i++ < 4;)       /* set suffix to highest possible */

    *suffix++ = C255;      /* value                          */

if (GetLTEKey(keyno,target,idxval))

  printf("\nthe key value >= %.19s is %.19s", target, idxval);

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered.

Note: The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

GetKey(), GetGTEKey(), GetGTKey(), GetLTKey(), ctSETHGH(), ctGETHGH().

GetLTERecord

Read the record with key less than or equal to target.

Short Name

LTEREC()

Type

ISAM function

Declaration

COUNT GetLTERecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetLTERecord() reads the last data record whose key value in keyno is equal to, or less than, the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetLTERecord() is frequently used to start searching a file via an index file that accepts duplicate keys. GetRecord() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

An alternative to GetLTERecord() is LastInSet(), which reads the last data record whose key value matches the significant bytes in a target key; it is not necessary to pad the target when using LastInSet(). The main difference between GetLTERecord() and LastInSet() is that GetLTERecord() does not require any match with the target.

If the associated data file has variable-length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetLTERecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contains the relationship between the index file number and the associated data file.

Return

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

Example

LONG      cust_number;

FILNO     keyno;

pTEXT     recptr;

scanf("%ld",cust_number);

if (GetLTERecord(keyno,&cust_number,recptr))

    printf("\nUnsuccessful search. Code = %d on file %d.", isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

GetGTEKey(), GetRecord(), LastInSet(), TransformKey(), CreateIFile(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetLTEVRecord

Read the variable-length record with key less than or equal to target.

Short Name

LTEVREC()

Type

ISAM function

Declaration

COUNT GetLTEVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetLTEVRecord() is the same as its fixed-length counterpart, GetLTERecord(), except one argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for GetLTERecord() for additional important information.

Return

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

See also

GetGTEVRecord(), GetGTVRecord(), GetLTVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

GetLTKey

Search index file for entry less than target.

Short Name

LTKEY()

Type

Low-Level index file function

Declaration

LONG GetLTKey(FILNO keyno, pVOID target, pVOID idxval) 

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

GetLTKey() searches index file keyno for the last entry that is strictly less than the key value pointed to by target. If such an entry exists, it is copied into the area pointed to by idxval.

Return

If GetLTKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty or the target key value is smaller than all entries in the index), GetLTKey() returns a zero. When GetLTKey() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO        keyno;

TEXT         target[24], idxval[24];

pTEXT        suffix;

/* Key length = 23. Assuming duplicates are allowed, the     *

 * last four bytes are for the suffix.                       */

scanf("%19s",target);

suffix = target + 20;      /* pointer to the last four bytes */

for (i = 0;i++ < 4;)       /* set suffix to highest possible */

    *suffix++ = C255;      /* value                          */

if (GetLTKey(keyno,target,idxval))

     printf("\nthe key value >= %.19s is %.19s", target, idxval);

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered.

Note: The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

GetKey(), GetGTEKey(), GetGTKey(), GetLTEKey()

GetLTRecord

Read the record with key less than target.

Short Name

LTREC()

Type

ISAM function

Declaration

COUNT GetLTRecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetLTRecord() reads the last data record whose key value in keyno is less than, the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetLTRecord() is frequently used to start searching a file via an index file that accepts duplicate keys. GetRecord() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

An alternative to GetLTRecord() is LastInSet(), which reads the last data record whose key value matches the significant bytes in a target key; it is not necessary to pad the target when using LastInSet(). The main difference between GetLTRecord() and LastInSet() is that GetLTRecord() does not require any match with the target.

If the associated data file has variable-length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetLTRecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contains the relationship between the index file number and the associated data file.

Return

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

Example

LONG      cust_number;

FILNO     keyno;

pTEXT     recptr;

scanf("%ld",cust_number);

if (GetLTRecord(keyno,&cust_number,recptr))

    printf("\nUnsuccessful search. Code = %d on file %d.",

           isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

GetGTEKey(), GetRecord(), LastInSet(), TransformKey(), CreateIFile(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetLTVRecord

Read the variable-length record with a key less than target.

Short Name

LTVREC()

Type

ISAM function

Declaration

COUNT GetLTVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetLTVRecord() is the same as its fixed-length counterpart, GetLTRecord(), except one argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the GetLTRecord() function description for additional important information.

Return

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

See also

GetGTEVRecord(), GetGTVRecord(), GetLTRecord(), GetLTEVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

GetORDKey

Return the record offset (recbyt) to the nth offset past the given target.

Short Name

ORDKEY()

Type

Low-Level index file function

Declaration

ctRECPT GetORDKey(FILNO keyno, pVOID target, LONG offset, pVOID idxval)

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

GetORDKey() returns the record offset, recbyt, for the nth active index entry, offset, past the given target for index number keyno. The target must be properly formed as is necessary with any c-tree function that retrieves data using indexes. This function is intended to aid developers programming “list boxes” in a GUI environment.

In V11.8 and later, the GetORDKey() function is supported for partitioned files.

Return

GetORDKey(), if successful, returns the record offset, recbyt, for the nth active index entry, offset, past the given target and the idxval argument contains the index value found at the index location target + offset.

If an error occurs or no active entries are found, GetORDKey() returns zero. When GetORDKey() returns zero, if uerr_cod is non-zero, an error condition was detected; otherwise no active key values were detected. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

The following example contains a duplicate allowed index over customer name. The code prompts the user for a beginning name and the number of active key values to skip. The value recbyt returned by GetORDKey() is the record offset in the data file for the key value found.

Example

FILNO  keyno=4;
LONG   maxbuf=40;

LONG ret_long, recbyt;
TEXT target[maxbuf];   /* target value to start search with */
TEXT idxval1[maxbuf];  /* input buffer for RNGENT function  */
TEXT idxval2[maxbuf];  /* input buffer for RNGENT function  */

printf("\n\tEnter name for GetORDKey:");
memset(target,' ',maxbuf);
gets(target);

TransformKey(4,target);    /* properly form search target */
printf("\n\tEnter offset to find with ORDKEY:");
memset(idxval1,0x0,maxbuf);
gets(idxval1);
ret_long = atol(idxval1);

if (!(recbyt = GetORDKey(keyno,target,ret_long,idxval2)))
    printf("\nError on GetORDKey, error = %d",uerr_cod);
else
    printf("\nSuccessful GetORDKey, recbyt =%ld, idxval2 = %s",recbyt, idxval2);

Limitations

The value of offset must be positive.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

NbrOfKeysInRange(), NbrOfKeyEntries()

GetRecord

Get data record with key equal to target value.

Short Name

EQLREC()

Type

ISAM function

Declaration

COUNT GetRecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetRecord() searches index file number keyno for an entry matching the key value pointed to by target. If an exact match is found, GetRecord() reads the associated data record into the buffer area pointed to by recptr, and this record becomes the current ISAM record. If no match is found or an error occurs, the current ISAM record remains unchanged.

If the associated data file has variable-length records, then only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to GetRecord(). Note that ReReadVRecord() requires you to specify the size of the buffer area so that it can check if sufficient space is available.

Notice that you do not directly identify the data file number involved. The IFIL structures described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Reference Guide contain the correspondence between the index file number (keyno) and the associated data file.

Does not support duplicate allowed (non-unique) indexes if 4-byte record offset is not known. Use GetGTERecord(), or a similar function, with duplicate keys.

Return

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

Example

FILNO    part_idx;
TEXT     part_key[25];

struct invd {
    TEXT     delflg[4];
    LONG     part_no;
    LONG     on_hand;
    LONG     on_order;
    TEXT     part_name[60];
} recbuf;

printf("\nEnter part name: ");
scanf("%24s",part_key);

switch (GetRecord(part_idx,part_key,&recbuf)) {

case NO_ERROR:
    printf("\nParts on order for %s = %ld",
           recbuf.part_name,recbuf.on_order);
    break;

case DLOK_ERR:
    printf("\nCould not get record lock.");
    break;

case INOT_ERR:
    printf("\nPart name not on file.");
    break;

default:
    printf("\nProgramming Error (code = %d file = %d)", isam_err,isam_fil);
}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

Does not support duplicate allowed (non-unique) indexes if 4-byte record offset is not known. Use GetGTERecord(), or a similar function, with duplicate keys.

See also

GetGTERecord(), TransformKey(), CreateIFile(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetSerialNbr

Get current data file sequence number.

Short Name

SERIALNUM()

Type

Low-Level data file function

Declaration

LONG GetSerialNbr(FILNO datno) 

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

GetSerialNbr() returns the current sequence number for data file datno used in ISAM applications using a SRLSEG key segment mode. Use ctGETHGH() to retrieve the high-word portion of an 8-byte sequence number.

When the SRLSEG key segment mode is used in an index, each call to NewData() or NewVData() increments the sequence number in the header of the associated data file. Calls to AddRecord() and AddVRecord() automatically invoke NewData() and NewVData(), respectively.

To manually manage serial numbers, use the OPS_SERIAL_UPD status_word described in the SetOperationState() function description.

Return

GetSerialNbr() returns a long integer containing the current sequence number. If an error occurs (such as data file not in use), GetSerialNbr() returns a zero value. Check uerr_cod for the error code. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

FILNO     datno;

if (OpenCtFile(datno,"MYDATA.DAT",(ctVIRTUAL | ctEXCLUSIVE))){
    printf("\nCould not open data file with error %d", uerr_cod);
    exit(2);
}
printf("\n Last used sequence number for MYDATA is %ld.",
       GetSerialNbr(datno));
exit(0);

Limitations

Serial numbers are not guaranteed to be sequential.

See also

ctGETHGH(), NewData(), NewVData(), AddRecord(), AddVRecord(), SetOperationState and ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide.

GetServerInfo

Listen for server information via TCP/IP.

Short Name

GetServerInfo()

Type

Low-Level function

Declaration

NINT GetServerInfo(pTEXT buffer, NINT bufsiz)

Description

On the client side, GetServerInfo() listens on the default port and stores the broadcast string in buffer. If the default port is not used, change the value for the client by altering the following define in ctcomm.h:

#define ctsrvBROADCAST_PORT  5595

By default, GetServerInfo() times out after 90 seconds. Adjust this timeout value by setting the following define in ctoptn.h or ctree.mak:

#define myWAIT_SEC 90

Return

This routine returns NO_ERROR (0) if it executed properly, -1 if the buffer was smaller than the string it received, or the value of the system-level errno if an error occurred. Check your compiler’s documentation for valid errno values.

Example

TEXT      info_buf[128];
NINT      retval;
pTEXT     wptr;

ctrt_printf("Checking for Broadcast Servers .........\n");

if (retval = GetServerInfo(info_buf, (NINT)sizeof(info_buf))) {
    ctrt_printf("Error getting available servers [%ld] \n",
                (LONG)retval);
}

if ((ctrt_strlen(info_buf) < 1) && !retval) {
    printf("No Broadcasting Servers Available \n");
} else {
    if ((wptr = strchr(info_buf,'|')))
        *wptr = '@';
    if ((wptr = strchr(info_buf,'|')))
        *wptr = '\0';
    ctrt_printf("We will attempt a connection to [%s] on port
               [%s].\n", info_buf, ++wptr);
    *svn = info_buf;
}

See also

• Server Name Broadcast Feature

GetServerInfoXtd

Listen for server information via TCP/IP, Extended Version.

Short Name

GetServerInfoXtd()

Type

Low-Level function

Declaration

NINT GetServerInfoXtd(pTEXT buffer, NINT bufsiz, UCOUNT port, LONG sec)

Description

GetServerInfoXtd() listens for a broadcasting FairCom Server on TCP/IP port port for sec seconds before timing out. The port value should match the TCP/IP port set in the Server BROADCAST_PORT keyword. A negative sec defaults to 90 seconds. If a broadcast is received, up to bufsiz bytes are stored at buffer.

Return

This routine returns NO_ERROR (0) if executed properly, -1 if the buffer was smaller than the string it received, or the value of the system-level errno if an error occurred. Check your compiler’s documentation for valid errno values.

Example

TEXT      info_buf[128];

NINT      retval;

pTEXT     wptr;

UCOUNT    port = myBroadcastPort;

LONG      sec = myBroadcastTimout;

ctrt_printf("Checking for Broadcast Servers .........\n");

if (retval = GetServerInfoXtd(info_buf, (NINT) sizeof(info_buf), port, sec)) {

    ctrt_printf("Error getting available servers [%ld] \n",

                (LONG)retval);

}

if ((ctrt_strlen(info_buf) < 1) && !retval) {

    printf("No Broadcasting Servers Available \n");

} else {

    if ((wptr = strchr(info_buf,'|')))

        *wptr = '@';

    if ((wptr = strchr(info_buf,'|')))

        *wptr = '\0';

    ctrt_printf("We will attempt a connection to [%s] on port

               [%s].\n", info_buf, ++wptr);

    *svn = info_buf;

}

See also

GetServerInfo()

• Server Name Broadcast Feature

GetSuperFileNames

Retrieve superfile member name.

Short Name

GETMNAME()

Type

Low-Level function

Declaration

COUNT GetSuperFileNames(FILNO filno, pTEXT nambuf,

                        VRLEN buflen, COUNT memberNo)

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

GetSuperFileNames() retrieves the superfile member name for member number memberNo in superfile filno. After successful execution, the nambuf array, which is buflen bytes long, contains the superfile member name for member number memberNo.

Return

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

Example

LON   buflen=64

TEXT  nambuf[buflen];   /* superfile member name buffer */

COUNT ret=0;           /* function return           */

FILNO membno;          /* member # for loop control    */

/*list superfile member names for superfile number 5   */

for (membno =1; ret == 0; membno ++)

{

    if (ret=GetSuperFileNames(5,nambuf,buflen, membno))

        printf("\nError on GETMNAME, error = %d decimal",

               ret) ;

    else

        printf("\n%s is member #%d of superfile #5", nambuf, membno);

}

GetSymbolicNames

Retrieve symbolic information about file.

Short Name

GETNAM()

Type

Low-Level function

Declaration

COUNT GetSymbolicNames(FILNO filno, pTEXT nambuf, VRLEN buflen, COUNT mode);

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 s

GetSymbolicNames() accesses items of information relating to file filno. Use mode to specify the type of information to return in nambuf. The following values can be used for mode:

Modes >= 128 do NOT require a valid file number

The ctTM structure is as shown below:

    typedef struct cttm {

        LONG    tm_sec;

        LONG    tm_min;

        LONG    tm_hour;

        LONG    tm_mday;

        LONG    tm_mon;

        LONG    tm_year;

        LONG    tm_wday;

        LONG    tm_yday;

        LONG    tm_isdst;

        } ctTM;

Return

The return value will be NO_ERROR (0) if no error has occurred. The information will be returned in nambuf. Otherwise, an error code will be returned.

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

Example

FILNO filnum;

TEXT  buffer[128];

if (GetSymbolicNames(filnum, buffer, 128L, FILNAM) == NO_ERROR)

    printf("\nFile Name is %s",buffer);

See also

GetCtFileInfo()

GetVRecord

Read the variable-length record with a key equal to target.

Short Name

EQLVREC()

Type

ISAM function

Declaration

COUNT GetVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetVRecord() is the same as its fixed-length counterpart, GetRecord(), except one argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for GetRecord() for additional important information.

Return

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

See also

GetRecord(), GetGTEVRecord(), GetGTVRecord(), GetLTEVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

GetXtdCreateBlock

Retrieves the extended file creation block, XCREblk.

Short Name

GETXCREBLK()

Type

Utility Function

Declaration

NINT GetXtdCreateBlock(FILNO filno, pXCREblk pxcreblk)

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

GetXtdCreateBlock() fills the structure pointed to by pxcreblk with the contents of an XCREblk corresponding to the extended create attributes for filno. Use GetXtdCreateBlock() to retrieve the XCREblk for an existing file so that a file can be created with the same extended create attributes.

Note: It is legitimate to call GetXtdCreateBlock() for files created using the Standard or Extended format. The resulting XCREblk from a call for a Standard format file can be used in a call to an extended create routine, and the result should be a Standard format (V6 compatible) file.

Return

If pxcreblk is NULL, then PNUL_ERR (540) is returned. If filno is not opened, FACS_ERR (26) is returned. If filno corresponds to an index member, KMEM_ERR (23) is returned. Otherwise, the structure is filled in and NO_ERROR (0) is returned.

Limitations

Must be called for each physical file.

See also

SetFileSegments()

GetXtdKeySegmentDef

Retrieves the requested extended key segment definition.

Short Name

GETKSEGDEF()

Type

ISAM data definition

Declaration

NINT GetXtdKeySegmentDef(FILNO filno, NINT segno, pctKSEGDEF pkdef) 

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

GetXtdKeySegmentDef() retrieves (i.e., fills in the elements of a ctKSEGDEF structure for) the requested extended key segment definition to pkdef, except that the kseg_type member of the pkdef structure should be set on input to the type of segment to be retrieved.

For example, to retrieve an ICU Unicode definition, set the kseg_type member to ctKSEG_Type_UNICODE before calling GetXtdKeySegmentDef(). If GetXtdKeySegmentDef() is called with ctKSEGhandle for the filno parameter and the handle value is passed in via the segno parameter (as shown in the third row in the table below), then the kseg_type member of the structure is ignored on input since the handle uniquely identifies the particular definition. On output, the kseg_type member will be set to the type of segment.

One of the main reasons to call GetXtdKeySegmentDef() is to be able to examine the actual locale being used for the ICU collation routines.

The filno and segno values determine which definition is returned, as follows:

Return

If successful, GetXtdKeySegmentDef() returns the handle associated with the definition. GetXtdKeySegmentDef() returns a negative value upon error, where the absolute value of the return value is the error code. The most common errors are shown below. See c-tree Error Codes in the c-tree Reference Guide for a complete listing of valid c-tree error values.

Example

See the API example in “Unicode Support”.

See also

PutXtdKeySegmentDef() (PutXtdKeySegmentDef, PutXtdKeySegmentDef), TransformXtdSegment()

InitCTree

Initialize file structures and index buffer area.

Short Name

INTREE()

Type

Low-Level file function

Declaration

COUNT InitCTree(COUNT bufs, FILNO fils, COUNT sect) 

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

InitCTree() acquires the memory space necessary for the data and index file structures as well as the space for the index file buffers. Finally, it initializes this memory area. Call CloseISAM() or StopUser() to free these resources.

The InitCTree() parameters are defined as follows:

In a single user system, increasing bufs reduces the number of disk accesses necessary to retrieve a key value. The buffers are shared across all index files via a “least recently used” scheme.

In Standalone Multi-user systems, the need to force updates back to the disk implies that local buffering is of little value. Rather, the shared hard disk should be cached in order to achieve global buffering of the index file. In a Standalone Multi-user system, bufs should be set around three, regardless of the number of index files in use.

sect * 128 determines how many bytes are available in each B-Tree node. When an index file is created, the node size is permanent. When an index file is opened, a check is made to be sure that the current node size is at least as large as when the index was created. That is, an index file can be opened if sect has been increased since file was created, but not if it has been reduced. Superfiles must be opened with the exact node size as when they were created.

Originally, the most common value used for sect is four, yielding a node size of 512 bytes. For efficiency, set the sect value to create nodes equal to the page size for the platform. Most common would be 32, yielding a node size of 4K.

Return

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

Example

COUNT     retval;

if (retval = InitCTree(6,7,4))

    printf("\nCould not initialize c-tree: Error %d.", retval);

else {

    printf("\nc-tree initialized.");

    StopUser()

}

See also

CloseISAM(), StopUser(), CreateDataFile(), CreateIndexFile(), CreateIndexMember(),
InitCTreeXtd(), InitISAM()

InitCTreeXtd

Initialize file structures and index buffer area (extended version).

Short Name

INTREEX()

Type

Extended Low-Level file function

Declaration

COUNT InitCTreeXtd(COUNT bufs, FILNO fils, COUNT sect,

                   COUNT dbufs, COUNT userprof, pTEXT userid,

                   pTEXT userword, pTEXT servname)

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

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

bufs and dbufs specify the number of buffers for index and data file I/O respectively. Usually bufs and dbufs have the same value. In a program using index file manipulations with very little data file work, make dbufs smaller to save buffer space. In a Server environment bufs, dbufs, and sect are ignored. They are set by the Server configuration. fils is limited by the FILES setting in the Server’s ctsrvr.cfg.

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.

For more information on user ID’s, user passwords, and server names, review ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) and Client-Side Operation in the c-tree Programmer’s Reference Guide.

Return

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

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

See also

InitCTree(), TransformKey(), GetCtTempFileName(), Begin(), OpenISAM(), CloseISAM()

InitISAM

Initialize file structures and index buffer area.

Short Name

INTISAM()

Type

ISAM function

Declaration

COUNT InitISAM(COUNT bufs, FILNO fils, COUNT sect) 

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

InitISAM() acquires the memory space necessary for the data and index file structures as well as the space for the index file buffers. Finally, it initializes this memory area, and prepares for incremental ISAM creates and opens.

Before any other ISAM functions can be used, InitISAM(), OpenISAM(), or CreateISAM() must be called. Further, these are mutually exclusive; only one of these routines can be called at a time. Once one of these has been called, you must call CloseISAM() before invoking one of these three functions again.

The InitISAM() parameters are defined as follows:

In a single user system, increasing bufs reduces the number of disk accesses necessary to retrieve a key value. The buffers are shared across all the index files via a “least recently used” scheme.

In Standalone Multi-user applications, the need to force updates back to the disk implies that local buffering is of little value. Rather, the shared hard disk should be cached in order to achieve global buffering of the index file. In a Standalone Multi-user application, bufs should be set around three, regardless of the number of index files in use.

sect * 128 determines how many bytes are available in each B‑Tree node. When an index file is created, the node size is fixed permanently. When an index file is opened, a check is made to be sure that the current node size is at least as large as when the index was created. That is, an index file can be opened if sect has been increased since file was created, but not if it has been reduced. Superfiles must be opened with the exact node size as when they were created.

Originally, the most common value used for sect is four, yielding a node size of 512 bytes. For efficiency, set the sect value to create nodes equal to the page size for the platform. Most common would be 32, yielding a node size of 4K.

Return

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

Example

COUNT     retval;

if (retval = InitISAM(6,7,4)) {

     printf("\nCould not initialize c-tree. Error #%d\n",

            retval);

     exit(2);

}

See also

OpenIFile(), CreateIFile(), OpenISAM(), CreateISAM(), InitISAMXtd(), CloseISAM()

InitISAMXtd

Initialize file structures and index buffer area (extended version).

Short Name

INTISAMX()

Type

Extended ISAM function

Declaration

COUNT InitISAMXtd(COUNT bufs, FILNO fils, COUNT sect,

                  COUNT dbufs, COUNT userprof, pTEXT userid,

                  pTEXT userword, pTEXT servname)

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

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

bufs and dbufs specify the number of buffers for index and data file I/O respectively. Usually bufs and dbufs have the same value. In a program using index file manipulations with very little data file work, make dbufs smaller to save buffer space. In a Server environment bufs, dbufs, and sect are ignored. They are set by the Server configuration. fils is limited by the FILES setting in the Server’s ctsrvr.cfg configuration file.

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.

USERPRF_X509 - If this bit is set then the caller is expected to provide a null terminated string containing a trusted certificate in PEM format in the userword argument and the userid is ignored. It is up to the caller to ensure the certificate is trusted which can be done by the TLS handshake. Presenting an untrusted or compromised certificate could allow unknown users to login with admin privileges. The server must be configured to allow x509 Authentication. See x509_AUTHENTICATION with the x509_PATH server keyword.

In database models besides server dll the USERPRF_X509 profile bit has no effect.

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.

For more information on user ID’s, user passwords, and server names, review ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) and Client-Side Operation in the c-tree Programmer’s Reference Guide.

Return

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

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

See also

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

IOPERFORMANCE

Monitor Input/Output of data/index caching and count Low-Level file reads and writes.

Short Name

IOPERFORMANCE()

Type

Low-Level function

Declaration

LONG IOPERFORMANCE(pVOID bufptr)

Description

IOPERFORMANCE() monitors the data and index cache as well as the Low-Level file reads and writes. On return, bufptr points to a structure of 8 unsigned long values, defined as follows:

ULONG     ct_dbrqs;          /* data buffer requests       */

ULONG     ct_dbhit;          /* data buffer hits           */

ULONG     ct_ibrqs;          /* index buffer requests      */

ULONG     ct_ibhit;          /* index buffer hits          */

ULONG     ct_rdops;          /* number of read operations  */

ULONG     ct_rdbyt;          /* bytes read                 */

ULONG     ct_wrops;          /* number of write operations */

ULONG     ct_wrbyt;          /* bytes written              */

Note the element defines used in the example below.

Return

IOPERFORMANCE() always returns a 0 (zero) value indicating NO_ERROR. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

ULONG  ct[8]  /* array of 8 longs for performance value */

IOPERFORMANCE(ct)

printf("\n\n=================================================");

printf("\ndata buffer requests  = %ld",ct[DataBufferRequests]);

printf("\ndata buffer hits      = %ld",ct[DataBufferHits]);

printf("\nindex buffer requests = %ld",

                                      ct[IndexBufferRequests]);
printf("\nindex buffer hits     = %ld",ct[IndexBufferHits]);

printf("\n# of read operations  = %ld",ct[NbrReadOperations]);

printf("\nbytes read            = %ld",ct[NbrBytesRead]);

printf("\n# of write operations = %ld",ct[NbrWriteOperations]);

printf("\nbytes written         = %ld",ct[NbrBytesWritten]);    

printf("\n===================================================");  

See also

IOPERFORMANCEX()

IOPERFORMANCEX

Monitor Input/Output of data/index caching and count Low-Level file reads and writes (Extended version).

Short Name

IOPERFORMANCEX()

Type

Low-Level function

Declaration

LONG IOPERFORMANCEX(pVOID bufptr)

Description

IOPERFORMANCEX() is the extended version of IOPERFORMANCE(). In addition to the eight (8) values reported in IOPERFORMANCE(), IOPERFORMANCEX() reports the following eleven (11) additional values:

IOPERFORMANCE() Values:

IOPERFORMANCEX() Values:

The communication statistics ignore the traffic for the logon/logoff operations. In order to ensure proper statistics on multiple-processor hardware, add the following to the FairCom Server configuration file:

COMPATIBILITY  MULTI_PROCESSOR

IOPERFORMANCEX() accepts an array of ULONG (Unsigned Longs) in which to place the performance data. ctIXPLMT is the size of the array for IOPERFORMANCEX(). ctIOPLMT is the array size for the non-extended version, IOPERFORMANCE(). This array dimension size should be used when working with this function in case the array is increased with a future release.

Return

IOPERFORMANCEX() always returns a 0 (zero) value indicating NO_ERROR. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

ULONG iopx[ctIXPLMT];

IOPERFORMANCEX(iopx);

printf("\n# check points = %ld  time in seconds = %ld\n",

       iopx[NbrCheckPoints], iopx[SystemTimeValue]);

See also

IOPERFORMANCE()

KeyAtPercentile

Find key value located at about the given percentile.

Short Name

FRCKEY()

Type

Low-Level index file function

Declaration

LONG KeyAtPercentile(FILNO keyno, pVOID idxval, COUNT percnt)

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

KeyAtPercentile() finds the key value located, approximately, at the percentile specified by percnt. The key value is copied into the area pointed to by idxval. percnt should be in the range from zero (0) to one-hundred (100).

KeyAtPercentile() is very efficient since it does not traverse all of the key values in order to determine the key value located at the specified percentile. However, KeyAtPercentile() is only approximate because it assumes that the key values are uniformly distributed among all of the b-tree leaf nodes. For more accuracy, use GetORDKey() or NbrOfKeysInRange().

KeyAtPercentile() can be used to support scroll bar positioning, found in many windowing environments, in those cases when the position must be maintained in key sequential order.

See also Record Offsets Under Huge File Support.

Return

If KeyAtPercentile() is successful, it returns the data record position associated with the key value in the index which is located, approximately, at the specified percentile value. If an error occurs or the index is empty, then KeyAtPercentile() returns zero. After a call to KeyAtPercentile() 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 c-tree Error Codes for a complete listing of valid c-tree error values.

Example

FILNO     keyno;

TEXT      idxval[24];

if (KeyAtPercentile(keyno,idxval,75))

    printf("\n value at the 75th percentile is %.23s",idxval);

else if (uerr_cod)

    printf("\n error %d occurred",uerr_cod);

else

    printf("\n the index is empty");

Limitations

Since KeyAtPercentile() is only approximate, it may be necessary in scroll bar applications to ensure that the result of KeyAtPercentile() is consistent with the current location. For example, you may want to detect the direction of the scroll bar motion and ensure that the key value returned is consistent. For more accuracy, use GetORDKey() or NbrOfKeysInRange().

While KeyAtPercentile() is approximate, it is self-consistent. As you increase (decrease) percnt, the associated key values will increase (decrease) in value.

See also

EstimateKeySpan(), GetORDKey(), NbrOfKeysInRange()