prg_env_attr_value_set()
Abstract
Assigns the value of a preference.
Syntax
prg_env_attr_value_set (attr_name, value)
| Argument | Type | Description |
|---|---|---|
attr_name |
const char* |
name of the attribute-of-interest. This value must be a defined preference, or an error will occur. |
value_ptr |
void* |
new value for the specified attribute. This argument can accept an integer, a double, a character string, or a pointer to a variable of type PrgT_List. The logic within this function determines the type of the passed argument based on the type of the attribute being assigned, and alters its attribute assignment technique accordingly. |
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
mod_dirs_dir_add (const char * directory_str)
{
FIN (mod_dirs_dir_add ())
/* Note this is a list, not a list-pointer. */
Prg_List * moddir_lptr;
moddir_lptr = prg_list_create ();
/* Populate the list with the model directories environment */
/* attribute (mod_dirs). Each element of the list will be a string */
/* representing a directory.*/
prg_env_attr_value_get (PrgC_Env_Attr_List, "mod_dirs", moddir_lptr);
/* Add a copy of the custom directory to the tail of the list. */
prg_list_strings_append (moddir_lptr, directory_str, PRGC_NIL);
/* Set the new list as the list of model directories.*/
prg_env_attr_value_set ("mod_dirs", moddir_lptr);
/* Free the list's elements. */
prg_list_free (moddir_lptr);
/* Free the list itself. */
prg_mem_free (moddir_lptr);
FOUT
}
Details
The current value of a preference in the current process can be changed. The new value must be of the same data type as the preference being queried. The attribute value is changed only in the current process and does not affect values stored in the preferences file or environment files.
If the attribute is of type PrgT_List, the list for the value argument 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 dynamically assign preferences within the current process.
Errors
- Program Abort: Segmentation violation. (due to an invalid value pointer, invalid address for attr_name, or value of incorrect type)
- Recoverable Error: Attribute name (<attr_name>) is unrecognized.
- Recoverable Error: Object ID (<objid>) is out-of-range.
- Recoverable Error: Value is invalid for attribute (<attr_name>).
Reference
- use prg_env_attr_value_get() to obtain a preference’s value
- use prg_preference_value_get() to obtain a preference’s value and ensure its subsequent appearance in the Preferences Editor
- use prg_preference_value_set() to set a preference’s value (and ensure that it appears in the Edit Preferences dialog box)