FairCom ISAM for C

Batch Parameters

The parameters for DoBatch() are:

• filno: the index file number to search,
• request: a pointer to a Partial Key Request structure, as defined later, defining the set of records,
• bufptr: a pointer to a buffer region into which the group of related records will be retrieved, if specified,
• mode: a value that specifies the type of action to be taken, together with a number of options.

DoBatchXtd() provides additional batch functionality. This function takes the same parameters as DoBatch except that the mode parameter is a ULONG instead of a UCOUNT. The function prototype is shown below:

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

Partial Key Request Structure

One of the parameters that is passed to DoBatch() is the Partial Key Request structure, PKEYREQ. This structure is used to specify which set to perform the batch operation on, and to return some statistics on that set. The PKEYREQ typedef 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;

When you call DoBatch() you pass a pointer to a PKEYREQ structure. The only fields that must be initialized are: target, containing the portion of a properly formed key to match, and siglen, specifying the significant number of bytes in the key. All keys in the appropriate index matching the first siglen bytes of target are processed.

After DoBatch() has been called, check the values in the PKEYREQ structure for the results. btotal tells how many records match the partial key target. If locks were requested on the records, bavail contains the number of records locked successfully. breturn specifies the number of records that fit in the buffer region.

It may be necessary to make a series of DoBatch() calls to process a batch. The first call specifies the batch and returns information on the number of records in the batch. When reading the records in the batch into the buffer area, if the buffer is not large enough to hold all of the records, make additional calls to process the rest of the records. Finally, make a last call to close or cancel the batch, in preparation for the next call.

Multiple Batches

Multiple batches can be active at the same time. To do this, it is necessary to call ChangeBatch() before calling DoBatch(). For more about using multiple batches, see ChangeBatch.