====== var_SetVarRef ======

===== Description =====

Set a variable to be a reference/alias of another variable. 

===== Function prototype =====

<code>bool CExtAPI::var_SetVarRef(ZVAR hPtrVar, ZVAR hSrcVar);</code>

===== Arguments =====

^ Name ^ Type ^ Comment ^
| hPtrVar | ZVAR | A ZVAR handle to a variable, which will become the reference/alias of //hSrcVar//. |
| hSrcVar | ZVAR | A ZVAR handle to a variable, which is to be referenced by //hPtrVar//. |


===== Return value =====

False if an error occurred, and true otherwise.

===== Comments =====

==== Use this function for... ====

This function is normally used to [[wp>Pass-by-reference#Call_by_reference|pass values by reference]] to functions when they either cannot be copied using [[zeolite:functions:var_CopyValue]] (such as a map), or when it is excessively wasteful to do so (such as for a very large varlist.) Please refer to the [[#example]] provided below. 

==== Automatic initialisation ====

If //hPtrVar// is not initialised as the variable type of //hSrcVar//, it will be automatically re-allocated as the appropriate type. 


==== Name is not changed ====

This function does not change the name of //hPtrVar//, so //hPtrVar// and //hSrcVar// may have different names. 

==== Using var_Delete ====

The [[zeolite:functions:var_Delete]] function may be safely used on variables that are references of another, as the real instance of the data is only deleted from the original variable.


===== Example =====

This example was taken from the [[bundywiki>plugins:calc:SphericalDistort|SphericalDistort]] plugin:

<code>
// create a temporary list to hold the arguments for the SphericalDistort function
ZLIST hArgs = theAPI.var_CreateTemp(VarID_varlist);
if(!hArgs) {
    return false;
}

// get a handle to the heightfield in the project
ZVAR hMap = theAPI.map_GetMap("project.HF");
if(!hMap) {
    return false;
}

// create a map handle in the function argument list
ZVAR hMap2 = theAPI.list_CreateItem(hArgs, VarID_map, "hMap");
if(!hMap2) {
    return false;
}

// Use SetVarRef to make "hMap" in the function argument list point to the data 
// of the map at "project.HF" (the project heightfield)
if(!theAPI.var_SetVarRef(hMap2, hMap)) {
    return false;
}

// set the radius
double radius = 6400*1000; // radius of earth
ZVAR hRad = theAPI.list_CreateItem(hArgs, VarID_double, "radius");
if(!hRad) {
    return false;
}
if(!theAPI.var_SetValue(hRad, &radius)) {
    return false;
}
if(!theAPI.var_EditUI(hRad, "Enter sphere radius in metres")) {
    bool TempBool = false;
    theAPI.var_SetValue(hRval, &TempBool);
    return true; // function returned safely, but the zeolite rval is OK
}

// now pass the argument list to the function and execute it
bool rval = SphericalDistort(hRval, hArgs);

// delete the temporary argument list
theAPI.var_Delete(hArgs);

// all done, lets go home
return rval;
</code>