====== Macros ======

ACS-SASSI generates a large amount of data that tends to be processed using repetitive tasks.  Due to the ridged command structure and the way data is stored  in Prep it was impossible to create commands to do these tasks.  This was the reason for the Batch Menu and why the options therein were added in [[Sassi:Prep]] 2.3.0. This worked well for some options however it was obvious that other batch options were highly inefficient. The [[SASSI:ACS-SASSI User Interface]] commands do not have the same constraints that limited the ability of Prep to access and modify the data that required the addition of the batch functionality.  For this reason, many new commands have been introduced that replace the batch functionality in the User Interface.  

While these new commands fix the inefficiency of some of the batch options, it does not reduce the burden of the user to create and verify a  file to do these operations. Some batch files need to cover hundreds or thousands of operations on data generated by the simulation [[:Modules]].  This is the reason the  why Macros have been introduced.

A Macro in ACS-SASSI is a specially formatted *.[[file:pre]] file that has variables. Macro variables are defined by a positive integer number that is encapsulated with dollar signs (example $1$, $2$ ... ,$10293$). Macros are loaded into the [[SASSI:ACS-SASSI User Interface]] with the use of the [[com:LOADMACRO]] command. The user can then call the macro by using the [[com:MACRO]] Command. When the user calls the macro command the variables are replaced by the arguments given to the instruction. The integer in the variable is directly related to the argument number in the command.    

Macros can be as simple or complex as the user wishes. There is no command limitations on what a macro contains including calls to other macros. It is suggested that a Macro not use the LOADMACRO command because the repeated call to LOADMACRO will hurt performance if the same data is being loaded repeatedly. All macro names will be translated to all upper case letters therefore Node and NODE will be the same macro.  There is a 50 character limit on the macro name and a 3000 character limit on what each variable can contain. Each command Line in the macro  is also limited to 3000 characters.  There is no limit on the number of variable that one macro can have. A Macro can have the same name as a command however this does not overwrite the User Interface command.
===== Example(s) =====

==== Basic Example ====
The basic example uses the macro to replace the N Command

<code> 
* Node-Macro.pre A Simple example Macro
N,1,$1$,$2$,$3$ 
</code>

<code>
* MacroTest Pre will be equivalent to N,1,13.52,15,100.25
LoadMacro,Node,.\Node-Macro.pre
Macro,Node,13.52,15,100.25
</code>

==== Graphing Example ====

The graphing example creates a macro to get the SRSS of 3 lines, save the result and captures the capture the plot of all of the lines in an image. The usage of the macro will then create the SRSS Line and graph for all points in the model.

<code>
* SRSS-macro.pre
* Load 3 lines SRSS data and output result to a file 
* and capture image of all the lines on the graph
READSPEC,$1$,1,1
READSPEC,$2$,1,2
READSPEC,$3$,1,3
SRSS,4,1,2,3
WRITESPEC,$4$,4 
* Capture images.
SPECPLOT,1,2,3,4
CAPTUREPLOT,$4$.png
CLOSEPLOT
</code>

<code>
* SRSS_folder.pre
* Create SRSS files for all nodes in the model
LOADMACRO,SRSS,SRSS-macro.pre
MACRO,SRSS,Node1x.rs,Node1y.rs,Node1z.rs,Node1srss.rs
MACRO,SRSS,Node2x.rs,Node2y.rs,Node2z.rs,Node2srss.rs
MACRO,SRSS,Node3x.rs,Node3y.rs,Node3z.rs,Node3srss.rs
MACRO,SRSS,Node4x.rs,Node4y.rs,Node4z.rs,Node4srss.rs
                        ...
MACRO,SRSS,Node5214x.rs,Node5214y.rs,Node5214z.rs,Node5214srss.rs
</code>
==== Nested Macro Example ====

This is a modification of the graphing example that uses the same SRSS-macro.pre to show how the user should next macros. Instead of the first macro SRSS-macro.pre being called directly the new macro will simplify the input of SRSS_folder.pre. Nesting allows for the design and reuse of more general macros while allowing input simplification for a specific problem or data set.  

<code>
* Nested-macro.pre
* Use SRSS-macro.pre to create a graph
MACRO,SRSS,Node$1$x.rs,Node$1$y.rs,Node$1$z.rs,Node$1$srss.rs
</code>

<code>
* SRSS_folder_Nested.pre
* Create SRSS files for all nodes in the model
* Does the same thing as SRSS_folder.pre
*
* Load the Macros
*
LOADMACRO,SRSS,SRSS-macro.pre
LOADMACRO,NESTED,Nested-macro.pre
*
* Use the Macros
* 
MACRO,NESTED,1
MACRO,NESTED,2
MACRO,NESTED,3
MACRO,NESTED,4
      ...
MACRO,NESTED,5214
</code>