F.96 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, 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 or BTST_ERR 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.

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
Symbolic Constant	Explanation
BAT_DEL	Delete records.
BAT_GET	Retrieve records.

Table F-2: DoBatch - Modifiers to Initial Mode
Symbolic Constant	Explanation
BAT_COMPLETE	DoBatch returns a successful completion value only if ALL matching records are successfully locked. You must also specify either BAT_LOK_RED or BAT_LOK_WRT.
BAT_GKEY	Process records that have a greater than or equal key match with the value in the PKEYREQ structure.
BAT_LOK_KEEP	Use on the first call to DoBatch to keep all locks after BAT_CAN or BAT_COMPLETE is sent.
BAT_KEYS	Process records that have a key match with one of the complete key values listed in the PKEYREQ structure. To supply input key values, view the PKEYREQ structure as an array of three longs followed by a TEXT buffer. Element 0 indicates the number of keys being passed in. Elements 1 and 2 are reserved for output values. Beginning at element 3, list the actual key values consecutively in the text buffer.
BAT_LOK_RED	Place a read lock on each record that matches the Partial Key Request.
BAT_LOK_WRT	Place a write lock on each record that matches the Partial Key Request.
BAT_PKEY	Process records that have a partial key match with the value in the PKEYREQ structure.
BAT_RET_REC	Place the data records in the buffer pointed to by bufptr.
BAT_RET_KEY	Place the keys of the matching records in the buffer pointed to by bufptr. The numeric segments of keys returned to bufptr are untransformed, i.e., in the native numeric format. c-tree Plus stores all index entries in HIGH_LOW order regardless of the data ordering of the underlying CPU. The data file record offset, recbyt, precedes each key value in the buffer.
BAT_RET_POS	Place only the record positions in the buffer pointed to by bufptr.
BAT_RET_FIX	Operates in the same manner as BAT_RET_REC except that only the fixed length portion of a variable length data record is returned. If BAT_RET_FIX is used for a fixed length data file the results will be the same as using BAT_RET_REC. When BAT_RET_FIX is called for a variable length file, it returns information in the same manner as BAT_RET_REC called for a variable length file except that only the fixed length portion is returned.
BAT_RPOS	Process records specified in the list of record positions listed in the PKEYREQ structure (the record positions could have been obtained using BAT_RET_POS). To supply record positions view the PKEYREQ as an array of longs. Element 0 indicates the number of record positions being passed in. Elements 1 and 2 are reserved for output values. At element 3 begin the actual record position values.
BAT_VERIFY	Verify that the keys in the index match the values in the key fields of the record.

Table F-3: DoBatch - Continuing Mode
Symbolic Constant	Explanation
BAT_NXT	Use this in a second and subsequent call to DoBatch to process the next group of matching records if they all could not fit in the buffer on the first call.

Table F-4: DoBatch - Finishing Mode
Symbolic Constant	Explanation
BAT_CAN	Used in the final call to cancel processing of the remaining records of a batch and free all locks.

RETURN


Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful processing of the batch call. If BAT_COMPLETE was specified, all of the records were locked successfully.
42	DLOK_ERR	If BAT_COMPLETE was specified.
101	INOT_ERR	No match for target key value found.
421	BTFL_ERR	Filter not supported yet. You have tried to access a feature that has not been implemented yet. The most likely cause would be an invalid value in the mode parameter.
422	BTFN_ERR	Other functions not supported yet. You have tried to access a feature that has not been implemented yet. The most likely cause would be an invalid value in the mode parameter.
423	BTIC_ERR	Batch incomplete. BAT_COMPLETE specified in mode.
424	BTAD_ERR	Add list error. This is an internal processing error, possibly the result of a memory overwrite.
425	BTIP_ERR	Batch already in progress. You are trying to start a new batch before you have completed the previous one. Complete the previous batch with DoBatch with a mode of BAT_CAN before starting a new batch.
426	BTNO_ERR	No batch active.
427	BTST_ERR	Status info already returned. You have tried two consecutive DoBatch calls requesting status info (you did not specify either BAT_RET_REC or BAT_RET_POS) without an intervening call with BAT_CAN.
428	BTMT_ERR	No more info. You made a call with a mode of BAT_NXT, but all of the records have been accessed.
429	BTBZ_ERR	bufsiz is too small for a record from this file.
430	BTRQ_ERR	Request is empty. NULL request pointer.

See Appendix A "c-tree Plus Error Codes" of the c-tree Plus Programmer's Reference Guide 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 */