|
|
|
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.
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.
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.
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() FairCom DB 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.
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;
}
