DoBatch

Perform operations on a group of records.

Short Name

BATSET()

Type

ISAM function.

Declaration

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

              VRLEN bufsiz, UCOUNT mode)

Description

DoBatch() attempts to perform a specified function on a group of records with keys matching a partial key value. filno specifies the index file used to retrieve the related records. bufptr is 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.

Normal batch operations require at least two calls to DoBatch(). The first call specifies the action to be taken with the minimum mode of BAT_GET or BAT_DEL. The last call will have a mode of BAT_CAN, as explained below.

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, even if not all records have been processed through additional DoBatch() calls, call DoBatch() with a mode of BAT_CAN. This closes the batch, frees all locks, and allows another batch. In some cases, this last call may get a BTNO_ERR (426), signifying there is no batch active. Ignore this error, since DoBatch() may close the batch automatically. However, 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 F-1: DoBatch - Initial Mode

Table F-2: DoBatch - Modifiers to Initial Mode

Table F-3: DoBatch - Continuing Mode

Table F-4: DoBatch - Finishing Mode

Return

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

Example

COUNT    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 */

See also

Please refer to Chapter 9 “c-tree Plus Features” of the c-tree Plus Programmer’s Guide for a detailed explanation of batch operations.