FairCom ISAM for C

Batch Read Operations

Several options are provided for reading a batched group of records.

Batch Read in Physical Order

A batch record read in physical order is performed by calling DoBatchXtd() with a mode of BAT_PHYS, specifying a request block comprised of 5 LONG integers. The first three values are the standard btotal, bavail and breturn from the PKEYREQ structure. The last two values are the high-order and low-order four-byte record position. 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). Subsequent DoBatchXtd() calls continue to return records in physical order until the logical end of the data file is reached (i.e., no more records remain in physical order).

Note: The next record position is returned for informational purposes. It is not used on a subsequent call (BAT_NXT) to retrieve additional records. The server maintains the starting point for the next batch retrieval internally.

Batch Read in Key Decreasing Order

A batch record read can be performed in key decreasing order by calling DoBatchXtd() with a mode of BAT_LKEY. Such a call returns records having a key value less or equal to the specified key value.

Batch Read with Index Range Definition

A batch record read can be performed under control of an index range definition by following these steps:

1. Call AllocateRange() to establish the range criteria.
2. Call DoBatchXtd() with a mode of BAT_RNGE.

When the BAT_RNGE mode is specified, the batch call behaves as when using the BAT_PKEY mode except that the records selected satisfy the range criteria established by the call to AllocateRange(). The siglen and target members of the partial key request (PKEYREQ) structure are ignored when the BAT_RNGE mode is specified.

Additional DoBatchXtd() Options

When using a batch read for the purpose of reading blocks of records to pass to a batch insert call, the following batch read modes may be useful to include in the batch read call:

• BAT_RET_BLK: Return a contiguous block of records as if they had been lifted directly from data file including VHDR structure for variable-length records. For batch reads, this mode can only be used with the BAT_PHYS mode. This mode is designed to return blocks of records in an appropriate format for a batch insert operation.

  Batch inserts using BAT_RET_BLK record organization should be marginally faster than BAT_RET_REC record organization when the target file has associated keys, and even better when it has no keys as the data records are written with one write operation when BAT_RET_BLK is in use. By comparison, BAT_RET_REC returns record images preceded by their 4 or 8 byte record position and 4-byte length which must be stripped before writing the records to the target file.

• BAT_RET_RAW: In heterogeneous client/server implementations, turns off the conversion of record images, key values and record positions returned by a batch retrieval call. This may prove especially useful with calls to retrieve a batch intended to be inserted into another file with BAT_INS.
• BAT_LOK_ONE: An alternative locking strategy: only locks the record during the record read; original locking strategy keeps locks on during entire batch processing.
• BAT_LOK_BLK: Converts BAT_LOK_RED and BAT_LOK_WRT to blocking read and write locks, respectively.