\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciParameters}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rciParameters}}
-- access RCI parameter database.

}
\manSection{USAGE}
\cverbatim
rciParameters (name, write)
  const char *name;
  int write; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt name} --}
Name of the parameter set.
\manItem{{\tt write} --}
Set true if the parameter set is to be writable.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{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 {\it 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.

{\tt rciParameters()} returns an integer handle giving access to the
parameter set defined by {\tt 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 {\tt getpar} functions
(q.v.), whereas read-write access also allows parameters in the set
to be declared
(or redefined) using the {\tt 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 {\tt .rciparams}.
Parameters consist of a {\it key} and a {\it value}, separated
by an equal sign ({\tt =}).
The entries in the file are arranged according to the form
\cverbatim
   name=<setname1> <key11>=<value11> <key12>=<value12> ...
   name=<setname2> <key21>=<value21> <key22>=<value22> ...
                .                       .
                .                       .
@endcverbatim
The name of each parameter set ({\tt 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 
{\tt name}, followed by the parameter set name, introduces a new set.
There are four types of parameter values:
\manItem{{\tt integer} --}
The usual C integer notation, including octal (denoted by a preceding {\tt 0}),
and hex (denoted by a preceding {\tt 0x}). A preceding negative sign
is permitted.
\manItem{{\tt float} --}
The usual C syntax for floating point numbers (must contain a decimal
point and/or an exponent to differentiate it from an integer).
\manItem{{\tt identifier} --}
A string of alphanumerics (including underscores and dollar signs) that
does not begin with a digit.
\manItem{{\tt string} --}
A sequence of characters (other than an identifier) 
delimited by either white space or double quotes ({\tt ""}).
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 {\tt \#} is special; it introduces a
comment to the end of the line. A {\tt \#} character may be introduced
into a string by preceding it with a backslash ({\tt \\}).
New lines do not play any special role
and are treated as white space.

The parameter
sets are read in from the {\tt .rciparam} files 
when the first call is made to {\tt rciParameters()}. The system
looks for these files first in {\filefont \$RCCL/conf}, then in the user's
home directory ({\tt \$HOME}), and lastly in the current directory
({\tt .}). 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.

\manSection{DIAGNOSTICS}

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

Possible error codes are:
\manItem{{\tt EEnviron} --}
Environment variable {\tt \$RCCL} is not set.
\manItem{{\tt EMemory} --}
Program has run out of memory.
\manItem{{\tt EBadAccess} --}
Can't open the system parameter file {\filefont \$RCCL/conf/.rciparams}.
\manItem{{\tt ESyntax} --}
Syntax error in one of the parameter files.

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

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt getpar(3)}, {\tt setpar(3)}, {\tt errorStack(3)}.

The descriptions of standard parameter sets (such as the parameter set
{\TT RCCL} may be found under the headings {\TT <setname>_params(5)}. So
for instance, see {\tt RCCL_params(5)}.
\manEnd
\end
