prg_env_attr_value_get()
Abstract
Obtains the value of a preference.
Syntax
prg_env_attr_value_get (attr_type, attr_name, 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 Table 1 Environment Attribute Package Symbolic Constants. |
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* |
pointer to a variable to be filled with the specified attribute’s value. See the Details section for more information. |
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 value_ptr argument can accept a character string or a pointer to a variable of type integer, double, or PrgT_List. The data type of the argument pointer must match the data type of the specified attribute, or an error will occur.
- In the case of a character string, the array of characters must be large enough to contain the attribute’s value.
- If the attribute is of type Boolean, the return value will either be
OPC_BOOLINT_ENABLEDorOPC_BOOLINT_DISABLED. - If the attribute is of type
PrgT_List, the list forvalue_ptrmust 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 obtain preferences from the current process. The current value of a preference in the current process can be obtained.
This function differs from prg_preference_value_get() in that prg_preference_value_get() ensures that any attribute it requests will subsequently appear when a user selects Edit Preferences, whereas this function does not ensure such behavior. You might prefer to use this function to obtain preference values that users have no need to view or edit; this can prevent the Preferences Editor from getting crowded with extraneous attributes.
Errors
- Program Abort: Segmentation violation (due to an invalid value pointer, pointer to an insufficient amount of memory, or invalid address for
attr_name) - Recoverable Error: Attribute name (<attr_name>) is unrecognized
Reference
- 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)
- use prg_preference_value_set() to set a preference’s value (and ensure that it appears in the Edit Preferences dialog box)