c-treeDB API API for C

Allocating and Releasing Resource Handles

Before any operations can be performed on resources with c-treeDB API, you are required to allocate a resource handle. Resource handles are opaque handles whose contents are not available to the developer. You must use the set of functions provided by c-treeDB API to set and get properties and perform resource operations. Handles allocated with ctdbAllocResource() should only be used with resource related functions.

To allocate a new resource handle you need to call the following functions:

CTHANDLE ctdbDECL ctdbAllocResource(CTHANDLE Handle, ULONG type, ULONG number, pTEXT name);

• Handle is a c-treeDB API table handle.
• type is the resource type.
• number is the resource number.
• name is the resource name.

If you do not know these values in advance, you can set the type and number parameters to zero and name to a NULL pointer or empty string (""). If the resource handle is allocated correctly, ctdbAllocResource() returns a pointer to the new resource handle. If an error occurs while allocating the resource handle, ctdbAllocResource() returns NULL and you should call ctdbGetError(Handle) to retrieve the error code of the error.

Once the resource handle is no longer needed, you must call ctdbFreeResource() to release all system resources used by c-treeDB API Resource processing. To release a resource handle you should invoke the following c-treeDB API function:

CTDBRET ctdbDECL ctdbFreeResource(CTHANDLE resource);

resource is a resource handle allocated by ctdbAllocResource(). ctdbFreeResource() returns CTDBRET_OK on success or a CTDBRET_NOTRESOURCE error if the handle passed to ctdbFreeResource() was not allocated by ctdbAllocResource() or is invalid. Once a resource handle is released by ctdbFreeResource(), the resource handle is invalid should not be used again.

c-treeDB API C API Allocate Resource Example

CTDBRET DisplayAllResources(CTHANDLE hTable)

{

CTDBRET eRet;

CTHANDLE hRes = ctdbAllocResource(hTable, 0, 0, NULL);

/* check if resource was allocated */

if (!hRes)

return ctdbGetError(hTable);

/* get the first resource */

/* note that no resource locks are acquired since we are not changing the resources */

if ((eRet = ctdbFirstResource(hRes, false)) != CTDBRET_OK)

{

ctdbFreeResource(hRes);

return eRet;

}

/* get the other resources */

do

{

/* display resource type, number and name */

printf("Resource type: %u, number: %u", ctdbGetResourceType(hRes), ctdbGetResourceNumber(hRes));

if (ctdbGetResourceName(hRes) != NULL)

printf(", name: \"\"\n", ctdbGetResourceName(hRes));

else

printf(", name: NULL"\n");

}

while ((eRet = ctdbNextResource(hRes, false)) != CTDBRET_OK);

ctdbFreeResource(hRes);

return eRet;

}