Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

Resource Functions

Five functions are provided to manage Resources (see c-tree Function Descriptions for declarations);

  • AddCtResource(): Add Resource to file.
  • UpdateCtResource(): Update Resource.
  • DeleteCtResource(): Delete Resource from file.
  • GetCtResource(): Retrieve Resource from file.
  • EnableCtResource(): Enable Resources for a file.

Each of these functions has as a parameter a pointer to a Resource Data Block. This is an area you create containing the description of the Resource, as follows:

Byte Offset

Data Type

Resource Elements

0 - 3

Unsigned long integer.

Resource Type

4 - 7

Unsigned long integer.

Resource Number

8 - m

null terminated character string.

Resource Name

m+1 - n

Any collection of data types desired.

Resource Information

The Resource Information can be any collection of data fields that you desire. You are not limited to a null terminated character string.

AddCtResource

Add a new Resource to a file. The combination of Resource Type and Resource Number must be unique to this file, or an error is returned. c-tree does not check to see if the Resource Name is in use yet. As mentioned, Resource Name is optional.

When passed a Resource Number of 0xffffffffL, c-tree assigns the next available Number for this Resource Type in this file. The assigned Number is placed in the appropriate field in the Resource Data Block.

When adding a Resource to a file, a special variable-length record is written to the file, containing the information from the Resource Data Block. This is done even if a data file uses fixed-length records. Now the information is available to any user accessing the file.

DeleteCtResource

Delete a resource from a given file. Since Resource Names are not guaranteed to be unique, the proper Resource Number and Type are required to delete a Resource. If the Resource record was locked via UpdateCtResource(), the lock is released.

UpdateCtResource

Update the information in a Resource. The Resource Type and Number is used to select a Resource, and then the new Resource Data Block is placed in the file, replacing the prior information.

Note: UpdateCtResource() automatically tries for a low-level record lock on the Resource record, unless the record is already locked via GetCtResource(). If the record cannot be locked, an error value is returned. The lock is automatically released when UpdateCtResource() is finished.

GetCtResource

Retrieves a Resource. The value returned by the function is the record address of the Resource record. The Resource Data Block is written to a buffer that you specify.

When retrieving a Resource, use one of the following resource modes, resmode, values:

  • RES_FIRST: Finds the Resource with the lowest available Type and Number.
  • RES_LENGTH: This mode must be OR-ed with a Resource retrieval mode such as RES_FIRST or RES_NAME. This mode returns three 4-byte integers: resource type, resource number, and resource length.
  • RES_NAME: Finds the first Resource with a matching Name (c-tree cannot guarantee unique Resource Names). resptr points to a buffer containing the Name for the search.
  • RES_NEXT: This mode allows the next physical resource to be retrieved from the specified file. Seed this mode with a resource type and resource number to receive the next greater resource.
  • RES_POS: Reads the Resource at a given record address obtained in a prior call to UpdateCtResource(). resptr points to a long integer with the record address to be read.
  • RES_TYPE: Finds the Resource with the matching Type and lowest available Number. resptr points to the resource Type.
  • RES_TYPNUM: Finds the Resource with the matching Type and Number. resptr points to a resource Type followed by a resource Number.

In addition you can OR the resmode with the value RES_LOCK. This makes GetCtResource() ask for a low-level exclusive lock on the matching Resource record. This lock is released by UpdateCtResource() or DeleteCtResource() for the same Resource, or with LockCtData(). It is important to note that Resource locks are NOT released by explicit or implicit calls to LockISAM().

EnableCtResource

Enable Resources in a file created with Resources disabled. First open the file with an ctEXCLUSIVE file mode, then call EnableCtResource().

TOCIndex