Epicsparamconf

EPICS Config Parameters API

Author: Michael Davidsaver <[email protected]> Date: June 2010

Purpose

Proposal for 3.15 series

Replace the API in envDefs.h with a more general purpose startup config.

• New parameters can be created at runtime by applications outside of Base (ie EDM).
• Provide a specification for a configuration mechanism which can be shared by all EPICS implimentations.
• Values will be taken from configuration file(s) in addition to the nvironment.
• Supports types: String, Int32, Double, and InetAddr (IPv4).
• Transparent handling of parameter arrays.

API

Types

enum paramType {
    paramTypeInvalid,
    paramTypeString,
    paramTypeInt32,
    paramTypeDouble,
    paramTypeInetAddr
};

Creation

int
paramArrayCreate(const char* name, paramType tp, epicsUInt32 maxelem, char sep, epicsUInt32 opt);

#define paramCreate(name,tp,opt) paramArrayCreate(name,tp,1,NULL,opt)

Creates a new parameter with the given value type. If number of elements is >1 and a separator string is not given then the default separator (OS dependent) is used.

The bit mask 'opt' defines the following bits.

bit #
0	Include environment variable in search path
1	Store value in environment variable
2	Don't strip leading and trailing whitespace
3	Allow the value to be modified/reread (use carefully)
4	Debug print when searching

RETURN

Code
0	Ok
-1	parameter name already exists
-2	Invalid arguments (ie nelem==0)
-3	Insufficient memory

Setting

int
paramArraySetString(const char* name, epicsUInt32 nelem, const char* const* val, epicsUInt32 opt)
/* 3 more for other types */

#define paramSetString(name, val, opt) paramArraySetString(name, 1, &(val), opt)
/* 3 more for other types */

Sets the value of an already created parameter. A value of NULL will clear the parameter value/default.

The bit mask 'opt' defines the following bits.

bit #

bit #
0	Set default. Overwrite the default value instead of the final value.
3	Allow the value to be modified/reread (use carefully)

RETURN

Code
0	Ok
-1	parameter name does not exist

Getting

extern const void* paramNone;
extern const void* paramConvertFail;
extern const void* paramNotReal;

INLINE epicsBoolean
paramValidValue(const void* V)
{
  switch(V) {
  case NULL:
  case paramNone:
  case paramConvertFail:
  case paramNotReal:
    return epicsFalse;
  default:
    return epicsTrue;
  }
}

const char* const*
paramArrayGetString(const char* name, epicsUInt32 *nelem, epicsUInt32 opt);
/* 3 more for other types */

INLINE const char*
paramGetString(const char* name, epicsUInt32 opt)
{
  epicsUInt32 N;
  const char* const* V=paramArrayGetString(name, 1, opt);
  if (!paramValidValue((const void*)V)) return (const char*)V;
  else return *V;
}
/* 3 more for other types */

Gets the value of an already created parameter

Note: Type-safe Getters will also be provided (ie paramArrayGetDouble())

Note: Type paramTypeString returns C type const char* const*.

The bit mask 'opt' defines the following bits.

bit #
3	Allow the value to be modified/reread (use carefully)
4	Debug print when searching

RETURN

Code
paramNone	Value not found
paramNotReal	Parameter name does not exist
paramConvertFail	Value could not be converted to requested type
NULL	Zero length array (nelems also set to 0)
others	Value pointer (dependent of type)

Misc

paramType
paramGetType(const char* name);

Get type of parameter or paramTypeInvalid if parameter does not exist.

epicsUInt32
paramGetNElem(const char* name);

Get number of entries or 0 if parameter does not exist (use paramGetType() to distinguish between a 0 length array and an invalid name).

char
paramGetSep(const char* name);

Get seperator string or NULL if parameter does not exist.

void
paramVisitAll(void *arg, void (*fnptr)(void*, const char* name));

Get a callback for each parameter.

void
paramShowAll(int verbose);

Print parameter info to standard out. Argument controls verbosity (larger -> more detail).

Values

All values are stored as strings, but may be requested as any type.

Parameters can have the special value paramNone. This is distinct from a zero length array. When created all parameters initially have paramNone as a default value.

Value Reread

The value of a parameter is determined when its value is retrieved with paramArrayGet() and stored for future use. Unless the reread option is given further calls to paramArrayGet() will return the same value. If the reread option is given then paramArrayGet() will start a new search and store the (possible different) value for future use.

If a parameter is ever to be reread then the reread option must be given when the parameter is created.

Note: Rereading a parameter invalidates all value pointers previously returned.

Search Path

Value may be found in the following locations. The first value found will be used.

1. Current value
2. Environment
3. Files (OS dependent)
4. Default value

The file search path is defined by the environment variable (EPICS_CONF_PATH). The default value is set in CONFIG_ENV at compile time. Since this parameter is read before the first file is searched it can not be specified in a file.

Entries in the search path may use arbitrary environment variables (macLib syntax).

Default UNIX-like search path

1. ./epics.conf
2. $HOME/epics.conf
3. $EPICS_BASE/epics.conf
4. /etc/epics.conf

Default Windows search path

1. .\epics.conf
2. $USERPROFILE\epics.conf
3. $EPICS_BASE\epics.conf
4. $ALLUSERSPROFILE\epics.conf

On windows xp

USERPROFILE=C:\Documents and Settings\username
ALLUSERSPROFILE=C:\Documents and Settings\All Users

On windows vista/7

USERPROFILE=C:\Users\username
ALLUSERSPROFILE=C:\ProgramData

Default VxWorks and RTEMS search path

None

Config File Syntax

Files specifying parameter values shall have lines of the following format. Lines may be seperated by one of the valid EOL combinations (cr, lf, cr+lf, lf+cr).

Blank lines '^\s*$'

Ignored

Comments '^\s*#.*$'

Ignored

key value pairs '^\s*[^\s=]+\s*=.*$'

When parsing files key names can contain any non-whitespace charactor except '='. However, keys being stored in the environment must also be valid environment variable names.

INI style section headers '\s*\[ [^\] ]+\]\s*$'

Reserved for future use. Parsing stops when the first section header is found.