struct variable can have a single pointer to auxiliary data of
void *. These functions manipulate a variable's auxiliary
Use of auxiliary data is discouraged because of its lack of flexibility. Only one client can make use of auxiliary data on a given variable at any time, even though many clients could usefully associate data with a variable.
To prevent multiple clients from attempting to use a variable's single auxiliary data field at the same time, we adopt the convention that use of auxiliary data in the active file dictionary is restricted to the currently executing command. In particular, transformations must not attach auxiliary data to a variable in the active file in the expectation that it can be used later when the active file is read and the transformation is executed. To help enforce this restriction, auxiliary data is deleted from all variables in the active file dictionary after the execution of each PSPP command.
This convention for safe use of auxiliary data applies only to the active file dictionary. Rules for other dictionaries may be established separately.
Auxiliary data should be replaced by a more flexible mechanism at some point, but no replacement mechanism has been designed or implemented so far.
The following functions work with variable auxiliary data.
Returns var's auxiliary data, or a null pointer if none has been assigned.
Sets var's auxiliary data to aux, which must not be null. var must not already have auxiliary data.
Before var's auxiliary data is cleared by
var_clear_aux, aux_dtor, if non-null, will be called with var as its argument. It should free any storage associated with aux, if necessary.
var_dtor_freemay be appropriate for use as aux_dtor:
Removes auxiliary data, if any, from var, first calling the destructor passed to
var_attach_aux, if one was provided.
dict_clear_auxto remove auxiliary data from every variable in a dictionary.
Removes auxiliary data, if any, from var, and returns it. Returns a null pointer if var had no auxiliary data.
Any destructor passed to
var_attach_auxis not called, so the caller is responsible for freeing storage associated with the returned auxiliary data.