|
Purpose |
Initialises a buffer for subsequent use in buffered fetch operations | |
|
Syntax (CCOWN) |
BF_HANDLE bf_open(short *datarec,int keysize,int count_wanted,int strategy) | |
|
Syntax (CCOWN) |
BF_HANDLE dp4_bf_open(short *datarec,int keysize,int count_wanted,int strategy) | |
|
Parameters |
short *datarec |
Address of record |
|
|
int keysize |
Number of bytes to compare when bf_reset() required |
|
|
int count_wanted |
Number of records for the buffer |
|
|
int strategy |
Processing strategy |
|
Description |
You call this function to initialise a buffer for subsequent buffered fetch operations. It should be noted that all the buffered functions are designed to work even when a buffer cannot be allocated, and that special action is not needed if the allocation fails: in this case the fetch will be done using rec_fetch(). The first parameter is a pointer to the L field of the database record for which buffered fetches are required. The L and TYPENR fields must be correctly filled in. For example, if the record is variable in length you must ensure that the length is the maximum possible for the record. Note that for such records, the underlying block fetches will never return more than one record at a time. However, the bf_xxxx functions work regardless of the number of records retrieved by the underlying block fetches, and if the interactive strategy is selected the buffered fetch functions will build up a cache of records using as much as possible of the buffer. The second parameter is the number of bytes to be used when comparing records for the bf_reset() function. It is normally the total size of the primary key, but may need to be greater if the prime key fields of the table do not precede all the other fields. You may pass 0 if the bf_reset() function is not required, which is usually the case except then bf_fetch() is being used with pick_recoed(). The third parameter is a suggested number of records for the buffer. If 0 is passed, the bf_open() function automatically creates the largest useful buffer possible. The final parameter indicates a strategy to be used. If BF_SEQUENTIAL is passed, the bf_xxxx functions assume that each record returned is processed once. If BF_INTERACTIVE is passed, the bf_xxxx functions do not assume this. The strategy differences are that if BF_INTERACTIVE is passed the default buffer size is twice as large as the largest number of records block fetch can return in one go, whereas for BF_SEQUENTIAL the buffer size is just the largest size. BF_VAR_INTERACTIVE should be passed if the interactive strategy is required for variable length records. Subsequently, whenever more records need to be read into the buffer:
| |
|
Return values |
Returns the address of the buffer or 0 if one cannot be allocated | |
|
Example |
See the example for the cache_find() function | |