Receive Email or Text: Critical Points in ANSYS® Run
ANSYS APDL language provides an email function available to users in Mechanical APDL as a command and also in Workbench Mechanical via inserted Command Snippets.
In writing macros or developing command snippets for runs that may be very lengthy or on a remote machine where continued surveillance is impractical, the functionality can provide the analyst with notification of the run’s status at critical points (e.g., completion or failure of a portion of a staged or coupled analysis, completion or failure of an entire run, etc.). This can become quite valuable in an instance where a colleague is waiting for the machine (or license) to free up; or perhaps the run is on a compute cloud and the company is paying for every hour the cloud machine is not in idle status; or maybe a critical deadline is approaching and the project cannot afford lost time due to a failed run over a weekend. The functionality can be extended to even include text messaging to a cell phone.
This article illustrates how to set up the email/text functionality, test it, and implement it. The article shows the procedure using ANSYS version 14.5.7 but can easily extrapolate to other versions. In developing this document, the procedures were performed and tested on a Windows 7 64-bit operating system using Microsoft Outlook 2013 on an exchange server. Applicability to other Windows operating systems is likely very similar. But usage on alternative systems (e.g., Linux) is not covered herein. More specifically, the functionality is likely usable on other systems since the ANSYS Help documentation mentions no limitations in that regard; however, details for implementing the function on other systems is excluded from this document.
Step 1—Adding Directory to System Path for Emailer
ANSYS’ ability to send emails is accomplished with a 3rd party email program called BLAT. BLAT is a simple program that operates from the operating system’s Command Prompt window via system commands. Once installed and operating, the user does not work within the Command Prompt anymore. Rather, ANSYS conveys the commands to the system behind-the-scenes with either the /MAIL or /SYS commands.
When ANSYS installs on a machine, the BLAT files are copied to the installation directory but not actually installed on the machine. The .EXE and .DLL files are:
C:\Program Files\ANSYS Inc\v145\ansys\bin\winx64\blat.exe
C:\Program Files\ANSYS Inc\v145\ansys\bin\winx64\blat.dll
To install, the user needs to need to see if the above directory (C:\Program Files\ANSYS Inc\v145\ansys\bin\winx64) is on the system's "path." This step is not addressed in the ANSYS Help Menu in the /MAIL write-up, but is necessary for operation. Go to:
Start -> All Programs -> Accessories -> Command Prompt
path hit enter
Many directories will be listed. Review them to see if the ANSYS directory is already in the system's path. If not, it needs to be added. To do so, go to:
Start -> RMB on My Computer -> Properties -> Advanced System Settings -> Advanced Tab -> Environment Variables -> Scroll to "Path" in lower portion of window
Highlight Path and select Edit. In the Edit screen, add the ANSYS directory by scrolling to the end of the path list, typing a semicolon, and then the ANSYS directory. Hit OK to close out all of the screens. Reboot the machine. Verify the ANSYS directory has been placed in the system path, by again typing “path” in the Command Prompt.
Once this step has been completed, it should not need done again. See Figure 1 below.
Figure 1: Adding ANSYS Directory to System’s Path Variable
Step 2—Installing Email Program
If not still open, reopen the Command Prompt to install BLAT. To begin installation, migrate to the ANSYS BLAT directory by typing:
cd c:\program files\ansys inc\v145\ansys\bin\winx64 hit enter
blat -install <SMTP domain address or IP address> <sender’s (the user) email address> hit enter
Once this has been completed and BLAT has been successfully tested, it should not need to be done again. See Figure 2 below. Note that <SMTP domain address or IP address> is the SMTP address for the user’s email server. Usually, an IT department would be able to provide this information. This is the server through which BLAT will send the emails. Often times, companies use Microsoft Outlook as their email client software, which can be configured to operate as an exchange system with an exchange domain address. However, most exchange systems also have an SMTP service and that is the address that would be needed for this BLAT installation, as opposed to the exchange domain address. Towards the conclusion of the document, the BLAT help menu is discussed; the help menu discusses BLAT also being able to support NNTP, POP3, and IMAP service domain addresses.
Figure 2: Installing BLAT
Step 3—Testing Email Program as Stand-Alone
Now test BLAT by itself. Open Notepad and type a few sentences in it. Save it to the desktop with an arbitrary name (test.txt). Again working from the Command Prompt, type:
blat c:\users\<user name>\desktop\test.txt -to <recipient’s email address> hit enter
Note that <user name> represents the user name assigned to the analyst on the PC. Also note that <recipient’s email address> may be any valid email address, to include the analyst’s (i.e., sending themselves the email). The contents of the file should then arrive in the recipient’s email inbox shortly. Note that this system command to execute BLAT does not need done from any specific working directory in the Command Prompt (i.e., there is no need to issue the "cd" command to migrate to a specific directory before issuing the command). Also note that there is the option to save test.txt elsewhere or give it another name so long as the BLAT command is issued with the correct directory and file name. See Figure 3 below.
Figure 3: Testing BLAT as Stand-Alone
Step 4—Testing Email Program from Workbench
Now the functionality can be tested in Workbench Mechanical. Note that the functionality can also be used in APDL with the same commands in a macro. Typically, an analyst may want to send the email file upon completion of a run. The example here illustrates where to enter the Command Snippets for a completed run. But it is possible to enter the commands elsewhere in Workbench Mechanical for notification of other critical points. With that, open Mechanical and:
RMB on Solution -> Insert -> Commands
Now the analyst can type commands in the Commands window that will execute immediately after the solution is done. There are various ways to create the file that will be emailed. Two options are: either the analyst can pre-create it using Notepad, WordPad, or other text editor and place it at a specific location on the hard drive or ANSYS can create the file using the *create command such as:
I am a test email message file.
Additionally, the analyst can tell ANSYS to simply redirect the run's output to a file using the /OUT command as the example shows in the Help Menu for /MAIL. Creating the file in one of these manners is up to the individual. Once it has been created, there are 2 ways to send the email (/MAIL or /SYS command) as discussed below. Note that you can RMB on other pieces of the Outline Tree and enter other Command Snippets if there was a need to insert this email command (or another command) elsewhere in the model's run.
Step 4a—Email From Workbench Mechanical Using /MAIL
The procedures set forth in the Help Menu should be followed. In other words, issue the /MAIL command with field 2 blank, email address in field 3, directory and file name in field 4, and file extension in field 5. See Figure 4 below.
Figure 4: Using /MAIL from Workbench Mechanical
Step 4b—Email From Workbench Mechanical Using /SYS
This command is usable anywhere in ANSYS to issue a command that a user would otherwise normally issue in the system Command Prompt. So therefore, the user can issue the command as done above in Step 3. See Figure 5 below.
Figure 5: Using /SYS from Workbench Mechanical
By using /SYS, the user is effectively executing the BLAT program from the system Command Prompt. When doing it this way, many options exist in BLAT that the analyst can use, such as CC (for colleagues), subject lines, time delays, etcetera. Review the attached BLAT help menu (accessibility is discussed towards the conclusion of this document) to learn about these various options. Using the /MAIL command prohibits these options and is more restrictive with regards to BLAT’s available options.
Figure 6 below shows an example of a newly received email from BLAT. The file was titled JobDone.txt and the contents of the file were as shown in the reading pane of Outlook (Your ANSYS run … great day!)
Figure 6: Example Email Received in Outlook
Step 5—Sending a Text Message to Cellular Device
Many cell phone text inboxes can receive emails from a typical email provider (e.g., Outlook, Hotmail, Gmail, etc.). It is necessary to know the cell phone inbox’s “email address” (<number>@<service address>), which may require a phone call to the cellular service provider for assistance. Two examples are:
for transmitting multimedia messages
for transmitting plain text messages
To integrate this functionality with the ANSYS commands, it is necessary that the email be first sent to the user’s typical email account (e.g., Outlook), since BLAT typically will not send directly to a cell phone address like those shown above. Once in Outlook, a “Rule” can be created that will forward the message to the cell phone address upon detecting certain criteria in the message (e.g., if subject contains “jobdone,” then forward to cell phone). See Figure 7 below.
Figure 7: Creating an Outlook Rule for Forwarding to Cell Phone
The use of Outlook will require some testing for each user’s application. Depending on the structure of the email system, the PC may or may not need to be on and Outlook open for the Rule to execute. In other words, sometimes, the Rule may execute itself from the exchange server when Outlook is closed, depending on the system.
The use of other email systems (Gmail, Hotmail, Yahoo Mail, etc.) will vary depending on whether or not the service allows the user to establish Rules.
The most common issue with setting up this email/text service involves getting BLAT to send emails stand-alone (i.e., Steps 2 & 3) since once it is set up and tested, the remaining steps are rather straightforward and build from there. As a result, some tips to help with BLAT failures are:
- It is often useful to issue the Step 3 command having an additional command tagged at the end:
|-debug||will direct debug output to the Command Prompt screen|
|-debug >debug.txt||will direct debug output to a text file in the currently active directory shown in the Command Prompt|
The next section of this article describes how to access the BLAT help menu, which will give a description of this command. Using the debug command will help the user determine what caused BLAT to fail.
- Review the syntax being used in the Step 3 Command Prompt. See the following section of this document that gives direction for accessing the BLAT help menu, which provides the syntax for all BLAT commands.
- Review the SMTP address being used in Step 2, which may require involvement from the company IT department. An exchange address typically will not work, but many exchange systems offer an accompanying SMTP service. As shown in the BLAT help menu (discussed in the following section) it also supports NNTP, POP3, and IMAP service domain addresses. Note that if the user needs to change the address, a simple redo of Step 2 will suffice. It is not necessary to “uninstall” and “re-install” BLAT. A redo of Step 2 will simply overwrite the computer registry keys each time Step 2 is executed for a revised installation.
- Some special characters (e.g., !%$#^*) in file names and/or directories will cause failures.
- Some email server domains require authentication and perhaps a password before allowing BLAT to send through the server. BLAT installation options can be used in Step 2 to set up these parameters for the user’s domain server.
BLAT Help Menu
The BLAT help menu can be accessed from a system Command Prompt window by issuing either of the following two commands:
|blat -h||will print the help menu on the Command Prompt screen|
|blat -h >blathelp.txt||will direct the help menu to a text file in the currently active directory shown in the Command Prompt|
ANSYS Mechanical APDL and Workbench Mechanical provide a notification system to keep the analyst informed of a run’s status when it is impractical for continued surveillance of the run. With a few easy steps to install and test BLAT, ANSYS can provide a user with real-time updates as to the status of their analysis, either to an email account or to a cellular device. This could mean hundreds or thousands of dollars in savings, when colleagues may be waiting for licenses, when cloud compute machines are charging by the hour, or when a critical deadline is fast approaching with no time for mistakes.