RENAME Procedure

Renames a PV‑WAVE variable.

Usage

RENAME, variable, new_name 

Input Parameters

variable—The variable to rename.

new_name—A string specifying the name of the new variable. By default, the new variable is placed at the $MAIN$ program level.

Keywords

Level—An integer, n, specifying the level of the program to which to add the renamed variable.

If n ³ 0, the level is counted from the $MAIN$ level to the current procedure.

If n < 0, the level count is relative, counting from the current procedure back to the $MAIN$ level.

Discussion

If the new variable already exists at the specified program level, the existing variable is overwritten.

To rename a variable that exists at a level other than the current level,use the UPVAR command to bind that variable to a local variable.

Example 1

This example is the simplest case, where a variable on the main program level is renamed.

orig = 1B
RENAME, orig, 'new'
INFO, new
; PV-WAVE prints:     new        BYTE      =    1

Example 2

The following program demonstrates how RENAME can be used with the Level keyword and the UPVAR procedure to move variables between program levels.

To run this example, do the following:

Copy or type the code for the TESTRENAME and TESTLEVEL2 procedures into a file called testrename.pro.

; This procedure tests the RENAME procedure first inside local 
; program level (level 1), and then by renaming variables on
; other program levels. 
PRO TESTRENAME
; First, create a variable in the local program level, and
; verify that the program level is level 1. 
orig1 = 'Original Level 1 Variable' 
INFO, Depth = d
; Rename the variable inside the local scope of TESTRENAME. 
RENAME, orig1, 'orig1_new', Level = d
; Verify that RENAME created the new variable. 
INFO, orig1_new 
; Grab a variable from program level 0 ($MAIN$) using UPVAR 
; and bind that variable to a variable within the local scope. 
UPVAR, 'orig0', orig_level1 
; Execute the TESTLEVEL2 procedure. 
TESTLEVEL2 
; After returning from TESTLEVEL2, verify the existence of the 
; variable local_level1 and print it. 
INFO, local_level1 
PRINT, local_level1 
END 
PRO TESTLEVEL2
; First, verify that the local scope is program level 2. 
INFO, /Depth
; Use UPVAR to pass the variable orig_level1 from program 
; level 1 to the current program level 2. Note the use of the 
; Level keyword, which causes UPVAR to look one program level 
; down from the current level to find the variable. 
UPVAR, 'orig_level1', orig_level2, Level = -1
; Rename the variable that was just passed into program 
; level 2. The Level keyword specifies that the renamed 
; variable be placed in program level 2. 
RENAME, orig_level2, 'new', Level = 2
; Verify that the new variable exists in the local scope.
INFO, new 
; Create a new variable within the current scope (level 2). 
local_level2 = INDGEN(10) + 222
; Rename this variable, but put the renamed version on a 
; different program level. The Level keyword accomplishes 
; this. It specifies that the renamed variable be placed one 
; program level down from the current level. The current 
; program level is 2, so the new variable is placed in program 
; level 1. 
RENAME, local_level2, 'local_level1', Level = -1
; Use RENAME to rename a variable in current scope (level 2)
; and place the renamed variable in program level 0 ($MAIN$).
; Note that program level 0 is where RENAME places renamed 
; variables by default, unless the Level key word is used. 
RENAME, new, 'new_main'
END

At the WAVE> prompt, compile the test procedures with .RUN.

.RUN testrename 

Next, create a main level variable (a string).

orig0 = 'Original Level 0 Variable' 

Run the procedure TESTRENAME.

TESTRENAME

PV-WAVE prints the following:

PROGRAM LEVEL            = 1 
ORIG1_NEW       STRING    = 'Original Level 1 Variable'
PROGRAM LEVEL            = 2
NEW             STRING    = 'Original Level 0 Variable'
LOCAL_LEVEL1    INT       = Array(10)
       222  223  224  225  226  227  228  229  230  231

Verify the existence of the variable new_main.

INFO, new_main
		; PV-WAVE prints: new_main STRING = 'Original Level 0 Variable' 

See Also

ADDVAR,  INFO,  UPVAR