Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic

Reading Resources

Essentially, there are four different methods to read resources from a FairCom DB table. Read all table resources, read all resources starting past a resource type and number, read a specific resource by specifying the Resource Type and Resource Number, or read a resource by specifying a Resource Name. Described below are examples of each method.

Read all c-tree Plus Resources from a Table

Read all resource starting with the first resource by calling ctdbFirstResource() and then read the remaining resources by calling ctdbNextResource(). To read the first resource in a table, call the following function:

CTDBRET ctdbDECL ctdbFirstResource(CTHANDLE resource, CTBOOL lock);

ctdbFirstResource() retrieves the first resource stored in a table.

  • resource is a handle allocated with a call to ctdbAllocHandle().
  • lock indicates if the resource should be locked, if it is found.

ctdbFirstResource() returns CTDBRET_OK on success. If the table contains no resources, ctdbFirstResource() returns RNOT_ERR (408).

To read the rest of the resources from the table, call the following function:

CTDBRET ctdbDECL ctdbNextResource(CTHANDLE resource, CTBOOL lock);

ctdbNextResource() retrieves the next resource stored in a table, after a successful call to ctdbFirstResource() is made.

  • resource is a handle allocated with a call to ctdbAllocHandle().
  • lock indicates if the resource should be locked, if it is found.

ctdbNextResource() returns CTDBRET_OK on success. After the last resource has been retrieved from the table, ctdbNextResource() returns RNOT_ERR (408).

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;

}

Read all FairCom DB Resources Given a Starting Point from a Table

Read all resources from a table starting from a given resource type and number by calling ctdbNextResource(). Start by allocating a resource handle, set the resource type and a resource number and then call ctdbNextResource(). In this case a resource is found if its type is greater or equal to the specified type and its number is greater than the specified number.

Example

/* read resources with type >= type and number > 0 */

CTDBRET DisplayResources(CTHANDLE hTable, ULONG type)

{

CTDBRET eRet;

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

/* check if resource was allocated */

if (!hRes)

return ctdbGetError(hTable);

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

while ((eRet = ctdbNextResource(hRes)) == CTDBRET_OK)

{

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

}

ctdbFreeResource(hRes);

return eRet;

}

Read a Specific FairCom DB Resource from a Table

Read a specific resource by providing the exact resource type and number by calling ctdbFindResource():

CTDBRET ctdbDECL ctdbFindResource(CTHANDLE resource, ULONG type, ULONG number, CTBOOL lock);

ctdbFindResource() locates and retrieves a resource from a table based on the Resource Type and Resource Number.

  • resource is a resource handle allocated by ctdbAllocResource().
  • type is a value of the resource type.
  • number is the value of the resource number to be located.
  • lock indicates if the resource should be locked, if it is found.

ctdbFindResource() returns CTDBRET_OK on success. If the specified resource is not in the table, ctdbFindResource() returns RNOT_ERR (408).

Example

/* display a particular resource */

CTDBRET DisplayResource(CTHANDLE hTable, ULONG type, ULONG number)

{

CTDBRET eRet;

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

/* check if resource was allocated */

if (!hRes)

return ctdbGetError(hTable);

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

if ((eRet = ctdbFindResource(hRes, type, number, NO)) == CTDBRET_OK)

{

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

if (ctdbGetResourceName(hRes) != NULL)

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

else

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

}

ctdbFreeResource(hRes);

return eRet;

}

Read a FairCom DB Resources by Name from a Table

Read a resource by providing its name with the ctdbFindResourceByName() c-treeDB API C API call.

CTDBRET ctdbDECL ctdbFindResourceByName(CTHANDLE resource, pTEXT name, CTBOOL lock);

ctdbFindResourceByName() locates and retrieves a resource by name. FairCom DB cannot guarantee unique resource names.

  • resource is a handle allocated with ctdbAllocHandle().
  • name is the resource name being located.
  • lock indicates if the resource should locked, if it is found.

ctdbFindResourceByName() returns CTDBRET_OK on success. If there are no resources for the table with the specified name, ctdbFindResourceByName() returns RNOT_ERR (408).

Example


/* display a particular resource */

CTDBRET DisplayResource(CTHANDLE hTable, pTEXT name)

{

CTDBRET eRet;

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

/* check if resource was allocated */

if (!hRes)

return ctdbGetError(hTable);

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

if ((eRet = ctdbFindResourceByName(hRes, name, NO)) == CTDBRET_OK)

{

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

if (ctdbGetResourceName(hRes) != NULL)

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

else

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

}

ctdbFreeResource(hRes);

return eRet;

}

TOCIndex