Reference Guide > R Routines > RENAME Procedure
  

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' 
See Also
ADDVARINFOUPVAR

Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.