NAME

catinfo - configuration and session information interface

DESCRIPTION

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.

STRUCTURE

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.

Automatic Loading of Values

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.

Naming Conventions

The format of node names should[1] adhere to the following conventions:

FUNCTION OVERVIEW

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.

RETURN VALUES

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.

SEE ALSO

cat, caterr, catinfo_foreach, catinfo_get, catinfo_getbypath, catinfo_init, catinfo_loadfrom, catinfo_name, catinfo_newnode, catinfo_set, catinfo_setpath