ANSYS Macro Programming with the *USE

Command

Figure 1: Macro for *USE Access

This article illustrates APDL programming with subroutines through the *USE command and
a macro library file. One large macro file can be used to execute many related subroutines and
optionally to define and support many toolbar buttons that execute complex procedures.
Construction of a Macro File with Subroutines
There is a way to write APDL programs that contain their subroutines in a single file, taking
advantage of the *USE command. A package of macros for one purpose does not have to
consist of a series of .mac files stored in one or multiple locationsall can be packaged in a
single .mac file. This can aid simplicity in version control and distribution. The technique keeps
all related macros inside one source file. An example illustrates.
This example starts in a main routine by declaring itself as a macro library with the *ULIB
command. The *ULIB command calls its own file using its own file name. It calls subroutine
macros inside itself with the *USE command. These subsidiary macros are positioned after the
main macro ends with the /EOF command. The principal trick in getting this technique to
work is to immediately follow each /EOF command that ends a block with the Label for the
next *USE macro block. Comments on each section follow the Label for the block that is a
subsidiary macro for the *USE command.

In addition to permitting a structured approach to programming, macros inside the resulting

macro library can be called by toolbar buttons that employ the *USE command, as long as the
*ULIB command is not reset inside any of the macros or by other user actions or macros. The
*CREATE command does not have to be used to create macro files that are called by toolbar
buttons for the purpose of user post-processing. The *CREATE command could still be used
inside the main routine, or a *USE subsidiary macro could be employed, to create Tcl/Tk files.
Except for ARGn parameters inside a macro, all other ANSYS scalar parameters, arrays,
coordinate systems, components and component assemblies have global scope. This complicates
programming. The following example would be stored in a macro file called mytest1.mac,
which declares itself with a *ULIB command.

! Programming ANSYS Macros with callable "Subroutines" in one file.

! This creates a one-file source macro that contains many sub-macros.
!
! Comments go here.
! This "main" routine calls "subroutine" macros further below.
!
! IMPORTANT: Place nothing between /EOF and the next data block label.
<==
!
! This first block is the main routine, which can do various things.
! It is ended by an /EOF command, which is followed by data blocks
! for various "subroutine" macros.
!
*ULIB,mytest1,mac ! Declare this macro file as a macro library
*USE,part1
! Call the first "subroutine", if desired
*USE,part2
! Call the second "subroutine", if desired
! Exiting if no Toolbar actions are wanted...
*ULIB
! Un-declare macro library
*msg,UI
! Send completion message to user
FINISHED
!
! The following /EOF command ends the first block.
/EOF
PART1
! Part 1 of the macro library--the first label.
!
! Description of part 1 of the macro library goes here. Commands follow.
!
*msg,UI
Part 1 of the macro
/wait,1

! End of "part1"
/EOF
PART2
! Part 2 of the macro library,--the second label.
!
! Description of part2 of the macro library.
!
*msg,UI
Part 2 of the macro
/wait,1
! End of part 2
/EOF

Figure 2: Example of *USE Access to Subroutines

Below is the note that appears at the end of the run of the above macro:

Figure 3: Closing Message

Support of Toolbar Buttons
If a macro library as above is to create and support toolbar buttons, either the main routine
above, one of its subroutines, or an independent macro can be used to refer to the macro
library with the *ULIB command, and define a set of toolbar buttons with the *ABBR
commands. The toolbar abbreviations would execute *USE commands that run the desired
macro block in the macro library file. The macro block, starting with a Label as above, could run
a complex sequence of commands.
The following example declares itself as a macro library with *ULIB, and creates two toolbar
buttons. It does not use a second *ULIB command to un-declare itself, so the toolbar buttons
will continue to function as long as mytest2.mac is the active macro library. Note that a toolbar
button could be defined to run a block that un-declares the macro library, and replaces the toolbar
buttons before ending. An ABBSAV and ABBRES command pair refreshes the toolbar to make
the new buttons visible. The following commands would be in a macro file called
mytest2.mac:

! Example of Toolbar Button support in a macro library.

*ULIB,mytest2,mac ! Declare this macro file as a macro library.
*ABBR,Part_1,'*USE,part1' ! The first abbreviation.
*ABBR,Part_2,'*USE,part2' ! The second abbreviation.
abbsav
! Write the toolbar abbreviations.
abbres
! Refresh the abbreviations.
! The following /EOF command ends the first block.
/EOF
PART1
! Part 1 of the macro library--the first label.
! Demonstrate an action
*msg,UI
Part 1 of the macro. The Part_1 Toolbar button was clicked.
/EOF
PART2
! Part 2 of the macro library,--the second label.
! Demonstrate an action
*msg,UI
Part 2 of the macro. The Part_2 Toolbar button was clicked.
/EOF

Figure 4: Support of Toolbar Buttons

Clicking either of the two toolbar buttons, Part_1 or Part_2, will execute the block of commands
as entered into the *ABBR commands in the main first part of the above macro. If the *ULIB
command is executed without arguments, the new toolbar buttons cease finding the assigned
blocks.
The following figure shows the result of clicking the Part_1 button in the Toolbar:

Figure 5: Response to a Toolbar Button Click

Conclusion
A macro library file identified by the *ULIB command can access blocks inside itself with
*USE commands, passing argument lists are required. This gives the user an APDL
programming approach that permits a main routine, followed by many subroutines, all
contained in one source file. The approach lets users employ one source file, rather than a large
set of macro files that must be kept together, when complex APDL programming is wanted.
A supplementary use of a macro library is to support a set of Toolbar buttons that execute blocks
inside the macro library by executing *USE commands when clicked. This permits Toolbar
buttons to execute complex APDL command sequences contained inside the blocks.
These approaches aid the use of complex APDL programs and Toolbar button actions, giving
more power to ANSYS users.
Critical to operation of the APDL macro library is to follow an /EOF command immediately
with the Label for the next block of commands.