FairCom DB API for C

Field Mask Support Added to FairCom DB API

In V11.6.1 and later, FairCom DB API introduces a new concept used to optimize client/server communication by retrieving only significant record portions - fields - instead of the entire record.

This feature requires a way to specify which of the record's fields are significant and will be accessed. When retrieving a record, FairCom DB API attempts, when possible, to retrieve only the portion that will be accessed. This reduces the number of bytes transmitted. In the case of batches, it increases the number of records retrieved in a single round-trip with a single batch call.

To achieve this objective, we implemented the concept of a "field mask." A field mask defines which are the significant fields. It is activated when the first field is added to the mask. Once active ctdbWriteRecord and ctdbDeleteRecord fail. The field mask cannot be changed when a batch is active. Only the fields specified in the field mask can be accessed using the ctdbGetFieldAs* functions.

New functions:

• A field mask is activated and populated by calling ctdbAddToFieldMask() (ctdbAddToFieldMask, ctdbAddToFieldMask).
• A field mask is deactivated and emptied by calling ctdbRemoveFieldMask() (ctdbRemoveFieldMask, ctdbRemoveFieldMask).
• Check if a field mask is active with ctdbIsFieldMaskOn() (ctdbIsFieldMaskOn, ctdbIsFieldMaskOn).

Batch column filtering for advanced record retrieval

Using the recently introduced FairCom DB API field mask support, it is now possible to filter columns in batch operations.

In ISAM, set the fldmask member of the PKEYREQ2 structure to be used as a "request" for the BATSETX call, using the BAT_EXTENSIONS mode. The fldmask must point to an array of ULONG sorted in ascending order containing the field number (DODA position) composing the partial record. It is also necessary to set the nfields member to indicate how many entries belong to the fldmask array.