prg_preference_value_set()
Abstract
Sets the value of a preference and ensures that the attribute appears when a user selects Edit Preferences.
Syntax
prg_preference_value_set (attr_type, group_name, attr_name, description_string, options, value_ptr)
| Argument | Type | Description |
|---|---|---|
attr_type |
PrgT_Env_Attr_Type |
the preference's data type. [This value must be a defined preference type, or an error will occur. The available types are listed in Symbolic Constants. |
group_name |
const char* |
group name of the attribute to set: Standard, FLS, GUI, etc. |
attr_name |
const char* |
name of the attribute to set. |
description_string |
const char* |
description of the attribute. This argument can be an empty string (“”). |
options |
int |
flag to specify binary options. This argument is reserved for future use. Currently the only defined value is PRGC_PREFERENCE_OPT_NONE. |
value_ptr |
void* |
pointer referencing the value to assign to attr_name. This value must be of the same type as specified by attr_type, and the pointer should be cast to reference the correct data type. |
Return Type
PrgT_Compcode
Completion code indicating whether the operation completed successfully. This code can be compared to the two symbolic constants PrgC_Compcode_Success and PrgC_Compcode_Failure.
Header
prg_env.h
Example
sprintf (attr_name, "engs_dir");
if ((status = prg_preference_value_set (PrgC_Env_Attr_String,
ENGSC_ATTR_GROUP, attr_name,
ENGSC_ATTR_DIR_DESC, PRGC_PREFERENCE_OPT_NONE, attr_value)) ==
PrgC_Compcode_Failure)
{
/* Could not set the engs_dir environment variable. */
printf("\nCould not set %s preference\n\n", attr_name);
}
Details
This function allows the setting and/or modifying of preferences.
This procedure allows you to
- Modify the existing systems attributes (example: mod_dirs, opnet_dir, num_errors, etc.)
- Add new attributes. If you create an attribute that does not exist, this results in a new attribute.
- Set your own attributes that were defined in the preferences file (.prefs).
If the attribute is of type PrgT_List, the list for value_ptr must be allocated and initialized with a function such as prg_list_create() or prg_list_init() prior to calling this function.
Purpose
Provides a mechanism to create and set preferences from the current process.
This function differs from prg_env_attr_value_set() in that prg_preference_value_set() ensures that any attribute it sets (and creates) will subsequently appear when a user selects Edit Preferences; prg_env_attr_value_set() does not ensure this behavior.
Errors
- Program Abort: Segmentation violation due to an invalid value pointer, pointer to an insufficient amount of memory, or invalid address for
group_name,attr_name,description_string, orvalue_ptr)
Reference
- use prg_env_attr_value_get() to obtain a preference's value
- use prg_env_attr_value_set() to change the value of a preference
- use prg_preference_value_get() to obtain a preference's value (and ensure that it appears in the Edit Preferences dialog box)