|
|
|
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:
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.
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.
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 1: DoBatch - Initial Mode
Symbolic Constant |
Explanation |
|---|---|
BAT_DEL |
Delete records. |
BAT_GET |
Retrieve records. |
Table 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. FairCom DB 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. See Treat fixed-length compressed data files consistently. |
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 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 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 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:
See also
|
|
|
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.
