New

The NEW command "stacks" copies of local variables and reinitializes those variables. An explicit or implicit QUIT from a DO, XECUTE or extrinsic function "unstacks" the NEWed variables, that is, restores the variable to the stacked value. A NEW lasts only while the current scope of execution is active.

The format of the NEW command is:

N[EW][:tvexpr] [[(]lvn[,...][)][,...]]

The NEW command provides a means of confining the scope of local variables. NEW operates only on unsubscripted local names and acts on the entire named array.

Examples of NEW

Example:

NEW1;
  Set A(1)=1,B=4,C=5
  Write !,"VARIABLES BEFORE NEW:",!
  ZWRite
  Do LABEL
  Write !,"VARIABLES AFTER RETURN:",!
  ZWRite
  Quit
LABEL    
  New A Set C=7
  Write !,"VARIABLES AFTER NEW:",!
  ZWRite
  Quit

Produces the results:

VARIABLES BEFORE NEW:
A(1)=1
B=4
C=5
VARIABLES AFTER NEW:
B=4
C=7
VARIABLES AFTER RETURN:
A(1)=1
B=4
C=7

Example:

NEW2;
  Set (A,B,C,D)="TEST"
  Do LABEL
  Write !,"VARIABLES AFTER RETURN:",!
  ZWRite
  Quit
LABEL
  New (B,C) SET (A,B,Z)="NEW"
  Write !,"VARIABLES AFTER EXCLUSIVE NEW:",!
  ZWRite
  Quit

Produces the results:

VARIABLES AFTER EXCLUSIVE NEW:
A="NEW"
B="NEW"
C="TEST"
Z="NEW"
VARIABLES AFTER RETURN:
A="TEST"
B="NEW"
C="TEST"
D="TEST"

Example:

/usr/lib/fis-gtm/V5.4-002B_x86/gtm -run ^stackalias   
stackalias ; Demonstrate New with alias
  ZPrint ; Print this program
  Set A=1,*B=A,*C(2)=A ; Create some aliases
  Write "------------",!
  Write "ZWRite in the caller before subprogram",!
  ZWRite
  Do S1 ; Call a subprogram
  Write "------------",!
  Write "ZWRite in the caller after subprogram - A association is restored",!
  ZWRite
  Quit
 ;
S1  ; Subprogram
  New A
  Set A="I am not an alias",B="I am an alias"
  Write "------------",!
  Write "ZWRite in the subprogram with new A and modified B",!
  ZWRite
  Quit
------------
ZWRite in the caller before subprogram
A=1 ;*
*B=A
C=3
*C(2)=A
D=4
------------
ZWRite in the subprogram with new A and modified B
A="I am not an alias"
B="I am an alias" ;*
C=3
*C(2)=B
D=4
------------
ZWRite in the caller after subprogram - A association is restored
A="I am an alias" ;*
*B=A
C=3
*C(2)=A
D=4

The following is essentially the same as the prior example but using an exclusive NEW:

$ /usr/lib/fis-gtm/V5.4-002B_x86/gtm -run ^stackalias1
stackalias1 ; Demonstrate New with alias
  ZPrint ; Print this program
  Set A=1,*B=A,*C(2)=A ; Create some aliases
  Write "------------",!
  Write "ZWRite in the caller before subprogram",!
  ZWRite
  Do S1 ; Call a subprogram
  Write "------------",!
  Write "ZWRite in the caller after subprogram - A association is restored",!
  ZWRite
  Quit
 ;
S1  ; Subprogram
  New (B)
  Set A="I am not an alias",B="I am an alias"
  Write "------------",!
  Write "ZWRite in the subprogram - Notice B is flagged as an alias",!
  ZWRite
  Quit
------------
ZWRite in the caller before subprogram
A=1 ;*
*B=A
C=3
*C(2)=A
D=4
------------
ZWRite in the subprogram - Notice B is flagged as an alias
A="I am not an alias"
B="I am an alias" ;*
------------
ZWRite in the caller after subprogram - A association is restored
A="I am an alias" ;*
*B=A
C=3
*C(2)=A
D=4

An exclusive New can create a scope in which only one association between a name or an lvn and an array may be visible. In this case, ZWRITE nevertheless shows the existence of an alias, even when that array is accessible from only one name or lvn.