DoBatchXtd

Perform operations on a group of records (extended version).

Short Name

BATSETX()

Type

ISAM function

Declaration

ctCONV COUNT ctDECL DoBatchXtd(COUNT filno, 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, but 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
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
BAT_INP_RAW: Turns off the conversion of record images, key values, and record positions passed to a batch function

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 c-tree Plus 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.

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.

Return

See “c-tree Plus Error Codes” in the c-tree Plus Programmer’s Reference Guide for a complete listing of valid c-tree Plus error values.

Example

The following example shows a strategy for using batch 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);