Lesson 13 - Wintrack macros

Now that you know about many of Wintrack's commands and features, it is time to come to a somewhat more complicated matter: Wintrack macros. It will take some effort to fully understand the concept behind Wintrack macros. But once you are familiar with this concept, you will realize that macros make the real power of Wintrack. Let's begin with the basics. Virtually every menu command in Wintrack has its equivalent macro statement with a set of parameters which correspond to the fields of the dialog box that is associated with the respective menu command. Basically, macros are no more than editable ASCII text files (again!) that contain a list of macro statements and some commentary. You create and edit them using Windows™ NotePad or an equivalent application and execute them using the Run Macro command.

Running a macro...

1. Select Run Macro from the Analysis menu or click the Run Macro button of the toolbar while pressing and holding downs 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 ANL1.MAK in 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. The macro will only consider the directory path of the file and look under that path for all data files it processes.
   • A custom setup file: specify POOL2.WSP in the WINTRACK directory and click Ok.
   • A custom variable definition file: specify CASE1.VDF in the WINTRACK directory and click Ok.
3. 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, let's take a look at the text of the macro you have just run. It shows the typical syntax elements of a Wintrack macro.

The syntax of macros...

Run Windows™ NotePad and open the file ANL1.MAK. The macro has two sections. The first begins with the label [dialogs] and contains the statements which control the macro's dialogs and their associated guide windows. The second section begins with the label [main], ends with [end] and contains the statements which do the actual work of the macro:

Macro, Example 1

[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 custom setup file"
GuideShow
Aprp /dh/iFile Type=Custom
GetParam {2} iFile
GuideClr

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

[main]

Aprp iFile={2}

Opca iFile={1}SWIM1.WTR Fmat=Min
Anly iFile={3} Rprt=Chain Vdef=File
Clca

Opca iFile={1}SWIM2.WTR Fmat=Min
Anly iFile={3} Rprt=Chain Vdef=File
Clca

Opca iFile={1}SWIM3.WTR Fmat=Min
Anly iFile={3} Rprt=Chain Vdef=File
Clca

Opca iFile={1}SWIM4.WTR Fmat=Min
Anly iFile={3} Rprt=Chain Vdef=File
Clca

[end] 

Before turning to the actual macro code, a brief remark on adding commentary to macros. There are two ways to add commentary to a macro in order to make it easier to read. First, all text that is typed either before [dialogs] or after [end] is ignored by the macro interpreter. You can use this space to enter text of any length. Second, Wintrack allows you to place commentaries within the code sections: any text included in single quotes or between a single quote character and the end of the line is considered as commentary.

The [dialogs] section

Let's look at the first block of statements in the [dialogs] section and take it apart, line by line. The first statement is GuideTxt. Its purpose is to fill a guide window with text, one line at a time. The first parameter indicates the number of the target line, the second the text to be displayed on that line. A guide window may display up to 10 lines of text. Note that the text has been included in double quotes. In Wintrack macros (as well as in custom setup and variable definition files), white spaces are used to separate statement parameters from each other and from the statement name. Because the text which is to be displayed in the guide window contains itself spaces, it must be included in double quotes. The second statement, GuideShow, displays the guide window on screen after it has been filled with text.

Opca /dh/iFile Fmat=Min is the command statement that forms the equivalent of the Open Case Document command that you normally activate by selecting Open Case from the File menu. When placed in the [dialogs] section, the command statement will not execute, however. It will merely display its Open Case Document dialog which you already know from previous lessons. The iFile parameter refers to the field case file of the dialog. The prefix /dh/ tells Wintrack to make the dialog field accessible and to put the most recently used file name as a default in its edit box. The Fmat parameter refers to the field Window in the dialog. =Min assigns it the selection minimize. Because there is no prefix, the field will be grayed and inaccessible for the user of the macro.

After the user of the macro has closed the Open Case Document dialog by clicking Ok, the selections he made must be stored if they are to be reused in the [main] section of the macro. This is achieved by the statement GetParam. Wintrack macros provide 16 parameter registers, each of which can hold the user selection for one parameter of any type. The combination {1} iFile tells Wintrack to store the selection made in the field case file of the dialog in parameter register 1. Take=Dir instructs Wintrack to use only the directory part of the selection and to disregard the file name. Finally, GuideClr removes the guide window from the screen and clears all its text lines.

The second block of statements in the [dialogs] section is built in a similar way as the one just explained. Its purpose is to display the Arena Properties dialog, let the user specify a custom setup file, and then store the file name in parameter register 2. Note that this time, Take=Dir has been omitted from the GetParam statement: Wintrack will store the entire path including the file name. Type=Custom preselects the option custom with setup file in the dialog field Type and makes the field inaccessible to the user. /dh/iFile lets the user specify a file name in the dialog field located next to the preselected option and presents the last used file as a default.

The third block of statements is again very similar. Its purpose is to display the Analyze Case Document dialog box, preset Variable definition to the option from custom file, and let the user specify a custom variable definition file. The specified file name is stored in parameter register 3.

The [main] section

Until now, only dialog boxes have been displayed. The [main] section of the macro contains the statements which will do the real work. Each statement is the equivalent of a Wintrack menu command. The first statement, Aprp, is the equivalent of the Arena Properties command you normally access by selecting Arena Properties from the Options menu. It opens the custom setup file specified for the iFile parameter. In this example, Type=Custom tells the command to load a custom setup file and iFile={2} specifies the content of parameter register 2 as the file to be loaded. As you might remember, parameter register 2 stores the selection made by the user while the Arena Properties dialog was displayed.

The second block of statements begins with Opca, the equivalent of the Open Case Document command. iFile={1}SWIM1.WTR specifies SWIM1.WTR as the name of the case file to be opened and the content of parameter register 1 as the directory where to look for the file. As you might remember, parameter register 1 stores the directory part of the selection made by the user while the Open Case Document dialog was displayed. Fmat=Min instructs the command to open the document minimized as an icon. The user probably will not pay attention to the contents of case windows while the macro is running, so the time needed to draw all the paths and setup objects can be saved. Next, Anly analyses the opened case document. Vdef=File tells the command to process a custom variable definition file and iFile={3} specifies the content of parameter register 3 as the file to be used. If a scrollsheet with the appropriate columns is currently open, the results are appended to it as instructed by Rprt=Chain. Else a new scrollsheet is created. Finally, Clca closes the case document.

The next three blocks contain the same combination of statements as the one just explained. They open and analyze three more case documents. Each Anly statement appends one more line to the scrollsheet.

Lesson 13 - Parameter tables for macros will teach you how to extend the power and versatility of Wintrack macros by using scrollsheet as parameter tables.