##unique

Creates a new, unique local variable within a macro definition for use at compile time or runtime.

Description

This macro preprocessor function creates a new, unique local variable within a macro definition for use at compile time or runtime. This preprocessor function is available for use only as part of #define or #def1arg call. It has the form:

 ##unique(new)
 ##unique(old)

where new specifies the creation of a new, unique variable and old specifies a reference to that same variable.

The variable created by SET ##unique(new) is a local variable with the name %mmmu1, subsequent SET ##unique(new) operations create local variables with the names %mmmu2, %mmmu3, and so forth. These local variables are subject to the same scoping rules as all % local variables; % variables are always public variables. Like all local variables, they can be displayed using ZWRITE and can be killed using an argumentless KILL.

User code can refer to the ##unique(old) variable just as it can refer to any other ObjectScript variable. The ##unique(old) syntax can be used an indefinite number of times to refer to the created variable.

Subsequent calls to ##unique(new) create a new variable; after calling ##unique(new) again, subsequent calls to ##unique(old) refer to the subsequently created variable.

For example, the following code uses ##unique(new) and ##unique(old) to swap values between two variables:

 #define Switch(%a,%b) SET ##unique(new)=%a, %a=%b, %b=##unique(old)
 READ "First variable value? ",first,!
 READ "Second variable value? ",second,!
 $$$Switch(first,second)
 WRITE "The first value is now ",first," and the second is now ",second,!

To maintain uniqueness of these variables:

Do not attempt to set ##unique(new) outside of a #define or #def1arg preprocessor directive.
Do not set ##unique(new) in a preprocessor directive within a method or procedure. These will generate a variable name that is unique to the method (%mmmu1); however, because this is a % variable, it is globally scoped. Invoking another method that sets ##unique(new) also creates %mmmu1, overwriting the variable created by the first method.
Never set a %mmmu1 variable directly. InterSystems IRIS reserves all % variables (except %z and %Z variables) for system use; they should never be set by user code.

##stripq