Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic

Adding New Resources

When adding a Resource to a table, a special variable-length record is written to the table, containing the information from the Resource Data Block. This is done even if a data file contains fixed-length records. Every Resource is identified by a unique combination of a Resource Type and a Resource Number. The Resource Number can optionally be assigned by FairCom DB when calling ctdbAddResource(). In addition, each Resource can be identified by a Resource Name. A Resource Name is not guaranteed to be unique.

The following steps are required to add a new resource to a table:

  1. Allocate a resource handle by calling ctdbAllocResource() and pass a unique resource type and number and an optional resource name.
  2. Call ctdbAddResource() to add the new resource, passing the resource data and the length of the data.
  3. Release the resource handle by calling ctdbFreeResource().

To add a new resource you must call the following function:

CTDBRET ctdbDECL ctdbAddResource(CTHANDLE resource, pVOID data, VRLEN size);

  • resource is a resource handle allocated by ctdbAllocResource().
  • data is any collection of data you wish to store as a Resource. This can be a character string, a structure, or any variable type.
  • size indicates the number of bytes occupied by the data parameter value.

The Resource Type must be a value greater than 65536. 0 through 65536 are reserved for FairCom use. If the Resource Number is a value of CTDB_ASSIGN_RESOURCE_NUMBER (0xffffffff), FairCom DB assigns to this Resource the next available Resource Number for this Resource Type in the specified data file. The assigned number can be retrieved by calling ctdbGetResourceNumber() before the resource handle is released. The Resource Name is optional. FairCom DB does not guarantee unique Resource Names. Names starting with the character sequences "FC!" or "RD!", are reserved for FairCom use.

c-treeDB API C API Add Resource Example

/* return CTDB_ASSIGN_RESOURCE_NUMBER on error */

ULONG AddMyResource(CTHANDLE Handle, ULONG type, pTEXT name, pVOID data, VRLEN size)



CTHANDLE hRes = ctdbAllocResource(Handle, type, number, name);


/* check if resource handle was allocated */

if (!hRes)


printf("ctdbAllocResource failed with error %d\n", ctdbGetError(Handle));

return number;


/* Add the resource */

if ((eRet = ctdbAddResource(hRes, data, size)) != CTDBRET_OK)


printf("ctdbAddResource failed with error %d\n", eRet);


return eRet;


/* retrieve the assigned resource number */

number = ctdbGetResourceNumber(hRes);

/* release the resource handle */


return number;