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