ctdbAddToFieldMask

Add the field to field Mask.

Declaration

CTDBRET ctdbDECL ctdbAddToFieldMask(CTHANDLE Handle, NINT FieldNbr)

Description

• Handle [IN] - Record handle
• FieldNbr [IN] - Field number of the field to be add to the list of fields that are exposed

On the first call activates the field Mask. When the field Mask is active only fields in the field Mask can be retrieved, not record write is allowed. It optimizes the client/server communication by reducing the information retrieved from the server.

Returns

Returns CTDBRET_OK if successful, or the c-tree error code on failure.

ctdbClearAllCallback

Clears all callbacks associated with any FairCom DB API handle.

DECLARATION

CTDBRET ctdbClearAllCallback(CTHANDLE Handle);

DESCRIPTION

ctdbClearAllCallback() clears all callbacks associated with a handle. Handle can be a session, database, table or record handle.

RETURN

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* allocate a record handle */

CTHANDLE hRecord = ctdbAllocRecord(hTable);

/* make sure there are no callbacks */

if (ctdbClearAllCallback(hRecord))

    printf("ctdbClearAllCallback failed\n");

SEE ALSO

ctdbClearCallback(), ctdbGetCallback(), ctdbSetCallback()

ctdbClearCallback

Clears a particular callback associated with a FairCom DB API handle.

DECLARATION

CTDBRET ctdbClearCallback(CTHANDLE Handle, CTDB_CALLBACK_TYPE CallBackType);

DESCRIPTION

You can clear a particular callback associated with a handle. Handle can be a session, database, table or record handle. CallBackType is one of the valid callback types.

RETURN

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* allocate a record handle */

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

/* make sure there are no CTDB_ON_TABLE_OPEN callbacks */

if (ctdbClearCallback(hSession, CTDB_ON_TABLE_OPEN))

    printf("ctdbClearCallback failed\n");

SEE ALSO

ctdbClearAllCallback(), ctdbGetCallback(), ctdbSetCallback()

ctdbCurrentTimestamp

Returns the number of microseconds since January 1, 1970 (which is incompatible with all other ctdb DateTime function calls).

Declaration

CTDBRET ctdbDECL ctdbCurrentTimestamp(ULONG8 * pTimestamp)

Description

• ULONG8 pTimestamp unsigned 8-byte integer representing current timestamp as the number of microseconds since January 1, 1970 UTC (excluding leap seconds).

This function relies on the system, and makes no guarantees for accuracy or monotonic behavior.

Returns

Returns NO_ERROR on success.

ctdbExecJsonAction

ctdbExecJsonAction() executes the JSON Action request with the user-defined JSON string and returns the JSON string with the JSON Action response. If the provided buffer is not large enough, error VBSZ_ERR is returned, and the required buffer size is populated in the outputSize parameter.

Declaration

CTDBRET ctdbExecJsonAction(CTHANDLE Handle,const char *input, char *output, size_t *outputSize);

Description

• Handle - Active ctdb Handle.
• input - specifies the JSON string being sent in the request.
• output - specifies the JSON string once it has been returned in the response.
• outputSize - specifies the size of the JSON string that was returned.

For best performance, the caller should avoid providing output buffers that are too small.

Return Values

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

ctdbGetCallback

Retrieves the callback function pointer associate with the callback type.

DECLARATION

ctdbCallbackFunction ctdbGetCallback(CTHANDLE Handle, CTDB_CALLBACK_TYPE CallBackType)

DESCRIPTION

• Handle is a valid FairCom DB API session, database, table or record handle.
• CallBackType is one of the valid callback types.

You can check if a given callback has been registered with a session, database, table or record handle by calling the ctdbGetCallback() function. If a callback function was set, ctdbGetCallback() returns the address of the function. If a particular callback is not set, ctdbGetCallback() returns NULL.

RETURN

Returns the function pointer, or NULL if the callback was not registered.

EXAMPLE

/* allocate a table handle */

CTHANDLE hTable = ctdbAllocTable(hDatabase);

/* make sure CTDB_ON_TABLE_OPEN callback is set */

if (ctdbGetCallback(hTable, CTDB_ON_TABLE_OPEN) == NULL)

if (ctdbSetCallback(hTable, CTDB_ON_TABLE_OPEN, OnTableOpen) != CTDBRET_OK)

printf("ctdbSetCallback failed\n");

SEE ALSO

ctdbClearAllCallback(), ctdbClearCallback(), ctdbSetCallback()

ctdbRemoveFieldMask

Empty and deactivate the field Mask.

Declaration

CTDBRET ctdbDECL ctdbRemoveFieldMask(CTHANDLE Handle)

Description

• Handle [IN] - Record handle

Returns

FairCom DB API return code on error.

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

FairCom DB 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. FairCom DB 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:

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 FairCom DB 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

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

ctdbSetFieldHotAlterCallbackFunction

Set the field hot alter table callback function.

Declaration

CTDBRET ctdbDECL ctdbSetFieldHotAlterCallbackFunction(CTHANDLE Handle, cpTEXT functionName)

Description

FairCom DB now supports passing the names of a shared library and a field conversion function to the hot alter table function. This permits application developers to set a user-defined field conversion function to convert field values from one version of a schema to another version.

We now extend our FairCom DB API API to specify the conversion callback library at a table level and the callback conversion function name at a field level. If the callback library name at table level is not specified, we retrieve the last one used. If no callback library has ever been specified, we return an error.

Returns

ctdbSetFieldHotAlterCallbackFunction() returns CTDBRET_OK on success, or a FairCom DB API API C API error code on failure.

See also

FairCom DB API API Functions for User-Defined Hot Alter Table Field Conversion Callback

ctdbGetTableHotAlterCallbackLib

ctdbSetTableHotAlterCallbackLib

ctdbIsFieldMaskOn

Return if a field Mask has been activated on the record handle.

Declaration

CTBOOL ctdbDECL ctdbIsFieldMaskOn(CTHANDLE Handle)

Description

• Handle [IN] - Record handle

Returns

TRUE if a field mask has been defined (and so it is active) on the record handle.

ctdbSetTableHotAlterCallbackLib

Set the callback library name for hot alter table.

Declaration

CTBOOL ctdbDECL ctdbSetTableHotAlterCallbackLib(CTHANDLE Handle, cpTEXT libName)

Description

FairCom DB now supports passing the names of a shared library and a field conversion function to the hot alter table function. This permits application developers to set a user-defined field conversion function to convert field values from one version of a schema to another version.

We now extend our FairCom DB API API to specify the conversion callback library at a table level and the callback conversion function name at a field level. If the callback library name at table level is not specified, we retrieve the last one used. If no callback library has ever been specified, we return an error.

Returns

ctdbSetTableHotAlterCallbackLib() returns FairCom DB API YES or NO.

See also

FairCom DB API API Functions for User-Defined Hot Alter Table Field Conversion Callback

ctdbSetFieldHotAlterCallbackFunction

ctdbGetTableHotAlterCallbackLib

ctdbSetCallback

Establishes a callback function.

Declaration

CTDBRET ctdbSetCallback(CTHANDLE Handle, CTDB_CALLBACK_TYPE

CallBackType,ctdbCallbackFunction CallBackFunc);

Description

ctdbSetCallback() establishes a new callback function to receive calls for a given callback type. Handle can be any valid FairCom DB API session, database, table or record handle. CallBackType is one of the following callback types from the table below. CallBackFunc is an address to a callback function.

You need to register your callback functions before they are invoked by FairCom DB API. A callback function is registered by calling the ctdbSetCallback() function and passing the appropriate FairCom DB API handle, the callback function type and the address of a function to receive the callback calls.

You can register any of the defined callback functions using the session handle and every time a database, table or record handle is allocated, they will automatically inherit their callbacks from the session handle. Conversely if you register callbacks using a database handle, every time a table or a record handle is allocated they will automatically inherit their callbacks from the database handle. Record handles will also inherit any callbacks registered with the table handle.

Return

See Appendix A for a complete listing of valid c-tree Plus error values.

Example

/* allocate a new session handle */

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

/* set table open callback */

if (ctdbSetCallback(hSession, CTDB_ON_TABLE_OPEN, OnTableOpen) != CTDBRET_OK)

printf("ctdbSetCallback failed\n");

See Also

ctdbClearAllCallback(), ctdbClearCallback(), ctdbGetCallback()

ctdbTableHasCallback

ctdbTableHasCallback () checks if there is at least one c-tree callback defined on the table.

Declaration

CTBOOL ctdbDECL ctdbTableHasCallback(CTHANDLE Handle)

Description

• Handle - an active table handle

Returns

• YES if at least one callback exists.
• NO if no callback is present.