c-treeDB API API for C

ctdbSetFieldCallback

Allows setting a callback function on a specific field. The same table can have fields with and without callbacks.

Declaration

CTDBRET ctdbDECL ctdbSetFieldCallback(CTHANDLE Handle, CTDB_FIELD_CALLBACK_TYPE CallBackType, ctdbFldCallbackFunc CallBackFunc);

• Handle is a pCTDBField handle.
• CallbackType is one of the callbacks defined in the CTDB_FIELD_CALLBACK_TYPE enum (see Callback Types below).
• CallBackFunc is a pointer to the callback function.

Description

It can be very powerful to have callback support at the time of retrieving or setting field information/content. This allows a typical use of callbacks, data conversion, to be performed at field access time instead of when reading/writing the entire buffer, with the benefit of converting only the field actually accessed.

The prototype for the callback is:

CTDBRET callbackfnc(CTHANDLE Handle, pVOID buffer, pVRLEN size, CTDB_FIELD_METATYPE rtype);

• Handle will be set to the pCTDBDATA for the field to be accessed
• buffer:

  the destination buffer for CTDB_FIELD_GET

  the source buffer for CTDB_FIELD_SET (may be different in case of t_string, t_fstring, t_vstring, at this time these rtypes are not implemented)

  pointer to a CTBOOL to be set for CTDB_FIELD_ISNULL

  pointer to CTDBTYPE to be set for CTDB_FIELD_GET_TYPE

  pointer to VRLEN to be set for CTDB_FIELD_GET_LENGTH

• size: pointer to a VRLEN containing the buffer size in input to be set in output to contain the "used" length
• rtype: data type metadata of the buffer.

Metatypes

c-treeDB API implemented a series of ctdbGetFieldAs and ctdbSetFieldAs functions that allow the programmer to get/set the field using a datatype (As*) different from the field data type. c-treeDB API performs the necessary conversion between the wanted data type and the field data type. To do this, it virtually grouped the field types in "metatypes": for each metatype there is an internal function _ctdbGet*Field() that extracts the information from the record buffer into memory passed into the function. The same concept applies to the Set functions. The callbacks are implemented in the _ctdbGet*Field() function because this allows the callback writer to focus on how to extract the data in the buffer into the exact field type it maps to, not the data type requested by the application.

The defined metatypes are:

CTDB_FIELD_METATYPE	Field Type	Type of *Buffer
t_invalid	N/A	N/A
t_bool	CT_BOOL	CTBOOL
t_signed	CT_CHAR CT_INT2 CT_INT4 CT_MONEY	CTSIGNED
t_unsigned	CT_CHARU CT_INT2U CT_INT4U CT_DATE CT_TIME	CTUNSIGNED
t_fstring [set only]	CT_ARRAY CT_FSTRING CT_F2STRING CT_F4STRING	NOT YET IMPLEMENTED
t_vstring [set only]	CT_STRING CT_PSTRING CT_2STRING CT_4STRING	NOT YET IMPLEMENTED
t_string [get only]	CT_ARRAY CT_FSTRING CT_F2STRING CT_F4STRING CT_STRING CT_PSTRING CT_2STRING CT_4STRING	CTSTRING
t_bigint	CT_BIGINT	CTBIGINT
t_ubigint	CT_UBIGINT	CTUBIGINT
t_currency	CT_CURRENCY	CTCURRENCY
t_number	CT_NUMBER	CTNUMBER
t_float	CT_SFLOAT CT_DFLOAT CT_EFLOAT CT_TIMES	CTFLOAT

If the CTDB_FIELD_GET_TYPE callback is in place for the field, the field type used within the various ctdbGetFieldAs* (as well as Set*) functions is determined by the value set by this callback.

Example

Suppose your buffer contains a 12-byte string representing a datetime formatted as YYMMDDHHMMSS and you want to represent it as a CT_DATE field. The application calls ctdbGetFieldAsString(), which calls the CTDB_FIELD_GET callback function requiring a t_unsigned, so the only conversion you need to think about for the field is from "string" to CTDATE and then store it in "buffer" that is a CTSIGNED pointer.

Then c-treeDB API will take care of converting CTDATE into a properly formatted string as requested by the ctdbGetFieldAsString() original call. It would have been possible to interface directly to the callbacks from the ctdbGetFieldAs* functions, however the number of conversion cases to be handled in the callback would have grown exponentially.

Note: The field callbacks must be set on the fields they apply to after opening the table. There is no need for a mechanism to propagate them to the records.

Callback Types

CTDB_FIELD_GET_TYPE: Called by ctdbGetFieldType and ctdbGetFieldProperty to retrieve the field type. This is useful if as part of the callback logic the field type does not match the one in the DODA structure.

CTDB_FIELD_GET_LENGTH: Called by ctdbGetFieldLength and ctdbGetFieldProperty to retrieve the field (defined) length. This is useful if as part of the callback logic the field len does not match the one in the DODA structure.

CTDB_FIELD_GET: Called by internal _ctdbGet*Field() function (see description later).

CTDB_FIELD_SET: Called by internal _ctdbSet*Field() function (see description later).

CTDB_FIELD_ISNULL: Called by ctdbIsNullField() to check if the field is NULL. When the callback is in place, ctdbIsNullField returns what was set by the callback.

CTDB_FIELD_CLEAR: Called by ctdbClearFiled() to set the field value to NULL. When the callback is in place, the callback it is responsible for the record buffer handling.

Return Values

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful operation.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.