FairCom DB API for C

ctdbAddResource

Add a new resource to a table.

DECLARATION

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

DESCRIPTION

ctdbAddResource() add a new resource to a table. 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 uses 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 during the call to ctdbAddResource(). In addition, each Resource can be identified by a Resource Name. The Resource Name is not guaranteed to be unique.

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 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. Names starting with "FC!" or "RD!", are reserved for FairCom use.

Resource is a handle allocated by ctdbAllocResource(). Data is any collection of data that you wish to store as a Resource. It can be a character string, a structure, or any variable type. Size indicates the number of bytes occupied by data.

RETURN

ctdbAddResource() returns CTDBRET_OK on success.

EXAMPLE

/* return CTDB_ASSIGN_RESOURCE_NUMBER on error */

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

{

ULONG number = CTDB_ASSIGN_RESOURCE_NUMBER;

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

CTDBRET eRet;

/* 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);

ctdbFreeResource(hRes);

return eRet;

}

/* retrieve the assigned resource number */

number = ctdbGetResourceNumber(hRes);

/* release the resource handle */

ctdbFreeResource(hRes);

return number;

}