MACRO <File="macrofile"> [<VarScope=Global|GlobalRestore|Local>] [<VarExclude=CommaSeperatedVarList>]
This command allows you to run another GSAK macro file. This allows you to reuse macro code (similar to using subroutines). Multiple levels are supported, that is, Macro A can call Macro B, which calls Macro C, which calls Macro D etc. At any stage you can check the calling level by using the $_MacroLevel system variable.
You can also pass parameters when calling a macro. For more information see this link.
File - File - The macro file to call. This must be a GSAK macro. If you just enter the file name then the default "macro" folder will be searched for the file. If your macro file is in any other folder, then you must full qualify the path name to the file.
VarScope - Optional, Default=Global.
Global - Means all variables (unless you have defined variables in VarExclude) are read/write in both the calling and called macro .
GlobalRestore - Use this option when you want the called macro to have access to all the variables of the calling macro, but you want the calling macro to restore the variable stack to the same state and values previous to calling a macro. Any new variables created by the called macro will be deleted when the called macro terminates.This insulates the calling macro and enables it to run another macro without fear of corrupting the values of any variables, yet at the same time allow it to "communicate" with it via any existing variables. VarExclude=" variables only excludes those variables from the "restore" part, not the "global" part. That is, any variable name you enter here will still be global, but their values will not be restored upon return from the called macro. This enables these variables to be updateable and shared between the two macros
Local - Means that all variables are kept separate between the calling and called macro (except persistent variables, and those defined in VarExclude). Effectively the called macro starts with no variables defined or set when the scope is local.
VarExclude - Optional. If used it must be a comma separated list of variable names (without the $ prefix) to exclude from this scope setting (in effect making these variables the opposite scope to that defined by VarScope).
By default, all GSAK macros use a global variable stack. This means that GSAK only keeps one copy of the variable in memory and all macros can read/write all variables regardless which macro created them. This can cause problems of "variable name collision" when one macro calls multiple macros. Use VarScope and VarExclude to change this default behaviour and help avoid variable name collision when calling macros. For more information see this link
Note1: Strictly speaking, the functions Array(), List() and AddStr() are not variables but they do act upon internal buffers that act similar to variables. Accordingly these 3 functions also respect the use of VarScope=Local. If you want to use VarExclude for any of these functions then you can add the reference via Array[nn] or Addstr[nn] or List[name]. For example, you want to call the macro "test.gsk" using a local variable scope. However, you still want to share Array 1, array 2, Addstr buffer 1, and the list named "MyList" as if they were global. The code would be:
Macro File="test.gsk" VarScope=Local VarExclude=Array[1],Array[2],AddStr[1],List[MyList] |
Note2: The intent of the "Local" scope is to isolate any variables between calling/called macros. Accordingly when VarScope=Local GSAK will isolate Option Explicit=Yes between called and calling macros. Although the Option command doesn't explicitly create variables it affects how variables are created. Therefore it makes sense to include the same isolation for the Option command.
Alpha List Category List