Product Documentation

c-treeDB API for C++ - Developers Guide

Previous Topic

Next Topic

Reading Resources

Essentially, there are four different methods to read resources from a c-tree Plus 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 method CTResource::First() and then read the remaining resources by calling method CTResource::Next(). To read the first resource in a table, call the following CTResource method:

CTBOOL CTResource::First(CTBOOL lock = NO) const;

CTResource::First() retrieve the first resource stored in a table.

  • lock is used to indicate if the resource should be locked, if it is found.

CTResource::First() returns YES if the resource was found or NO if no resource was found. If an error is detected, CTResource::First() throws a CTException exception.

To read all other resources of a table call the following CTResource method:

CTBOOL CTResource::Next(CTBOOL lock = NO) const;

CTResource::Next() retrieves the next resource stored in a table, after a successful call to CTResource::First() is made.

  • lock is used to indicate if the resource should be locked, if it is found.

CTResource::Next() returns YES if the resource was found or NO if no resource was found. If an error is detected, CTResource::First() throws a CTException exception.

Example

void DisplayAllResources(const CTTable& hTable)

{

CTResource* hRes = new CTResource(hTable);

try

{

// get the first resource

if (hRes->First())

{

do

{

// display resource type, number and name

printf("Resource type: %u, number: %u",

hRes->GetType(), hRes->GetNumber());

}

while (hRes->Next());

}

}

catch (CTException &err)

{

printf("Error %d - %s\n", err.GetErrorCode(), err.GetErrorMsg());

}

delete hRes;

}

Read all c-tree Plus Resources Given a Starting Point from a Table

Read all resources starting from a given resource type and number by calling method CTResource::Next(). Start by instantiating a resource object setting the resource type and a resource number and then call CTResource::Next(). 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

void DisplayResources(const CTTable& hTable, ULONG type)

{

CTResource* hRes = new CTResource(hTable, type, 0);

try

{

while (hRes->Next())

{

printf("Resource type: %u, number: %u",

hRes->GetType(), hRes->GetNumber());

}

}

catch (CTException &err)

{

printf("Error %d - %s\n", err.GetErrorCode(), err.GetErrorMsg());

}

delete hRes;

}

Read a Specific Plus Resources from a Table

Read a specific resource by providing exact resource type and number by calling CTResource::Find():

CTBOOL Find(ULONG type, ULONG number, CTBOOL lock = NO) const;

Locates and retrieves a resource in a table based on type and number.

  • type is a value of the resource type.
  • number is the value of the resource number to be located.
  • lock is used to indicate if the resource should be locked, if it is found.

CTResource::Find() returns YES if the resource was found or NO if this particular resource was not found. If an error occurs, CTResource::Find() throws a CTException exception.

Example

// display a particular resource

void DisplayResource(const CTTable& hTable, ULONG type, ULONG number)

{

CTResource* hRes = new CTResource(hTable);

try

{

if (hRes->Find(type, number))

{

printf("Resource type: %u, number: %u, name: %s\n",

hRes->GetType(), hRes->GetNumber(),

hRes->GetName().c_str());

}

else

printf("Resource %d,%d not found\n", type, number);

}

catch (CTException &err)

{

printf("Error %d - %s\n", err.GetErrorCode(), err.GetErrorMsg());

}

delete hRes;

}

Read a c-tree Plus Resources by Name from a Table

Read a resource by providing its name by calling CTResource::Find():

CTBOOL CTResource::Find(const CTString& name, CTBOOL lock = NO) const;

CTResource::Find() locates and retrieves a resource by name. c-tree Plus cannot guarantee unique resource names.

  • name is the resource name being located.
  • lock should indicate if the resource should locked, if it is found.

CTResource::Find() returns YES if the resource is located or NO if no resource is located. If errors are detected a CTException exception object is thrown.

Example

// display a particular resource by name

void DisplayResource(const CTTable& hTable, const CTString& name)

{

CTResource* hRes = new CTResource(hTable);

try

{

if (hRes->Find(type, name))

{

printf("Resource type: %u, number: %u, name: %s\n",

hRes->GetType(), hRes->GetNumber(),

hRes->GetName().c_str());

}

else

printf("Resource %s not found\n", name.c_str());

}

catch (CTException &err)

{

printf("Error %d - %s\n", err.GetErrorCode(), err.GetErrorMsg());

}

delete hRes;

}

TOCIndex