Beruflich Dokumente
Kultur Dokumente
Table of Contents
ANSYS APDL Programmer's Guide
1 What is APDL?
3 Using Parameters
6 Encrypting Macros
1 What is UIDL?
5 Advanced Topics
6 Programming Example
1 What is APDL?
2 Adding Commands to the Toolbar
2.1 Modifying the Toolbar
3 Using Parameters
3.1 Parameters
6 Encrypting Macros
6.1 Preparing a Macro for Encryption
Convention Indicates
File names, which may or may not include directory paths. These are
shown as lower-case, bold text, unless case is significant. Examples are
path/filename.ext shown with the UNIX directory separator character "/" (slash); if you are
using a Microsoft Windows system, use "\" (backslash) as your directory
separator character.
Command input listings, ANSYS output listings, and text that a user
command,arg1,arg2
enters are shown in fixed-width font.
Information that supplements the main topic being discussed, such as
Note-
important tips or guidelines.
Actions or situations that can shut down ANSYS, damage files, cause loss
Warning:
of data, etc.
This guide was designed for ANSYS users that have some programming skills and wish to tap
the power of the ANSYS Parametric Design Language (APDL). APDL is a scripting language
that is very similar to Fortran 77. The guide describes how to define parameters (variables),
how to create macro programs using APDL, how to use APDL for simple user interaction, how
to encrypt an APDL macro, and how to debug an APDL macro.
The UIDL Programmer's Guide covers the User-Interface Design Language (UIDL) including
how to modify or construct menus, dialogs, and online help from within ANSYS.
ANSYS provides a set of Fortran 77 functions and routines that are available to extend or
modify the program's capabilities. Using these routines requires relinking the ANSYS
program, resulting in a custom version of ANSYS. ANSYS release 5.4 and later provides an
external commands capability to create shared libraries available to ANSYS (either from ANSI
standard C or Fortran 77). You can use this feature to add custom extensions to ANSYS
without the need to rebuild the ANSYS executable.
This guide describes the formats for various ANSYS files plus a group of utilities and routines
that you can use to directly access the ANSYS database. You can also use these capabilities to
access data in any of the binary files that ANSYS writes or uses.
The entire set of programmer's guides can be accessed online as HTML files or downloaded (in either
HTML or Postscript format) through the ANSYS documentation web site,
http://www.ansys.com/Documentation/Manuals/872. You can also order a hardcopy version of the
set by downloading the Documentation order form from
http://www.ansys.com/ServSupp/Library/library.html
Chapter 1: What is APDL?
Go to the Next Chapter
Go to the Table of Contents for This Manual.
APDL stands for ANSYS Parametric Design Language, a scripting language that you can use to
automate common tasks or even build your model in terms of parameters (variables). APDL also
encompasses a wide range of other features such as repeating a command, macros, if-then-else
branching, do-loops, and scalar, vector and matrix operations.
While APDL is the foundation for sophisticated features such as design optimization and adaptive
meshing, it also offers many conveniences that you can use in your day-to-day analyses. In this guide
we'll introduce you to the basic features- parameters; macros; branching, looping, and repeating; and
array parameters-and show you some simple examples. As you become more adept at the language,
you will see that the applications for APDL are limited only by your imagination.
You can add frequently used ANSYS functions or macros to the ANSYS toolbar (creating macros is
covered starting in Section 4.1). You do this by defining abbreviations. An abbreviation is simply an
alias (up to eight characters long) for an ANSYS command, GUI function name, or macro name. For
example, MATPROP might be an abbreviation for a macro that lists material properties, SAVE_DB is
an abbreviation for the SAVE command, and QUIT is an abbreviation for the Fnc_/EXIT function
(which launches the "Exit from ANSYS" dialog box).
The ANSYS program provides two ways to use abbreviations. You can issue the abbreviation (and
execute the macro, command, etc. that it performs) by typing it at the beginning of a command line.
Or, if you're using the ANSYS GUI, you can execute the macro or command by pressing the
appropriate button on the ANSYS toolbar.
The toolbar, shown in the following figure, contains buttons that correspond to existing abbreviations.
While some abbreviations, such as SAVE_DB, are predefined, the abbreviations the toolbar contains
and the functions they execute are up to you. A single toolbar can hold up to 100 abbreviations (you
can "nest" toolbars to extend this number). You can redefine or delete abbreviations at will; however,
abbreviations are not automatically saved and must be explictly saved to a file and reloaded for each
ANSYS session.
● Clicking OK automatically updates the toolbar (using the *ABBR command requires that you
use the Utility Menu >MenuCtrls > Update Toolbar menu item to make your new
abbreviation appear on the toolbar).
● You can easily edit the abbreviation if required.
Where
Abbr
The abbreviation name that will appear on the toolbar button. The name can contain up to eight
characters.
String
The Stringargument is the name of the macro or command that Abbrrepresents. If Stringis the
name of a macro, the macro must be within the macro search path. For more information about
using macros, see Section 4.1. If Stringreferences an ANSYS picking menu or dialog box
(using UIDL), then specify "Fnc_string." For example, in the abbreviation definitions for
"QUIT," "POWRGRPH," and "ANSYSWEB" shown above, "Fnc_/QUIT,"
"Fnc_/GRAPHICS," and "Fnc_HomePage" are all unique UIDL function names which identify
the ANSYS picking menu or dialog box associated with the QUIT, POWRGRPH, and
ANSYSWEB abbreviations respectively. For more information about accessing UIDL
functions, see Section 5.6. The stringyou specify can contain up to 60 characters and it can't
include any of the following:
The new button is appended to the button bar as shown in the following figure.
Toolbar buttons are not persistent from one ANSYS session to the next; however, they are saved and
maintained in the database so that any "resume" of the session will still contain these abbreviations.
To save your custom button definitions, you must explicitly save them to a file through the Utility
Menu >MenuCtrls > Save Toolbar menu item (*ABBSAV command) and restore them for each
session using the Utility Menu >MenuCtrls > Restore Toolbar menu item (*ABBRES command).
You can do this programmatically in a macro.
Note-If any abbreviations already exist in the named file, the *ABBSAV command overwrites them.
The format of the abbreviations file is simply the APDL commands that are used to create the
abbreviations. Thus, if you wish to edit a large set of buttons or change their order, you may find
using a text editor to be the most convenient method. For example, the following is the file that results
from saving the default toolbar buttons.
/NOPR
*ABB,SAVE_DB ,SAVE
*ABB,RESUM_DB,RESUME
*ABB,QUIT ,Fnc_/EXIT
*ABB,POWRGRPH,Fnc_/GRAPHICS
*ABB,ANSYSWEB,Fnc_HomePage
/GO
The *ABB commands (the abbreviated form of *ABBR) define the buttons. The /NOPR at the top
turns off echoing to the log file while the /GO at the bottom turns log file echoing on.
*ABBR,PREP_ABR,ABBRES,,PREP,ABBR
PREP_ABR will appear as a button on the toolbar. Clicking it will replace the existing buttons with
the set of buttons defined in the prep.abbr file.
By defining abbreviations to restore these files and including those abbreviations in the appropriate
files, you can have a virtually unlimited number of abbreviations in a given ANSYS session. You can
even extend this concept and create your own menu hierarchy by nesting several abbreviation files. If
you implement such a hierarchy, it's a good practice to add an abbreviation as a "return" button in
each file to navigate back through the menus.
3.1 Parameters
Parameters are APDL variables (they are more similar to Fortran variables than to Fortran parameters). You don't need to
explicitly declare the parameter type. All numeric values (whether integer or real) are stored as double-precision values.
Parameters that are used but not defined are assigned a near-zero, or "tiny," value of approximately 2-100. For example, if
parameter A is defined as A=B, and B is not defined, then A is assigned the tiny value.
ANSYS uses two types of parameters: scalar and array. The first part of this chapter discusses information that is applicable
to both types. Starting with section 3.11, the information is specific to array type parameters.
Character strings (up to eight characters long) can be assigned to parameters by simply enclosing the string in single quotes.
APDL also provides several types of array parameters: numeric, character, and table (a special numeric type that
automatically interpolates values).
You can use a parameter (instead of a literal number or character string) as an argument to any ANSYS command; the
parameter is evaluated and its current value is used for that argument. For example, if you assign the value 2.7 to a
parameter named AA and then issue the command
N,12,AA,4
N,12,2.7,4
Valid:
ABC
PI
X_OR_Y
Invalid:
● Avoid parameter names that match commonly used ANSYS labels, such as:
❍ Degree of freedom (DOF) labels (TEMP, UX, PRES, etc.)
● Be aware that parameter names ARG1 through ARG9 and AR10 through AR99 are reserved for local parameters.
Generally, local parameters are used in macros (see Section 4.4). Use of these names as "regular" parameters is not
recommended.
● Make sure that parameter names don't match abbreviations defined with the *ABBR command. For more
information about abbreviations, see Section 2.1.
● Don't begin parameter names with an underscore (_). This is the convention reserved for parameters used by the GUI
and ANSYS-supplied macros.
This capability was added specifically for those who are developing APDL macros for large audiences. You can use this to
build macros that your ANSYS users and other macro programmers cannot list.
You can either assign values to parameters or retrieve values supplied by ANSYS and store these values in parameters. For
retrieving values from ANSYS, you can use either the *GET command or the various inline get functions. The following
sections cover these subjects in detail.
You can use an "=" as a shorthand way of calling the *SET command (this is the most convenient method). The format of
the shortcut is Name=Value, where Name is the name assigned to the parameter and Value is the numeric or character value
stored in that parameter. For character parameters, the assigned value must be enclosed in single quotes and cannot exceed
eight alphanumeric characters. The following are examples of "=" in use:
ABC=-24
QR=2.07E11
XORY=ABC
CPARM='CASE1'
In the GUI, you can either type the "=" directly in the ANSYS input window or in the "Selection" field of the Scalar
Parameter dialog box (accessed by the Utility Menu>Parameters>Scalar Parameters menu item).
It's a good practice to avoid assigning one or two character parameter names at startup to avoid conflicts with ANSYS
command line options.
Note-Remember that UNIX shells treat single quotes and many other non- alphanumeric characters as special symbols.
When defining character parameters, you must tell UNIX not to interpret the quotes by inserting a back slash (\) before the
single quotes. For example, the following defines two character parameters having the values `filename' and `200.'
If you use the ANSYS Launcher to start ANSYS, you can define parameters through the Interactive or Batch menu items
(using the -Name Value format described above).
If you are defining a large number of parameters at startup, you'll find it much more convenient to define these in the
start5x.ans file or through a separate file that you can load through the /INPUT command instead of the command line.
● The *GET command, which retrieves a value from a specified item and stores it in a specified parameter.
● The inline get functions, which can be used in operations. Each get function returns a specific value from a specific
item.
The *GET command (Utility Menu>Parameters>Get Scalar Data) retrieves an ANSYS-supplied value for an item (a
node, an element, an area, etc.) and stores it as a user-named parameter. Various keyword, label, and number combinations
identify the retrieved item. For example, *GET,A,ELEM,5,CENT,X returns the centroid x-location of element 5 and stores
the result as parameter A.
*GET,Par,Entity,ENTNUM,Item1,IT1NUM,Item2,IT2NUM
where
You can think of the *GET command as a path down a tree structure, from general to specific information.
The following examples show the *GET command in use. The first command below gets the material attribute (the MAT
reference number) of element 97 and assigns it to parameter BCD:
For some items, you can use inline "get functions" in place of the *GET command. A get function returns a value for an
item and uses it directly in the current operation. This allows you to bypass the dual steps of storing the value with a
parameter name and then entering the parameter name in an operation. For example, suppose that you want to calculate the
average x-location of two nodes. You could do the following using the *GET function:
1. Issue the following command to assign the x-location of Node 1 to parameter L1.
*GET,L1,NODE,1,LOC,X
2. Issue a second *GET command to assign the x-location of Node 2 to parameter L2.
A shorter method is to use the node location "get function" NX(N), which returns the x-location of node N. You can use it to
calculate the MID location without setting intermediate parameters L1 and L2, as is shown in the following example:
MID=(NX(1)+NX(2))/2
Get function arguments can themselves be parameters or other get functions. For instance, get function
NELEM(ENUM,NPOS) returns the node number in position NPOS for element ENUM. Combining functions,
NX(NELEM(ENUM,NPOS)) returns the x-location of that node.
Entity Status:
Locations:
Nearest to Location:
Number of the selected node nearest the X,Y,Z point (in the active coordinate system; lowest number for
NODE(X,Y,Z)
coincident nodes)
Number of the selected keypoint nearest the X,Y,Z point (in the active coordinate system; lowest number
KP(X,Y,Z)
for coincident keypoints)
Distance:
Distance between the centroid of element E and node N. Centroid is determined from the selected nodes
DISTEN(E,N)
on the element.
Angles:
Subtended angle between two lines (defined by three nodes where N1 is the vertex node). Default
ANGLEN(N1,N2,N3)
is in radians (see the *AFUN command to select degrees).
Subtended angle between two lines (defined by three keypoints where K1 is the vertex keypoint).
ANGLEK(K1,K2,K3)
Default is in radians (see the *AFUN command to select degrees).
Nearest to Entity:
NNEAR(N) Selected node nearest node N
ENEARN(N) Selected element nearest node N. The element position is calculated from the selected nodes.
Areas:
AREAND(N1,N2,N3) Area of the triangle with vertices at nodes N1, N2, and N3
AREAKP(K1,K2,K3) Area of the triangle with vertices at keypoints K1, K2, and K3
Area at node N apportioned from selected elements attached to node N. For 2-D planar solids,
ARNODE(N) returns edge area associated with the node. For axisymmetric solids, returns edge surface area
associated with the node. For 3-D volumetric solids, returns face area associated with the node.
Normals:
NORMNX(N1,N2,N3) X-direction cosine of the normal to the plane containing nodes N1, N2, and N3
NORMNY(N1,N2,N3) Y-direction cosine of the normal to the plane containing nodes N1, N2, and N3
NORMNZ(N1,N2,N3) Z-direction cosine of the normal to the plane containing nodes N1, N2, and N3
NORMKX(K1,K2,K3) X-direction cosine of the normal to the plane containing keypoints K1, K2, and K3
NORMKY(K1,K2,K3) Y-direction cosine of the normal to the plane containing keypoints K1, K2, and K3
NORMKZ(K1,K2,K3) Z-direction cosine of the normal to the plane containing keypoints K1, K2, and K3
Connectivity:
Element connected to node N. LOC is the position in the resulting list when many elements share the
ENEXTN(N,LOC)
node. A zero is returned at the end of the list.
Faces:
Element adjacent to a face (FACE) of element E. The face number is the same as the surface
ELADJ(E,FACE) load key number. Only elements of the same dimensionality and shape are considered. A -1 is
returned if more than one element is adjacent; A 0 is returned if there are no adjacent elements.
Node in position LOC of a face number FACE of element E. The face number is the same as
NDFACE(E,FACE,LOC) the surface load key number. LOC is the nodal position on the face (for an IJLK face, LOC=1 is
at node I, 2 is at node J, etc.).
Face number of element E containing the selected nodes. The face number output is the surface
NMFACE(E) load key. If multiple load keys occur on a face (such as for line and area elements), the lowest
load key for that face is output.
For 2-D planar solids and 3-D volumetric solids, returns the area of the face of element E
ARFACE(E)
containing the selected nodes. For axisymmetric elements, the area is the full (360°) area.
*STATUS
You can also access this information through either the Utility Menu>List>Other>Parameters or Utility
Menu>List>Status>Parameters>All Parameters menu items.
Note-Any parameters beginning or ending in an underscore (_) are not shown by the *STATUS command.
You can check the status of individual parameters by providing these as arguments to the *STATUS command. The
following example shows the status of the ABC parameter.
*STATUS,ABC
You can also check the status of specific parameters through the Utility Menu>List>Other>Named Parameter or Utility
Menu>List>Status> Parameters>Named Parameters menu items.
Note-Although ANSYS allows a maximum of 1000 parameters, fewer than 1000 are available to the user due to GUI and
ANSYS macro requirements. The number of parameters defined by the user interface (internal parameters) is listed by the
*STATUS command. The command *GET,par,PARM,,MAX returns the total number of parameters defined.
● Issue the "=" command, leaving the right-hand side of the command blank. For example, to delete the QR parameter
issue this command:
QR=
● Issue the *SET command (Utility Menu>Parameters>Scalar Parameters), but don't specify a value for the
parameter. For example, to delete the QR parameter via the *SET command issue the command as follows:
*SET,QR,
Setting a numeric parameter equal to zero doesn't delete it. Similarly, setting a character parameter equal to empty single
quotes (` `) or placing blanks within single quotes doesn't delete the parameter.
● As arguments to any applicable command field (that is, where alphanumeric input is expected)
● As macro name arguments for the *USE command (Utility Menu>Macro>Execute Data Block)
● As arguments to macro calls for *USE and for the "unknown command" macro. Any of the following macro calls
are allowed:
ABC='SX'
*USE,NAME,ABC
or
*USE,NAME,'SX'
DEF='SY'
NEWMACRO,DEF ! Calls existing macro file NEWMACRO.MAC
or
NEWMACRO,'SY'
Y=0
X=2.7
N,1,X,Y ! Node 1 at (2.7,0)
Y=3.5 ! Redefining parameter Y now does not update node 1
Conversely, you can force parameter substitution in titles, subtitles, and filenames by enclosing the parameter name with
percent signs (%). For example,
specifies a title in which the numerical value of parameter TM is substituted. Note that the parameter is substituted at the
time the title is used.
As with numerical parameters, you can force the substitution of a character parameter value in certain cases where
substitution would not occur otherwise. This is done by enclosing the character parameter name with percent signs (%).
Forced substitution of character parameters is valid for the following commands:
● /TITLE command (Title field). Specifies titles for various printed output.
● /STITLE command (Title field). Specifies subtitles, similar to /TITLE. (You cannot access the /STITLE command
directly in the GUI.)
● /TLABEL command (Text field). Specifies text string for annotation.
● /SYP command (ARG1 - ARG8 fields). Passes a command string (plus arguments) to the operating system. (You
cannot access the /SYP command directly in the GUI.)
● *ABBR command (Abbr field). Defines an abbreviation.
● Any filename or extension command argument. These arguments apply to commands such as /FILENAME,
RESUME, /INPUT, /OUTPUT, and FILE. (Direct parameter substitution is also valid in these fields.)
● Any 32 character field: A typical example is the directory path field that is available for many commands. (Direct
substitution is not valid for these fields.)
● As a command name in any command name field. Also as an "unknown command" macro name in field 1. For
example:
R='RESUME'
%R%,MODEL,DB
The following example of the command input method shows forced substitution for a subtitle definition and for a directory
name.
A='TEST'
B='.RST'
C='/ANSYS'
D='/MODELS/'
/STITLE,,RESULTS FROM FILE %C%%D%%A%%B%
SUBTITLE 1 =
RESULTS FROM FILE /ANSYS/MODELS/TEST.RST
/POST1
FILE,A,RST,%C%%D% ! Read results from /ANSYS/MODELS/TEST.RST
In addition to the more general applications already discussed, there are some specific instances where character parameters
are allowed for added convenience. The commands which are affected and details of usage are outlined below.
*ASK
This command may prompt the user for an alphanumeric string (up to eight characters enclosed in single quotes)
which is assigned to a character scalar parameter. (You cannot access the *ASKcommand directly in the GUI.)
*CFWRITE
This command writes ANSYS commands to the file opened by *CFOPEN. It can be used to write a character
parameter assignment to that file. For example, *CFWRITE,B='FILE'is valid. (You cannot access the
*CFWRITEand *CFOPENcommands directly in the GUI.)
Character parameters may be used for the VAL1and VAL2arguments of these commands. For the Operargument,
only labels EQ (equal) and NE (not equal) are valid when using character parameters. (You cannot access the
*IFand *ELSEIFcommands directly in the GUI.) Example:
CPARM='NO'
*IF,CPARM,NE,'YES',THEN
*MSG
Character parameters are allowed as input for the VAL1 through VAL8arguments. The data descriptor %C is used to
indicate alphanumeric character data on the format line (which must follow the *MSGcommand). The %C
corresponds to the FORTRAN descriptor A8. (You cannot access the *MSG command directly in the GUI.)
*VREAD
This command (Utility Menu>Parameters>Array Parameters>Read from File)can be used to read alphanumeric
character data from a file and produce a character array parameter. The FORTRAN character descriptor (A) may be
used in the format line which must follow the *VREADcommand.
*VWRITE
This command (menu path Utility Menu>Parameters>Array Parameters>Write to File) can be used to write
character parameter data to a file in a formatted sequence. The FORTRAN character descriptor (A) may be used in
the format line which must follow the *VWRITEcommand.
Although character parameters have much of the same functionality as numerical parameters, there are several instances
where character parameters are not valid.
● Character parameter substitution is not allowed for the Par argument of the *SET, *GET, *DIM, and *STATUS
commands.
● Interactive editing of array parameters (*VEDIT command) is not available for character array parameters.
● Vector operation commands, such as *VOPER, *VSCFUN, *VFUN, *VFILL, *VGET, and *VITRP, do not work
with character array parameters.
● When operating on character parameters, the specification commands *VMASK and *VLEN are applicable only to
the *VWRITE and *VREAD commands.
● Character parameters are not valid in parametric expressions which use addition, subtraction, multiplication, etc.
Example:
XYZ='CASE 1'
/TITLE,This is %XYZ%
APLOT
The title "This is CASE 1" will appear on the area plot.
You can then change the value of XYZ and the new title will appear on subsequent plots, even though you did not reissue
/TITLE.
XYZ='CASE 2'
X=A+B
P=(R2+R1)/2
D=-B+(E**2)-(4*A*C) ! Evaluates to D = -B + E2 - 4AC
XYZ=(A<B)+Y**2 ! Evaluates to XYZ = A + Y2 if A is less than B;
! otherwise to XYZ = B + Y2
INC=A1+(31.4/9)
M=((X2-X1)**2-(Y2-Y1)**2)/2
Operator Operation
+ Addition
_ Subtraction
* Multiplication
/ Division
** Exponentiation
You can also use parentheses for clarity and for "nesting" of operations, as shown above. The order in which the ANSYS
program evaluates an expression is as follows:
Thus an expression such as Y2=A+B**C/D*E will be evaluated in this order: B**C first, /D second, *E third, and +A last.
For clarity, you should use parentheses in expressions such as these. Parentheses can be nested up to four levels deep, and
up to nine operations can be performed within each set of parentheses. As a general rule, avoid using blank spaces between
operators in expressions. In particular, never include a blank space before the * character because the rest of the input line
(beginning with the *) will be interpreted as a comment and therefore will be ignored. (Don't use this convention as a
comment; use an exclamation point (!) for this purpose.)
GDIS(x,y) Random sample of a Gaussian (normal) distribution with mean x and standard deviation y.
Sine, Cosine, and Tangent of x. x is in radians by default, but can be changed to degrees
SIN(x), COS(x), TAN(x)
with *AFUN.
SINH(x), COSH(x), TANH(x) Hyperbolic sine, Hyperbolic cosine, and Hyperbolic tangent of x.
Arcsine, Arccosine, and Arctangent of x. x must be between -1.0 and +1.0 for ASIN and
ASIN(x), ACOS(x), ATAN(x) ACOS. Output is in radians by default, but can be changed to degrees with *AFUN.
Range of output is -pi/2 to +pi/2 for ASIN and ATAN, and 0 to pi for ACOS.
Arctangent of y/x with the sign of each component considered. Output is in radians by
ATAN2(y,x)
default, but can be changed to degrees with *AFUN. Range of output is -pi to +pi.
VALCHR (CPARM) Numerical value of CPARM (if CPARM is anumeric, returns 0.0).
Character value of numerical parameter PARM. Number of decimal places depends on
CHRVAL (PARM)
magnitude.
To write parameters to a file, use the PARSAV command (Utility Menu>Parameters>Save Parameters).
The parameters file is simply an ASCII file consisting largely of APDL *SET commands used to define the various
parameters. The following example shows the format of this file.
/NOPR
*SET,A , 10.00000000000
*SET,B , 254.3948750000
*SET,C ,'string '
*SET,_RETURN , 0.0000000000000E+00
*SET,_STATUS , 1.000000000000
*SET,_ZX ,' '
/GO
To read parameters from a file use the PARRES command (Utility Menu>Parameters>Restore Parameters)
If you wish, you can write up to ten parameters or array parameters using FORTRAN real formats to a file. You can use this
feature to write your own output file for use in other programs, reports, etc. To do this, use the *VWRITE command
(Utility Menu>Parameters>Array Parameters>Write to File). The *VWRITE command command is discussed in
Section 3.11.7.
ARRAY
This type is similar to FORTRAN 77 arrays and is the default array type when dimensioning arrays. As with
FORTRAN arrays, the indices for rows, columns, and planes are sequential integer numbers beginning with one.
Array elements can be either integers or real numbers. This type can have up to 10242-1 rows, up to 255 columns,
and up to 7 planes.
CHAR
This is a character array, with each element consisting of an alphanumeric value not exceeding eight characters. The
indices for rows, columns, and planes are sequential integer numbers beginning with one. This type can have up to
10242-1 rows, up to 255 columns, and up to 7 planes.
TABLE
This is a special type of numeric array which allows ANSYS to calculate (through linear interpolation) values
between these array elements explicitly defined in the array. Moreover, you can define the array indices for each
row, column, and plane and these indices are real (not integer) numbers. Array elements can be either integers or real
numbers. As we'll see in the later discussion on TABLE arrays, this capability provides a powerful method for
describing mathematical functions. This type can have up to 65,535 rows, up to 255 columns, and up to 7 planes.
The parameter NTEMP could be an array of temperatures at selected nodes; NTEMP(1)=-47.6 could be the temperature at
node 27, NTEMP(2)=-5.2 could be the temperature at node 43, and so on. Similarly, EVOLUM could be an array of
element volumes, and COMPSTRS could be an array of nodal component stresses, with each column representing a
particular direction (X, Y, Z, XY, YZ, XZ, for example).
A type CHAR array parameter is structured similarly to an ARRAY parameter, with the tabular values being alphanumeric
character strings (up to eight characters). Two examples of character array parameters are:
● ANSYS can calculate (through linear interpolation) any values that fall in-between the explicitly declared array
element values.
● A table array contains a 0 row and 0 column used for data-access index values, and unlike standard arrays, these
index values can be real numbers. The only restriction is that the index values must be numerically increasing (never
decreasing) numbers. You must explicitly declare a data access index value for each row and column; otherwise the
default value assigned is the "tiny number" (7.888609052E-31).
● A plane index value resides in the 0,0 location for each plane.
The following figure shows a TABLE array with data-access index values. Note that the indexes are specified as the "0"
row and column values.
As shown in the above example, when configuring a table array you must set
● The plane index value as the 0,0 element value for each plane.
● The data-access column index values in the elements in the 0 row in plane 1. These values are used only when
accessing data from the array. When setting the array element values, you use the traditional row and column index
numbers.
● The data-access row index values in the elements in the 0 column in plane 1. Again, these values are used only when
accessing data from the array. When setting the array element values, you use the traditional row and column index
numbers.
Row and column index values may be set or changed in any plane, and those values will be applied to all planes.
This following examples illustrate the *DIM command used to dimension various types of arrays:
Note-Array elements for ARRAY and TABLE are initialized to 0 (except for the 0 row and column for TABLE, which is
initialized to the tiny value). Array elements for CHAR are initialized to a blank value.
● Setting individual array element values through the *SET command or "=" shortcut.
● Filling individual vectors (columns) in the array with either specified or calculated values (the *VFILL command,
for example).
● Interactively specifying values for the elements through the *VEDIT dialog box.
● Reading the values from an ASCII file (*VREAD or *TREAD commands).
You can use either the *SET command or the "=" shortcut. Usage is the same as for scalar parameters, except that you now
define a column of data (up to ten array element values per "=" command). For example, to define the parameter XYZ
dimensioned above as a 12x1 array you will need two "=" commands. In the following example the first command defines
the first eight array elements and the second command defines the next four array elements:
XYZ(1)=59.5,42.494,-9.01,-8.98,-8.98,9.01,-30.6,51
XYZ(9)=-51.9,14.88,10.8,-10.8
The following example shows how to define the element values for the 4x3 array parameter T2, dimensioned earlier in the
*DIM examples:
T2(1,1)=.6,2,-1.8,4 ! defines (1,1),(2,1),(3,1),(4,1)
T2(1,2)=7,5,9.1,62.5 ! defines (1,2),(2,2),(3,2),(4,2)
T2(1,3)=2E-4,-3.5,22,.01 ! defines (1,3),(2,3),(3,3),(4,3)
The following example defines element values for the TABLE array parameter FORCE discussed earlier.
FORCE(1)=0,560,560,238.5,0
FORCE(1,0)=1E-6,.8,7.2,8.5,9.3
Character array parameters can also be defined using the "=" command. Assigned values can be up to eight characters each
and must be enclosed in single quotes. For example:
Notice that, as when defining a numerical array parameter, the starting location of the array element must be specified (in
this case, the row index number 1 is indicated).
Note-CHAR cannot be used as a character parameter name because it will create a conflict with the CHAR label on the
*DIM command. ANSYS will substitute the character string value assigned to parameter CHAR when CHAR is input on
the third field of the *DIM command (Type field).
You can use the *VFILL commands (Utility Menu>Parameters>Array Parameters> Fill) to "fill" an ARRAY or
TABLE vector (column).
See the *VFILL command reference information in the ANSYS Commands Reference for more detail about the command
syntax. The following example illustrates the capabilities of the *VFILL command.
Complete instructions for using the dialog box are available from the box's Help button.
Figure 3-5 An example of the *VEDIT dialog box for an ARRAY type array.
Figure 3-5 An example of the *VEDIT dialog box for a TABLE array.
and an array called EXAMPLE that has been dimensioned as 3 x 2, the following commands (provided as either a part or a
macro or input listing)
*VREAD,EXAMPLE(1,1),,,2
(3F6.1)
result in
Note that the *VREAD command cannot be issued directly from the command input window. However, the Utility
Menu>Parameters>Array Parameters>Read from File dialog box offers a way to specify the data descriptors and issue
the command in interactive mode.
Once configured, you have two options for specifying values for the TABLE array elements: you can add values as you
would for any other type of array, or you can read in a table of data from an external file.
To read in a table of data from an external file, you still define the TABLE array first, specifying the number of rows,
columns, and planes, and the labels for each. You can then read an ASCII file containing the table of data using the
*TREAD command (Utility Menu>Parameters>Array Parameters>Read from File). At this time, you also specify the
number of lines to skip (NSKIP) between the top of the file and the first line of the table.
● The file containing the table of data can be created in a text editor or an external application (such as Microsoft
Excel), but it must be in ASCII form, tab-delimited, to be read into ANSYS.
● You must first define the array in ANSYS, remembering to allow for the index values (0,0).
● The values are read straight across the rows until all columns on each row of the array are filled; ANSYS then wraps
from one row to the next and begins to fill those columns, and so on. Be sure that the dimensions of the array you
defined are correct. If you mistakenly define fewer columns in the ANSYS array than required, ANSYS will start
filling in the next row of the array using the values remaining in the first row of the data table being read. Similarly,
if you define more columns in the ANSYS array than required, ANSYS will fill all columns of the array using values
from the next row of the data table being read, and only then wrap and begin filling the next row.
You can create 1-D, 2-D, and 3-D tables by reading data from an external file. Examples of how you create each of these
follows.
Example 1: 1-D Table
First, create the 1-D table using the application of your choice (such as a spreadsheet application, a text editor, etc.) and then
save the file as a text file in tab-delimited format. In this example, the table is named "Tdata" and contains data for time vs.
temperature. In its ASCII form, the table would look like this:
Time Temp
0 20
1 30
2 70
4 75
In ANSYS, you define a TABLE parameter "Tt" using the *DIM command (Utility Menu>Parameters>Array
Parameters>Define/Edit). Specify 4 rows and 1 column, row label of Time, and column label of Temp. Note that the data
table you created has four rows and one column of data, plus the row and column index values (the first column -- TIME -
is the row index values) Then read in the file as described earlier, specifying 2 skipped lines. The TABLE array in ANSYS
would look like this:
This same example, done via command input, would look like the following:
*DIM,Tt,table,4,1,1,TIME,TEMP
*TREAD,Tt,tdata,txt,,2
For this example, create (in a spreadsheet application, a text editor, etc.) a 2-D table named "T2data" containing temperature
data as a function of time and x-coordinate and read it into a TABLE array parameter called "Ttx." The table, in its ASCII
form, would look like this:
0 0 .3 .5 .7 .9
0 10 15 20 25 30
1 15 20 25 35 40
2 20 25 35 55 60
4 30 40 70 90 100
In ANSYS, you define a TABLE parameter "Ttx" using the *DIM command (Utility Menu>Parameters>Array
Parameters>Define/Edit). Specify 4 rows, 5 columns, 1 plane, row label of TIME, and column label of X-COORD. Note
that the data table you created has four rows and five columns of data, plus the row and column index values. Then read in
the file as described earlier, specifying 2 skipped lines. The TABLE array in ANSYS would look like this:
This same example, done via command input, would look like the following:
*DIM,Ttx,table,4,5,,time,X-COORD
*TREAD,Ttx,t2data,txt,,2
For this example, create a 3-D table named "T3data" containing temperature data as a function of time, x-coordinate, and y-
coordinate and read it into a TABLE array parameter called "Ttxy." The table, in its ASCII form, would look like this:
Time X-Coordinate
0 0 .3 .5 .7 .9
0 10 15 20 25 30
1 15 20 25 35 40
2 20 25 35 55 60
4 30 40 70 90 100
1.5 0 .3 .5 .7 .9
0 20 25 30 35 40
1 25 30 35 45 50
2 30 35 45 65 70
4 40 50 80 100 120
In the example above, the bold values (in the (0,0,Z) positions) indicate the separate planes. Each plane of data, along with
the row and column index values, is repeated for the separate planes. Only the plane index value and the actual data values
are different. The shaded area above shows the values that change from plane to plane.
In ANSYS, you define a TABLE parameter "Ttxy" using the *DIM command (Utility Menu>Parameters>Array
Parameters>Define/Edit). In the case of a 3-D table, the table is dimensioned according to the number of rows, columns,
and planes of data. The first column (TIME) is the row index values and the first row is the column index values. Specify 4
rows, 5 columns, 2 planes, row label of TIME, column label of X-COORD, and plane label of Y-COORD. Note that the
data table you created has four rows and five columns of data in two planes, plus the row and column index values. Then
read in the file as described earlier, specifying 2 skipped lines. The TABLE array in ANSYS would look like this for the
second plane of data (Y=1.5):
This same example, done via command input, would look like the following:
*DIM,Ttxy,table,4,5,2,TIME,X-COORD,Y-COORD
*TREAD,Ttxy,t3data,txt,,2
As examples of how ANSYS interpolates values in TABLE arrays, consider the following:
Given that A is a TABLE array parameter, the ANSYS program can calculate any value between A(1) and A(2), for
example
This feature allows you to describe a function, such as y=f(x), using a TABLE array parameter. You would use the j=0
column for values of the independent variable x and the "regular" j=1 column for values of y. Consider, for example, a time-
history forcing function described by five points as shown below.
You can specify this function as a TABLE array parameter whose array elements are the force values, and whose row index
numbers 1 through 5 are time values 0.0 through 9.3. Schematically, the parameter will then look like this:
ANSYS can calculate (through linear interpolation) force values at times not specified in the FORCE parameter. For the
above example, ANSYS will calculate a value of 89.4375 for FORCE(9). If a parameter location beyond the dimensions of
the array is used, no extrapolation is done and the end value is used. For example, ANSYS will provide a value of 560.0 for
FORCE(5,2) or 0.0 for FORCE(12)
You can see from these examples that TABLE array parameters can be very powerful tools in your analysis. Typical
applications are time-history loading functions, response spectrum curves, stress-strain curves, material-versus- temperature
curves, B-H curves for magnetic materials, and so forth. Be aware that TABLE array parameters require more computer
time to process than the ARRAY type.
You can use the *VGET command (Utility Menu>Parameters>Get Array Data), which is similar to *GET, to retrieve
ANSYS supplied values and store them in an array.
You must define a starting array location number for the array parameter the *VGET command creates. Looping continues
over successive entity numbers for the KLOOP default. For example, *VGET,A(1),ELEM,5,CENT,X returns the centroid x-
location of element 5 and stores the result in the first location of A. Retrieving continues with elements 6, 7, and so on until
successive array locations are filled. In this example, if KLOOP is 4, then the centroid of x, y, and z are returned.
To restore array parameter values, use the *VPUT command (Utility Menu>Parameters>Array Operations>Put Array
Data).
The *VPUT command uses the same arguments as the *VGET command (described above), but does the opposite of the
*VGET operation. For a list of valid labels for *VPUT items, see the command's description in the ANSYS Commands
Reference.
The ANSYS program "puts" vector items directly, without any coordinate system transformation. *VPUT can replace
existing array items, but can't create new items. Degree of freedom results that are changed in the database are available for
all subsequent operations. Other results change temporarily, and are available mainly for immediately following print and
display operations.
Note-Use this command with extreme caution, as it can alter entire sections of the database. The *VPUT command
doesn't support all items on the *VGET item list because putting values into some locations could make the ANSYS
database inconsistent.
As with scalar parameters, you can use the *STATUS command to list array parameters. The following examples illustrate
the *STATUS command in use:
*STATUS
ABBREVIATION STATUS-
ABBREV STRING
SAVE_DB SAVE
RESUM_DB RESUME
QUIT Fnc_/EXIT
POWRGRPH Fnc_/GRAPHICS
ANSYSWEB Fnc_HomePage
LOCATION VALUE
5 1 1 -8.98000000
6 1 1 9.01000000
7 1 1 -30.6000000
8 1 1 51.0000000
9 1 1 -51.9000000
LOCATION VALUE
1 0 1 0.000000000E+00
2 0 1 0.800000000
3 0 1 7.20000000
4 0 1 8.50000000
5 0 1 9.30000000
1 1 1 0.000000000E+00
2 1 1 560.000000
3 1 1 560.000000
4 1 1 238.500000
5 1 1 0.000000000E+00
LOCATION VALUE
1 1 1 0.600000000
2 1 1 2.00000000
3 1 1 -1.80000000
4 1 1 4.00000000
1 2 1 7.00000000
2 2 1 5.00000000
3 2 1 9.10000000
4 2 1 62.5000000
1 3 1 2.000000000E-04
2 3 1 -3.50000000
3 3 1 22.0000000
4 3 1 1.000000000E-02
LOCATION VALUE
1 1 1 SX (CHAR)
2 1 1 SY (CHAR)
3 1 1 SZ (CHAR)
An array vector, specified with a starting element location (such as MYARRAY(1,2,1)). You can also use an expression,
which is evaluated as a constant value for that field in each row of the data file. The keyword SEQU evaluates to a
sequential column of integers, starting from one.
The format of each row in the data file is determined by the data descriptor line. You must include one descriptor for each
argument to the command. Do not include the word FORMAT in the descriptor line. You can use any real format or
character format descriptor; however, you may not use either integer or list directed descriptors.
If you aren't familiar with FORTRAN data descriptors, this section will get you started with formatting your data file. For
more information, consult the documentation for the FORTRAN 77 compiler for your particular platform.
You must provide a data descriptor for each data item you specify as an argument to the *VWRITE command. In general,
you can use the F descriptor (floating point) for any numeric values. The F descriptor takes the syntax
Fw.d
where
Thus, for a field that is 10 characters wide and has eight characters after the decimal point, you would use the following
data descriptor:
F10.8
For character fields, you can use the A descriptor. The A descriptor has the syntax
Aw
where
w
Is the width of the data field in characters.
Thus, for a character field that is eight characters wide, the descriptor is
A8
The following examples illustrate the *VWRITE command and data descriptors in use.
Given that the MYDATA array has been dimensioned and filled with the following values:
The following short macro first defines the scalar parameter X as having a value of 25 and then opens the file vector
(*CFOPEN command). The *VWRITE command then defines the data to be written to the file. In this case, the first
vector written uses the SEQU keyword to provide row numbers. Note that in some cases that constants, scalar parameters,
and operations that include array element values are written to the file. Note the data file contents for these items.
x=25
*cfopen,vector
*vwrite,SEQU,mydata(1,1,1),mydata(1,2,1),mydata(1,3,1),10.2,x,mydata(1,1,1)+3
(F3.0,' ',F8.4,' ',F8.1,' 'F8.6,' ',F4.1,' 'F4.0,' 'F8.1)
*cfclos
The second example uses the following previously dimensioned and filled array:
*vwrite,SEQU,mydata(1,1),mydata(1,2),(mydata1(1,1)+mydata1(1,2))
(' Row',F3.0,' contains ',2F7.3,'. Is their sum ',F7.3,' ?')
Vector operations are simply a set of operations-addition, subtraction, sine, cosine, dot product, cross product, etc.-repeated
over a sequence of array elements. Do-loops (discussed in Section 4.5.5) can be employed for this purpose, but a more
convenient and much faster way is to use the vector operation commands-*VOPER, *VFUN, *VSCFUN, *VITRP,
*VFILL, *VREAD, and *VGET. Of these listed vector operation commands, only *VREAD and *VWRITE are valid for
character array parameters. Other vector operation commands apply only to array parameters dimensioned (*DIM) as
ARRAY type or TABLE type.
The *VFILL, *VREAD, *VGET, *VWRITE, and *DIM commands were introduced earlier in this chapter. Other
commands that are discussed in this section include
Performs an operation on two input array vectors and produces a single output array vector.
Performs a function on a single input array vector and produces a single output array vector.
Determines the properties of a single input array vector and places the result in a specified scalar parameter.
Forms an array parameter (type ARRAY) by interpolating an array parameter (type TABLE) at specified table index
locations.
The examples below illustrate the use of some of these commands. Refer to the ANSYS Commands Reference for syntactical
information about these commands. For all of the following examples, the array parameters (of type ARRAY) X, Y, and
THETA have been dimensioned and defined.
In the following example, the result array is first dimensioned (Z1). The *VOPER command then adds column 2 of X to
column 1 of Y, both starting at row 1, and then places the result into Z1. Notice that the starting location (the row and
column index numbers) must be specified for all array parameters. The operation then progresses sequentially down the
specified vector.
*DIM,Z1,ARRAY,4
*VOPER,Z1(1),X(1,2),ADD,Y(1,1)
In the following example, again the result array (Z2) is dimensioned first. The *VOPER command then multiplies the first
column of X (starting at row 2) with the fourth column of Y (starting at row 1) and writes the results to Z2 (starting at row
1).
*DIM,Z2,ARRAY,3
*VOPER,Z2(1),X(2,1),MULT,Y(1,4)
In this example, again the results array (Z4) is dimensioned first. The *VOPER command then performs the cross product
of four pairs of vectors, one pair for each row of X and Y. The i, j, and k components of these vectors are columns 1, 2, and
3 respectively of X and columns 2, 3, and 4 of Y. The results are written to Z4, whose i, j, and k components are vectors 1,
2, and 3 respectively.
*DIM,Z4,ARRAY,4,3
*VOPER,Z4(1,1),X(1,1),CROSS,Y(1,2)
In the following example, the results array (A3) is dimensioned first. The *VFUN command then raises each element in
vector 2 of X to the power of 2 and writes the results to A3.
*DIM,A3,ARRAY,4
*VFUN,A3(1),PWR,X(1,2),2
In this example, the results array (A4) is dimensioned. The two *VFUN commands then calculate the cosine and sine of
array elements in THETA and place the results in the first and second columns, respectively, of A4. Notice that A4 now
represents a circular arc spanning 90°, described by seven points (whose x, y, and z global Cartesian coordinates are the
three vectors). The arc has a radius of 1.0 and lies parallel to the x-y plane at z = 2.0.
*DIM,A4,ARRAY,7,3
*AFUN,DEG
*VFUN,A4(1,1),COS,THETA(1)
*VFUN,A4(1,2),SIN,THETA(1)
A4(1,3)=2,2,2,2,2,2,2
In this example, the results array (A5) is first dimensioned. Then, the *VFUN command calculates the tangent vector at
each point on the curve represented by A4, normalizes it to 1.0, and places the results in A5.
*DIM,A5,ARRAY,7,3
*VFUN,A5(1,1),TANG,A4(1,1)
Two additional *VOPER operations, gather (GATH) and scatter (SCAT), are used to copy values from one vector to
another based on numbers contained in a "position" vector. The following example demonstrates the gather operation. Note
that, as always, the results array must be dimensioned first. In the example, the gather operation copies the value of B1 to
B3 (using the index positions specified in B2). Note that the last element in B3 is 0 as this is its initialized value.
*DIM,B1,,4
*DIM,B2,,3
*DIM,B3,,4
B1(1)=10,20,30,40
B2(1)=2,4,1
*VOPER,B3(1),B1(1),GATH,B2(1)
Matrix operations are mathematical operations between numerical array parameter matrices, such as matrix multiplication,
calculating the transpose, and solving simultaneous equations.
Performs matrix operations on two input array parameter matrices and produces one output array parameter matrix.
Matrix operations include
● Matrix multiplication
● Solution of simultaneous equations
● Sorting (in ascending order) on a specified vector in a matrix
● Covariance between two vectors
● Correlation between two vectors
Copies or transposes an array parameter matrix (accepts one input matrix and produces one output matrix).
The examples below illustrate the use of some of these commands. Refer to the ANSYS Commands Reference for syntactical
information about these commands.
This example shows the sorting capabilities of the *MOPER command. For this example, assume that the array
(SORTDATA) has been dimensioned and its element values have been defined as follows:
First, the OLDORDER array is dimensioned. The *MOPER command will place the original order of the rows into
OLDORDER. The *MOPER command then sorts the rows in SORTDATA so that the 1,1 vector is now in ascending
order.
*dim,oldorder,,5
*moper,oldorder(1),sortdata(1,1),sort,sortdata(1,1)
To put the SORTDATA array back into its original order, you could then issue the following command:
*moper,oldorder(1),sortdata(1,1),sort,oldorder(1,1)
In the following example, the *MOPER command solves a set of simultaneous equations. The following two arrays have
been dimensioned and their values assigned:
The *MOPER command can solve a set of simultaneous equations for a square matrix. The equations take the form
In the case of the above arrays, the *MOPER command will solve the following set of simultaneous equations:
To solve the equations, first the results array (C) is dimensioned. Then the *MOPER command solves the equations, using
A as the matrix of a coefficients and B as a vector of b values.
*DIM,C,,4
*MOPER,C(1),A(1,1),SOLV,B(1)
The following example shows the *MFUN command used to transpose data in an array. For this example, assume that the
array (DATA) was dimensioned and filled with the following values.
As always, the results array (DATATRAN) is dimensioned first, then the *MFUN command transposes the values and
writes them to DATATRAN.
*DIM,DATATRAN,,2,3
*MFUN,DATATRAN(1,1),TRAN,DATA(1,1)
All the vector and matrix operation commands are affected by the setting of the following specification commands:
*VCUM, *VABS, *VFACT, *VLEN, *VCOL, and *VMASK. (Of all specification commands, only *VLEN and
*VMASK, in conjunction with *VREAD or *VWRITE, are valid for character array parameters.) You can check the
status of these commands with the *VSTAT command. Most of these commands (and their corresponding GUI paths) were
introduced earlier in this chapter. The others are explained in the following.
With the exception of the *VSTAT command, which you cannot access directly in the GUI, all of the specification
commands described below are available via menu path Utility Menu>Parameters>Array Operations>Operation
Settings.
Important: All specification commands are reset to their default settings after each vector or matrix operation.
*VCUM
Specifies whether results will be cumulative or non-cumulative (overwriting previous results). ParR, the result of a
vector operation, is either added to an existing parameter of the same name or overwritten. The default is non-
cumulative results, that is, ParRoverwrites an existing parameter of the same name.
*VABS
Applies an absolute value to any or all of the parameters involved in a vector operation. The default is to use the real
(algebraic) value.
*VFACT
Applies a scale factor to any or all of the parameters involved in a vector operation. The default scale factor is 1.0
(full value).
*VCOL
Specifies the number of columns in matrix operations. The default is to fill all locations of the result array from the
specified starting location.
*VSTAT
The following table lists the various specification commands and the vector and matrix array commands that they affect.
*VLEN
*VABS *VFACT *VCUM *VCOL *VMASK
NROW,NINC
*MFOURI No No No N/A No No No
The examples below illustrate the use of some of the specification commands. Refer to the ANSYS Commands Reference for
syntactical information about these commands.
In the following, the results array (CMPR) is dimensioned. The two *VFUN commands, in conjunction with the preceding
*VMASK and *VLEN commands, then compress selected data and write them to specified locations in CMPR. The
complement to the COMP operation is the EXPA operation on the *VFUN command.
*DIM,CMPR,ARRAY,4,4
*VLEN,4,2 ! Do next *V---- operation on four rows,
! skipping every second row
*VFUN,CMPR(1,2),COMP,Y(1,1)
*VMASK,X(1,3) !Use column 3 of X as a mask for next *V----
! operation
*VFUN,CMPR(1,3),COMP,Y(1,2)
This example uses the *VFACT command to round the values in an array vector to the number of decimal places specified
by the NUMDP scalar parameter (set to 2 in the example). The NUMDATA array has been dimensioned and filled with the
following values:
numdp=2
*vfact,10**numdp
*vfun,numdata(1),copy,numdata(1)
*vfun,numdata(1),nint,numdata(1)
*vfact,10**(-numdp)
*vfun,numdata(1),copy,numdata(1)
numdp=2
*vfact,10**numdp
*vfun,numdata(1),copy,numdata(1)
*vfact,10**(-numdp)
*vfun,numdata(1),nint,numdata(1)
This example uses the *VLEN and *VMASK commands to find the set of prime numbers less than 100. An array,
MASKVECT, is created using 1.0 to indicate that the row value is a prime number and 0.0 to indicate that the value isn't
prime. The algorithm used to create the mask vector is to initialize all rows whose value is greater than 1 to 1.0 and then
loop thorugh the range of possible factors, eliminating all multiples of the factor. The *VLEN command sets the row
increment for performing operations to FACTOR. When the *VFILL command is processed, the row number is
incremented by this value. Because the starting row is FACTOR x 2, the rows are processed by each loop in the following
manner: FACTOR x 2, FACTOR x 3, FACTOR x 4, etc.
*dim,maskvect,,100
*vfill,maskvect(2),ramp,1
*do,factor,2,10,1
*vlen,,factor
*vfill,maskvect(factor*2),ramp,0
*enddo
*vmask,maskvect(1)
*dim,numbers,,100
*vfill,numbers(1),ramp,1,1
*status,numbers(1),1,10
The resultant output from the *STATUS command, showing the first 10 elements in NUMBERS is
The following demonstrates some of the capabilities of the *VPLOT command. For this example, two TABLE arrays
(TABLEVAL and TABLE) and one numeric array have been dimensioned and filled with the following values:
The following are example *VPLOT commands and their resulting plots. Note that since ARRAY data is unordered it is
plotted as a histogram; TABLE data is ordered and is therefore plotted as a curve.
*vplot,,arrayval(1,1),2
*vplot,,tableval(1,1),2
*vplot,table2(1),tableval(1,1),2
*vplot,tableval(1,0),tableval(1,1),2
You can also nest macros. That is, one macro can call a second macro, the second macro can call a third macro, and so
on. You can use up to 20 nesting levels, including any file switches caused by the ANSYS /INPUT command. After
each nested macro executes, the ANSYS program returns control to the previous macro level.
The following is a very simple example macro file. In this example, the macro creates a block with dimensions 4, 3,
and, 2 and a sphere with a radius of 1. It then subtracts the sphere from one corner of the block.
/prep7
/view,,-1,-2,-3
block,,4,,3,,2
sphere,1
vsbv,1,2
finish
If this macro were called mymacro.mac, you could execute this sequence of commands with the following single
ANSYS command
*use,mymacro
mymacro
Clearly, this isn't a terribly useful macro, but it does illustrate the principle.
This chapter provides information on the various ways you can create, store, and execute macros. It also discusses the
basic information you need to use APDL as a scripting language in creating macros.
For any long, complex macro you should always consider either using a similar macro as a starting point or running the
task interactively in ANSYS and using the resulting log file as the basis of your macro. Either method can greatly
reduce the time and effort required to create a suitable macro.
To ensure that you aren't using the name of an ANSYS command, before creating a macro try running the file name
that you wish to use as an ANSYS command. If ANSYS returns the message shown below, you'll know that the
command is not used in the current processor. To be "safe," you should check the macro file name in each processor in
which you plan to use the macro. (You could also check if the macro file name matches any command listed in the
online documentation; however, this method can't locate the names of undocumented commands.)
Figure 4-1 ANSYS message box stating that an unknown command was issued.
Using the .mac extension allows ANSYS to execute the macro as it would any internal command. The extension
.MAC is used for ANSYS internal macros and you should avoid using this.
1. The directory (or directories) designated by the ANSYS_MACROLIB environment variable (if defined) or the login
(home) directory. This environment variable is documented in the ANSYS installation and configuration guide for your
platform.
2. The directory designated by /PSEARCH command (if defined). This directory is searched before the login directory,
but after the directory designated by the ANSYS_MACROLIB environment variable.
3. The current directory.
You can place macros for your personal use in your home directory. Macros that should be available across your site
should be placed in the ANSYS documentation directory or some commonly accessible directory that everyone can
reference through the ANSYS_MACROLIB environment variable.
● For Windows 95 users: You must designate the "home directory" and drive using environment variables, see the
ANSYS Installation and Configuration Guide for Windows.
● For Windows NT users: The "current directory" is the default directory (usually a network resource) set by
administrators and you should ask your network administrator for its location. You can use environment
variables to create a local "home directory." The local home directory is checked after the default directory
designated in your domain profile. See the ANSYS Installation and Configuration Guide for Windows for more
information.
● Issuing the *CREATE command in the input window. Parameter values are not resolved and parameter names
are written to the file.
● Using the *CFOPEN, *CFWRITE, and *CFCLOS commands. Parameter names are resolved to their current
values and those values are written to the macro file.
● Choosing the Utility Menu>Macro>Create Macro menu item. This method opens a dialog box that can be
used as a simple, multi-line editor for creating macros. Parameter values are not resolved and parameter names
are written to the file.
Issuing *CREATE redirects ANSYS commands entered in the command input window to the file designated by the
command. All commands are redirected until you issue the *END command. If an existing file has the same name as
the macro filename you specify, the ANSYS program overwrites the existing file.
For example, suppose that you want to create a macro called matprop.mac, which automatically defines a set of
material properties. The set of commands entered into the input window for this macro might look like this:
*CREATE,matprop,mac,macros\
MP,EX,1,2.07E11
MP,NUXY,1,.27
MP,DENS,1,7835
MP,KXX,1,42
*END
The *CREATE command takes arguments of the file name, the file extension, and the directory path (in this case, the
macros directory is specified). Note that UNIX users must append a slash to the end of the directory path.
When using *CREATE, all parameters used in commands are written to the file (the currently assigned values for the
parameter are not substituted). If your current parameter values are important, you can save the parameters to a file
using the PARSAV command.
4.2.3.2 Using *CFWRITE
If you wish to create a macro file in which current values are substituted for parameters you can use *CFWRITE.
Unlike *CREATE, the *CFWRITE command can't specify a macro name; you must first specify the macro file with
the *CFOPEN command. Only those ANSYS commands that are explicitly prefaced with a *CFWRITE command
are then written to the designated file; all other commands entered in the command input window are executed. As with
the *CREATE command, *CFOPEN can specify a file name, a file extension, and a path. The following example
writes a BLOCK command to the currently open macro file.
*cfwrite,block,,a,,b,,c
Note that parameters were used for arguments to the BLOCK command. The current value of those parameters (and
not the parameter names) are written to the file. So, for this example, the line written to the macro file might be
*cfwrite,block,,4,,2.5,,2
Note-While it is possible to create a macro through this method, these commands are most useful as a method for
writing ANSYS commands to a file during macro execution.
Choosing this menu item opens an ANSYS dialog box that you can use as a simple editor for creating macros. You
cannot open and edit an existing macro with this facility; if you use the name of an existing macro as the arguments for
the *CREATE field the existing file will be overwritten.
Figure 4-2 The Utility Menu>Macro>Create Macro dialog, shown with a simple macro.
As with the *CREATE command, parameters are not evaluated but are written verbatim into the macro file. Note that
you do not make the last line a *END command.
If you use this method to create macros, don't include the *CREATE and *END commands.
Macros libraries have no explicit file extension and follow the same file naming conventions as macro files. A macro
library file has the following structure:
MACRONAME1
.
.
.
/EOF
MACRONAME2
.
.
.
/EOF
MACRONAME3
.
.
.
./EOF
For example, the following macro file contains two simple macros:
mybloc
/prep7
/view,,-1,-2,-3
block,,4,,3,,2
finish
/EOF
mysphere
/prep7
/view,,-1,-2,-3
sphere,1
finish
/EOF
Note that each macro is prefaced with a macro name (sometimes refered to as a data block name) and ends with a /EOF
command.
A macro library file can reside anywhere on your system, although for convenience you should place it within the
macro search path. Unlike macro files, a macro library file can have any extension up to eight characters.
*use,mymacro
In this case, the macro takes no arguments. If instead the macro was called MYMACRO.MACRO and resided in
/myaccount/macros, you could call it with
*use,/myaccount/macros/mymacro.macro
Note that the *USE command allows you to enter the path and extension along with the file name and that these are not
entered as separate arguments.
If a macro has a .mac file extension and resides in the search path, you can execute it as if it were an ANSYS command
by simply entering it in the command input window. For example, to call mymacro.mac you could simply enter
mymacro
You can also execute macros with a .mac extension through the Utility Menu>Macro>Execute Macro menu item.
If the same macro takes arguments (see Section 4.4.1 for more information about passing arguments to macros), then
these can be entered on the command line as follows
mymacro,4,3,2,1.5
or
*use,mymacro.mac,4,3,2,1.5
The Utility Menu>Macro>Execute Macro menu item dialog provides fields for arguments.
Executing macros contained in macro libraries is similar. You must first specify the library file using the *ULIB
command. For example, to specify that macros are in the mymacros.mlib file, which resides in the
/myaccount/macros directory, you would issue the following command:
*ulib,mymacros,mlib,/myaccount/macros/
After selecting a macro library, you can execute any macro contained in the library by specifying it through the *USE
command. As with macros contained in individual files, you can specify arguments as parameters in the *USE
command.
Note-You can't use the *USE command to access macros not contained in the specified macro library file after issuing
the *ULIB command.
● A set of scalar parameters that provide a way of passing command line arguments to the macro.
● A set of scalar parameters that can be used within the macro. These provide a set of local variables that can be
used to define values only within that macro.
● Numbers
● Alphanumeric character strings (up to eight characters enclosed in single quotes)
● Numeric or character parameters
● Parametric expressions
Note-You can pass only the values of parameters ARG1 through AR18 to a macro as arguments with the *USE
command. If you create a macro that can be used as an ANSYS command (the macro files has a .mac extension), you
can pass the values of parameters ARG1 through AR19 to the macro.
For example, the following simple macro requires four arguments, ARG1, ARG2, ARG3, and ARG4:
/prep7
/view,,-1,-2,-3
block,,arg1,,arg2,,arg3
sphere,arg4
vsbv,1,2
finish
mymacro,4,3,2.2,1
The following sections detail each of these program control capabilities. For the exact syntax of the commands, refer to
the ANSYS Commands Reference.
mystart
/prep7
/view,,-1,-2,-3
mysphere,1.2
finish
/eof
mysphere
sphere,arg1
/eof
*GO,:BRANCH1
--- ! This block of commands is skipped (not executed)
---
:BRANCH1
---
---
The label specified by the *GO command must start with a colon (:) and must not contain more than eight characters,
including the colon. The label can reside anywhere within the same file.
Note-The use of *GO is now considered obsolete and is discouraged. See the other branching commands for better
methods of controlling program flow.
Where
● VAL1 is the first numerical value (or numerical parameter) in the comparison.
● Oper is the comparison operator.
● VAL2 is the second numerical value (or numerical parameter) in the comparison.
● Base is the action that occurs if the comparison evaluates as true.
APDL offers eight comparison operators, which are discussed in detail in the *IF command reference. Briefly these
are:
EQ
NE
GT
LE
GE
ABLT
ABGT
By giving the Base argument a value of THEN, the *IF command becomes the beginning of an if-then-else construct
(similar to the FORTRAN equivalent). The construct consists of
In its simplest form, the *IF command evaluates the comparison and, if true, branches to a label specified in the Base
argument. This is similar to the "computed goto" in FORTRAN 77. (In combination, a set of such *IF commands could
function similarly to the CASE statements in other programming languages.) Take care not to branch to a label within
an if-then-else construct or do-loop.
By setting the Base argument to a value of STOP, you can exit from ANSYS based on a particular condition.
An if-then-else construct simply evaluates a condition and executes the following block or jumps to the next statement
following the *ENDIF command (shown with the "Continue" comment).
*IF,A,EQ,1,THEN
! Block1
.
.
*ENDIF
! Continue
The following example shows a more complex structure. Note that only one block can be executed. If no comparison
evaluates to true, the block following the *ELSE command is executed.
Figure 4-4 A sample if-then-else construct, using all of the possible APDL branching commands.
Note-You can issue a /CLEAR command within an if-then-else construct. The /CLEAR command does not clear the
*IF stack and the number of *IF levels is retained. An *ENDIF is necessary to close any branching logic. Also, keep
in mind that the /CLEAR command deletes all parameters, including any that are used in your branching commands.
You can avoid any problems that might arise from the deletion of parameters by issuing a /PARSAV command before
the /CLEAR command, and then following the /CLEAR command with a /PARRES command.
E,1,2
*REPEAT,5,0,1
the E command generates one element between nodes 1 and 2 and the following *REPEAT command specifies that E
executes a total of five times (including the original E command), incrementing the second node number by one for
each additional execution. The result is five total elements with node connectivities 1-2, 1-3, 1-4, 1-5, and 1-6.
Note-Most commands that begin with a slash (/) or an asterisk (*), as well as macros executed as "unknown
commands," cannot be repeated. However, graphics commands that begin with a slash can be repeated. Also, avoid
using the *REPEAT command with interactive commands, such as those that require picking or those that require a
user response.
*DO,I,1,5 ! For I = 1 to 5:
LSREAD,I ! Read load step file I
OUTPR,ALL,NONE ! Change output controls
ERESX,NO
LSWRITE,I ! Rewrite load step file I
*ENDDO
You can add your own loop controls by using the *IF, *EXIT, or *CYCLE commands.
● Do not branch out of a do-loop with a :Label on the *IF or *GO commands.
● Avoid using a :Label to branch to a different line within a do-loop. Use if-then-else-endif instead.
● Output from commands within a do-loop is automatically suppressed after the first loop. Use /GOPR or /GO
(no response line) within the do-loop if you need to see output for all loops.
● Take care if you include a /CLEAR command within a do-loop. The /CLEAR command does not clear the do-
loop stack, but it does clear all parameters including the loop parameter in the *DO statement itself. You can
avoid the problem of having an undefined looping value by issuing a /PARSAV command before the /CLEAR
command, and then following the /CLEAR command with a /PARRES command.
Most of the important information about these commands appears here, but you may want to look at the complete
command descriptions in the ANSYS Commands Reference.
· IVAL and FVAL are the initial and final parameter values.
You must use one *ENDDO command for each nested "do"
Ends a "do" loop and starts the
*ENDDO loop. The *ENDDO and *DO commands for a loop must be on
looping action.
the same file.
When executing a "do" loop, the You can use the cycle option conditionally (via the *IF
ANSYS program bypasses all
command).
commands between the
*CYCLE *CYCLE command and the
The *CYCLE command must appear on the same file as the
*ENDDO command, then (if
*DO command and must appear before the *ENDDO
applicable) initiates the next
loop. command.
- :label (skips to the first line starting with the matching label)
Terminates an if-then-else
*ENDIF construct. (See the *IF The *IF and *ENDIF commands must appear in the same file.
discussion for details.)
Solid modeling functions generate the _RETURN parameter, which contains the result of executing the function. The
following table defines the _RETURN values for the various solid modeling functions:
Keypoints
Lines
Areas
Volumes
V Volume through keypoints Volume number
Executing an ANSYS command, whether in a macro or elsewhere, generates the parameter _STATUS. This parameter
reflects the error status of that command:
● 0, for no error
● 1, for a note
● 2, for a warning
● 3, for an error
You also can create assemblies-groups that combine two or more components or even multiple assemblies. You can
nest assemblies up to five levels deep. For example, you could build an assembly named MOTOR from components
called STATOR, PERMMAG, ROTOR, and WINDINGS.
The table below describes some of the commands you can issue to build components and assemblies. For more detailed
discussions of these commands, see the ANSYS Commands Reference. For further information on components and
assemblies, see Chapter 7 of the ANSYS Basic Analysis Procedures Guide.
Command Description
Groups geometry items into a component. Arguments are:
CMGRP, Aname,Oper,Cnam1,... · Aname - the name of the assembly. The name can have up to eight characters
Cnam8 and must begin with a letter.
Lists the entities contained in a component or assembly. Name is the name of the
CMLIST,Name component or assembly to be listed. If you specify no Name, the program lists all
components and assemblies.
Selects a subset of components and assemblies. Type is a label identifying the
type of select operation:
2. R - Reselect a set
CMSEL,Type,Name
3. A - Additionally select a set and extend the current set
4. U - Unselect a set
The following example macro, called bilinear.mac, evaluates two bilinear materials. This is a useful macro that can be
run after solving a static analysis. Material 1 is the tension properties, and Material 2 is the compression properties.
ARG1 is the number of iterations (default is 2).
/nop
_niter = arg1 ! set number of iterations
*if,_niter,lt,2,then
_Niter = 2
*endif
*do,iter,1,_niter ! loop on number of iterations
/post1
set,1,1
ar11,=elmiqr(0,14) ! call elmiqr function to get no. of elements
*dim,_s1,,ar11 ! array for element s1
*dim,_s3,,ar11 ! array for element s3
etable,sigmax,s,1 ! s1 is in element table sigmax
etable,sigmin,s,3 ! s3 is in element table sigmin
*vget,_s1(1),elem,1,etab,sigmax ! get element maximum stress in s1
*vget,_s3(1),elem,1,etab,sigmin ! get element minimum stress in s3
*dim,_mask,,ar11 ! array for mask vector
*voper,_mask(1),_s1(1),lt,0 ! true if max. stress < 0
*vcum,1 ! accumulate compression elements
*vabs,0,1 ! absolute value of s3
*voper,_mask(1),_s3(1),gt,_s1(1) ! true if abs(minstr) > maxstr
finish
Within an ANSYS macro, you have several ways to access components of the ANSYS graphical user interface
(GUI):
● You can modify and update the ANSYS toolbar (this is discussed in detail in Section ).
● You can issue the *ASK command to prompt a user to enter a single parameter value.
● You can create a dialog box to prompt a user to enter multiple parameter values.
● You can issue the *MSG command to have the macro write an output message.
● You can have the macro update or remove a status bar.
● You can allow the user to select entities through graphical picking from within a macro.
● You can call any dialog box.
*ASK,Par,Query,DVAL
Where
● Par is an alphanumeric name that identifies the scalar parameter used to store the user input.
● Query is the text string that ANSYS displays to prompt the user. This string can contain up to 54
characters. Don't use characters that have special meanings, such as "$" or "!".
● DVAL is the default value given the parameter if a user issues a blank response. This value can be either a
one-to-eight character string (enclosed in single quotes) or a number. If you assign no default, a blank user
response deletes the parameter.
The *ASK command prints the Query text on the screen and waits for a response. It reads the response from the
keyboard except when ANSYS runs in batch mode. (In that case, the response or responses must be the next-read
input line or lines.) The response can be a number, a one-to-eight character string enclosed in single quotes, a
numeric or character parameter, or an expression that evaluates to a number. ANSYS then sets the value of Par to
the read-in response. For example:
When you issue *ASK within a macro, ANSYS writes the user's response to File.LOG on the line following the
macro name.
MULTIPRO,'start',Prompt_Num
*CSET,Strt_Loc,End_Loc,Param_Name,'Prompt_String',Def_Value
MULTIPRO,'end'
Where
'start'
A literal string that, when encountered as the first argument, marks the beginning of the
MULTIPROconstruct. The literal must be enclosed in single quotes.
Prompt_Num
Required only if Def_Valueis omitted from at least one *CSETcommand or if Def_Valueis set to 0. The
Prompt_Numvalue is an integer equal to the number of following *CSETprompts.
Strt_Loc,End_Loc
The initial value for Strt_Locfor the first *CSETcommand is1, and the value for End_Locis Strt_Loc+2 (3
for the first *CSETcommand). The value of each subsequent Strt_Locis the previous End_Loc+1.
Param_Name
The name of the parameter that will hold either the value specified by the user or, if the user supplies no
value, the value of Def_Value.
'Prompt_String'
A string, which can contain up to 32 characters, which can be used to describe the parameter. This string
must be enclosed in single quotes.
'end'
A literal string, used as the first argument for the closing MULTIPROcommand.
multipro,'start',3
*cset,1,3,beamW,'Enter the overall beam width',12.5
*cset,4,6,beamH,'Enter the beam height',23.345
*cset,7,9,beamL,'Enter the beam length',50.0
multipro,'end'
Up to two optional *CSET commands can be added to the construct that can provide two 64 character strings.
You can use these to provide instructions to the user. The syntax for these specialized *CSET commands is
*CSET,61,62,'Help_String','Help_String'
*CSET,63,64,'Help_String','Help_String'
Where
'Help_String'
A string which can contain up to 32 characters. If you need more than 32 characters, you can use a second
Help_Stringargument.
The following is an example of a MULTIPRO construct using the optional help lines. Note that two Help_String
arguments are used to overcome the 32 character limit.
multipro,'start',3
*cset,1,3,dx,'Enter DX Value',0.0
*cset,4,6,dy,'Enter DY Value',0.0
*cset,7,9,dz,'Enter DZ Value',0.0
*cset,61,62,'The MYOFSET macro offsets the',' selected nodes along each'
*cset,63,64,'of the three axes. Fill in the ',' fields accordingly.'
multipro,'end'
The above construct creates the following multiple-prompt dialog box.
You can check the status of the buttons by testing the value of the _BUTTON parameter. The following lists the
button status values:
*MSG,Lab,VAL1,VAL2,VAL3,VAL4,VAL5,VAL6,VAL7,VAL8
Where Lab is one of the following labels for output and termination control:
WARN Writes the message with a "WARNING" heading, and also writes it to the errors file, Jobname.ERR.
Writes the message with an "ERROR" heading and also writes it to the errors file, Jobname.ERR. If
ERROR
this is an ANSYS batch run, this label also terminates the run at the earliest "clean exit" point.
Writes the message with a "FATAL ERROR" heading and also writes it to the errors file,
FATAL
Jobname.ERR. This label also terminates the ANSYS run immediately.
UI Writes the message with a "NOTE" heading and displays it in the message dialog box.
VAL1 through VAL8 are numeric or alphanumeric character values to be included in the message. Values can be
the results of evaluating parameters. All numeric values are assumed to be double precision.
You must specify the message format immediately after the *MSG command. The message format can contain
up to 80 characters, consisting of text strings and predefined "data descriptors" between the strings where
numeric or alphanumeric character data are to be inserted. These data descriptors are:
● %i, for integer data. The FORTRAN nearest integer (NINT) function is used to form integers for the %I
specifier.`
● %g, for double precision data
● %c, for alphanumeric character data
● %/, for a line break
The corresponding FORTRAN data descriptors for the first three descriptors are I9, 1PG16.9, and A8
respectively. A blank must precede each descriptor. You also must supply one data descriptor for each specified
value (eight maximum), in the order of the specified values.
Don't begin *MSG format lines with *IF, *ENDIF, *ELSE, or *ELSEIF. If the last non-blank character of the
message format is an ampersand (&), the ANSYS program reads a second line as a continuation of the format.
You can use up to 10 lines (including the first) to specify the format information.
Consecutive blanks are condensed into one blank upon output, and a period is appended. The output produced
can be up to 10 lines of 72 characters each (using the $/ descriptor).
The example below shows you an example of using *MSG that prints a message with two integer values and one
real value:
Note-The command /UIS,MSGPOP controls which messages a message dialog box displays when the GUI is
active. See the ANSYS Commands Reference for more information about this command.
*ABSET,Title40,Item
● Title40 is the text string that appears in the dialog box with the status bar. The string can contain a
maximum of 40 characters.
● Item is one of the following values:
● Percent is an integer between 0 and 100. It gives the position of the status bar.
● NewTitle is a 40-character string that contains progress information. If you specify a string for NewTitle, it
replaces the string supplied in Title40.
If you specify KILL or BOTH, your macro should check the _ERROR parameter after each execution of
*ABCHECK to see if the user has pressed the STOP button, then take the appropriate action.
To remove the status bar from the ANSYS GUI, issue the *ABFINI command.
The following example macro illustrates the status bar (complete with bar and STOP button) in use. The status
dialog box that is produced is shown in the following figure. Note that the macro checks the status of the
_ERROR parameter and, if the STOP button is pressed, posts the "We are stopped......" message.
fini
/clear,nost
/prep7
n,1,1
n,1000,1000
fill
*abset,'This is a Status Bar',BOTH
myparam = 0
*do,i,1,20
j = 5*i
*abcheck,j
*if,_return,gt,0,then
myparam = 1
*endif
*if,myparam,gt,0,exit
/ang,,j
nplot,1
*if,_return,gt,0,then
myparam = 1
*endif
*if,myparam,gt,0,exit
nlist,all
*if,_return,gt,0,then
myparam = 1
*endif
*if,myparam,gt,0,exit
*enddo
*if,myparam,gt,0,then
*msg,ui
We are stopped.........
*endif
*abfinish
fini
Figure 5-3 A Typical Status Dialog Box, Showing The Status Bar And Stop Button.
Keep in mind that picking commands are not available in all ANSYS processors, and that you must first switch to
an appropriate processor before calling the command.
Note-If a macro includes GUI functions, the /PMACRO command should be the first command in that macro.
This command causes the macro contents to be written to the session log file. This is important, because if you
omit the /PMACRO command, ANSYS can't read the session log file to reproduce the ANSYS session.
Keep in mind that many dialog boxes have a number of dependencies, including that the appropriate ANSYS
processor is active and that certain required preexisting conditions are met. For example, launching a dialog box
to select nodes first supposes that nodes exist, if no nodes exist the macro will fail when the user clicks OK or
Apply.
Note-If a macro includes GUI functions, the /PMACRO command should be the first command in that macro.
This command causes the macro contents to be written to the session log file. This is important, because if you
omit the /PMACRO command, ANSYS can't read the session log file to reproduce the ANSYS session.
ANSYS provides the ability to encrypt macro files so that the source is not "human-readable."
Encrypted macros require an encryption key to run. The encryption key can be either explicitly placed
(in readable ASCII) in the macro or it can be set by the user in ANSYS as a global encryption key.
/ENCRYPT,Encryption_key,File_name,File_ext,Directory_Path/
Where
Note the placement of the /ENCRYPT commands at the top and bottom of the listing in the following
example
/encrypt,mypasswd,myenfile,mac,macros/
/nopr
/prep7
/view,,-1,-2,-3
block,,arg1,,arg2,,arg3
sphere,arg4
vsbv,1,2
/gopr
finish
/encrypt
The /ENCRYPT command at the top of the macro instructs ANSYS to encrypt the file and use the
string "mypasswd" as the encryption key. It will create an encrypted macro file called myenfile.mac
and place it in the /macros subdirectory of the home directory. The /ENCRYPT command at the
bottom instructs ANSYS to stop the encryption process and write the encrypted macro to the specified
file.
Note-The encrypted macro uses a /NOPR command as its second line to turn off echoing of ANSYS
commands to the session log file. This is important if you wish to prevent users from reading the
contents of the macro from the session log. It's a good practice to reactivate the session log by issuing
the /GOPR command as the last command in the macro before the ending /ENCRYPT command.
/DECRYPT,mypasswd
013^Z,^%
02x^0Se|Lv(yT.6>?
03J3]Q_LuXd3-6=m+*f$k]?eB
04:^VY7S#S>c>
05daV;u(yY
06T]3WjZ
/DECRYPT
Note that the individual commands within the macro are now encrypted, and that the encrypted
material is enclosed by /DECRYPT commands. The encryption key is the argument to the first
/DECRYPT command.
/DECRYPT,PASSWORD
Before executing the macro within ANSYS, issue the following command through the ANSYS Input
command line
/DECRYPT,PASSWORD,Encryption_Key
Where Encryption_Key is the encryption key used to encrypt the file. You can now execute the
encrypted password. To delete the current global encryption key, issue the following ANSYS
command.
/DECRYPT,PASSWORD,
Preface
Conventions Used in This Guide
1.2.1 Nomenclature
1.8.4.7 Group 5 - Indicates The End Of The 5 Record Storage For This Row
2.1.3 Abbreviations
2.1.7 Function binset (Opening a Blocked Binary File or Initializing Paging Space)
2.1.8 Subroutine bintfo (Defining Data for a Standard ANSYS File Header)
2.2.1 Program bintst (Demonstrates Dumping a Binary File and Copying It for
Comparison Purposes)
2.2.6 Subroutine rdfull (Demonstrates Reading and Reformatting the .FULL File)
2.3.2 Function rhdiqr (Retrieving Model Information from the Results File Header)
2.3.3 Function rhdget (Retrieving Analysis Information from the Results File)
2.3.4 Function rgmiqr (Retrieving Geometry Summary Information from the Results
File)
2.3.5 Function rgmget (Retrieving Geometry Information from the Results File)
2.3.6 Function rlsfnd (Retrieving Data Set Numbers for Load Steps or Substeps)
2.3.7 Function rlsiqr (Retrieving Model Information From the Results File Header)
2.3.8 Function rnsget (Retrieving Nodal Solution Data from the Results File)
2.3.9 Function resget (Retrieving Element Solution Data from the Results File)
3.3.1 R Command
3.3.4 N Command
3.3.6 EN Command
3.3.9 CP Command
3.3.10 CE Command
3.3.11 M Command
Convention Indicates
File names, which may or may not include directory paths. These are
shown as lower-case, bold text, unless case is significant. Examples are
path/filename.ext shown with the UNIX directory separator character "/" (slash); if you are
using a Microsoft Windows system, use "\" (backslash) as your directory
separator character.
Command input listings, ANSYS output listings, and text that a user
command,arg1,arg2
enters are shown in fixed-width font.
Information that supplements the main topic being discussed, such as
Note-
important tips or guidelines.
Actions or situations that can shut down ANSYS, damage files, cause loss
Warning:
of data, etc.
This guide was designed for ANSYS users that have some programming skills and wish to tap
the power of the ANSYS Parametric Design Language (APDL) to increase their productivity.
APDL is a scripting language that is very similar to Fortran 77. The guide describes how to
define parameters (variables), how to create macro programs using APDL, how to use APDL
for simple user interaction, how to encrypt an APDL macro, and how to debug an APDL
macro.
The UIDL Programmer's Guide covers the User Interface Design Language (UIDL) including
how to modify or construct menus, dialogs and online help from within ANSYS.
ANSYS provides a set of Fortran 77 functions and routines that are available to extend or
modify the program's capabilities. Using these routines requires relinking the ANSYS
program, resulting in a custom version of ANSYS. ANSYS release 5.4 provides an external
commands capability which you can use to create shared libraries available to ANSYS (either
from ANSI standard C or Fortran 77). You can use this feature to add custom extensions to
ANSYS without the need to rebuild the ANSYS executable.
The entire set of programmer's guides can be accessed online as HTML files or downloaded (in either
HTML or Postscript format) through the ANSYS documentation web site,
http://www.ansys.com/Documentation/Manuals/872. A list containing the complete set of available
ANSYS documentation is available at http://www.ansys.com/ServSupp/Library/library.html
Chapter 1: Format of Binary Data Files
Go to the Next Chapter
Go to the Table of Contents for This Manual.
● The following results files, in which the ANSYS program stores the results of solving finite
element analysis problems:
❍ Jobname.RST - A structural or coupled-field analysis
The files listed above cover almost all users' needs, although there are others. For more information, see
the ANSYS Basic Analysis Procedures Guide.
● Record ID is the identifier for this record. Not all records will have identifiers; they're indicated
only for records whose record pointers are stored in a header.
● Type indicates what kind of information this record stores.
● Number of records indicates how many records of this description are found here.
● Record length indicates the number of items stored in the record.
In some record descriptions, actual variable names used may appear in the record contents area.
Item 2 The file format. This item has a value of 0 if the file is internal, or 1 if the file is external.
· 1 for SI units
Item 5
· 2 for CSG units
Item 10 The ANSYS release level in integer form ("5.4" in character form)
Items 12-14 The machine identifier in integer form (three four-character strings)
Items 17-18 The ANSYS product name in integer form (two four-character strings)
Item 19 The ANSYS special version label in integer form (one four-character string)
Items 20-22 The user name in integer form (three four-character strings)
Items 23-25 The machine identifier in integer form (three four-character strings)
Items 41-60 The main analysis title in integer form (20 four-character strings)
Items 61-80 The first subtitle in integer form (20 four-character strings)
This section explains the contents of the results file; that is, those files with the following extensions:
.rfl .brfl
.rmg .brmg
.rst .brst
.rth .brth
.lnn
1.2.1 Nomenclature
A load case contains the results for an instance in an analysis. A load case is defined by a load step
number and a substep number. A load case is also categorized by a cumulative iteration number and
time (or frequency) values. A load case is identified by all three methods in the results file.
The results file does not have to contain all the load cases of an analysis.
For a complex analysis, there will be two data sets for each load case. The first data set contain the real
solution and the second contains the imaginary solution.
ptrGEO 0 0 0 units
nSector 0 ptrend8 0 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
where
1 - SI
2 - CSG
Most nodal data is stored in arrays equal to the number of used or reference nodes. This table equates
the actual node number to the number used for storage.
(baclst (i), i=1, nnod)
Element equivalence table. The ANSYS program stores all element data in the numerical order that the
SOLUTION processor solves the elements. This table equates the order number used to the actual
element number.
This record contains the record pointers for the beginning of each data set. The first resmax words are
the first 32 bits of the pointer and the second resmax words are the second 32 bits of the 64-bit pointer
to the data set. For files less than 8GB, the second 32 bit word is zero. To create the 64-bit pointer, use
the (system dependent) conversion routine:
LONGPTR = largeIntGet (index(i),index(i+resmax))
where i is the load set of interest and LONGPTR is integer*8.
This record contains the time (or frequency) values for each data set.
This record contains the load step, substep, and cumulative iteration numbers for each data set.
This record contains record pointers for each element type description.
Each of these records is pointed to by a record pointer given in the record labeled ptrETY.
These items are typically stored into the IELC array, and are used to determine the element type
characteristics at runtime. The following items are typically of interest:
This record contains record pointers for each real constant set.
These records contain real constant data used for the elements. (See the ANSYS Elements Reference
manual for values for a specific element.) Each of these records is pointed to by a record pointer given
in the record labeled ptrREL. The length of these records varies for each element type (actual length is
returned from routine BINRD).
This record contains the record pointers for each coordinate system set. ANSYS writes coordinate
systems only if local coordinate systems were defined. If a local system was defined, the predefined
global systems 1 to 2 also will be written. The global Cartesian system 0 will never be written.
These records contain coordinate system data for each coordinate system defined. Each of these records
is pointed to by a record pointer given in the record labeled ptrSYS. The items stored in each record are
as follows:
This group contains the node number and coordinates (in the order X,Y,Z,THXY,THYZ,THZX) of each
node.
Each of these records is pointed to by a record pointer given in the record labeled ptrEID. The length of
these records varies for each element (actual length is returned from routine BINRD). nodelm shown
here is the number of nodes for this element. Its value is defined in the element type description record.
mat, type, real, elnum, esys, death, solidm, shape, pexcl, 0, NODES.
= 0 - alive
= 1 - dead
Each set of data is pointed to by a record pointer given in the record labeled DSI.
Where:
= 0 - move
= 2 - extrapolate always
= 0 - real
= 1 - imaginary
The pointers in the solution data header (pointed to by the data sets index table) are relative to the
pointer in the index table; e.g. the element solution data is at location ptr+ptrESL, where ptr is the 64-bit
pointer from the index table. To address these records first identify the pointer offset to the file reading
routine:
call bioBasePut (nblk,LONGPTR)
To read the solution data header:
loc = bioiqr (nblk,12) ! returns the file location of the header (loc is integer*4)
call biord (nblk,loc,100,ivect(1),kbf)
and the reading of the data remains unchanged, e.g.
ptrESL = ivect(12)
call biord (nblk,ptrESL,...
The pointers in the header records in 5.5 are relative addresses.
To continue reading 5.4 and earlier files (which will be detectable by noting that only resmax DSI items
were read):
2. call bioinf (nblk,12,1) ! tell the file reading routines to use absolute addressing
where
● timfrq - time value (or frequency value, for a modal or harmonic analysis)
● lfacto - the "old" load factor (used in ramping a load between old and new values)
● lfactn - the "new" load factor
● cptime - elapsed cpu time (in seconds)
● tref - the reference temperature
● tunif - the uniform temperature
● tbulk - Bulk temp for FLOTRAN film coefs.
● 0.0 - position not used
● 0.0 - position not used
● 0.0 - position not used
● positions 11-13 -Linear acceleration terms
● positions 14-16 - Angular velocity
● positions 17-19 - Angular acceleration
● positions 20-22 - Angular velocity about the center of gravity
● positions 23-25 - Angular acceleration about the center of gravity
● positions 26-28 - Center of gravity location
● if pmeth=1: positions 31-100 - P convergence values
● if pmeth=0: positions 51-100 - Load data position 53 - Convergence key (if 1, substep
converged)
Positions 1-32 - current extra Flotran DOFs for this result set. Positions 33-64 - current extra Flotran
DOF labels for this set. Extra Flotran DOF reference numbers are as follows:
29 - 32 are spares.
The DOF solution for each node in the nodal coordinate system. The DOF order is the same as shown
above in the DOF number reference table. The nodal order is the same order given above in the nodal
equivalence table. If a DOF for a node isn't valid, a value of 2.0**100 is used. Note1: Sum dof =
numdof+nfldof. Note2: If, upon reading of this record, there is less than nnod*Sumdof items in the
record, then only a selected set of nodes were output. Another record follows (integer, less than nnod
long) which contains the list of nodes for which DOF solutions are available. (bit 10 (PDBN) in mask).
● Record ID: RF
● Type: Integer
● Number of Records: 1
● Record Length: nrf
This index is calculated as (N-1)*numdof+DOF, where N is-the position number of the node in the
nodal equivalence table, and DOF is the DOF reference number. (bit 11 (PDBR) in mask)
Reaction forces. The force values are ordered according to the DOF order shown above in the DOF
number reference table. (bit 11 (PDBR) in mask).
This index is calculated as (N-1)*numdof+DOF, where N is the position number of the node in the
nodal equivalence table, and DOF is the DOF reference number. (bit 4 in mask)
● Record ID: BC
● Type: Integer
● Number of Records: 1
● Record Length: 40 Integers
ptrFOR 0 0 0 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
where
This index is calculated as N*32+DOF, where N is the node number and DOF is the DOF reference
number. Values are in the same order as the DOF number reference table.
This record contains present and previous values (real and imaginary) of the nodal constraints at each
DOF.
This index is calculated as N*32+DOF, where N is the node number and DOF is the DOF reference
number. Values are in the same order as the DOF number reference table.
This record contains present and previous values (real and imaginary) of the nodal input force loadings
at each DOF.
1.2.6.8.5 Record 5 - Two Displacement Result Sets For Transient Solution In FLOTRAN
This record contains pointers to each element solution. The order of the elements is the same as the
order in the element equivalence table. (bit 12 (PDBE) in mask)
The solution information for each individual element is stored starting at this point in the file. The next
19 records on the file are repeated as a group nelm times (once for each element). Item nelm is defined
in the file header.
ptrECT 0 0 0 0
where
Note-If ptrxxx is negative, then all prtx items are zero and are not on the file.
This record contains the forces at each node, in the same DOF order as the DOF number reference table.
For static, damping, and inertia forces, a set of forces will be repeated (as appropriate). Number of data
items stored in this record can be calculated as follows: nodfor*NDOF*M, where NDOF is the number
of DOFs/node for this element, nodfor is the number of nodes per element having nodal forces (defined
in element type description record), and M may be 1, 2, or 3. For a static analysis, M=1 only. For a
transient analysis, M can be 1, 2, or 3.
This record contains the stresses at each corner node, in the order
SX,SY,SZ,SXY,SYZ,SXZ,S1,S2,S3,SI,SIGE. Nodal order corresponds to the connectivity defined in
the element description. Stresses can be nodal values extrapolated from the integration points or values
at the integration points moved to the nodes. If an element is nonlinear, integration point values always
will be written. (See item rxtrap in the solution header for the setting.) An element is considered
nonlinear when either plastic, creep, or swelling strains are present.
● For solid elements, stresses are at each corner node and the number of items in this record is
nodstr*11.
● For shell elements, stresses are at each corner node (first at the top surface, then the bottom) and
the number of items in this record is 2*nodstr*11.
● For layered elements (with KEYOPT(8)=0), stresses for the "first" layer are at each corner node
(first at the bottom surface of the bottom layer, then at the top surface of the top layer). Stresses
for the "second" layer are at each corner node (first at the bottom surface, then at the top surface
for the layer with the largest failure criteria). The number of items in this record is
NL*2*nodstr*11, where NL is 2 (for two layers). The second layer isn't present if failure criteria
weren't used or aren't appropriate.
● For layered elements (with KEYOPT(8)=1), stresses for each layer are at each corner node (first
at the bottom surface, then at the top surface) and the number of items in this record is
NL*2*nodstr*11, where NL is the number of layers.
● For beam elements, the contents and number of data items is element dependent. For beam
elements, see the Output Data section for the particular element in the ANSYS Elements
Reference.
where
This record contains the gradients at each corner node in the order X, Y, Z. Nodal order corresponds to
the connectivity defined in the element description. If this is a coupled-field analysis, the data is stored
in the following order (as available): fluid, thermal (TEMP), electric (VOLT), and magnetic (AZ).
Gradients can be nodal values extrapolated from the integration points or values at the integration points
moved to the nodes. See item rxtrap in the solution header for the setting. The number of items in this
record is nodstr*3*N, where N can be 1, 2, 3, or 4 (depending on the coupled-field conditions).
Element nodal component plastic strains. Strains are in the same order as the nodal-stresses given in the
record labeled ENS. Plastic strains are always values at the integration points moved to the nodes. For
beam elements, see the Output Data section for the particular element in the ANSYS Elements Reference.
Strains are in the same order as the nodal stresses given in the record labeled ENS. Creep strains are
always values at the integration points moved to the nodes. For beam elements, see the Output Data
section for the particular element in the ANSYS Elements Reference.
Strains are in the same order as the nodal stresses given in the record labeled ENS plus the element
swelling strain. Thermal strains can be nodal values extrapolated from the integration points or values at
the integration points moved to the nodes. If the element in nonlinear, integration point data always will
be written. (An element is considered nonlinear when either plastic, creep, or swelling strains are
present.) See item rxtrap in the solution header for the setting. For beam elements, see the Output Data
section for the particular element in the ANSYS Elements Reference.
● For lower-ordered elements, rotations are at the centroid and the number of items in this record is
3.
● For higher-ordered elements, rotations are at each corner node and the number of items in this
record is nodstr*3.
● For layered shells, rotations are at each corner node, plus the layer rotation angle for each layer
(real constant THETA). The number of items in this record is nodstr*3+NL, where NL is the
number of layers.
● For the layered solid, rotation angles are at the centroid, plus the layer rotation angle for each
layer (real constant THETA). The number of items in this record is 3+NL.
This record contains the fluxes at each corner node in the order X,Y,Z. If this is a coupled field analysis,
the flux data is stored in the following order: thermal, electric, magnetic. Nodal order corresponds to the
connectivity defined in the element description. Fluxes can be nodal values extrapolated from the
integration points or values at the integration points moved to the nodes. See item rxtrap in the solution
header for the setting. The number of items in this record is nodstr*3*N, where N can be 1, 2, or 3
depending on the coupled-field conditions.
This record lists the forces at each node in the order X,Y,Z. For most elements, the number of items in
this record is nodfor*3. However, for the PLANE53 element, the number of items in this record is either
nodfor*3 or nodstr*3. (See the description of KEYOPT(7) for PLANE53 in the ANSYS Elements
Reference.)
Note-nodfor and nodstr are defined in the element type description record.
The contents and number data items for this record is element dependent. See the Output Data section
for the particular element in the ANSYS Elements Reference.
This record contains the calculated current densities in the order X,Y,Z.
This record stores nonlinear data at each corner node n the order SEPL, SRAT, HPRES, EPEQ, PSV,
and PLWK, followed by 4 spares.
● For solid elements, the record contains nonlinear data at each corner node and the number of
items in this record is nodstr*10.
● For shell elements, the record contains nonlinear data at each corner node (first at the top surface,
then the bottom surface), and the number of items in this record is 2*nodstr*10.
● For layered elements, the record contains nonlinear data at each layer at each corner node (first at
the top surface, then the bottom) and the number of items n this record is NL*2*nodstr*10,
where NL = number of layers.
● For beam elements, the contents and number of data items in this record is element dependent.
For beam elements, see the Output Data section for the particular element in the ANSYS Elements
Reference.
Note-nodfor and nodstr are defined in the element type description record.
The length of this record is nsurf*19 where nsurf is the number of surfaces that have surface stress
information. The stress information is simply repeated in the format shown below for each surface.
For 2d elements:
For 3d elements:
s2 s3 sint seqv
where:
This record contain the element normal pressures (one value per face). See the ANSYS Elements
Reference for a description of the element face pressures.
This record stores contact data at each corner node in the order, STAT, PENE, PRES, STOTAL, and
SLIDE, followed by four spaces.
kan 0 0 0 0
0 0 0 0 0
ptrFRQ ptrDSP 0 0 0
0 0 0 0 0
0 0 0 0 0
Where
(curdof(i),i=1,numdof)
UX = 1 UY = 2 UZ = 3 ROTX= 4 ROTY= 5
ROTZ= 6 AX = 7 AY = 8 AZ = 9 VX =10
● Record ID:N/A
● Type: Integer
● Number of Records: 1
● Record Length: lenbac
This table equates the actual node number to the number used for storage. (baclst(i),i=1,lenbac)
where
The DOFs are calculated as (N-1)*numdof+DOF, where N is the position number of the node in the
nodal equivalence table and DOF is the DOF reference number given above.
If the analysis uses the reduced method, the original DOF order (see next record) is rearranged so that
DOFs having nodal constraints are listed first.
If the analysis uses the mode superposition method (using the reduced mode extraction technique), the
DOF order is the same as the original order (see next group). (l(i),i=1,nmrow)
The DOFs are calculated as (N-1)*numdof+DOF, where N is the position number of the node in the
nodal equivalence table and DOF is the DOF reference number given above.
If the analysis uses the reduced method, the original DOF order, plus the number of nodal constraints
(nbcdsp), is stored.
If the analysis uses the mode superposition method (using the reduced mode extraction technique), this
record matches the previous record. The nmrow+1 entry will be zero. (lorig(i),i=1,nmrow),nbcdsp
This record is present only if the analysis uses the reduced method and nbcdsp > 0 (see record at
ptrDOF). These numbers are the positions in the previous record of DOFs with a nodal constraint. These
are nodal constraints only on nodes that also are masters. (na(i),i=1,nbcdsp)
Each row of the matrix is stored as a record. The matrix is present only if nmatrx > 0 and analysis is not
using mode superposition method (using the subspace mode extraction method). Row order is the same
as the DOF order in record at ptrDOF. (ak(i,j),i=1,nmrow)
Each row of the matrix is stored as a record. The matrix is present only if nmatrx > 1 and analysis is not
using mode superposition method (using the subspace extraction technique). Row order is the same as
the DOF order in record at ptrDOF. (am(i,j),i=1,nmrow)
If the analysis uses the reduced method, each record will be nmrow items in length. The reduced
damping matrix is present only if nmatrx > 2. There will be nmrow records of this type stored here.
Row order is the same as the DOF order in record at ptrDOF.
If the analysis uses the mode superposition method (using the reduced mode extraction technique), each
record will be nmode items in length. These records contain mode shapes (eigenvectors) of the
frequencies (eigenvalues) actually used in the harmonic analysis. There will be nmode records of this
type stored here, with the first N records containing the mode shapes and the other records containing
zeros, where N is the number of modes actually used in the harmonic-analysis. Order corresponds to the
DOF order given in record at ptrDOF.
If the analysis uses the mode superposition method (using the subspace mode extraction technique), this
record will not be present.
(psi(i,j),i=1,nmrow) (or ac)
This record is present only if the analysis uses the mode superposition method. The first nmode values
are the frequencies extracted from the modal analysis. The remaining values have no meaning.
(freq(i),i=1,nmrow)
The first nmrow entries are the displacements in the same order as the original set of DOFs (see record
AFTER ptrDOF). For the last five entries:
3. Substep number
5. Scale factor (zero if the analysis uses the reduced method). (u(i),i=1,nmrow),time,itime,iter,ncumit,
scale
Note-If , upon reading this record, there is less than nmrow+5 items in the record, then only a selected
set of nodes were output. Another record follows (integer, less than lenbac long) which contains the list
of nodes for which DOF solutions are available.
The order of these forces corresponds to the node position order given in record at ptrDNC. This record
is present only if the analysis uses the reduced method and ngaps > 0. (fgaps(i),i=1,ngaps)
kan 0 0 0 0
0 0 0 0 0
ptrFRQ ptrDSP 0 0 0
0 0 0 0 0
0 0 0 0 0
where:
UX = 1 UY = 2 UZ = 3 ROTX= 4
ROTY= 5 ROTZ= 6 AX = 7 AY = 8
This table equates the actual node number to the number used for storage. (baclst(i),i=1,lenbac)
The DOFs are calculated as (N-1)*numdof+DOF, where N is the position number of the node in the
nodal equivalence table and DOF is the DOF reference number given above.
If the analysis uses the reduced method, the original DOF order (see next record) is rearranged so that
DOFs having nodal constraints are listed first.
If the analysis uses the mode superposition method (using the reduced mode extraction technique), the
DOF order is the same as the original order (see next record). (l(i),i=1,nmrow)
1.4.3.5 Group 5 - Original Reduced Set Of Degrees Of Freedom Used
The DOFs are calculated as (N-1)*numdof+DOF, where N is the position number of the node in the
nodal equivalence table and DOF is he DOF reference number given above.
If the analysis uses the reduced method, the original DOF order, plus the number of nodal constraints
(nbcdsp), is stored.
If the analysis uses the mode superposition method (using the reduced mode extraction technique), this
record matches the previous record. The nmrow+1 entry will be zero. (lorig(i),i=1,nmrow),nbcds
This record is present only if the analysis uses the reduced method and nbcdsp > 0 (see record at
ptrDOF). These numbers are the positions in the previous record of dofs with a nodal constraint. These
are nodal constraints only on nodes that also are masters. (na(i),i=1,nbcdsp)
Each row of the matrix is stored as a record. The matrix is present only if nmatrx > 0 and analysis is not
using mode superposition method (using the subspace mode extraction method). Row order is the same
as the DOF order in record at ptrDOF. (ak(i,j),i=1,nmrow)
Each row of the matrix is stored as a record. The matrix is present only if nmatrx > 1 and analysis is not
using mode superposition method (using the subspace extraction technique). Row order is the same as
the DOF order in record at ptrDOF. (am(i,j),i=1,nmrow)
If the analysis uses the reduced method, each record will be nmrow items in length. The reduced
damping matrix is present only if nmatrx > 2. There will be nmrow records of this type stored here.
Row order is the same as the DOF order in record at ptrDOF.
If the analysis uses the mode superposition method (using the reduced mode extraction technique), each
record will be nmode items in length. These records contain mode shapes (eigenvectors) of the
frequencies (eigenvalues) actually used in the harmonic analysis. There will be nmode records of this
type stored here, with the first N records containing the mode shapes and the other records containing
zeros, where N is the number of modes actually used in the harmonic analysis. Order corresponds to the
DOF order given in record at ptrDOF.
If the analysis uses the mode superposition method (using the subspace mode extraction technique), this
record will not be present. (psi(i,j),i=1,nmrow) (or ac)
This record is present only for analyses using the mode superposition method (using the reduced mode
extraction technique). (freq(i),i=1,nmrow)
The first nmrow entries are the displacements in the same order as the original set of DOFs (see record
AFTER ptrDOF). For the last five entries:
4. zero zero
5. scale factor (zero if the analysis uses the reduced method) zero
Note-If , upon reading this record, there is less than nmrow+5 items in the record, then only a selected
set of nodes were output. Another record follows (integer, less than lenbac long) which contains the list
of nodes for which DOF solutions are available.
ptrLPM ptrSP1 0 0 0
0 0 0 0 0
Where
= 1 - lumped
= 0 - reduced
= 1 - subspace
= 3 - unsymmetric Lanczos
= 4 - damped Lanczos
= 6 - block Lanczos
= 0 - Frontal solver
= 1 - Power Dynamics
= 1 - buckling
= 2 - modal
UX = 1 UY = 2 UZ = 3 ROTX= 4 ROTY= 5
ROTZ= 6 AX = 7 AY = 8 AZ = 9 VX =10
This table equates the actual node number to the number used for storage. (baclst(i),i=1,lenbac)
This record is present only if extopt = 0. The DOFs are calculated as (N-1)*NUMDOF+DOF, where N
is position number of the node in the nodal equivalence table and DOF is the DOF reference number
given above
(l(i),i=1,nmrow) (if nmatrx>0)
Frequencies are complex if extopt=3 or 4. Numbers stored are the squares of the natural circular
frequencies (
**2, where
=radians/time). You can obtain the natural frequencies, f (in cycles/time), using the equation.
f=
/2
(freq(i),i=1,nmode)
(modecf(i),i=1,nmode)
(dampmd(i),i=1,nmode)
Mode shapes are complex if extopt=3 or 4. If extopt=0, the mode shape order corresponds to the DOF
list stored at position ptrRDF. If extopt does not equal 0, the order corresponds to the nodal equivalence
table.
(psi(i,j),i=1,nmrow)
This record is present only if lumpms=1 and nmatrix=0. It is a vector containing the mass at each node
in the system.
(mass(i),i=1,nmrow)
Each row of the matrix is stored as a record. The matrix is present only if nmatrx > 0. Row order is the
same as the DOF order stored at position ptrRDF.
(ak(i,j),i=1,nmrow)
1.5.4.2 Group 2 - Reduced Mass Matrix
Each row of the matrix is stored as a record. The matrix is present only if nmatrx > 1. Row order is the
same as the DOF order stored at position ptrRDF.
(am(i,j),i=1,nmrow)
Each row of the matrix is stored as a record. The matrix is present only if nmatrx > 2. Row order is the
same as the DOF order stored at position ptrRDF.
(ac(i,j),i=1,nmrow)
kygrf 0 0 0 0
0 0 0 0 0
0 0 0 0 0
Where
= 0 - do not calculate
= 1 - calculate
= 0 - do not calculate
= 1 - calculate
= 0 - do not calculate
= 1 - calculate
= 0 - do not calculate
= 1 - calculate
= 0 - do not calculate
= 1 - calculate
Where
UX = 1 UY = 2 UZ = 3 ROTX= 4 ROTY= 5
ROTZ= 6 AX = 7 AY = 8 AZ = 9 VX =10
This table equates the actual node number to the number used for storage.
(baclst(i),i=1,lenbac)
The ANSYS program stores all element data in the numerical order that the SOLUTION processor
solves the elements. This table equates the order number used to the actual element number
(eorder(i),i=1,nume)
This record specifies the file location for the beginning of the data for each element.
(index(i),i=1,nume)
where
= 1 - matrix present
= 1 - matrix present
= 1 - matrix present
= 1 - matrix present
= 1 - vector used
= 1 - vector used
This record specifies the DOF locations of this element matrix in relation to the global matrix. The
index is calculated as (N-1)*NUMDOF+DOF, where N is the position number of the node in the nodal
equivalence table and DOF is the DOF reference number given above.
This record is repeated for each stiffness, mass, damping, and stress stiffening matrix. If the matrix is
diagonal, the length of the records will be nmrow. If the matrix is unsymmetric, the length of the records
will be nmrow*nmrow. If the matrix is symmetric, only the lower triangular terms are written and the
length of the records will be (nmrow)*(nmrow+1)/2.
This record contains both the applied force vector and the (restoring or imaginary) load vector. ANSYS
always writes this record.
where
= 0 - symmetric
= 1 - unsymmetric
= 1 - matrix is on file
= 1 - matrix is on file
= 1 - matrix is on file
= 1 - matrix is on file
>0 - substructure copied from another substructure, via either SESSYM or SETRAN
● name3 - third four characters of the substructure file name, in integer form
● name4 - fourth four characters of the substructure file name, in integer form
● ptrDOF - pointer to the DOF/node list
● ptrDST - pointer to the local DOF set
● ptrBAC - pointer to the nodes comprising the substructure
● ptrTIT - pointer to the title
● ptrNOD - pointer to the unique nodes defining the substructure
● ptrXYZ - pointer to the coordinates of the unique nodes
● ptrEDG - pointer to the substructure edges
● ptrGDF - pointer to the global DOF set
● thsubs - thermal key
= 0 - structural
= 1 - thermal
= 1 - axisymmetric
= 2 - 2-D
= 3 - 3-D
Note-name1-8 are the inexc4 representation of the 32 character filename. name1-2 and name5-8 will be
"0" for pre revision 5.2 files.
Note-If ntrans > 0, records from position ptrDOF to ptrGDF will be identical to the data for the copied
substructure.
= 1 - x coordinate
= 2 - y coordinate
= 3 - z coordinate
● 4th variable - reference number of coordinate system to be used for symmetry operation
UX = 1 UY = 2 UZ = 3 ROTX= 4 ROTY= 5
ROTZ= 6 AX = 7 AY = 8 AZ = 9 VX =10
This record contains degrees of freedom for this substructure of the unique nodes, as used with this
substructure, in ascending order. This index is calculated as (N-1)*numdof+DOF, where N is the node
number and DOF is the DOF reference number given above
(lsort(i),i=1,nmrow).
This record stores the positions of the local DOF set in relation to the generated DOF set.
(lposit(i),i=1,nmrow).
This index is calculated as (N-1)*NUMDOF+DOF, where N is the position number of the node in the
nodal equivalence table and DOF is the DOF reference number given above (lorig(i),i=1,nmrow).
This group describes nodes that defined the substructure during the generation pass of the analysis.
Nodal data is stored in arrays equal to the number of used or referenced nodes. This table equates the
number used for storage to the actual node number.
(baclst(i),i=1,lenbac).
This record describes unique nodes defining the substructure for the use pass of the analysis. These are
also the nodes having master degrees of freedom. (node(i),i=1,nnod)
This record describes the coordinates of a unique node, in the order X, Y, Z, THXY, THYZ, and THXZ.
Nodal order corresponds to that of the node list given above.
(xyzang(j,i),j=1,6)
This record describes global degrees of freedom of the unique nodes in ascending order, as used during
the analysis use pass. This index is calculated as (N-1)*32+DOF, where N is the node number and DOF
is the DOF reference number given above (l(i),i=1,nmrow) (sorted)
--- dp 1 nmrow Row of the stress stiffening matrix, if nmatrx > 3. (gs(i,j),i=1,nmrow)
LOD dp nvect nmrow This record contains the load vectors. (f(i),i=1,nmrow)
ptrEN2 0 0 ptrTRI 0
where
= 1 - lumped
● ptrMS1, ptrMS2 - These two values are two halves of a 64 bit pointer that points to the master
DOF list
● ptrEN1, ptrEN2 - These two values are two halves of a 64 bit pointer that points to the end of file
● 0 - position not used
● 0 - position not used
● ptrTRI - pointer to the beginning of the triangularized matrix data
● 0 - position not used
UX = 1 UY = 2 UZ = 3 ROTX= 4 ROTY= 5
ROTZ= 6 AX = 7 AY = 8 AZ = 9 VX =10
This table equates the actual node number to the number used for storage. (baclst(i),i=1,lenbac)
The next two descriptions show the format for a row that does not have a constraint equation associated
with it:
If keyuns=0, this record will contain the non diagonal terms of this column, the diagonal term itself, the
normalized F term, followed by the reciprocal of the row pivot.
If keyuns=1, this record will contain the non-diagonal terms of this column, the diagonal term itself, the
normalized F term, the reciprocal of the row pivot, followed by the non-diagonal terms of this row.
The length of this record will vary (actual length is returned from routine BINRD). If kan=3, this record
contains complex information, otherwise it contains double-precision information.
(ktri(i),i=1,n),vload,diag (symmetric) - (ktri(i),i=1,n), vload, diag,(utri(i),i=1,n) -(unsymmetric)
The first item signifies what term in the row belongs to the pivot. The second term signifies what DOF
is being eliminated, and the remaining items signify the new DOFs being introduced (if any). The length
of this record will vary (actual length is returned from routine BINRD). (lll(i),i=1,m)
The next five descriptions show the format for a row that has a constraint equation associated with it.
The length of this record will vary (actual length is returned from the routine BINRD).
(coeff(i), i=1, n+2)
If keyuns=0, this record will contain the non diagonal terms of this column, the diagonal term itself, the
normalized F term, followed by the reciprocal of the row pivot.
If keyuns=1, this record will contain the non-diagonal terms of this column, the diagonal term itself, the
normalized F term, the reciprocal of the row pivot, followed by the non-diagonal terms of this row.
The length of this record will vary (actual length is returned from routine BINRD). If kan=3, this record
contains complex information, otherwise it contains double-precision information.
(ktri(i),i=1,n),vload,diag (symmetric) - (ktri(i),i=1,n), vload, diag, (utri(i),i=1,n) -(unsymmetric)
The first item signifies what term in the row belongs to the pivot. The second term signifies what DOF
is being eliminated, and the remaining items signify the new DOFs being introduced (if any). The length
of this record will vary (actual length is returned from routine BINRD). (lll(i),i=1,m)
It is included for situations when the file is being read from the bottom up. Its contents:
● -cenum: n
● cenum: the constraint equation number for the constraint equation stored above
● n: the length of a row of the matrix being written
This record is present only if nmast > 0. This index is calculated as (N-1)*NUMDOF+DOF, where N is
the position number of the node in the nodal equivalence table, and DOF is the DOF reference number
given above.
ncefull ncetrm 0 0 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
Where
= 1 - lumped
= 0 - reduced
= 1 - lumped
= 3 - unsymmetric Lanczos
= 4 - damped Lanczos
= 6 - block Lanczos
● jcgnmx - currently not used. This position reserved for future development.
● sclstf - scale factor for matrices
● nxrows - the maximum rank for this solution
● ptrIDX - pointer to the matrix row indices.
● 0 - position not used
● ncefull- Number of constraint equations on the full file
● ncetrm - Total number of terms in the constraint equations
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
● 0 - position not used
UX = 1 UY = 2 UZ = 3 ROTX= 4 ROTY= 5
ROTZ= 6 AX = 7 AY = 8 AZ = 9 VX =10
This table equates the actual node number to the number used for storage. (baclst(i),i=1,lenbac)
The next five records are repeated as a group nontp times. When the matrices get written, one row of
each matrix is written to the file at a time. i.e. the first row of each matrix is written, then the second
row of each matrix, etc. this pattern continues until all the rows of each matrix have been written to the
file. If kan=3, the matrix rows will be complex valued, otherwise they will be double precision values.
Note-NOTE: If the FULL file was generated at revision 5.2, there will be some extra records at this
point. These extra records are undocumented at this time.
The first item signifies what term in the row belongs to the pivot. The second term signifies what DOF
is being eliminated, and the remaining items signify the new DOFs being introduced (if any). The length
of this record will vary (actual length is returned from routine BINRD)
(lll(i),i=1,m)
Indicates positions and values of terms to be reduced. The length of this record will vary (actual length
is returned from routine BINRD)
(index(i),i=1,n) for compressed rows
If keyuns=0, this record will contain the non-diagonal terms of this column, the diagonal term itself,
followed by the normalized F term.
If keyuns=1, this record will contain the non-diagonal terms of this column, the diagonal term itself, the
non-diagonal terms of this row, followed by the normalized F term.
If lumpm = 1, then the mass for this node is located after the F term. The length of this record will vary
(actual length is returned from routine BINRD)
(krow(i),i=1,n), vload, (mass) (symmetric) (n-1 column) diag (n-1 row) load (dmass) (unsymmetric)
If keyuns=0, this record will contain the non-diagonal terms of this column, the diagonal term itself,
followed by the normalized F term.
If keyuns=1, this record will contain the non-diagonal terms of this column, the diagonal term itself,
followed by the non-diagonal terms of this row.
The length of this record will vary (actual length is returned from routine BINRD)
(mrow(i),i=1,n) (symmetric) (n-1 column) diag (n-1 row) (unsymmetric)
If keyuns=0, this record will contain the non-diagonal terms of this column, the diagonal term itself,
followed by the normalized F term.
If keyuns=1, this record will contain the non-diagonal terms of this column, the diagonal term itself,
followed by the non-diagonal terms of this row.
The length of this record will vary (actual length is returned from routine BINRD)
(ceqn(i),i=1,n) (symmetric) (n-1 column) diag (n-1 row) (unsymmetric)
Your distribution medium also includes sample FORTRAN source files which employ the BINLIB library:
bintrd.F The bintrd subroutine, which reads and prints the contents of an ANSYS binary file
bintwr.F The bintwr subroutine, which copies an ANSYS binary file to a new file
The bintst program, which calls the bintwr and bintrd subroutines as an example of how to use the binlib
library to print the contents of a file, copy the original file to a new file, and then print the contents of the new
bintst.F
file. Routine bintst has no inputs or outputs. It requires use of the bintcm common. (For more information, see
the descriptions of the bintrd and bintwr routines later in this chapter.)
These files also reside in the subdirectory \ansys55\custom\misc (on Windows systems) or /ansys55/custom/misc (on
UNIX systems). To compile and link the bintst program, execute the CUSTOM procedure from this subdirectory.
1. An ANSYS binary file is a direct access, unformatted file. You read or write a record by specifying (as a number) what
location to read or write.
2. Before the ANSYS program actually writes data to a file on a disk, it uses buffers to store data in memory until those
buffers become full. A block number designates these buffers. Most access routines use this block number.
3. By default, ANSYS files are external files. The standardized "external" format the files use enables you to transport
them across different computer systems.
4. In addition to file names, ANSYS uses file numbers to identify the files. File handles and other information are
associated with the file numbers.
5. Some binary files contain data values that point to the start of certain data (for example, the start of the data steps index
table record). Both the ANSYS program and external binary files access routines use these pointers to locate data on the
various binary files.
AUX2 doesn't use the data pointers discussed in item 5 above. It uses record numbers to locate the binary file data to
dump. Although the information that AUX2 provides includes the pointer, using the pointer alone won't get you that
information. To get it, you must correlate the pointer and the record number by trial and error.
2.1.3 Abbreviations
The input and output for the routines discussed in this chapter are described with the following abbreviations:
int - integer
dp - Double-precision
char - character
sc - scalar variable
ar(n) - array of size n
in - input only
out - output only
inout - both an input and an output variable
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout
c
c input arguments:
c variable (typ,siz,intent) description
c nblk (int,sc,in) - the block number to close
c (as defined with subroutine binset)
c stat (chr,sc,in) - keep or delete flag
c = 'K' - keep file
c = 'D' - delete file
c buffer (int,ar(*),inout) - work array for paging, should be the
c same array as used in binset
c
c output arguments:
c variable (typ,siz,intent) description
c buffer (int,ar(*),inout) - work array for paging
intpdp int, sc, comm The number of integers per double precision word
Note-The bintst program is not part of the binlib.a library. It is included here only to aid you.
Note-The bintrd routine and the bintwr routine described below aren't part of binlib.a. This chapter includes it only to aid
you. You can find the source for this routine on the ANSYS distribution medium.
● COMMON/BINTCM/ IOUT,INTPDP,LENFNM,RECLNG
● Iout is the output unit number.
● Intpdp is the number of integers per double precision word.
● Lenfnm is the number of characters in the filename.
● Reclng is the system record length.
c *********************************************************************
c * Program to write ANSYS substructure file with usrsub. To be *
c * used as a base for 3rd party companies to create their routines *
c * for writing the file. *
c *********************************************************************
c * This program is for use in ANSYS Rev 5.x *
c *********************************************************************
c input arguments:
c jobnam jobname of problem
c pname name of substructure file to be created
c units units of the problem
c 0 - user defined
c 1 - si
c 2 - csg
c 3 - british using feet
c 4 - british using inches
c nmat number of matrices:
c 1 - stiffness only
c 2 - stiffness and mass
c 3 - stiffness, mass, and damping
c 4 - stiffness, mass, damping, and stress stiffness
c nrow number of rows in substructure matrices
c nfor number of load vectors
c nnod number of unique nodes
c kuns 0 - symmetric matrices
c 1 - unsymmetric matrices
c thsubs 0 - structural substructure
c 1 - thermal substructure
c dimkey dimensionality key
c 1 - axisymmetric
c 2 - 2d
c 3 - 3d
c nodes(nrow) list of substructure nodes BY row
c direct(nrow) list of substructure degrees of freedom by row
c (4 characters, upper case, left justified)
c (see idhed for possibilities)
c ldof(nrow) scratch array of integer DOF numberS
c k(nrow,nrow) stiffness matrix (symmetric)
c m(nrow,nrow) mass matrix (symmetric)
c c(nrow,nrow) damping matrix (symmetric)
c g(nrow,nrow) stress stiffening matrix (symmetric)
c for(nrow) matrix of load vectors (one column per vector)
c title title for substructure
c nodlst(nnod) array of unique nodes (order is insignficant)
c xyzang(6,nnod) node locations in nodlst order
If you want to use the rdfull subroutine, be sure to define your analysis as modal by issuing the command ANTYPE,2.
You also need to specify full subspace mode; to do so, issue the command MODOPT,SUBSP,nmode,0,0, ,OFF. (The
nmode argument isn't used; it can be any value.)
If you want to use the free stiffness and mass matrices, make sure that there are no constraints on your model.
2.3 Results File Access Routines
You can use the routines that retrieve data from the results file with the file access routines used to access other binary
files. You can retrieve these routines from the customer download area on the ANSYS web site.
Note-You must use this routine first to set the required pointers to data in the results file.
2.3.3 Function rhdget (Retrieving Analysis Information from
the Results File)
function rhdget (key,iarry,iwork)
c *** primary function: return information from a results file header
c *** secondary functions: none
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout
c
c input arguments:
c variable (typ,siz,intent) description
c key (int,sc,in) - type of information requested
c = 1 - return number dof/node
c = 2 - return node order list
c = 3 - return element order list
c iwork (int,ar(*),inout) - work array for paging when reading file
c should be same array used in binset
c
c output arguments:
c variable (typ,siz,intent) description
c rhdiqr (int,func,out) - status of info get
c > 0 - number of items returned
c = 0 - error on retrieving data
c iarry (int,ar(*),out) - requested information
Note-You must use this routine first to set the required pointers to data in the results file.
In the following list, commands or menu paths shown with an asterisk (*) are the minimum
requirements for a solution.
Defines nonlinear
TB Main Menu>Preprocessor>Material Props>Data Tables material data, some
element data, or both
Main Menu>Preprocessor>Create>
N* Defines a nodal location
Nodes>In Active CS or On Working Plane
Main Menu>Preprocessor>-Loads-
F Defines nodal forces
>Apply>force type>On entity
Main Menu>Preprocessor>-Loads_ Defines surface loads on
SF or SFE
>Apply>surface load type>On entity element faces
● If you place the command /NOPRINT at the beginning of the file and /GOPRINT at the end
of the file, you can suppress printing of the file and speed up the time to read it.
● Use the /COM command to add comments to the file. If the file contains the /NOPRINT
command, /COM provides status information about what is being read in. For example:
● Group elements with the same attributes (TYPE, REAL, MAT, ESYS). Don't use a separate
MAT, REAL, TYPE, and ESYS command for each element.
● Use Utility Menu>File>Change Title or the /TITLE command to add a title to graphics
displays and printouts.
● Use Utility Menu>File>Read Input From or the /INPUT command at the Begin level to
input the file.
The Jobname.cdb file contains selected geometry (nodes and elements), load items, and other model
data in terms of ANSYS input commands. (For a complete list of data in the file, see the CDWRITE
description in the ANSYS Commands Reference.) You can convert this information to a format
compatible with the program into which you're importing it. The next few pages describe special
considerations and commands you may need to do this conversion.
Note-Files created by the CDWRITE command have the active coordinate system set to Cartesian
(CSYS, 1),
You can change the labels to reflect the degrees of freedom of the other program by issuing the
command /DFLAB. If you're customizing the DOF labels, /DFLAB must be the first command you
enter within the ANSYS program. You may want to include the command in the ANSYS start-up file,
START.ANS. You can use /DFLAB only at the Begin processing level.
/DFLAB assigns or reassigns the "displacement" and "force" labels in the ANSYS DOF list. For
example, degree of number 1 is predefined to have a displacement label of UX and a force label of
FX, but you can assign new labels to this DOF using by issuing /DFLAB. Changing predefined labels
generates a warning message.
/DFLAB,NDOF,LabD,LabF
You can also use /DFLAB to assign labels to spare degree of freedom numbers. Spare displacement
and force labels are from 13 to 18 and from 27 to 32. All other DOF numbers are predefined, as
follows:
2 UY FY
3 UZ FZ
4 ROTX MX
5 ROTY MY
6 ROTZ MZ
7 AX CSGX
8 AY CSGY
9 AZ CSGZ
10 VX VFX
11 VY VFY
12 VZ VFZ
19 PRES FLOW
20 TEMP HEAT
21 VOLT AMPS
22 MAG FLUX
23 ENKE NPKE
24 ENDS NPDS
25 EMF CURT
26 CURR VLTG
3.3.1 R Command
The R command defines a real constant set. You repeat the command until all real constants for this
set are defined. The command format in Jobname.CDB is:
R,R5.0,NSET,Type,STLOC,VAL1,VAL2,VAL3
STLOC The starting location in the table for the next three constants
VAL1,VAL2,VAL3 Real constant values assigned to three locations in the table starting at STLOC
LOCAL,R5.0,Type,NCSY,CSYTYP,VAL1,VAL2,VAL3
The type of data to be defined. Valid labels are LOC (read in system origin),
Type
ANG (read in rotation angles), and PRM (read in system parameters).
NCSY The coordinate system reference number
Values to be read
where
The solid model key. The node is part of a solid model if the keyword SOLID appears
Solkey
here.
Data descriptors defining the format. For the NBLOCK command, this is always
Format
(3i8,6e16.9).
● Field 1 - Node.
● Field 2 - The solid model entity (if any) in which the node exists.
● Field 3 - The line location (if the node exists on a line).
● Fields 4-6 - The nodal coordinates.
● Fields 7-9 - The rotation angles.
The final line of the block is always an N command using a -1 for the node number. The following
example shows a typical NBLOCK formatted set of node information. Note that this example has no
rotational data, so that it only contains the first six fields.
3.3.4 N Command
If the UNBLOCKED option is used with the CDWRITE command, then the N command defines a
node. This is also the method used for defining nodes in .CDB files before ANSYS 5.4. The
command format in Jobname.CDB is:
N,R5.3,Type,NODE,SOLID,PARM,VAL1,VAL2,VAL3
The type of data to be defined. Valid labels are LOC (read in system origin) and
Type
ANG (read in rotation angles).
Values to be read
VAL1,VAL2,VAL3 ● If Type is LOC, values are the system origin in global Cartesian
coordinates.
● If Type is ANG, values are the rotation angles in degrees.
where
NUMFIELD The number of fields in the blocked format (the default is 19).
The solid model key. The element is part of a solid model if the keyword SOLID
Solkey
appears here.
Data descriptors defining the format. For the EBLOCK command, this is always
Format
(19i7).
3.3.6 EN Command
If the UNBLOCKED option is used with the CDWRITE command, then the EN command is used to
define an element. This is also the method used for defining elements in .CDB files before ANSYS
5.4. If an element contains more than eight nodes, the EN command is repeated until all nodes are
defined. The command format in Jobname.CDB is:
EN,R5.1,Type,NUMN,I1,I2,I3,I4,I5,I6,I7,I8
The type of data to be defined. Valid labels are ATTR (read in element
Type
attributes) and NODE (read in nodes defining the element).
● If Type is ATTR, the values are the element attributes. Attributes are in
I1,I2,I3,I4,I5,I6,I7,I8
the order: NUMN,MAT,TYPE,REAL,NUMELEMENT,ESYS,
Solid_Ref,Birth/Death,Pexclude
● If Type is NODE, the values are the node numbers.
MPTEMP,R5.0,LENGTH,STLOC,TEMP1,TEMP2,TEMP3
STLOC The starting location in the table for the next three temperature values
TEMP1,
TEMP2, Temperatures assigned to three locations in the table starting at STLOC
TEMP3
MPDATA,R5.0,LENGTH,Lab,MAT,STLOC,VAL1,VAL2,VAL3
VAL1,VAL2,VAL3 Property values assigned to three locations in the table starting at STLOC
3.3.9 CP Command
The CP command defines a coupled node set. You repeat the command until all nodes are defined.
The command format in Jobname.CDB is:
CP,R5.0,LENGTH,NCP,Dlab,N1,N2,N3,N4,N5,N6,N7
N1,N2,N3, N4,N5, N6,N7 The next seven node numbers in the coupled set
3.3.10 CE Command
The CE command defines the constant term in a constraint equation. The command format in
Jobname.CDB is:
CE,R5.0,Type,LENGTH,NCE,CONST
Another version of the CE command defines the variable terms in a constraint equation. You must
issue this version of the command after the CE command described above. This command repeats
until all terms are defined.
CE,R5.0,Type,N1,Dlab1,C1,N2,Dlab2,C2
C1 The coefficient of N1
C2 The coefficient of N2
3.3.11 M Command
The M command defines a master degree of freedom. The command format in Jobname.CDB is:
M,R5.0,NODE,Dlab
SFE,ELEM,LKEY,Lab,KEY,R5.0
ELEM The element number
● PRES (pressure)
● CONV (convection)
Lab ● HFLU (heat flux)
● IMPD (impedance)
● SEL (substructure load vector)
● SELV (S. E. load vectors)
● CHRG (charge density)
A value key. If it's 1, the values are real (film coefficient if convection). If it's 2, values are
KEY
imaginary (bulk temperature if convection).
SFBEAM,ELEM,LKEY,Lab,R5.0,DIOFFST,DJOFFST
Lab A label indicating the type of surface load. PRES (for pressure) is the only valid label.
● Source code, with comments, for a program called PLOT33 which plots all of the plots on the coded plot file.
You can link this program with user-supplied Calcomp HCBS software (plot, plots, symbol) or other software
that uses the Calcomp subroutine protocol. For example, Hewlett-Packard's ISPP product, Tektronix's Preview
product, and Veratec's Versaplot product use the Calcomp protocol.
To work with other plotter software, you may need to remove the calls to the Calcomp subroutine (plot, plots,
and symbol) and substitute the subroutine calls for the plotter software being used.
Note-Because ANSYS customers use a wide variety of plotters, ANSYS, Inc. can't verify the use of the PLOT33
program with all plotter types.
● A description of the format for the ANSYS neutral graphics file. This listing excludes format information for z-
buffered graphics, but the PLOT33 program does include a section on z-buffered graphics.
KPX is the resolution specified by the /GFILE,SIZE command (where SIZE is the pixel resolution) or by choosing
menu path Utility Menu>PlotCtrls>Redirect Plots>To File. Default resolution is 800.
Most ANSYS users won't need to know the format of the graphics file. However, in rare cases, you may want to edit
your graphics file or, as a programmer, you may need to know the file format to write a program that reads it. Although
the file is ASCII coded, it can be difficult to interpret. This section gives details about the file format.
● Numerals 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9
● Uppercase alphabetic characters A through Z
● The following characters: $ ( ) * + , - . < = >
● The space character, " ".
Within a graphics file, one directive directly follows the preceding directive. For example, below is the first line of a
graphics file:
The Text-Size directive, which determines the type size of displayed text strings. The 2
2A
is the command character, and A represents the size value.
The Window directive, which sets the coordinates for the displayed image. 0 is the
command character. AAAAAA represents the first set of coordinates (the lower left
0AAAAAAPPPLPO
corner of the image), and PPPLPO represents the second coordinate set (the right upper
corner of the image).
The Text-Color directive, which sets the color of displayed text. > is the command
>AP
character. AP is a parameter value specifying the color.
The first of several Text directives. $ is the command character, MEKLKB are the
$MEKLKBAJANSYS 5.3 coordinates for the text, AJ is the number of characters in the string, and ANSYS 5.3 is
the text string itself.
$MEKLEFALNOV 15 1996 A second Text directive, defining the position and length of the string NOV 15 1996.
$MEKKOJAI10:01:40 A third Text directive, defining the position and length of the string 10:01:40
The descriptions of graphics file directives in the next section include discussions of the parameter or parameters for
each directive. There are five types of parameters:
Xy 6 bytes, base 16 (letters A through P) 0 through 4095, mapped to coordinate space of -1.0 to 1.67
String An array of Nchar characters Characters from the common character set.
The next few pages describe each of the graphics file directives. Parameters are always specified in the order shown
below.
Graphics Directive Command Character Parameters Parameter Types
Start_Plot ( kcntr - Defines whether the display Int, Int, Int, Int, Int
uses a contour color map or shading
color map (1 = contour, 0 = shading)
Below is the list of color specifications used by the directives that set colors for areas, graphs, and text. If more than a
single intensity of a color is available, use the value specified by the Normal directive to complete the selection.
Normal of 0 represents the lowest intensity and normal of 255 represents the highest intensity.
Value Color
Black
Cyan
Blue-Magenta
0
1 Red
2
3
Cyan-Blue
4
5
Magenta-Red
6
7
8 Green
9
Orange
10
Magenta
11
Yellow-Green
12
Blue
13
Green-Cyan
14
Yellow
15
Dark Gray
Light Gray
White
16
:
Reserved for future use
127
Blue
Cyan
Green
128
:
:
Indices 128 through 255 represent the color spectrum used to display the Low (Blue) to High (Red) contour
values.
:
:
255
Yellow
Orange
Red
● The ANSYS command stream used to create a simple graphics plot, shown in Figure 4-2 below
● The encoded graphics file that these commands produce
● The decoded graphics plot directives
/PREP7
/TITLE, ANSYS 5.3 Example Graphics File
N,1,1
N,2,2
NGEN,2,2,1,2,1,,1
ET,1,42
E,1,2,4,3
/PNUM,ELEM,1
/PNUM,NODE,1
/SHR,.1
/SHOW,F33
EPLOT
FINISH
2A Text-Size: Default
2B Text-Size: Small
) End-Plot
No-Op
Preface
Conventions Used in This Guide
1 What is UIDL?
1.1 What Is the ANSYS UIDL?
5 Advanced Topics
5.1 Using ANSYS Parameters for Data Flow
6 Programming Example
Appendix A UIDL Command Dictionary
A.1 UIDL Commands and Controls
Symbols
R
S
D.2 Troubleshooting
Convention Indicates
File names, which may or may not include directory paths. These are
shown as lower-case, bold text, unless case is significant. Examples are
path/filename.ext shown with the UNIX directory separator character "/" (slash); if you are
using a Microsoft Windows system, use "\" (backslash) as your directory
separator character.
Command input listings, ANSYS output listings, and text that a user
command,arg1,arg2
enters are shown in fixed-width font.
Information that supplements the main topic being discussed, such as
Note-
important tips or guidelines.
Actions or situations that can shut down ANSYS, damage files, cause loss
Warning:
of data, etc.
This guide was designed for ANSYS users that have some programming skills and wish to tap
the power of the ANSYS Parametric Design Language (APDL) to increase the productivity.
APDL is a scripting language that is very similar to Fortran 77. The guide describes how to
define parameters (variables), how to create macro programs using APDL, how to use APDL
for simple user interaction, how to encrypt an APDL macro, and how to debug an APDL
macro.
The UIDL Programmer's Guide covers the User Interface Design Language (UIDL) including
how to modify or construct menus, dialogs and online help from within ANSYS.
ANSYS provides a set of Fortran 77 functions and routines that are available to extend or
modify the program's capabilities. Using these routines requires relinking the ANSYS
program, resulting in a custom version of ANSYS. Ansys release 5.4 and later provides an
external commands capability which you can use to create shared libraries available to ANSYS
(either from ANSI standard C or Fortran 77). You can use this feature to add custom
extensions to ANSYS without the need to rebuild the ANSYS executable.
The entire set of programmer's guides can be accessed online as HTML files or downloaded (in either
HTML or Postscript format) through the ANSYS documentation web site,
http://www.ansys.com/Documentation/Manuals/872. A list containing the complete set of available
ANSYS documentation is available at http://www.ansys.com/ServSupp/Library/library.html
Chapter 1: What is UIDL?
Go to the Next Chapter
Go to the Table of Contents for This Manual.
Customizing the GUI lets you modify many ANSYS menus and dialogs and integrate locally-
developed programs into the ANSYS environment.
The UIDL processor reads the control file, inserts ANSYS indexing information (which relates the
building blocks to the ANSYS GUI) into the control file, and builds the GUI.
To customize the ANSYS GUI with UIDL, perform the following steps:
3. Add the name of the new local control file to the menulist55.ans file.
4. Run ANSYS to see if the changes you made appear in the GUI.
5. Make any changes to the original in the subdirectory and copy it to the same directory as you did in
Step 2.
Note-Never modify these files! Modifying the standard ANSYS control files will make the ANSYS
GUI fail. Before you do any UIDL programming, copy these files to a subdirectory of your working
directory, then copy the blocks out of the files you want to modify.
Help files contain online help in multiple formats. See Chapter 4 for more information.
Note-Never modify these files! Modifying the standard ANSYS control files will make the ANSYS
GUI fail. Since the standard help control files are quite large and require special treatment, do not
copy them. See Chapter 4 for complete information on how to build online help.
A control file header is a set of specific UIDL commands that defines information about the control
file for the UIDL processor. A line in a control file cannot exceed 80 characters in length. All header
commands begin with a colon (:). A control file header contains the following four commands in this
order:
:F NEWMENU.GRN
:D Modified on %E%, defines new menus for ANSYS GUI
:I 0, 0, 0
:!
Required; control file description, must appear on line 2. If you maintain source under
a system such as SCCS, strings enclosed with percent signs (such as %E%) are
:D String
expanded according to conventions defined by the source control system. If you do not
use SCCS, insert a date instead of %E%.
Required; space holder for ANSYS indexing, must appear on line 3. The 0s (zeros)
:I 0, 0, 0
must be in columns 9, 18 and 27 and must be separated by commas.
Optional but encouraged; separates the control file header from the blocks, must
:!
appear on line 4.
For more information on the commands, see Appendix A, "UIDL Command Dictionary."
When UIDL processes an edited control file, the 0s and commas are replaced with indexing
information. If you modify an indexed control file, you must reinsert the :I command with the 0s and
commas in their proper places.
Note-Keep a clean copy of every control file in a subdirectory. Consider creating a one-line file that
consists of :I and the 0s and commas in their correct locations. Whenever you create a new control
file, you can insert the one-line file and ensure that the location of the 0s (zeros) is always correct.
Once you start ANSYS after having created new control files, ANSYS adds additional information to
the end of the control file. ANSYS inserts :X INDEX ADDED BY ANSYS at the end of each control
file. The name of each block appears, followed by an index number. If you ever modify an indexed
control file, you must delete everything after the final :E END command of the control file.
As you build new blocks, create at least one control file for menus, one for functions and one for
online help. Store a clean copy of each control file in a subdirectory. Always test each block
separately before adding it to one of your final control files-set up a TEST.GRN file as described in
Appendix D, "Testing and Troubleshooting." Store the final versions of your control files in your
working directory.
The menu blocks control the organization and content of the ANSYS Main Menu in the GUI. The
standard ANSYS menu blocks are all contained in the UIMENU.GRN file. Menu blocks are
discussed in detail in Chapter 2, "Modifying Menu Blocks."
The standard ANSYS dialogs are stored in the UIFUNC1.GRN and the UIFUNC2.GRN files.
Function blocks are discussed in detail in Chapter 3, "Modifying Function Blocks."
Help blocks control the organization and content of the GUI help screens. The contents of the help
screens are stored in the .HLP and .HPS files in the docu directory. Help blocks are discussed in
detail in Chapter 4, "Creating Help Blocks."
1.3 Overview of Building Blocks
Each building block consists of three sections:
● Header Section
● Data Controls Section
● Ending Section
Each type of building block has different data controls. Each control file typically contains multiple
building blocks.
Figure 1-1 shows a sample control file containing a menu block for an ANSYS GUI menu. This menu
block builds the ANSYS Main Menu. The arrows relate portions of the code to some of the options on
the menu.
Figure 1-1 A Control File Containing the ANSYS Main Menu Building Block
Note-Menu names are prefixed by the Men_ string. The only exception to this is the MenuRoot menu
depicted above.
The :T indicates the type of building block: Menu, Cmd, or Help. Optional UIDL commands, such
as :A (menu heading) and :D (block description), can also be in the header. The header section is
processed as soon as the building block is entered by the UIDL processor.
An error in a block can cause lines to be deleted in the control file or can cause erratic behavior when
the UIDL processor indexes it.
For easier readability, separate each block with the :! command and use uppercase characters for all
ANSYS commands.
1.5 The menulist55.ans File
In order for ANSYS to incorporate your changes into the GUI, you need to add the name of the any
new control file to the menulist55.ans file. This file contains the pointers to all ANSYS control files,
which in turn contain the GUI building blocks. ANSYS looks for menulist55.ans using the following
search path order:
If menulist55.ans is not found, an error condition occurs. ANSYS reads the contents of
menulist55.ans sequentially, checking to see if each control file has been indexed. If a control file
hasn't yet been indexed, the UIDL processor does the indexing and updates the control file
automatically. Indexing tells ANSYS where each of the building blocks fits into the structure of the
GUI.
Each time you create a new control file, you must update the menulist55.ans file. The
menulist55.ans file containing pointers to your customized control files should be in your working
directory or home directory. The menulist55.ans file allows a maximum of 20 pointers. If ANSYS
finds multiple blocks with the same name during the indexing process, the GUI uses the last block
found. Always insert pointers to your control files at the end of the menulist55.ans file.
Here is a sample menulist55.ans file, with one new control file added:
/ansys55/docu/UIMENU.GRN
/ansys55/docu/UIFUNC1.GRN
/ansys55/docu/UIFUNC2.GRN
/ansys55/docu/UICMDS.HLP
/ansys55/docu/UICMDS.HPS
/ansys55/docu/UIELEM.HLP
/ansys55/docu/UIELEM.HPS
/ansys55/docu/UIGUID.HLP
/ansys55/docu/UIGUID.HPS
/ansys55/docu/UITHRY.HLP
/ansys55/docu/UITHRY.HPS
/ansys55/docu/UIOTHR.HLP
/ansys55/docu/UIOTHR.HPS
NEWMAIN.GRN
The ANSYS GUI information defined by the NEWMAIN.GRN file takes precedence over the GUI
information defined in the standard ANSYS control files because it appears last in the menulist55.ans
file.
Figure 2-1 shows the menu block for the TimeHist Postproc menu. The arrows relate portions of the
code to some of the options on the menu.
The data controls section lists all commands which will appear on a menu. Note that on a menu, each
reference to a submenu ends in a greater-than sign, and each reference to a dialog ends in ellipses.
Required; defines the type of the block. To define a menu block the string
:T Menu
Menu must appear after the :T command.
Optional; filters this menu block based on keywords. See Appendix A for a
:K Keyword Logic
list of ANSYS keywords.
Optional; filters this menu block based on product codes. See Appendix B
:P Product Code Logic
for a list of product codes.
Adds the menu block named by String to the menu. The String used in this command
Men_String
must match a String defined by an :N command in another menu block.
Adds the function block named by String to the menu. The String used in this
Fnc_String
command must match a String defined by an :N command in a function block.
Sep_ Inserts a separator line on the menu between commands.
Inserts the text to be used as a menu title. Note-In the menu block header, the contents
String
of the :A string should be indented by three spaces.
Note-Always copy material from the UIMENU.GRN file to create your own menu control files.
Never modify this file.
If you want to create a completely new menu structure, you must include the menu block named
MenuRoot and retain its internal name (MenuRoot).
Hide a function in a menu if the user explicitly turned it off through the Preferences dialog. If no
preference was set, the user should see the item dimmed if its functionality is not available.
Dialog
A dialog accepts input from the user and processes it according to the ANSYS commands included in
the function block. Data controls build most dialogs with an absolute minimum of UIDL coding. Figure
3-1 shows a standard ANSYS dialog with its associated function block, which uses the /GSAVE
command to save plot controls to a selected directory.
Figure 3-1 Function Block for the Save Plot Controls Dialog
When building the data control section for a dialog, use at least one Typ_ data control and do not use
any Inp_P controls.
Picking box
A picking box lets the user select keypoints, lines, volumes, nodes (etc.) from a model. Here is a
standard ANSYS picking box, which uses the ANSYS A command to create areas through selected
keypoints, and requires that at least three keypoints be selected:
Figure 3-2 Function Block for a Create Area thru KPs Picking Box
When building the data control section of a picking box, include the Inp_P data control and at least one
Typ_ data control.
Hidden
A hidden function is performed without displaying a dialog or picking box. Figure 3-3 shows a sample
hidden function block:
:N Fnc_CirBD_3
:S 0, 0, 0
:T Cmd
:A Hidden (Change Element Color)
:C )! Fnc_CirBD_3
:C )/nopr
:C )*get,_z(30),graph,,number
:C )/pnum,mat,1
:C )/num,1
:C )eplot
:C )/num,_z(30)
:C )/go
:P (ELECMAG)
Inp_P
Cmd_)!
:E END
When building the data control section for a hidden function, include the Inp_P data control and at
least one Cmd_ data control with no Typ_ data controls which require input from the user. To make it
more readable include :A Hidden in the header section of the function block, and include some
information about what the function block does.
Required; defines the type of the block. To define a function block the string
:T Cmd
Cmd must appear after the :T command.
Optional but strongly suggested; defines the name of the function as it will
appear on a menu. If you omit this command, the internal name defined by
:A String
the :N command will appear on menus. Note-Items listed on a menu under a
subhead should be indented by three spaces.
Required; provides the heading for the dialog, which appears in the title bar
:D String
of the dialog window.
Optional; filters this function block based on product codes. See Appendix C
:P Product Code Logic
for a complete list of product codes.
Optional; defines the internal name of the help block which documents the
:H Hlp_String dialog. The procedure for naming and writing help blocks is documented in
Chapter 4.
Cal_ Calls another function block; must be used just before the :E END command
General Controls
Fld_ Defines the field number, typically related to the Cmd_ preceding it
Picking Controls
Cnt_ Sets maximum number of items, except an apply is not done
Listing Controls
Typ_Idx Creates side-by-side scrolling lists from the subsequent Idx_ controls
File Controls
Typ_File Creates a file selection box with filter, directory and file names
Numerical Controls
Character Controls
Logical Controls
Typ_Logi Creates a toggle button for off and on labels
Note-Always copy material from the UIFUNC1.GRN or UIFUNC2.GRN files to create your own
function control files. Never modify these files.
Figure 3-4 The Function Block for the Put Results Data in Database Dialog
Some of the UIDL commands behave differently in a dialog block than in a menu. The :D command,
for example, is used to insert text into the title bar of the dialog. There are some additional header
commands for function blocks, such as the :H command. The :H command is used to associate an
online help file with the dialog's Help button. The Cal_Fnc_ command is used rather than the Cmd_
command since *VPUT is called with different arguments depending on the type of data the user
selects.
● Any ANSYS command name must be all uppercase and enclosed in brackets.
● Use the same case for field names as in the ANSYS Commands Reference.
● Use the Typ_Sep control to vertically separate logical groups within a dialog (for example
commands, options, etc.).
● Use "white" space as a horizontal separator, not characters (i.e. *, -, #, etc.).
● When a prompt is longer than one line, use a "-" dash at the end of the first line and at the
beginning of the second line.
● Capitalize the title heading-style and be sure it describes the whole dialog.
● Avoid using a scroll bar in a dialog-limit the vertical height appropriately.
● Do not use picking inside a dialog. It does not exhibit clean behavior.
● Do not document the commands within the dialog. Keep field explanations brief. Use online
help to document commands. See Chapter 4 for more information.
● Add a line containing the text :C )!Fnc_String to the header section of the function block. To
write the name of the function block to the log file, type KEYW,QALOGKEY,1 into the
ANSYS Input Window for debugging purposes.
● An error in a function block can cause lines to be deleted in the control file when the UIDL
processor indexes it.
● For better readability, separate each function block with a :! line.
● You can use the K_ and P_ commands together, but you can use only one of each (with the
exception of K_LN).
● If a dialog's contents will change after an Apply operation (for example, *READ for a list),
place an Rmk_ control at the top of the function's data control section.
● A line in a control file cannot be more than 80 characters.
Figure 3-5 Function Block for Creating a Dialog with Single-Selection Lists
Fld_2
Prm_Apply this color to the areas:
Typ_Color
Fld_0
Typ_Sep
Fld_0
Typ_Lab
Prm_Use Typ_Lis for a single selection text list
Fld_3
Typ_Lis
Lis_Structural,1
Lis_Thermal,2
Lis_Magnetics,3
Lis_Electric,4
Lis_CFD,5
Prm_Chosen item appears in Selection
Fld_0
Typ_Sep
Fld_0
Typ_Lab
Prm_Use Typ_Lis_OptionB for a text option button list
Fld_4
Prm_DOF set to be used
Typ_Lis_OptionB
Lis_Structural,UX,UY,UZ
Lis_Electric,AX,AY,AZ
Fld_0
Typ_Sep
Fld_0
Typ_Lab
Prm_Use Typ_Lis_RadioB to create a radio-style button list
Fld_5
Prm_Save the graphic as
Typ_Lis_RadioB
Lis_PostScript,ps
Lis_Interleaf,il
Lis_HPGL,gl
:E End
Figure 3-6 Function Block for Creating a Dialog with Multiple-Selection Lists
Fld_0
Typ_Sep
Fld_0
Typ_Lab
Prm_Use Typ_Idx for a side-by-side parent-child list
Fld_0
Typ_Lab
Prm_[*GET] Get Scalar Data Fld_2
Prm_Type of data to be retrieved
Typ_Idx
Idx_Current settings,Current settings,1
Idx_Graphics data ,Graphics data ,2
Idx_Model data ,Nodes ,3
Idx_Model data ,Elements ,4
Idx_Model data ,Keypoints ,5
Idx_Model data ,Lines ,6
Idx_Model data ,Areas ,7
Idx_Model data ,Volumes ,8
Idx_Model data ,For selected set,9
Idx_Model data ,Coord systems ,10
Idx_Model data ,Element types ,11
Idx_Model data ,Real constants ,12
Idx_Model data ,Material props ,13
Figure 3-7 Function Block for Creating a Dialog with a File Selection Box
Figure 3-8 Function Block for Creating a Dialog with Data Entry Fields
Fld_0
Typ_Lab
Prm_Use Typ_Real to create real valued input fields
Fld_4
Typ_Real
Prm_Typ_Real
Fld_5
Typ_Real2
Prm_Typ_Real 2
Fld_6
Typ_Real3
Prm_Typ_Real3
Fld_0
Typ_Sep
Fld_0
Typ_Lab
Prm_Use Typ_Char to create a character input field
Fld_7
Typ_Char
Def_Default
Prm_Jobname to be used
Fld_0
Typ_Sep
Fld_0
Typ_Lab
Prm_Use Typ_Logi to create a logical toggle button
Fld_8
Typ_Logi,Yes,No
Prm_Do you want to exit
:E End
Figure 3-9 Function Block for Building a Picking Box for Creating Areas through Keypoints
! Cust_Cal_Fnc_FunctionName
! Cust_Cmd_CommandName
It is possible for there to be more than one ! Cust_ line for a custom dialog and since they are
comments they may be placed anywhere in the data control section of the block.
Figure 4-1 shows a simple help block for online help. The arrows relate portions of the code to some
of the options on the menu.
Figure 4-1 Help Block for Customized Online Help Using an ASCII File
Note that help blocks have an additional section-the help contents section. This section does not
contain any commands; it contains the text or screen image that will appear online as the help. While
technically part of the data controls section, it is useful to view the help contents as a separate section.
Note the numbers at the end of the header and data controls sections. The number in the data controls
section is the number of bytes in the help contents section. The number in the header section is the
number of BYTES in the help contents and data controls sections combined. Each time you modify
the contents of a help contents section, you must update the byte counts in all locations. Listing the
contents of a directory or using the wc -c command in Unix will give you the byte count for a
specified file.
Required; tells the UIDL that the data controls will be for a help block. BYTES
represents the number of bytes in the data controls and help contents sections
:T Help BYTES combined. This value must follow Help and must be updated each time the help
contents section is modified. For PostScript and ZBitmap files, enter this line as :T
Help, BYTES (a comma is required after Help).
To be able to readily create consistent names for help blocks, ANSYS has adopted the following
naming conventions:
For the help block names for the chapters in the Analysis Guides, Guide is the first three letters of the
document title. For instance, in the example shown above, "MOD10" specifies Chapter 10 of the
ANSYS Modeling and Meshing Guide. When you are creating help block names for function blocks
that you've written, be sure to give the help block a name similar to the function block to ease
software maintenance.
Required; points to the previous link for this help block by using the
Hlp_Previous_Block or internal name of the help block. If this help block does not link to
Hps_Previous_Block another one, leave a blank after the Hlp_ control. The Hps_ control is
for printable help on Unix systems only.
Required; points to the next link for this help block by using the
Hlp_Next_Block or internal name of the help block. If this help block does not link to
Hps_Next_Block another one, leave a blank after the Hlp_ control. The Hps_ control is
for printable help on Unix systems only.
Optional; definition for each hyperlink inside the help window. Valid
for ZBITMAP files only. You can have multiple hyperlink definition
lines. For more information, see Section 4.1.2.2.
Required; marks the end of the hyperlinks and the start of the help
contents section. Note that even though hyperlinks can only be used
END_OF_HYPERLINKS
with ZBITMAP files, this line must always appear in the data controls
section.
There are three kinds of help data types: ASCII, PostScript and ZBITMAP. You must calculate the
number of bytes in the help contents section and enter this information as follows:
● ASCII DATA_SIZE_IN_BYTES
Example: ASCII 279
● ZBITMAP COMPRESSED_DATA_SIZE_IN_BYTES DATA_SIZE_IN_BYTES
Example: ZBITMAP 2798 223797
● POSTSCRIPT COMPRESSED_DATA_SIZE_IN_BYTES DATA_SIZE_IN_BYTES
Example: POSTSCRIPT 2798 223797
Note-PostScript files are not displayed as online help; they are included to allow the printing of help
on Unix systems. The POSTSCRIPT data type is not used on Windows systems.
Hyperlinks can only be used with the ZBITMAP data type. Hyperlinks in online help appear as text
surrounded by the lines of a box. When the hyperlink is selected, another page of online help is
displayed. Figure 4-2 shows the online help for the *EXIT command with hyperlinks:
In this example, the string APDL: Process Controls, the Product groups, and the commands
*ENDDO, *IF and *DO are all hyperlinks. Selecting any of these strings will display the online help
associated with those strings.
Here are some sample hyperlink codes. In this example, the codes build the links for the online help
for the ANSYS *EXIT command:
Note-Never modify the standard ANSYS help files found in the docu directory. Always build your
own help control files using the process described in this section.
Additionally, online help files on Unix systems must be stored as as PostScript files for printing.
Before you can associate individual help files with parts of ANSYS, you first must create the help in
individual files and store them as text, compressed PostScript, or compressed XWD files. You must
also understand how to point to commands, elements and portions of various manuals to add your
own online help to the system.
To get the required byte counts, create each help contents block in its own file and use a directory
listing or the Unix wc -c command to get a byte count of each help contents section. Then, combine
the help contents section with the other sections to create a whole help block.
A control file which holds the help blocks must not be indexed when the control file is being edited. If
the control file is indexed, either remove the indexing or use a clean, unindexed copy. Therefore,
when creating a new control file or editing an existing one, always keep a clean backup copy that you
can revert to.
An error in a building block can cause lines to be deleted in the control file when the UIDL processor
indexes it.
As described earlier, it is useful to think of each help block consisting of four independent sections:
● header section
● data controls section
● help contents section
● ending section
When building a help block, each section should be in its own file. The following examples show
three different kinds of help blocks. Each block is included in its own help control file. The first
example consists of the code used to display a help screen when the Help>Table of Contents>Other
command is chosen. All the file names include the string other. For consistency, we recommend
naming the header section head_other, the data controls section hlp_other1 and the help contents
section hlp_other2.
In the second and third examples, all the filenames contain the string exitst since they provide online
help for the *EXIT command. Using a standard naming convention will help you maintain the help
sections.
Note-If you are using a text editor that does not include a linefeed as the last line, then you must press
the ENTER key to include a linefeed as the last line of each file. The vi editor includes end-of-file
linefeeds automatically.
1. Create a file containing the help contents section and save it as an ASCII file: The file may not have
more than 80 characters per line. In this example, the name of the file is hlp_other2.
2. Determine the byte count of hlp_other2. The byte count may be determined by displaying a
directory listing and checking the byte column or, in Unix, by using the wc command:
wc -c hlp_other2
164 hlp_other2
This byte count is the number displayed before the file name. Record this number. In Step 3,
you will insert this value after the string ASCII.
Customized Help
Hlp_
Hlp_
ASCII 164
END_OF_HYPERLINKS
In this example, there are not any related help blocks, so the two Hlp_lines following the help
window title are included but do not have any internal help block names attached.
4. Join hlp_other1 and hlp_other2 together into a new file (hlp_other). Unix users can use the
concatentation command:
5. Determine the byte count of hlp_other. The byte count may be determined by displaying a
directory listing and checking the byte column or, in Unix, by using the wc command:
wc -c hlp_other
218 hlp_other
This byte count is the number displayed before the file name. Record this number. In Step 6,
you will insert this value after the string :T HELP.
:N Hlp_O_Contents
:S 0, 0, 0
:T HELP 218
:E End
:F OTHER.HLP
:D Modified on 1/17
:I 0, 0, 0
:!
9. Join these four files into a control file (OTHER.HLP) and save this file to your current working
directory. Unix users can use the concatentation command:
10. Add the file name OTHER.HLP to the end of the menulist55.ans file and start ANSYS to view
the new online help.
1. Create a file containing the help contents section and save it as an XWD file. In this example, the
name of the file is hlp_exitst2. The graphic in the file must be 744 pixels wide by 925 pixels high.
2. Determine the byte count of hlp_exitst2. The byte count may be determined by displaying a
directory listing and checking the byte column or, in Unix, by using the wc command:
wc -c hlp_exitst2
89208 hlp_exitst2
This byte count is the number displayed before the file name. Record this number. In Step 5,
this is the second number inserted after the string ZBITMAP.
3. Compress the PostScript file using the Unix compress command to save the file in Adaptive
Lempel-Ziv Coding format.
compress hlp_exitst2
4. Determine the byte count of the compressed file, hlp_exitst2.Z The byte count may be determined
by displaying the directory listing and checking the size column or, in Unix, by using the wc -c
command. Record this number. In Step 5, this is the first number inserted after the string ZBITMAP.
In this example, the two Hlp_lines following the help window title have the block names for
the command description preceding the *EXITcommand and for the command description
following. The lines following the data type line (ZBITMAP...) may be omitted if there are no
hyperlinks on the page.
6. Join hlp_exitst1 and hlp_exitst2.Z together into a file (hlp_exitst). Unix users can use the
concatentation command:
7. Determine the byte count of hlp_exitst. The byte count may be determined by displaying a
directory listing and checking the byte column or, in Unix, by using the wc command:
wc -c hlp_exitst
6182 hlp_exitst
This byte count is the number displayed before the file name. Record this number. In Step 8,
you will insert this value after the string :T HELP.
:N Hlp_C_*EXIT
:S 0, 0, 0
:T HELP,6182
:E End
10. Create a text file (control_exitst) containing the control file header:
:F EXITST.HLP
:D Modified on 1/17
:I 0, 0, 0
:!
11. Join these four files into a control file (EXITST.HLP) and save this file to your current working
directory. Unix users can use the concatentation command:
12. Add the file name EXITST.HLP to the end of the menulist55.ans file and start ANSYS to view
the new online help.
1. Create a file containing the help contents section and save it as a PostScript file. To create this file,
start the application containing the help pages and print them to a file with a PostScript print driver. In
this example, the name of the file is ps_exitst2.
2. Determine the byte count of ps_exitst2. The byte count may be determined by displaying a
directory listing and checking the byte column or, in Unix, by using the wc command:
wc -c ps_exitst2
26504 ps_exitst2
This byte count is the number displayed before the file name. Record this number. In Step 5,
this is the second number inserted after the string POSTSCRIPT.
3. Compress the PostScript file using the Unix compress command to save the file in Adaptive
Lempel-Ziv Coding format.
compress ps_other2
4. Determine the byte count of the compressed file, ps_exitst2.Z The byte count may be determined
by displaying a directory listing and checking the size column or, in Unix, by using the wc command.
Record this number. In Step 5, this is the first number inserted after the string POSTSCRIPT.
In this example, the two Hps_lines following the help title have the block names for the
command description before *EXIT command and for the one after.
6. Join ps_exitst1 and ps_exitst2.Z together into a file (ps_exitst). Unix users can use the
concatentation command:
7. Determine the byte count of ps_exitst. The byte count may be determined by displaying a directory
listing and checking the byte column or, in Unix, by using the wc command:
wc -c ps_exitst
7327 ps_exitst
This byte count is the number displayed before the file name. Record this number. In Step 8,
you will insert this value after the string :T HELP.
:N Hps_C_*EXIT
:S 0, 0, 0
:T HELP,7327
:E End
10. Create a text file (controlps_exitst) containing the control file header:
:F EXITST.HPS
:D Modified on 1/17
:I 0, 0, 0
:!
11. Join these four files into a control file (EXITST.HPS) and save this file to your current working
directory. Unix users can use the concatentation command:
12. Add the file name EXITST.HPS to the end of the menulist55.ans file and start ANSYS to view
the new online help.
For information about some tools that can help automate the help-building process, see Appendix E,
"Additional Help Tools."
_z1 scalar
_z2 scalar
_z3 scalar
_z4 scalar
_z5 scalar
_z6 scalar
_z7 scalar
_z8 scalar
_z9 scalar
_z(i,j,k) array
_zc(i,j,k) character array
You can use these parameters over and over again. Therefore, you can't count on parameter values
being preserved outside the function blocks in which they're defined and used, because other function
blocks will be using the same parameter names.
When using array parameters, you must delete and then dimension the array parameter at the beginning
of the function block. For example:
:C *DEL,_z(1)
:C *DIM,_z,,5,2
The *DEL command silently deletes parameters that begin with underscore (_), whether or not they
exist or have been previously dimensioned.
You can also use the GUI command *CSET to pass a 32-character string. See ANSYS Commands
Reference for more information.
To see the current status of hidden parameters, use the command *STAT,_prm. It will list all of the "_"
parameters in use and their values.
Use the ) option in the building blocks to save users from seeing unfamiliar commands on their log
files. However, using this option can lead to CLASS3-type errors. To ensure consistent usage and to
avoid undesirable situations when creating building blocks, you must observe the following rules
concerning the use of the ) option. The ANSYS commands that these rules apply to are those used
with the :C and Cmd_ block commands and do not use any blank spaces in the command.
● Although ")" commands aren't written to the command log, their action is echoed to the primary
output when they execute. To avoid this output, enclose the suppressed commands with /NOPR
and /GO as follows:
Invalid
Invalid
:C *GET,_z1,....
:C N,1,_z1,3,1
:C )*DEL,_z1 Clean-up *GET value that did not use ")".
The following example demonstrates chained function blocks. This example executes the /CLEAR
command, which requires that the user be at the Begin level of the program. Chaining determines the
current level of the program and prompts to execute the /CLEAR command.
Chained function blocks should not contain an Apply button until the last dialog in the chain (and then
only if one is needed in the last dialog box).
Go to the beginning of this chapter
Chapter 6: Programming Example
Go to the Next Appendix
Go to the Previous Chapter
Go to the Table of Contents for This Manual.
The following function block, PlaceBeam, uses a picking box to store the picked keypoints, then calls
PlaceBeam2 to create a beam. PlaceBeam uses locational picking, and the FLST and FITEM
commands store the picked coordinates. PlaceBeam2 uses the *FPIK control to get the location for
each field.
Fld_5
Typ_Def_*FPIK(2,3)
Fld_6
Typ_Def_*FPIK(2,4)
Fld_7
Typ_Def_*FPIK(2,5)
Fld_8
Typ_Def_*FPIK(2,6)
:E End
Symbols
:! String
Header
String
Notes
Comment lines are recommended for separating building blocks. Insert a :!command at the
beginning of each new block header.
Avoid using a :!on a line by itself-insert a blank space after the :!to create a block separator
without a comment.
! String
Indicates a comment line.
Data Control
String
Notes
A
:A String
Defines the string to display on the menu calling this building block. (Required)
String
A 1- to 16-character string which names the menu. If this is a menu building block, a greater-
than symbol >will be appended to the string in column 18.
Notes
The name of this building block can match the name of other building blocks.
This string is not the same as the internal name defined by the :Ncommand. The string defined
by the :Ncommand is the internal name of the menu; it is only used for programming and is
not displayed to the user.
ALIAS
This control is used to call the next help block automatically. It must follow a pair of
Hlp_Help_Block controls in the help data controls section.
B
Bnd_LOWER,UPPER
LOWER,UPPER
A lower and upper limit for the multiple list. Both limit values must be double precision
numbers.
C
:C Command
Header
Command
Any valid 1- to-76-character command string. The string can consist of a standard ANSYS
command, a line of APDL code, a user-programmable feature or a call to an external libraries.
See the APDL Programmer's Guidefor more information on APDL.
Notes
You can specify multiple :Clines inside a building block, but they must be in the Header
section of the block and they should be listed together.
Cal_Fnc_Block,FIELD,Oper,VALUE,CMDNUM
Fnc_Block
The internal name of the function block to be called (as defined by a :Ncommand) if the if-test
is satisfied.
FIELD
Oper
The comparison operation to use for the evaluation. Valid operations are: EQ, NE, LT, GT,
LE, GE, and ES (string equality).
VALUE
CMDNUM
The order of the command in this data block whose field the test will use.
Notes
Omit the FIELD, Oper, VALUE, and CMDNUMarguments for an unconditional callback of a
function block. You may use parameter substitution by enclosing a parameter name with the
%symbol. Use %(I)name%to force conversion of a numeric parameter to integer form.
When a call is encountered, it executes and the processing returns immediately to the next line
after the call and continues processing. A dialog invoked by the first instance of Cal_will be
replaced by the dialog invoked by the second instance of Cal_. We do not recommend using
this sequence to call a hidden dialog followed by a call to another dialog.
This command must be the last line in a function block, immediately preceding the :E
ENDcommand.
Examples
The following command will call Fnc_Blockif field number 4 of the second command (the
second Cmd_ Block) in the current data control has a value greater than 1 when the current
function block executes:
Cal_Fnc_Block,4,GT,1,2
Cal_Fnc_TEST%name%
Cal_REFRESH
If input entered in a dialog effect the keywords used to activate a menu item, the menu is refreshed to
reflect the new settings.
Cmd_Command
Constructs and issues an ANSYS command as part of a function data control block.
Command
Any valid ANSYS command name. This includes APDL calls, macros, and calls to external
libraries.
Notes
You can include more than one Cmd_data control in a single data block, but not more than 50.
If this command shouldn't be included in menu paths, then on the preceding line, add this text:
! Exclude_from_paths
Example
The following command issues ANSYS command APLOT, which displays an area plot in the
Graphics Window:
Cmd_APLOT
Cnt_INTEGER
Defines the maximum number of items users can pick for this field, without automatically
invoking Apply.
INTEGER
An integer greater than or equal to 1 but not higher than 1000 (for locational picking) and not
more than 9999 (for entity picking). If you omit the integer, it defaults to 1.
You can replace INTEGERwith an "l"(the letter l) or an "s,"which doesn't limit entity picking.
The "l"is a flag indicating an ordered list of picked items. The "s"is a flag indicating an
unordered list of picked items.
Notes
This command is useful when a user is picking items to create or select and the picked items
should be verified before performing the next operation. See Max_to see how to set a
maximum value and invoke Apply automatically. See Mok_to see how to set a maximum
value with an automatic OK.
Examples
This command sets the order of selection as unimportant for "Select Entities:"
Cnt_s
Cnt_8
*CPAR(N)
(N)
The number of the appropriate vector position. This command usually is used in conjunction
with the Typ_Def_command.
Example
The following commands instruct the ANSYS program to use the data stored in the
*CSETvector position 101 as the default value:
Typ_Def_*CPAR(101)
CPAR
Fetches the double-precision equivalent of the data stored in the *CSET command from an
ANSYS *GET command.
Explanation
Example
The following command assigns the double-precision equivalent of the data stored in the
CSET vector position 101:
*GET,_z1,CPAR,101
*CSET,START_LOC,END_LOC,Fields
Stores a string in a vector.
START_LOC
END_LOC
An integer between 1 and 150. To maintain precision, use the START_LOC+ 3 for the ending
location.
Fields
The string to be stored at the location starting at START_LOCand ending with END_LOC. Fill
these fields using Fld_controls; each field can hold as many as 32 characters. If the string
contains spaces, you must enclose the complete string in single quotation marks, as follows:
`my string'
Example
This command fills the *CSETvector positions 1 through 1 with the following field
specifications
Cmd_*CSET,1,1
Fld_2:
Prm_Name of the ANSYS job
Typ_Char
Cmd_*CSET,1,1,`This is a test'
Notes
When settings defaults for filtering, use parameters to set the value first. For example, in an
IGES import, you cannot set *.*or *in the Def_statement. Instead, a *PAR of a parameters
such as _Z10 is used (_Z10="*.*").
! Cust_Cal_Function_Name
Notes
! Cust_Cmd_Command_Name
Notes
D
:D String
Defines the title of the dialog, and the description of a control file or a menu. (Required for
control file and function block headers.)
String
A string of 1 to 76 characters.
Notes
Only the first 60 characters of the string appear in the dialog's title bar. Only the first 22
characters of the string will show in a picking dialog. If you reset the default font size for the
dialog boxes, a different number of characters will appear.
In menu blocks, this command can be used to store descriptive information about the menu,
but the information is not displayed to the user.
Def_String
String
The String, limited to eight characters in length, may be any of the following:
● the string Blank, which will produce a blank input field. The field also defaults to a blank input
field if the value returned from *GET, *PAR, etc. is tiny (2**-100).
● a numeric value, which sets the default. If the user changes the value for this field, then it
overrides the setting for String. The user will see the changed value if no more than 40 other
dialog boxes have been shown before this same dialog is called again.
● a *GET value or a *PAR value which overrides previous user values. More properly, though,
the *GET value should match the user value so that when the command is executed, the
database is updated and reflects the new user value. Thus, a subsequent entry will get the user
value from the database.
● a *CPAR value which overrides previous user values.
● a *PICK value, which uses the information from the Typ_XYZ_WP function picking control.
● a *FENT or *FPIK value.
● a *Str value, which passes up to 72 characters into a field as one character.
● a string matching an item in a Lis_ data control. If the string contains spaces, enclose it in
single quotes.
You can specify up to three default values, separated by commas, as the defaults for double
and triple data types (for example, Typ_Real2, Typ_Real3).
Examples
Def_*GET(Entity,ENTNUM,
Gets a value the same way as the ANSYS *GET command
Item1,IT1NUM,Item2,IT2NUM)
Dlm_Character
Defines the command field delimiter the UIDL processor will use when building the command
to send to ANSYS.
Character
A character, which can be a blank space, to use afterthis field as the delimiter. The default
character is a comma.
The character "~"causes ANSYS to use no delimiter between fields. Fields are compressed to
the last non-blank character.
Example
The following data block invokes the vi editor for the given filename in the ANSYS Output
Window, and sets the delimiter character to a space:
Cmd_/SYS
Fld_2
Typ_Def_vi
Dlm_ Note-a single space follows Dlm_
Fld_3
Typ_CHAR
Prm_Enter Filename
E
:E END
Ending
Notes
Most blocks end with only the :E ENDcommand in the ending section. However, when you
are creating online help, you need to insert a blank line immediately before the :E
ENDcommand.
END_OF_HYPERLINKS
Ends the data controls section and begins a help contents section in a help block. (Required)
Notes
Even though only ZBITMAP files can contain hyperlinks, this command must appear in all
help block data control sections.
F
:F String
String
Example
The following example shows the first four required lines of a control file:
:F UIFUNC.GRN
:D Modified on %E%, defines standard ANSYS dialogs
:I 0, 0, 0
:!
*FENT(FIELD,ITEM)
Retrieves data stored by the FLST and FITEM commands for entity picks.
FIELD
The field number associated with the ANSYS command used for the picking. This can be a
value between 2 and 9.
ITEM
The item number for the entities picked by FIELD. The item number can be between 0 and
999. A zero value for the item number returns the number of entities picked.
Explanation
Fld_N
The field number of the ANSYS command field. The field definition always begins with Fld_,
and ends with the next Fld_or Cmd_control. The Cmd_control immediately preceding the
Fld_is related to the field.
Notes
The maximum number of Fld_data controls allowed in a function is 80.
Specify Fld_0for labels. These will appear in a dialog box as a separate text line, without a text
input box attached. Fld_1should not be used explicitly; UIDL associates Fld_1with the
command used for the dialog.
Example
The following example defines Fld_2as a labeled field that will accept a character string of up
to eight characters in length:
Fld_2
Prm_Name of parameter to be defined
Typ_Char,8
Fmt_H
Notes
Do not use this command with the Inp_P control. Any Prm_labels will be shown above their
corresponding button or data entry field.
Fnc_String
Points to the name of a function block from a menu, or defines the internal name of a function.
(Required in function headers.)
String
The internal name of the function block, indicating a function to be displayed or activated
when the user chooses this item from a menu.
Notes
The contents of Stringare defined by a :Ncommand in a function header.
*FPIK(FIELD,ITEM)
Retrieves data stored by the FLST and FITEM commands for locational picks.
FIELD
The field number associated with the ANSYS command used for the picking. This can be a
value between 2 and 9.
ITEM
The item number associated with the X, Y, or Z coordinate (in the global Cartesian coordinate
system) of the entity chosen with Field. The item numbers correspond to the coordinates of the
entities that were picked. The item number can be between 0 and 999 (i.e., there can be 333
coordinate locations). A zero value for the item number returns the number of points picked.
Always double check the return value.
Explanation
Example
G
*GET(String)
The same format as the ANSYS *GETcommand after the parameter field.
Entity
Entity keyword. Valid keywords are NODE, ELEM, KP, LINE, AREA, VOLU, etc; see
Entity= in the *GETtable in the ANSYS Commands Reference.
ENTNUM
The number of the entity (as shown for ENTNUM= in the *GETtable in the ANSYS Commands
Reference). A zero (or blank) ENTNUM represents all entities of the set.
Item1
The name of a particular item for the given entity. Valid items are as shown in the
Item1columns of the *GETtable in the ANSYS Commands Reference.
IT1NUM
The number (or label) for the specified Item1(if any). Valid IT1NUMvalues are as shown in the
IT1NUMcolumns of the *GETtable in the ANSYS Commands Reference. Some Item1labels do
not require an IT1NUMvalue.
Item2, IT2NUM
A second set of item labels and numbers to further qualify the item for which data are to be
retrieved. Most items do not require this level of information.
Notes
This command is useful for working with Def_data controls. See the ANSYS Commands
Referencefor detailed information on the *GETcommand. For *GEToperations on character
commons, CHR4 reads through the common in blocks of four and CHR8 reads through the
common in blocks of eight.
H
:H Hlp_String
Function Header
String
The internal name of the help block that should be displayed when a user clicks the Help
button of the dialog box.
Example
The following command displays the online help for the RECTNGcommand when a user
looks for information about that command:
:H Hlp_C_RECTNG
Notes
To be able to readily create consistent names for help blocks, ANSYS has adopted the
following naming conventions:
For the help block names for the chapters in the Analysis Guides, Guide is the first three letters of the
document title. For instance, in the example shown above, "MOD10" specifies Chapter 10 of the
ANSYS Modeling and Meshing Guide. When you are creating help block names for function blocks
that you've written, be sure to give the help block a name similar to the function block to ease
software maintenance.
Hlp_Help_Block
Help_Block
Explanation
This control is used to define a sequence of help blocks. The first Hlp_Help_Blockin the help
data controls section defines the previous help block in the sequence. The second
Hlp_Help_Blockin the help data controls section defines the next help block in the sequence.
Hps_Help_Block
Help_Block
Explanation
This control is used to define a sequence of help blocks when printing PostScript help. The
first Hps_Help_Blockin the help data controls section defines the previous help block in the
sequence. The second Hps_Help_Blockin the help data controls section defines the next help
block in the sequence.
I
:I 0, 0, 0
Explanation
The :Icommand must appear as the third line of the control file header, with comma-separated
zeros in columns 9, 18, and 27 respectively.
When the UIDL processor processes this file, the placeholders are overwritten with index
numbers. Always keep a clean copy of every control file with the index line set to 0s.
The first field is a placeholder for the total number of building blocks. The second field is the
placeholder for the starting location of the :X INDEXin bytes. The third field is a placeholder
for the total size of the control file in bytes.
Idx_
This can only be used with the Typ_Idxcommand. See the Typ_Idxcommand.
Inp_NoApply
Explanation
When Inp_NoApplyis used, it must be the first entry in the data controls section. Do not use
Inp_NoApplywith the Inp_Pcontrol.
Inp_NoApplymust be used with unique specification commands (not available for multiple
windows, sets, etc.), an action performed only once, and all visible dialogs of a chain except
the last visible one (if an Applyis appropriate)
Inp_P
Acts as a prompt mode flag for including a picking dialog or for a hidden block.
Notes
This command, if used, must be the first entry in the function data controls block. Don't use
this control if a dialog box is to appear for the function block.Do not use this control with the
Inp_NoApplycommand.
If you use Inp_Pwith a data type (Typ_Control) that includes picking, the picking dialog will
be displayed in addition to the prompt window. Do notuse this command to display a prompt
window without a picking dialog.
K
:K Keyword Logic
Defines logic that must produce a true result before a dialog is shown or menu selections are
activated.
Header
Keyword Logic
Keyword logic is an algebraic Boolean operation-"|"is orand "&"is and. You can enclose the
logic in parentheses nested up to three levels deep.
An uppercase keyword requires that the keyword be set for a true condition to be returned. A
lowercase keyword requires that the keyword notbe set for a true condition to be returned. If
the keyword produces a false condition, the block is notdisplayed. If you place a "#"symbol
before the first parenthesis, the menu item corresponding to the building block is grayed out
instead of not being displayed. The Keyword Logicstring can contain up to 76 characters.
Keywords may be selected by ANSYS or you can include them in your programming.
Notes
You can include more than one :Kline in the Header Section but not more than 10. When you
use multiple :Klines, the ANSYS program uses the andlogic between them. This enables you
to dim or hide a function based on keywords.
Filtering only works in the first level of the Utility Menu-filtering does not work in cascaded
menus.
Example
:K ((PREP7|SOLUTION)&begin)
Defines keyword logic that must produce a true result before the identified item will be shown.
Type
LN (applies keyword logic to the following line, no matter what control type it is. You can use an
unlimited number of K_LN lines.)
Keyword Logic
The keyword logic is an algebraic Boolean operation, where "|"is orand "&"is and. You can
enclose the logic in parentheses nested up to 3 levels deep.
An uppercase keyword requires that the keyword be set for a true condition to be returned. A
lowercase keyword requires that the keyword notbe set for a true condition to be returned. If
the keyword produces a false condition, the block is notdisplayed. If you place a "#"symbol
before the first parenthesis, the menu item corresponding to the block is dimmed (grayed out)
instead of not being displayed. The Keyword Logicstring can contain up to 76 characters.
Keywords may be selected by ANSYS or you can include them in your programming.
Notes
You can include more than one K_LN line where andlogic is used between lines. Appendix
Blists and describes the keywords ANSYS uses.
L
Lis_
Explanation
This command can only be used with the Typ_Liscommand. See the Typ_Liscommand for a
description of how to use Lis_.
M
Max_INTEGER
Sets the maximum number of items users can pick for this field, automatically invoking Apply.
INTEGER
An integer greater than or equal to 1, but not exceeding 1000 (for locational picking) or 9999
(for entity picking). If you omit the integer, it defaults to 1.
You can replace the integer value with an "l"(the letter l) or an "s,"which doesn't limit entity
picking. The "l"is a flag indicating an ordered list of picked items. The "s"is a flag indicating
an unordered list of picked items.
Notes
The ANSYS program does an "Apply"automatically when the user picks the maximum
number. See the Cnt_description for information on how to specify a maximum value without
doing an Apply. See the description of Mok_to find out how to specify a maximum value with
an automatic OK.
Examples
Max_s
The following command sets the maximum number of picked items at eight:
Max_8
Men_String
String
The internal name of the menu block, which indicates the menu to be displayed when the user
picks this item in a menu.
Notes
Min_INTEGER
Sets the minimum number of items that users must pick for this field.
An integer greater than or equal to 1. If you omit the integer, the default is 1; however, a good
practice is to specify a minimum integer value and not rely on the default.
Notes
This control sets the minimum number of items that must be picked before the ANSYS GUI
will accept an Apply or an OK.
Example
The following control sets the minimum number of picked items to four:
Min_4
Mok_INTEGER
Sets the maximum number of items users can pick for this field.
INTEGER
An integer greater than or equal to 1, but not exceeding 1000 (for locational picking) or 9999
(for entity picking). If you omit the integer, it defaults to 1.
You can replace the integer value with an "l"(the letter "l") or an "s,"which doesn't limit entity
picking. The "l"is a flag indicating an ordered list of picked items. The "s"is a flag indicating
an unordered list of picked items.
Notes
The ANSYS program does an OK operation automatically when the maximum is picked. See
the Cnt_description for information on how to specify a maximum value without an automatic
Apply. See the description of Max_to find out how to specify a maximum value with an
automatic Apply.
N
:N String
Header
String
Notes
If the same internal block name is defined more than once, ANSYS uses only the lastbuilding
block found with that name. Each internal name should be unique. See the :Hdescription for
more information on naming help blocks.
P
:P Product Code Logic
Defines the product codes that must be present before the building block will be shown.
Header
The ANSYS program sets product codes. (A product code identifies the ANSYS products for
which your site is licensed.) The product code logic is an algebraic Boolean operation where
"|"is orand "&"is and. You can enclose the product code logic in parentheses nested up to 3
levels deep.
An uppercase product code requires that the product code be set for a true condition to be
returned. A lowercase product code requires that the product code notbe set for a true condition
to be returned. If the product code produces a false condition, the building block will notbe
displayed. If you place a "#"symbol before the first parenthesis, the menu item corresponding
to the building block will be dimmed (grayed out) instead of not being displayed. The Product
Code Logicstring can contain up to 76 characters.
Notes
You can use only one :Pcommand in the header section of a function block.
Appendix Cof this manual lists and describes the ANSYS product codes.
Filtering only works in the first level of the Utility Menu-filtering does not work in cascaded
menus.
Example
The following command requires the THERMAL product code to be active before the building
block will be displayed (that is, ANSYS/Thermal must be running on the system):
:P (THERMAL)
Defines product code logic that must produce a true result before the identified item will be
shown.
Type
The type of product code logic to use. Specify one of the following:
LN (product code logic applies to the following command, no matter what control type it is)
An uppercase product code requires that the keyword be set for a true condition to be returned.
A lowercase product code requires that the keyword notbe set for a true condition to be
returned. If the keyword produces a false condition, the building block will notbe displayed. If
you place a "#"symbol before the first parenthesis, the menu item corresponding to the
building block will be dimmed (grayed out) instead of not being displayed. The Product Code
Logicstring can contain up to 76 characters.
A product code in uppercase letters required that the product code be set to "true."A lowercase
product code must be set to false. If a product code produces a false condition, the building
block isn'tdisplayed.
Notes
*PAR(_ZString)
_ZString
A parameter that was previously defined. This command is used in conjunction with the
Def_or Typ_Def_command.
Example
The following example uses the parameter _Z1 as the default node number.
Fld_4
Prm_Node number N
Typ_INT
Def_*PAR(_Z1)
Pcn_FLAG
Specifies whether a set of picked entities should or should not be ordered for retrieval picking.
FLAG
2, where the first item chosen is the first in the set and the other items are unordered. This is
available for loop picking and single picks.
Notes
For an ordered set, the following picking dialog buttons will be dimmed: Box, Polygon, Circle,
and Pick All.
Pdp_FLAG
Controls whether the user can pick duplicates of an entity for retrieval picking
FLAG
Pfm_FLAG
FLAG
0, to have the UIDL processor determine if a picked set or the command line should be used
(default).
2, to place the picked items directly on the command line (The ANSYS commands FITEMand
FLSTwill notbe used.)
*PICK(N)
Retrieves the data in the Nth text field of the model picker.
(N)
Example
In the following example, two working plane locations (the two diagonal corners of a
rectangle) are picked:
:N Fnc_BLC4_2d
:S 0, 0, 0
:T Cmd_P
:c )! Fnc_BLC4_2d
:A By 2 Corners
:D Rectangle by 2 corners
:K #(PREP7)
:H Hlp_C_BLC4
Inp_P
Cmd_BLC4
Fld_0
Typ_XYZ_WP
Prm_[BLC4] Pick 2 WP locations (2 diagonal corners)
Min_2
Max_2
Rub_
Fld_2
Typ_Def_*PICK(1)
Fld_3
Typ_Def_*PICK(2)
Fld_4
Typ_Def_*PICK(3)
Fld_5
Typ_Def_*PICK(4)
:E END
Prm_String
String
The string can contain up to 72 characters but will be truncated to 32 characters when in a
dialog box for any data type (Typ_) other than Typ_Lab.
Notes
You can substitute ANSYS parameters in the labels by enclosing them with %symbols.
Consider this command:
If the %num%parameter is set to 5 and the %color%parameter is set to green, the text string
will read:
Example
Pwr_FLAG
FLAG
Notes
This command enables the storage of picked items or coordinates for retrieval by the *FENTor
*FPIKcommands.
R
Rmk_
Notes
This control must be the first line of the Data Controls section.
Rub_N
1 Lines
5 Partial Annulus
13 3 Equal-sided Polygon
14 4 Equal-sided Polygon
15 5 Equal-sided Polygon
16 6 Equal-sided Polygon
17 7 Equal-sided Polygon
18 8 Equal-sided Polygon
For Three-dimensional Picking Between Keypoints
51 Straight Lines
101 Polyhedron
102 Block
103 Cylinder-solid
104 Cylinder-hollow
109 Cone
201 Inductor
202 Capacitor
203 Resistor
204 Circuit 1
205 Circuit 2
206 Circuit 3
207 Circuit 4
S
:S 0, 0, 0
Header
Explanation
The :Scommand must appear as the second line of every header section, with comma-separated
zeros in columns 9, 16, and 23 respectively.
When the UIDL processor processes a block, the placeholders are overwritten with index
numbers. Always keep a clean copy of every block with the index line set to 0s.
The first field is a placeholder for the size of the block in bytes. The second field is the
placeholder for the start index of the data controls section in bytes. The third field is a
placeholder for the total size of the data controls section in bytes.
Sel_FLAG
FLAG
Sep_
*Str(String)
GUI command
(String)
A string containing up to 72 characters. You can include ANSYS parameters in the string by
enclosing them with %symbols (%parameter%). Use %#parameter%to prevent
compression of spaces in a character parameter. If a parameter causes the string to exceed 72
characters, the string is truncated.
This command is used with the Typ_Def_and Def_commands,
Example
F1=`/usr/loc`
F2=`al/ansys`
F3=`file.in`
F4=`p`
Cmd_/INPUT
Fld_2
Typ_Def_*Str(%F1%%F2%%F3%%F4%)
T
:T Type
Specifies the type of data controls a building block will use. (Required)
Header
Type
Menu
Defines the block as a menu block. The data controls section contains the internal names of the
submenus and functions. The ANSYS program automatically appends a ">"symbol on the
menu to the names (specified on the :Aline) of menu blocks having submenus.
Cmd
Defines the block as a function block. An ellipses (...) appears on the menu after the name of
each dialog.
Cmd_N
Defines the block as a function block. No symbol will be shown (this indicates immediate
action). This is used for a hidden dialog.
Cmd_P
Defines the block as a function block for a picking dialog. The symbol + appears on the menu
after the name of each picking box.
Help
Defines the block as a help block. Help blocks can be in ASCII, bitmap (XWD) or PostScript
format (PostScript is used for printable help only).
Finish
Defines the block as a "finish block."Using this data type and the FINISHcommand collapses
the side menus automatically to the top level when a user chooses this command.
Notes
Changing the function block type changes only the symbol shown, not the functionality of the
function itself.
Typ_Entity
Uses picking mode to obtain entity numbers for commands requiring them.
Entity
Notes
Typ_Char,FIELD1,FIELD2
FIELD1
FIELD2
An integer between 1 and 80 for the input field view width (defaults to 32).
Typ_Color
Explanation
The default prompt for Typ_Coloris Color. The color chosen passes the actual color name to
the field. If you want to set a default color (Def_line), the correspondence shown below applies
for the default ANSYS color map. (If using a *GETcommand to fetch a color value, you must
add 1 to it to match this table.)
1 BLAC 5 BLUE 9 GREE 13 RED
If you do not specify any parameters, ANSYS produces a selection list in the dialog that looks
like this:
The user selects a color, and the button is shown in the color selected.
Typ_Def_String
String
The String, limited to eight characters in length, may be any of the following:
You can specify up to three default values, separated by commas, as the defaults for double
and triple data types (for example, Typ_Real2, Typ_Real3).
Examples
Typ_Def_*GET(Entity,ENTNUM,
Gets a value the same way as the ANSYS *GET command
Item1,IT1NUM,Item2,IT2NUM)
Typ_File
Creates the file selection box, which displays the filter, directory, and file name.
Explanation
Using this control produces a standard selection box on a dialog. The user can select a file,
browse directories to find a file, or filter the contents of a directory according a user-specified
extension.
Typ_File_Inline
Creates a text entry field for the directory, filename and extension.
Explanation
Creates a text entry field. When the user enters a string, it is converted automatically into the
ANSYS format of Filename,Extension,Directory. The filename is limited to 32 characters, the
extension to 9 characters, and the directory name to 39 characters.
Typ_Idx
Creates an indexed list for side-by-side display of categories and their associated items.
Idx_Category,Item,Value
Defines each line of the scrolling lists. You must identify each item using the Idx_designator,
followed by the category, item, and value. All categories are shown once in the left scrolling
list. Each time a user chooses a category, all the items associated with that category appear in
the right scrolling list. When a user chooses a specific item, the name of the item appears in a
field labeled Selection.
Example
The following example creates a pair of scrolling lists permitting a user to select coordinate
data about the model:
Fld_2
Prm_Coord sys data to be retrieved
Typ_IDX
IDX_Origin location ,X ,LOC,X
IDX_Origin location ,Y ,LOC,Y
IDX_Origin location ,Z ,LOC,Z
IDX_Rotation angle ,XY ,ANG,XY
IDX_Rotation angle ,YZ ,ANG,YZ
IDX_Rotation angle ,ZX ,ANG,ZX
IDX_Attributes ,Coord sys type ,ATTR,KCS
IDX_Attributes ,Ratio Y-rad/X-rd,ATTR,PAR1
IDX_Attributes ,Ratio Z-rad/X-rd,ATTR,PAR2
IDX_Attributes ,Maj rad of torus,ATTR,PAR1
IDX_Attributes ,Theta singularit,ATTR,KTHET
IDX_Attributes ,Phi singularity ,ATTR,KPHI
Here is the function block as it would appear in a dialog if a user had selected the Coord sys
typeitem from the Attributescategory:
Typ_Int
Notes
Using this command does not prevent non-integer data from being entered. Typ_Inttakes the
default and converts it to an integer before displaying it.
Typ_Int2
Creates two side-by-side text entry fields for displaying integer data.
Typ_Int3
Creates three side-by-side text entry fields for displaying integer data.
Defines a label data type which is used to display labels without an associated button or entry
field.
Explanation
Specify the labels using the Prm_control. Typ_Labusually is used with the Fld_0control. You
can use multiple Fld_0controls in a data block.
Example
Fld_0
Typ_lab
Prm_ Enter part name
Typ_Lis
Explanation
Use one Lis_ designator for each item on the list. Each item name can be 16 characters long,
and will be shown in a scrolling window. The associated value of an item will be used by the
command field.
Radio Buttons
Typ_Lis_RadioB
Lis_Item,Value
Use one Lis_ designator for each item. The item name is shown as a radio button. The
associated value of an item is used by the command field.
Option Buttons
Typ_Lis_OptionB
Lis_Item,Value
Use one Lis_ designator for each item. The list of items is shown as a single option button. The
associated value of an item is used by the command field.
Current database items will be displayed in a scrolling window, from which the user can select
one or more items. The selected item(s) will be used by the command field. Itemwill have one
of the following values:
Off_Label
On_Label
Typ_MLis
Explanation
Typ_Real
Typ_Real2
Creates two side-by-side text entry fields for real number display.
Creates three side-by-side text entry fields for real number display.
Typ_Resu
Explanation
To pass a parameter to the ItNdescriptor, use *CPAR(N). The IT vector is an A32 data type,
and IT0_Stringwill set the entire vector. The entity can be a node or an element, and the
Itemand Componentare any items and components that can be plotted.
Specify the entity to be shown as IT1_Entity, the item to be shown as IT2_Item, and the
component to be shown as IT3_Component.
Typ_Sep
Notes
This control should follow a Fld_0control. Do not use with prompt mode.
Typ_XYZ
Use this control only with the Inp_Pcontrol mode. You also can use Typ_XYZin conjunction
with the Pwr_1and Typ_Def_*FPIKUIDL function controls.
Typ_XYZ_SCREEN
Notes
You can use this control only with the Inp_Pcontrol mode. The picking dialog displays
automatically.
Typ_XYZ_WP
Invokes the model picker which obtains the working plane coordinates of a point in picking
mode and other geometry information based on Rub_.
Notes
To use this control, chain two function blocks. The data is stored in the PICK vector, and you
can extract it to a command in a chained function block by using Typ_Def_*PICK(N). You
must use Typ_XYZ_WPwith the Typ_Def_*PICKfunction control. You can pick up to six
points.
U
*UILIST,Fname,Ext,Dir
GUI Command
Fname
Ext
Dir
The directory where the file resides. Dirdefaults to the current working directory. Enclose the
directory name in single quotation marks (for example, 'mydir').
Notes
You must use this command with the Cmd_function command control.
X
:X INDEX
UIDL processor inserts this line at the end of every control file.
Do not use this line in blocks.ANSYS inserts this line automaticallyat the end of every control
file. ANSYS also writes the contents of each :Ncommand line, and shows the byte count of its
location in the control file.
ANSYS Entry
BEGIN 1
X11 1 If -d X11
X11C 1 If -d X11C
X3D 1 If -d X3D
ANSYS Exit
/EXIT,(blank) RESULTS 0
/EXIT,MODEL RESULTS 0
/EXIT,SOLU N/A
/EXIT,ALL N/A
/EXIT,NOSAV N/A
/SHOW
Routine Entry
Routine Exit
SAVE
RESUME
ET,ETDELE,DOF
STRUCTRL 1 If DOFGRP = n0000 (n>0)
PR_STRUC
PR_THERM
PR_ELMAG
PR_CFD
PR_MULTI
PR_SET
DEFAULT
ANTYPE 0 STATIC 1
ANCONT 0 NEWANLY 1
ANTYPE,
NTYPE,,
BUCOPT,
MODOPT,
TRNOPT,
SPOPT,
ON SRPASS 1
other "options" = 0
OFF SRPASS 0
Solution Complete
LSTEPGT1 1
SOLVE or PSOLVE
RESULTS 1
Results in Database
ESHAPE,
0 NOMIXMSH 0
Not 0 NOMIXMSH 1
FMAGBC,
otherwise FMAGBC 0
MOPT,
AMESH,RV51 MOPTRV51 1
AMESH,RV52 MOPTRV51 0
MeshTool MESHTOOL 1
SOLID5
ELEM3D 1
SCALARP 1 If KEYOPT(1)= 0, 1, 10
ANISO 1
PLANE13
ELEM2D 1
VECTORP 1 If KEYOPT(1) = 0, 4, 6
ANISO 1
PLANE53
ELEM2D 1
VECTORP 1
SOLID62
ELEM3D 1
VECTORP 1
SOLID64
ANISO 1
SOLID96
ELEM3D 1
SCALARP 1 If KEYOPT(2)= 0
VECTORP 1 If KEYOPT(2)= 1, 2
SOLID97
ELEM3D 1
VECTORP 1
SOLID98
ELEM3D 1
SCALARP 1 If KEYOPT(1)= 0, 1, 10
ANISO 1
INFIN110
ELEM3D 1
SCALARP 1 If KEYOPT(1)= 0
INFIN111
ELEM2D 1
SCALARP 1 If KEYOPT(1)= 0
VECTORP 1 If KEYOPT(1)= 1
INTER115
ELEM3D 1
SCALARP 1
VECTORP 1
FLUID131
CFD 1
FLUID132
CFD 1
FLUID141
CFD 1
FLUID142
CFD 1
Element Type
No preferences K_FL(pr_set+pmethod+cfd)
Structural K_FL(PR_STRUC+pr_multi+pmethod+cfd)
Thermal K_FL(PR_THERM+pr_multi+pmethod+cfd)
Electromagnetic K_FL(PR_ELMAG+pr_multi+pmethod+cfd)
Multiple K_FL(PR_MULTI+pmethod+cfd)
P-Method K_FL(PMETHOD+pr_cfd+cfd)
Loads / Solution
:K (PR_STRUC*pr_set)
Structural
:K #(STRUCTRL)
:K (PR_THERM*pr_set)
Thermal
:K #(THERMAL)
:K (PR_ELMAG*pr_set)
Electromagnetic
:K #(ELECTRIC*MAGNETIC)
:K (PR_FLUID*pr_set)
ANSYS Fluid
:K #(FLUID)
:K (PR_CFD*pr_set)
CFD FLOTRAN
:K #(CFD)
Results Data
Structural K_FL(STRUCTRL+multifld)
Thermal K_FL(THERMAL+multifld)
Electromagnetic K_FL((ELECTRIC*MAGNETIC)+structrl+thermal+fluid)
:K (PR_STRUC*pr_set)
Structural
:K #(STRUCTRL+RESULTS)
:K (PR_THERM*pr_set)
Thermal
:K #(THERMAL+RESULTS)
:K (PR_ELMAG*pr_set)
Electromagnetic
:K #((ELECTRIC*MAGNETIC)+RESULTS)
:K (PR_FLUID*pr_set)
ANSYS Fluid
:K #(FLUID+RESULTS)
:K (PR_CFD*pr_set)
CFD FLOTRAN
:K #(CFD+RESULTS)
ANSYS/LinearPlus LINPLUS
ANSYS/Thermal THERMAL
ANSYS/Emag 3D E3 ELECMAG
PP FULL_ANS LINPLUS
ANSYS/PrepPost THERMAL E3 ELECMAG
FLOTRAN MULTDISC
FULL_ANS LINPLUS THERMAL
ANSYS/University E3 ELECMAG FLOTRAN
MULTDISC
ED FULL_ANS LINPLUS
ANSYS/ED THERMAL E3 ELECMAG
FLOTRAN MULTDISC
PP FULL_ANS LINPLUS
ANSYS/DYNAPrepPost s
THERMAL E3 ELECMAG
(PrepPost stand-alone )
FLOTRAN MULTDISC LSDYNA
1. Create a TEST.GRN control file (see Chapter 1 for control file information).
4. Run ANSYS and check the functionality of the new building block(s).
If the building block doesn't seem to be working inside the GUI, that block may contain an error. Edit
TEST2.GRN and verify that the :S and :I commands contain 0s in the appropriate places (see
Chapter 1 for more information).
To aid in testing ")" lines, use the command KEYW,QALOGKEY,1 to force the writing of the ")"
lines to the ANSYS log file. Setting the QALOGKEY keyword allows you, for debugging purposes,
to see which commands were passed to ANSYS.
You can use the /DEBUG command to display some information. Issue the command /DEBUG,2 to
see what is being written to the output file. To see the substitution of parameters, issue the command
/DEBUG,4.
To eliminate keyword or product code filtering during debugging, set the NOFILTER flag.
Filtering only works in the first level of the Utility Menu-filtering does not work in cascaded menus.
Do not edit the control file once it's been indexed by ANSYS. Always edit the clean copy, as
described in Chapter 1.
If your menus do not appear as expected, you might have not set up the control file header properly.
Be sure both the header for the whole granule and the header for each individual block is set as
documented.
To compare block design and functionality, copy existing building blocks into your test file and run
tests on them.
D.2 Troubleshooting
D.2.1 Troubleshooting Dialogs
Dialog does not appear when selected.
The dialog may not be properly indexed. Check the function control file-If the :S command still has
0s, it means that block is ignored by ANSYS. Check to make sure the :E END command appears at
the end of the block.
The procedures for building help, which are directly related to UIDL coding, are documented in
Chapter 4. However, some additional help-building tools are available at the ANSYS FTP site. Since
these Perl tools are not part of a formal ANSYS product, and since online help can be built without
them, we are documenting them separately in this appendix, with the following warning:
NEITHER ANSYS, INC., NOR ITS DISTRIBUTORS, SHALL BE LIABLE FOR ANY
DAMAGES WHATSOEVER, INCLUDING, BUT NOT LIMITED TO, DIRECT INDIRECT,
SPECIAL, CONSEQUENTIAL OR INCIDENTAL DAMAGES, LOSS OF BUSINESS
PROFITS, LOSS OF REVENUE, OR LOSS OF USE, ARISING OUT OF OR RELATED TO
THE INFORMATION PROVIDED HEREIN, WHETHER SUCH DAMAGES ARISE IN
CONTRACT, TORT, NEGLIGENCE, IN EQUITY OR ARE STATUTORY, AT LAW OR
OTHERWISE. FURTHER ANSYS, INC. SHALL NOT BE RESPONSIBLE FOR ANY
ERRORS IN OMISSIONS PROVIDED HEREIN, AND RESERVES THE RIGHT TO
MAKE CHANGES WITHOUT NOTICE. THE INFORMATION PROVIDED HEREIN IS
PROVIDED "AS IS"WITHOUT WARRANTY OF ANY KIND, AND ANSYS, INC.
DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.
ftp ftp.ansys.com
3. Type bin and press Enter to set the file type to binary.
4. Type prompt to turn prompting off.
Most of the files you have downloaded are scripts which will run on either Unix or Windows
machines. An executable, compress.exe, is provided for Windows users-Unix users must delete
this file. A readme file is included. Print this file for further instructions.
Preface
Conventions Used in This Guide
1.3.5 Subroutine uel100 (Computing Element Matrices, Load Vectors, and Results)
1.3.6 Subroutines uel101 through uel105
1.4.5 Subroutine svpidx (Writing the Saved Variable Element Index to a File)
1.4.7 Subroutine subrd (Reading Element Load Data for a Substructure Generation
Run)
1.4.8 Subroutine subwrt (Writing an Element Load Vector to a File for a Substructure
Generation Run)
1.5.1 Subroutine userfd (Computing the Complex Load Vector for Frequency Domain
Logic)
1.6.6 Subroutine usrhyp (Computing Derivatives of Strain Energy Density with Respect
to Invariants)
1.6.7 Subroutine usrogp (Computing Derivatives of Strain Energy Density with Respect
to Stretch Ratios)
1.6.8 Subroutine usrogd (Computing Derivatives of Strain Energy Density with Respect
to Stretch Ratios)
1.7.4 Subroutine userfx (Changing Element Face Heat Flux Surface Information)
1.7.5 Subroutine userch (Changing Element Face Charge Density Surface Information)
2.4.6 elprev Function (Getting the Number of the Previous Selected Element)
2.5.4 ndgall Function (Getting the XYZ/Rotation Coordinates Vector for a Node)
2.5.5 ndspgt Subroutine (Getting the Nodal Solution for a Node of an Element)
2.9.32 esfiqr Function (Getting Information About Element Surface Stress Data)
2.10.25 eeliqr Function (Getting Information About an Element's Nodal Elastic Strains)
2.10.29 epliqr Function (Getting Information About an Element's Nodal Plastic Strains)
2.10.33 ecriqr Function (Getting Information About an Element's Nodal Creep Strains)
2.10.40 ethdel Subroutine (Deleting an Element's Thermal, Initial, and Swelling Strains)
3.3.3 vmax Function (Retrieving the Maximum Vector Value at a Given Location)
3.3.4 lastv Function (Retrieving the Position of the Last Non-zero Term in a Double
Precision Vector)
3.3.15 vamb Subroutine (Gets a Third Vector by Subtracting One Vector from Another)
3.4.6 maat Subroutine (Changing a Matrix Value via Addition, Multiplication, and
Transposition)
3.4.7 matsym Subroutine (Filling the Lower Triangle from the Upper Triangle)
Convention Indicates
File names, which may or may not include directory paths. These are
shown as lower-case, bold text, unless case is significant. Examples are
path/filename.ext shown with the UNIX directory separator character "/" (slash); if you are
using a Microsoft Windows system, use "\" (backslash) as your directory
separator character.
Command input listings, ANSYS output listings, and text that a user
command,arg1,arg2
enters are shown in fixed-width font.
Information that supplements the main topic being discussed, such as
Note-
important tips or guidelines.
Actions or situations that can shut down ANSYS, damage files, cause loss
Warning:
of data, etc.
This guide was designed for ANSYS users that have some programming skills and wish to tap
the power of the ANSYS Parametric Design Language (APDL) to increase their productivity.
APDL is a scripting language that is very similar to Fortran 77. The guide describes how to
define parameters (variables), how to create macro programs using APDL, how to use APDL
for simple user interaction, how to encrypt an APDL macro, and how to debug an APDL
macro.
The UIDL Programmer's Guide covers the User Interface Design Language (UIDL) including
how to modify or construct menus, dialogs and online help from within ANSYS.
ANSYS provides a set of Fortran 77 functions and routines that are available to extend or
modify the program's capabilities. Using these routines requires relinking the ANSYS
program, resulting in a custom version of ANSYS. ANSYS release 5.4 and later provides an
external commands capability which you can use to create shared libraries available to ANSYS
(either from ANSI standard C or Fortran 77). You can use this feature to add custom
extensions to ANSYS without the need to rebuild the ANSYS executable.
The entire set of programmer's guides can be accessed online as HTML files or downloaded (in either
HTML or Postscript format) through the ANSYS documentation web site,
http://www.ansys.com/Documentation/Manuals/872. A list containing the complete set of available
ANSYS documentation is available at http://www.ansys.com/ServSupp/Library/library.html
Chapter 1: Using User Programmable Features (UPFs)
Go to the Next Chapter
Go to the Table of Contents for This Manual.
● ANSYS/Multiphysics
● ANSYS/Mechanical
● ANSYS/Structural
● ANSYS/PrepPost
● ANSYS/ED (Research Faculty/Student version)
● To read information into or fetch information from the ANSYS database, you can create subroutines and either link them into the
ANSYS program or use them in the external command feature (see Appendix A for more information about external commands). If
you link these subroutines into ANSYS, you are lilmited to 10 database access commands. Such commands, created through either
method, operate at all levels of ANSYS operation, including the begin, preprocessor, general postprocessor, time-history
postprocessor, and solution levels. For more information about accessing the ANSYS database, see Chapter 2.
● ANSYS provides a set of routines you can use to specify various types of loads, including BF or BFE loads, pressures, convections,
heat fluxes, and charge densities. These routines are described under section 1.7.
● Another set of UPF routines enables you to define the following material properties: plasticity, creep, swelling law, viscoplasticity,
hyperelasticity, and layered element failure criteria. To see inputs and outputs for these routines, see section 1.6.
● Several sets of UPFs enable you to define new elements and to adjust the nodal orientation matrix. See section 1.3 for more
information.
● Another group of UPFs enables you to modify and monitor existing elements. For details, see section 1.5.
● You can customize UPF userop to create a custom design optimization routine. For more information, see section 1.12.
● You can call the ANSYS program as a subroutine in a program you've written. To learn how, see section 1.8.
The UPF subroutines are written in FORTRAN 77; some extensions are used. They contain comments intended to give you enough detail
to develop your own versions of the subroutines.
To use UPFs successfully, you need strong working knowledge of the following:
● The ANSYS program.
● The UPF subroutines themselves. Study the UPF subroutines before customizing them, and make sure that you fully understand the
subroutines, as well as any applicable functions. Unless you review them carefully, a few UPF subroutines may seem like a maze
with many logic paths to consider. You may have to set special variables correctly in order to run your customized ANSYS
program without errors. Even if you have in-depth knowledge of the ANSYS input and your desired outputs, you still need to
ensure that everything that needs to be done in the UPF subroutines is done properly in your custom version.
● FORTRAN 77. Besides knowing how to write FORTRAN 77 subroutines, you must be sure that the level of the FORTRAN 77
compiler is as least as high as the level mentioned in your ANSYS installation manual. You also need to know what to do should
the computer abort the program due to an arithmetic error, a file read error, a memory access error, and so on.
● The mathematics of the phenomenon you're planning to include.
Important
● UPFs aren't available in certain data center environments or on some hardware configurations, such as machines using parallel
processing for element formulation. For additional information, consult your ANSYS installation manual or your on-site ANSYS
system support person
● Carefully consider whether you wish to use UPFs, especially if you are linking them into ANSYS (rather than into a shared library
for use as external commands). When you add your own routines to ANSYS by either method, you're creating a customized, site-
dependent version of the program. ANSYS, Inc. considers the use of UPFs a non-standard use of the program, one that the ANSYS
Quality Assurance verification testing program doesn't cover. Therefore, you're responsible for verifying that the results produced
are accurate and that your customizations don't adversely affect other, standard areas of the ANSYS program.
● Although the flexibility that UPFs offer can be highly attractive, UPF usage is a complicated process that can introduce errors.
Consider what you want your customizations to accomplish. You may be able to customize ANSYS more easily and safely with
macros than with UPFs.
For other guidelines for non-standard uses of the ANSYS program, see Chapter 6 of the ANSYS Advanced Analysis Techniques Guide.
● Does the capability you want already exist in the ANSYS program? Remember, a capability may not be obvious at first, especially
to a novice ANSYS user.
● Does your proposed subroutine fit into the ANSYS program architecture and specifications? For example, you can't program a user
element that has more than 32 degrees of freedom per node or more than 20 nodes per element.
Use your experience and judgment to answer these questions. If you need help to do so, consult your ANSYS Support Distributor. If you
can respond "no" to both questions, then the user routine you're planning will be both useful and feasible.
● If you have a UNIX version of ANSYS, the source code for the UPF routines resides in directory /ansys55/customize/user.
● If you're running the ANSYS program under Windows NT or Windows 95, the UPF source code resides in directory
\ansys55\custom\user\intel.
Most of the user routines have at least simple functionality, so print out the routines of interest before you start programming. All source
routines are concatenated onto file user.f or user.for. Delete the routines you don't want and make appropriate changes to the others.
You need to take care when calling FORTRAN subroutines from C subroutines. You must use the symbol associated with the FORTRAN
subroutine when invoking the subroutine from a C function. This symbol typically differs slightly from the FORTRAN subroutine name,
and is extremely system dependent.
On many UNIX systems, you build this symbol name by taking the FORTRAN subroutine name, converting it to lower case, and
appending an underscore. For example, the symbol name for the FORTRAN subroutine HeapInquire would be heapinquire_. You
would have to use the symbol heapinquire_ in the invoking C function to avoid an unsatisfied external reference when the program is
linked.
Keep in mind that the instance described above is just an example. Compilers from different vendors may construct the symbols
differently. Please consult the manuals for your specific compiler for information on how to call FORTRAN subroutines from C functions.
The example procedure below illustrates this type of gradual process. The example assumes that you're creating a new element for the
ANSYS program. You develop and test it by performing these steps:
1. Get the applicable element subroutines for uel101 from the ANSYS distribution medium. Add a small change (such as a misspelling in
an output heading), then compile and link the subroutines.
2. Using a production version of the ANSYS program, run several analysis problems using LINK8 (and maybe other elements) to form a
base for comparison.
3. Replacing LINK8 with USER101, run the same problem on your custom version of ANSYS.
4. Compare the results from Steps 2 and 3. If they show discrepancies other than the misspelled output heading, resolve them before you
go on to Step 5.
5. Choose the standard ANSYS element that most closely resembles your new custom element, and run some problems on a production
version of ANSYS using that element.
6. Modify the element subroutines to match the element in chose in Step 5. Then, compile and link those subroutines into a custom version
of ANSYS.
7. Again, compare the results from Steps 5 and 6. If they don't match, resolve the discrepancies before moving on to Step 8.
8. Modify your element subroutines to include the features you want. Then, compile and link the subroutines into a custom version of
ANSYS.
9. Test the changes with a series of increasingly complex problems for which you already know the answers.
To insert include decks in a subroutine or function, use the INCLUDE (or an analogous) statement. Do not modify an include deck under
any circumstances. The following table lists some of the more commonly used ANSYS include files and the definitions they contain:
stack.inc Defines stack storage. You must include this common in any routines that access stack space.
● Link your routines into shared libraries (as discussed starting in Appendix A).
● Compile and link your custom routines into the ANSYS program itself. This is discussed for UNIX systems in 1.1.9 and for
Windows systems in 1.1.10. You may need super-user or root privileges to run the procedure that does the linking.
When you run a user-linked version of the ANSYS program, the output will include the following:
The ANSCUSTOM procedure compiles all FORTRAN files (files ending with .F) and all C files (files ending with .c) in the current
working directory. The procedure then loads all object files (files ending with .o) along with the default ANSYS objects and libraries in
/ansys55/customize/user/platform (where platform is a directory that uniquely identifies the hardware platform version). The new
executable file created will be named ansys.e55t and will reside in the current directory.
FORTRAN files are assumed to be FORTRAN 77 (some extensions are allowed), and C files are assumed to be ANSI C.
Chapter 1 of the ANSYS Installation and Configuration Guide for UNIX lists the compilers you'll need to use UPFs.
2. Copy the following files from \ansys55\custom\user\platform to your working directory: anscust.bat, makefile, and any user routines
you plan to modify. If you're running Windows 95, also copy file fcomp.bat.
3. Run the procedure ANSCUST. This procedure compiles all FORTRAN files (files ending with .F) and all C files (files ending with .c)
in the current working directory. The procedure then loads all object files (files ending with .obj), along with the default ANSYS objects
and libraries (in \ansys55\custom\user\platform). The executable file created will be named ansys.exe and will reside in the current
working directory. The executable will be named ansys.exe and will reside in the current working directory.
Windows 95 Users Only:Set the environment variable ANSYS55_DIRto the root ANSYS directory, as shown below:
SET ANSYS55_DIR=C:\ANSYS55
If you installed the program in a directory other than c:\ansys55, you'll also need to modify the ANSYS55_DIRvariable in the
makefile.
Important-Be sure to answer "no" when the linking procedure asks, "Do you want to overwrite it (current executable)?" If your answer isn't
"no," all other ANSYS program users will also get your changes.
UPFs that are not activated by the means described above must be activated by either of the following methods:
To activate or deactivate the routines, issue the command USRCAL,Rnam1,...Rnam9, where Rnam1 and Rnam9 are the names of specific
routines. You can specify up to nine routines with one USRCAL command, or you can issue multiple USRCAL commands.
Issue the command USRCAL,NONE to deactivate all valid user subroutines. To list the status of the routines, issue the command
USRCAL,STAT.
For a list of the user routines that the USRCAL command (or its equivalent menu paths) affects, see the USRCAL command description
in the ANSYS Commands Reference.
If you don't activate the UPFs in this manner, standard ANSYS logic will be used by default. For instance, when you apply a convection
load, standard ANSYS logic is the default even if you have a user convection routine linked in. The user convection routine must be
activated by the USRCAL command or its menu equivalent.
Make certain that your custom version of the ANSYS program performs correctly for the combinations of elements, analysis types,
materials, boundary conditions, etc. that you plan to use. Confirm that the logic you introduced is correct and doesn't produce any
unwanted side effects.
In testing your custom user routines, you also should verify that the changes you've made don't affect standard, non-customized ANSYS
features. To do so, you can compare the results of a set of problems from the ANSYS Verification Manual run on the standard version and
on the customized version. Input for these problems is also available on your ANSYS distribution medium.
Always remember: your last step, a series of steps, or even your concept may be wrong. Proceed in clear steps, and verify your work as
often as possible. Keep intermediate versions of your modified source code on backup media.
Note-If you contact your site's ANSYS system support person or any ANSYS, Inc. representative about the performance of a custom
version of ANSYS, always tell him or her explicitly that you're using a user programmable feature. If you feel that an error exists in an
unrelated feature of the ANSYS program, demonstrate the suspected error in an non-customized, production version of the program before
you report the error to an ANSYS. Inc. representative.
The /TRACK command issues a message when the program logic enters and leaves some of the higher level subroutines. Subroutines
TrackBegin and TrackEnd (see Chapter 6) set up the /TRACK command. Then, issue the command using the format below
/TRACK,MonLevel,PrintLevel,SumLevel
MonLevel is the level for timing monitoring. PrintLevel is the level for enter/exit printout, and SumLevel is the level at which the timing
sum is output. Each of these arguments can be any value between 0 and 9 (default is 0).
You can use the /TRACK command to identify which section of code is causing the program to abort. For example, to flag up to eight
levels of subroutines to determine when the program logic enters and leaves them, you would issue the command /TRACK,,8.
The /DEBUG command generates debugging at various points in the output. You can specify one of three formats for /DEBUG: solution
debug format, element debug format, and general debug format.
/DEBUG,-1,F1,F2,F3,F4,F5,F6,F7,F8,F9
3 (provides element matrix debugging with matrix diagonals and load vectors)
2 (provides Newton-Raphson debugging and prints out-of-balance forces or incremental displacement or each
F7
DOF)
3 (provides Newton-Raphson debugging and prints applied loads and n-r restoring force for each DOF)
/DEBUG,-3,G1,G2,G3,G4,G5,G6,G7,G8,G9
3 (provides element matrix debugging with matrix diagonals and load vectors)
/DEBUG,H1,H2,,H4,H5
H5 1 (provides pre-element debugging, element characteristics debugging, and element field load debugging)
Issue the /UCMD command to make a user routine into a custom command. For more information, see section 1.9 later in this chapter.
You can shorten the time ANSYS takes to read such files by including two commands in your programs, UPFs, or macros: EBLOCK and
NBLOCK. The NBLOCK command converts nodal data into fixed format data blocks (which ANSYS can read more quickly than
commands). The EBLOCK command places element data into a fixed format block, one line per element. These commands also compress
displacement constraint data to one line per constraint node.
EBLOCK,Nnodes
You must follow the EBLOCK command with a valid format statement defining five element attributes, followed by Nnodes. Nnodes are
the node numbers associated with this element. Use commas to separate the node numbers, (don't use blanks) and enclose the string of
node numbers in parentheses.
The EBLOCK command can indicate multiple element lines in the file.
The value EBLOCK returns will either be 0 (if the command executes successfully), or a negative element number if an error occurs.
NBLOCK,Ncoord
Ncoord is the number of coordinates defined for this node. The default for Ncoord is 3 and the maximum value is 6. The default coordinate
values are the X, Y, and Z coordinates, and the other values are THXY, THYZ, and THZX.
Normally, you specify one NBLOCK command for each line of nodal data. The value NBLOCK returns will be either 0 (if the command
executes successfully) or a negative node number if an error occurs.
int - integer
dp - double precision
log - logical
chr - character
sc - scalar variable
in - input argument
Routines uel100 through uel105 calculate the element matrices (stiffness, specific heat, etc.), the element load vector (force, heat flow,
etc.), and any element output quantities. The element printout also is generated, and the variables to be saved are calculated and stored in
the results file.
Other user routines available for manipulating element information include the following:
● Routines uep100 through uep105 provide printed output of line elements. The general ANSYS postprocessor, POST1, calls the
subroutines, or you can call them using uel100 through uel105.
● Routine usertr allows access to the nodal transformations.
● Routine userac describes some of the data handling.
external erhandler
#include "echprm.inc"
c
external nminfo,erinqr
integer erinqr
integer ielc(*),i,kerr
character*28 elcdn
c
C
c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97
c *** ansys, inc.
c *** Notice - This file contains ANSYS Confidential information ***
c
c typ=int,dp,log,chr siz=sc,ar(n) intent=in,out,inout
c
c input arguments:
c variable (typ,siz,intent) description
c ielc (int,ar(IELCSZ),inout) - element characteristics
c see include deck elccmt for details
c kerr (int,sc,inout) - error flag up to this point.
c (do not initialize to zero)
c
c output arguments:
c variable (typ,siz,intent) description
c elcdn (chr,sc,out) - name of element
c ielc (int,ar(IELCSZ),inout) - element characteristics
c see include deck elccmt for details
c kerr (int,sc,inout) - error flag (set to 1 if error)
c note to programmers: the validity of keyopt values may be checked here
c
The source code for subroutines uex101, uex102, uex103, uex104, and uex105 is identical to the code for subroutine uex100 listed above.
c input arguments:
c svindx (int,ar(10),in) - index for svr for this element (see svgidx)
c nset (int,sc,in) - the set number in this index
c = 1 - structural svrs
c = 2 - thermal/electric/fluid svrs
c = 3 - magnetic svrs
c = 4 - nonlinear svrs
c = 5 - plasticity svrs
c = 6 - creep svrs
c = 7 - coupled svrs
c = 8 - user svrs
c nsvr (int,sc,inout) - number of dp words expected in this set
c output arguments:
c nsvr (int,sc,inout) - number of dp words in this set
c svr (dp,ar(nsvr),in) - data in this set
c integer lp(3)
c data lp /1,10,13/
c call propev (elem,mat,lp(1),tem,prop(1),3)
c
c *** Notice - This file contains ANSYS Confidential information ***
c input arguments:
c iel (int,sc,in) - element number
c mtr (int,sc,in) - material number(input quantity mat, mat comma
c lp (int,ar(n),in) - keys for which specific value is requested
c each group must be in ascending
c order (ex,ey,ez, etc)
c if negative, a required property
c if zero, leave prop term unchanged
c EX = 1, EY = 2, EZ = 3, NUXY= 4, NUYZ= 5, NUXZ= 6, GXY = 7, GYZ = 8
c GXZ = 9, ALPX=10, ALPY=11, ALPZ=12, DENS=13, MU =14, DAMP=15, KXX =16
c KYY =17, KZZ =18, RSVX=19, RSVY=20, RSVZ=21, C =22, HF =23, VISC=24
c EMIS=25, ENTH=26, LSST=27, PRXY=28, PRYZ=29, PRXZ=30, MURX=31, MURY=32
c MURZ=33, PERX=34, PERY=35, PERZ=36, MGXX=37, MGYY=38, MGZZ=39, EGXX=40
c EGYY=41, EGZZ=42, TGXX=43, TGYY=44, TGZZ=45, SONC=46,
c (see chapter 2 of the elements volume of the user's manual
c for a detailed description))
c
c tem (dp,sc,in) - temperature at which to evaluate material
c n (int,sc,in) - number of properties to be evaluated.
c (20 maximum)
c If n = 1, use prope1 instead.
c
c output arguments:
c prop (dp,ar(n),out) - values of material property
c
1.4.13 Function gtplop (Retrieving the Start Point for Plastic Data)
function gtplop (mat,plopt)
c *** primary function: get the plasticity option
c *** secondary function: return the virtual starting address for the data
c (see nlpropcheck for similar logic)
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c input arguments:
c mat (int,sc,in) - material reference number
c
c output arguments:
c plopt (int,sc,out) - plasticity option:
c 1 bkin
c 2 mkin
c 3 miso
c 4 biso
c 5 aniso
c 6 dp
c 7 anand
c 12 melas
c 100 user
c gtplop (int,sc,out) - virtual starting position of the data
c
1.4.14 Function gtcrop (Retrieving the Start Position for Creep Data)
function gtcrop (mat,cropt)
c *** primary function: get the creep options
c *** secondary function: return the virtual starting address for the data
c (see nlpropcheck for similar logic)
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c input arguments:
c mat (int,sc,in) - material reference number
c
c output arguments:
c cropt (int,sc,out) - creep option:
c 10000*(irrad+1) + 1000*(secondary+1) +
c (primary+1)
c where:
c primary - primary creep (constant C6)
c secondary - secondary creep (constant C12)
c irrad - irradation induced (constant C66)
c see creep table documentation
c (TB command)
c gtcrop (int,sc,out) - virtual starting position of the data
c
c input arguments:
c ielem (int,sc,in) - element number
c edtype (int,sc,in) - element data type (see elparm)
c lcerst (int,sc,inout) - pointer to results file position
c edindx (int,ar(25),inout)- index to results file data
c nval (int,sc,in) - the total number of values
c if edtype = EDEMS,
c this should -always- be ielc(nmsmis),
c unless there is a variable number, as
c in the layered shell elements.
c value (dp,ar(nval),in) - output values (real)
c input arguments:
c elem (int,sc,in) - element number
c ielc (int,ar(IELCSZ),in) - element characteristic vector
c defined in elccmt
c lcerst (int,sc,inout) - pointer to results file position
c edindx (int,ar(25),inout)- index to results file data
c nudb (in,sc,in) - size of what the user wants to add
c udbdat (dp,ar(*),in) - what the user wants to add
c nval (int,sc,in) - the total number of values to
c be output(does not include nudb)
c this should -always- be ielc(NMNMIS),
c unless there is a variable number, as
c in the layered shell elements.
c value (dp,ar(ndval),in) - output values
c ndval (int,sc,in) - dimension of value - must be no less than
c ielc(NMNMIS) + ielc(NMNMUP)
c input arguments:
c variable (typ,siz,intent) description
c prs (dp,ar(5),in) - pressure vector
c rvrp (dp,ar(11),in) - real constants(see elements manual)
c angle (dp,sc,in) - subtended angle
c ex (dp,sc,in) - Young's modulus
c nuxy (dp,sc,in) - Poisson's ratio
c output arguments:
c variable (typ,siz,intent) description
c userpe (dp,sc,out) - rotation caused by internal pressure on the
c elbow element
c primary function: User routine to access element matrices and load vectors.
c Needs to have USRCAL,UELMATX to be accessed.
c Called after the call to the element routine and
c before the solver.
c May be used to monitor and/or modify the element matrices
c and load vectors.
c input arguments:
c variable (typ,siz,intent) description
c elem (int,sc,in) - User element number
c nr (int,sc,in) - number of rows in element matrix
c ls (int,ar(nr),in) - Dof Index vector for this element matrix
c zs (dp,ar(nr,nr,4),inout)- K,M,C,SS matrices for this element
c zsc (dp,ar(nr,2),inout) - Element load vector and N-R correction vec
c uelm (dp,ar(nr,5),in) - Nodal displacements for this element
c ielc (int,ar(150),in) - Element type characteristics
c nodes (int,ar(*),in) - Nodes for this element
c edof (int,ar(*),in) - Dofs per node for this element
c elmdat (int,ar(10),in) - Element data for this element
c xyzang (dp,ar(6,*),in) - X,Y,Z,THXY,THYZ,THZX for each element node
c lenu (int,sc,in) - Length of global displacement vector
c output arguments:
c zs (dp,ar(nr,nr,4),inout)- K,M,C,SS matrices for this element
c zsc (dp,ar(nr,2),inout) - Element load vector and N-R correction vec
c WARNING: any CHANGES to these (or any other) arguments will have a direc
c impact on the solution, possibly giving meaningless results. The normal
c usage of this routine is simply monitor what is happening.
Note-If you write a material behavior routine using any of the ANSYS commands MPDATA, MPDELE, TB, or TBDELE, be aware that
these commands interpret the string "_MATL" to mean the current active material when it appears in their MAT field. The "_MATL" is
used in conjunction with the library (LIB) option of the MPREAD and MPWRITE commands. MPWRITE inserts "_MATL" in lieu of
the specified material number as these commands are written to the material library file. This occurs only when you use the LIB option.
When ANSYS reads a material library file written in this format, it interprets "_MATL" to mean the currently active material (as defined
by the MAT,MAT command). Don't use the "_MATL" string outside the scope of the MPREAD command.
external erhandler
c
external vmax,pplock,ppunlock
integer elem,matlay,iott,keyer, loc
double precision
x eps(6),sig(6),fc6,tem,elim(9),slim(12), vmax,vect(9)
c
c ___________________________________________________________________
c /1 2 2 2 1 2 2 2
c \ / -*((ep - ep ) + (ep - ep ) + (ep - ep ) + -*(ep + ep + ep ))
c \/ 2 1 2 2 3 3 1 2 4 5 6
c ------------------------------------------------------------------------
c (1 + posn)
c input arguments:
c variable (typ,siz,intent) description
c kcomp (int,sc,in) - number of components of strain
c ep (dp,ar(6),in) - the strain components
c posn (dp,sc,in) - poisson's ratio
c output arguments:
c egen (dp,func,out) - the combined strain value
c
● Setting custom values for scalar fields (temperatures, heat fluxes, etc.)
● Changing element pressure information
● Changing information about element face convection surfaces
● Changing information about element face heat flux surfaces
● Changing information about element face convection surfaces
● Changing information about element face convection surfaces
● Changing information about element face charge density surfaces.
Activate these routines by issuing the USRCAL command or by choosing an equivalent menu path.
c
c output arguments:
c variable (typ,siz,intent) description
c dat (dp,ar(ndat),inout) - fluxes
c (defines input values for each corner
c of each face)
c
c the input argument dat may be used in one of three ways:
c 1. they may be simply passed thru.
c 2. they may be used as a flag(e.g. if dat(2) = -3.0, use
c a certain set of logic).
c 3. they may be completely ignored.
c and instead redefined with new logic
c object/library:
c current - acel
c input arguments:
c key (int,sc,in) - Key to desired acceleration components
c 0 - Translational acceleration
c 1 - Angular Velocity
c 2 - Angular Acceleration
c 3 - Angular Velocity around C.G.
c 4 - Angular Acceleration arount C.G.
c 5 - C.G. Location in global coord. system
c output arguments:
c vect (dp,ar(3),out) - Return value as given by key
Below is an example of using the usercv subroutine. First, here is the ANSYS input for the example:
/bat,list
/prep7
/title,test of velocity-dependent film coefficient
/com default logic (triggered with usrcal,usercv) will set the
/com film coefficient in SURF19 to the velocity in FLUID66
et,1,66
keyo,1,9,1 ! flag to save values
et,3,55
r,1,1,1,,1
mp,dens,,1
mp,kxx,,11
mp,mu,,0.01
n,1
n,4,100
fill
n,11, ,5
n,12,30,5
n,13,30,8
n,14, ,8
type,1
e,1,2
egen,3,1,-1
type,2
e,11,12,2
type,3
e,11,12,13,14
elist,all
noor
fini
Now, look at the results from this example analysis (shown below). Note that the FLOW RATE magnitude for FLUID66 matches the
HFILM for SURF19.
c
c Two Dimensional model (plane42)
c component rotation
c FAST OMGFAST
c SLOW OMGSLOW
return
end
/bat,list
/title, demonstrate use of useracel
/prep7
et,1,42
/nopr
mp,ex,,12e6
mp,dens,,.004
n,1
n,11,50
fill
ngen,6,20,1,11,1,,3
e,1,2,22,21
egen,10,1,1
egen,3,40,all
d,1,all,,,101,20
d,all,uy
esel,s,elem,,11,20 ! define FAST component
cm,FAST,elem
eall
esel,s,elem,,21,30 ! define SLOW component
cm,SLOW,elem
eall
omega,0,0,0,1 ! turn on spin softening
OMGFAST = 1000 ! define parameter for use in useracel
OMGSLOW = 500 ! define parameter for use in useracel
! note that first 10 elements will be stationary
finish
/solu
/title, BASE CASE - STANDARD VERSION
/title, DEMONSTRATE USE OF useracuel(useracuel HAS BEEN LINKED IN AND USED)
Suppose that you ran this example problem using the standard ANSYS product. You'd receive the following output information:
Now, suppose that you re-run the problem after linking in and using the useracel subroutine. Your new results should look like those
shown below:
program ansys
If you're running ANSYS on a UNIX system (but not under Windows 95 or Windows NT), you also can call the ANSYS program as a
subroutine in a program you've written. To do so, use the following:
subroutine ansys
For multiple calls to subroutine ANSYS, you must open and close standard input in the calling routine. (Usually, input and output are
FORTRAN units 5 and 6, respectively.) The calling routine can't use the database access routines. But, other user programmable features
can use the database access routines freely.
1. Insert the code for the functions you want to perform into routine user01 (or user02, etc.).
3. Issue the ANSYS command /UCMD to define a name for a custom command that calls and executes your routine. Use the command
format shown below:
/UCMD,Cmd,SRNUM
Cmd is the name for your new command. It can contain any number of characters, but only the first four are significant. The name you
specify can't conflict with the name of any ANSYS command or the names of any other commands or macros.
SRNUM is the number of the routine your command should call; that is, a value between 01 and 10. For example, suppose that you create
and link in a user routine for a parabolic distribution of pressure, and you name that routine user01. Issuing the command shown below
creates a new command, PARB, that when issued calls your parabolic pressure distribution routine:
/UCMD,PARB,1
To make these "custom command" routines available in all your ANSYS sessions, include the /UCMD commands in your start-up file
(START.ANS).
You also can use /UCMD to remove a custom command. To do so, simply use a blank value for Cmd, as shown below:
/UCMD,,1
This command removes the PARB command. To list all user-defined command names, issue the command /UCMD,STAT.
c /*******************************************************************\
c | see user01 for additional information on user routines |
c \*******************************************************************/
c input arguments:
c variable (typ,siz,intent) description
c intin (int,ar(12),in) - integers from command line
c dpin (dp,ar(12),in) - double precision from command line
c ch4in (ch*4,ar(12),in) - upper case 4 characters from command
c ch8in (ch*8,ar(12),in) - as input 8 characters from command
c **************************************************************
c intin(2), dpin(2), ch4in(2), and ch8in are all representations
c of the contents of the second field on the command line
c (the field after the command label)
c **************************************************************
external wrinqr,ndinqr,ndgxyz,ndpxyz,erhandler
integer wrinqr,ndinqr,ndgxyz
#include "ansysdef.inc"
do i = 1,maxnp
ksel = ndgxyz (i,xyz(1))
if (ksel .eq. 1) then
xyz(1) = xyz(1) + dpin(2)
xyz(2) = xyz(2) + dpin(3)
xyz(3) = xyz(3) + dpin(4)
call ndpxyz (i,xyz(1))
endif
enddo
return
end
#include "ansysdef.inc"
#include "stack.inc"
c
c Get nodal xyz locations and calculate standard deviation of
c x coordinates, y coordinates, & z coordinates
c
c increment index
i = i + 1
endif
return
end
c primary function: Get the displacement at a node from the disp vector
c secondary functions: Return pointer for fast access
c object/library: usr
c input arguments:
c variable (typ,siz,intent) description
c Node (int,sc,in) - Node Number (User)
c Label (ch*4,sc,in) - DOF Label (Upper Case)
c 'UX ','UY ','TEMP','VOLT','ROTY', etc
c output arguments:
c variable (typ,siz,intent) description
c GetStackDisp (int,sc,out) - status/pointer
c = 0 - data not valid
c > 0 - dstack pointer to data for fast access
c see comments below
c Value (dp,sc,out) - Solution value for Node,Label
c example usage:
c external GetStackDisp
c#include "stack.inc" (only if dstack(ptr) form is used)
c integer GetStackDisp, ptr, Node2
c double precision Value
c later...
c Value = dstack(ptr)
c input arguments:
c variable (typ,siz,intent) description
c Label (ch*4,sc,in) - Result Type
c Comp (ch*4,sc,in) - Result Component (8 char for ESTR)
c LabAvg (ch*4,sc,in) - 'AVG ' or 'NOAV' ('AVG ' default)
c output arguments:
c TypeData (int,sc,out) - Code for data type
c nVal (int,sc,out) - Number of values per point
c If 0, no data
c Loc (int,sc,out) - Location of Comp in values
c input arguments:
c variable (typ,siz,intent) description
c nPoints (int,sc,in) - Number of evaluation points
c *** from ElInterp ***
c ebest (int,ar(nPoints),in) - Element(s) containing points
c elcord (dp,ar(3,nPoints),in) - Element coordinates
c *** from ElResultStrt ***
c TypeData (int,sc,in) - Data type code
c Loc (int,sc,in) - Start of selected data
c nVal (int,sc,in) - Number of results per point
c output arguments:
c Result (dp,ar(nvar,nPoints),out) - Array of results
c object/library: upf
c input arguments:
c variable (typ,siz,intent) description
c nPoints (int,sc,in) - Number of points to find (do in one group)
c xyzPoints(dp,ar(3,nPoints),in)- XYZ coordinates of each point
c tolInside(dp,sc,in) - Tolerance for point inside element
c (0.0d0 defaults to 1.0d-4)
c tolOutside(dp,sc,in) - Maximum distance outside to be associated
c with an element (0.0d0 defaults to 0.25)
c output arguments:
c variable (typ,siz,intent) description
c ebest (int,ar(nPoints),out) - Best element number for each point
c elcord (dp,ar(3,nPoints),out) - Element coordinates of the point
Issue the USRCAL command (or use an equivalent menu path) to activate or deactivate these routines.
User Subroutine Is Called
Subroutines USSBeg, UItBeg, UItFin and USSFin default to reading a command macro file from the current working directory whose
name is subroutine.mac (i.e., ussfin.mac is read by USSFin.F). No user action to relink the ANSYS program is required for the command
macro to be read except that the calling subroutine must be activated by the USRCAL command. The design of the command reading
ability of these subroutines is limited to APDL parameter setting commands (*GET, *SET, a=value, etc) and testing for general ANSYS
commands is limited. Commands which are known to work include *DIM, *STAT. Commands which require another line (*MSG,
*VWRITE) are not allowed. Other commands which are known to not work are the solution loading commands (D, F, SFE, etc). If these
capabilties are required, the user will need to create a Fortran subroutine and link this subroutine into ANSYS, as described in Section 1.1.
While parameter substitution into commands is not permitted, USSBeg, etc. were designed to be used in conjunction with dynamic tables
and parameter substitution from the user subroutine. As an example, consider an ANSYS table defined as d5 = f(par1), If d5 contains
values of displacement as a function of PAR1, then d5 may be used as a constraint, as
*dim,d5,table,10,1,1,PAR1
d5(1)=0,.1,.25,
/solu
d,5,ux,%d5%
Modify the value of PAR1 in USSBeg.MAC and the constraint on node 5, ux can then be modified in the middle of a load step.
The following is an example of a valid input that may be read by USSBeg, UItBeg, UItFin and USSFin.
This chapter describes both methods. You can find additional information on design optimization techniques and procedures in Chapter 1
of the ANSYS Advanced Analysis Techniques Guide.
However, if you plan to use an optimization routine of your own design, you must do the following:
1. Define parameters for your external optimization routine, using either the OPUSER command or GUI path Main Menu>Design
Opt>Method/Tool. (For more information about OPUSER, see the ANSYS Commands Reference.)
2. Either issue the OPTYPE,USER command or choose menu path Main Menu>Design Opt>Method/Tool and specify user-defined
optimization logic.
3. Issue the OPEXE command or choose GUI path Main Menu>Design Opt>Run.
Issuing the OPTYPE,USER command (or its GUI equivalent) instructs the ANSYS program to bypass the standard ANSYS design
optimizer logic and instead execute your custom optimization routine.
Below is a simplified flow chart showing how a user-defined optimization routine interacts with the ANSYS program:
For information about the kopusr variable and the userop routine, see the next section.
Below is a listing of the inputs and outputs for userop and the comments of common block cmopt:
When you finish customizing the userop routine, you relink it using either of the methods described in section 1.1.8 and in the ANSYS
Installation and Configuration Guide for UNIX or in the ANSYS Installation and Configuration Guide for Windows. You must include the
cmopt common block in your routine, to allow it to pass common data (such as design variables, state variables, and objective function
values) to and from the ANSYS program.
/OPT
OPTYPE,USER ! ANSYS optimization logic bypassed
OPUSER, ! user-defined optimization to be done
OPVAR ! design and state variables & objective function values defined
.
.
.
OPEXE ! looping begins
The commented example below shows you sample ANSYS command input for design optimization, done with a user-customized version
of the userop routine:
c!!!---- minimize y = x1**2 + x2**2
c!!! --- subject to: 1 < x1 < 10
c!!! --- 1 < x2 < 10
c!!! --- g = x1 - x2 > 1
/OPT
OPTYPE,USER ! ANSYS optimization logic bypassed
OPUSER, ! user-defined optimization to be done
OPVAR ! design and state variables & objective function values defined
.
.
.
OPSAVE ! jobname.opt written for use by user-supplied program
/SYS ! run the user-supplied program
OPRESU ! read results of user-supplied program from jobname.out
OPEXE ! looping begins
The OPSAVE and OPRESU commands write data to and read data from Jobname.OPT, and they also pass data to and from your custom
optimization program.
Note-The order of oplim, optol, and optvar is state variables, design variables, then objective function. In addition, optvar can contain any
other ANSYS parameter.
Variable Description
fstfst First design set number in the range of first order sets
grdtyp Reference design set type (best, last, or number) for gradient
ilamda Exponent that controls the resolution (sharpness) of the unconstrained objective function (in first order optimization)
nmswps The number of sweep evaluations to be made in each design variable dir.
optol(I) Tolerance
rdfrom Indicates where to begin reading the analysis file (0 = top, 1 = after /Prep7)
swptyp Reference design set type (best, last, or number) for sweep
The ANSYS program allocates Heap space dynamically as it runs. User routines can use heap space to avoid adding large data sets (arrays)
within these routines. Include the file stack.inc (on the ANSYS distribution medium) to allocate data space from the Heap. To do so,
follow these steps:
1. Use the function HeapAllocPtr to notify the ANSYS program that space from the Heap is required.
The starting location for the array(s) in the Heap memory area is also returned. Where leng(argument 1) is the number of array
words needed:
You must include the ansysdef.inccommon to get the parameter values of HEAP_INTEGER, HEAP_DOUBLE,
HEAP_COMPLEX, and HEAP_REAL.
4. Use the arrays. You must include the common stack.inc in the routines accessing the Heap space. You can find stack.inc on the
ANSYS distribution medium. The location of the first data entry for the array depends on the type of numbers in the array:
5. If one routine allocates Heap space and another routine uses the space, you need to pass only the "handle" to the second routine. You
also must include the stack common, just as you did in Step 4. The HeapGetPtr function can retrieve the starting location minus 1, as
follows:
ptri =HeapGetPtr(iHandle)
ptrdp =HeapGetPtr(dHandle)
ptrcp =HeapGetPtr(cHandle)
ptrr =HeapGetPtr(rHandle)
call HeapDealloc(iHandle)
call HeapDealloc(dHandle)
call HeapDealloc(cHandle)
For real numbers:
call HeapDealloc(rHandle)
The next few pages provide input and output listings for the memory management routines.
For an example, see the section "Function user03 (Demonstrates Using Heap Memory)," which appears earlier in this chapter.
c object/library: heap
c input arguments:
c nValues (int,sc,in) - Number of Values needed in Block
c c16Label (ch*16,sc,in) - 16 character name for the Block
c flagAlloc(int,sc,in) - Flags describing this block (See ANSYSDEF
c and heapcom for more information)
c output arguments:
c hHeapHandle (int,sc,out) - Handle (Block number) for this block
c HeapAllocPtr (int,sc,out) - Pointer to this data block (Use Ptr+i) for
c reference to ith value in the block
c object/library: heap
c input arguments:
c hHeapHandle (int,sc,out) - Handle (Block number) for this block
c object/library:
c current - heap
c output arguments:
c HeapGetPtr (int,sc,out) - The corresponding pointer
c *dim,parm8,type,d1,d2,d3,name1,name2,name3
c input arguments:
c label8 (chr*8,sc,in) - the name of the parameter to create
c labl4 (chr*4,sc,in) - 'TABL' or 'ARRA' or 'CHAR'
c nxyz (int,ar(3),in) - the dimensions of the array
c names (chr*8,ar(3),in) - Names for x,y,z directions in table
c input arguments:
c label8 (chr*8,sc,in) - the name of the parameter
c (must be upper case, left justified)
c nval (int,sc,in) - the number of subscripts (0,scaler)
c subc (dp,ar(3),in) - values for the subscripts (if any)
c lvl (int,sc,in) - 0,1 no error output 2, report error
c -1, set kerr flag with no anserr call
c output arguments:
c parevl (dp,sc,out) - the value of the parameter (may be a
c packed character*8
c kerr (int,sc,out) - error flag (0,ok -1,output is packed
c 0=ok, 1=error, 2=error but TINY is used
c input arguments:
c label8 (chr*8,sc,in) - name of parameter
c label 8 is a character*8 variable that
c contains the name of the parameter that
c is to be defined.
c
c ctype (int,sc,in) - 0, dp 1,character
c ctype is an integer key which describes
c the type of data that the parameter data
c holds. This would also indicate the
c contents of "value" (arg 5).
c 0=double precision data
c 1=character data
c
c nval (int,sc,in)i - number of subscripts
c nval is the number of subscripts that the
c "label8" (arg 1) contains.
c 1=single dimensioned variable (ex. x(10))
c 2=double dimensioned variable (ex. y(10,3))
c 3=triple dimensioned variable (ex. z(10,3,2))
c -1=delete this parameter from the internal
c tables.
c
c subc (dp,ar(3),in) - values of subscripts
c subc is a double precision vector that
c contains the subscripts of "label8" (arg 1).
c There should be enough values defined to
c match "nval" (arg 3). For example if "x"
c was dimensioned as "x(10,3,2)" and you wanted
c to set "x(5,1,1)=123.0", then "nval" (arg 3)
c should be set to 3, and "subc" should be set
c to 5.0, 1.0, 1.0, and "value" (arg 5) should
c be 123.0. Another example is if "y" was
c dimensioned to as "y(20,20)" and you were
c setting "y(5,8)=987", then "nval" (arg 3) should
c be set to 2 and "subc" should be set to 5.0,
c 8.0, 0.0, and "value" (arg 5) should be 987.0.
c
c Remember subroutine "pardef" is only storing
c a data value of "label8" or "label8(x,y,z)". The
c proper dimensions were set by a "*dim" command.
c
c Please note that although the values of "subc"
c should be double precision, subroutine "pardef"
c uses the intrinsic "nint" (nearest integer)
c function to get and use the integer equivalent.
c
c You should also note the "nval" (arg 3) and
c "subc" (arg 4) must fall within the range that was
c set with a "*dim" or "*set" command or an error
c will occur.
c
c value (dp,sc,in) - the value for this parameter
c (should be a packed character*8 if
c ctype=1. To pack a char into a dp
c variable use "call chtodp(ch8,dp)".
c To unpack a dp variable into a char
c use "call dptoch(dp,ch8)" )
c Value is the data value that is to be stored for
c "label8" (arg 1). If "ctype=1" (arg 2) then this
c value would be a "packed character" data from the
c "chtodp" Ansys function.
c
c output arguments:
c kerr (int,sc,out) - error flag (0=ok, 1=error)
c kerr is an integer error flag that is
c returned to the calling subroutine. Any
c non zero number would indicate an error
c was detected in subroutine "pardef"
Note-For a demonstration of parameter processing, see the examples based on the useracel routine in this manual. You can find examples
in section 1.7.7.
● The erhandler routine displays output messages (notes, warnings, and errors).
● The runcmd function lets you issue an ANSYS command from within a user routine.
● The GetStackDisp routine retrieves current displacement values.
● The /UNDO command writes an "undo" file at critical points as a user routine executes.
● The /HOLD command allows you to synchronize multiple tasks in ANSYS.
● The /TRACK function enables you to do program tracing and timing.
For further descriptions of erhandler and /TRACK, see Chapter 3, "Subroutines for Users' Convenience." For details about the
GetStackDisp function, see section 1.10.2.
c object/library: upf
c input arguments:
c command (ch*128,sc,in) - A character string containing a
c valid ANSYS command, up to 128 char
You can use the database access routines with any of the user-programmable features. For example, you can create your own
ANSYS commands and use them to execute database access routines (or have a database access routine call a user-defined
command).
int - integer
dp - double precision
log - logical
chr - character
sc - scalar variable
in - input argument
c input arguments:
c variable (typ,siz,intent) description
c node (int,sc,in) - node number
c vctn (dp,ar(6),in) - array of 3 nodal coordinates and
c 3 nodal rotation angles.
c kcrot (int,sc,in) - local coordinate system in which the nodal
c coordinates and angles are defined
c output arguments:
c none.
c output arguments:
c ceget (int,func,out) - number of dof in equation
c ieqn (int,ar(ceget+1),out) - integer info
c ieqn(1:ceget) - list of node*32+dof
c ieqn(ceget+1) - number of dof in equation
c (copy of return value)
c deqn (dp,ar(ceget+1),out) - dp info
c deqn(1:ceget) - list of coefficients
c deqn(ceget+1) - constant term
c input arguments:
c nce (int,sc,in) - constraint equation set number
c n (int,sc,in) - number of degrees of freedom in set
c ieqn (int,ar(n+1),in) - integer info
c ieqn(1:n) - node*32+dof for each dof in set
c ieqn(n+1) - number of dof in set (copy of n above)
c deqn (dp,ar(n+1),in) - dp info
c deqn(1:n) - coefficients of each dof in set
c deqn(n+1) - constant term
c output arguments:
c none.
c output arguments:
c none.
c output arguments:
c none.
c output arguments:
c none.
c input arguments:
c node (int,sc,in) - node number
c ndf (int,sc,in) - number of results to be stored
c idf (int,ary(ndf),in) - reference number for the DOF: (1-32)
c value (dp,ar(ndf),in) - displacement values
c output arguments: none
int - integer
dp - double precision
log - logical
chr - character
sc - scalar variable
in - input argument
out - output argument
c input arguments:
c dp8 (dp,sc,in) - dp variable containing characters
c output arguments:
c ch8 (ch*8,sc,out) - characters retreived from the dp word
c input arguments:
c sub16 (char*(*),sc,in) - name of subroutine being entered and left
c (16 characters max)
c input arguments:
c subname (char*(*),sc,in) - name of subroutine being left
c (16 characters max)
c input arguments:
c variable (typ,siz,intent) description
c filein (ch*16,sc,in) - Filename used for character portion of
c message ID (this is the file name of the
c file which contains the source for this
c routine)
c msgid (int,sc,in) - Numeric portion of the message ID
c 1 - 9999, unique for each erhandler
c call in the FILE. Recommend using
c a sequence, similar to format conventions,
c i.e., 3010, 3020, 3030
c msglvl (int,sc,in) - level of error (same as anserr)
c 0=no label (used for u/i pop-ups)
c -1=no label (used for u/i pop-ups) timed
c as a note message
c 1=note, 2=warning, 3=error, 4=fatal
c messg (ch*256,sc,in) - error message to display. use keywords
c of %i %g %c %/ for formating (same as
c anserr)
c dperr (dp,ar(*),in) - vector of data to display. contains both
c integer and double precision data.
c (same as anserr)
c cherr (ch*(*),ar(*),in) - vector of character data to display
c max length of character data is 32 characters
c vector element. (same as anserr)
3.2.7 intrp Subroutine (Doing Single Interpolation)
subroutine intrp (klog,kppx,kstpz,xval,ax,ay,yval,nmax,kyoff)
c *** primary function: **** subroutine for single interpolation ****
c (if double interpolation is needed, see intrpt)
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c typ=int,dp,log,chr,dcp siz=sc,ar(n),func intent=in,out,inout
c
c input arguments:
c variable (typ,siz,intent) description
c klog (int,sc,in) - interpolation type
c = 0 - use linear interpolation
c = 1 - use log interpolation
c kppx (int,sc,in) - X value end of table signal
c = 0 - a repeated x-value will signal the end
c of the table
c = 1 - a repeated x-value will not signal the
c end of the table
c (only known use = c evaluation)
c kstpz (int,sc,in) - Y value end of table signal
c = 0 - a yval of zero will not signal the end
c of the table (e.g. stress fitting)
c = 1 - a yval of zero will signal the end of
c the table (in general, material
c properties (exception: alpx))
c
c NOTE: the end of the table will be signaled thru
c either of the above conditions, or more
c commonly, that nmax values have been processed,
c or that the present x table entry is less than
c the previous one (ax(i) .lt. ax(i-1)).
c evaluations done after the end of the table are
c evaluated as if they were at the end of the
c table. similarly, evaluations done before the
c beginning of the table are done as if they were
c done at the beginning of the table.
c
c xval (dp,sc,in) - value of x with which to go into the table
c ax (dp,ar(*),in) - table of x values, in ascending order
c ay (dp,ar(*),in) - table of y values
c nmax (int,sc,in) - maximum table size allowed
c
c output arguments:
c yval (dp,sc,out) - value of y which comes back from the table
c kyoff (int,sc,out) - xval status flag
c = 0 - xval in x range
c = 1 - xval less than minimum x
c = 2 - xval greater than maximum x
c input arguments:
c v1 (dp,ar(n),in) - vector v1
c v2 (dp,ar(n),in) - vector v2
c n (int,sc,in) - length of vectors v1 and v2
c output arguments:
c vdot (dp,sc,out) - dot product of v1 and v2
c input arguments:
c va (dp,ar(n),in) - vector va
c n (int,sc,in) - length of vector va
c output arguments:
c vsum (dp,sc,out) - vector sum
c input arguments:
c v (dp,ar(n),in) - vector v
c n (int,sc,in) - length of vector v
c output arguments:
c locmax (int,sc,out) - location of max value in vector v
c vmax (dp,sc,out) - max value in vector v
3.3.4 lastv Function (Retrieving the Position of the Last
Non-zero Term in a Double Precision Vector)
function lastv (v,n)
c *** primary function: find position of last non-zero term in a d.p. vector
c
c input arguments:
c v (dp,ar(n),in) - vector V
c n (int,sc,in) - the number of items in the vector
C output arguments:
c lastv (dp,sc,out) - the position of the last non-zero term
C output arguments:
c v2 (int,ar(*),out) - vector v2
c input arguments:
c v (dp,ar(n),inout) - vector to zero out
c n (int,sc,in) - number of words to zero out
c output arguments:
c v (dp,ar(n),inout) - zeroed vector
3.3.8 vmove Subroutine (Moving One Vector into Another)
subroutine vmove (v1,v2,n)
c *** primary function: move a vector into another vector
c
c *** Notice - This file contains ANSYS Confidential information ***
c
c input arguments:
c v1 (dp,ar(*),in) - vector v1
c n (int,sc,in) - length of vectors v1, v2
c
c output arguments:
c v2 (dp,ar(*),out) - vector v2
c input arguments:
c n (int,sc,in) - length of vector v
c const (dp,sc,in) - constant to set vector v to
c output arguments:
c v (dp,ar(n),out) - vector v
c input arguments:
c a (dp,ar(n),in) - a vector
c b (dp,ar(n),in) - b vector
c n (int,sc,in) - length of vectors a,b,c
c output arguments:
c c (dp,ar(n),out) - c vector
c input arguments:
c a (dp,ar(n),inout) - a vector
c b (dp,ar(n),in) - b vector
c n (int,sc,in) - length of vectors a,b
c output arguments:
c a (dp,ar(n),inout) - a vector
c input arguments:
c a (dp,ar(n),inout) - vector a
c b (dp,ar(n),in) - vector b
c n (int,sc,in) - length of vectors a,b
c const (dp,sc,in) - constant to multiply b
c output arguments:
c a (dp,ar(n),inout) - vector a
c input arguments:
c a (dp,ar(n),in) - vector a
c b (dp,ar(n),in) - vector b
c n (int,sc,in) - length of vectors a,b,c
c output arguments:
c c (dp,ar(n),out) - vector c
c input arguments:
c a (dp,ar(n),inout) - a vector
c b (dp,ar(n),in) - b vector
c n (int,sc,in) - length of vectors a,b
c output arguments:
c a (dp,ar(n),inout) - a vector
c output arguments:
c v2 (dp,ar(n),out) - vector v2
c input arguments:
c v1 (dp,ar(n),inout) - vector v1
c n (int,sc,in) - length of vector n
c const (dp,sc,in) - constant to multiply v1
c output arguments:
c v1 (dp,ar(n),inout) - vector v1
c input arguments:
c a (dp,ar(3),in) - first vector to be cross-multiplied
c b (dp,ar(3),in) - second vector to be cross-multiplied
c output arguments:
c c (dp,ar(3),out) - resulting vector
c input arguments:
c iel (int,sc,inout) - element number
c v (dp,ar(3),inout) - vector to be normalized
c output arguments:
c iel (int,sc,inout) - if 0, vector has zero length
c v (dp,ar(3),inout) - normalized vector
c input arguments:
c a (dp,ar(nr,*),in) - matrix a
c v (dp,ar(*),in) - vector v
c nr (int,sc,in) - number of rows in matrix a
c nc (int,sc,in) - number of columns to multiply in matrix a
c output arguments:
c w (dp,ar(*),out) - product vector w
c input arguments:
c a (dp,ar(nr,nc),in) - matrix a
c v (dp,ar(nc),inout) - vector v
c nr (int,sc,in) - number of rows in matrix a
c *** nr limited to 60 ***
c nc (int,sc,in) - number of columns to multiply in matrix a
c output arguments:
c v (dp,ar(nr),inout) - product, stored in vector v
c input arguments:
c a (dp,ar(nr,*),in) - matrix a (first dimension must = nr)
c v (dp,ar(nv),in) - vector v (nv must be greater or equal
c to nr)
c nr (int,sc,in) - first dimension and number of active
c rows of the untransposed matrix a
c (also the number of active rows
c of vector v)
c nc (int,sc,in) - number of columns of the untransposed
c matrix a
c (also the number of computed items
c in the product vector w)
c if negative, accumulate
c output arguments:
c w (dp,ar(na,*),out) - product vector w
c input arguments:
c a (dp,ar(nr,*),in) - matrix a
c v (dp,ar(nr),inout) - vector v
c nr (int,sc,in) - number of rows in matrix (un-transposed)
c nc (int,sc,in) - number of columns in matrix (un-transposed)
c *** nc limited to 60 ***
c output arguments:
c v (dp,ar(nc),inout) - product, stored in vector v
c input arguments:
c a (dp,ar(na,*),in) - matrix a
c b (dp,ar(nb,*),in) - matrix b
c na (int,sc,in) - number of rows in matrix a
c nb (int,sc,in) - number of rows in matrix b
c nc (int,sc,in) - number of rows in matrix c
c n1 (int,sc,in) - number of rows in matrix c to fill
c n2 (int,sc,in) - number of columns in matrix c to fill
c n3 (int,sc,in) - number of columns in matrix a and
c number of rows of matrix b
c to work with (the two need
c to be the same for the inner product)
c output arguments:
c c (dp,ar(nc,*),out) - product matrix c
c input arguments:
c a (dp,ar(*),in) - vector to be multiplied by itself to
c generate an nxn square matrix
c (a by a-transposed)
c c (dp,ar(nc,*),inout) - matrix to be accumulated onto
c nc (int,sc,in) - number of rows in the c matrix
c n (int,sc,in) - size of square matrix
c con (dp,sc,in) - multiplier on above square matrix
c output arguments:
c c (dp,ar(nc,*),inout) - matrix to be accumulated onto
c only the lower triangular matrix is done
c input arguments:
c a (dp,ar(nd,*),inout) - matrix to have its lower triangular part
c copied to its upper triangular part
c nd (int,sc,in) - number of rows of the a matrix
c n (int,sc,in) - size of matrix to be processed
c output arguments:
c a (dp,ar(nd,*),inout) - matrix that has its lower triangular part
c copied to its upper triangular part
c input arguments:
c a (dp,ar(na,na),inout) matrix to be pre and post multiplied
c (part operated on must be
c square(nold x nold) and symmetric)
c na (int,sc,in) first dimension of the a matrix
c c (dp,ar(nc,nnew),in) matrix to pre and post multiply a by
c (part used may be rectangular(nold x nnew))
c nc (int,sc,in) first dimension of the c matrix
c nold (int,sc,in) size of part of 'A' matrix that is
c to be processed(input size). maximum = 64
c nnew (int,sc,in) size of part of 'A' matrix that
c results from this operation(output size).
c maximum = 64
c output arguments:
c a (dp,ar(na,na),inout) resulting matrix
c (still square(nnew x nnew) and symmetric).
c input arguments:
c variable (typ,siz,intent) description
c zs (dp,ar(nz,nz),inout) - matrix to be transformed
c tr (dp,ar(ntr,ntr),in) - transformation matrix
c nz (int,sc,in) - dimensioned size of zs matrix
c ntr (int,sc,in) - dimensioned size of tr matrix
c nrow (int,sc,in) - number of rows of zs matrix to transform
c irot (int,sc,in) - block size to transform(size of tr matrix)
c output arguments:
c variable (typ,siz,intent) description
c zs (dp,ar(nz,nz),inout) - transformed matrix
3.4.10 symeqn Subroutine (Solving Simultaneous Linear
Equations)
subroutine symeqn (a,nd,n,nc)
c primary function: solve a set of simultaneous linear equations
c secondary functions: invert a matrix
c this routine assumes that the matrix to be solved or
c inverted is positive definite
c input arguments:
c variable (typ,siz,intent) description
c a (dp,ar(nd,*),inout) - matrix to be solved or inverted
c second dimension must be at least:
c n + abs(nc)
c nd (int,sc,in) - first dimension of the a matrix
c n (int,sc,in) - number of equations
c nc (int,sc,in) - number of additional columns.
c if nc = +n or -n, invert n x n matrix and
c put result in the n+1 to 2xn columns.
c if nc is 0 or negative, nc will be reset to
c n and then symeqn will set up identity
c matrix after the input matrix, where the
c result of the inversion will be put.
c if nc is positive and less than n, do a
c partial inversion. see example 1 below.
c output arguments:
c variable (typ,siz,intent) description
c a (dp,ar(nd,*),inout) - results or inverted matrix.
c starts in column n+1.
c note: original information is destroyed.
c
c example 1: Solve three simultaneous linear equations:
c call symeqn (a(1,1),3,3,1)
c calling routine has a dimensioned as a(3,4)
c each equation has its 3 coefficents in the first 3 columns,
c and the constant term is in the fourth column.
c solution is in fourth column.
c
c example 2: Invert a 3x3 matrix:
c call symeqn (a(1,1),3,3,-3)
c calling routine has a dimensioned as a(3,6)
c input matrix was input in first 3 columns
c output matrix in ouput in last 3 columns
● IRIX
● HP-UX
● Solaris
● Digital UNIX
● AIX
Refer to your installation guide for currently supported operating system levels and compilers. This capability is
currently not available for any version of Microsoft Windows (note that the presence of compatible compilers and
linkers is assumed in these instructions).
● Create an external table file (ans_ext.tbl), listing the various shared libraries, each function, and the related
command.
● Set an environment variable pointing to the directory that holds the external table file. This variable must be
set before executing ANSYS.
● The C program interface is an integer function that has one argument (a char pointer).
● The FORTRAN program interface is an interger function that takes an integer argument. (The integer
argument is assumed to be the same size as a pointer.)
Note-In the following C example, for the HP/UX platform "icmdan_ " is "icmdan" (no trailing underbar).
#include <stdio.h>
extern void icmdan_(int*, int[]);
extern void writeoutc(char[],int);
/*
------------------------------ Function Description -----------------------
extfnc
int extfnc(uecmd)
char *uecmd;
Purpose:
Demonstrate C API entry function for an external command.
Parameters:
Input
-----------------------------
uecmd
The ANSYS external command string.
Output
-----------------------------
Return Value:
The return value is ignored by the calling function;
where
-h
-64
Configures the Makefile to use the -mips4option for IRIX64 6.1 and 6.2.
shared_object_name
As gen_share is executing, you may see one or more "No match" messages. This is normal. The script is searching
for .c, .f, and .F file types in the current directory and returns this message if it cannot locate any files matching one of
those types.
For example, to create a shared library called mylibrary.so, you would issue the following command:
% gen_share mylibrary.so
The utility will produce a Makefile in the current directory. If your compiler is properly installed, you will be able to
generate the shared library by issuing the following command:
make (shared_object_name)
For example, to create the shared library for mylibrary.so, you would issue the following command:
% make mylibrary.so
If all went well, you will find the specified shared library file in the current directory. You may also see warning from
the make process and you may need to modify the Makefile as required.
Where
/shared/library/path/library.so
Is the path to the directory that contains the shared library file. (Remotely mounted file systems aren't
recommended.)
~cm_name
Is the used to invoke the function within ANSYS. The command name must begin with a tilde (~) and each
command name must be unique within the first four characters.
function_name
Is the name of the function that is referenced by the specified command name. (This must be unique within the
first four characters if multiple external commands are specified.)
For example, the following entry references the /home/mydir/mylibs/myobject.so shared library and the myobject_
function and specifies ~myobj as the related command:
ANSYS also makes use of external commands, and places its own shared libraries and the associated external table
file in the /ansys55/lib/platform directory (where platform is the directory specific to your computing platform, such
as /sgi32 or /hppa8000).
● ANSYS first checks the ans_ext.tbl file in the /ansys55/lib/platform directory and loads any external
commands referenced there.
● ANSYS then loads external commands referenced by the external table file in the directory designated with the
ANSYS_EXTERNAL_TABLE environment variable (see section A.2.4).
If you designate a command name that has the same first four characters as a command listed in the
/ansys55/lib/platform/ans_ext.tbl file, you won't be able to access your command. Therefore, it's a good practice to
check the ANSYS external table file to make sure you have no external command name conflicts. Don't modify the
/ansys55/lib/platform/ans_ext.tbl file. You can also use the ~DEBUG command to verify that no external command
name conflicts exist.
Note-All platforms except for HP-UX use the convention of specifying an underscore (_) as the last character of a
FORTRAN function. HP-UX does not require the trailing underscore.
Note-The shared library must be consistant with the computer type and OS level on which ANSYS will be executed.
A.2.4 Setting the ANSYS_EXTERNAL_TABLE
Environment Variable
Before launching ANSYS, you must first set the ANSYS_EXTERNAL_TABLE to point to the directory containing
the external table file. (For convenience, if you distribute your new functionality to other users they should set this
their your .login files so that it is persistent from session to session.) For example, the following sets the environment
variable to point to the /home/mydir directory.
Note-Avoid recursive external commands; that is, avoid situations where an external command calls another external
command.
Note that the output lists the command, the related shared library, the function, and if the command has been
accessed.
by issuing the ~RESET command. The command issues the following message to confirm that the reset operation
was complete.
~RESET was processed: The external command buffers have been cleared.
Note-The /CLEAR command also closes/resets all external command shared libraries.
subroutine newsub(i1)
return
end
You can create a Makefile for this function by issuing the following command:
% gen_share ecmd.so
% make ecmd.so
After you've created your shared library, you can create the external table file with a single entry for that library,
function, and command. Remember to set the ANSYS_EXTERNAL_TABLE environment variable to point to the
directory that contains the file.
Launch ANSYS, enter the /PREP7 processor and create at least one node (N,1,1,1, for example). You can issue the
command name that you defined and you should see something like the following in the output window: