catinfo - configuration and session information interface
The catinfo is an interface that allows sessions runtime access to configuration data
and other session-specific information.
There is a process-global information tree, commonly referred to as the catinfo tree, where information can be stored and retrieved through the catinfo
interface. Data can be loaded from an external source, but any changes made
will be in the memory of the current process only.
An entry in an info tree has the format .name1.name2. ... .nameN
. The '.' (dot) is the node separator and the single '.' corresponds to the
root of the info tree.
A path starting with a ``.'' is referred to as an absolute path. There can be a maximum of one entry in the tree that corresponds to an
absolute path.
A relative path is a path that does not start with a ``.''. There can be several entries
that match a relative path, depending on the prefix (i.e. the position in
the tree).
Relative names are the atomic components that make up a path.
name1
, name2
, ..., name3
above are relative names. Relative names can contain printable ASCII
characters except ``.'' characters. Letters can be either upper or lower
case but all comparisons are case-insensitive, hence ``ORBITAL'',
``Orbital'', and ``orbital'' are considered equal.
There is a distinction between nodes and values. Nodes might be internal or leaves in the tree and cannot contain any
data. Values are always leaves.
Values can be read automatically from files (UNIX and Windows NT)
directories (UNIX) or the registry (Windows NT). This is accomplished by
registering a node as linked to external configuration information using
the catinfo_loadfrom() function.
The format of node names should[1] adhere to the following conventions:
-
Variable names will be case insensitive. Within the catinfo structure, the
names will be lower case.
-
Whitespace is allowed in variable names. Multiple whitespaces are allowed,
but will be compressed into a single space.
-
Spaces at dots (``.'') are removed.
-
Spaces at the beginning or the end of a name are removed.
-
(Windows NT) Dots in names are to be converted to underscores ``
_
''.
- catinfo_foreach
-
Traverse a subtree in the info tree and apply a supplied callback function
to each node and value in the subtree. All subtrees in the info tree can be
traversed.
- catinfo_get
-
Retrieve a value from the info tree.
- catinfo_getbypath
-
Perform a lookup using an explicit path. The functionality of this function
is a combination of catinfo_get() and catinfo_setpath().
- catinfo_init
-
Initialize the info tree.
- catinfo_loadfrom
-
Inform the catinfo interface of the location of configuration data. On
UNIX, this will be files; on Windows NT, this will be the registry.
- catinfo_name
-
Convert a name to catinfo format, that is, all lowercase characters and
with dot ``.'' characters converted to underscore ``_'' characters.
- catinfo_newnode
-
Create a new node in the info tree.
- catinfo_set
-
Add or delete values from the catinfo tree.
- catinfo_setpath
-
Set the search path to be used when searching for values in the info tree.
All functions that return integers return a negative value on error. The
generic error codes are described in caterr.
For other functions, the return values are given in the corresponding
function documentation.
cat, caterr,
catinfo_foreach, catinfo_get, catinfo_getbypath,
catinfo_init, catinfo_loadfrom, catinfo_name,
catinfo_newnode, catinfo_set, catinfo_setpath