Procedure Variables
Procedures and methods both support private and public variables; all of the following statements apply equally to procedures and methods:
Variables used within procedures are automatically private to that procedure. Hence, you do not have to declare them as such and they do not require a NEW command. To share some of these variables with procedures that this procedure calls, pass them as parameters to the other procedures.
You can also declare public variables. These are available to all procedures and methods; those that this procedure or method calls and those that called this procedure or method. A relatively small number of variables should be defined in this way, to act as environmental variables for an application. To define public variables, list them in square brackets following the procedure name and its parameters.
The following example defines a procedure with two declared public variables [a, b] and two private variables (c, d):
publicvarsexample
; examples of public variables
;
DO proc1() ; call a procedure
QUIT ; end of the main routine
;
proc1() [a, b]
; a private procedure
; "c" and "d" are private variables
{
WRITE !, "setting a" SET a = 1
WRITE !, "setting b" SET b = 2
WRITE !, "setting c" SET c = 3
SET d = a + b + c
WRITE !, "The sum is: ", d
}
USER>WRITE
USER>DO ^publicvarsexample
setting a
setting b
setting c
The sum is: 6
USER>WRITE
a=1
b=2
USER>
Public versus Private Variables
Within a procedure, local variables may be either public or private. The public list [pubvar] declares which variable references in the procedure are added to the set of public variables; all other variable references in the procedure are to a private set seen only by the current invocation of the procedure.
Private variables are undefined when a procedure is entered, and they are destroyed when a procedure is exited.
When code within a procedure calls any code outside of that procedure, the private variables are restored upon the return to the procedure. The called procedure or routine has access to public variables (as well as its own private ones.) Thus, [pubvar] specifies both the public variables seen by this procedure and the variables used in this procedure that are capable of being seen by a routine that the procedure calls.
If the public list is empty, then all variables are private. In this case, the square brackets are optional.
Variables whose name starts with the percent (%) character are typically variables used by the system or for some special purpose. InterSystems IRIS reserves all % variables (except %z and %Z variables) for system use; user code should only use % variables that begin with %z or %Z. All % variables are implicitly public. They can be listed in the public list (for documentation purposes) but this is not necessary.
Private Variables versus Variables Created with NEW
Note that private variables are not the same as variables newly created with NEW. If a procedure wants to make a variable directly available to other procedures or subroutines that it calls, then it must be a public variable and it must be listed in the public list. If it is a public variable being introduced by this procedure, then it makes sense to perform a NEW on it. That way it will be automatically destroyed when the procedure exits, and also it protects any previous value that public variable may have had. For example, the code:
MyProc(x,y)[name]{
NEW name
SET name="John"
DO xyz^abc
}
enables procedure xyz in routine abc to see the value John for name, because it is public. Invoking the NEW command for name protects any public variable named name that may already have existed when the procedure MyProc was called.
The NEW command does not affect private variables; it only works on public variables. Within a procedure, it is illegal to specify NEW x or NEW (x) if x is not listed in the public list and x is not a % variable.
Making Formal List Parameters Public
If a procedure has a formal list parameter, (such as x or y in MyProc(x,y) ) that is needed by other procedures it calls, then the parameter should be listed in the public list.
Thus,
MyProc(x,y)[x] {
DO abc^rou
}
makes the value of x, but not y, available to the routine abc^rou.
