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'