LOCAL Designation of Local Data

Formats

1.	Assign Local Variables:	LOCAL varlist LOCAL DIM var[$][dim1[,dim2] ...]]
2.	Define Local Properties (OOP):	LOCAL prop1 [OBJECT], prop2 [OBJECT]...
3.	Define Local Variables for User-Defined Functions:	DEF FNxxxxx (LOCAL var [, LOCALvar ...] )

Where:

OBJECT

Optional keyword identifies that the property contains an object identifier to another object.

prop1,
prop2 …

Property names – treated like any other variable in the system. (In Object Oriented Programming, data is referred to as properties.)

varlist

Variables to be used temporarily in the execution of a sub-routine, sub-program, FOR/NEXT, SWITCH/END SWITCH, WHILE/WEND, REPEAT/UNTIL or user-defined function.

Variables may also be dimensioned as local numeric or string arrays. A range may be specified to define the minimum and maximum index values of the array. See Format 1.

Description

The LOCAL directive is used to reassign variable names temporarily without affecting the original contents. In Object Oriented Programming (OOP), the LOCAL directive is similar to the PROPERTY directive but is used to declare data that is only visible to processing logic.

Format 1

Assign Local Variables

LOCAL varlist
LOCAL DIM var[$][dim1[,dim2] ...]]

Use the LOCAL varlist format to reassign variable names temporarily without affecting the original contents. If the variable name supplied in the LOCAL directive is in current use, PxPlus will preserve its value/contents. Once the current FOR/GOSUB stack has been cleared or the program is exited, PxPlus restores variables that were designated local to their original values. (Local variables are only active until the current stack is cleared.)

The LOCAL directive can take an assignment during declaration; however, direct assignment does not work for arrays that are declared as local.

The LOCAL DIM var[$][dim1[,dim2] ...]] format can be used to dimension variables as local numeric or string arrays. A range may be specified to define the minimum and maximum index values of the array. See Example 2.

The local array can have a different number of elements than the original array. Once the current FOR/GOSUB stack has been cleared or the program is exited, PxPlus restores the array to its original size and contents, the same way it restores simple local variables.

Example 1:

In this example, X is designated as local for both sub-routines (CHK_IT and LOOP); therefore, the value of X is restored to its original value "1234" after the GOSUB stack is cleared for each sub-routine. Since X$ was not designated as local in the LOOP subroutine, its value has changed from "START TEST, X=" to "LOOP" after the GOSUB stack for the LOOP has been cleared.

     X=1234,X$="START TEST, X=";
     print X$,X
     gosub CHK_IT
     print "TEST DONE"
     gosub LOOP
     print X$,X," DONE";
     stop

CHK_IT:
     local X$,X;
     X$="CHECK X:";
     print X$,X
     X=X+10
     print X$,X
     return

LOOP:
     print "START LOOP, X=",X
     X$="LOOP" ! Not designated as local
     for local X=1 to 4
          print X$,X
     next X
     return

     ->run
     start TEST,X=1234
     CHECK X: 0
     CHECK X: 10
     TEST DONE
     START LOOP, X=1234
     LOOP 1
     LOOP 2
     LOOP 3
     LOOP 4
     LOOP 1234 DONE

Example 2:

This example shows LOCAL DIM used with an array.

Inside the GOSUB, the x$ array is made local while the y$ array is not. Therefore, the original elements in the x$ array are unaffected by the code in the GOSUB, while the values in the y$ array are changed.

Before the GOSUB, x$ has three elements ("one", "two", "three"), and y$ has two elements ("aaaa", "bbbb"). In DO_GOSUB, x$ is given four elements using LOCAL DIM, while y$ is given the same two elements using DIM (not local).

dim x$[3],y$[2]
   x$[1]="one",x$[2]="two",x$[3]="three"
   y$[1]="aaaa",y$[2]="bbbb"
   msgbox "Before GOSUB"+SEP+x$[1]+SEP+x$[2]+SEP+x$[3]+SEP+SEP+y$[1]+SEP+y$[2]
   gosub DO_GOSUB
 ! x$[4] is now invalid
   msgbox "After GOSUB"+SEP+x$[1]+SEP+x$[2]+SEP+x$[3]+SEP+SEP+y$[1]+SEP+y$[2]
   end
 !
 DO_GOSUB:
   local dim x$[4] ! one element larger
   dim y$[2]
   x$[1]="111",x$[2]="222",x$[3]="333",x$[4]="444"
   y$[1]="CCCC",y$[2]="DDDD"
   msgbox "In GOSUB"+SEP+x$[1]+SEP+x$[2]+SEP+x$[3]+SEP+x$[4]+SEP+SEP+y$[1]+SEP+y$[2]
   return

Because the x$ array was declared local, it returns to its original size and values once the GOSUB returns: the second MSGBOX again shows "one", "two", "three", and the fourth element is gone. Because the y$ array was not declared local, the values set inside the GOSUB ("CCCC" and "DDDD") stay in effect after the RETURN.

Variables in function definitions can be designated as local to prevent changes in program variables:

def fnXY(local X, local Y, local Z)=X+Y+Z

Format 2

Define Local Properties in Object Oriented Programming

LOCAL prop1 [OBJECT], prop2 [OBJECT]...

In Object Oriented Programming (OOP), the LOCAL directive can be used to define the properties for an object class that are not exposed to external applications. They can be accessed during the execution of program logic within the object class itself.

This format of the LOCAL directive is similar to the PROPERTY directive: variable declarations may include dimensioned arrays and object references.

LOCAL properties are typically used for:

File handles (if the object is maintained on a file).
Security information.
Flags and status information used by the programming logic.

If the local variable contains an object identifier to another object, specify the keyword OBJECT after the variable name. When the object is deleted, PxPlus will use the REF( ) function against the object identifier to remove it (as long as it has no other references):

def class "Customer"
local File object

When you delete an object whose class is "Customer", then the system reduces the reference count of the object whose identifier is in "File" and, if it is no longer being referenced, deletes it as well.

Format 3

Define Local Variables for User-Defined Functions

DEF FNxxxxx (LOCAL var[, LOCAL var ...] )

When defining a user function, the LOCAL keyword can be used to specify that the variables declared in the parameter list are local to the function; that is, the assignment of values from the function invocation parameter list will only affect the variables while within the function.