rciParameters(3)

NAME
rciParameters -- access RCI parameter database.

USAGE
rciParameters (name, write)
  const char *name;
  int write;

ARGUMENTS

name --
    Name of the parameter set.

write --
    Set true if the parameter set is to be writable.

RESTRICTIONS
This routine must be called from the planning level.

DESCRIPTION
The RCI parameter facility provides something akin to environment variables, except that default definitions are stored in a file and sets of parameters are clustered together into sets. Each parameter is a name/value pair, where the value may be an integer, float, identifier, or string. Parameter sets may be used by RCI application programs to specify default operating parameters associated with program operation. Parameter files may be defined in several different places (see below), with multiple definitions resolved using precedence rules.

rciParameters() returns an integer handle giving access to the parameter set defined by name. The handle can be specified for either read or read-write access. Read access means that parameters in the set can be retrieved with the getpar functions (q.v.), whereas read-write access also allows parameters in the set to be declared (or redefined) using the setpar functions (q.v.). Opening a parameter set for write access will always return sucessfully, whereas opening a parameter set for read-only access will return sucessfully only if the parameter set already exists. The parameter set will exist if either (1) it has been predeclared in a parameter file (see below), or (2) the program previously opened the set for write access.

Sets of parameters can be predeclared in a file named .rciparams. Parameters consist of a key and a value, separated by an equal sign (=). The entries in the file are arranged according to the form
   name=<setname1> <key11>=<value11> <key12>=<value12> ...
   name=<setname2> <key21>=<value21> <key22>=<value22> ...
                .                       .
                .                       .

The name of each parameter set (setname), as well as each parameter key, must be an alphanumeric string beginning with an alphabetic character (underscores and dollar signs are also permitted). The keyword name, followed by the parameter set name, introduces a new set. There are four types of parameter values:

integer --
    The usual C integer notation, including octal (denoted by a preceding 0), and hex (denoted by a preceding 0x). A preceding negative sign is permitted.

float --
    The usual C syntax for floating point numbers (must contain a decimal point and/or an exponent to differentiate it from an integer).

identifier --
    A string of alphanumerics (including underscores and dollar signs) that does not begin with a digit.

string --
    A sequence of characters (other than an identifier) delimited by either white space or double quotes (""). Quoted strings obey the usual C escape conventions.

The type of each parameter value is determined automatically by its form.

White space in the parameter file is ignored, except when it is used to delimit a string. The character # is special; it introduces a comment to the end of the line. A # character may be introduced into a string by preceding it with a backslash (. New lines do not play any special role and are treated as white space.

The parameter sets are read in from the .rciparam files when the first call is made to rciParameters(). The system looks for these files first in $RCCL/conf, then in the user's home directory ($HOME), and lastly in the current directory (.). Redefinitions of parameters sets in files searched later (or redefinitions later on in the same file) take precedence over previous definitions. A redefinition of a parameter set completely overwrites the old definition.

DIAGNOSTICS

rciParameters() returns 0 if an attempt is made to open a set read-only and the set does not exist. It returns -1 if an error occurred. Error information is returned on the errorStack (q.v.), and error code values can be obtained with the routine getErrorCode().

Possible error codes are:

EEnviron --
    Environment variable $RCCL is not set.

EMemory --
    Program has run out of memory.

EBadAccess --
    Can't open the system parameter file $RCCL/conf/.rciparams.

ESyntax --
    Syntax error in one of the parameter files.

The routine will abort the program if called from the control level.

SEE ALSO
getpar(3), setpar(3), errorStack(3).

The descriptions of standard parameter sets (such as the parameter set "RCCL" may be found under the headings "<setname>_params(5)". So for instance, see RCCL_params(5).