Handle Functions

About varTerms

Occasionally there is a need within an Analytica model to perform meta-reasoning about the model and its objects or dimensions. In these cases, one needs to manipulate object handles, hereafter referred to as varTerms, as atoms or as elements in lists or arrays.

In result views, when a cell contains a varTerm, the title attribute of its object is displayed, unless the title is not set or "Show By Identifier" is on. If the title is not set or "Show By Identifier" is on, then the identifier of the object is displayed. "Show By Identifier" can be toggled from the Object menu or by pressing CTRL-Y.

When a varTerm is displayed in a result table cell, the cell becomes a hyperlink. Clicking on that cell will take you to the object window for that object.

When a variable is defined as a list of variable identifiers, the index value for that variable is a list of varTerms. Its value is the result of evaluating those varTerms, but in its result view, the number format for each varTerm column is taken from the varTerm object. This allows each column in a result to be based on a separate number format.

Manipulating varTerms can be a bit tricky, primarily because you must be aware of when the term is treated as an atomic varTerm or is evaluated. Normally, when you use an identifier in an expression, the identifier is evaluated, so you end up with the value, not a handle to the variable.

Some Analytica attributes consist of lists of varTerms. For example, Attribute Contains is a var-list containing all objects contained in a given module. Meta-inference code, for example, may use this attribute to walk the module hierarchy.

Function VarTerm

The VarTerm function returns a varTerm (a handle to an object) from an identifier.

Function VarTerm( X : VariableType ; AsIndex : optional boolean atomic )

If you want to create a user-defined function that returns a varTerm, in most cases the return value needs to involve a call to the VarTerm function. If you simply place the identifier of a local variable (even if it declared as VariableType) as the return value, it will be evaluated. For example, consider these two functions:

Function Fu1( X : VariableType ) := X
Function Fu2( X : VariableType ) := VarTerm(X)
Variable Va1 := 5

Suppose you evaluate Fu1(Va1) and Fu2(Va1). Fu1 returns the value of Va1, that is 5. Fu2 returns a handle to the Va1 object. Hence, to return a varTerm, a call to Function VarTerm was necessary.

You can declare a local variable to be a varTerm using, for example,

var a := VarTerm(Va1) do ...

where Va1 is the identifier of an object. In the scope of this var declaration, a then becomes an alias for Va1. In other words, anywhere you might use the identifier Va1 in an expression, you could equivalently use a.

To create an alias to an index, use

var I := VarTerm( In1, AsIndex:True ) do ...

The local variable I will then serve as an alias to the original index In1 inside the scope of this var statement. The AsIndex parameter causes I's index values to be used when I appears in a value context (this is relevant when the original object is a self-indexed array, having both a value and an index value).

When an index contains varTerms, and you wish to subscript across that index, the recommended syntax is:

 A[ I = VarTerm(x) ]

In this example, x would be the identifier appearing as one of the elements of I.

Function GetVariableByName

GetVariableByName( varName : atmoic text )

Finds an object in the global namespace having the indicated name and returns a varTerm (i.e., object handle) to that object. If no such object exists, returns Null (use IsUndef to test for null if you worry about backward compatibility).

One danger with using this function is that Analytica has no dependency influence information. For example, the following expression

 var x := GetVariableByName("Va1") do x

evaluates Va1 and returns that value; however, if Va1 were to change, Analytica would have no way of knowing that this result needs to be invalidated. Obviously, in this example, it would better to use just the identifier Va1 in the expression, but as a basis of comparison, note that Analytica would be aware of the dependency influence if this variation were used:

 var x:= VarTerm(Va1) do x

If the value of Va1 changes, it would know that this value needs to be re-computed.

Function IndexesOf

IndexesOf( A : Array )

Returns a list of varTerms, each one serving as a handle to the indexes of array A.

This is similar to IndexNames(A), except that IndexesOf returns actual varTerms, while IndexNames returns the index identifiers (as text strings).

It is possible for an array to have more than one local index having identical names. Obviously, this is not recommended, but in the unusual case where this occurs, the index handles returned by IndexesOf are unambiguous.