Working with Resources
It can be advantageous at times to attach auxiliary information to a particular table that does not conform to the record structure of that table. For example, features such as versioning or special flags relating to the status of the table. Generally, this information is not repeated in every record of the table. You could create a special record, with a special key value, that you do not process as you do your regular records. Ultimately, however, this forces exceptional handling routines for this special case and can impose a heavy maintenance cost on the life cycle of the application.
FairCom DB provides a unique feature created for exactly this purpose: FairCom DB Resources. Resources are special variable-length records stored within your data file, whether you use fixed or variable-length records. A set of FairCom DB API functions provide access to create, update, and delete these resource records. These records do not require a key in an index, therefore your program does not access them via routine data handling functions.
Resources provide critical support for many advanced FairCom DB features. FairCom-defined resources allow seamless functionality of many of the Incremental ISAM features, conditional index support, FairCom DB API, FairCom DB SQL, c-tree ODBC Drivers, and the r-tree Report Engine. These resources continue to be important as new technology is added. Resources are added either automatically by some FairCom DB features or manually by the developer. The use of resources requires the RESOURCES define in the FairCom DB library, which is the default.
This section focuses on user defined resources added by you, the developer, and provides important background information on the use of resources.
Types of Resources
There are three general types of resources that can be attached to a file.
User-defined resources
Information that you wish to store in the table, such as a version number, or an infrequently accessed counter. Use resources to store information associated with a table that varies from the type of information stored repetitively in the data records.
FairCom-defined resources
There is a variety of information that, under certain circumstances, FairCom wishes to store in the table. This can be information relating to IFIL structures, alternate collating sequences, special characters for key padding, and so forth. Usually you do not access this information directly. It is available to a variety of FairCom DB API functions that use it.
Third-party resources
As other developers create utilities integrating with FairCom DB, FairCom assigns resource identifiers when necessary.
Resource Identification
Within a given data file, a Resource is identified by three elements.
| Resource Element | Data Type |
|---|---|
| Type | unsigned long integer |
| Number | unsigned long integer |
| Name | null terminated string |
Within each file, you can identify a Resource by its unique combination of Type and Number, or by its Name.
Note: The Resource Name is not guaranteed to be unique.
Resource Type
Resource Type gathers Resources into related groups. Resource Types in the range of 1 to 127 are reserved for use by FairCom. These are special Resources used by the FairCom DB, r-tree Report Generator, the d-tree application builder, FairCom DB API, and FairCom DB SQL. Resource Types in the range of 128 to 65536 are also reserved and are explicitly assigned to third party developers by FairCom. Resource Types numbered 65537 and above are available to any developer and can be assigned as desired.
Resource Number
There are no restrictions on assigning Resource Numbers. They separate various Resources within a given Resource Type. When adding a Resource to a file, FairCom DB can assign the next available value for this Resource Type in the referenced table.
Resource Name
You can use the Resource Name as a way to access Resources in a file instead of using the Type and Number. This can make application code more readable if you use a symbolic name rather than a pair of numbers. If you are adding a number of Resources to a data file over a period of time you may not know what Resource Number has been used, particularly as FairCom DB can automatically assign the next available Resource Number. Access via Resource Name is simpler than keeping track of what Resource Number has been assigned.
However, use caution when assigning Resource Names. FairCom DB cannot guarantee that each Resource Name is unique within a table. It is possible to add a duplicated Resource name to a table.
Resource Names are optional. They are not required for a Resource. The Resource Name is a null terminated character string of any length. FairCom recommends you do not make them too long. Resource Names starting with the character sequence "FC!" are reserved for use by FairCom. Resource Names starting with with the character sequence "RD!" are reserved for Resources assigned to third party developers by FairCom.