Contents - Index
A macro is a set of instructions to EES. Macros can only be used in the Professional license. The instructions contained in a macro allow EES to open a file, solve the equations, create and solve a table, store calculated results in a file, produce a plot, print results, and other functions. In fact, all of the capabilities provided with the menu commands in EES can be implemented with macro instructions as well as many capabilities not provided with the menu commands. Variables can be set to values in a macro, just as they can be set in the Equations window. The macro provides commands for looping and logic. In addition, EES can directly communicate with MATLAB, Microsoft EXCEL and WORD using macro commands as well as other programs and the serial port. The macro commands are very powerful.
Macro commands can be read from an ASCII file having an .emf file name extension or from one of the tabbed edit windows in the Macro Window. They can also be embedded in the Equations window with the $RunMacroBefore or $RunMacroAfter directives. The information provided here explains how to create, save, and play macros in the Macro Window.
Creating an EES Macro File
The easiest way to create an EES Macro file is to select the New Macro command in Macros Menu. After selecting this command, this action will open the Macro Window (if it not already open) and create a tabbed input window for the macro instructions, similar to that shown here.
The tab will show the name of the macro file. By default, the new macro is given a name Macro N (where N is the tab number) and set to be saved with the currently open EES file. This name can be changed by selecting Rename Macro from the popup menu that appears when you click the right-mouse button on the tab.
This popup window also offers the option to save the macro in a separate .emf file rather than with the EES file. If this option is selected, the tab name will end with .emf.
The Macro Window can be sized, moved or minimized as for any window. If the Macro Window is minimized or hidden behind other windows, use the Macro Window menu command in the Windows menu to bring it to front.
The Macro Window provides a toolbar on the right side of the window with nine buttons. These buttons have the following functions.
Note that the Macros menu provides a similar set of commands. The commands in the Macro menu can be applied to any one of the macro files in the Macro Window, whereas the commands on the toolbar are directed to the macro that is foremost in the Macro window. The green Play Macro button is also displayed in the speed bar below the main EES menu bar when the Macro Window is open. Clicking the Play button on the speed bar will play the macro that is foremost in the macro window.
When the Macro Window is visible, macro equivalents of the instructions you enter into EES with the normal menu commands will be entered into the foremost macro window, provided that it set to record macro commands. In this case, (recording) will appear in the caption of the Macro Window. You will hear a 'pop' sound when the command is added to the Macro window. For example, when you enter the Solve command, EES will add a line to the Macro Window of the form.
You can prevent the contents of the Macro window from being changed by clicking the Record macro commands button in the toolbar or selecting the Record Macro Commands menu item in the Macros menu. Note that you will be asked to confirm that you want to keep the Macro Window if you use the New or Open commands.
The macro command window is editable, so that you can modify the commands that appear in this window, add new commands or delete them if you wish. See the list of Macro Commands. Clicking the Play button will signal EES to play the macro commands that appear in the window starting at the top.
The Macro Window has a horizontal splitter bar. The upper window shows the macro commands. The lower window displays the log file as shown below. If you do not wish to see the log file, pull the splitter bar to the bottom of the screen or, more simply click the small log window size control shown in the figure below. If you want to restore the log window to its last position, again click the log window size control.
Note that logging and displaying the log window requires computer time that may affect the operation of a macro in time-sensitive operations, such as reading and writing to the serial port. It is best to close the log window and turn off logging with a Log Off macro command when doing time-sensitive operations.
Right-clicking on a tab in the Macro Window will bring up a popup menu providing the options to Rename, specify how the macro is saved, Close or Clear the log file for the selected macro, as shown below.
As of version 10.688, macro files can be saved with the.EES file, rather than in separate .emf files. By default, new macros are set to be saved with the .EES file. To save a macro in a separate .emf file, select the Save Macro in .emf file command. A check mark will be displayed to the left of the menu item showing which save option is selected. Also, if a macro is set to be saved in an .emf file, the .emf filename extension will appear in the tab name. References to the macro should use the same name as displayed in the tab. If the macro is set to be saved with the .EES file, then all of the information relating to the macro will be saved when the .EES file is saved and restored when the macro is opened. This option is convenient as it eliminates the need for providing and opening separate .emf files.
Multiple macro files can be open. The Play button will execute the macro instructions for the selected macro file, i.e., the file whose tab is foremost. The order of the tabs can be changed by dragging a tab to the desired location. Only one macro can be playing at one time.
The Close button at the right of the Macro Window title bar closes (hides) the Macro Window, but does not affect the macro files. The visibility of the Macro Window can be restored by selecting Macro Window from the Windows menu
. To close a tabbed Macro file, either right-click on the tab and select Close Macro or click the X button on the toolbar. (You can also select the Close/Delete command in the Macros menu.) The action taken depends on whether the macro is set to be saved with the .EES file or in a separate .emf file. If it is set to be saved with the .EES file, the macro file will be deleted. The contents of the file will be lost. A confirmation that you want to delete the file will be presented.
If the macro file is set to be saved in an external .emf file and f any changes have been made to the macro file since is was last saved, you will be prompted to save the file.
Clicking the right mouse button in the Macro window will bring up the following pop-up menu.
Note that text following // is considered to be comment up to the end of the current line. Selected lines can be commented or uncommented by clicking the right mouse button and selecting the Comment or Uncomment menu command in the popup menu.
The Print command will print the text that is selected in the Macro window on the printer selected with the Printer Setup command. If no text is selected, the entire contents of the Macro window will be printed.
EES variables can be assigned a value in the macro window or in a macro file. For example, variable X_o is assigned a value of 0 in the above macro window. This assignment is equivalent to having X_o being assigned a value in the Equations window. If a variable is assigned a value in a macro file, it cannot be reassigned in the Equations window. Note that values of variables that are assigned within the Macro Command Edit window or with the $RunMacroAfter directive will be shown in the Macro Variables tab of the Solution window.
One purpose of the macro capability is to allow an external program to use the EES solving engine. Using the macro file, EES can be instructed to open an existing EES or .TXT file and solve the equations in that file. EES macro files provide instructions to save the contents of the Solution and Parametric Table windows so that the solution can be returned to the program that called EES. The Solution or Parametric table can also be copied to the clipboard using the Copy macro command.
If a Repeat ..... Until (test condition) construct is included in the macro file, the commands between the Repeat and Until keywords (which are on separate lines) are repeated until the test condition (e.g., X-Y>1000) is true. Pressing the Esc key or clicking the Stop button in the tool palette will stop execution. A Pause command can be included in the macro file so that EES will pause for a specified time period between each execution of the macro commands. With these commands, it is easy to interface EES to a data acquisition program that outputs data to a file or to the Clipboard as specified time intervals. EES can repeat its calculations with each new set of data placed in the file or on the clipboard. The Repeat Until construct is also useful for solving periodic steady-state problems.
Long macro commands may be placed on multiple lines by placing a line break character (&) at the end of the line. Multiple spaces are ignored. Here is an example of a long macro command broken into two lines.
New3DPlot Name='Points' Table=ARR X=XA[i] Y=yA[i] Z=zA[i] XMin=-1.25 XMax=1.25 YMin=-1.25 YMax=1.25 ZMin=-0.25 ZMax=0.75 &
Rows=1..NA Type=Polygon Lines=0 Symbol=1 SymbolSize=10 Color=Red
A macro file can also be embedded in the Equations window (without using the Macro Window) between the $RunMacroBefore or $RunMacroAfter and $EndMacro directives.
Using a Macro to Communicate with EXCEL or WORD
Using a Macro for Serial Port Communications
Running a Macro from an External Program