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:
1. 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
2. At the WAVE> prompt, compile the test procedures with .RUN.
.RUN testrename
3. Next, create a main level variable (a string).
orig0 = 'Original Level 0 Variable'
4. 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
5. Verify the existence of the variable new_main.
INFO, new_main
; PV-WAVE prints: new_main STRING = 'Original Level 0 Variable'
