Contents - Index
A macro is a set of instructions to EES that are read from an ASCII file or from one of the tabbed edit windows in the Macro Window and automatically executed. Macro files can only be used in the Professional license. The filename extension for a macro file is .emf, which signifies EES Macro File. The instructions contained in the file 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 with macro commands as well as other programs and the serial port. The macro commands can be very powerful.
Using the macro file capability, EES can be run from the Windows command line, from the Macro Play button in EES, or it can be controlled from another program using Dynamic Data Exchange (DDE) commands. The macro file name is placed after the EES executable file name. For example, to start EES and have it run the commands in file myMac.emf stored in the C:\EES32 directory, you would enter:
The .emf filename extension is required. Otherwise EES will consider the file to be a normal EES file.
When EES is started with this command, it will remain hidden while it opens the macro file and executes each of the instructions in that file. Provided that no errors are encountered, all of the instructions will be executed in the order in which they appear and then EES will quit. EES writes an ASCII log file that indicates what instructions it has completed and any error messages. By default, the log file name is EESMacro.log and it is placed in the same directory as the .emf file. However, the log file name can be specified by placing a LogFileName macro command anywhere in the macro file.
Creating an EES Macro File
The easiest way to create an EES Macro file is to select the Open or Create Macro command in the File menu or the Macro Window button in the menu tool bar. After selecting this command, EES will prompt the user to provide a name for the macro file. Enter an existing macro file name to open that file or a new name to create a new macro file. 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 short name (without any directory information) of the macro file. 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 green Play Macro button is also displayed in the toolbar below the main EES menu bar. Clicking the Play button will play the macro in the foremost macro window.
When the Macro Window is visible, it will accumulate the macro equivalents of the instructions you enter into EES with the normal menu commands. For example, when you enter the Open command, EES will add a line to the Macro Window of the form.
OPEN C:\XXX .EES
You can prevent the contents of the Macro window from being changed by clicking the lock button in the toolbar.
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. When you are done entering instructions, select the Save Macro button on the toolbar to save the contents of the tabbed window. Clicking the Play button will signal EES to play the macro commands that appear in the window starting at the top. If the Log window is open and logging is enabled, you will see a display of each macro command as it is executed at the bottom of the Macro Window, as explained below.
Right-clicking on a tab in the Macro Window will bring up a popup menu providing the options to Save, 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. To save a macro with the .EES file, select the Save Macro with .EES file option. A check mark will be displayed to the left of the menu item when this option is selected, as shown in the following figure. Also, the .emf filename extension will be removed from the tab name. References to the macro should use the same name as displayed in the tab. All of the information relating to the macro will be saved with the .EES file 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.
To close a tabbed Macro Window, either right-click on the tab and select Close Macro or click the X button on the toolbar. If any changes have been made to the macro file since is was last saved, you will be prompted to save the file. Click the X button at the upper right of the Macro Window to close all open macro files and hide the Macro window. NOTE: If you close a macro that is to be saved with the .EES file, it will not be save and the contents of this macro window will be lost.
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.
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 at the cursor location 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.
Once a macro program has been entered, it can be saved as an .EMF (EES Macro File) or with the .EES file, as indicated above. If the macro is saved in a separate .emf file, you can add a $Include MyMacro.emf directive in the Equations window. In this case, the Macro Window will open and load the macro when the file is opened. The advantage of saving the macro with the .EES file is that separate .emf files are not needed. It is possible to have multiple saved macro files opened in this way by providing a $Include directive for each macro file.
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 $RunMacroAfter and $EndMacro directives.
Using a Macro to Communicate with EXCEL or WORD
Using a Macro for Serial Port Communications