Accesses a variable that is not on the current program level.

name—A string containing the name of a variable that is on the program level specified by the Level keyword.

local—The name of the local variable that you want to bind to the variable name.

Add—If nonzero, creates a new variable on the $MAIN$ program level if the variable with the name “name” doesn’t already exist.

Level—An integer (n) specifying the program level on which to find the variable name. (Default: program level 0, which is $MAIN$)

If n ≥ 0, the program level is counted from $MAIN$ (level 0) to the current procedure (absolute).

If n < 0, the program level is counted from the current procedure to the $MAIN$ level (relative).

Creating two or more local bindings to the same variable can result in unpredictable behavior and is not recommended or supported.

You can use the INFO procedure with the Upvar keyword to determine whether a variable exists on a specific program level and, if it exists, determine its name. The name returned by INFO and the Upvar keyword can be used directly in the UPVAR procedure (see Example 1).

A variable name is obtained with the INFO command and its Upvar keyword. The variable name is then used in the UPVAR command.

; Obtain the name of the variable "var", which is

; on the $MAIN$ program level.

INFO, var, Upvar=v_name

; Bind the variable "var" from the $MAIN$ program level.

UPVAR, v_name, local_var

UPVAR is useful in VDA Tool development, such as when you need to pass variables from one program level to another without using Common Blocks. For example, the following procedure is a callback for a TM_CONVERT method. This procedure replots a variable whenever a window has been resized. To find out which variable to plot, it first lists the variables associated with a specific instance of a VDA Tool, then uses UPVAR to pass the variables into the local procedure. (Assume that for this VDA Tool, variables were created on the $MAIN$ program level, which is where UPVAR gets variables by default.)

PRO ConvertPlotTool, tool_name

   IF !D.NAME EQ 'X' THEN BEGIN

      plot_var = TmEnumerateVars(tool_name)

      UPVAR, plot_var(0), local

      PLOT, local, Xstyle=4, Ystyle=4, /Nodata, /Noerase

   END

END

ADDVAR, DELVAR, INFO