Table of Contents

var_GetValue

Description

Retrieve the value of a variable.

Function prototype

bool CExtAPI::var_GetValue(ZVAR hVar, void* pValue);

Arguments

Name Type Comment
hVar ZVAR A ZVAR handle to a variable, the value of which is to be retrieved.
pValue void* A user-supplied handle to an allocated block of memory for the appropriate data type, ready to receive the value from the ZVAR.

Return value

False if:

  1. hVar does not reference a valid variable (e.g. is null).
  2. pValue is null.
  3. The variable referenced by hVar is not initialised.
  4. The variable type of hVar cannot be copied (see comments below.)

True otherwise.

Comments

Check the variable type, or use var_GetValueEx

Before retrieving the value of a variable it is strongly recommended that you check the type using var_IsType (see example below.) This is to ensure that the variable type is what you think it is, so that your pValue handle is the correct storage type. If, for instance, you don't check the variable type and provide a pValue handle to a char data type (1 byte) when the variable is actually a long (4 bytes), you will have corrupted memory somewhere and the world may end.

Alternatively, you can use the var_GetValueEx function, which includes a test of the variable type.

Incompatible types

The following variable types are not compatible with var_GetValue (and var_SetValue, var_GetValueEx and var_SetValueEx):

Type Reason
VarID_void Voids contain no data, and hence no value to retrieve.
VarID_string Strings are stored in a funny way. Use the str API functions to read/write the values.
VarID_map Maps do not contain a single value. Use the map API functions instead.
VarID_varlist Lists do not (necessarily) contain a single value. Use the list API functions instead.
VarID_format Formats do not contain a single value. Use the format API functions instead.
VarID_buffer Buffers do not (necessarily) contain a single value. Use the buffer API functions instead.
VarID_ComboSelector ComboSelector dialogs do not (necessarily) contain a single value. Use the combosel API functions instead.
VarID_ProgBox Progress dialogs do not contain a single value. Use the progbox API functions instead.
VarID_ZeoFunc Zeolite extension functions do not contain a single value. Use the zeofunc API functions instead.

Example

// get a variable called 'radius'
ZVAR hVar = theAPI.var_GetVar("radius");

// check it is the correct type (a double, in this example)
if(!theAPI.var_IsType(hVar, VarID_double)) {
   ReportError("Incorrect variable type!");
   return false;
}

// get the value using var_GetValue
double radius;
if(!theAPI.var_GetValue(hVar, &radius)) {
   ReportError("Cannot retrieve variable data!");
   return false;
}

// now use radius for something...