Lesson 14 - Parameter tables for macros

Congratulations! You have not only survived to the first lesson about Wintrack macros, but still want to learn more about them. Be warned, though! This lesson might even be tougher than the last one. You will discover the power of parameter tables which allow you to reuse your macros in different situations without having to rewrite and re-debug their code.

Running a macro with parameter tables...

1. Select Run Macro from the Analysis menu or click the Run Macro button of the toolbar while pressing and holding down the Shift key. The Run Macro dialog is displayed:
   • In the dialog field Options, activate the run dialogs, run macro, and set macro directory options. The check macro syntax option and the dialog field parameters will be grayed and you can ignore them.
   • Use the dialog field macro to specify the macro file ANL2.MAK of the WINTRACK directory on your hard disk as the macro to be run.
   • Click Ok to run the macro.
2. First, the macro will display a series of dialogs together with guide windows that give instructions what to specify in the dialogs. The macro will ask for:
   • A data file: specify any of the sample .WTR files in the WINTRACK directory and click Ok.
   • A custom setup file: specify POOL2.WSP of the WINTRACK directory and click Ok.
   • A custom variable definition file: specify CASE1.VDF of the WINTRACK directory and click Ok.
   • A parameter table: specify SWIM.WTB of the WINTRACK directory and click Ok.
3. The macro will execute and terminate by displaying a scrollsheet with the results of the analysis.

   So, what is the difference? Well, remember: in macro ANL1.MAK, the names of the case documents to be analyzed were hard coded in the macro text. Instead, ANL2.MAK gets the names from a parameter table, for example the scrollsheet SWIM.WTB. You can open SWIM.WTB if you want. It has one column named cases that contains the names of the case documents to be processed.

Creating a parameter table with another set of cases...

Imagine you want to do the same analysis with another set of case documents. With ANLY1.MAK which was introduced in the last lesson you would have to edit the macro code and change all the names. That is no problem with a macro as simple as ANLY1.MAK, but could take more effort with a more sophisticated macro. With ANLY2.MAK you do not have to change the macro code. You simply create a scrollsheet with the new names and use it as parameter table for ANLY2.MAK.

case
SECOND1.WTR
SECOND2.WTR
SECOND3.WTR
SECOND4.WTR
SECOND5.WTR

1. Start Windows NotePad™ and create a new document. Type case, press Return, type SECOND1.WTR, press Return. And so on until you reach SECOND5.WTR. Do not press Return after the last name. Your list should look as the one shown above. When done typing, select all names with the mouse and copy the selection to the clipboard.
2. If there are any documents left open in Wintrack, select Close All from the Window menu and do not let Wintrack save any changes.
3. Click the Paste button of the toolbar while pressing and holding down the Shift key. The New Scrollsheet dialog is displayed:
   • Accept the default scrollsheet name.
   • In the dialog field Window, click fit to data.
   • In the dialog field Data, leave the option clipboard selected.
   • In the dialog field named fixed columns, enter 0. You could use this option to freeze a given number of columns at the left edge of a large scrollsheet and prevent them from scrolling away.
   • In the dialog field Options, select read column names and deselect all other options. Wintrack will interpret the first row of the imported data as column names.
   • Press Ok to close the dialog box.
4. Wintrack creates the new scrollsheet and fills it with the data that was copied to the clipboard from Windows NotePad™.
5. Click the Save button of the toolbar while pressing and holding down the Shift key. The Save Scrollsheet As dialog is displayed. Save the scrollsheet as SECOND.WTB to your WINTRACK directory, choosing normal in the dialog field Format. If the file already exists in your WINTRACK directory, let Wintrack overwrite it.
6. Click the Run Macro button of the toolbar without pressing the Shift key. This bypasses the Run Macro dialog and runs the same macro as last time when the command was invoked, i.e. ANLY2.MAK. ANLY2.MAK displays its usual series of dialogs, asking for the following:
   • A data file: accept the default and click Ok.
   • A custom setup file: accept the default POOL2.WSP and click Ok.
   • A custom variable definition file: accept the default CASE1.VDF and click Ok.
   • A parameter table: specify the file SECOND.WTB you have just created in the WINTRACK directory and click Ok.
7. The macro will execute and terminate by displaying a minimized scrollsheet with the results of the analysis. Double click the scrollsheet's icon to look at the results. When done, select Close All from the Window menu and let Wintrack close all open documents without saving changes.

   Instead of first converting the list you typed in Windows™ NotePad into a Wintrack scrollsheet, you could also save it from NotePad and directly specify the NotePad file as parameter table in the corresponding dialog of ANLY2.MAK. Wintrack can in fact use plain text files as parameter tables. This works fine with lists as short as the one used in this example. However, macros can become very slow if they have to process large parameter tables in text format. You do not need to use Windows™ NotePad to create parameter tables. In MS Excel™, you would enter your list into a range of cells in a worksheet, then select the cells and transfer them to a Wintrack scrollsheet via the clipboard as you did with the Windows™ NotePad list. As with Windows™ NotePad, you could also save the entire worksheet in text format and use that file directly as a parameter table.

   Now, imagine you have another custom variable definition file CASE2.VDF which you would like to apply to both sets of cases. No problem: COMBO.WTB is a parameter table which combines the file names of both sets. Both files are available in the WINTRACK directory of your hard disk, so we can start right away.

Reusing the same macro with still other cases and variables...

1. Click the Run Macro button of the toolbar without pressing the Shift key. ANLY2.MAK runs again and displays its usual series of dialogs, asking for the following:
   • A data file: accept the default and click Ok.
   • A custom setup file: accept the default POOL2.WSP and click Ok.
   • A custom variable definition file: specify CASE2.VDF in the WINTRACK directory and click Ok.
   • A parameter table: specify the just created COMBO.WTB in the WINTRACK directory and click Ok.
2. The macro will execute and terminate by displaying a minimized scrollsheet with the results of the analysis. Double click the scrollsheet's icon to look at the results. When done, select Close All from the Window menu and let Wintrack close all open documents without saving changes.

   Now that you know how to use parameter tables with macros, let us see how all this is actually implemented. Using parameter tables requires nesting of two macros: a master macro calls a slave macro repeatedly and feeds it the parameters listed in the parameter table.

The syntax of the master macro...

Below is a listing of ANLY2.MAK, the master macro that you called with the Run Macro command:

Macro, Example 2 (master macro)

[dialogs]

GuideTxt 1 "Specify file for extraction of data directory"
GuideShow
Opca /dh/iFile Fmat=Min
GetParam {1} iFile Take=Dir
GuideClr

GuideTxt 1 "Specify a setup file"
GuideShow
Aprp /dh/iFile Type=Custom
GetParam {2} iFile
GuideClr

GuideTxt 1 "Specify a variable definition file"
GuideShow
Anly /dh/iFile Vdef=File Rprt=Chain
GetParam {3} iFile
GuideClr

GuideTxt 1 "Specify a parameter table"
GuideShow
Opsc /dh/iFile
GetParam {4} iFile
GuideClr

[main]

Aprp iFile={2} Type=Custom
{4}?XANL2 {1} case? {3}

[end] 

The [dialogs] section is similar to the one in ANLY1.MAK which has been explained in detail in a previous lesson. A fourth block of statements has been added. It runs the Open Scrollsheet dialog in order to let the user specify a scrollsheet or tab delimited text file as a parameter table. Opsc is the macro statement that corresponds to the Open Scrollsheet command. The GetParam statement writes the file name to parameter register 4.

The [main] section is quite different, though, compared to that in ANLY1.MAK. The first statements is the same as in ANLY1.MAK. But the rest of the section has been collapsed into a single statement: {4}?XANL2 {1} case? {3}. This statement implements the call to the slave macro XANLY2.MAK. Note that .MAK does not need to be typed for the macro call. The prefix {4}? links the parameter table name stored in parameter register 4 to the slave macro: XANLY2.MAK is automatically called once for each line in the parameter table. With each call, three parameters are passed to the slave. {1} refers to the case file directory the user specified in the first dialog and which was stored in parameter register 1. case? instructs the slave macro to look up the parameter value in the parameter table in the column named case. Finally, {3} passes the name of the variable definition file which was stored in parameter register 3 during dialog processing. Thus, the first and second parameter passed to the slave are the same for every call, while the second one changes for every call as specified in the parameter table.

Parameter tables can have any number of columns. This is why the columns need to be given names. Parameter tables may also have "silent" columns which are never referenced by the macro that uses the table. This allows different macros with different sets of parameters to share a parameter table.

The syntax of the slave macro...

Now let us terminate the lesson by taking a look at the syntax of the slave macro XANLY2.MAK. Below is a listing of the macro:

Macro, Example 2 (slave macro)

[main]

Opca iFile={1}{2} Fmat=Min
Anly iFile={3} Rprt=Chain Vdef=File
Clca

[end]

Slave macros can't run dialogs, therefore this macro lacks a [dialogs] section. The [main] section contains three statements: Opca opens a case document, Anly analyses it, and Clca closes it. After processing these three statements, the slave returns control to the master macro. You might wonder what the bracketed numbers mean, in a macro that has no [dialogs] section. Well, remember: when calling the slave, the master passes it three parameters. During the call, the parameters are stored in the slave's parameter registers, in the same order as they appear in the call statement. The bracketed numbers are place holders that refer to the parameter registers. {1} is the case file directory, {2} is the case file name (looked up in the parameter table). {1} and {2} are combined to a complete path which is assigned to iFile in the Opca statement. {3} is the name of the variable definition file which is assigned to iFile in the Anly statement.

A slave could call another slave. Wintrack allows up to ten levels of macro nesting. Each macro that calls another macro can pass up to 16 parameters to it. When debugging slave macros you can run them from Wintrack using the Run Macro command. If you deselect the run dialogs option in the options field of the Run Macro dialog, the parameters field is activated and the parameters which are to be passed to the slave can be typed in the edit box.