This function first creates a KeyMap by reading the values from a specified text file (argument " def" ). This text files specifies the complete list of all allowed config parameters and their default values. The KeyMap is then locked by setting its MapLocked attribute to a true value. A GRP group is then obtained from the environment using the specified parameter (argument " param" ). The config settings thus obtained are stored in the KeyMap. An error is reported if the user-supplied group refers to any config parameters that were not read earlier from the default file.

Both the defaults file and the user-supplied configuration may contain several sets of " alternate" configuration parameter values, and the set to use can be specified by the caller via the supplied " nested" keymap. For instance, if a basic configuration contains keys " par1" and " par2" , the user could supply two alternate sets of values for these keys by prepending each key name with the strings " 850" and " 450" (say). Thus, the user could supply values for any or all of: " par1" , " par2" , " 450.par1" , " 450.par2" , " 850.par1" , " 850.par2" . Note, values supplied without any prefix take priority over values supplied with a prefix.

The " nested" keymap supplied by the caller serves two functions: 1) it defines the known alternatives, and 2) it specifies which of the alternatives is to be used. Each key in the supplied " nested" keymap should be the name of an allowed alternative. In the above example, a KeyMap containing keys " 850" and " 450" could be supplied. No error is reported if the user-supplied configuration fails to provide values for one or more of the alternatives. The value associated with each key in the " nested" keymap should be an integer - the alternative to be used should have a non-zero value, and all other should be zero.

So first, the configuration parameters specified by the supplied defaults file are examined. Any parameter that starts with the name of the selected alternative (i.e. the key within " nested" that has an associated value of 1) has the name of the alternative removed (but only if no value has been supplied for the parameter without an alternative prefix - thus " filt=10" takes priority of " 450.filt=20" ). Any parameter that starts with the name of any of the other alternatives is simply removed from the configuration. Thus, using the above example, if " nested" contains two entries - one with key " 850" and value " 1" , and the other with key " 450" and value " 0" - the " 850.par1" and " 850.par2" entries in the defaults file would be renamed as " par1" and " par2" (so long as no values already existed for " par1" and " par2" ), and the " 450.par1" and " 450.par2" entries would be deleted.

Next, the same process is applied to the user-supplied configuration obtained via the specified environment parameter.

Finally, the values in the user-supplied configuration are used to replace those in the defaults file.

The benefits of using this function are that 1) the user gets to know if they mis-spell a config parameter name, and 2) the default parameter values can be defined in a single place, rather than hard-wiring them into application code at each place where the config parameter is used.

AstKeyMap $\ast$kpg1Config( const char $\ast$param, const char $\ast$def, AstKeyMap $\ast$nested, int null, int $\ast$status )

param = const char $\ast$ (Given)

def = const char $\ast$ (Given)

nested = AstKeyMap $\ast$ (Given)

null = int (Given)

status = int $\ast$ (Given & Returned)

A pointer to the AST KeyMap, or NULL if an error occurrs.

• The KeyError attribute is set non-zero in the returned KeyMap so that an error will be reported by astMapGet$<$X$>$ if the requested key does not exist in the KeyMap.