This object provides methods to read and write configuration files providing other objects with system and user-configurable data through a well-defined interface. Two files are processed: a system configuration file and a user configuration file, which overrides the system file if there are any conflicts.
To learn more about the UMSConfig object, see:
For introductory information, see Configuration Objects.
Alias1: Property1 "Data1" Property2 "Data2" *NEXT: Property1 "Data1" Property2 "Data2" Alias2: Property1 "Data1"
AliasN is a string of non-whitespace characters, which does not begin with an * (asterisk). An alias must be on the first line of the file. PropertyN is a string of non-whitespace characters, not containing a quotation mark or a double quotation mark, and preceded by at least one space or tab. DataN is a string of characters surrounded by quotation marks. An * followed by any other characters is a reserved alias, which is not valid as the first in the file.
Each alias is assumed to be a series of words separated by a . (period). The search process attempts to find the longest match, first, in the user configuration file and, second, in the system configuration file. If an exact match does not exist, the rightmost word and the associated period are stripped and a match is looked for in the user and the system file. This process is continued until either a match is found or the alias is exhausted.
The actual location of the system and user files are highly modifiable. By default, the system file is found in the $UMSDIR/defaults directory, while the user file is in $HOME/.UMS_config. The two environment variables, $UMS_system_config and $UMS_user_config, control where the UMSConfig object actually searches for the system and user files, respectively. When the variable is not set, the default file is read. If the variable is set to the NULL string (""), that file is ignored in the search process. Otherwise, the value of the variable is read as the file that the UMSConfig object searches.
To avoid name collision on defines, integer values have been captured as enumerated lists. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object are:
enum ReturnCode {
Success,
Failure
};
When called before seek_alias or after a seek_alias has returned NULL, this method returns Failure. When called after a successful seek_alias, a check is made for the next *NEXT clause after the current set of properties. If not found, Failure is returned, and the state of the UMSConfig object is as if seek_alias had returned NULL. When the next *NEXT clause is found, Success is returned, and the property list after it becomes the current set of properties.
When called before seek_alias or after a seek_alias has returned NULL, this method returns NULL. When called after a successful seek_alias, the passed-in property name string is compared to all Property names following the Alias but before the next Alias or *NEXT clause. If the property is found, the data on the same line after that property, without the quotation marks, is returned. If not, NULL is returned.
| in string property | This string is checked against the current property set to determine if there is a property name match. |
The return value is a pointer to the string that is the associated value for the string property in the original call. The pointer points to static data and should not be freed. The return value is NULL if there is no match for the property name in the current set of properties.
When called before seek_alias or after a seek_alias has returned NULL, this method returns NULL. When called after a successful seek_alias, the passed in value string is compared to the string value paired with each successive property name. If there is a value match, the corresponding property name is returned. If not, NULL is returned.
| in string value | This string is checked against the current property set to determine if there is a value match. |
The return value is a pointer to the string that is the property name associated with the value. The pointer points to static data and should not be freed. The return value is NULL if there is no value match in the current set of properties.
The alias is searched for in the system files and user files as described in the previous section on the configuration files. If a match is successfully found, the set of properties just after the alias in the file becomes the current set of properties. If there is no match, the current set of properties becomes NULL.
| in string alias | This is the string that is searched for in the configuration database. |
The return value is a pointer to the string that is the longest match for the requested alias. The pointer points to static data and should not be freed. The return value is NULL if there is no match for the alias.
When called before seek_alias or after a seek_alias returns a NULL value, this method returns a NULL value. When called after a successful seek_alias on seek_next, the property name string in that is returned. Subsequent calls to get_next_property_name returns the next property name in the list until there are no more names in the list. In this case, the call returns NULL.
The return value is a pointer to a string containing a property name. The pointer points to static data and should not be freed. The string value is replaced on subsequent calls to get_next_property_name.
For introductory information, see Configuration Objects.