Substitution Table
Sometimes you want to be able to define parameters, used by a macro, while the macro is running. For example, you have written a macro that extracts and processes data for a bench in your pit. The bench is defined by a top and bottom elevation. You want to be able to use the same macro for any bench without editing the macro file each time. There are 2 ways to handle this:
- In the form that uses the variable parameters (in our example the top and bottom elevation of the bench), type a question mark ('?') in the response field. This will cause the macro to pause allowing you to enter the appropriate values. Once this is done, click the OK or RUN button on the form to resume the macro.
- Substitution Tables offer greater flexibility (and actually use the functionality of the first option). The problem with the question mark approach is that there may be multiple forms that use the variable parameters. Or there may be some lengthy processes to run before the variable parameters are used, requiring you to wait at the computer until the macro pauses. Substitution Tables are explained below.
The macro process to invoke a Substitution Table is called MACSUB. Its menu equivalent is Script | Macro Commands | Utilities | Substitution Table.
The Substitution Table form looks like this:
MACSUB is normally one of the first processes in the macro. The form (above) has been filled out to reflect how it might be used for our hypothetical bench example. The text in the '@' column are (user defined) names that will be used as replaceable values (%1, %2 fields) by subsequent processes in the macro. Because the form contains a question mark the macro will pause, allowing you to type in values for the 2 variables. Once you have done this press the run button to resume the macro.
In the macro, you would use the substitution names as shown below (note some of the macro fields have been hidden).
The SUBSET process (or, more accurately, the FILTER used by the SUBSET process) will reference the replaceable %1 and %2 parameters. Because the names in the %1 and %2 fields of the macro have '@' as a suffix, it treats them as the names defined in the Substitution Table and uses the values entered in the Substitution column as pass parameters.
The substitutions defined in the Substitution Table need not be related to each other. For example, as well as defining the top and bottom elevations of the bench we could also define the name of the file, or field, to be used by some other step in the macro.
Any process in the macro can use values defined in the Substitution Table. More importantly these values are also available to any macro called by the main macro. So, suppose that you wanted to have a macro that generated output for all the benches in your pit. It might look something like this:
|
|
|
The macro called by the steps 2, 4, 6 etc would actually do all the work and they would use the @Top_RL and @Bottom_RL substitutions to define the bench limits.
One final comment. In the example above you could have saved the substitution values for each bench as separate forms. The MACSUB process would then have used a different form number before calling the macro that does the real work.
This illustrates a more automated way of defining parameters when the macro pauses in the Substitution Table. Remember this example..?
If you have previously saved forms (using the same substitution names) for each bench, you can now click on the Forms button, select the saved set for the appropriate bench (to populate the current form) and then click on the Run button. This is probably not such a big deal for the bench scenario, but if you were using more than 2 substitutions it can make things a lot easier.
Note that you can also reference predefined substitution parameters (or the project substitutions you define yourself) in expressions or enter them directly in a form. See: Substitution Variables and Predefined Substitution Parameters
Predefined Substitutions do not need to be included in the Substitutions table.