NAME

CQCC::Parm - Class used to manage class parameters


CLASS DESCRIPTION

This class manages all class parameters and facilitates setting them from configuration files, environment variables, command line options, and other sources.

The class methods are not invoked by callers directly but through a series of convenience functions which handle Parm objects through a set of hash lists.

DefineParm() is called by the owning class to describe the parameter and its limitations and sources.

SetConfigParm() , SetCmdParm() , and SetIntParm() are functions which will remember a ``preference'' for the parameter's value on their own separate lists. This allows parameter settings to be made before the parameter has been defined.

GetParm() ``evaluates'' the parameter by seeing if there is a source for a non-default value that fits the boundary conditions (multiple available sources are evaluated in priority order); if not it will return the default value if one is defined. Once the parameter has been evaluated its value is stored so that later accesses to it will not require re-evaluation.

ForceParm() can be used to force overrides by clearing the current setting, storing an Internal parameter value (highest priority) and reevaluating the parameter.

SUPPORT POLICY: See TriggerCQCC.pm for the Rational Support Policy.


METHODS

ClassTest(@args)
This method will create samples of each type of parameter then evaluate them, to ensure that range checking and other aspects of evaluation works.

DefineParm(keys)
This function creates a new parm object and stores it into the Parm array to control how GetParm will handle evaluating it. It does NOT evaluate the function, in order to allow other events to set preferred values before it is needed.

EvalParms()
This function will force evaluation of all parms - otherwise parms are evaluated only as needed in ``lazy evaluation'' mode. PrintParms will effectively accomplish the same thing.

ForceParm($name,$value)
This internal function forces parameter values as internal overrides. It will clear any existing value, set its own value as an internal parameter, and call GetParm to reevaluate the parameter. This will ensure all normal checks are still performed but the provided value will override all other sources.

GetParm($name)
This function will lookup the Parm for ``$name''. If it already has been evaluated then its value will be returned immediately. Otherwise its definition will be checked for acceptable sources and value ranges. Once evaluated the value will be stored for future use and is returned to the original caller.

GetParmHandle($name)
This internal method gets a reference to the value cell for the named parameter. It is only intended for use by GUI widgets that are interacting with the parameter.

GetParmNameList($src)
This function will lookup the Parms that have the requested source and return a list of names that match. If no source is provided then the entire Parm list is returned.

new CQCC::Parm()
This method defines a new parm and add it to the parm hash list. Nothing is evaluated at definition time but the information is used to control the later evaluation when the variable is needed.

A Parm can be preset from one or more sources including, in order of priority, environment variables (SRC_EV=>1), command line options (SRC_CMD=>1), configuration settings (SRC_CFG=>1) or internal calls (SRC_INT=>1). Which sources are valid depends on the definition of the parameter. This allows complete control over which sources are allowed for each parameter. An additional source (SRC_CACHE) is supported but the parameters must also have an additional source such as SRC_INT.

A Parm can have a DEFAULT value set when it is defined and can have rudimentary value checking done by setting RANGE_MIN, RANGE_MAX or RANGE_LIST which will apply their respective tests when the Parm is being evaluated for the first time by GetParm().

Each Parm is assumed to have a message catalog entry that describes its use in appropriate detail for end user consumption.

The new() method is not called directly but is invoked by the convenience function DefineParm().

Errors:

(1) Parm with same name already exists.

(2) Need to add error checks for complete enough information

ParmDefined($name, { $source })
This function will lookup the Parm for ``$name'' and return 1 if it is found, 0 if it doesn't. This permits a ClassInit function to see if it has already been called.

The optional $source argument also checks if a given data source provides a value, i.e. if ``CONFIG'', the method will only return 1 if the parameter exists and SetConfigParm has already been called for the parameter to set a configuration value. Permitted values include ``CONFIG'', ``CMDLINE'', and ``ENV''.

ParmParse($string)
This function will parse a string of the form ``parmname=value'' that has been used to store the parameter in a file or read back a value from the user. The complement function to generate this string is ParmString($name);

ParmString($name)
This function will return a string of the form ``parmname=value'' that can be used to store the parameter into a file or display it for debugging purposes. The complement function to read back the value is ParseParm($string).

PrintParms( {source} )
This function will print the evaluated values of all defined parms. If the optional source argument is provided, only parameters that use that source will be shown, i.e. ``SRC_EV'' will only show parameters that are accessible through environment variables.

If a list result is expected, it will return the list of printable values rather than printing them directly. =back

SetConfigParm($name,$value)
This function is used by administrators in configuration files to set preferences for class parameters.

It stores a parameter value ``preference'' that will be used only if it is higher priority than other sources. It may be called before DefineParm() has defined the parameter but must be called before GetParm() has a chance to evaluate other options.

SetCmdParm($name,$value)
This function is used by the trigger main loop as it evaluates its command line arguments of the form -p name,value to allow the command line to override other sources.

It stores a parameter value ``preference'' that will be used only if it is higher priority than other sources. It may be called before DefineParm() has defined the parameter but must be called before GetParm() has a chance to evaluate other options.

SetIntParm($name,$value)
This function is used by the integration to force the override of other sources in some rare cases, such as allowing -test mode to force debugging to be on.

It stores a parameter value ``preference'' that will be used only if it is higher priority than other sources. It may be called before DefineParm() has defined the parameter but must be called before GetParm() has a chance to evaluate other options.

SetParmDefaults(keys)
Convenience function to set defaults for DefineParm calls for a set of parameters. Should be used before to set defaults and after to reset to () to avoid side effects in other areas. Not required to use DefineParm.