ANSYS Programmer's Manual Table of Contents

ANSYS APDL Programmer's Guide 1 What is APDL? 2 Adding Commands to the Toolbar 3 Using Parameters 4 APDL as a Macro Language 5 Interfacing With the GUI 6 Encrypting Macros Guide to Interfacing with ANSYS 1 Format of Binary Data Files 2 Accessing Binary Data Files 3 Using CDREAD and CDWRITE 4 ANSYS Graphics File Format ANSYS UIDL Programmer's Guide 1 What is UIDL? 2 Modifying Menu Blocks 3 Modifying Function Blocks 4 Creating Help Blocks 5 Advanced Topics

6 Programming Example Appendix A UIDL Command Dictionary Appendix B ANSYS Keywords Appendix C ANSYS Product Codes Appendix D Testing and Troubleshooting Appendix E Additional Help Tools Guide to ANSYS User Programmable Features 1 Using User Programmable Features (UPFs) 2 Accessing the ANSYS Database 3 Subroutines for Users' Convenience Appendix A External Commands

ANSYS APDL Programmer's Guide Table of Contents Preface

Conventions Used in This Guide About the Programmer's Guide Set

1 What is APDL? 2 Adding Commands to the Toolbar

2.1 Modifying the Toolbar 2.2 Nesting Toolbar Abbreviations

3 Using Parameters
3.1 Parameters 3.2 Guidelines for Parameter Names 3.3 Defining Parameters 3.3.1 Assigning Parameter Values During Execution 3.3.2 Assigning Parameter Values At Startup 3.3.3 Assigning ANSYS-Supplied Values to Parameters 3.3.3.1 Using the *GET Command 3.3.3.2 Using Inline Get Functions

3.3.4 Listing Parameters 3.4 Deleting Parameters 3.5 Using Character Parameters 3.6 Substitution of Numeric Parametric Values 3.6.1 Preventing Substitution 3.6.2 Substitution of Character Parametric Values 3.6.2.1 Forced Substitution 3.6.2.2 Other Places Where Character Parameters Are Valid 3.6.2.3 Character Parameter Restrictions 3.7 Dynamic Substitution of Numeric or Character Parameters 3.8 Parametric Expressions 3.9 Parametric Functions 3.10 Saving, Resuming, and Writing Parameters 3.11 Array Parameters 3.11.1 Array Parameter Basics 3.11.2 Array Parameter Examples 3.11.2 TABLE Type Array Parameters 3.11.3 Defining and Listing Array Parameters 3.11.4 Specifying Array Element Values 3.11.4.1 Specifying Individual Array Values

3.11.4.2 Filling Array Vectors 3.11.4.3 Interactively Editing Arrays 3.11.4.4 Filling an Array From a Data File Using *VREAD 3.11.4.4 Filling a TABLE Array From a Data File Using *TREAD 3.11.2 Interpolating Values 3.11.4.5 Retrieving Values into or Restoring Array Parameter Values 3.11.4.6 Listing Array Parameters 3.11.5 Writing Data Files 3.11.5.1 Format Data Descriptors 3.11.6 Operations Among Array Parameters 3.11.6.1 Vector Operations 3.11.6.2 Matrix Operations 3.11.6.3 Specification Commands for Vector and Matrix Operations 3.11.7 Plotting Array Parameter Vectors

4 APDL as a Macro Language

4.1 What is an APDL Macro? 4.2 Creating a Macro 4.2.1 Macro File Naming Conventions 4.2.2 Macro Search Path

4.2.3 Creating a Macro Within ANSYS 4.2.3.1 Using *CREATE 4.2.3.2 Using *CFWRITE 4.2.3.3 Using Utility Menu>Macro>Create Macro 4.2.4 Creating Macros with a Text Editor 4.2.5 Using Macro Library Files 4.3 Executing Macros and Macro Libraries 4.4 Local Variables 4.4.1 Passing Arguments to a Macro 4.4.2 Local Variables Within Macros 4.4.3 Local Variables Outside of Macros 4.5 Controlling Program Flow in APDL 4.5.1 Nested Macros: Calling Subroutines Within a Macro 4.5.2 Unconditional Branching: Goto 4.5.3 Conditional Branching: The *IF Command 4.5.4 Repeating a Command 4.5.5 Looping: Do-Loops 4.6 Control Functions Quick Reference 4.7 Using the _STATUS and _RETURN Parameters in Macros 4.8 Using Macros with Components and Assemblies

4.9 Reviewing Example Macros

5 Interfacing With the GUI

5.1 Prompting Users For a Single Parameter Value 5.2 Prompting Users With a Dialog Box 5.3 Using Macros to Display Your Own Messages 5.4 Creating and Maintaining a Status Bar from a Macro 5.5 Picking within Macros 5.6 Calling Dialog Boxes From a Macro

6 Encrypting Macros
6.1 Preparing a Macro for Encryption 6.2 Creating an Encrypted Macro 6.3 Running an Encrypted Macro

APDL Programmer's Guide Index

Preface Conventions Used in This Guide

This guide uses the following typographic conventions to indicate various types of information: Convention Indicates ANSYS commands. These are shown as uppercase, bold text (for example, K, DDELE, etc.). In the online documentation, these provide hyperlinks to the appropriate command reference information. Menu paths (sometimes referred to as GUI paths). These are shown as bold text with mixed-case, separated by angle brackets ">". An angle bracket indicates a branch to a new menu item. File names, which may or may not include directory paths. These are shown as lower-case, bold text, unless case is significant. Examples are shown with the UNIX directory separator character "/" (slash); if you are using a Microsoft Windows system, use "\" (backslash) as your directory separator character. Arguments for numeric values (such as VALUE, INC, TIME) in command syntax. These are shown as upper-case italic text. On some commands, non-numeric convenience labels (for example, ALL and P) can also be entered for these arguments. Arguments for alphanumeric values (for example, Lab or Fname) in command syntax. These are shown in mixed-case, italic letters. The guide also uses italic text for emphasis. The name of an ANSYS manual. Command input listings, ANSYS output listings, and text that a user enters are shown in fixed-width font.

COMMAND

Menu > Item

path/filename.ext

ARGUMENT

Argument

ANSYS Guide Title

command,arg1,arg2

Note-

Information that supplements the main topic being discussed, such as important tips or guidelines. Actions or situations that could cause problems, unexpected ANSYS behavior, or unexpected results. Actions or situations that can shut down ANSYS, damage files, cause loss of data, etc.

Caution:

Warning:

About the Programmer's Guide Set

The ANSYS programmer's guide set provides information about the various programming interfaces available to customers. These manuals assume that you have at least a basic knowledge of programming (a working knowledge of Fortran 77 would be very helpful). The set of four manuals includes the following: The APDL Programmer's Guide 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 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. Guide To ANSYS User Programmable Features 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. Guide to Interfacing with ANSYS 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. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6

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.

Go to the beginning of this chapter

Chapter 2: Adding Commands to the Toolbar

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6

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. Figure 2-1 The ANSYS Toolbar Showing the Default Buttons.

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.

2.1 Modifying the Toolbar

You can create abbreviations either through the *ABBR command or through the Utility Menu > Macro > Edit Abbreviations or Utility Menu >MenuCtrls > Edit Toolbar menu items. Using one of the menu items is preferable for two reasons:
G

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.

The syntax for the *ABBR command and related dialogs is *ABBR, Abbr, String 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:
G G

The character "$" The commands C***, /COM, /GOPR, /NOPR, /QUIT, /UI, or *END

The default ANSYS toolbar has the following abbreviations predefined: *ABBR, *ABBR, *ABBR, *ABBR, *ABBR, SAVE_DB, SAVE RESUM_DB, RESUME QUIT, Fnc_/EXIT POWRGRPH, Fnc_/GRAPHICS ANSYSWEB, Fnc_HomePage

For example, to add a button to the toolbar that calls the macro file mymacro.mac, you would enter the values shown in the following figure in the Utility Menu >MenuCtrls > Edit Toolbar dialog box. Figure 2-2 Adding a New Abbreviation.

The new button is appended to the button bar as shown in the following figure. Figure 2-3 The Button for the New Abbreviation.

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.

2.2 Nesting Toolbar Abbreviations

The save-and-restore features described above allow you to nest abbreviations. By nesting abbreviations under one button, you can define specialized toolbars (if you have many abbreviations, having them on a single toolbar can be cluttered, making it difficult to find the proper button). To nest abbreviations, you simply define an abbreviation that restores an abbreviation file. For example, the following command defines PREP_ABR as an abbreviation that restores abbreviations from the file prep.abbr. *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.

Go to the beginning of this chapter

Chapter 3: Using Parameters

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6

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 the ANSYS program will interpret the command as N,12,2.7,4 (which defines node 12 at X=2.7 and Y=4).

3.2 Guidelines for Parameter Names

Parameter names must
G G G

Begin with a letter. Contain only letters, numbers, and underscore characters. Contain no more than eight characters.

Examples of valid and invalid parameter names are Valid: ABC

PI X_OR_Y Invalid: NEW_VALUE (more than 8 characters) 2CF3 (begins with a number) M&E (invalid character "&") When naming parameters
G

Avoid parameter names that match commonly used ANSYS labels, such as: H Degree of freedom (DOF) labels (TEMP, UX, PRES, etc.) H Convenience labels (ALL, PICK, STAT, etc.) H User-defined labels (such as those defined with the ETABLE command) H Array type field labels (such as CHAR, ARRAY, TABLE, 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.

3.3.2 Hiding Parameters from *STATUS

Section 3.3.4 discusses listing parameters through the *STATUS comand. You can use a parameter naming convention to "hide" parameters from the *STATUS comand. Any parameter whose name ends in an underscore (_) will not be listed by *STATUS. 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.

3.3 Defining Parameters

Unless otherwise specified, the information in the next several sections applies to both scalar and array type parameters. Beginning with Section 3.11, the information is specific to array type parameters. 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.

3.3.1 Assigning Parameter Values During Execution

You can use the *SET command to define parameters. The following examples illustrate a set of example parameters defined using *SET:

*SET,ABC,-24 *SET,QR,2.07E11 *SET,XORY,ABC *SET,CPARM,'CASE1' 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).

3.3.2 Assigning Parameter Values At Startup

You can define parameters as arguments when launching ANSYS from the operating system command line. Simply type parameter definitions after the ANSYS execution command (which is system dependent) using the format -Name Value. For example, the following defines two parameters (parm1 and parm2) having the values 89.3 and -0.1: ansys55 -parm1 89.3 -parm2 -0.1 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.' ansys55 -cparm1 \'filename\' -cparm2 \'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.

3.3.3 Assigning ANSYS-Supplied Values to Parameters

ANSYS provides two powerful methods for retrieving values:
G G

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.

3.3.3.1 Using the *GET Command

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. The format for the *GET command is: *GET,Par,Entity,ENTNUM,Item1,IT1NUM,Item2,IT2NUM where
G G

G G

Par is the name of the parameter to store the retrieved item. Entity is a keyword for the item to be stored. Valid keywords are NODE, ELEM, KP, LINE, AREA, VOLU, etc. For a complete list of valid keywords, see the *GET description in the ANSYS Commands Reference. ENTNUM is the number of the entity (or zero for all entities). Item1 is the name of an item for a particular entity. For example, if Entity is ELEM, Item1 will be either NUM (the highest or lowest element number in the selected set) or COUNT (the number of elements in the set). (For a complete list of Item1 values for each entity type, see the *GET description in the ANSYS Commands Reference.)

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: *GET,BCD,ELEM,97,ATTR,MAT *GET,V37,ELEM,37,VOLU *GET,EL52,ELEM,52,HGEN *GET,OPER,ELEM,102,HCOE,2 *GET,TMP,ELEM,16,TBULK,3 *GET,NMAX,NODE,,NUM,MAX *GET,HNOD,NODE,12,HGEN *GET,COORD,ACTIVE,,CSYS ! ! ! ! ! ! ! ! BCD = Material number of element 97 V37 = volume of element 37 EL52 = value of heat generation in element 52 OPER = heat coefficient of element 102,face2 TMP = bulk temperature of element 16,face3 NMAX = maximum active node number HNOD = value of heat generation at node 12 COORD = active coordinate system number

3.3.3.2 Using Inline Get Functions

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. 3. Compute the middle location from MID=(L1+L2)/2. 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. The following table summarizes the available get functions: Get Function Retrieved Value Entity Status: NSEL(N) Status of node N (-1=unselected, 0=undefined, 1=selected) ESEL(E) Status of element E (-1=unselected, 0=undefined, 1=selected) KSEL(K) Status of keypoint K (-1=unselected, 0=undefined, 1=selected) LSEL(L) Status of line L (-1=unselected, 0=undefined, 1=selected) ASEL(A) Status of area A (-1=unselected, 0=undefined, 1=selected) VSEL(V) Status of volume V (-1=unselected, 0=undefined, 1=selected) Next Selected Entity: NDNEXT(N) Next selected node having a node number greater than N ELNEXT(E) Next selected element having an element number greater than E KPNEXT(K) Next selected keypoint having a keypoint number greater than K LSNEXT(L) Next selected line having a line number greater than L ARNEXT(A) Next selected area having an area number greater than A VLNEXT(V) Next selected volume having a volume number greater than V Locations: CENTRX(E) CENTRY(E) CENTRZ(E) NX(N) Centroid x-coordinate of element E in global Cartesian coordinate system Centroid y-coordinate of element E in global Cartesian coordinate system Centroid z-coordinate of element E in global Cartesian coordinate system X-coordinate of node N in the active coordinate system

NY(N) NZ(N) KX(K) KY(K) KZ(K)

Y-coordinate of node N in the active coordinate system Z-coordinate of node N in the active coordinate system X-coordinate of keypoint K in the active coordinate system Y-coordinate of keypoint K in the active coordinate system Z-coordinate of keypoint K in the active coordinate system

LX(L,LFRAC) X-coordinate of line L at length fraction LFRAC (0.0 to 1.0) LY(L,LFRAC) Y-coordinate of line L at length fraction LFRAC (0.0 to 1.0) LZ(L,LFRAC) Z-coordinate of line L at length fraction LFRAC (0.0 to 1.0) Nearest to Location: Number of the selected node nearest the X,Y,Z point (in the active coordinate system; lowest number for coincident nodes) Number of the selected keypoint nearest the X,Y,Z point (in the active coordinate system; lowest number for coincident keypoints)

NODE(X,Y,Z)

KP(X,Y,Z)

Distance: DISTND(N1,N2) Distance between nodes N1 and N2 DISTKP(K1,K2) Distance between keypoints K1 and K2 Distance between the centroid of element E and node N. Centroid is determined from the selected nodes on the element.

DISTEN(E,N)

Angles: Subtended angle between two lines (defined by three nodes where N1 is the vertex node). Default 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). Default is in radians (see the *AFUN command to select degrees).

ANGLEN(N1,N2,N3)

ANGLEK(K1,K2,K3)

Nearest to Entity:

NNEAR(N) KNEAR(K)

Selected node nearest node N Selected keypoint nearest keypoint K

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, 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.

ARNODE(N)

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 node. A zero is returned at the end of the list.

ENEXTN(N,LOC)

NELEM(E,NPOS) Node number in position NPOS (1-20) of element E Faces: Element adjacent to a face (FACE) of element E. The face number is the same as the surface 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.

ELADJ(E,FACE)

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 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 containing the selected nodes. For axisymmetric elements, the area is the full (360) area.

NMFACE(E)

ARFACE(E)

Degree of Freedom Results: UX(N) UY(N) UZ(N) UX structural displacement at node N UY structural displacement at node N UZ structural displacement at node N

ROTX(N) ROTX structural rotation at node N ROTY(N) ROTY structural rotation at node N ROTZ(N) ROTZ structural rotation at node N TEMP(N) Temperature at node N PRES(N) Pressure at node N VX(N) VY(N) VZ(N) VX fluid velocity at node N VY fluid velocity at node N VZ fluid velocity at node N

ENKE(N) Turbulent kinetic energy (FLOTRAN) at node N ENDS(N) Turbulent energy dissipation (FLOTRAN) at node N VOLT(N) Electric potential at node N MAG(N) Magnetic scalar potential at node N AX(N) AX magnetic vector potential at node N

AY(N) AZ(N)

AY magnetic vector potential at node N AZ magnetic vector potential at node N

3.3.4 Listing Parameters

Once you have defined parameters, you can list them using the *STATUS command. If the *STATUS command is issued without arguments, it provides a list of all of the currently defined parameters. The following example shows the command and a typical listing. *STATUS PARAMETER STATUSNAME ABC HEIGHT QR X_OR_Y CPARM VALUE -24.0000000 57.0000000 2.070000000E+11 -24.0000000 CASE1 ( 5 PARAMETERS DEFINED)

TYPE DIMENSIONS SCALAR SCALAR SCALAR SCALAR CHARACTER

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 PARAMETER STATUS- abc NAME ABC VALUE -24.0000000 ( TYPE SCALAR 5 PARAMETERS DEFINED) DIMENSIONS

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.

3.4 Deleting Parameters

You can delete specific parameters in two ways:
G

Issue the "=" command, leaving the right-hand side of the command blank. For example, to delete the QR parameter issue this command:

QR=
G

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.

3.5 Using Character Parameters

Typically, character parameters are used to provide file names and extensions. The desired file name can be assigned to a character parameter, and that parameter can be used anywhere a file name is required. Similarly, a file extension can be assigned to a character parameter and used where appropriate (typically the Ext command argument). In batch mode, this allows you to easily change file names for multiple runs by simply changing the initial alphanumeric "value" of the character parameter in your input file. Note-Remember that character parameters are limited to a total of eight characters. The following is a list of general uses for character parameters.
G G

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) ! MACRO is the name of a macro file ! Calls MACRO

NAME='MACRO' *USE,NAME
G

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 or NEWMACRO,'SY'

! Calls existing macro file NEWMACRO.MAC

3.6 Substitution of Numeric Parametric Values

Whenever you use a parameter name in a numeric command field, its value is automatically substituted. If no value has been assigned to the parameter (that is, if the parameter has not been defined), a near-zero value (2-100) will be substituted, usually without warning.

Note-Defining the parameter after it is used in a command does not "update" the command in most cases. (Exceptions are the commands /TITLE, /STITLE, *ABBR, and /TLABEL. See Section 3.6.2.1 for more information.) For example: Y=0 X=2.7 N,1,X,Y Y=3.5

! Node 1 at (2.7,0) ! Redefining parameter Y now does not update node 1

3.6.1 Preventing Substitution

You can prevent parameter substitution by enclosing the parameter name with single quotes ('), for example, 'XYZ'. The literal string is then used; therefore, this feature is valid only in non-numerical fields. Conversely, you can force parameter substitution in titles, subtitles, and filenames by enclosing the parameter name with percent signs (%). For example, /TITLE, TEMPERATURE CONTOURS AT TIME=%TM% 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.

3.6.2 Substitution of Character Parametric Values

Use of a character parameter in an alphanumeric command field generally results in automatic substitution of its value. Forced substitution and character parameter restrictions are explained below.

3.6.2.1 Forced Substitution

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:
G G

G G

/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.

Forced substitution is also valid in the following types of fields:

G

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

3.6.2.2 Other Places Where Character Parameters Are Valid

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.) *IF and *ELSEIF 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.) PARSAV and PARRES

These commands will save character parameters to a file (PARSAV command or menu path Utility Menu>Parameters> Save Parameters) and resume character parameters from a file (PARRES or Utility Menu>Parameters> Restore Parameters). *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.

3.6.2.3 Character Parameter Restrictions

Although character parameters have much of the same functionality as numerical parameters, there are several instances where character parameters are not valid.
G

G G

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.

3.7 Dynamic Substitution of Numeric or Character Parameters

Dynamic substitution of parameters will occur for the following commands: /TITLE, /STITLE, *ABBR, and /TLABEL. Dynamic substitution allows the revised value of a parameter to be used, even if the command which uses the parameter value has not been reissued. 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' The title "This is CASE 2" will appear on subsequent plots.

3.8 Parametric Expressions

Parametric expressions involve operations among parameters and numbers such as addition, subtraction, multiplication, and division. For example: X=A+B P=(R2+R1)/2 D=-B+(E**2)-(4*A*C) XYZ=(A<B)+Y**2

! Evaluates to D = -B + E2 - 4AC ! 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 The following is a complete list of APDL operators: Operator Operation + _ * / ** < > Addition Subtraction Multiplication Division Exponentiation Less-Than Comparison Greater-Than Comparison

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: 1. Operations in parentheses (innermost first) 2. Exponentiation (in order, from right to left) 3. Multiplication and division (in order, from left to right) 4. Unary association (such as +A or -A) 5. Addition and subtraction (in order, from left to right) 6. Logical evaluation (in order, from left to right) 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.)

3.9 Parametric Functions

A parametric function is a programmed sequence of mathematical operations which returns a single value, such as SIN(X), SQRT(B), and LOG(13.2). The following tables provide a complete list of functions currently available in ANSYS. Standard FORTRAN 77 Functions ABS(x) SIGN(x,y) EXP(x) LOG(x) LOG10(x) SQRT(x) NINT(x) MOD(x,y) Absolute value of x. Absolute value of x with sign of y. y=0 results in positive sign. Exponential of x (ex). Natural log of x (ln (x)). Common log of x (log10(x)). Square root of x. Nearest integer to x. Remainder of x/y. y=0 returns zero (0). Random number (uniform distribution) in the range x to y (x = lower bound, y = upper bound). 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 with *AFUN.

RAND(x,y)

GDIS(x,y)

SIN(x), COS(x), TAN(x)

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 default, but can be changed to degrees with *AFUN. Range of output is -pi to +pi. Numerical value of CPARM (if CPARM is anumeric, returns 0.0).

ATAN2(y,x)

VALCHR (CPARM)

CHRVAL (PARM)

Character value of numerical parameter PARM. Number of decimal places depends on magnitude. Upper case equivalent of CPARM. Lower case equivalent of CPARM.

UPCASE (CPARM) LWCASE (CPARM)

The following are examples of parametric functions: PI=ACOS(-1) Z3=COS(2*THETA)-Z1**2 R2=SQRT(ABS(R1-3)) X=RAND(-24,R2) *AFUN,DEG THETA=ATAN(SQRT(3)) PHI=ATAN2(-SQRT(3),-1) *AFUN,RAD ! PI = arc cosine of -1, PI calculated to machine accuracy

! X = random number between -24 and R2 ! ! ! ! Units for angular functions are degrees THETA evaluates to 60 degrees PHI evaluates to -120 degrees Units for angular functions reset to radians

X249=NX(249) ! X-coordinate of node 249 SLOPE=(KY(2)-KY(1))/(KX(2)-KX(1)) ! Slope of line joining keypoints 1 and 2 CHNUM=CHRVAL(X) UPPER=UPCASE(LABEL) ! CHNUM = character value of X ! UPPER = uppercase character value of parameter LABEL

3.10 Saving, Resuming, and Writing Parameters

If you must use currently defined parameters in another ANSYS session, you can write them to a file and then read (resume) that file. When you read the file, you can either completely replace currently defined parameters or simply add to them (replacing those that already exist). 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 *SET,B *SET,C *SET,_RETURN *SET,_STATUS *SET,_ZX /GO

, 10.00000000000 , 254.3948750000 ,'string ' , 0.0000000000000E+00 , 1.000000000000 ,' '

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.

3.11 Array Parameters

In addition to scalar (single valued) parameters, you can define array (multiple valued) parameters. ANSYS arrays can be
G G G

One-dimensional (a single column) Two-dimensional (rows and columns) Three-dimensional (rows, columns, and planes)

ANSYS provides three types of arrays 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.

3.11.1 Array Parameter Basics

Consider a two-dimensional array (either ARRAY or CHAR) as shown below. It is m rows long and n columns wide; that is, its dimensions are m times n. Each row is identified by a row index number i, which varies from 1 to m, and each column is identified by a column index number j, which varies from 1 to n. The quantities that make up the array are array elements. Each array element is identified as (i,j), where i is its row index number and j is its column index number. Figure 3-1 A Graphical Representation of a Two-Dimensional Array.

We can extend these definitions to a three-dimensional array parameter, which may be m rows long, n columns wide, and p planes deep. The plane index number is k, which varies from 1 to p. Each array element is identified as (i,j,k). The following figure shows a three-dimensional array. Figure 3-2 A Graphical Representation of a Three-Dimensional Array.

3.11.2 Array Parameter Examples

Type ARRAY parameters consist of discrete numbers that are simply arranged in a tabular fashion for convenience. Consider the following examples.

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:

3.11.3 TABLE Type Array Parameters

A type TABLE array parameter consists of numbers (alphanumeric values are not valid) arranged in a tabular fashion, much like the ARRAY type. However, there are three important differences
G

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.

Figure 3-3 A Graphical Representation of a Table Array

As shown in the above example, when configuring a table array you must set
G G

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.

3.11.4 Defining and Listing Array Parameters

To define an array parameter, you must first declare its type and dimensions using the *DIM command (Utility Menu>Parameters>Array Parameters>Define/Edit). This following examples illustrate the *DIM command used to dimension various types of arrays: *DIM,AA,,4 *DIM,XYZ,ARRAY,12 *DIM,FORCE,TABLE,5 *DIM,T2,,4,3 *DIM,CPARR1,CHAR,5 ! ! ! ! ! Type ARRAY is default, dimension 4[x1x1] Type ARRAY array, dimension 12[x1x1] Type TABLE array, dimension 5[x1x1] Dimensions are 4x3[x1] Type CHAR array, dimension 5[x1x1]

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.

3.11.5 Specifying Array Element Values

You can specify array element values by
G G

G G

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).

3.11.5.1 Specifying Individual Array Values

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 T2(1,2)=7,5,9.1,62.5 T2(1,3)=2E-4,-3.5,22,.01

! defines (1,1),(2,1),(3,1),(4,1) ! defines (1,2),(2,2),(3,2),(4,2) ! 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: *DIM,RESULT,CHAR,3 !Character array parameter with ! dimensions (3,1,1) !Assigns values to parameter RESULT

RESULT(1)='SX','SY','SZ'

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).

3.11.5.2 Filling Array Vectors

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. *DIM,DTAB,ARRAY,4,3 *VFILL,DTAB(1,1),DATA,-3,8,-12,57 *VFILL,DTAB(1,2),RAMP,2.54,2.54 *VFILL,DTAB(1,3),RAND,1.5,10 ! ! ! ! ! ! ! dimension 4 x 3 numeric array four data values loaded into vector 1 fill vector 2 with values starting at 2.54 and incrementing by 2.54 fill vector 3 with random numbers between 1.5 and 10. Results will vary due to random number generation.

3.11.5.3 Interactively Editing Arrays

The *VEDIT command (Utility Menu>Parameters>Array Parameters>Define/Edit), which is available only in interactive mode, launches a data entry dialog box you can use to edit an ARRAY or TABLE (not CHAR) array. The dialog box provides a number of convenient features:
G G G G

A spreadsheet-style editor for array element values. Navigational controls for scrolling through large arrays. An initialize function to set any row or column to a specified value (ARRAY type only). Delete, copy, and insert functions for moving rows or columns of data (ARRAY type only).

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.

3.11.5.4 Filling an Array From a Data File Using *VREAD

You can fill an array from a data file using the *VREAD command (Utility Menu>Parameters>Array Parameters>Read from File). The command reads information from an ASCII data file and begins writing it into the array, starting with the index location that you specify. You can control the format of the information read from the file through data descriptors. The data descriptors must be enclosed in parenthesis and placed on the line following the *VREAD command. See Section 3.11.7.1 for more information about data descriptors. The data descriptors control the number of fields to be read from each record, the width of the data fields, and the position of the decimal point in the field. For example, given the following data file: 1.5 15.6 7.8 -45.6 12.3 42.5

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.

3.11.5.5 Filling a TABLE Array From a Data File Using *TREAD

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. When reading data from an external file, remember:
G

G G

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 Temperature Table Time Temp 0 1 2 4 20 30 70 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 Example 2: 2-D Table 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: Temp (time-X-coord) Table

Time 0 0 1 2 4 0 10 15 20 30

X-Coordinate .3 15 20 25 40 .5 20 25 35 70 .7 25 35 55 90 .9 30 40 60 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 Example 3: 3-D Table For this example, create a 3-D table named "T3data" containing temperature data as a function of time, x-coordinate, and ycoordinate and read it into a TABLE array parameter called "Ttxy." The table, in its ASCII form, would look like this: Temp (time-X-coord) Table Time 0 0 0 X-Coordinate .3 .5 20 .7 25 .9 30

10 15

1 2 4 1.5 0 1 2 4

15 20 20 25 30 40 0 .3

25 35 70 .5 30 35 45 80

35 55 90 .7 35 45 65 100

40 60 100 .9 40 50 70 120

20 25 25 30 30 35 40 50

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

3.11.6 Interpolating Values

When accessing information from the array, ANSYS will interpolate values between those explicitly set. 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
G G G

A(1.5) evaluates to 20.0 (halfway between 12.0 and 28.0) A(1.75) evaluates to 24.0 A(1.9) evaluates to 26.4

Similarly, if PQ is a TABLE array parameter

G G G

PQ(1.5,1) evaluates to -3.4 (halfway between 2.8 and -9.6) PQ(1,1.5) evaluates to 3.5 (halfway between 2.8 and 4.2) PQ(3.5,1.3) evaluates to 14.88

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 timehistory forcing function described by five points as shown below. Figure 3-4 Time-History Forcing Function

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.

3.11.6.1 Retrieving Values into or Restoring Array Parameter Values

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 xlocation 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.

3.11.5.2 Listing Array Parameters

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 STATUSABBREV SAVE_DB RESUM_DB QUIT POWRGRPH ANSYSWEB STRING SAVE RESUME Fnc_/EXIT Fnc_/GRAPHICS Fnc_HomePage ( (INCLUDING NAME VALUE TYPE 5 PARAMETERS DEFINED) 2 INTERNAL PARAMETERS) DIMENSIONS

PARAMETER STATUS-

MYCHAR MYPAR MYPAR1

hi .987350000

CHARACTER ARRAY SCALAR

*STATUS,XYZ(1),5,9 PARAMETER STATUS- XYZ LOCATION 5 1 6 1 7 1 8 1 9 1

! Lists rows 5 through 9 of XYZ ( 4 PARAMETERS DEFINED) VALUE -8.98000000 9.01000000 -30.6000000 51.0000000 -51.9000000 ! Lists parameter FORCE, includes j=0 column ( 4 PARAMETERS DEFINED)

1 1 1 1 1

*STATUS,FORCE(1),,,0 PARAMETER STATUS- FORCE LOCATION 1 0 2 0 3 0 4 0 5 0 1 1 2 1 3 1 4 1 5 1 *STATUS,T2(1,1) PARAMETER STATUS- T2 LOCATION 1 1 2 1 3 1 4 1 1 2 2 2 3 2 4 2 1 3 2 3 3 3 4 3 *STATUS,RESULT(1)

1 1 1 1 1 1 1 1 1 1

VALUE 0.000000000E+00 0.800000000 7.20000000 8.50000000 9.30000000 0.000000000E+00 560.000000 560.000000 238.500000 0.000000000E+00 ! Lists parameter T2 ( 4 PARAMETERS DEFINED)

1 1 1 1 1 1 1 1 1 1 1 1

VALUE 0.600000000 2.00000000 -1.80000000 4.00000000 7.00000000 5.00000000 9.10000000 62.5000000 2.000000000E-04 -3.50000000 22.0000000 1.000000000E-02 !Lists parameter RESULT

PARAMETER STATUS- RESULT LOCATION

( 4 PARAMETERS DEFINED) VALUE

1 2 3

1 1 1

1 1 1

SX SY SZ

(CHAR) (CHAR) (CHAR)

3.11.7 Writing Data Files

You can write formatted data files (tabular formatting) from data held in arrays through the *VWRITE command. The command takes up to 10 array vectors as arguments and writes the data contained in those vectors to the currently open file (*CFOPEN command). The format for each vector is specified with FORTRAN 77 data descriptors on the line following the *VWRITE command (therefore you can't issue the *VWRITE command from the ANSYS input window.) 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.

3.11.7.1 Format Data 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 w Is the width of the data field in characters. d Is the number of digits to the right of the decimal point. 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 macro creates the following data file: 1. 2. 3. 4. 5. 6. 2.1522 2.3049 2.0105 2.3683 2.8491 2.2280 3.9 4.0 3.4 3.3 4.8 3.5 5.286370 5.409196 5.936638 5.632203 5.978024 5.546851 10.2 10.2 10.2 10.2 10.2 10.2 25. 25. 25. 25. 25. 25. 5.2 5.2 5.2 5.2 5.2 5.2

The second example uses the following previously dimensioned and filled array:

Note the use of descriptors in the following example *VWRITE command: *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,' ?') The resulting data file is Row 1. contains Row 2. contains Row 3. contains 10.000 50.000. 20.000 60.000. 30.000 70.000. Is their sum Is their sum Is their sum 60.000 ? 60.000 ? 60.000 ?

3.11.8 Operations Among Array Parameters

Just as parametric expressions and functions allow operations among scalar parameters, a series of commands is available to perform operations among array parameters. There are classes of operations: operations on columns (vectors), known as vector operations and operations on entire matrices (arrays), known as matrix operations. All operations are affected by a set of specification commands, which are discussed in Section 3.11.8.3.

3.11.8.1 Vector Operations

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 *VOPER or Utility Menu>Parameters>Array Operations>Vector Operations Performs an operation on two input array vectors and produces a single output array vector. *VFUN or Utility Menu>Parameters>Array Operations>Vector Functions Performs a function on a single input array vector and produces a single output array vector. *VSCFUN or Utility Menu>Parameters>Array Operations>Vector-Scalar Func Determines the properties of a single input array vector and places the result in a specified scalar parameter. *VITRP or Utility Menu>Parameters>Array Operations>Vector Interpolate 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)

3.11.8.2 Matrix Operations

Matrix operations are mathematical operations between numerical array parameter matrices, such as matrix multiplication, calculating the transpose, and solving simultaneous equations. Commands discussed in this section include

*MOPER or Utility Menu>Parameters>Array Operations>Matrix Operations Performs matrix operations on two input array parameter matrices and produces one output array parameter matrix. Matrix operations include
G G G G G

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

*MFUN or Utility Menu>Parameters>Array Operations>Matrix Functions Copies or transposes an array parameter matrix (accepts one input matrix and produces one output matrix). *MFOURI or Utility Menu>Parameters>Array Operations>Matrix Fourier Calculates the coefficients for or evaluates a Fourier series. 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) The following array values result from the *MOPER command:

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 C array now contains the following solutions.

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) The following shows the results in the DATATRAN array:

3.11.8.3 Specification Commands for Vector and Matrix Operations

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. The following lists the available array specification commands: *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 noncumulative 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 Lists the current specifications for the array parameters. *VLEN or Utility Menu>Parameters>Array Operations>Operation Settings Specifies the number of rows to be used in array parameter operations. *VMASK or Utility Menu>Parameters>Array Operations>Operation Settings Specifies an array parameter as a masking vector. The following table lists the various specification commands and the vector and matrix array commands that they affect. *VLEN *VABS *VFACT *VCUM *VCOL NROW,NINC *VMASK

*MFOURI No *MFUN Yes

No Yes Yes Yes Yes Yes Yes Yes No Yes Yes Yes No

No Yes Yes Yes Yes Yes Yes Yes N/A No Yes Yes N/A

N/A No No N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A

No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

No No No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

*MOPER Yes *VFILL *VFUN *VGET *VITRP *VOPER *VPLOT *VPUT *VREAD Yes Yes Yes Yes Yes No Yes Yes

*VSCFUN Yes *VWRITE 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) or, you can use a slightly shorter version numdp=2 *vfact,10**numdp *vfun,numdata(1),copy,numdata(1) *vfact,10**(-numdp) *vfun,numdata(1),nint,numdata(1) The resultant NUMDATA array is then

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 PARAMETER STATUS- NUMBERS ( (INCLUDING 5 PARAMETERS DEFINED) 2 INTERNAL PARAMETERS)

LOCATION 1 1 2 1 3 1 4 1 5 1 6 1 7 1 8 1 9 1 10 1

1 1 1 1 1 1 1 1 1 1

VALUE 0.000000000E+00 2.00000000 3.00000000 0.000000000E+00 5.00000000 0.000000000E+00 7.00000000 0.000000000E+00 0.000000000E+00 0.000000000E+00

3.11.9 Plotting Array Parameter Vectors

You can graphically display array vector values using the *VPLOT command. 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. The plot (below) resulted from the following command. *vplot,,arrayval(1,1),2 Figure 3-6 Example Plot

The plot (below) resulted from the following command. *vplot,,tableval(1,1),2 Figure 3-7 Example Plot

The plot (below) resulted from the following command. *vplot,table2(1),tableval(1,1),2 Figure 3-8 Example Plot

The plot (below) resulted from the following command. *vplot,tableval(1,0),tableval(1,1),2 Figure 3-9 Example Plot

Go to the beginning of this chapter

Chapter 4: APDL as a Macro Language

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6

4.1 What is an APDL Macro?

You can record a frequently used sequence of ANSYS commands in a macro file (these are sometimes called command files). Creating a macro enables you to, in effect, create your own custom ANSYS command. For example, calculating power loss due to eddy currents in a magnetic analysis would require a series of ANSYS commands in the postprocessor. By recording this set of commands in a macro, you have a new, single command that executes all of the commands required for that calculation. In addition to executing a series of ANSYS commands, a macro can call GUI functions or pass values into arguments. 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 or (because the extension is .mac) 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.

4.2 Creating a Macro

You can create macros either within ANSYS itself or using your text editor of choice (such as emacs, vi, or wordpad). If your macro is fairly simple and short, creating it in ANSYS can be very convenient. If you are creating a longer, more complex macro or editing an existing macro then you'll need a text editor. Also, using a text editor allows you to use a similar macro or ANSYS log file as the source for your macro. 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.

4.2.1 Macro File Naming Conventions

Macros are nothing more than a sequence of ANSYS commands stored in a file. Macros should not have the same name as an existing ANSYS command; ANSYS will execute the internal command instead of the macro. The following naming restrictions apply to macro files:
G G G

G G

The file name cannot exceed 32 characters. The file name cannot begin with a numeral. The file extension cannot contain more than eight characters (if you are executing the macro as if it were an ANSYS command it should have the extension .mac.) The file name or extension cannot contain spaces. The file name or extension cannot contain any characters prohibited by your file system and for portability shouldn't contain any characters prohibited by either UNIX or Windows file systems.

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.

4.2.2 Macro Search Path

By default, ANSYS searches for a user macro file (.mac extension) in the following locations: 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.
G

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.

4.2.3 Creating a Macro Within ANSYS

You can create a macro by three methods from within ANSYS
G

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.

The following sections detail each of these methods.

4.2.3.1 Using *CREATE

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 To close the macro file, issue the *CFCLOS command. 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.

4.2.3.3 Using Utility Menu>Macro>Create Macro

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.

4.2.4 Creating Macros with a Text Editor

You can use your favorite text editor to create or edit macro files. Any ASCII editor will work. Moreover, ANSYS macros can have their lines terminated by either UNIX or Windows line ending conventions (carriage-return, line-feed pairs or simply line-feeds) so you can create a macro on one platform and use it on several platforms. If you use this method to create macros, don't include the *CREATE and *END commands. Figure 4-3 A Simple Macro Created in a Text Editor.

4.2.5 Using Macro Library Files

As a convenience, ANSYS allows you to place a set of macros in a single file, called a macro library file. You can create these either through the *CREATE command or through a text editor. Given that macro libraries tend to be longer than single macros, using a text editor normally provides the best approach. 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.

4.3 Executing Macros and Macro Libraries

You can execute any macro file by issuing the *USE command. For example, to execute the macro called MYMACRO (no extension) residing somewhere in the macro search path, you would issue *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.

4.4 Local Variables

APDL provides two sets of specially named scalar parameters which are available for use as local variables. These consist of
G G

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.

The following sections discuss both of these variable types in detail.

4.4.1 Passing Arguments to a Macro

There are 19 scalar parameters that you can use to pass arguments from the macro execution command line to the macro. These scalar parameters can be reused with multiple macros; that is, their values are local to each macro. The parameters are named ARG1 through AR19 and they can be used for any of the following items:
G G G G

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 To execute this macro, a user might enter mymacro,4,3,2.2,1

4.4.2 Local Variables Within Macros

Each macro can have up to 79 scalar parameters used as local variables (AR20 through AR99). These parameters are completely local to the macro, and multiple macros can each have their own unique values assigned to these parameters. These parameters are not passed to macros called from macros (nested macros). They are passed to any files processed through a /INPUT command or a "do loop" processed within the macro.

4.4.3 Local Variables Outside of Macros

ANSYS also has a similar set of ARG1 through AR99 scalar parameters that are local to an input file, and are not passed to any macros called by that input file. Thus, once a macro finishes and execution returns to an input file, the values of ARG1 through ARG99 revert to whatever values were defined within the input file.

4.5 Controlling Program Flow in APDL

When executing an input file, ANSYS is normally restricted to linear program flow; that is, each statement is executed in the order that it is encountered in the listing. However, APDL provides a rich set of commands that you can use to control program flow.
G G G G G

Call subroutines (nested macros). Branch unconditionally to a specified location with a macro. Branch based upon a condition to a specified location within a macro. Repeat the execution of a single command, incrementing one or more command parameters. Loop through a section of a macro a specified number of times.

The following sections detail each of these program control capabilities. For the exact syntax of the commands, refer to the ANSYS Commands Reference.

4.5.1 Nested Macros: Calling Subroutines Within a Macro

APDL allows you to nest macros up to 20 levels deep, providing functionally similar capability to a FORTRAN 77 CALL statement or to a function call. You can pass up to 19 arguments to the macro and, at the conclusion of each nested macro, execution returns to the level that called the macro. For example, the following extremely simply macro library file shows the MYSTART macro, which calls the MYSPHERE macro to create the sphere. mystart /prep7 /view,,-1,-2,-3 mysphere,1.2 finish /eof

mysphere sphere,arg1 /eof

4.5.2 Unconditional Branching: Goto

The simplest branching command, *GO, instructs the program to go to a specified label without executing any commands in between. Program flow continues from the specified label. For example *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.

4.5.3 Conditional Branching: The *IF Command

APDL allows you to execute one of a set of alternative blocks based on the evaluation of a condition. The conditions are evaluated by comparing two numerical values (or parameters that evaluate to numerical values). The *IF command has the following syntax *IF, VAL1, Oper, VAL2, Base Where
G G G G

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 Equal (for VAL1=VAL2). NE Not equal (for VAL1#VAL2).

LT Less than (for VAL1<VAL2). GT Greater than (for VAL1>VAL2). LE Less than or equal (for VAL1vVAL2). GE Greater than or equal (for VAL1>=VAL2). ABLT Absolute values of VAL1and VAL2before <operation. ABGT Absolute values of VAL1and VAL2before >operation. 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
G G G G

An *IF command, followed by One or more optional *ELSEIF commands An optional *ELSE command A required *ENDIF command, marking the end of the construct.

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.

4.5.4 Repeating a Command

The simplest looping capability, the *REPEAT command, allows you to execute the directly preceding command a specified number of times, incrementing any field in that command by a constant value. In the example 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.

4.5.5 Looping: Do-Loops

A do-loop allows you to loop through a series of commands a specified number of times. The *DO and *ENDDO commands mark the beginning and ending points for the loop. *DO command has the following syntax:

The following example do-loop edits five load step files (numbered 1 through 5) and makes the same changes in each file. *DO,I,1,5 LSREAD,I OUTPR,ALL,NONE ERESX,NO LSWRITE,I *ENDDO ! For I = 1 to 5: ! Read load step file I ! Change output controls ! Rewrite load step file I

You can add your own loop controls by using the *IF, *EXIT, or *CYCLE commands. Keep the following guidelines in mind when constructing do-loops.
G G G

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 doloop 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.

4.6 Control Functions Quick Reference

The table below describes APDL commands that perform control functions within macros. 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. APDL Command Action It Takes Usage Tips Command format is *DO,Par,IVAL,FVAL,INC, where: Par is a scalar parameter to be used as the loop index. IVAL and FVAL are the initial and final parameter values. INC is the amount by which IVAL is incremented at each loop execution. You also can control looping via the *IF command. ANSYS allows up to 20 levels of nested "do" loops, although "do" loops that include /INPUT, *USE, or an "unknown" command macro support fewer nesting levels because they do internal file switching. *DO, *ENDDO, *CYCLE, and *EXIT commands in a "do" loop must all read from the same file or the

*DO

Defines the start of a "do" loop. The commands following the *DO command execute (up to the *ENDDO command) repeatedly until some loop control is satisfied.

keyboard. Don't include picking operations in a "do" loop. Take care if you include a /CLEAR command within a doloop. 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. You must use one *ENDDO command for each nested "do" loop. The *ENDDO and *DO commands for a loop must be on the same file.

*ENDDO

Ends a "do" loop and starts the looping action.

*CYCLE

When executing a "do" loop, the ANSYS program bypasses all commands between the *CYCLE command and the *ENDDO command, then (if applicable) initiates the next loop.

You can use the cycle option conditionally (via the *IF command). The *CYCLE command must appear on the same file as the *DO command and must appear before the *ENDDO command.

*EXIT

Exits from a "do" loop.

The command following the *ENDDO command executes next. The *EXIT and *DO commands for a loop must be on the same file. You can use the exit option conditionally (via the *IF command). Command format is *IF,VAL1,Oper,Val2,Base, where: VAL1 is the first numeric value (or parameter that evaluates to a numeric value) in the conditional comparison. Oper is the operation label: EQ (equal), NE (not equal), LT (less than), GT (greater than), LE (less than or equal), GE (greater than or equal), ABLT (absolute values of VAL1 and VAL2 before < operation) or ABGT (absolute values of VAL1 and VAL2 before > operation). VAL2 is the second numeric value (or numeric parameter value) in the conditional comparison. Base is an action based on the logical operation being true. (If it's false, the next line in the block is read.) Possible actions are: - :label (skips to the first line starting with the matching label) - STOP (exits from the ANSYS program)

*IF

Causes commands to be read conditionally.

- EXIT (exits the current "do" loop)

- CYCLE (skips to the end of the current "do" loop - THEN (makes this IF an if-then-else construct) You can have up to 10 nested levels of *IF blocks. You can't jump into, out of, or within a "do" loop or an if-then-else construct to a :label line, and jumping to a :label line isn't allowed with keyboard entry. 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. Terminates an if-then-else construct. (See the *IF discussion for details.) Creates a final, optional block separator within an if-then-else construct. (See the *IF discussion for details.)

*ENDIF

The *IF and *ENDIF commands must appear in the same file.

*ELSE

The *ELSE and *IF commands must appear in the same file.

Command format is *ELSEIF,VAL1,Oper,VAL2, where: VAL1 is the first numeric value (or parameter that evaluates to a numeric value) in the conditional comparison. Oper is the operation label: EQ (equal), NE (not equal), LT (less than), GT (greater than), LE (less than or equal), GE (greater than or equal), ABLT (absolute values of VAL1 and VAL2 before < operation) or ABGT (absolute values of VAL1 and VAL2 before > operation). VAL2 is the second numeric value (or numeric parameter value) in the conditional comparison. If Oper=EQ or NE, VAL1 and VAL2 can also be character strings (enclosed in quotes) or parameters. The *IF and *ELSEIF commands must be on the same file.

Creates an optional, *ELSEIF intermediate block separator within an if-then-else construct.

4.7 Using the _STATUS and _RETURN Parameters in Macros

The ANSYS program generates two parameters, _STATUS and _RETURN, that you can also use in your macros. For example, you might use the _STATUS or _RETURN value in an "if-then-else" construct to have the macro take some action based on the outcome of executing an ANSYS command or function. 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: Command Function Keypoints K KL KNODE KBET KCENT Lines BSPLIN CIRCLE L L2ANG LANG LARC LAREA LCOMB Generate spline Generate circular arc lines Line between two keypoints Line at angle with two lines Line tangent to two lines Defines a circular arc Line between two keypoints Combine two lines into one Line number First line number Line number Line number Line number Line number Line number Line number Defines a keypoint Keypoint on line Keypoint at node Keypoint between two keypoints Keypoint at center Keypoint number Keypoint number Keypoint number KP number KP number _RETURN Value

LDIV LDRAG LFILLT LRCS

Divide line into two or more lines First keypoint number Line by keypoint sweep Fillet line between two lines First line number Fillet line number

Rotate point around two keypoints Line number First line number Line number Line number Line number First line number

LROTATE Arc by keypoint rotation LSPA LSTR LTAN SPLINE Areas A ACCAT ADRAG AFILLT AL ALLP AOFFST AROTAT ASKIN ASUB Volumes Area connecting keypoints Concatenate two or more areas Drag lines along path Fillet at intersection of two areas Area bounded by lines All loops Area offset from given area Rotate lines around axis Project line segment on an area Straight line Line at end and tangent Segmented spline

Area number Area number First area number Fillet area number Area number Area number Area number First area number

Skin surface through guiding lines First area number Area using shape of existing area Area number

V VA VDRAG VEXT VOFFST

Volume through keypoints Volume bounded through areas

Volume number Volume number

Drag area pattern to create volume First volume number Volume by extruding areas Volume offset from given area First volume number Volume number First volume number

VROTATE Volume by rotating areas

Executing an ANSYS command, whether in a macro or elsewhere, generates the parameter _STATUS. This parameter reflects the error status of that command:
G G G G

0, for no error 1, for a note 2, for a warning 3, for an error

4.8 Using Macros with Components and Assemblies

To make large models easier to manage, you may wish to divide a model into discrete components based on different types of entities: nodes, elements, keypoints, lines, areas, or volumes. Each component can contain only one type of entity. Doing this enables you to perform tasks such as applying loads or producing graphics displays conveniently and separately on different portions of the model. 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: Cname - a component name, which contains up to eight characters and must begin with a letter Entity - a four-character label identifying the type of geometry items to be grouped. Possible values are VOLU, AREA, LINE, KP (keypoints), ELEM, and NODE. Deletes a component or assembly. The Name argument identifies the entity to be deleted. Edits an existing component or assembly. The ANSYS program updates assemblies automatically to reflect deletions of lower-level or assemblies. Command arguments are: Aname - the name of the assembly to edit CMEDIT, Aname,Oper,Cnam1,... Cnam7 Oper - an operation label (ADD to add components, or DELE to remove components) Cnam1,...Cnam7 - the names of components and assemblies to be added to or deleted from the assembly. You must separate the component or assembly names with commas. Groups components and assemblies into one assembly. Once defined, an assembly can be listed, deleted, selected, or unselected using the same commands as for a component. Arguments are: CMGRP, Aname,Oper,Cnam1,... Aname - the name of the assembly. The name can have up to eight characters and must begin with a letter. Cnam8 Cnam1,...Cnam8 - the names of existing components and assemblies to be included in this assembly. You must separate the component or assembly names with commas. You can specify up to five levels of assemblies within an assembly. Lists the entities contained in a component or assembly. Name is the name of the component or assembly to be listed. If you specify no Name, the program lists all components and assemblies.

CM,Cname,Entity

CMDELE,Name

CMLIST,Name

Selects a subset of components and assemblies. Type is a label identifying the type of select operation: 1. S - select a new set; default 2. R - Reselect a set CMSEL,Type,Name 3. A - Additionally select a set and extend the current set 4. U - Unselect a set 5. ALL - Select all components 6. NONE - Unselect all components

4.9 Reviewing Example Macros

Following are two example macros. The example macro below, called offset.mac, offsets selected nodes in the PREP7 preprocessor. This macro is for demonstration purposes only as the NGEN command provides a more convenient method. ! ! ! /nop *get,nnode,node,,num,max *dim,x,,nnode *dim,y,,nnode *dim,z,,nnode *dim,sel,,nnode *vget,x(1),node,1,loc,x *vget,y(1),node,1,loc,y *vget,z(1),node,1,loc,z *vget,sel(1),node,1,nsel *voper,x(1),x(1),add,arg1 *voper,y(1),y(1),add,arg2 *voper,z(1),z(1),add,arg3 ! *do,i,1,nnode ! *if,sel(i),gt,0,then ! n,i,x(i),y(i),z(i) ! *endif ! *enddo ! ***** NEW FORM AT 5.3 ***** Macro to offset selected nodes in PREP7 The below file is saved as: offset.mac (must be lowercase) Usage: offset,dx,dy,dz ! suppress printout for this macro ! get number of nodes ! set up arrays for node locations

! set up array for select vector ! get coordinates

! get selected set ! offset locations

! store new positions ! this form takes 98 sec for 100,000 nodes

*vmask,sel(1) ! this form takes 3 seconds for 100,000 nodes ! NOTE: AT 5.3 NNODE MUST be caps in the following: n,(1:NNODE),x(1:NNODE),y(1:NNODE),z(1:NNODE) x(1) = y(1) = z(1) = sel(1) = i= nnode= /go ! delete parameters (cleanup)

! resume printout

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 *if,_niter,lt,2,then _Niter = 2 *endif *do,iter,1,_niter /post1 set,1,1 ar11,=elmiqr(0,14) *dim,_s1,,ar11 *dim,_s3,,ar11 etable,sigmax,s,1 etable,sigmin,s,3 *vget,_s1(1),elem,1,etab,sigmax *vget,_s3(1),elem,1,etab,sigmin *dim,_mask,,ar11 *voper,_mask(1),_s1(1),lt,0 *vcum,1 *vabs,0,1 *voper,_mask(1),_s3(1),gt,_s1(1) finish /prep7 mat,1 emod,all *vput,_mask(1),elem,1,esel mat,2 emod,all call finish _s1(1)= _s3(1)= _mask(1)= /solve

! set number of iterations

! loop on number of iterations

! ! ! ! ! ! ! ! ! ! ! !

call elmiqr function to get no. of elements array for element s1 array for element s3 s1 is in element table sigmax s3 is in element table sigmin get element maximum stress in s1 get element minimum stress in s3 array for mask vector true if max. stress < 0 accumulate compression elements absolute value of s3 true if abs(minstr) > maxstr

! go to prep7 for element material mods ! set all materials to tension properties

! select compression elements ! change selected elements to compression

! select all elements

! clean up all vectors (set to zero)

! rerun the analysis

solve finish *enddo _niter= _iter= /gop ! end of iterations ! clean up iteration counters

Go to the beginning of this chapter

5 Interfacing With the GUI

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6

Within an ANSYS macro, you have several ways to access components of the ANSYS graphical user interface (GUI):
G G G G G G G

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.

5.1 Prompting Users For a Single Parameter Value

By including the *ASK command within a macro, you can have the macro prompt a user to type in a parameter value. The format for the *ASK command is *ASK,Par,Query,DVAL Where
G G

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: *ask,parm1,'username (enclose the username in single quotes)'

Displays the following dialog box, then sets the parameter PARM1 to the value the user enters. Figure 5-1 An Example *ASK Dialog Box.

When you issue *ASK within a macro, ANSYS writes the user's response to File.LOG on the line following the macro name.

5.2 Prompting Users With a Dialog Box

The MULTIPRO command constructs a simple, multiple-prompt dialog box that can contain up to 10 parameter prompts. The command allows you to use a set of UIDL *CSET commands to create the prompts as well as specify a default value for each prompt. The MULTIPRO command must be used in conjunction with
G G

Between one and 10 *CSET command prompts Up to two special *CSET commands that provide a two line area for user instructions.

The command has the following syntax: 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. The following is a typical example of the MULTIPRO command. 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. Figure 5-2 A Typical 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:
G G

_BUTTON=0 indicates that the OK button was pressed. _BUTTON=1 indicates that the Cancel button was pressed.

At present, the Help button is not functional.

5.3 Using Macros to Display Your Own Messages

By issuing the *MSG command within a macro, you can display custom output messages via the ANSYS message subroutine. The command has the following format: *MSG,Lab,VAL1,VAL2,VAL3,VAL4,VAL5,VAL6,VAL7,VAL8 Where Lab is one of the following labels for output and termination control: INFO NOTE Writes the message with no heading (default). Writes the message with a "NOTE" heading.

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 this is an ANSYS batch run, this label also terminates the run at the earliest "clean exit" point.

ERROR

FATAL

Writes the message with a "FATAL ERROR" heading and also writes it to the errors file, Jobname.ERR. This label also terminates the ANSYS run immediately. Writes the message with a "NOTE" heading and displays it in the message dialog box.

UI

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:
G

G G G

%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: *MSG, INFO, 'Inner' ,25,1.2,148 Radius ( %C) = %I, Thick = %G, Length = %I The resulting output message is as follows: Radius (Inner) = 25, Thick = 1.2, Length = 148 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.

5.4 Creating and Maintaining a Status Bar from a Macro

Within macros, you can insert commands to define an ANSYS dialog box containing a status bar displaying the

progress of an operation, a STOP button you can click on to stop the operation, or both. To define a status dialog box, issue the following command: *ABSET,Title40,Item
G

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: Displays the status bar with no STOP button

BAR

KILL Displays a STOP button with no status bar BOTH Displays both the status bar and STOP button To update the status bar, issue the command *ABCHECK,Percent,NewTitle.
G G

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 Note-Do not call *ABCHECK more than about 20 times in a loop. Figure 5-3 A Typical Status Dialog Box, Showing The Status Bar And Stop Button.

5.5 Picking within Macros

If you're running the ANSYS program interactively, you can call a GUI picking menu from within a macro. To do so, simply include a picking command in the macro. Many ANSYS commands (such as K,,P) accept the input "P" to enable graphical picking. When ANSYS encounters such a command, it displays the appropriate picking dialog and then continues macro execution when the user clicks OK or Cancel. 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.

5.6 Calling Dialog Boxes From a Macro

When the ANSYS program encounters a dialog box UIDL function name (such as Fnc_UIMP_Iso), it displays the appropriate dialog box. Thus, you can launch any ANSYS dialog box by simply making its function name a separate line in the macro file. When you dismiss that dialog box, the program continues processing the macro starting with the next line after the function call. You can find a complete list of the available dialog box function names in the online help system. Refer to the Utility Menu > Help > Using the GUI > Menu Tree Structure

menu item. 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.

Go to the beginning of this chapter

Chapter 6: Encrypting Macros

Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6

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.

6.1 Preparing a Macro for Encryption

Before encrypting a macro, you first create and debug the macro as usual. You then add an /ENCRYPT command as the first line and last of the macro. The /ENCRYPT command for the first line of the macro has the following syntax: /ENCRYPT,Encryption_key,File_name,File_ext,Directory_Path/ Where
G G G

Encryption_Key is an eight-character password. File_name is the name of the encrypted macro filename. File_ext is an optional file extension for the encrypted macro file. If you wish users to execute the macro as an "unknown" command, you should use the .mac extension. Directory_Path/ is the optional directory path that can contain up to 60 characters; you only need this argument if you don't want to write the encrypted macro file to your "home" directory. Note that you must make the "/" (or "\" for Windows systems) the final character of the path name (otherwise the last directory name is prepended to the file name).

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.

6.2 Creating an Encrypted Macro

After putting the /ENCRYPT commands at the top and bottom of the macro, you can proceed to create the encrypted version of the macro. To do this, simply execute the macro through ANSYS. ANSYS will create the encrypted version with the name and location you specified through the /ENCRYPT command at the top of the macro. The result should look something like this /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.

6.3 Running an Encrypted Macro

You can run an encrypted macro just as you would any other macro; simply place the encrypted macro within the macro search path. If you would prefer to run the encrypted macro without having the encryption key resident in the macro file, you can define the key as a "global encryption key" within ANSYS. To do this you must first replace the encryption key argument in the /DECRYPT

command with the parameter PASSWORD. Thus, the first line of the encrypted macro becomes /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,

Go to the beginning of this chapter

Table of Contents Preface

Conventions Used in This Guide About the Programmer's Guide Set

1 Format of Binary Data Files

1.1 What Are ANSYS Binary Files? 1.1.1 Conventions Used to Describe Binary Files 1.1.2 The Standard Header for ANSYS Binary Files 1.2 Format of the Results File 1.2.1 Nomenclature 1.2.2 Set 1 - Standard Ansys File Header 1.2.3 Set 2 - Results File Header 1.2.4 Set 3 - Analysis Information 1.2.4.1 Group 1 - Finite Element Information 1.2.4.2 Group 2 - Data Set Information 1.2.5 Set 4 - Geometry Information 1.2.5.1 Group 1 - Geometry Header 1.2.5.2 Group 2 - Element Type Information

1.2.5.3 Group 3 - Real Constant Information 1.2.5.4 Group 4 - Coordinate System Information 1.2.5.5 Group 5 - Nodal Locations 1.2.5.6 Group 6 - Element Information 1.2.6 Set 5 - Solution Information 1.2.6.1 Group 1 - Solution header 1.2.6.2 Group 2 - Solution Data 1.2.6.3 Group 2A - Header Extension 1.2.6.4 Group 2B Header Extension 1.2.6.5 Group 3 - Nodal Solution 1.2.6.6 Group 4 - Reaction Force Information 1.2.6.7 Group 5 - Master DOF List 1.2.6.8 Group 6 - Boundary Condition Index Table 1.2.6.9 Group 7 - Element Solutions Index Table 1.3 Description of the Reduced Displacement File 1.3.1 Set 1 - Standard ANSYS File Header 1.3.2 Set 2 - RDSP File Header 1.3.3 Set 3 - Analysis Information 1.3.3.1 Group 1 - Degrees Of Freedom Per Node 1.3.3.2 Group 2 - Nodal Equivalence Table 1.3.3.3 Group 3 - Time Information

1.3.3.4 Group 4 - Degree Of Freedom Set Used 1.3.3.5 Group 5 - Original Reduced Set Of Degrees Of Freedom Used 1.3.3.6 Group 6 - DOF Of Nodal Constraints 1.3.4 Set 4 - Reduced Matrices Data 1.3.4.1 Group 1 - Reduced Stiffness Matrix 1.3.4.2 Group 2 - Reduced Mass Matrix 1.3.4.3 Group 3 - Reduced Damping Matrix Or Mode Shapes 1.3.4.4 Group 4 - Frequencies Extracted From The Modal Analysis 1.3.5 Set 5 - Calculated Displacements 1.3.5.1 Group 1 - Calculated Displacements 1.3.5.2 Group 2 - Gap Restoring Forces 1.4 Description of the Reduced Complex Displacement File 1.4.1 Set 1 - Standard ANSYS File Header 1.4.2 Set 2 - RFRQ File Header 1.4.3 Set 3 - Analysis Information 1.4.3.1 Group 1 - Degrees Of Freedom Per Node 1.4.3.2 Group 2 - Nodal Equivalence Table 1.4.3.3 Group 3 - Unused Record 1.4.3.4 Group 4 - Degree Of Freedom Set Used

1.4.3.5 Group 5 - Original Reduced Set Of Degrees Of Freedom Used 1.4.3.6 Group 6 - DOF Of Nodal Constraints 1.4.4 Set 4 - Reduced Matrices Data 1.4.4.1 Group 1 - Reduced Stiffness Matrix 1.4.4.2 Group 2 - Reduced Mass Matrix 1.4.4.3 Group 3 - Reduced Damping Matrix Or Mode Shapes 1.4.4.4 Group 4 - Frequencies Extracted From The Modal Analysis 1.4.5 Set 5 - Calculated Displacements 1.4.5.1 Group 1 - Calculated Complex Displacements 1.5 Description of the Modal Results File 1.5.1 Set 1 - Standard ANSYS File Header 1.5.2 Set 2 - MODE File Header 1.5.3 Set 3 - Analysis Information 1.5.3.1 Group 1 - Degrees Of Freedom Per Node 1.5.3.2 Group 2 - Nodal Equivalence Table 1.5.3.3 Group 3 - Reduced Set Of Degrees Of Freedom Used 1.5.3.4 Group 4 - Frequencies (eigenvalues) 1.5.3.5 Group 5 - Participation Factors 1.5.3.6 Group 6 - Mode Coefficients

1.5.3.7 Group 7 - Modal Damping Coefficients 1.5.3.8 Group 8 - Mode Shapes (Eigenvectors) 1.5.3.9 Group 9 - Load Vector 1.5.3.10 Group 10 - Lumped Mass Vector 1.5.4 Set 4 - Reduced Matrices Data 1.5.4.1 Group 1 - Reduced Stiffness Matrix 1.5.4.2 Group 2 - Reduced Mass Matrix 1.5.4.3 Group 3 - Reduced Damping Matrix 1.5.4.4 Group 4 - Spectrum Data 1.6 Description of the Element Matrices File 1.6.1 Set 1 - Standard ANSYS File Header 1.6.2 Set 2 - EMAT File Header 1.6.3 Set 3 - Analysis Information 1.6.3.1 Group 1 - Time information 1.6.3.2 Group 2 - Degrees Of Freedom Per Node 1.6.3.3 Group 3 - Nodal Equivalence Table 1.6.3.4 Group 4 - Element Equivalence Table 1.6.3.5 Group 5 - First Element At A DOF Table 1.6.3.6 Group 6 - Last Element At A DOF Table 1.6.3.7 Group 7 - Element Index Table 1.6.4 Set 4 - Element Matrices Data

1.6.4.1 Group 1 - Element Matrix Header 1.6.4.2 Group 2 - DOF Index Table 1.6.4.3 Group 3 - Element Matrices 1.6.4.4 Group 4 - Element Force Vectors 1.7 Description of the Substructure Matrices File 1.7.1 Set 1 - Standard ANSYS File Header 1.7.2 Set 2 - SUB File Header 1.7.3 Set 3 - Substructure Information 1.7.3.1 Group 1 - Substructure Transformations 1.7.3.2 Group 2 - Degrees Of Freedom Per Node 1.7.3.3 Group 3 - Local DOF Set 1.7.3.4 Group 4 - Positions Of The Local DOF Set 1.7.3.5 Group 5 - DOF Set Of The Model As Defined During Generation Pass 1.7.3.6 Group 6 - Nodal Equivalence Table 1.7.3.7 Group 7 - Substructure Title 1.7.3.8 Group 8 - Unique Node List 1.7.3.9 Group 9 - Coordinates Of The Unique Nodes 1.7.3.10 Group 10 - Edge Of Substructure 1.7.3.11 Group 11 - Global DOF Set 1.7.4 Set 4 - Substructure Matrices

1.8 Description of the Triangularized Stiffness File 1.8.1 Set 1 - Standard ANSYS File Header 1.8.2 Set 2 - TRI File Header 1.8.3 Set 3 - Analysis Information 1.8.3.1 Group 1 Degrees Of Freedom Per Node 1.8.3.2 Group 2 Nodal Equivalence Table 1.8.4 Set 4 - Triangularized Matrix Data 1.8.4.1 Group 1 - A Row Of The Triangularized Matrix 1.8.4.2 Group 2 - Triangular Matrix Row Indices 1.8.4.3 Group 1 - Flag Record 1.8.4.4 Group 2 - Coefficients of the Constraint Equation 1.8.4.5 Group 3 - Triangularized Matrix Row 1.8.4.6 Group 4 - Triangular matrix row indices 1.8.4.7 Group 5 - Indicates The End Of The 5 Record Storage For This Row 1.8.5 Set 5 - Master Degree Of Freedom List 1.9 Description of the Full Stiffness-Mass File 1.9.1 Set 1 - Standard ANSYS File Header 1.9.2 Set 2 - FULL File Header 1.9.3 Set 3 - Analysis Information 1.9.3.1 Group 1 Degrees Of Freedom Per Node

1.9.3.2 Group 2 - Nodal Equivalence Table 1.9.3.3 Group 3 - Stiffness-Mass Matrices

2 Accessing Binary Data Files

2.1 Accessing ANSYS Binary Files 2.1.1 Characteristics of ANSYS Binary Files 2.1.2 Viewing Binary File Contents 2.1.3 Abbreviations 2.1.4 binini (Initializing Buffered Binary I/O Systems) 2.1.5 Function sysiqr (Retrieving the Status of a File) 2.1.6 Function biniqr (Retrieving System-Dependent Parameters) 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.1.9 Subroutine binhed (Writing the Standard ANSYS File Header) 2.1.10 Subroutine binrd (Reading Data from a Buffered File) 2.1.11 Subroutine binwrt (Writing Data to a Buffered File) 2.1.12 Subroutine exinc4 (Decoding an Integer String into a Character String) 2.1.13 Subroutine inexc4 (Coding a Character String into an Integer String) 2.1.14 Subroutine binclo (Closing or Deleting a Blocked Binary File) 2.2 Demonstration Routines 2.2.1 Program bintst (Demonstrates Dumping a Binary File and Copying It for

Comparison Purposes) 2.2.1.1 Common Variables: 2.2.2 Subroutine bintrd (Demonstrates Printing a Dump of File Contents) 2.2.3 Subroutine bintwr (Demonstrates Copying Binary File Contents) 2.2.4 Subroutine wrtsub (Demonstrates Writing an ANSYS Substructure File) 2.2.5 Subroutine rdsubs (Demonstrates Reading a Substructure File) 2.2.6 Subroutine rdfull (Demonstrates Reading and Reformatting the .FULL File) 2.3 Results File Access Routines 2.3.1 Requirements for Using the Routines 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 Using CDREAD and CDWRITE

3.1 Using the CDREAD Command 3.1.1 Tips for Reading Files with CDREAD 3.2 Using the CDWRITE Command 3.2.1 Customizing Degree of Freedom Labels: the /DFLAB Command 3.3 Coded Database File Commands 3.3.1 R Command 3.3.2 LOCAL Command 3.3.3 NBLOCK Command 3.3.4 N Command 3.3.5 EBLOCK Command 3.3.6 EN Command 3.3.7 MPTEMP Command 3.3.8 MPDATA Command 3.3.9 CP Command 3.3.10 CE Command 3.3.11 M Command 3.3.12 SFE Command 3.3.13 SFBEAM Command

4 ANSYS Graphics File Format

4.1 Modifying ANSYS Graphics Files

4.2 Pixmap Format for Graphic Display Files 4.3 Neutral Graphics File Format 4.3.1 Characters the Graphics File Uses 4.3.2 Graphics File Directives 4.3.2.1 Parameter Types for Graphics File Directives 4.3.2.2 Directive Descriptions 4.3.2.3 Color Specification 4.4 Decoding a Graphics File: an Example 4.4.1 The Example Command Stream 4.4.2 Example Graphics File Contents 4.5 The PLOT33 Program

Preface Conventions Used in This Guide

This guide uses the following typographic conventions to indicate various types of information: Convention Indicates ANSYS commands. These are shown as uppercase, bold text (for example, K, DDELE, etc.). In the online documentation, these provide hyperlinks to the appropriate command reference information. Menu paths (sometimes referred to as GUI paths). These are shown as bold text with mixed-case, separated by angle brackets ">". An angle bracket indicates a branch to a new menu item. File names, which may or may not include directory paths. These are shown as lower-case, bold text, unless case is significant. Examples are shown with the UNIX directory separator character "/" (slash); if you are using a Microsoft Windows system, use "\" (backslash) as your directory separator character. Arguments for numeric values (such as VALUE, INC, TIME) in command syntax. These are shown as upper-case italic text. On some commands, non-numeric convenience labels (for example, ALL and P) can also be entered for these arguments. Arguments for alphanumeric values (for example, Lab or Fname) in command syntax. These are shown in mixed-case, italic letters. The guide also uses italic text for emphasis. The name of an ANSYS manual. Command input listings, ANSYS output listings, and text that a user enters are shown in fixed-width font.

COMMAND

Menu > Item

path/filename.ext

ARGUMENT

Argument

ANSYS Guide Title

command,arg1,arg2

Note-

Information that supplements the main topic being discussed, such as important tips or guidelines. Actions or situations that could cause problems, unexpected ANSYS behavior, or unexpected results. Actions or situations that can shut down ANSYS, damage files, cause loss of data, etc.

Caution:

Warning:

About the Programmer's Guide Set

The ANSYS programmer's guide set provides information about the various programming interfaces available to customers. These manuals assume that you have at least a basic knowledge of programming (a working knowledge of Fortran 77 would be very helpful). The set of four manuals includes: The APDL Programmer's Guide 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 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. Guide To ANSYS User Programmable Features 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. Guide to Interfacing with ANSYS

This guide describes the format of the various binary data files that ANSYS creates, as well as routines supplied by ANSYS that allow you to retrieve data from these files. The chapter also discusses the CDWRITEcommand and the .cdbfile that it creates, as well as the format of the neutral graphics file. 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. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4

1.1 What Are ANSYS Binary Files?

The ANSYS program writes several binary files to store data created by solving an analysis. These files are named Jobname.ext, where Jobname is the name of the analysis that caused the file to be generated and .ext is an extension indicating the type of data in the file. ANSYS-written binary files include the following:
G

G G G G G G G

The following results files, in which the ANSYS program stores the results of solving finite element analysis problems: H Jobname.RST - A structural or coupled-field analysis H Jobname.RTH - A thermal analysis H Jobname.RMG - A magnetic analysis H Jobname.RFL - A FLOTRAN analysis The Jobname.MODE file, storing data related to a modal analysis The Jobname.RDSP file, storing data related to a reduced transient analysis The Jobname.RFRQ file, storing data related to a reduced harmonic analysis The Jobname.EMAT file, storing data related to element matrices The Jobname.SUB file, storing data related to substructure matrices The Jobname.TRI file, storing the triangularized stiffness matrix The Jobname.FULL file, storing the full stiffness-mass matrix

The files listed above cover almost all users' needs, although there are others. For more information, see the ANSYS Basic Analysis Procedures Guide.

1.1.1 Conventions Used to Describe Binary Files

In the information describing the binary file formats:
G

G G G

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.

1.1.2 The Standard Header for ANSYS Binary Files

Each of the ANSYS program's binary files contains a standard, 100-integer file header that describes the file contents. The header contains the items listed below, always in the order shown: Item 1 Item 2 Item 3 Item 4 The file number The file format. This item has a value of 0 if the file is internal, or 1 if the file is external. The time, in compact form The date, in compact form The units of measurement used. The value of this item is as follows: 0 for user-defined units 1 for SI units Item 5 2 for CSG units 3 for British units (feet)
G

4 for British units (inches)

Item 10 Item 11

The ANSYS release level in integer form ("5.4" in character form) The date of the ANSYS release

Items 12-14 The machine identifier in integer form (three four-character strings) Items 15-16 The Jobname in integer form (two 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) Item 26 Item 27 Item 28 Item 29 The system record size The maximum file length The maximum record number The number of processors assigned to this task

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)

1.2 Format of the Results File

The next few pages describe the format of the ANSYS results file for ANSYS version 5.5 or later. (In the following tables, records with a record ID containing an asterisk (*) are those you can read and store into the ANSYS database via the LDREAD command.) Note that the minimum change required to read the 5.5 or later result file format is to make sure the storage for the result data set index is 2*resmax, rather than the previous resmax and recognizing that the pointers in the data set headers are relative pointers, not absolute (e.g., ptrESL = index(i) + ptrESL [ivect(12)]). 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. A data set is used in this chapter to designate a load case. 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.

1.2.2 Set 1 - Standard Ansys File Header

See 1.1.2 for a description of this set. File number (Item 1) is 12.

1.2.3 Set 2 - Results File Header

G G G G

Record ID: N/A Type: Integer Number of records: 1 Record length: 100 items

The following lists the items found in the header by position. fun12 maxe maxn nelm nnod kan resmax numdof nsets ptrend

ptrDSI ptrTIM ptrLSP ptrELM ptrNOD ptrGEO 0 nSector 0 0 0 0 0 units 0 0

ptrend8 0 0 0

0 0 where
G G G G

0 0

0 0

0 0

0 0

G G G G G G G G G G G G G

fun12 = unit number (results file is 12) maxn = maximum node number of the model nnod = the actual number of nodes used in the solution phase resmax = the maximum number of data sets allowed on the file (defaults to 1000; minimum allowed is 10) numdof = number of DOFs per node maxe= maximum element number of the finite element model nelm = number of finite elements kan = analysis type nsets = number of data sets on the file ptrend = version 5.4 or previous files, pointer to the last record on the file ptrDSI = pointer to the data sets index table ptrTIM = pointer to the table of time values for a load step ptrLSP = pointer to the table of load step, substep, and cumulative iteration numbers ptrELM = pointer to the table of load step, substep, and cumulative iteration numbers ptrNOD = pointer to the nodal equivalence table ptrGEO = pointer to the beginning of geometry information units = unit system used: 0 - user defined units 1 - SI 2 - CSG 3 -British (using feet) 4 - British (using inches)

G G

nSector= Number of sectors for cyclic symmetry ptrEnd8 = Pointer to the end of the file (version 5.5 and later). Item 23 is the first 32 bits of this pointer and item 24 is the second 32 bits.

1.2.4 Set 3 - Analysis Information

1.2.4.1 Group 1 - Finite Element Information
1.2.4.1.1 Record 1 - Degrees Of Freedom Per Node

G G G G

Record ID: N/A Type: Integer Number of records: 1 Record length: numdof

Degree of freedom reference numbers UX=1 AX=7 UY=2 AY=8 UZ=3 AZ=9 ROTX=4 ROTY=5 ROTZ=6 AX=7 VX=10 VY =11 VZ =12 PRES=19

TEMP=20 VOLT=21 MAG=22 ENKE=23 ENDS=24 EMF=25 CURR=26 Reference numbers 13 through 18 and 27 through 32 are spares. 1.2.4.1.2 Record 2 - Nodal Equivalence Table
G G G G

Record ID: Located by the ptrNOD variable defined in Set 2 Type: Integer Number of records: 1 Record length: nnod

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) 1.2.4.1.3 Record 3 - Element Equivalence Table
G G G G

Record ID: Located by the ptrELM variable defined in Set 2. Type: Integer Number of records: 1 Record length: nelm

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.

1.2.4.2 Group 2 - Data Set Information

1.2.4.2.1 Record 1 - Data Sets Index Table
G

Record ID: Located by the ptrDSI variable defined in Set 2.

G G G

Type: Integer Number of records: 1 Record length: Equal to 2*resmax.

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. 1.2.4.2.2 Record 2 - Time/Frequency Table
G G G G

Record ID: Located by the ptrTIM variable defined in Set 2. Type: Double-precision Number of records: 1 Record length: resmax.

This record contains the time (or frequency) values for each data set. 1.2.4.2.3 Record 3 - Data Set Identifiers
G G G G

Record ID: Located by the ptrLSP variable defined in Set 2. Type: Integer Number of records: 1 Record length: Equal to 3*resmax.

This record contains the load step, substep, and cumulative iteration numbers for each data set.

1.2.5 Set 4 - Geometry Information

1.2.5.1 Group 1 - Geometry Header
G G G G

Record ID: Located by the ptrGEO variable in set 2. Type: Integer Number of records: 1 Record length: 20 items

The geometry header consists of the following 20 items:

Where:
G G G G G G G G G G G G G G G G G G G G

0 = Position not used. maxety = The maximum element type reference number in the model. maxrl = The maximum real constant reference number in the model. ndnod = The number of defined nodes in the model. nelm = The number of defined elements in the model. maxcsy = The maximum coordinate system reference number in the model. ptrETY = Pointer to the element type index table. ptrREL = Pointer to the real constant index table. ptrNLC = Pointer to the nodal point locations. ptrSYS = Pointer to the local coordinate system index table. ptrEID = Pointer to the element index table. 0 = Position not used. 0 = Position not used. 0 = Position not used. 0 = Position not used. ptrMAS = Pointer to the diagonal mass matrix. csysiz = The number of items describing a local coordinate system (usually 24). elmsiz = The maximum number of nodes that a defined element may have. etysiz = The number of items describing an element type (usually 150). rlsiz = The maximum number of items defining a real constant (0, if no real constants are defined).

1.2.5.2 Group 2 - Element Type Information

1.2.5.2.1 Record 1 - Element Types Index Table
G G G G

Record ID: Located by ptrETY. Type: Integer Number of records: 1 Record length: Defined by maxety.

This record contains record pointers for each element type description. 1.2.5.2.2 Record 2 - Element Type Description
G G

Record ID: N/A Type: Integer

G G

Number of records: Defined by numety. Record length: Defined by etysiz.

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:
G G G G G G G

Item 1 - element type reference number Item 2 - element routine number Items 3-14 - element type option keys (keyopts) Item 34 - DOF/node for this element type. This is a bit mapping of the DOF/node. Item 61 - number of nodes for this element type (nodelm) Item 63 - number of nodes per element having nodal forces, etc. (nodfor). Item 94 - number of nodes per element having nodal stresses, etc. (nodstr). This number is the number of corner nodes for higher-ordered elements.

1.2.5.3 Group 3 - Real Constant Information

1.2.5.3.1 Record 1 - Real Contstants Index Table
G G G G

Record ID: Located by ptrREL. Type: Integer Number of records: 1 Record length: Defined by maxrl.

This record contains record pointers for each real constant set. 1.2.5.3.2 Record 2 - Element Real Contstant Data
G G G G

Record ID: N/A Type: Double-precision Number of records: Defined by numrl Record length: Varies

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).

1.2.5.4 Group 4 - Coordinate System Information

1.2.5.4.1 Record 1 - Coordinate Systems Index Table
G

Record ID: Located by the ptrSYS variable.

G G G

Type: Integer Number of records: 1 Record length: Defined by maxcsy.

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. 1.2.5.4.2 Record 2 - Coordinate System Description
G G G G

Record ID: N/A Type: Double-precision Number of records: Defined by numcsy. Record length: Defined by csysiz.

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:
G G G G G G G

Items 1-9 are the transformation matrix. Items 10-12 are the coordinate system origin (XC,YC,ZC). Items 13-14 are the coordinate system parameters (PAR1, PAR2). Items 16-18 are the angles used to define the coordinate system. Items 19-20 are theta and phi singularity keys. Item 21 is the coordinate system type (0, 1, 2, or 3). Item 22 is the coordinate system reference number.

1.2.5.5 Group 5 - Nodal Locations

G G G G

Record ID: Located by ptrNLC. Type: Double-precision Number of records: 1 Record length: Equal to 7*ndnod.

This group contains the node number and coordinates (in the order X,Y,Z,THXY,THYZ,THZX) of each node.

1.2.5.6 Group 6 - Element Information

1.2.5.6.1 Record 1 - Element Descriptions Index Table
G G G G

Record ID: Located by the ptrEID variable. Type: Integer Number of records: 1 Record length: Defined by nelm.

This record contains the record pointers for each element description. 1.2.5.6.2 Record 2 - Element Descriptions
G G G G

Record ID: N/A Type: Integer Number of records: Defined by nelm. Record length: number of items equal to 10+nodelm.

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. The items stored in each record are as follows: mat, type, real, elnum, esys, death, solidm, shape, pexcl, 0, NODES. mat type real elnum esys NODES death

solidm shape pexcl 0

Each item is described below:

G G G G G G

mat - material reference number type - element type number real - real constant reference number elnum - element number esys - element coordinate system death - death flag = 0 - alive = 1 - dead

G G G G

solidm - solid model reference shape - coded shape key pexcl - P-Method exclude key NODES - node numbers defining the element.

(See the ANSYS Elements Reference for nodal order of an element). 1.2.5.6.3 Record 3 - Diagonal Mass Matrix
G

Record ID: MAS

G G G

Type: Double-precision Number of Records: 1 Record Length: nnod*numdof

1.2.6 Set 5 - Solution Information

The solution information is stored starting at this point in the file. The remaining records in the file are repeated as a group nsets times (once for each data set). Item nsets is defined in the file header. Each set of data is pointed to by a record pointer given in the record labeled DSI.

1.2.6.1 Group 1 - Solution header

G G G G

Record ID: N/A Type Integer: Integer Number of Records: 1 Record Length: 100 integers nelm ncumit nnod nrf ptrRF isym mask itime

0 iter

maxesz nmast ptrMST ptrBC kcmplx numdof

ptrNSL ptrESL rxtrap mode

DOFS positions 51-70 - title positions 71-90 - stitle1 dbmtim dbmdat dbfncl soltim nfldof ptrEXA Where:
G G G G

soldat ptrEXT

ptrOND ptrOEL

0 - position not used nelm - number of elements nnod - number of nodes mask - bitmask for the existence of several records. If a bit is set here, it indicates that the corresponding record exists on the file. The items in the bitmask that correspond to each record are shown in the record descriptions below. itime - loadstep

G G G G G G G G G G G

iter - iteration number ncumit - cumulative iteration number nrf - number of reaction forces maxesz nmast - number of masters ptrNSL - pointer to nodal solution ptrESL - pointer to element solution ptrRF - pointer to reaction forces ptrMST - pointer to the masters ptrBC - pointer to the boundary conditions rxtrap - key to extrapolate integration point results to nodes = 0 - move = 1 - extrapolate unless active non-linear = 2 - extrapolate always

G G G

mode - mode number of harmonic loading (nodalDia for Cyclic Symmetry) isym - symmetry condition for harmonic loading (nSector for Cyclic Symmetry) kcmplx - complex key = 0 - real = 1 - imaginary

G G G G G G G G G G G G G G

numdof - number of DOFs/nodes for this data set DOFS - DOF/node reference numbers (numdof values) title - main title (in integer form) stitle1- 1st subtitle (in integer form) dbmtim - time (in compact form) when the database was last modified dbmdat - date (in compact form) when the database was last modified dbfncl - number of times that the database was modified soltim - time (in compact form) when the solution for this data set was done soldat - date (in compact form) when the solution for this data set was done ptrOND - pointer to the ordered node list (load case files only) ptrOEL - pointer to the ordered element list (load case files only) nfldof - number of extra Flotran DOFs/nodes for this data set ptrEXA - pointer to header extension ptrEXT - pointer to header extension

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): 1. zero out the second half of the index. 2. call bioinf (nblk,12,1) ! tell the file reading routines to use absolute addressing 3. follow the code samples above.

1.2.6.2 Group 2 - Solution Data

G G G G

Record ID: N/A Type: Double-precision Number of Records: 1 Record Length: 100 reals lfacto tbulk lfactn 0.0 if pmeth=1: p convergence values (positions 31-100) cptime tref 0.0 0.0

timfrq tunif

velocity-acceleration-center of if pmeth=0: load data gravity terms (positions 11-28) (positions 51-100) where
G G G G G G G G G G G

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

G G G G G G G

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)

1.2.6.3 Group 2A - Header Extension

G G G G

Record ID: EXA Type: Integer Number of Records: 1 Record Length: 64

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: DENS= 1 VISC= 2 EVIS= 3 COND= 4 ECON= 5 LMD1= 6 LMD2= 7 LMD3= 8

LMD4= 9 LMD5=10 LMD6=11 EMD1=12 EMD2=13 EMD3=14 EMD4=15 EMD5=16 EMD6=17 PTOT=18 TTOT=19 PCOE=20 MACH=21 STRM=22 HFLU=23 HFLM=24 YPLU=25 TAUW=26 SPHT=27 CMUV=28 29 - 32 are spares.

1.2.6.4 Group 2B Header Extension

G G G G

Record ID: EXT Type: Integer Number of Records: 1 Record Length: 200 Integers positions 1-32 - current DOF for this result set positions 33-64 - current DOF labels for this result set positions 65-84 - The third title, in integer form positions 85-104 - The fourth title, in integer form

positions 105-124 - The fifth title, in integer form position 125 = ptrTRF if pmeth=1: positions 164-200 - p convergence specs

1.2.6.5 Group 3 - Nodal Solution

G G G G

Record ID: NSL Type: Double-precision Number of Records: 1 Record Length: Equal to nnod*Sumdof.

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).

1.2.6.6 Group 4 - Reaction Force Information

1.2.6.6.1 Record 1 - Reaction Force DOFs
G G G G

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) 1.2.6.6.2 Record 2 - Reaction forces
G G G G

Record ID: N/A Type: Double-precision Number of Records: 1 Record Length: nrf

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).

1.2.6.7 Group 5 - Master DOF List

G G G G

Record ID: MST Type: Integer Number of Records: 1 Record Length: nmast

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)

1.2.6.8 Group 6 - Boundary Condition Index Table

G G G G

Record ID: BC Type: Integer Number of Records: 1 Record Length: 40 Integers

(bit 23 (PDBBC) in mask) numdis ptrDIX ptrDIS numfor ptrFIX ptrFOR 0 0 0 0 0 0 0 where
G G G G G G G

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

numdis - number of nodal constraints ptrDIX - pointer to the table of nodes having nodal constraints ptrDIS - pointer to nodal constraint values numfor - number of nodal input force loadings ptrFIX - pointer to the table of nodes having nodal forces ptrFOR - pointer to nodal force values positions 7-40 are unused.

1.2.6.8.1 Record 1 - Nodal Constraint DOFs

G G G G

Record ID: DIX Type: Integer Number of Records: 1 Record Length: numdis

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. 1.2.6.8.2 Record 2 - Nodal Constraints
G G G G

Record ID: DIS Type: Double-precision Number of Records: 1 Record Length: 4*numdis

This record contains present and previous values (real and imaginary) of the nodal constraints at each DOF. 1.2.6.8.3 Record 3 - Nodal Input Force DOFs
G G G G

Record ID: FIX Type: Integer Number of Records: 1 Record Length: numfor

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. 1.2.6.8.4 Record 4 - Nodal forces
G G G G

Record ID: FOR Type: Double-precision Number of Records: 1 Record Length: 4*numfor

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
G G

Record ID: TRF Type: Double-precision

G G

Number of Records: 1 Record Length: 28*nnod (bit 24 (PDTRFL) in mask)

1.2.6.8.6 Record 6 - Ordered Node List

G G G G

Record ID: OND Type: Integer Number of Records: 1 Record Length: nnod

This record exists for a load case file only. 1.2.6.8.7 Record 7 - Ordered Element List
G G G G

Record ID: OEL Type: Integer Number of Records: 1 Record Length: nelm

This record exists for a load case file only.

1.2.6.9 Group 7 - Element Solutions Index Table

G G G G

Record ID: ESL Type: Integer Number of Records: 1 Record Length: nelm

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. 1.2.6.9.1 Record 1 - Individual Element Index Table
G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: 25

ptrEMS ptrENF ptrENS ptrENG ptrEGR ptrEEL ptrEPL ptrECR ptrETH ptrEUL ptrEFX ptrELF ptrEMN ptrECD ptrENL ptrEHC ptrEPT ptrESF ptrEPR ptrETB ptrECT 0 where
G G G G G G G G G G G G G G G G G G G G G G

ptrEMS - pointer to misc. data ptrENF - pointer to nodal forces ptrENS - pointer to nodal stresses ptrENG - pointer to volume and energies ptrEGR - pointer to nodal gradients ptrEEL - pointer to elastic strains ptrEPL - pointer to plastic strains ptrECR - pointer to creep strains ptrETH - pointer to thermal strains ptrEUL - pointer to euler angles ptrEFX - pointer to nodal fluxes ptrELF - pointer to local forces ptrEMN - pointer to misc. non-sum values ptrECD - pointer to element current densities ptrENL - pointer to nodal nonlinear data ptrEHC - pointer to calculated heat generations ptrEPT - pointer to element temperatures ptrESF - pointer to element surface stresses ptrEPR - pointer to face pressures(92 only) ptrETB - pointer to ETABLE items(post1 only ptrECT - pointer to contact data 0 - position not used

Note-If ptrxxx is negative, then all prtx items are zero and are not on the file. 1.2.6.9.2 Record 2 - Element Summable Miscellaneous Data
G G G G

Record ID: EMS Type: Double-precision Number of Records: 1 Record Length: varies

The contents and number of data items is element dependent. For a list of what's available, see the Output Data section for the particular element in the ANSYS Elements Reference. 1.2.6.9.3 Record 3 - Element Nodal Forces
G G G G

Record ID: ENF Type: Double-precision Number of Records: 1 Record Length: varies

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. 1.2.6.9.4 Record 4 - Element Nodal Component Stresses
G G G G

Record ID: ENS Type: Double-precision Number of Records: 1 Record Length: varies

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.
G

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. Note-nodstr is defined in the element type b description record. 1.2.6.9.5 Record 5 - Element Volume And Energies
G G G G

Record ID: ENG Type: Double-precision Number of Records: 1 Record Length: 6

volume energy 0.0 kenrgy magnet co-energy incremental energy where

G G G G G G

volume - the element volume energy - the element energy associated with the stiffness matrix 0.0 - position not used kenrgy - the kinetic energy (if meaningful) magnet co-energy incremental energy

1.2.6.9.6 Record 6 - Element Nodal Field Gradients

G G G G

Record ID: EGR Type: Double-precision Number of Records: 1 Record Length: varies

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). Note-nodstr is defined in the element type description record. 1.2.6.9.7 Record 7 - Element Nodal Component Elastic Strains
G G G G

Record ID: EEL Type: Double-precision Number of Records: 1 Record Length: varies

This record contains strains in the same order as the nodal stresses given in the record labeled ENS. Elastic strains 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 xtrap in the solution header for the setting. An element is considered nonlinear when either plastic, creep, or swelling strains are present. For beam elements, see the Output Data section for the particular element in the ANSYS Elements Reference. 1.2.6.9.8 Record 8 - Element Nodal Component Plastic Strains
G G G G

Record ID: EPL Type: Double-precision Number of Records: 1 Record Length: varies

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. 1.2.6.9.9 Record 9 - Element Nodal Component Creep Strains
G G G G

Record ID: ECR Type: Double Precision Number of Records: 1 Record Length: varies

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. 1.2.6.9.10 Record 10 - Element Nodal Component Thermal Strains
G G G G

Record ID: ETH Type: Double Precision Number of Records: 1 Record Length: varies

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. 1.2.6.9.11 Record 11 - Element Euler Angles

G G G G

Record ID: EUL Type: Double Precision Number of Records: 1 Record Length: varies

This record contains the Euler rotations (THXY,THYZ,THZX).

G

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.

Note-nodstr is defined in the element type description record. 1.2.6.9.12 Record 12 - Element Nodal Field Fluxes
G G G G

Record ID: EFX Type: Double-precision Number of Records: 1 Record Length: varies

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. Note-nodstr is defined in the element type description record. 1.2.6.9.13 Record 13 - Element Nodal Coupled-field Forces
G G G G

Record ID: ELF Type: Double-precision Number of Records: 1 Record Length: varies

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. 1.2.6.9.14 Record 14 - Element Non-summable Miscellaneous Data
G G G G

Record ID: EMN Type: Double-precision Number of Records: 1 Record Length: varies

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. 1.2.6.9.15 Record 15 - Element Current Densities
G G G G

Record ID: ECD Type: Double-precision Number of Records: 1 Record Length: 3

This record contains the calculated current densities in the order X,Y,Z. 1.2.6.9.16 Record 16- Element Nodal Nonlinear Data
G G G G

Record ID: ENL Type: Double-precision Number of Records: 1 Record Length: varies

This record stores nonlinear data at each corner node n the order SEPL, SRAT, HPRES, EPEQ, PSV, and PLWK, followed by 4 spares.
G

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-nodstr is defined in the element type description record.

1.2.6.9.17 Record 17 - Element Structural Nodal Temperatures

G G G G G

Record ID: EPT Type: Double-precision Number of Records: 1 Record Length: varies For solid elements and SHELL41, the record contains nodal temperatures at each node and the number of items in this record is nodfor. For shell elements, except SHELL41 and SHELL91, the record contains nodal temperatures at each corner node for the top surface and the bottom surface. The number of items in this record is nodstr*2. For SHELL91, the record contains nodal temperatures at each corner node for the bottom of the bottom layer, and each succeeding interlayer surface up to the top of the top layer. The number of items in this record is (NL+1)*nodstr, where NL = number of layers. For beam elements, the contents and number of data items in this record is element dependent. 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. 1.2.6.9.18 Record 18 - Element Heat Generafion
G G G G

Record ID: EHC Type: Double-precision Number of Records: 1 Record Length: 1

This record stores the calculated heat generation. 1.2.6.9.19 Record 19 - Element Surface Stresses
G G G G

Record ID: ESF Type: Double-precision Number of Records: 1 Record Length: nsurf*19

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: facenm area epy epz temp press epx 0.0d0 sx sy

sz 0.0d0

0.0d0 0.0d0 0.0d0 0.0d0 0.0d0 sint seqv

For 3d elements: facenm area temp press epx epy sz s2 epz epxy sx sy

sxy 0.0d0 0.0d0 s1 s3 sint seqv

For axisymmetric elements: facenm 0.0d0 temp 0.0d0 epx epy sz 0.0d0 where:
G G G G G G G G G G G G G G G

epz

epxy sx

sy 0.0d0

0.0d0 0.0d0 sxz 0.0d0 0.0d0 0.0d0

facenm - face number area - face area temp - face temperature press - face pressure epx - EPEL(X) - strain parallel to face epy - EPEL(Y) - strain perpendicular to face epz - EPEL(Z) epxy - EPEL(XY) epxz - EPEL(XZ) - torsion shear strain sx - S(X) - stress parallel to face sy - S(Y) - stress perpendicular to face sz - S(Z) sxy - S(XY) sxz - torsion shear stress s1 - S(1)

G G G G G

s2 - S(2) s3 - S(3) sint - S(INT) seqv - S(EQV) 0.0d0 - position not used

1.2.6.9.20 Record 20 - Element Pressures

G G G G

Record ID: EPR Type: Double-precision Number of Records: 1 Record Length: varies

This record contain the element normal pressures (one value per face). See the ANSYS Elements Reference for a description of the element face pressures. 1.2.6.9.21 Record 21 - Contact Data
G G G G

Record ID: ELT Type: Double-precision Number of Records: 1 Record Length: varies

This record stores contact data at each corner node in the order, STAT, PENE, PRES, STOTAL, and SLIDE, followed by four spaces.

1.3 Description of the Reduced Displacement File

This section explains the content of the reduced displacement file (file.rdsp).

1.3.1 Set 1 - Standard ANSYS File Header

See 1.1.2 for a description of this set. File number (Item 1) is 10.

1.3.2 Set 2 - RDSP File Header

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: 40

fun10 maxn kan 0

nmrow nmatrx nmode numdof wfmax lenbac ngaps 0 0 0 0 0 0 ncumit 0 0

ptrDOF ptrDNC ptrSTF ptrMAS ptrDMP ptrFRQ ptrDSP 0 0 0 Where

G G G G G G G G G G G G G G G G G G G G G G G G

0 0 0

0 0 0

0 0

0 0

fun10 - unit number (rdsp file is 10) nmrow - number of rows/columns in matrices nmatrx - number of reduced matrices on the file nmode - number of modes extracted during modal analysis (or nmrow if reduced method) numdof - number of dofs per node maxn - maximum node number wfmax - maximum wavefront lenbac - number of nodes ngaps - number of gaps ncumit - total number of iterations done during analysis kan - analysis type = 5 for reduced transient analysis 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 ptrDOF - pointer to degree of freedom set used in model ptrDNC - pointer to nodal constraints ptrSTF - pointer to the reduced stiffness matrix ptrMAS - pointer to the reduced mass matrix

G G G G G G G G G G G G G G G G

ptrDMP - pointer to the reduced damping matrix or mode shapes ptrFRQ - pointer to the frequencies ptrDSP - pointer to the calculated displacements 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

1.3.3 Set 3 - Analysis Information

1.3.3.1 Group 1 - Degrees Of Freedom Per Node
(curdof(i),i=1,numdof) Degree of freedom reference numbers: UX = 1 UY = 2 UZ = 3 AY = 8 ROTX= 4 ROTY= 5 AZ = 9 VX =10

ROTZ= 6 AX = 7 VY =11 VZ =12

13-18 are spares PRES=19 TEMP=20 ENKE=23 ENDS=24 EMF =25

VOLT=21 MAG =22 CURR=26 27-32 are spares

1.3.3.2 Group 2 - Nodal Equivalence Table

G G G G

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)

1.3.3.3 Group 3 - Time Information

G G G G

Record ID: N/A Type: Double-precision Number of Records: 1 Record Length: 10

dtime 0.0 0.0 0.0 0.0 0.0 where

G G G G G G G G G G

0.0 0.0 0.0 timend

dtime - the time increment 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used timend - the final time of the analysis

1.3.3.4 Group 4 - Degree Of Freedom Set Used

G G G G

Record ID: DOF Type: Integer Number of Records: 1 Record Length: 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 (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)

1.3.3.5 Group 5 - Original Reduced Set Of Degrees Of Freedom Used

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: nmrow+1

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

1.3.3.6 Group 6 - DOF Of Nodal Constraints

G G G G

Record ID: DNC Type: Integer Number of Records: 1 Record Length: 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)

1.3.4 Set 4 - Reduced Matrices Data

1.3.4.1 Group 1 - Reduced Stiffness Matrix
G G G G

Record ID: STF Type: Double-precision Number of Records: nmrow Record Length: nmrow

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)

1.3.4.2 Group 2 - Reduced Mass Matrix

G G G

Record ID: MAS Type: Double-precision Number of Records: nmrow

Record Length: 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)

1.3.4.3 Group 3 - Reduced Damping Matrix Or Mode Shapes

G G G G

Record ID: DMP Type: Double-precision Number of Records: varies Record Length: varies

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)

1.3.4.4 Group 4 - Frequencies Extracted From The Modal Analysis

G G G G

Record ID: FRQ Type: Double-precision Number of Records: 1 Record Length: nmrow

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)

1.3.5 Set 5 - Calculated Displacements

The next two groups are repeated (as a pair) until the time value equals the value of timend. The number of iterations is stored as ncumit. (See the previous records that deal with time).

1.3.5.1 Group 1 - Calculated Displacements

G G G G

Record ID: DSP Type: Double-precision Number of Records: 1 Record Length: nmrow+5

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: 1. Time for these displacements 2. Load step number 3. Substep number 4. Cumulative iteration 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.

1.3.5.2 Group 2 - Gap Restoring Forces

G G G G

Record ID: N/A Type: Doubple-precision Number of Records: 1 Record Length: ngaps

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)

1.4 Description of the Reduced Complex Displacement File

This section explains the content of the reduced complex displacement file (jobname. rfrq).

1.4.1 Set 1 - Standard ANSYS File Header

See 1.1.2 for a description of this set. File number (Item 1) is 10.

1.4.2 Set 2 - RFRQ File Header

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: 40 nmrow nmatrx nmode numdof wfmax lenbac 0 0 0 0 0 0 0 ncumit 0 0

fun10 maxn kan 0

ptrDOF ptrDNC ptrSTF ptrMAS ptrDMP ptrFRQ ptrDSP 0 0 0 where:

G G G G G G G G G G G G G G

0 0 0

0 0 0

0 0

0 0

fun10 - unit number (rfrq file is 10) nmrow - number of rows/columns in matrices nmatrx - number of reduced matrices on file nmode - number of modes extracted during modal analysis (or nmrow if reduced method) numdof - number of dofs per node maxn - maximum node number wfmax - maximum wavefront lenbac - number of nodes 0 - position not used ncumit - total number of iterations done during analysis kan - analysis type = 6 - reduced harmonic 0 - position not used 0 - position not used 0 - position not used

G G G G G G G G G G G G G G G G G G G G G G G G G G

0 - position not used 0 - position not used 0 - position not used 0 position not used 0 - position not used 0 - position not used ptrDOF - pointer to degree of freedom set used in model ptrDNC - pointer to nodal constraints ptrSTF - pointer to the reduced stiffness matrix ptrMAS - pointer to the reduced mass matrix ptrDMP - pointer to the reduced damping matrix or mode shapes ptrFRQ - pointer to the frequencies ptrDSP - pointer to the calculated displacements 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

1.4.3 Set 3 - Analysis Information

1.4.3.1 Group 1 - Degrees Of Freedom Per Node
The following define the degree of freedom reference numbers: UX = 1 ROTY= 5 AZ = 9 UY = 2 ROTZ= 6 VX =10 UZ = 3 AX = 7 VY =11 ROTX= 4 AY = 8 VZ =12

13-18 are spares PRES=19 MAG =22 ENKE=23

TEMP=20 VOLT=21 ENDS=24 EMF =25

CURR=26

27-32 are spares

1.4.3.2 Group 2 - Nodal Equivalence Table

G G G G

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)

1.4.3.3 Group 3 - Unused Record

G G G G

Record ID: N/A Type: Double-precision Number of Records: 1 Record Length: 10

The record contents are as follows: 1.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0

1.4.3.4 Group 4 - Degree Of Freedom Set Used

G G G G

Record ID: DOF Type: Integer Number of Records: 1 Record Length: 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 (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

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: nmrow+1

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

1.4.3.6 Group 6 - DOF Of Nodal Constraints

G G G G

Record ID: DNC Type: Integer Number of Records: 1 Record Length: 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)

1.4.4 Set 4 - Reduced Matrices Data

1.4.4.1 Group 1 - Reduced Stiffness Matrix
G G G G

Record ID: STF Type: Double-precision Number of Records: 1 Record Length: 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)

1.4.4.2 Group 2 - Reduced Mass Matrix

G

Record ID: MAS

G G G

Type: Double-precision Number of Records: nmrow Record Length: 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)

1.4.4.3 Group 3 - Reduced Damping Matrix Or Mode Shapes

G G G G

Record ID: DMP Type: Double-precision Number of Records: varies Record Length: varies

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)

1.4.4.4 Group 4 - Frequencies Extracted From The Modal Analysis

G G G G

Record ID: FRQ Type: Double-precision Number of Records: 1 Record Length: nmrow

This record is present only for analyses using the mode superposition method (using the reduced mode extraction technique). (freq(i),i=1,nmrow)

1.4.5 Set 5 - Calculated Displacements

Located by the PTRDSP variable defined in Set 2. Set 5 is repeated NCUMIT times.

1.4.5.1 Group 1 - Calculated Complex Displacements

G G G G

Record ID: DSP Type: cmp Number of Records: ncumit Record Length: nmrow+5

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: Real part 1. frequency for these values 2. load step number 3. cumulative iteration number 4. zero Imaginary part frequency increment substep number 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.

1.5 Description of the Modal Results File

This section explains the content of the modal results file (jobname.mode).

1.5.1 Set 1 - Standard ANSYS File Header

See 1.1.2 for a description of this set. File number (Item 1) is 9.

1.5.2 Set 2 - MODE File Header

G G

Record ID: N/A Type: Integer

G G

Number of Records: 1 Record Length: 40 nmrow nmatrx nmode numdof wfmax lenbac 0 nontp ldstep

fun09 maxn

lumpms extopt

SvCode kan

numitr expbeg expend nspect nSPdat ptrRDF ptrFRQ ptrPRT ptrSHP ptrLOD ptrSTF ptrMAS ptrDMP ptrCOF ptrDCF ptrLPM ptrSP1 0 0 Where
G G

0 0

0 0

G G G G G G G G G

fun09 - unit number (mode file is 9) nmrow - number of rows/columns in matrices (maxn*numdof). If extopt = 0, nmrow is the number of rows in the reduced matrices and the number of master degrees of freedom. nmatrx - number of reduced matrices on the file (applies only if extopt=0) nmode - number of modes extracted numdof - number of dof per node maxn - maximum node number (If extopt = 3 or 4, the actual number of nodes is referenced.) wfmax - maximum wavefront (Does not apply if extopt = 3 or 4.) lenbac - number of nodes 0 - position not used nontp - number of equations on the .TRI file (Does not apply if extopt = 0.) lumpms - lumped mass (Does not apply if extopt = 3 or 4.), key = 0 - default matrix type = 1 - lumped

extopt - mode extraction method = 0 - reduced

= 1 - subspace = 3 - unsymmetric Lanczos = 4 - damped Lanczos = 6 - block Lanczos

G

SvCode - Solver code = 0 - Frontal solver = 1 - Power Dynamics

kan - analysis type = 1 - buckling = 2 - modal

G G

G G G G G G G G G G G G G G G G G G G G G G G

ldstep - load step number numitr - total number of cumulative iterations done during analysis. (Does not apply if extopt = 3 or 4.) expbeg - beginning of the frequency range of interest expend - end of the frequency range of interest nspect - number of spectra nSPdat - number of data items per spectrum ptrRDF - pointer to reduced degree of freedom set used in model ptrFRQ - pointer to the frequencies ptrPRT - pointer to the participation factors ptrSHP - pointer to the mode shapes (eigenvectors) ptrLOD - pointer to the load vectors ptrSTF - pointer to the reduced stiffness matrix ptrMAS - pointer to the reduced mass matrix ptrDMP - pointer to the reduced damping matrix ptrCOF - pointer to the mode coefficients ptrDCF - pointer to the modal damping coefficients ptrLPM - pointer to the diagonal mass vector ptrSP1 - pointer to the the spectrum data 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

1.5.3 Set 3 - Analysis Information

1.5.3.1 Group 1 - Degrees Of Freedom Per Node
The following defines the degree of freedom reference numbers: UX = 1 UY = 2 UZ = 3 AY = 8 ROTX= 4 ROTY= 5 AZ = 9 VX =10

ROTZ= 6 AX = 7 VY =11 VZ =12

13-18 are spares PRES=19 TEMP=20 ENKE=23 ENDS=24 EMF =25

VOLT=21 MAG =22 CURR=26 27-32 are spares

1.5.3.2 Group 2 - Nodal Equivalence Table

G G G G

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)

1.5.3.3 Group 3 - Reduced Set Of Degrees Of Freedom Used

G G G G

Record ID: RDF Type: Integer Number of Records: 1 Record Length: nmrow

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)

1.5.3.4 Group 4 - Frequencies (eigenvalues)

G G G G

Record ID: FRQ Type: Double-precision Number of Records: 1 Record Length: nmode

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)

1.5.3.5 Group 5 - Participation Factors

G G G G

Record ID: PRT Type: Double-precision Number of Records: 1 Record Length: nmode

Factors are complex if EXTOPT=3 or 4. (pfact(i),i=1,nmode)

1.5.3.6 Group 6 - Mode Coefficients

G G G G

Record ID: COF Type: Double-precision Number of Records: 1 Record Length: nmode

(modecf(i),i=1,nmode)

1.5.3.7 Group 7 - Modal Damping Coefficients

G G G G

Record ID: DCF Type: Double-precision Number of Records: 1 Record Length: nmode

(dampmd(i),i=1,nmode)

1.5.3.8 Group 8 - Mode Shapes (Eigenvectors)

G G G G

Record ID: SHP Type: Double-precision Number of Records: nmode Record Length: nmrow

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)

1.5.3.9 Group 9 - Load Vector

G G G G

Record ID: LOD Type: Double-precision Number of Records: 1 Record Length: nmrow

This record is present only if extopt=0 or 1. (f(i),i=1,nmrow)

1.5.3.10 Group 10 - Lumped Mass Vector

G G G G

Record ID: LPM Type: Double-precision Number of Records: 1 Record Length: 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)

1.5.4 Set 4 - Reduced Matrices Data

1.5.4.1 Group 1 - Reduced Stiffness Matrix
G G G G

Record ID: STF Type: Double-precision Number of Records: nmrow Record Length: 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

G G G G

Record ID: MAS Type: Double-precision Number of Records: nmrow Record Length: nmrow

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)

1.5.4.3 Group 3 - Reduced Damping Matrix

G G G G

Record ID: DMP Type: Double-precision Number of Records: nmrow Record Length: nmrow

1.5.4.4 Group 4 - Spectrum Data

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) for each spectrum (nspect records): SP1 dp 1 nmode Mode coeff for this spectra ------dp 1 nmode Modal damping values dp 1 130 dp 1 20 svcom: freqtb, etc. misc. spectra data

1.6 Description of the Element Matrices File

This section explains the content of the element matrices file (jobname.emat).

1.6.1 Set 1 - Standard ANSYS File Header

See 1.1.2 for a description of this set. File number (Item 1) is 2.

1.6.2 Set 2 - EMAT File Header

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: 40 nume 0 kygm 0 0 0 numdof lenu 0 kycd 0 0 0 lenbac

fun02 maxn kygst kygrf 0 0

nodref lumpm kygss kygaf 0 0 0 0 0 0

ptrDOF ptrBAC ptrELM ptrFST ptrLST 0 Where

G G G G G G G G G G

ptrEHD ptrIDX 0

ptrend

fun02 - unit number (emat file is 2) nume - number of elements numdof - number of dofs per node lenu - total DOFs of model lenbac - number of nodes maxn - maximum node number 0 - position not used 0 - position not used nodref - actual number of nodes referenced lumpm - lumped mass key = 0 - default matrix type

= 1 - lumped
G

kygst - global stiffness matrix calculate key = 0 - do not calculate = 1 - calculate

kygm - global mass matrix calculate key = 0 - do not calculate = 1 - calculate

kycd - global damping matrix calculate key = 0 - do not calculate = 1 - calculate

G G G G

kygss - global stress stiffening matrix calculate key 0 - do not calculate 1 - calculate kygaf - global applied force vector calculate key = 0 - do not calculate = 1 - calculate

kygrf - global restoring force vector calculate key (Newton-Raphson only) = 0 - do not calculate = 1 - calculate

G G G G G G G G G

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

G G G G G G G G G G G G G G G

0 - position not used 0 - position not used 0 - position not used 0 - position not used 0 - position not used ptrDOF - pointer to degrees of freedom per node used in model ptrBAC - pointer to nodal equivalence table ptrELM - pointer to element equivalence table ptrFST - pointer to first element at a DOF table ptrLST - pointer to last element at a DOF table 0 - position not used ptrEHD - pointer to the start of the element matrices ptrIDX - pointer to element matrices index table 0 - position not used ptrend - pointer to the end of the file

Note-The global calculate keys are set by the analysis type.

1.6.3 Set 3 - Analysis Information

1.6.3.1 Group 1 - Time information
G G G G

Record ID: N/A Type: Double-precision Number of Records: 1 Record Length: 20

timval timinc frqval timbeg timend 0.0 0.0 0.0 Where

G G G G G G

0.0 0.0 0.0

0.0 0.0 0.0

0.0 0.0 0.0

0.0 0.0 0.0

timval - the current time timinc - the time increment frqval - the current frequency (from a harmonic analysis) timbeg - the start time for the analysis timend - the end time for the analysis 0.0 - position not used

G G G G G G G G G G G G G G

0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used 0.0 - position not used

1.6.3.2 Group 2 - Degrees Of Freedom Per Node

The following defines the degree of freedom reference numbers: UX = 1 UY = 2 UZ = 3 AY = 8 ROTX= 4 ROTY= 5 AZ = 9 VX =10

ROTZ= 6 AX = 7 VY =11 VZ =12

13-18 are spares PRES=19 TEMP=20 ENKE=23 ENDS=24 EMF =25

VOLT=21 MAG =22 CURR=26 27-32 are spares

1.6.3.3 Group 3 - Nodal Equivalence Table

G G G G

Record ID: BAC 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)

1.6.3.4 Group 4 - Element Equivalence Table

G G G G

Record ID: ELM Type: Integer Number of Records: 1 Record Length: nume

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)

1.6.3.5 Group 5 - First Element At A DOF Table

G G G G

Record ID: FST Type: Integer Number of Records: 1 Record Length: lenu

This record signifies the first element encountered at a particular DOF. (frstel(i),i=1,lenu)

1.6.3.6 Group 6 - Last Element At A DOF Table

G G G G

Record ID: LST Type: Integer Number of Records: 1 Record Length: lenu

This record signifies the last element encountered at a particular DOF. (lastel(i),i=1,lenu)

1.6.3.7 Group 7 - Element Index Table

G G G G

Record ID: IDX Type: Integer Number of Records: 1 Record Length: nume

This record specifies the file location for the beginning of the data for each element. (index(i),i=1,nume)

1.6.4 Set 4 - Element Matrices Data

The records at the end of the file store element information and get written as a set for each element (nume sets of these records will appear on the file at this point) ptrEHD indicates the beginning of the element data. If substructure matrices are written to the .EMAT file, they are written in a different

format than is shown here. This alternate format is not documented at this time, as it is likely to change in the future.

1.6.4.1 Group 1 - Element Matrix Header

G G G G

Record ID: EHD Type: Integer Number of Records: 1 Record Length: 10

stkey mkey dkey sskey akey nrkey ikey 0 where

G

nmrow

stkey - stiffness matrix key = 0 - matrix not present = 1 - matrix present

mkey - mass matrix key = 0 - matirx not present = 1 - matrix present

dkey - damping matrix key = 0 - matrix not present = 1 - matrix present

sskey - stress stiffening matrix key = 0 - matrix not present = 1 - matrix present

akey - applied load vector key = 0 - vector not used

= 1 - vector used
G

nrkey - newton-raphson(restoring) load vector key (for nonlinear analyses) = 0 - vector not used = 1 - vector used

ikey - imaginary load vector key (for complex analyses) = 0 - vector not used = 1 - vector used

G G G

0 - position not used 0 - position not used nmrow - numbers/columns in matrices. If the number is negative, the matrices will be written in lower triangular form.

1.6.4.2 Group 2 - DOF Index Table

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: nmrow

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.

1.6.4.3 Group 3 - Element Matrices

G G G G

Record ID: N/A Type: Double-precision Number of Records: varies Record Length: varies

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.

1.6.4.4 Group 4 - Element Force Vectors

G G G G

Record ID: N/A Type: dp Number of Records: 1 Record Length: 2*nmrow

This record contains both the applied force vector and the (restoring or imaginary) load vector. ANSYS always writes this record.

1.7 Description of the Substructure Matrices File

This section explains the contents of the substructure matrices file (jobname.sub).

1.7.1 Set 1 - Standard ANSYS File Header

See 1.1.2 for a description of this set. File number (Item 1) is 8.

1.7.2 Set 2 - SUB File Header

G G G G

Record ID: HED Type: Integer Number of Records: 1 Record Length: 50 nmrow nmatrx nedge wfmax lenbac kmass 0 nnod numdof kunsym nvect prtLOD

fun08 maxn kstf 0 ntrans

kdamp kss sesort lenlst

ptrMAT ptrXFM ptrHED name1 trok name3 name4

name2 lrok

ptrDOF ptrDST ptrBAC ptrTIT ptrNOD

ptrXYZ ptrEDG ptrGDF thsubs ptrORG stfmax 0 where

G G G G G G G G G

ptrPOS keydim

0 name6

name5

name7 name8

fun08 - unit number (sub file is 8) nmrow - number of rows in matrices (also number of dofs in substructure) nmatrx - number of matrices on file nedge - number of edges for outline numdof - number of dofs per node maxn - maximum node number of complete model presently in database wfmax - maximum wavefront of substruct. during generation pass lenbac - number of nodes defining substructure during the generation pass nnod - number of unique nodes in the substructure having DOFs, and which define this substructure during the use pass. Also, the number of nodes having master DOFs. kunsym - unsymmetric matrix key = 0 - symmetric = 1 - unsymmetric

kstf - stiffness matrix present key = 0 - matrix is not on file = 1 - matrix is on file

kmass - mass matrix present key = 0 - matrix is not on file = 1 - matrix is on file

kdamp - damping matrix present key = 0 - matrix is not on file = 1 - matrix is on file

kss - stress stiffening matrx present

= 0 - matrix is not on file = 1 - matrix is on file

G G G G

nvect - number of load vectors (at least 1 is required) 0 - position not used 0 - position not used sesort - DOF set sort key = 0 - numbers are not sorted = 1 - numbers are sorted in ascending order

G G G

lenlst - maximum length of DOF set for this substructure (maxn*numdof) ptrLOD - pointer to the start of the load vectors ntrans - transformed key = 0 - substructure has not been transformed >0 - substructure copied from another substructure, via either SESSYM or SETRAN

G G G G G G

ptrMAT - pointer to the start of the substructure matrices ptrXFM - pointer to the substructure transformations ptrHED - pointer to the SUB file header name1 - first four characters of the substructure file name, in integer form name2 - second four characters of the substructure file name, ininteger form lrok - large rotation key = 0 - DOF set is not valid for large rotations = 1 - DOF set is valid

trok - SETRAN rotation key = 0 - DOF set is not valid for SETRAN nodal rotation = 1 - DOF set is valid

G G G G G G G

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

G G G G

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

G G G G G G G

ptrPOS - pointer to the sorted substructure DOF set to the original ptrORG - pointer to the DOF set of the model during the generation pass 0 - position not used 0 - position not used 0 - position not used stfmax - maximum diagonal stiffness term (packed into an integer) keydim - dimensionality key = 1 - axisymmetric = 2 - 2-D = 3 - 3-D

G G G G G

0 - position not used name5 - fifth four characters of the substructure file name, in integer form name6 - sixth four characters of the substructure file name, in integer form name7 - seventh four characters of the substructure file name, in integer form name8 - eighth four characters of th substructure file name, in integer form

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.7.3 Set 3 - Substructure Information

1.7.3.1 Group 1 - Substructure Transformations
G G G G

Record ID: XFM Type: Double-precision Number of Records: 1 Record Length: 125

(5*25 double precisions). This record has meaning only if ntrans > 0. You can define up to five levels of transformations, with 25 variables in each level. Up to the first seven variables are used as follows: If the substructure was transferred (via the SETRAN command):
G G G G G G G

1st variable - 1.0 2nd variable - nodal increment 3rd variable - reference number of coordinate system where substructure will be transferred 4th variable - reference number of coordinate system where substructure is presently defined 5th variable - x coordinate increment 6th variable - y coordinate increment 7th variable - z coordinate increment

If the substructure used symmetry (via the SESYMM command):

G G G

1st variable - 2.0 2nd variable - nodal increment 3rd variable - number of coordinate component to be used in operation = 1 - x coordinate = 2 - y coordinate = 3 - z coordinate

4th variable - reference number of coordinate system to be used for symmetry operation

1.7.3.2 Group 2 - Degrees Of Freedom Per Node

G G G G

Record ID: DOF Type: Integer Number of Records: 1 Record Length: numdof

The following defines the degree of freedom reference numbers: UX = 1 UY = 2 UZ = 3 AY = 8 ROTX= 4 ROTY= 5 AZ = 9 VX =10

ROTZ= 6 AX = 7 VY =11 VZ =12

13-18 are spares PRES=19 TEMP=20

VOLT=21 MAG =22 CURR=26 27-32 are spares

ENKE=23

ENDS=24 EMF =25

1.7.3.3 Group 3 - Local DOF Set

G G G G

Record ID: DST Type: Integer Number of Records: 1 Record Length: nmrow

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).

1.7.3.4 Group 4 - Positions Of The Local DOF Set

G G G G

Record ID: POS Type: Integer Number of Records: 1 Record Length: nmrow

This record stores the positions of the local DOF set in relation to the generated DOF set. (lposit(i),i=1,nmrow).

1.7.3.5 Group 5 - DOF Set Of The Model As Defined During Generation Pass
G G G G

Record ID: ORG Type: Integer Number of Records: 1 Record Length: 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).

1.7.3.6 Group 6 - Nodal Equivalence Table

G G G

Record ID: BAC Type: Integer Number of Records: 1

Record Length: lenbac

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).

1.7.3.7 Group 7 - Substructure Title

G G G G

Record ID: TIT Type: Integer Number of Records: 1 Record Length: 20

Substructure title (converted to integers, see inexc4)

1.7.3.8 Group 8 - Unique Node List

G G G G

Record ID: NOD Type: Integer Number of Records: 1 Record Length: nnod

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)

1.7.3.9 Group 9 - Coordinates Of The Unique Nodes

G G G G

Record ID: XYZ Type: Double-precision Number of Records: nnod Record Length: 6

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)

1.7.3.10 Group 10 - Edge Of Substructure

G G G G

Record ID: EDG Type: Double-precision Number of Records: nedge Record Length: 6

This record contains beginning and ending locations (X1, Y1, Z1, X2, Y2, Z2 coordinates) of a straight line comprising an edge of the substructure.

1.7.3.11 Group 11 - Global DOF Set

G G G G

Record ID: GDF Type: Integer Number of Records: 1 Record Length: nmrow

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)

1.7.4 Set 4 - Substructure Matrices

The substructure matrices are written at this position in the file. 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 nmrow rows of each matrix have been written to the file. MAT dp 1 ------dp 1 dp 1 dp 1 nmrow Row of the stiffness matrix, if nmatrx > 0. (ak(i,j),i=1,nmrow) nmrow Row of the mass matrix, if nmatrx > 1. (am(i,j),i=1,nmrow) nmrow Row of the damping matrix, if nmatrx > 2. (ac(i,j),i=1,nmrow) 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)

1.8 Description of the Triangularized Stiffness File

This section explains the contents of the triangularized stiffness file (jobname.tri).

1.8.1 Set 1 - Standard ANSYS File Header

See 1.1.2 for a description of this set. File number (Item 1) is 11.

1.8.2 Set 2 - TRI File Header

G G G G

Record ID: N/A Type: integer Number of Records: 1 Record Length: 20 nontp nmast 1 kan

fun11

wfmax lenbac numdof ptrMST ptrend lumpm keyuns ptrMS1 ptrMS2 ptrEN1 ptrEN2 0 where
G G G G G G G G G

ptrTRI 0

fun11 - unit number (tri file is 11) nontp - number of equations on file nmast - number of master dofs 1 - position not used, always = 1 kan - analysis type wfmax - maximum wavefront lenbac - number of nodes numdof - number of degrees of freedom (DOF) per node ptrMST - 32 bit pointer to the master dof list, only here for backward compatibility. Do not use if ptrMS1 or ptrMS2 are non-zero. ptrend - 32 bit pointer to the end of file only here for backward compatibility. Do not use if ptrEN1 or ptrEN2 are non-zero. lumpm - lumped mass key = 0 - default matrix type = 1 - lumped

keyuns - unsymmetric key = 0 - the matrix is not unsymmetric = 1 - the matrix is unsymmetric

ptrMS1, ptrMS2 - These two values are two halves of a 64 bit pointer that points to the master

G G G G G

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

1.8.3 Set 3 - Analysis Information

1.8.3.1 Group 1 Degrees Of Freedom Per Node
The following defines the degree of freedom reference numbers:
G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: numdof UY = 2 UZ = 3 AY = 8 ROTX= 4 ROTY= 5 AZ = 9 VX =10

UX = 1

ROTZ= 6 AX = 7 VY =11 VZ =12

13-18 are spares PRES=19 TEMP=20 ENKE=23 ENDS=24 EMF =25

VOLT=21 MAG =22 CURR=26 27-32 are spares

1.8.3.2 Group 2 Nodal Equivalence Table

G G G G

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)

1.8.4 Set 4 - Triangularized Matrix Data

At this point in the file, the triangularized matrix information is stored. The info is written row by row,

and there are two different storage options for writing a row. If the row being written does not have a constraint equation associated with it, then two records are written to describe the row. If the row being written has a constraint equation associated with it, then five records are written to describe the row. Both formats are shown below. These groupings of two or five records per row will be written a total of nontp times (to include all rows) The next two descriptions show the format for a row that does not have a constraint equation associated with it:

1.8.4.1 Group 1 - A Row Of The Triangularized Matrix

G G G G

Record ID: N/A Type: Double-precision/complex Number of Records: 1 Record Length: varies

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)

1.8.4.2 Group 2 - Triangular Matrix Row Indices

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: varies

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.

1.8.4.3 Group 1 - Flag Record

G G G G

Record ID: N/A Type: Double-precision Number of Records: 1 Record Length: 2

Indicates that constraint equations are being stored, and that the storage is shown here. Both values are TINY.

1.8.4.4 Group 2 - Coefficients of the Constraint Equation

G G G G

Record ID: N/A Type: Double-precision Number of Records: 1 Record Length: varies

The length of this record will vary (actual length is returned from the routine BINRD). (coeff(i), i=1, n+2)

1.8.4.5 Group 3 - Triangularized Matrix Row

G G G G

Record ID: N/A Type: Double-precision/Complex Number of Records: 1 Record Length: varies

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)

1.8.4.6 Group 4 - Triangular matrix row indices

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: varies

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)

1.8.4.7 Group 5 - Indicates The End Of The 5 Record Storage For This Row

G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: 2

It is included for situations when the file is being read from the bottom up. Its contents:
G G G

-cenum: n cenum: the constraint equation number for the constraint equation stored above n: the length of a row of the matrix being written

1.8.5 Set 5 - Master Degree Of Freedom List

G G G G

Record ID: MST or MS1, MS2 Type: Integer Number of Records: 1 Record Length: nmast

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.

1.9 Description of the Full StiffnessMass File

This section explains the contents of the full file (jobname.full).

1.9.1 Set 1 - Standard ANSYS File Header

See 1.1.2 for a description of this set. File number (Item 1) is 4.

1.9.2 Set 2 - FULL File Header

G G G G

Record ID: N/A Type: integer Number of Records: 1 Record Length: 40

fun04

nontp nmrow nmatrx kan

wfmax lenbac numdof ptrend ptrend lumpm jcgeqn jcgtrm keyuns extopt jcgnmx sclstf nxrows ptrIDX 0 0 0 0 0 0 0 0 0

ncefull ncetrm 0 0 0 0 Where

G G G G G G G G G G G

0 0 0

0 0 0

fun04 - unit number (full file is 4) nontp - number of equations on file nmrow - number of rows in matrices nmatrx - number of matrices on file kan - analysis type wfmax - maximum wavefront lenbac - number of nodes numdof - number of dofs per node ptrend - pointer to end of file ptrend - pointer to end of file lumpm - lumped mass key = 0 - default matrix type = 1 - lumped

G G G

jcgeqn - number of jcg equations jcgtrm - number of coefficients in sparce jcg storage keyuns - unsymmetric key = 0 - no unsymmetric matrices on file = 1 - there is at least one unsymmetric matrix on file

extopt - mode extraction method = 0 - reduced = 1 - lumped = 3 - unsymmetric Lanczos = 4 - damped Lanczos = 6 - block Lanczos

G G G G G G G G G G G G G G G G G G G G G G G G G

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

1.9.3 Set 3 - Analysis Information

1.9.3.1 Group 1 Degrees Of Freedom Per Node
The following defines the degree of freedom reference numbers:
G

Record ID: N/A

G G G

Type: Integer Number of Records: 1 Record Length: numdof UY = 2 UZ = 3 AY = 8 ROTX= 4 ROTY= 5 AZ = 9 VX =10

UX = 1

ROTZ= 6 AX = 7 VY =11 VZ =12

13-18 are spares PRES=19 TEMP=20 ENKE=23 ENDS=24 EMF =25

VOLT=21 MAG =22 CURR=26 27-32 are spares

1.9.3.2 Group 2 - Nodal Equivalence Table

G G G G

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)

1.9.3.3 Group 3 - Stiffness-Mass Matrices

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. 1.9.3.3.1 Record 1 - Matrix Row Indices
G G G G

Record ID: IDX Type: Integer Number of Records: 1 Record Length: varies

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) 1.9.3.3.2 Record 2 - A Second Level Of Indexing For The Matrix
G G G G

Record ID: N/A Type: Integer Number of Records: 1 Record Length: varies

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 1.9.3.3.3 Record 3 - Stiffness Matrix
G G G G

Record ID: N/A Type: Double-precision/Complex Number of Records: 1 Record Length: varies

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) 1.9.3.3.4 Record 4 - Mass Matrix
G G G G

Record ID: N/A Type: Double-precision/Complex Number of Records: 1 Record Length: varies

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) 1.9.3.3.5 Record 5- Damping Matrix
G G G G

Record ID: N/A Type: Double-precision/Complex Number of Records: 1 Record Length: varies

This record exists only if nmatrx > 2. 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)

Go to the beginning of this chapter

Chapter 2: Accessing Binary Data Files

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4

2.1 Accessing ANSYS Binary Files

The following section explains the routines you need to read to, write from, or modify an ANSYS binary file. This collection of routines (called binlib) resides on your ANSYS distribution medium in an object library file. The binlib library is in the archive library \ansys55\custom\misc\binlib.a (on Windows systems) or /ansys55/custom/misc/binlib.a (on UNIX systems). 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.

2.1.1 Characteristics of ANSYS Binary Files

Before accessing ANSYS binary files, you need to know certain file characteristics: 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.

2.1.2 Viewing Binary File Contents

To view the contents of certain ANSYS binary files, you issue the command /AUX2 or choose menu path Utility Menu>File>List>Binary Files or Utility Menu>List>File>Binary Files. (You can do so only at the Begin level.) The ANSYS program then enters its binary file dumping processor, AUX2, and dumps the binary file record by record. 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:
G

Type of variable is one of the following: int - integer dp - Double-precision log - logical (true or false) char - character

Size of variable is one of the following: sc - scalar variable ar(n) - array of size n

intent of variable is one of the following: in - input only out - output only inout - both an input and an output variable

2.1.4 binini (Initializing Buffered Binary I/O Systems)

subroutine binini (iott) c *** primary function: initialize buffered binary i/o system c --- This routine is intended to be used in standalone programs. c --- This routine should not be linked into the ANSYS program. 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 iott (int,sc,in) - output unit number for error output

c c c

output arguments: none.

2.1.5 Function sysiqr (Retrieving the Status of a File)

function sysiqr (nunit,fname,lname,inqr) c *** primary function: do a file system inquire (system dependent) 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 nunit (int,sc,in) - fortran unit number (used only for inqr='O') c fname (chr,sc,in) - name of file c lname (int,sc,in) - length of file name (characters, max=50) c inqr (chr,sc,in) - character key for information requested c = 'E' - return whether file exists c sysiqr = 1 - file exists c = 0 - file does not exist c < 0 - error occured c = 'O' - return whether file is open c sysiqr = 1 - file is open c = 0 - file is closed c < 0 - error occured c = 'N' - return unit number of file c sysiqr > 0 - unit number for file c = 0 - file not assigned to a unit c < 0 - error occured c c output arguments: c sysiqr (int,func,out) - the returned value of sysiqr is based on c setting of inqr

2.1.6 Function biniqr (Retrieving System-Dependent Parameters)

function biniqr (nblk,key) c *** primary function: get data about a block i/o buffer c --- This routine is intended to be used in standalone programs. c --- This routine should not be linked into the ANSYS program. 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 nblk (int,sc,in) - the block number for the inquiry

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

key

or zero (see below) (int,sc,in) - key for information requested nblk = 0 - return information about system/file key = 1 - return system block size = 2 - return number of integers per dp = 3 - return filename length nblk > 0 - return information about this block key = 1 - return fortran unit number = 2 - retrun number of blocks in file = 3 - return length of page in 32 bit words = 4 - return open status biniqr = 0 - file close = 1 - file open = 5 - return file format biniqr = 0 - internal format = 1 - external format = 6 - return read/write status biniqr = 0 - both read & write = 1 - read = 2 - write = 7 - return current position on file = 8 - return maximum length of file (in words) = 9 - return starting word for this page in buffer

output arguments: biniqr (int,func,out)

- the returned value of biniqr is based on setting of nblk and key

2.1.7 Function binset (Opening a Blocked Binary File or Initializing Paging Space)
c c c c c c 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 note: BIO_MAXFILES is 9 BIO_MAXBLOCKS is 16 c c input arguments: c variable (typ,siz,intent) description c nblk (int,sc,in) - block number (1 to BIO_MAXFILES max) c ntap (int,sc,in) - fortran unit number for the file c (if 0, bit bucket) function binset (nblk,ntap,keyrw,istart,paglen,npage, x pname,nchar,kext,buffer) *** primary function: initialize paging space for a blocked binary file. binset should be used to open a blocked file before binrd or binwrt are used. binclo should be used to close the file. --- This routine is intended to be used in standalone programs. --- This routine should not be linked into the ANSYS program.

c c c c c c c c c c c c c c c c c c c c c c c c c c c

keyrw

(int,sc,in)

istart

paglen

npage pname nchar kext

buffer

- read/write flag = 0 - both read & write = 1 - read = 2 - write (int,sc,in) - starting location in buffer array usually 1 for nblk=1, paglen*npage+1 for nblk=2,etc. (int,sc,in) - page length in integer*4 words for external files or page length in integer*(IBYT) words for internal files paglen should always be a multiple of 512 words for efficiency (int,sc,in) - number of pages (1 to BIO_MAXBLOCKS max) (chr,ar(*),in) - name of the file (int,sc,in) - number of characters in the file name(<=50) (int,sc,in) - internal/external format flag = 0 - internal format = 1 - external format (int,ar(*),inout) - work array for paging, should be dimensioned to paglen*npage*nblk (max)

output arguments: variable (typ,siz,intent) binset (int,func,out)

buffer

description - error status = 0 - no error <>0 - error occurred (int,ar(*),inout) - work array for paging

2.1.8 Subroutine bintfo (Defining Data for a Standard ANSYS File Header)
c c c c c c c c c c c c c c c c c c c c c c subroutine bintfo (title,jobnam,units,code) *** primary function: set information necessary for binhed --- This routine is intended to be used in standalone programs. --- This routine should not be linked into the ANSYS program. *** Notice - This file contains ANSYS Confidential information *** typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout

input arguments: variable (typ,siz,intent) description title (chr*80,ar(2),in) - main title and 1st subtitle jobnam (chr*8,sc,in) - Jobname units (int,sc,in) - units = 0 - user defined units = 1 - SI = 2 - CGS = 3 - British, using feet = 4 - British, using inches code (int,sc,in) - code defining 3rd party vendor (contact ANSYS, Inc. for code assignment) output arguments:

none

2.1.9 Subroutine binhed (Writing the Standard ANSYS File Header)

c c c c c 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) - block number of open binary file c (as defined with subroutine binset) c nunit (int,sc,in) - the unit number for this 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 filpos (int,sc,out) - the position after the header c buffer (int,ar(*),inout) - work array for paging c c ********** ANSYS standard header data description (100 words) ********** c loc no. words contents c 1 1 fortran unit number c 2 2 file format c = 0 - internal format c = 1 - external format c 3 1 time in compact form (ie 130619 is 13:06:19) c 4 1 date in compact form (ie 901023 is 10/23/90) c 5 1 units c = 0 - user defined units c = 1 - SI c = 2 - CSG c = 3 - British, using feet c = 4 - British, using inches c 10 1 revision in text format ' 5.0' (inexc4) c 11 1 date of revision release for this version c 12 3 machine identifier - 3 4-character strings c 15 2 Jobname - 2 4-character strings c 17 2 product name - 2 4-character strings c 19 1 special version label - 1 4-character string c 20 3 user name - 3 4-character strings c 23 3 machine identifier - 3 4-character strings c 26 1 system record size at file write c 27 1 maximum file length c 28 1 maximum record number subroutine binhed (nblk,nunit,filpos,buffer) *** primary function: put standard header on a binary file, all permanent binary files should have this header *** secondary functions: return the first data position --- This routine is intended to be used in standalone programs. --- This routine should not be linked into the ANSYS program.

c 41 c 61 c 100 c

20 20 1

main title - 20 4-character strings first subtitle - 20 4-character strings 654321 (undocumented) for an ansys file

2.1.10 Subroutine binrd (Reading Data from a Buffered File)

c c c c c c c c c c c c c c c c c c c c c c c c c c c subroutine binrd (nblk,loc,leng,ivect,kbfint,buffer) *** primary function: buffer read routine --- This routine is intended to be used in standalone programs. --- This routine should not be linked into the ANSYS program. *** Notice - This file contains ANSYS Confidential information *** typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout

input arguments: variable (typ,siz,intent) nblk (int,sc,in) loc leng buffer

description - block number (as defined with subroutine binset) (int,sc,inout) - current pointer to buffer (int,sc,inout) - expected record length (int,ar(*),inout) - work array for paging, should be the same array as used in binset

output arguments: variable (typ,siz,intent) loc (int,sc,inout) leng (int,sc,inout) ivect kbfint

buffer

description - new pointer to buffer - actual record length = 0 - end of file was reached (int,ar(*),in) - vector containing record read (int,sc,out) - dp or integer flag = 0 - double precision buffer > 0 - length of integer buffer (int,ar(*),inout) - work array for paging

2.1.11 Subroutine binwrt (Writing Data to a Buffered File)

subroutine binwrt (nblk,loc,leng,ivect,kbfint,buffer) c *** primary function: buffer write routine c --- This routine is intended to be used in standalone programs. c --- This routine should not be linked into the ANSYS program. 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) - block number c (as defined with subroutine binhed) c loc (int,sc,inout) - current location in buffer array c leng (int,sc,in) - record length (num words to read)

c c c c c c c c c c c

kbfint

(int,sc,in)

buffer

- dp/integer flag = 0 - double precision buffer > 0 - length of integer buffer (int,ar(*),inout) - work array for paging, should be the same array as used in binset on this block

output arguments: variable (typ,siz,intent) description loc (int,sc,inout) - new location in buffer array ivect (int,ar(*),out) - vector containing record to be written buffer (int,ar(*),inout) - work array for paging

2.1.12 Subroutine exinc4 (Decoding an Integer String into a Character String)

c c c c c subroutine exinc4 (ichext,chin,n) primary function: decode externally formatted integer versions of 4-character strings to plain 4-character strings (used to convert data from externally formatted files to data for interally formatted files) secondary functions: none

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout

input arguments: variable (typ,siz,intent) ichext (int,ar(n),in) n (int,sc,in)

description - externally formatted integer form of 4-character strings - number of strings to convert

output arguments: variable (typ,siz,intent) chin (char,ar(n),out)

description - strings in character form

2.1.13 Subroutine inexc4 (Coding a Character String into an Integer String)

subroutine inexc4 (chin,ichext,n) c primary function: encode plain 4-character strings into externally formatted c integer versions of 4-character strings (used to convert c data from internally formatted files to data for externally c formatted files) 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 chin (char,ar(n),out) - strings in character form

c c c c c c c c c

(int,sc,in)

- number of strings to convert

output arguments: variable (typ,siz,intent) ichext (int,ar(n),in)

description - externally formatted integer form of 4-character strings

#include "impcom.inc"

2.1.14 Subroutine binclo (Closing or Deleting a Blocked Binary File)

c c c c c subroutine binclo (nblk,stat,buffer) *** primary function: close a blocked file, every block/file opened with binset should be closed with binclo *** secondary function: the file can be deleted by specifying 'D' in stat --- This routine is intended to be used in standalone programs. --- This routine should not be linked into the ANSYS program.

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

2.2 Demonstration Routines

The bintst program and the bintrd and bintwr routines demonstrate several ways to use the binary file access routines provided with ANSYS. The program and two routines described below (all available on your distribution medium), demonstrate other tasks that the binary access routines can do.

2.2.1 Program bintst (Demonstrates Dumping a Binary File and Copying It for Comparison Purposes)
The bintst program dumps a binary file with the name file.rst to the screen. It then takes that file, copies it to a new file, file2.rst, and dumps the new file to the screen for comparison purposes.

2.2.1.1 Common Variables:

Variable Type, Size, intent Description iout intpdp lenfrm reclng int, sc, comm int, sc, comm int, sc, comm int, sc, comm The output unit number The number of integers per double precision word The number of characters in the filename The system record length

Note-The bintst program is not part of the binlib.a library. It is included here only to aid you.

2.2.2 Subroutine bintrd (Demonstrates Printing a Dump of File Contents)

subroutine bintrd (pname) c *** primary function: bin file dump utility 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 pname (chr,sc,in) - name of binary file which is to c be dumped to the screen c c output arguments: c none. c c common variables: c iout (int,sc,comm) - output unit number c intpdp (int,sc,comm) - number of integers per double precision word c lenfnm (int,sc,comm) - number of characters in the filename c reclng (int,sc,comm) - system record length c c NOTE: bintrd is not part of binlib.a. it is c included only as an aid to users. 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. Both subroutines require the following common:
G G G G

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.

2.2.3 Subroutine bintwr (Demonstrates Copying Binary File Contents)

subroutine bintwr (pname,nname) c *** primary function: bin file copy utility 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 pname (chr,sc,in) - name of binary file which is to be copied c c output arguments: c variable (typ,siz,intent) description c nname (chr,sc,out) - name of new binary file which is a copy c of pname c common variables: c iout (int,sc,comm) - output unit number c intpdp (int,sc,comm) - number of integers per double precision word c lenfnm (int,sc,comm) - number of characters in the filename c reclng (int,sc,comm) - system record length c c NOTE: bintwr is not part of binlib.a. it is c included only as an aid to users.

2.2.4 Program wrtsub (Demonstrates Writing an ANSYS Substructure File)

program wrtsub c primary function: c secondary function: demonstrates use of binary access routines write an ANSYS substructure file

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c ********************************************************************* * Program to write ANSYS substructure file with usrsub. To be * * used as a base for 3rd party companies to create their routines * * for writing the file. * ********************************************************************* * This program is for use in ANSYS Rev 5.x * ********************************************************************* input arguments: jobnam jobname of problem pname name of substructure file to be created units units of the problem 0 - user defined 1 - si 2 - csg

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

nmat

nrow nfor nnod kuns thsubs dimkey

nodes(nrow) direct(nrow)

ldof(nrow) k(nrow,nrow) m(nrow,nrow) c(nrow,nrow) g(nrow,nrow) for(nrow) title nodlst(nnod) xyzang(6,nnod) output arguments:

3 - british using feet 4 - british using inches number of matrices: 1 - stiffness only 2 - stiffness and mass 3 - stiffness, mass, and damping 4 - stiffness, mass, damping, and stress stiffness number of rows in substructure matrices number of load vectors number of unique nodes 0 - symmetric matrices 1 - unsymmetric matrices 0 - structural substructure 1 - thermal substructure dimensionality key 1 - axisymmetric 2 - 2d 3 - 3d list of substructure nodes BY row list of substructure degrees of freedom by row (4 characters, upper case, left justified) (see idhed for possibilities) scratch array of integer DOF numberS stiffness matrix (symmetric) mass matrix (symmetric) damping matrix (symmetric) stress stiffening matrix (symmetric) matrix of load vectors (one column per vector) title for substructure array of unique nodes (order is insignficant) node locations in nodlst order none

2.2.5 Program rdsubs (Demonstrates Reading a Substructure File)

Subroutine rdsubs demonstrates how you read an ANSYS substructure file. This demonstration program can handle up to MAXNODE nodes and MAXDOF degrees of freedom.

2.2.6 Program rdfull (Demonstrates Reading and Reformatting the .FULL File)
Subroutine rdfull demonstrates how to read and reformat the .FULL file. ANSYS writes the full file if the PSOLVE,ELFORM, PSOLVE,ELPREP, PSOLVE,TRIANG sequence is used. 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.

2.3.1 Requirements for Using the Routines

To use the results file access routines, you must do the following:
G

Define the contents of the following common:

COMMON / SYSCM / INTPDP,NBLK

G

Use the rhdiqr routine first to set the required pointers.

2.3.2 Function rhdiqr (Retrieving Model Information from the Results File Header)
function rhdiqr (maxn,nnod,maxds,numdof,maxe,nelm,antyp,nsets, x iwork) c *** primary function: read a results file header and return model c information 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 iwork (int,ar(*),inout) - work array for paging when reading file c (should be the same array used with c subroutine binset) c c output arguments: c variable (typ,siz,intent) description c rhdiqr (int,func,out) - error flag c = 0 - no errors c = 1 - error on reading header c maxn (int,sc,out) - max node no c nnod (int,sc,out) - no of nodes c maxds (int,sc,out) - maximum no. of data sets c numdof (int,sc,out) - no of dof/node c maxe (int,sc,out) - max elem no c nelm (int,sc,out) - no of elements c antyp (int,sc,out) - analysis type c nsets (int,sc,out) - no of data sets on file c 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.

2.3.4 Function rgmiqr (Retrieving Geometry Summary Information from the Results File)
function rgmiqr (maxet,maxrl,maxcs,csysiz,nodelm,etysiz,rlsiz, x iwork) c *** primary function: return information from the results file c geometry header c *** secondary functions: node 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 iwork (int,ar(*),inout) - work array for paging when reading file c c output arguments: c variable (typ,siz,intent) description c rgmiqr (int,func,out) - error flag c = 0 - no errors c = 1 - error in reading file c maxet (int,sc,out) - max no of element types

c c c c c c

maxrl maxcs csysiz nodelm etysiz rlsiz

(int,sc,out) (int,sc,out) (int,sc,out) (int,sc,out) (int,sc,out) (int,sc,out)

max no of real const sets max no of coordinate systems no of items describing a coord system max no of nodes for any defined element no of items describing an element type no of items in a real const set

2.3.5 Function rgmget (Retrieving Geometry Information from the Results File)
function rgmget (key,num,iarry,ivect,iwork) c *** primary function: return information from a results file c geometry record 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 element type data c = 2 - return real const data c = 3 - return coordinate system data c = 4 - return nodal points coordinates and c rotation angles c = 5 - return element data c num (int,sc,in) - number of entity for which you want c information. i.e. num=3 returns info about c the 3rd element type, real const set, cs, etc. c for key=4, num will be ignored c ivect (int,ar(*),inout) - work array for reading indices c iwork (int,ar(*),inout) - work array for paging when reading file c c output arguments: c variable (typ,siz,intent) description c rgmget (int,func,out) - > 0 - number of items returned c = 0 - no information found c =-1 - error c iarry (int,ar(*),out) - requested information

2.3.6 Function rlsfnd (Retrieving Data Set Numbers for Load Steps or Substeps)
function rlsfnd (key,ls,iter,timfrq,kcmplx,ivect,iwork) c *** primary function: given a load step/substep nos, cumlative c iteration no, or a time/freq, return the c data set number c c *** Notice - This file contains ANSYS Confidential information *** c

c c c c c c c c c c c c c c c c c c c c c c c c c

typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) key (int,sc,in)

siz=sc,ar(n)

intent=in,out,inout

ls iter

(int,sc,in) (int,sc,in)

timfrq kcmplx

(dp,sc,in) (int,sc,in)

ivect iwork

(int,ar(*),inout) (int,ar(*),inout) -

description search key = 1 - search by load step/substep nos = 2 - search by cumlative iter no = 3 - search by time/freq load step no (used only for key=1) iteration number key = 1 - substep no = 2 - cumlative iter no time/freq value complex key = 0 - return real solution = 1 - return imaginary solution working array for reading indices work array for paging when reading file

output arguments: variable (typ,siz,intent) rlsfnd (int,sc,out)

description - info about the = 0 - data set > 0 - data set < 0 - error in

search not found on file no. reading file

2.3.7 Function rlsiqr (Retrieving Model Information From the Results File Header)
function rlsiqr (dsno,lstep,itter,ncumt,time,nrf,nnc,nnf,nmas, mode,isym,kcmplx,numdof,nconv,title,ivect,iwork,stitle) c *** primary function: return information from the result file'S c load step header 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 dsno (int,sc,in) - data set no. c ivect (int,ar(*),inout) - work array for reading data set index c iwork (int,ar(*),inout) - work array for paging when reading file c c output arguments: c variable (typ,siz,intent) description c rlsiqr (int,func,out) - error flag c = 0 - no error c = 1 - error c lstep (int,sc,out) - load set no. c itter (int,sc,out) - iteration no. c ncumt (int,sc,out) - cumulative iteration no. c time (dp,sc,out) - time c nrf (int,sc,out) - no. of reaction forces x

c c c c c c c c c c c c

nmas mode isym kcmplx

(int,sc,out) (int,sc,out) (int,sc,out) (int,sc,out)

numdof nconv

(int,sc,out) (int,sc,out)

title stitle

(chr*80,sc,out) (chr*80,sc,out)

no. of master dofs mode no. for harmonic loading symmetry conditon for harmonic loading complex key = 0 - real solution = 1 - imaginary solution no. of dof/node for this load set convergence key = 0 - no convergence for this load step = 1 - this load step converged title for this load set subtitle for thie load set

2.3.8 Function rnsget (Retrieving Nodal Solution Data from the Results File)
function rnsget (dsno,key,iarry,ivect,iwork) c *** primary function: returns a load case'S NODAL DATA FROM THE c results file 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 dsno (int,sc,in) - data set no. c key (int,sc,in) - type of data requested c = 1 - return dof/node list c = 2 - return react force nodes & dof id c = 3 - return react force values c = 4 - return nodal constraints nodes & dof id c = 5 - return nodal const values c = 6 - return input nodal forces nodes & dof id c = 7 - return input nodal forces values c = 8 - return master dof nodes & dof id c = 9 - return nodal solution c ivect (int,ar(*),inout) - work array for reading data set indix c iwork (int,ar(*),inout) - work array for paging when reading file c c output arguments: c variable (typ,siz,intent) description c rnsget (int,func,out) - status of read c =-1 - error on read c = 0 - no info found c > 0 - number of items found c iarry (int,ar(10),out) - requested information c

2.3.9 Function resget (Retrieving Element Solution Data from the Results File)

function resget (dsno,key,elem,darry,ivect,iwork) c *** primary function: returns a load case's element data from the c results file 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 dsno (int,sc,in) - data set no. c key (int,sc,in) - type of data requested c = 1 - return summable misc data c = 2 - return nodal forces c = 3 - return nodal comp stresses c = 4 - return volume and energies c = 5 - return nodal gradients c = 6 - return elas strains c = 7 - return plast strains c = 8 - return creep strains c = 9 - return thermal strains c = 10 - return euler angles c = 11 - return nodal fluxes c = 12 - return local forces c = 13 - return non-summable misc data c = 14 - return elem current density c = 15 - return nonlinear data c = 16 - return calc heat generations c = 17 - return elem temp's c elem (int,sc,in) - elem no. c ivect (int(ar(*),inout) - working array for reading indices c iwork (int,ar(*),inout) - work array for paging when reading file c c output arguments: c variable (typ,siz,intent) description c rlnget (int,func,out) - status of read c =-1 - error on read c = 0 - no info found c > 0 - number of items returned c darry (int,ar(10),out) -

Go to the beginning of this chapter

Chapter 3: Using CDREAD and CDWRITE

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4

3.1 Using the CDREAD Command

The CDREAD command and its GUI equivalent, Main Menu>Preprocessor>Archive Model>Read, read a file of model and database information into the ANSYS database. The commands and menu paths listed below define the input data that the ANSYS program requires to solve a model. If the file you're reading into the database via CDREAD or Main Menu>Preprocessor>Archive Model>Read doesn't contain all of the required input data, you can use these commands or menu paths to define that data in the preprocessor. For detailed information about the commands, see the ANSYS Commands Reference. In the following list, commands or menu paths shown with an asterisk (*) are the minimum requirements for a solution. Command Equivalent Menu Path Definition Enters the general preprocessor Defines the element types Defines the material properties Defines a table of material temperatures

/PREP7*

Main Menu>Preprocessor*

ET*

Main Menu>Preprocessor>Element Type>Add*

MP*

Main Menu>Preprocessor>Material Props*

MPTEMP Main Menu>Preprocessor>Temp Table

MPDATA Main Menu>Preprocessor>Material Props>Prop Table

Defines a table of material properties Defines nonlinear material data, some element data, or both Defines element real constants

TB

Main Menu>Preprocessor>Material Props>Data Tables

Main Menu>Preprocessor>Real Constants

LOCAL

Utility Menu>WorkPlane>Local Coordinates>Create Local Defines a local coordinate CS>At Specified Loc system Main Menu>Preprocessor>Create> Nodes>In Active CS or On Working Plane

N*

Defines a nodal location

E or EN*

Main Menu>Preprocessor>Create> Elements>Thru Nodes

Defines an element. (You must set the correct TYPE, MAT, REAL, and ESYS pointers before defining the element.) Defines the analysis type. See the ANSYS Commands Reference for details. Defines master degrees of freedom Defines the acceleration vector Defines degree of freedom constraints

ANTYPE Main Menu>Preprocessor>-Loads->New Analysis

Main Menu>Preprocessor>-Loads->Master DOFs>Define

ACEL

Main Menu>Preprocessor>-Loads->Apply>Gravity

D*

Main Menu>Preprocessor>-Loads>Apply>constraint Main Menu>Preprocessor>-Loads>Apply>force type>On entity

Defines nodal forces

SF or SFE

Main Menu>Preprocessor>-Loads_ >Apply>surface load type>On entity Main Menu>Preprocessor>-Loads>Apply>load type>On entity

Defines surface loads on element faces Defines body forces on elements

BF or BFE

3.1.1 Tips for Reading Files with CDREAD

The following list describes practices to follow when reading files with CDREAD or its menu path equivalent:
G

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:

/COM, READING NODES N,1,..... , , /COM, READING ELEMENTS EN,1,.....

G

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.

3.2 Using the CDWRITE Command

To export a model from the ANSYS program to another application, use menu path Main Menu>Preprocessor>Archive Model>Write or the CDWRITE command within the general preprocessor, PREP7. This produces a coded database file called Jobname.cdb. You specify the jobname using Utility Menu>File>Change Jobname or the /FILNAM command. If you supply no jobname, the ANSYS program uses the default name "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),

3.2.1 Customizing Degree of Freedom Labels: the /DFLAB Command

The ANSYS program uses a set of default labels for the degrees of freedom. You use these labels when entering boundary conditions, or ANSYS uses the labels when writing the Jobname.cdb file. 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. The format for the /DFLAB command is: /DFLAB,NDOF,LabD,LabF NDOF ANSYS degree of freedom number (1 to 32) LabD Displacement degree of freedom label to be assigned (up to four characters) LabF Force label to be assigned (up to four characters) 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: DOF Number Corresponding Displacement Label Corresponding Force Label

1 2 3 4 5 6 7 8 9 10 11 12 19 20 21 22 23 24

UX UY UZ ROTX ROTY ROTZ AX AY AZ VX VY VZ PRES TEMP VOLT MAG ENKE ENDS

FX FY FZ MX MY MZ CSGX CSGY CSGZ VFX VFY VFZ FLOW HEAT AMPS FLUX NPKE NPDS

25 26

EMF CURR

CURT VLTG

3.3 Coded Database File Commands

In the coded database file Jobname.CDB, most ANSYS commands have the same format they have elsewhere. (See the ANSYS Commands Reference for command-specific information.) However, the format for some commands differs slightly in the Jobname.CDB file. The format for these commands is described below.

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 NSET Type STLOC The real constant set reference number The type of data to be defined. LOC is the valid label. 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

3.3.2 LOCAL Command

The LOCAL command defines a local coordinate system. The command format in Jobname.CDB is: LOCAL,R5.0,Type,NCSY,CSYTYP,VAL1,VAL2,VAL3 The type of data to be defined. Valid labels are LOC (read in system origin), ANG (read in rotation angles), and PRM (read in system parameters).

Type

NCSY CSYTYP

The coordinate system reference number The coordinate system type (0, 1, 2, or 3) Values to be read

VAL1,VAL2,VAL3

G G

If Type is LOC, values are the system origin in global Cartesian coordinates. If Type is ANG, values are the rotation angles in degrees. If Type is PRM, values are the first and second parameters of the system.

3.3.3 NBLOCK Command

At ANSYS 5.4, the default method for defining nodes in a Jobname.CDB file was changed to a "blocked" format. This greatly reduces the time required to read large models through the CDREAD command. The command syntax is NBLOCK, NUMFIELD, Solkey Format where NUMFIELD The number of fields in the blocked format. The solid model key. The node is part of a solid model if the keyword SOLID appears here. Data descriptors defining the format. For the NBLOCK command, this is always (3i8,6e16.9).

Solkey

Format

The format of the node "block" is as follows:

G G G G G

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 ANG (read in rotation angles). The node number The solid model reference key Line parameter value (0 if not on line) Values to be read VAL1,VAL2,VAL3
G

Type

NODE SOLID PARM

If Type is LOC, values are the system origin in global Cartesian coordinates. If Type is ANG, values are the rotation angles in degrees.

3.3.5 EBLOCK Command

At ANSYS 5.4, the default method for defining elements in a Jobname.CDB file was changed to a a "blocked" format. This greatly reduces the time required to read large models through the CDREAD command. The command syntax is EBLOCK, NUMFIELD, Solkey Format where NUMFIELD The number of fields in the blocked format (the default is 19).

Solkey

The solid model key. The element is part of a solid model if the keyword SOLID appears here. Data descriptors defining the format. For the EBLOCK command, this is always (19i7).

Format

The format of the element "block" is as follows:

G G G G

G G G G G G G G

Field 1 - The material number. Field 2 - The element type number. Field 3 - The real constant number. Field 4 - The section ID attribute (beam section) number. See elements BEAM188 and BEAM189 for more information. Field 5 - The element coordinate system number. Field 6 - The birth/death flag. Field 7- The solid model reference number. Field 8 - The element shape flag. Field 9 - 0 Field 10 - The exclude key (p-elements). Field 11 - The element number. Field 12-19 - The node numbers. The next line will have the additional node numbers if there are more than eight.

The final line of the block is always a -1.

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 attributes) and NODE (read in nodes defining the element). The number of nodes

Type

NUMN

Integer values to be read I1,I2,I3,I4,I5,I6,I7,I8

G

If Type is ATTR, the values are the element attributes. Attributes are in the order: NUMN,MAT,TYPE,REAL,NUMELEMENT,ESYS, Solid_Ref,Birth/Death,Pexclude If Type is NODE, the values are the node numbers.

3.3.7 MPTEMP Command

The MPTEMP command defines a temperature table. You repeat the command until all temperature values are defined. The command format in Jobname.CDB is: MPTEMP,R5.0,LENGTH,STLOC,TEMP1,TEMP2,TEMP3 LENGTH The total number of temperatures in the table 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

3.3.8 MPDATA Command

The MPDATA command defines a material property data table. You repeat the command until all properties are defined. The command format in Jobname.CDB is: MPDATA,R5.0,LENGTH,Lab,MAT,STLOC,VAL1,VAL2,VAL3 LENGTH The total number of temperatures in the table The material property label. See the MP command description in ANSYS Commands Reference for valid labels The material reference number

Lab

MAT

STLOC

The starting location in the table for the next three property values

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 LENGTH NCP Dlab The total number of nodes in the coupled set The coupled node reference number The degree of freedom label for the set

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 Type The type of data to be defined. DEFI is the valid label.

LENGTH The total number of variable terms in the constraint equation NCE CONST The constraint equation reference number The constant term of the equation

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. The alternate format for the CE command is: CE,R5.0,Type,N1,Dlab1,C1,N2,Dlab2,C2 Type The type of data to be defined. NODE is the valid label. N1 The node number of the next term

Dlab1 The DOF label of N1 C1 N2 The coefficient of N1 The node number of the next term

Dlab2 The DOF label of N2 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 NODE The node number Dlab The DOF label

3.3.12 SFE Command

The SFE command defines a surface load. Values associated with this specification are on a new input line with a (4f16.9) format. The command format in Jobname.CDB is: SFE,ELEM,LKEY,Lab,KEY,R5.0

ELEM The element number LKEY The load key associated with this surface load A label indicating the type of surface load: Valid labels are:
G G

Lab

G G G G G

PRES (pressure) CONV (convection) HFLU (heat flux) IMPD (impedance) SEL (substructure load vector) SELV (S. E. load vectors) CHRG (charge density)

KEY

A value key. If it's 1, the values are real (film coefficient if convection). If it's 2, values are imaginary (bulk temperature if convection).

3.3.13 SFBEAM Command

The SFBEAM command defines a surface load on selected beam elements. Remaining values associated with this specification are on a new input line with a (4f16.9) format. The command format in Jobname.CDB is: SFBEAM,ELEM,LKEY,Lab,R5.0,DIOFFST,DJOFFST ELEM LKEY Lab The element number The load key associated with these surface loads A label indicating the type of surface load. PRES (for pressure) is the only valid label.

DIOFFST Offset distance from node I DJOFFST Offset distance from node J

Go to the beginning of this chapter

Chapter 4: ANSYS Graphics File Format

Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4

4.1 Modifying ANSYS Graphics Files

Some ANSYS users may wish to translate ANSYS graphics files to other formats (such as Encapsulated PostScript or AI). If you plan to translate graphics files, this chapter provides some information to help you:
G

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.
G

A description of the format for the ANSYS neutral graphics file. This listing excludes format information for zbuffered graphics, but the PLOT33 program does include a section on z-buffered graphics.

4.2 Pixmap Format for Graphic Display Files

The ANSYS graphics display is KPX pixels high by KPX * 1.33 pixels wide. 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. IX1,IY1 is the lower left corner of the z-buffer image. IX2,IY2 is the upper right corner of the z-buffer image. The image should be mapped to the hardcopy device accordingly. The following graphic illustrates the items described above: Figure 4-1. Display Format for Z-buffered Graphics

4.3 Neutral Graphics File Format

The neutral graphics file is an 80-byte, ASCII coded file with fixed length records. It contains plot directives representing the image of a display, as formed in ANSYS, encoded onto a host-independent, printable character set. 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.

4.3.1 Characters the Graphics File Uses

The host-independent printable character set consists of the ASCII characters listed below:
G G G G

Numerals 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9 Uppercase alphabetic characters A through Z The following characters: $ ( ) * + , - . < = > The space character, " ".

4.3.2 Graphics File Directives

Graphics files contain a set of directives that define various aspects of how ANSYS displays a plot, such as window coordinates, colors for graphs and test, line dimensions, etc. Each directive consists of a command character followed by one or more parameters. Within a graphics file, one directive directly follows the preceding directive. For example, below is the first line of a graphics file: (BBAAA2A0AAAAAAPPPLPO>AP$MEKLKBAJANSYS 5.3$MEKLEFALNOV 15 1996$MEKKOJAI10:01:40 The text of this example line breaks down as follows:

(BBAAA

The Start-Plot directive, beginning with command character. (B, B, A, A, and A are the values of parameters defining the plot environment. (Parameters for all plot directives, and their possible values, are explained later.) The Text-Size directive, which determines the type size of displayed text strings. The 2 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 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 character. AP is a parameter value specifying the color. The first of several Text directives. $ is the command character, MEKLKB are the coordinates for the text, AJ is the number of characters in the string, and ANSYS 5.3 is the text string itself.

2A

0AAAAAAPPPLPO

>AP

$MEKLKBAJANSYS 5.3

$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

4.3.2.1 Parameter Types for Graphics File Directives

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: Parameter Type Parameter Attributes Int Long Byt3 Xy String Valid Parameter Values

1 byte, base 16 (letters A through P) 0 through 15 2 bytes, base 16 (letters A through P) 0 through 255 3 bytes, base 16 (letters A through P) 0 through 65535 6 bytes, base 16 (letters A through P) 0 through 4095, mapped to coordinate space of -1.0 to 1.67 An array of Nchar characters Characters from the common character set.

4.3.2.2 Directive Descriptions

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 keras - Defines whether the display surface is cleared prior to the plot (0 = don't clear the surface, 1 = clear it) kras - Defines whether the display uses raster mode or vector mode (1 = raster mode, 0 = vector mode) Start_Plot ( kcntr - Defines whether the display uses a contour color map or shading color map (1 = contour, 0 = shading) kdocu - Defines whether the Docu column is compressed (1 = don't compress, 0 = compress) ispare - A spare value Window 0 x1,y1, x2,y2 (x and y coordinates) iclra - Sets the color for the displayed area. (See "Color Specification" below.) iclrg - Sets the color for the displayed graph. (See "Color Specification" below.)

Parameter Types

Int, Int, Int, Int, Int

Xy, Xy

Area-Color

<

Long

Graph-Color

Long

Text-Color

>

iclrt - Sets the color for displayed text. Long (See "Color Specification" below.) tsize - Defines the size of displayed text (0 = normal, 1 = small)

Text-Size

Int

Line-Type

ltype - Defines the type of lines used in Int the display (0 = solid, 1 = dashed) lwidth - Defines the width of displayed lines (0 = normal, 1 to 5 = larger line Int size) size - Defines the size of the node marker (0 = the smallest size, 15 = the largest size)

Line-Width

Marker Size

int

Point Move Draw

* . -

x,y - Defines a point at coordinates x,y Xy x,y - Moves to coordinates x,y x,y - Draws a line to coordinates x,y x,y - Sets coordinates for where text will display Xy Xy

Text

nchar - Defines the number of displayed characters string - Defines the text string itself inorm - This value, divided by 255, is cos(), where is the viewing direction and the surface normal of subsequent polygons n - Defines the number of polygon vertices kedge - Defines whether the polygon edge is displayed (0, = don't display edge, 1 = display it) xy1,xyn - Defines coordinates for the polygon

Xy, Long, String

Normal

Long

Polygon

Int, Int, XyXy

No-Op End-Plot

none )

no parameters no parameters kpx - Defines the pixel resolution x1,y1 - Sets coordinates for the lower left corner of the z-buffer image x2,y2 - Sets coordinates for the upper right corner of the z-buffer image

none none

Pixmap

The following three parameters are runlength encoded data which repeats until Byt3, Xy, Xy, Long, Long, all pixels are read in, as defined by the Long, window (X2-X1 + 1) * (Y2-Y1 + 1) n - Defines the number of pixels in a row

inrm - Sets the normal for pixels iclr - Sets the color for the pixmap

4.3.2.3 Color Specification

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 2 3 4 5 6 7 8 9 10 Magenta 11 Yellow-Green 12 Blue 13 Green-Cyan 14 Yellow 15 Dark Gray Light Gray White Red Cyan-Blue Magenta-Red Green Orange

16 : 127 Blue : Cyan : Green 128 : : 255 : Indices 128 through 255 represent the color spectrum used to display the Low (Blue) to High (Red) contour values. : Yellow : Orange : Red Reserved for future use

4.4 Decoding a Graphics File: an Example

The following example shows you the following:
G G G

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

Figure 4-2. Example Display of a Graphics File

4.4.1 The Example Command Stream

To create the graphics display shown in Figure 4-2, you'd issue the following ANSYS commands: /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

4.4.2 Example Graphics File Contents

The commands listed above produce the display shown in Figure 4-2 and the following graphics file:

(BBAAA2A0AAAAAAPPPLPO&#60AA&#62AP$MEKLKBAJANSYS 5.3$MEKLEFALNOV 16 1996$MEK KOJAI15:57:07$MEKKIMAMPLOT NO. 1$MEKKDAAIELEMENTS$MEKJNEAIELEM NUM2 B0AAAAAALPOLPO&#60AB/PP+EBBBHBBHKOGBBHKOGKOGBBHKOG$FPPFPPAB1$AILAILAB1$L HCAILAB2$LHCLHCAB4$AILLHCAB32A0AAAAAAPPPLPO.AAAAAA-LPOAAA-LPOLPO-AAAL PO-AAAAAA>AB$ABLLKBAB1>AP$MEKJBLAGZV =1$MEKILPAJDIST=0.55$MEKIGCAIXF =1.5$MEKIAGAIYF =0.5$MEKHKKAPCENTROID HIDDEN$ABOABOCA ANSYS 5.3 Ex ample Graphics File)

The decoded plot directives are:

(BBAAA 2A 0AAAAAAPPPLPO &#60AA &#62AP $MEKLKBAJANSYS 5.3 $MEKLEFALNOV 16 1996 $MEKKOJAI15:57:07 $MEKKIMAMPLOT NO. $MEKKDAAIELEMENTS $MEKJNEAIELEM NUM 2B 0AAAAAALPOLPO &#60AB /PP 1

Start-Plot: /ERASE, raster mode Text-Size: Default Window: 0.0 4095,3070 Area-Color: Black Text-Color: White Text: 3146 2977 "ANSYS 5.3" Text: 3146 2885 "NOV 15 1996" Text: 3146 2793 "15:57:07" Text: 3146 2700 "PLOT NO. 1" Text: 3146 2608 "ELEMENTS" Text: 3146 2516 "ELEM NUM" Text-Size: Small Window: 0 0 3070 3070 Area-Color: Cyan Normal: 255 Polygon: 279, 279, 2790, 279

+EBBBHBBHKOGBBHKOGKOGBBHKOG 2790,2790 279, 2790 $FPPFPPAB1 $AILAILAB1 $LHCAILAB2 $LHCLHCAB4 $AILLHCAB3 Text: 1535 1535 "1" Text: 139 139 "1" Text: 2930 139 "2" Text: 2930 2930 "4" Text: 139 2930 "3"

2A 0AAAAAAPPPLPO .AAAAAA -LPOAAA -LPOLPO -AAALPO -AAAAAA >AB $ABLLKBAB1 >AP $MEKJBLAGZV =1

Text-Size: Default Window: 0,0 4095,3070 Move: 0,0 Draw: 3070,0 Draw: 3070,3070 Draw: 0,3070 Draw: 0,0 Text-Color: Cyan Text: 27 2977 "1" Text Color: White Text: 3146 2331 "ZV =1" Text: 3146 2239 "DIST=0.55" Text: 3146 2146 "XF =1.5" Text: 3146 2054 "YF =0.5" Text: 3146 1962 "CENTROID HIDDEN"

$MEKILPAJDIST=0.55 $MEKIGCAIXF=1.5 $MEKIAGAIYF =0.5

$MEKHKKAPCENTROID HIDDEN

$ABOABOCA ANSYS 5.3 Example Text: 30 30 "ANSYS 5.3 Example Graphics File" Graphics File ) End-Plot No-Op

4.5 The PLOT33 Program

program plot33 c ********** this program plots all the plots on the coded plot file c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,96 ANSYS,INC. c *********

cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c c c the plot33 program is provided in source format to allow users to c c make any modifications necessary for a particular system. c c c c this standard version may be linked with user-supplied calcomp c c hcbs software (plot, plots, symbol), or other software that uses c c the calcomp subroutine protocol, e.g., hewlett-packard ispp, c c tektronix preview, veratec versaplot, etc. c c c c to work with other plotter software it may be necessary for the c c user to remove the calcomp subroutine calls (plots, plot, and c c symbol) and substitute the subroutine calls appropriate for the c c software being used. c c c c because of the large variety of different plotters used by ansys c c customers, it is not possible for sasi to verify the use of this c c plot33 program with all plotter types. c c c cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c #include "impcom.inc" c external plots,plot,symbol,pl33in,pl33xy,pack integer oufile,i,ibufpl(1),iout,numplt,ipl(80),kerase,krastr, x iclra,iclrg,iclrt,iltyp,inorm,nchar,nvert,kedge,kytsiz real chsize,xp1,x1p2,ysz,xzero,xmin,ymin,xmax,ymax,x,y,xy(2,8) character*80 strng integer infile,inbuf,ibf,ix1,iy1,ix2,iy2,kpx,npix,ntot, x n,iclr,inrm real xsize,ysize common /pl33cm/ xsize,ysize,infile,inbuf,ibf(80) data xzero,xp1,x1p2 /0.0, 0.1, 1.2/ c c ********** set the file number ********** infile = 33 oufile = 77 c ********** define the output file ********** iout = 6 c ********** open the file ********** open (unit=infile,file='FILE33.DAT',status='OLD',iostat=i) if (i .ne. 0) then write (iout,1111) 1111 format (' *** ERROR *** FILE33.DAT DOES NOT EXIST.') go to 999 end if c ********** begin session ********** write (iout,2000) infile 2000 format (/,' ***** BEGIN PLOT33 FROM FILE',i2,' *****') c ********** initialize the plotting device ********** call plots (ibufpl(1),1,oufile) inbuf = 80 xsize = 10.0 ysize = 10.0

numplt = 0 chsize = xp1 c c ********** loop through all the plotting commands 10 continue call pl33in (1,ipl(1)) if (ipl(1) .eq. 0) then ********** end-of-file ********** call plot (xzero,xzero,999) go to 900 else if (ipl(1) .eq. 40) then ********** start plotting ********** call pl33in (5,ipl(1)) kerase = ipl(1) - 65 krastr = ipl(2) - 65 if ((numplt .ge. 1) .and. (kerase .eq. 1)) then ********** advance paper ********** ysz = x1p2 * xsize call plot (ysz,xzero,-3) end if if (kerase .eq. 1) numplt = numplt + 1 else if (ipl(1) .eq. 41) then ********** end plotting ********** inbuf = 80 else if (ipl(1) .eq. 48) then ********** window ********** call pl33in (6,ipl(1)) call pl33xy (ipl(1),xmin,ymin) call pl33in (6,ipl(1)) call pl33xy (ipl(1),xmax,ymax) else if (ipl(1) .eq. 60) then ********** area color ********** call pl33in (2,ipl(1)) iclra = 16 * (ipl(1)-65) + ipl(2) - 65 else if (ipl(1) .eq. 61) then ********** graph color ********** call pl33in (2,ipl(1)) iclrg = 16 * (ipl(1)-65) + ipl(2) - 65 else if (ipl(1) .eq. 62) then ********** text color ********** call pl33in (2,ipl(1)) iclrt = 16 * (ipl(1)-65) + ipl(2) - 65 else if (ipl(1) .eq. 44) then ********** line type ********** call pl33in (1,ipl(1)) iltyp = ipl(1) - 65 else if (ipl(1) .eq. 49) then ********** line width ********** call pl33in (1,ipl(1)) iltyp = ipl(1) - 65 else if (ipl(1) .eq. 51) then ********** marker size ********** call pl33in (1,ipl(1)) iltyp = ipl(1) - 65 **********

else if (ipl(1) .eq. 47) then ********** normal ********** call pl33in (2,ipl(1)) inorm = 16 * (ipl(1)-65) + ipl(2) - 65 else if (ipl(1) .eq. 42) then ********** dot ********** call pl33in (6,ipl(1)) call pl33xy (ipl(1),x,y) call plot (x,y,3) call plot (x,y,2) else if (ipl(1) .eq. 46) then ********** move ********** call pl33in (6,ipl(1)) call pl33xy (ipl(1),x,y) call plot (x,y,3) else if (ipl(1) .eq. 45) then ********** draw ********** call pl33in (6,ipl(1)) call pl33xy (ipl(1),x,y) call plot (x,y,2) else if (ipl(1) .eq. 36) then ********** text ********** call pl33in (6,ipl(1)) call pl33xy (ipl(1),x,y) call pl33in (2,ipl(1)) nchar = 16 * (ipl(1)-65) + ipl(2) - 65 call pl33in (nchar,ipl(1)) call pack (ipl(1),strng,nchar) call symbol (x,y,chsize,strng,xzero,nchar) else if (ipl(1) .eq. 43) then ********** area ********** call pl33in (2,ipl(1)) nvert = ipl(1) - 65 kedge = ipl(2) - 65 do 20 i = 1,nvert call pl33in (6,ipl(1)) call pl33xy (ipl(1),xy(1,i),xy(2,i)) 20 continue elseif (ipl(1) .eq. 50) then ********** set text size key ********** call pl33in (1,ipl(1)) kytsiz = ipl(1) - 65 elseif (ipl(1) .eq. 90) then ********** pixmap [z] ********** call pl33in (15, ipl(1)) kpx = 256*(ipl(1) -65) + 16*(ipl(2) -65) + ix1 = 256*(ipl(4) -65) + 16*(ipl(5) -65) + iy1 = 256*(ipl(7) -65) + 16*(ipl(8) -65) + ix2 = 256*(ipl(10)-65) + 16*(ipl(11)-65) + iy2 = 256*(ipl(13)-65) + 16*(ipl(14)-65) + npix = (ix2-ix1+1)*(iy2-iy1+1) ntot = 0 300 call pl33in (6, ipl(1)) n = 16*(ipl(1)-65) + ipl(2) - 65

ipl(3) -65 ipl(6) -65 ipl(9) -65 ipl(12)-65 ipl(15)-65

c c

inrm = 16*(ipl(3)-65) + ipl(4) - 65 iclr = 16*(ipl(5)-65) + ipl(6) - 65 ntot = ntot + n if (ntot .lt. npix) go to 300 else if (ipl(1) .eq. 32) then ********** no-op ********** else ********** unknown ********** end if go to 10

c c

******** close input file ******** 900 close (unit=infile) write (iout,2001) 2001 format (/,' ***** END OF PLOT33 *****') 999 stop end subroutine pl33in (n,ib) c ********** read in "n" characters and unpack them ********** c ********** into the ascii integer array, "ib(*)". ********** c *** Notice - This file contains ANSYS Confidential information *** external unpack integer n,ib(*),nn,ii,j,k,i character*80 inline integer infile,inbuf,ibf real xsize,ysize common /pl33cm/ xsize,ysize,infile,inbuf,ibf(80) c nn = n ii = 0 10 continue if (inbuf .eq. 80) then read (infile,1000,end=900) inline 1000 FORMAT (A80) call unpack (inline,ibf(1),80) inbuf = 0 end if k = inbuf + nn if (k .le. 80) then do 21 i = 1,nn ib(ii+i) = ibf(inbuf+i) 21 continue inbuf = k else j = 80 - inbuf do 30 i = 1,j ib(ii+i) = ibf(inbuf+i) 30 continue inbuf = 80 nn = nn - j ii = ii + j go to 10 end if go to 999

900 continue ib(1) = 0 inbuf = 80 c 999 return end subroutine pl33xy (ipl,x,y) c ********** get the x,y location of a point ********** c *** Notice - This file contains ANSYS Confidential information *** integer ipl(6) real x,y,x3070 integer infile,inbuf,ibf real xsize,ysize common /pl33cm/ xsize,ysize,infile,inbuf,ibf(80) data x3070 /3070.0/ c x = 256 * (ipl(1)-65) + 16 * (ipl(2)-65) + ipl(3) - 65 x = x * xsize / x3070 y = 256 * (ipl(4)-65) + 16 * (ipl(5)-65) + ipl(6) - 65 y = y * ysize / x3070 c return end subroutine pack(invar,outvar,n) c *** Notice - This file contains ANSYS Confidential information *** c c --- pack ascii data into character data c #include "impcom.inc" c integer invar(*),i,n character*1 outvar(*) c do 10 i = 1, n c must add 128 for prime parity bit outvar(i) = char(invar(i)) 10 continue return end subroutine unpack(invar,outvar,n) c *** Notice - This file contains ANSYS Confidential information *** c c --- unpack character data into ascii data c #include "impcom.inc" c integer outvar(*),i,n character*1 invar(*) c do 10 i = 1, n c must subtract 128 for prime parity bit outvar(i) = ichar(invar(i)) 10 continue return

system

system

end

Go to the beginning of this chapter

UIDL Programmer's Guide Table of Contents Preface

Conventions Used in This Guide About the Programmer's Guide Set

1 What is UIDL?
1.1 What Is the ANSYS UIDL? 1.2 The Structure of UIDL 1.2.1 Control Files 1.2.1.1 Control File Header 1.2.2 Building Blocks 1.2.2.1 Menu Blocks 1.2.2.2 Function Blocks 1.2.2.3 Help Blocks 1.3 Overview of Building Blocks 1.3.1 The Header Section 1.3.2 The Data Controls Section 1.3.3 Ending Line

1.4 General Guidelines for Control Files 1.5 The menulist54.ans File

2 Modifying Menu Blocks

2.1 Creating Menu Blocks 2.1.1 Menu Block Header Section Commands 2.1.2 Menu Block Data Controls Section 2.1.3 Menu Block Ending Line 2.2 General Guidelines for Writing Menu Block Control Files

3 Modifying Function Blocks

3.1 Types of Function Blocks 3.1.1 Function Block Header Section Commands 3.1.2 Function Block Data Control Section Commands 3.1.2.1 General Data Control Commands 3.1.2.2 Command Controls 3.1.2.3 Field Controls 3.1.3 Function Block Ending Line 3.2 General Guidelines for Writing Function Block Control Files 3.3 Sample Dialogs and Function Blocks 3.4 Custom Dialogs 3.4.1 Maintaining the Interface Between UIDL and Custom Dialogs

3.4.2 Example of a Custom Dialog

4 Creating Help Blocks

4.1 Customizing Online Help 4.1.1 Help Block Header Section Commands 4.1.1.1 Creating Internal Names for Help Bocks 4.1.2 Help Block Data Controls Section Commands 4.1.2.1 Setting Data Types 4.1.2.2 Creating Hyperlinks 4.1.3 Help Contents Section 4.1.4 Help Ending Line 4.2 General Guidelines for Writing Help Control Files 4.2.1 Creating Online Help Using ASCII Files 4.2.2 Creating Online Help Using XWD Files 4.2.3 Creating Printable Help Pages Using PostScript Files

5 Advanced Topics
5.1 Using ANSYS Parameters for Data Flow 5.2 Suppressing ANSYS Commands 5.2.1 General Guidelines for Command Suppression 5.2.2 Examples of Command Suppression

5.3 Chained Function Blocks

6 Programming Example Appendix A UIDL Command Dictionary

A.1 UIDL Commands and Controls Symbols A B C D E F G H I K L M N P R

S T U X

Appendix B ANSYS Keywords

B.1 List of Keywords and Settings B.1.1 Global Keywords B.1.2 Discipline and Preference Keywords B.1.3 Analysis Type and Option Keywords B.1.4 Solution/Results Keywords B.1.5 Miscellaneous Keywords B.1.6 Element-Specific Keywords B.2 Logic Used for Keyword Evaluation

Appendix C ANSYS Product Codes

C.1 ANSYS Product Codes

Appendix D Testing and Troubleshooting

D.1 Testing and Verification D.1.1 Testing a Building Block

D.1.2 Debugging and Keywords D.1.3 Verifying a Building Block D.2 Troubleshooting D.2.1 Troubleshooting Dialogs

Appendix E Additional Help Tools

E.1 Downloading the Additional Help Tools

Preface Conventions Used in This Guide

This guide uses the following typographic conventions to indicate various types of information: Convention Indicates ANSYS commands. These are shown as uppercase, bold text (for example, K, DDELE, etc.). In the online documentation, these provide hyperlinks to the appropriate command reference information. Menu paths (sometimes referred to as GUI paths). These are shown as bold text with mixed-case, separated by angle brackets ">". An angle bracket indicates a branch to a new menu item. File names, which may or may not include directory paths. These are shown as lower-case, bold text, unless case is significant. Examples are shown with the UNIX directory separator character "/" (slash); if you are using a Microsoft Windows system, use "\" (backslash) as your directory separator character. Arguments for numeric values (such as VALUE, INC, TIME) in command syntax. These are shown as upper-case italic text. On some commands, non-numeric convenience labels (for example, ALL and P) can also be entered for these arguments. Arguments for alphanumeric values (for example, Lab or Fname) in command syntax. These are shown in mixed-case, italic letters. The guide also uses italic text for emphasis. The name of an ANSYS manual. Command input listings, ANSYS output listings, and text that a user enters are shown in fixed-width font.

COMMAND

Menu > Item

path/filename.ext

ARGUMENT

Argument

ANSYS Guide Title

command,arg1,arg2

Note-

Information that supplements the main topic being discussed, such as important tips or guidelines. Actions or situations that could cause problems, unexpected ANSYS behavior, or unexpected results. Actions or situations that can shut down ANSYS, damage files, cause loss of data, etc.

Caution:

Warning:

About the Programmer's Guide Set

The ANSYS programmer's guide set provides information about the various programming interfaces available to customers. These manuals assume that you have at least a basic knowledge of programming (a working knowledge of Fortran 77 would be very helpful). The set of four manuals includes: The APDL Programmer's Guide 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 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. Guide To ANSYS User Programmable Features 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. Guide to Interfacing with ANSYS

This guide describes a group of utilities as well as a set Fortran 77 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. 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. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

1.1 What Is the ANSYS UIDL?

The ANSYS User Interface Design Language (UIDL) is a programming language that lets you customize many components of the ANSYS Graphical User Interface (GUI). The configurable components include:
G G G

Items on the ANSYS Main Menu Dialogs, including picking dialogs Online help

Customizing the GUI lets you modify many ANSYS menus and dialogs and integrate locallydeveloped programs into the ANSYS environment.

1.2 The Structure of UIDL

Each UIDL program consists of a control file header and a series of "building blocks." A building block is a series of UIDL commands, used to create a component of the GUI. There are three types of building blocks:
G G G

menu blocks, for creating menus function blocks, for creating dialogs help blocks, for displaying online help

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: 1. Create at least one new control file and save it to a subdirectory.

2. Copy the control file to the directory where your copy of the menulist55.ans file resides. 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.

1.2.1 Control Files

A control file consists of a control file header and at least one building block. A control file name always ends with the extension .GRN, except for the control files for online help, which end in .HLP or .HPS. ANSYS uses control files to build all the standard dialogs, online help and menus. The control files are stored in the /ansys55/docu directory. These files are extremely useful in helping you get started with UIDL since they contain many examples of how to code menus, dialogs and help files in UIDL. Here is a list of some of the standard ANSYS control files and the component of the GUI they build: UIFUNC1.GRN GUI Functions UIFUNC2.GRN GUI Functions UIMENU.GRN ANSYS Menus 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. Here is a list of the standard ANSYS help control files: UICMDS.HLP UICMDS.HPS Command Help UIELEM.HLP UIELEM.HPS Element Help UIGUID.HLP UIGUID.HPS GUI Help UITHRY.HLP UITHRY.HPS Theory Help

UIOTHR.HLP UIOTHR.HPS Other Help 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.

1.2.1.1 Control File Header

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 :! Here are brief descriptions of these commands: :F Filename Required; name of the control file, must appear on line 1. 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 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) 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.

:D String

:I 0, 0, 0

:!

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.

1.2.2 Building Blocks

Building blocks follow the control file header in the control file. Building blocks can be menu blocks, function blocks, or help blocks. 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.

1.2.2.1 Menu Blocks

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."

1.2.2.2 Function Blocks

Function blocks control the following:
G G G

Layout and content of the configurable dialogs and prompts Picking operations Hidden operations which build and pass commands from the GUI to ANSYS

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."

1.2.2.3 Help 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:
G G G

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.

1.3.1 The Header Section

All header commands begin with a colon (:). Each header section must begin with a :N command which defines the unique, internal name of the building block. The next command, :S, is a space holder for the index line. This command must have zeros, separated by commas, in columns 9, 16 and 23. Consider creating a one-line file that consists of :S and the 0s and commas in their correct locations. 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.

1.3.2 The Data Controls Section

This section must include at least one data control. The data controls used depend on the type of building block defined by the :T line. In menu blocks, the data control section contains calls to existing menu blocks (Men_String) and to function blocks (Fnc_String). In function blocks, the data control section defines the contents of a dialog. In help blocks, the data control section sets up the contents of the online help. The discussions of each building block type in the following chapters describe which specific data controls to use in each type of block.

1.3.3 Ending Line

A block must always end with the :E END command. At least one separator (:! command) should appear between blocks.

1.4 General Guidelines for Control Files

When creating a control file, always be aware that the UIDL processor inserts additional information in each control file. The processor overwrites all :I and :S command lines with indexing information, and adds the :X command and the internal name of each block to the end of the control file. It is critical that you always save an extra copy of any new control file and block, and store them in a directory other than your working directory or your login directory. Whenever you modify a control file, you must start with a clean copy, not one that ANSYS has modified. 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: 1. The current working directory 2. The user's home login directory 3. The docu directory 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.

Go to the beginning of this chapter

Chapter 2: Modifying Menu Blocks

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

2.1 Creating Menu Blocks

You can use UIDL to modify existing ANSYS menus or to create new ones. This chapter documents how to modify or create menus. 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. Figure 2-1 Menu Block for the TimeHist Postproc Menu

This example also shows the use of a simple APDL routine in the header section, which is used to determine the current ANSYS routine, and, if it is not in /POST26, it will enter the Time-History Postprocessor. See the APDL Programmer's Guide for more information. The :C UIDL command calls ANSYS commands, which include APDL routines, user-programmable functions and external libraries. 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.

2.1.1 Menu Block Header Section Commands

The header section of the menu block uses the UIDL commands which begin with a colon (:). The following commands are valid in the header section of a menu block: :! Separates menu blocks and designates comments.

:N Men_String

Required; defines the internal name of the menu block. Required; space holder for ANSYS indexing. The 0s (zeros) must be in columns 9, 16 and 23 and must be separated by commas. Required; defines the type of the block. To define a menu block the string Menu must appear after the :T command. Required; defines the title of the menu block as it appears on a submenu. When the current menu block is called by another menu block, it displays the title of the menu and appends a > to the string. Note-Items listed on a menu under a subhead should be indented by three spaces. Optional; describes the menu block. Optional; executes ANSYS commands, APDL, user-defined functions or external library calls when this menu block is entered. Optional; filters this menu block based on keywords. See Appendix A for a list of ANSYS keywords. Optional; filters this menu block based on product codes. See Appendix B for a list of product codes.

:S 0, 0, 0

:T Menu

:A String

:D String

:C Command String

:K Keyword Logic

:P Product Code Logic

2.1.2 Menu Block Data Controls Section

The data control section of the menu block requires at least one line of information. While you can include many data control commands, you should avoid making a menu too long. When the menu length exceeds the boundaries of the screen, the user cannot access all parts of the menu. Break long menus down into smaller menu blocks. The following data control UIDL commands are valid: Adds the menu block named by String to the menu. The String used in this command 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 command must match a String defined by an :N command in a function block.

Men_String

Fnc_String

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 of the :A string should be indented by three spaces.

String

2.1.3 Menu Block Ending Line

The :E END command always appears in the ending section of every block.

2.2 General Guidelines for Writing Menu Block Control Files

Menu blocks should be stored in their own control files. Do not mix ASCII and binary data in the same control file. If you need to modify a control file that ANSYS has already processed, you must reset all the index strings (the lines beginning with :I and :S) to the sequence of space-holding 0s. You must also delete all the information following the last :E END command near the end of the control file. A line in a control file cannot exceed 80 characters in length. 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.

Go to the beginning of this chapter

Chapter 3: Modifying Function Blocks

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

3.1 Types of Function Blocks

Menu blocks are little more than lists of calls to menus and dialogs, so they are very straightforward to build and modify. Function blocks, however, include extensive functionality for accepting various types of input from users. There are several types of function blocks: 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: Figure 3-3 Function Block for a Hidden Function :N :S :T :A :C :C :C :C :C Fnc_CirBD_3 0, 0, 0 Cmd Hidden (Change Element Color) )! Fnc_CirBD_3 )/nopr )*get,_z(30),graph,,number )/pnum,mat,1 )/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.

3.1.1 Function Block Header Section Commands

The header section of the function block uses the UIDL commands which begin with a colon (:). The header section of the function block can include the following UIDL commands: :! :N Fnc_String Separates function blocks and designates comments. Required; defines the internal name of the function block. Required; space holder for ANSYS indexing. The 0s (zeros) must be in columns 9, 16 and 23 and must be separated by commas. Required; defines the type of the block. To define a function block the string 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 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 of the dialog window. Optional; executes ANSYS commands, APDL, user-defined functions or external library calls when this function block is entered.

:S 0, 0, 0

:T Cmd

:A String

:D String

:C Command

:K Keyword Logic

Optional; filters this function block based on keywords. See Appendix B for a complete list of keywords. Optional; filters this function block based on product codes. See Appendix C for a complete list of product codes. Optional; defines the internal name of the help block which documents the dialog. The procedure for naming and writing help blocks is documented in Chapter 4.

:P Product Code Logic

:H Hlp_String

3.1.2 Function Block Data Control Section Commands

The data control section of the function block supports many data control commands. Each command has been grouped by functionality. For detailed descriptions of each command, see Appendix A, "UIDL Command Dictionary."

3.1.2.1 General Data Control Commands

! Cal_ Defines a comment line Calls another function block; must be used just before the :E END command

Cal_REFRESH Forces a refresh of the lowest active side menu Fmt_H Inp_ P Inp_NoApply K _LN P_LN Forces a narrow dialog Defines picking boxes or hidden function blocks Suppresses the Apply button Sets keyword logic for the next line Sets product code logic for the next line

Pwr_ Rmk_ Typ_Def_ Typ_Lab

Switches FLST and FITEM on and off Forces a rebuild of a dialog after an Apply Defines a default value for a field which is not displayed Displays label without an associated button or entry field

3.1.2.2 Command Controls

Cmd_ Initiates a command sequence K_CM Sets keyword logic for this command P_CM Sets product code logic for this command

3.1.2.3 Field Controls

General Controls Dlm_ Delimits fields Def_ Sets initial default value for the field Fld_ Defines the field number, typically related to the Cmd_ preceding it

K_FL Sets keyword logic for this field P_FL Sets product code logic for this field Prm_ Defines label or prompt to use with this field Picking Controls

Cnt_ Max_ Min_ Pcn_ Pdp_ Pfm_ Rub_ Sel_ Typ_Entity Typ_Resu Typ_XYZ

Sets maximum number of items, except an apply is not done Sets maximum number of items Sets minimum number of items Defines ordered or unordered set Permits duplicate entity picking Controls how picked items are processed Defines the type of rubber banding to use Defines type of selection allowed Gets the numbers of the specified entities Gets the results for a specified entities Gets the coordinates of a point

Typ_XYZ_SCREEN Gets the screen coordinates Typ_XYZ_WP Listing Controls Bnd_LOWER,UPPER Creates bounds for Typ_MLis Typ_Color Typ_Idx Typ_Lis_OptionB Creates an option button of available colors Creates side-by-side scrolling lists from the subsequent Idx_ controls Creates an option button list Gets the working plane coordinates of a point

Typ_Lis_RadioB Typ_Lis Typ_MLis Lis_label,value Lis_*READ,label File Controls Typ_File

Creates a radio button list Creates a single selection scrolling list Creates a multiple selection scrolling list Creates items in the list Defines a list of items from a database

Creates a file selection box with filter, directory and file names

Typ_File_Inline Creates a text entry field for passing a filename to ANSYS Numerical Controls Typ_Int Typ_Int2 Typ_Int3 Creates a single input field for integer data Creates two input fields for integer data Creates three input fields for integer data

Typ_Real Creates a single input field for real number data Typ_Real2 Creates two input fields for real number data Typ_Real3 Creates three input fields for real number data Character Controls Typ_Char Creates an input field for character data Logical Controls

Typ_Logi Creates a toggle button for off and on labels

3.1.3 Function Block Ending Line

The :E END command always appears in the ending section of every block.

3.2 General Guidelines for Writing Function Block Control Files

Function blocks should be stored in their own control files. Do not mix ASCII and binary data in the same control file. If you need to rebuild a new control file from an existing one, you must reset all the index strings (the lines beginning with :I and :S) to the sequence of space-holding 0s. You must also delete all the indexing information following the last :E END command near the end of the control file. Always keep a clean backup copy of every function block. Note-Always copy material from the UIFUNC1.GRN or UIFUNC2.GRN files to create your own function control files. Never modify these files. Here is an example of a function block and the dialog it will produce: 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. Here is a list of guidelines to help you write function blocks:
G G G

G G

G G G G

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

G G

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.

3.3 Sample Dialogs and Function Blocks

Figures 3-5-3-9 display UIDL code for function blocks and the dialogs or picking boxes they create. 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 Idx_Model Idx_Model Idx_Model Idx_Model Idx_Model

data data data data data data

,Volumes ,8 ,For selected set,9 ,Coord systems ,10 ,Element types ,11 ,Real constants ,12 ,Material props ,13 ,Data tables ,14 ,Global measures ,15 ,Nodal results ,16 ,Element results ,17 ,Modal results ,18 ,Elem table data ,19 ,Elem table sums ,20 ,Elem table misc ,21 ,Path operations ,22 ,Other operations,23 ,Time-hist var's ,24 ,Design opt data ,25 ,Parameters ,26 ,Run time stats ,27

Idx_Model data Idx_Results data Idx_Results data Idx_Results data Idx_Results data Idx_Results data Idx_Results data Idx_Results data Idx_Results data Idx_Results data Idx_Results data Idx_Design opt data Idx_Parameters Idx_Run time stats Fld_0 Typ_Sep Fld_0 Typ_Lab Prm_Use Inp_Noapply :E End

to suppress the apply button

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

3.4 Custom Dialogs

Custom dialogs are those dialogs which have been "hard" coded for GUI use. That is, they do not use

the UIDL to create the layout and are usually invoked by issuing a variation of the ANSYS STAT command. The custom dialogs usually call other function blocks and/or ANSYS commands as a result of the user pressing a button in the custom dialog.

3.4.1 Maintaining the Interface Between UIDL and Custom Dialogs

To establish the relationships between the menu blocks and function blocks that call custom dialogs and the custom dialogs that call function blocks and/or commands, always include the following lines in the data controls of the building block that calls a custom dialog: ! Cust_Cal_Fnc_FunctionName Lists the locations of the function in the ANSYS GUI. ! Cust_Cmd_CommandName Lists the locations of the command in the ANSYS GUI.

3.4.2 Example of a Custom Dialog

The following function block calls a custom dialog and then indicates the function block and ANSYS command that the custom dialog will call.

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.

Go to the beginning of this chapter

Chapter 4: Creating Help Blocks

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

4.1 Customizing Online Help

You can use UIDL to create online help for new programming that you have added to ANSYS. This chapter documents how to create online help, using ASCII files or bitmapped (XWD) files. 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.

4.1.1 Help Block Header Section Commands

:N Hlp_String Required; gives the internal name of the help block; see the section on "Creating Internal Names for Help Blocks" below. Required for indexing. Zeros must be in columns 9, 16 and 23.

:S 0, 0, 0

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).

4.1.1.1 Creating Internal Names for Help Blocks

To be able to readily create consistent names for help blocks, ANSYS has adopted the following naming conventions:
G G

Hlp_String for a user-created help block. Hlp_C_ANSYSCommandName for a command documented in the ANSYS Commands Reference (the internal name for the help block for AADD is Hlp_C_AADD). A user can enter Help, ANSYSCommandName in the ANSYS Input Window to display online help about the specified command. Hlp_E_S4.ELEMENTNUMBER for an element documented in the ANSYS Elements Reference (the internal name for the help block for LINK8 is Hlp_E_S4.8). A user can enter Help, ELEMENTNUMBER in the ANSYS Input Window to display online help about the specified element. Hlp_T_SSECTIONNUMBER for a section in the ANSYS Theory Reference (the internal name for help block for Section 12.5 is Hlp_T_S12.5). Hlp_G_GuideCHAPTERNUMBER for the Analysis Guides (the internal name for the help block for Chapter 10 of the ANSYS Modeling and Meshing Guide is Hlp_G_MOD10). Hlp_UI_Widget_Name for a screen in the ANSYS GUI Help Manual (the internal name for the

help block for the Pan Zoom Rotate control panel is Hlp_UI_Pan_Zoom). 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.

4.1.2 Help Block Data Controls Section Commands

The help block data controls section includes the following commands. They must appear in the block in the following order: String Required; defines the title of the help window. Required; points to the previous link for this help block by using the internal name of the help block. If this help block does not link to 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 internal name of the help block. If this help block does not link to another one, leave a blank after the Hlp_ control. The Hps_ control is for printable help on Unix systems only. Required; Data type represents the type of help information: ASCII, POSTSCRIPT or ZBITMAP. BYTES represents the number of bytes in the help contents section. For more information, see Section 4.1.2.1. Note-This string can be replaced by ALIAS, to automatically display the help block defined by Hlp_Next_Block. Hyperlink_text PAGE#, X, Y, WIDTH, HEIGHT Help_block 0, 0, 0, 0 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.

Hlp_Previous_Block or Hps_Previous_Block

Hlp_Next_Block or Hps_Next_Block

Data type BYTES

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.

4.1.2.1 Setting Data Types

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:
G

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.

4.1.2.2 Creating Hyperlinks

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: Figure 4-2 Online Help for the *EXIT Command

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. The hyperlink command has the following format: Hyperlink_text PAGE#, X, Y, WIDTH, HEIGHT Help_block 0, 0, 0, 0
G G G G G G G G

Hyperlink_text is the anchor of the link on the page. PAGE# is the page number of the document starting at 0. X is the x pixel position from the top left corner of the page. Y is the y pixel position from the top left corner of the page. WIDTH is the width of the hyperlink box in pixels. HEIGHT is the height of the hyperlink box in pixels. Help_block is the name of the help block to display when the link is chosen. 0, 0, 0, 0 is a string of place-holding zeros that must end each hyperlink line.

Here are some sample hyperlink codes. In this example, the codes build the links for the online help for the ANSYS *EXIT command: APDL 0, 514, 126, 134, 12 Hlp_C_2.4e 0, 0, 0, 0 Mp 0, 110, 145, 304, 14, Hlp_UI_ProdCodes 0, 0, 0, 0 *ENDDO 0, 304, 207, 54, 12 Hlp_C_*ENDDO 0, 0, 0, 0 *IF 0, 227, 225, 19, 12 Hlp_C_*IF 0, 0, 0, 0 *DO 0, 132, 241, 28, 12 Hlp_C_*DO 0, 0, 0, 0

4.1.3 Help Contents Section

The help contents section does not contain any commands; it only contains the contents of the help window. Always create help contents sections in individual files before merging them with the header, data controls and ending sections to create complete help blocks.

4.1.4 Help Ending Line

The :E END command always appears in the ending section of every block.

4.2 General Guidelines for Writing Help Control Files

Help blocks should be stored in their own control files. Do not mix help, function and menu blocks in the same control file. If you have to recreate a control file from an existing one, you must reset all the index strings (the lines beginning with :I and :S) to the sequence of space-holding 0s (zeros). You

must also delete all the information following the last :E END command near the end of the control file. 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. UIDL supports storing online help content in two different ways:
G G

as text (ASCII data type) as compressed XWD format (ZBITMAP data type)

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:
G G G G

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.

4.2.1 Creating Online Help Using ASCII Files

The ASCII help data type is used for displaying ASCII text as a help page. As of ANSYS 5.4, the ASCII help data type is supported on all Windows and Unix platforms. The following procedure documents how to create online help using ASCII help files: 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. Help for Locally-developed ANSYS Add-ons You'll find more online help about our functions on the Local Functions dialog, which is attached to the ANSYS Main Menu. 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 The following information is displayed: 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. 3. Create a text file (hlp_other1) containing the data controls section. 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: cat hlp_other1 hlp_other2 > hlp_other Windows users can use the DOS copy command: copy hlp_other1 + hlp_other2 hlp_other 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 The following information is displayed: 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. 6. Create a text file (head_other) containing the header section. :N Hlp_O_Contents :S 0, 0, :T HELP 218

7. Create a text file (end) containing the ending section. :E End 8. Create a text file (control_other) containing the control file header: :F OTHER.HLP :D Modified on 1/17 :I 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: cat control_other head_other hlp_other end > OTHER.HLP

Windows users can use the DOS copy command: copy control_other + head_other + hlp_other + end OTHER.HLP 10. Add the file name OTHER.HLP to the end of the menulist55.ans file and start ANSYS to view the new online help.

4.2.2 Creating Online Help Using XWD Files

The ZBITMAP help data type is used for displaying a bitmap image on a screen as a help page. The following procedure documents how to use XWD files in 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 The following information is displayed: 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. 5. Create a text file (hlp_exitst1) containing the data controls section. Commands 3.E *EXIT Hlp_EWRITE Hlp_/EXIT ZBITMAP 5854 89208

APDL 0, 514, 126, 134, 12 Hlp_C_2.4e 0, 0, 0, 0 Mp 0, 110, 145, 304, 14, Hlp_UI_ProdCodes 0, 0, 0, 0 *ENDDO 0, 304, 207, 54, 12 Hlp_C_*ENDDO 0, 0, 0, 0 *IF 0, 227, 225, 19, 12 Hlp_C_*IF 0, 0, 0, 0 *DO 0, 132, 241, 28, 12 Hlp_C_*DO 0, 0, 0, 0 END_OF_HYPERLINKS

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: cat hlp_exitst1 hlp_exitst2.Z > hlp_exitst Windows users can use the DOS copy command: copy hlp_exitst1 + hlp_exitst2.Z hlp_exitst 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 The following information is displayed: 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. 8. Create a text file (head_exitst) containing the header section: :N Hlp_C_*EXIT :S 0, 0, :T HELP,6182

9. Create a text file (end) containing the ending section. :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, :!

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: cat control_exitst head_exitst hlp_exitst end > EXITST.HLP WIndows users can use the DOS copy command: copy control_exitst + head_exitst + hlp_exitst + end EXTIST.HLP 12. Add the file name EXITST.HLP to the end of the menulist55.ans file and start ANSYS to view the new online help. Note-Do not examine the XWD files in a text editor.

4.2.3 Creating Printable Help Pages Using PostScript Files

The PostScript help is used for printing help pages that have been saved in PostScript. Creating PostScript pages for the help system tends to produce cleaner output when a page is printed, and is the only way to generate printable pages in Unix. Both .HLP and .HPS files can be listed in the menulist55.ans file. The following procedure documents how to associate PostScript help files with your 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 The following information is displayed: 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. 5. Create a text file (ps_exitst1) containing the data controls section. Commands 3.E *EXIT Hps_EWRITE Hps_/EXIT POSTSCRIPT 14407 26504 END_OF_HYPERLINKS

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: cat ps_exitst1 ps_exitst2.Z > ps_exitst Windows users can use the DOS copy command: copy ps_exitst1 + ps_exitst2.Z ps_exitst 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 The following information is displayed: 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. 8. Create a text file (headps_exitst) containing the header section. :N Hps_C_*EXIT :S 0, 0, :T HELP,7327

9. Create a text file (end) containing the ending section. :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, :!

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: cat controlps_exitst headps_exitst ps_exitst end > EXITST.HPS Windows users can use the DOS copy command: copy controlps_exitst + headps_exitst ps_exitst end > EXITST.HPS 12. Add the file name EXITST.HPS to the end of the menulist55.ans file and start ANSYS to view the new online help. Note-Do not examine the PostScript files in a text editor. For information about some tools that can help automate the help-building process, see Appendix E, "Additional Help Tools."

Go to the beginning of this chapter

Chapter 5: Advanced Topics

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

5.1 Using ANSYS Parameters for Data Flow

The nine scalar parameters, single array parameter, and single character array parameter listed below are "reserved" for use in the building blocks. They also must be the only parameters used in the building blocks. If you feel that using these parameters is confusing because they're not descriptive, create a correspondence table showing what the parameters map to. _z1 _z2 _z3 _z4 _z5 _z6 _z7 _z8 _z9 _z(i,j,k) _zc(i,j,k) scalar scalar scalar scalar scalar scalar scalar scalar scalar array 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 you use a scalar parameter, initialize it to prevent incorrect values. 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.

5.2 Suppressing ANSYS Commands

To suppress the writing of an ANSYS command to the log file and to the internal database command log, insert a ) (a right parenthesis) immediately before it. You can use this option in the GUI menu blocks to prevent the log file from becoming cluttered with commands (such as the *GET command) used to set up dialog box defaults, temporary UIDL underscore parameters, etc. 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.
G G

The suppressed command is not likely to be used as an abbreviation or macro name. The suppressed command is not required when the log file is run in batch. That is, the output from the batch run of the log file should not be different from that of an interactive run. The suppressed command does not affect any subsequent ANSYS commands that do not use the ) option, and the result of the ) command does not affect any commands issued after it. The result of the suppressed command nullifies only the effect of a previous ANSYS command that did use the ) option.

5.2.1 General Guidelines for Command Suppression

G

The *GET commands and other APDL commands that begin with an * (asterisk) used in preparing defaults for function data fields qualify for using this option. Don't suppress xPLOT, xLIST, etc. commands even though these commands aren't absolutely required for a batch run. You can suppress module name commands (NODE, ELEM, MESH, etc.), and a following STATUS command. Commands on the same line (using $) should individually use this option if they need to be

suppressed. For example, in :C )*GET,_z1,... $*DEL,_z1, the *DEL command will be written to the log file. To suppress both commands, use: H :C )*GET,_z1.... $)*DEL,_z1 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: Suppress command echo Following commands to be suppressed

:C :C :C :C :C :C

)/NOPR )*GET,_z1,.... )*GET,_z2,.... )_z3=_z1+_z2 )*DEL,_z1 )/GO

Resume command echo

5.2.2 Examples of Command Suppression

Valid :C :C )*GET,_z1,...... )*DEL,_z1 Get a value from database. Command nullifies previous *GET.

Invalid :C :C )*GET,_z1,...... N,1,_z1,3,1 Fails Rule 3 (_z1 used subsequently).

Invalid :C :C :C *GET,_z1,.... N,1,_z1,3,1 )*DEL,_z1

Clean-up *GET value that did not use ")".

5.3 Chained Function Blocks

Chained function blocks provide a mechanism for calling different commands or functions based on user input. They can also use hidden dialogs to process data. 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. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

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

Go to the beginning of this chapter

Appendix A: UIDL Command Dictionary

Go to the Next Appendix Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

A.1 UIDL Commands and Controls

This chapter describes the commands and controls for GUI programming. The descriptions include examples of command or control usage, except in cases where you specify only the command or control with no additional arguments.

Symbols
:! String Indicates a comment line or block separator. Header String A string containing 1 to 76 characters. 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 A string containing 1 to 76 characters. Notes Avoid using a !on a line by itself-insert a blank space after the !.

A
:A String Defines the string to display on the menu calling this building block. (Required) Menu Header, Function Header String A 1- to 16-character string which names the menu. If this is a menu building block, a greaterthan 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 Calls the next help block automatically. Help Data Control

Explanation 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 Provides an upper and lower limit for the Typ_MLis control. Function Data Control LOWER,UPPER A lower and upper limit for the multiple list. Both limit values must be double precision numbers.

C
:C Command Specifies a command to be executed upon entry to a building block. 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 Calls another function block, based on an if-test for a specified field. Function Data Control Fnc_Block The internal name of the function block to be called (as defined by a :Ncommand) if the if-test is satisfied. FIELD The number of the field to be evaluated. Oper The comparison operation to use for the evaluation. Valid operations are: EQ, NE, LT, GT, LE, GE, and ES (string equality). VALUE The value with which to evaluate FIELD. 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 The command below calls Fnc_TESTCALL for parameter name='CALL': Cal_Fnc_TEST%name%

Cal_REFRESH Refreshes the lowest active level of the main menu. Function Data Control 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. Function Command Control 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 Note-See "Suppressing ANSYS Commands,"Section 5.2for details on the use of ) and $

Cnt_INTEGER Defines the maximum number of items users can pick for this field, without automatically invoking Apply. Function Picking Data Control 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 This command limits the number of picked keypoints to 8: Cnt_8

*CPAR(N) Retrieves data stored in the *CSET command vector. Function GUI Control (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. Function GUI Control Explanation This command usually is used in conjunction with the Typ_Def_command. 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. Function GUI Control START_LOC An integer between 1 and 150. 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 Names the function block which the custom dialog calls.

Function Data Control Notes This command can only appear after a comment command (!).

! Cust_Cmd_Command_Name Names the ANSYS command which the custom dialog calls. Function Data Control Notes This command can only appear after a comment command (!).

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.) Control File Header, Function Header, Menu Header 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 Defines a default value to be used and displayed in this field. Function Field Control String The String, limited to eight characters in length, may be any of the following:
G

G G G G G

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) Def_*PAR(Parm) Evaluates Parm, which is an ANSYS parameter Gets the field N information from the Typ_XYZ_WP picker, where N is a number from 1 to 9.

Def_*PICK(N)

Def_*PAR(_z1),*PICK(3),5 Def_*CPAR(101) Def_Blank

Used for a triple data type Use the 101 value in the CSET vector Produces a blank input field

Dlm_Character Defines the command field delimiter the UIDL processor will use when building the command to send to ANSYS. Function Field Control 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_ Fld_3 Typ_CHAR Prm_Enter Filename

Note-a single space follows Dlm_

:E END Ends every building block. (Required) 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) Help Data Control Notes Even though only ZBITMAP files can contain hyperlinks, this command must appear in all help block data control sections.

F
:F String Defines the name of the GUI control file. (Required) Control File Header String The name of this control file. 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. Function Data Control 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 *FENTbuilds commands based on data previously stored by the FLSTand FITEMcommands from a previous function block. It is typically used in conjunction with the Typ_Def_command.

Fld_N Specifies the field number Function Field Control 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 Forces narrow horizontal sizing of dialogs. Function Data Control 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.) Menu Data Control 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. Function Data Control 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 *FPIKbuilds commands based on data previously stored by the FLSTand FITEMcommands from a previous function block. It is typically used in conjunction with the Typ_Def_command. Example See Chapter 6for a programming example using *FPIK.

G
*GET(String) Gets a value without first placing it in a parameter. Function GUI Command

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 Hlp_String Points to a help block. 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 Multiple :Hlines are acceptable. To be able to readily create consistent names for help blocks, ANSYS has adopted the following naming conventions:
G G

Hlp_String for a user-created help block. Hlp_C_ANSYSCommandName for a command documented in the ANSYS Commands Reference (the internal name for the help block for AADD is Hlp_C_AADD). A user can enter Help, ANSYSCommandName in the ANSYS Input Window to display online help about the specified command. Hlp_E_S4.ELEMENTNUMBER for an element documented in the ANSYS Elements Reference (the internal name for the help block for LINK8 is Hlp_E_S4.8). A user can enter Help, ELEMENTNUMBER in the ANSYS Input Window to display online help about the specified element. Hlp_T_SSECTIONNUMBER for a section in the ANSYS Theory Reference (the internal name for help block for Section 12.5 is Hlp_T_S12.5). Hlp_G_GuideCHAPTERNUMBER for the Analysis Guides (the internal name for the help block for Chapter 10 of the ANSYS Modeling and Meshing Guide is Hlp_G_MOD10). Hlp_UI_Widget_Name for a screen in the ANSYS GUI Help Manual (the internal name for the help block for the Pan Zoom Rotate control panel is Hlp_UI_Pan_Zoom).

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 Points to a help block. Help Data Control Help_Block The internal name of a help block for ASCII or bitmap help. 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 Points to a help block; used only for printable PostScript help. Help Data Control Help_Block The internal name of a help block for PostScript help. 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 0, 0, 0 Fixed-format placeholder for the UIDL processor-generated index numbers. (Required) Control File Header 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_ Defines categories, items and values for scrolling windows Function Data Control This can only be used with the Typ_Idxcommand. See the Typ_Idxcommand.

Inp_NoApply Suppresses the Apply button in a dialog. Function Data Control 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. Function Data Control 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. Appendix Blists and describes the keywords ANSYS uses. Filtering only works in the first level of the Utility Menu-filtering does not work in cascaded menus. Example The following command specifies that either "PREP7"or"SOLUTION"must be true, and"BEGIN"must be falsein order for the GUI to display the block-ANSYS must be running either in preprocessor or solution mode. :K ((PREP7|SOLUTION)&begin)

K_Type (Keyword Logic) Defines keyword logic that must produce a true result before the identified item will be shown. Function Data Control Type The type of keyword logic used. Possible values are: CM (applies keyword logic to the previous Cmd_) FL (applies keyword logic to the previous Fld_) 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_ Defines items for lists on dialogs. Function Data Control 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. Function Picking Control 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 The following command defines the order of selection as unimportant: Max_s The following command sets the maximum number of picked items at eight: Max_8

Men_String Points to the name of a menu block to display on a menu. Menu Data Control 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 The contents of Stringare defined by a :Ncommand in a menu header.

Min_INTEGER Sets the minimum number of items that users must pick for this field. Function Picking Control

INTEGER 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. Function Picking Control 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 Defines the internal name of a building block. (Required) Header String A unique 1- to 12-character name, prefixed with one of the following: Fnc_, for a function block Men_, for a menu block Hlp_, for a help block (Hps_for printable PostScript files) 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 Product Code Logic 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)

P_Type (Product Code Logic) Defines product code logic that must produce a true result before the identified item will be shown. Function Data Control, Menu Data Control Type The type of product code logic to use. Specify one of the following: CM (product code logic applies to the previous Cmd_) FL (product code logic applies to the previous Fld_) LN (product code logic applies to the following command, no matter what control type it is) Product Code Logic

Product code 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 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. The Product Code Logic string can contain up to 76 characters. Notes Appendix Cof this manual lists the ANSYS product codes.

*PAR(_ZString) Retrieves data stored in a parameter. Function GUI Control _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. Function Picking Control FLAG One of the following values: 0, for an ordered set (default) 1, for an unordered set 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 Function Picking Control FLAG One of the following values: 0, if no duplicates are allowed (default) 1, to allow duplicates of an entity

Pfm_FLAG Controls how the ANSYS program processes picked items.

Function Picking Control FLAG One of the following values: 0, to have the UIDL processor determine if a picked set or the command line should be used (default). 1, to use a picked set (The ANSYS commands FITEMand FLSTwill be used.) 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. Function Picking Control (N) The text field number of the model picker 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 Defines the label (or prompt) to be used with this field. Function Field Control 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: Prm_Specify %num% widgets that are %color%. If the %num%parameter is set to 5 and the %color%parameter is set to green, the text string will read: Specify 5 widgets that are green. Use the %#parameter% to prevent compression of spaces in a character parameter. Example The following command specifies the prompt, "Enter fillet radius."

Prm_Enter fillet radius

Pwr_FLAG Switches the FLST and FITEM off and on for a field. Function Field Control FLAG One of the following: 0, to have FITEMand FLSTwrite the items (default) 1, to disable writing of items by FITEMand FLST Notes This command enables the storage of picked items or coordinates for retrieval by the *FENTor *FPIKcommands.

R
Rmk_ Rebuilds the dialog box after an Apply operation. Function Data Control Notes This control must be the first line of the Data Controls section.

Rub_N Specifies the type of rubber banding to be used in a picking operation.

Function Picking Control N A numeric key from the following list: For Two-dimensional Picking on the Working Plane 1 2 3 4 5 6 7 8 Lines Rectangle (Corner - Opposite Corner) Circle (Center - Radius) Annulus (Center - R1 & R2) Partial Annulus Rectangle (Center - Corner) Circle (On Circle - On Circle) Rectangle (Center - Edge)

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 52 Lines In Active Csys 53 Area In Active Csys 54 Area With Straight Lines For Three-dimensional Picking on the Working Place Plus Z Dimension 101 Polyhedron 102 Block 103 Cylinder-solid 104 Cylinder-hollow 105 Partial Cylinder 106 Block (Center - Corner) 107 Cylinder-solid (On Circle - On Circle) 109 Cone 113 3 Equal-sided Polyhedron 114 4 Equal-sided Polyhedron 115 5 Equal-sided Polyhedron 116 6 Equal-sided Polyhedron

117 7 Equal-sided Polyhedron 118 8 Equal-sided Polyhedron For Electrical Circuits (3 Points to Create) 201 Inductor 202 Capacitor 203 Resistor 204 Circuit 1 205 Circuit 2 206 Circuit 3 207 Circuit 4

S
:S 0, 0, 0 Fixed-format placeholder for the UIDL processor-generated index numbers. (Required) 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 Defines the type of selection picking that is allowed. Function Picking Control FLAG One of the following values: s, to allow only currently selected entities to be picked (default). 1, to pick all defined entities, whether or not they're selected. Use this setting only for retrieval picking. u, to allow picking only entities that currently aren't selected.

Sep_ Displays a separator bar in a menu. Menu Data Control

*Str(String) Passes character information into a field as a character. 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 The following block reads a file into ANSYS: 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 One of the following types: 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. Function Picking Control Entity Use one of the following values for Entity: NODE Pick node numbers from the screen. ELEM Pick element numbers from the screen. KEYP Pick keypoint numbers from the screen.

LINE Pick line numbers from the screen. AREA Pick area numbers from the screen. VOLU Pick volume numbers from the screen. TRAC Pick trace point numbers from the screen. Notes Use this data type only in the Inp_P control mode.

Typ_Char,FIELD1,FIELD2 Creates a text entry field for character data display. Function Character Control FIELD1 An integer between 1 and 80 for maximum character input (defaults to 80). FIELD2 An integer between 1 and 80 for the input field view width (defaults to 32).

Typ_Color Creates an option button with 16 color choices available. Function Listing Control 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 2 MRED 6 CBLU 10 YGRE 14 DGRA 3 MAGE 7 CYAN 11 YELL 15 LGRA 4 BMAG 8 GCYA 12 ORAN 16 WHIT

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 Defines a hidden default value to be used but not displayed. Function Field Control String The String, limited to eight characters in length, may be any of the following:
G G

a numeric value, which sets the default. a *GET value or a *PAR value which overrides previous user values. More properly, though,

G G G G

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. 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_Def_*PAR(Parm) Evaluates Parm, which is an ANSYS parameter Gets the field N information from the Typ_XYZ_WP picker, where N is a number from 1 to 9. Used for a triple data type Use the 101 value in the CSET vector

Typ_Def_*PICK(N)

Typ_Def_*PAR(_z1),*PICK(3),5 Typ_Def_*CPAR(101)

Typ_File Creates the file selection box, which displays the filter, directory, and file name. Function File Control 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. Function File Control 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. Function Listing Control 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 IDX_Attributes IDX_Attributes

,Maj rad of torus,ATTR,PAR1 ,Theta singularit,ATTR,KTHET ,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 Creates a text entry field for displaying integer data. Function Numeric Control 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. Function Numeric Control

Typ_Int3 Creates three side-by-side text entry fields for displaying integer data. Function Numeric Control

Typ_Lab Defines a label data type which is used to display labels without an associated button or entry field. Function Field Control 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 Displays a list of choices for a field. Function Field Control Explanation You can specify a number of types of lists: Single-selection Scrolling Lists Typ_Lis Lis_Item,Value 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. Multiple-selection Scrolling Lists Typ_MLis Lis_Item,Value

Use one Lis_ control for each item. The item name can be up to 16 characters long, and is shown in a scrolling window. The item's associated value is used by the command field. See the Bnd_command to learn how to limit the number of choices. Each item selected is separated by a comma. 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. Database Read, Single-selection, or Multiple-selection Scrolling List Typ_Lis or Typ_MLis Lis_*READ,Item 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: DOF Current degree-of-freedom set F Current force set CM Current defined components ASSM Current defined assemblies ETAB Current element table items PATH Current path items DV Current design variables SV Current state variables OBJ Current objective function PAR Current parameters PARX Current parameters notused as opt. variables FIT Current fitting functions MAT Current material numbers OPTH Current list of paths TYPE Current element types REAL Current real constant numbers

Typ_Logi,Off_Label,On_Label Creates an on/off toggle button. Function Logical Control Off_Label An optional character string containing up to 16 characters. On_Label An optional character string containing up to 16 characters.

Typ_MLis Displays a list of choices for a field, permitting multiple choices. Function Listing Control Explanation See the description of the Typ_Liscontrol for complete information.

Typ_Real Creates a text entry field for real number display. Function Numeric Control

Typ_Real2 Creates two side-by-side text entry fields for real number display. Function Numeric Control

Typ_Real3 Creates three side-by-side text entry fields for real number display. Function Numeric Control

Typ_Resu Enables the user to view results interactively on the screen by picking. Function Picking Control 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 Displays a separator bar in a dialog. Function Data Control Notes This control should follow a Fld_0control. Do not use with prompt mode.

Typ_XYZ Obtains the coordinates of a point in picking mode. Function Picking Control

Notes 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 Obtains the screen coordinates of a point in picking mode. Function Picking Control 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_. Function Picking Control 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 Displays a named file in the ANSYS GUI lister window. GUI Command

Fname The name of the file. Ext The extension of that file. 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. UIDL processor-inserted Command 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.

Go to the beginning of this chapter

Appendix B: ANSYS Keywords

Go to the Next Appendix Go to the Previous Appendix Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

B.1 List of Keywords and Settings

B.1.1 Global Keywords
Command/Status Keyword ANSYS Entry BEGIN 1 system name system dependent If -d X11 If -d X11C If -d X3D GUI on or off Val Keyword Val Comments

"SYSTEM" 1 IEEE X11 X11C X3D LEVEL ANSYS Exit 1/0 1 1 1 1/0

/EXIT,(blank) /EXIT,MODEL /EXIT,SOLU /EXIT,ALL /EXIT,NOSAV /SHOW /SHOW,X11 /SHOW,X11C /SHOW,X3D Routine Entry /PREP7 /SOLU /POST1 /POST26 /OPT /RUNSTAT /AUX2 /AUX12

RESULTS RESULTS N/A N/A N/A

0 0

X11 X11C X3D

1 1 1

X11C&X3D 0 X11&X3D 0

X11&X11C 0

PREP7

BEGIN BEGIN BEGIN BEGIN BEGIN BEGIN BEGIN BEGIN

0 0 0 0 0 0 0 0

Other routine names = 0 Other routine names = 0 Other routine names = 0 Other routine names = 0 Other routine names = 0 Other routine names = 0 Other routine names = 0 Other routine names = 0

SOLUTION 1 POST1 POST26 OPT 1 1 1

RUNSTAT 1 AUX2 AUX12 1 1

/AUX15 Routine Exit FINISH /EOF /QUIT SAVE SAVE RESUME

AUX15

BEGIN

Other routine names = 0

BEGIN BEGIN BEGIN

1 1 1

"ROUTINE" 0 "ROUTINE" 0 "ROUTINE" 0

ROUTINE refers to above items

Write all active keywords to .db file

1. Read keyword settings from .db file RESUME 2. Re-establish the following keywords from the current stat of ANSYS: "routine" = 1 (current routine name) "system" = 1 (current system name) LEVEL = 1/0 (GUI on or off) 1. Set all keywords to zero CLEAR 2. Re-establish the following keywords from the current stat of ANSYS: "routine" = 1 (current routine name) "system" = 1 (current system name) LEVEL = 1/0 (GUI on or off)

/CLEAR

B.1.2 Discipline and Preference Keywords

Command/Status Keyword ET,ETDELE,DOF Val Comments

STRUCTRL 1 THERMAL 1 ELECTRIC 1 MAGNETIC 1 FLUID CFD 1 1

If DOFGRP = n0000 (n>0) If DOFGRP = 0n000 (n>0) If DOFGRP = 00n00 (n>0) If DOFGRP = 000n0 (n>0) If DOFGRP = n000n (n>0) See Element Specific Keywords Any combination of two or more of the above

MULTIFLD 1 Preferences Dialog Box PR_STRUC PR_THERM PR_ELMAG PR_FLUID PR_CFD PR_MULTI PR_SET /PMETHOD PMETHOD 1

These are set to a value of one if they are chosen in the "Preferences" dialog box.

If P-Method is turned on

B.1.3 Analysis Type and Option Keywords

Command/Status SOPTCM Variable Val Keyword DEFAULT ANTYPE ANCONT ANTYPE, STATIC BUCKL MODAL HARMIC TRANS SUBST SPECT NTYPE,, NEW RESTA BUCOPT, REDUC SUBSP EXTOPT EXTOPT 0 1 REDUCED SUBSPACE ANCONT ANCONT 0 1 NEWANLY RESTART ANTYPE ANTYPE ANTYPE ANTYPE ANTYPE ANTYPE ANTYPE 0 1 2 3 4 7 8 STATIC 0 0 STATIC NEWANLY

Val Comments

1 1

BUCKLING 1 MODAL 1 other "ANTYPE" & "options" = 0

HARMONIC 1 TRNSIENT 1

SUBSTRUC 1 SPECTRUM 1

1 1

RESTART = 0 NEWANLY = 0

1 other "options" = 0 1

HROPT, REDUC FULL MSUP MODOPT, REDUC SUBSP UNSYM DAMP TRNOPT, REDUCED FULL MSUP SPOPT, SPRS DDAM MPRS PSD SPANAL SPANAL SPANAL SPANAL 0 1 2 3 SINGLEPT DDAM MULTIPNT 1 1 other "options" = 0 1 TRNOPT TRNOPT TRNOPT 1 0 2 REDUCED FULL MODESUP 1 1 1 other "options" = 0 EXTOPT EXTOPT EXTOPT EXTOPT 0 1 3 4 REDUCED SUBSPACE 1 1 other "options" = 0 UNSYMMET 1 DAMPED 1 HRMOPT HRMOPT HRMOPT 1 0 2 REDUCED FULL MODESUP 1 1 1 other "options" = 0

PSDRANDM 1

EXPASS, ON OFF SRPASS SRPASS 1 other "options" = 0 0

B.1.4 Solution/Results Keywords

Command/Status Solution Complete LSTEPGT1 1 SOLVE or PSOLVE RESULTS 1 Results in Database SET, SUBSET, FLREAD RESULTS 1 Exit from SOLUTION FINISH, /EOF, /QUIT LSTEPGT1 0 Keyword Val

B.1.5 Miscellaneous Keywords

Command/Status Keyword ESHAPE, 0 Not 0 NOMIXMSH 0 NOMIXMSH 1 Val

FMAGBC, command issued otherwise MOPT, AMESH,RV51 AMESH,RV52 MeshTool MOPTRV51 1 MOPTRV51 0 MESHTOOL 1 FMAGBC FMAGBC 1 0

B.1.6 Element-Specific Keywords

Element Type Keyword SOLID5 ELEM3D 1 If KEYOPT(1)= 0, 1, 10 Val Comments

SCALARP 1 ANISO PLANE13 ELEM2D 1 1

VECTORP 1 ANISO 1

If KEYOPT(1) = 0, 4, 6

PLANE53 ELEM2D 1

VECTORP 1 SOLID62 ELEM3D 1

VECTORP 1 SOLID64 ANISO SOLID96 ELEM3D 1 If KEYOPT(2)= 0 If KEYOPT(2)= 1, 2 1

SCALARP 1 VECTORP 1 SOLID97 ELEM3D 1

VECTORP 1 SOLID98 ELEM3D 1 If KEYOPT(1)= 0, 1, 10

SCALARP 1

ANISO INFIN110 ELEM3D

1 If KEYOPT(1)= 0

SCALARP 1 INFIN111 ELEM2D 1

SCALARP 1 VECTORP 1 INTER115 ELEM3D 1

If KEYOPT(1)= 0 If KEYOPT(1)= 1

SCALARP 1 VECTORP 1 FLUID131 CFD FLUID132 CFD FLUID141 CFD 1 1 1

FLUID142 CFD 1

B.2 Logic Used for Keyword Evaluation

GUI Area Element Type No preferences Structural Thermal K_FL(pr_set+pmethod+cfd) K_FL(PR_STRUC+pr_multi+pmethod+cfd) K_FL(PR_THERM+pr_multi+pmethod+cfd) Filtering Used

Electromagnetic K_FL(PR_ELMAG+pr_multi+pmethod+cfd) ANSYS Fluid Multiple K_FL(PR_FLUID+pr_multi+pmethod+cfd) K_FL(PR_MULTI+pmethod+cfd)

CFD FLOTRAN K_FL(PR_CFD*CFD) P-Method Loads / Solution :K (PR_STRUC*pr_set) :K #(STRUCTRL) :K (PR_THERM*pr_set) :K #(THERMAL) K_FL(PMETHOD+pr_cfd+cfd)

Structural

Thermal

Electromagnetic

:K (PR_ELMAG*pr_set) :K #(ELECTRIC*MAGNETIC) :K (PR_FLUID*pr_set) :K #(FLUID) :K (PR_CFD*pr_set) :K #(CFD)

ANSYS Fluid

CFD FLOTRAN

Results Data Utility Menu Dialog Box Structural Thermal :K #(POST1+RESULTS) :K #(POST1+RESULTS) K_FL(STRUCTRL+multifld) K_FL(THERMAL+multifld)

Electromagnetic K_FL((ELECTRIC*MAGNETIC)+structrl+thermal+fluid) ANSYS Fluid K_FL(FLUID+multifld)

CFD FLOTRAN K_FL(CFD) All Disciplines K_FL(MULTIFLD+(STRUCTRL*THERMAL*FLUID))

Results Operations / Categories :K (PR_STRUC*pr_set) :K #(STRUCTRL+RESULTS) :K (PR_THERM*pr_set) :K #(THERMAL+RESULTS) :K (PR_ELMAG*pr_set) :K #((ELECTRIC*MAGNETIC)+RESULTS)

Structural

Thermal

Electromagnetic

ANSYS Fluid

:K (PR_FLUID*pr_set) :K #(FLUID+RESULTS) :K (PR_CFD*pr_set) :K #(CFD+RESULTS)

CFD FLOTRAN

Go to the beginning of this chapter

Appendix C: ANSYS Product Codes

Go to the Next Appendix Go to the Previous Appendix Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

C.1 ANSYS Product Codes

Product Product Codes FULL_ANS LINPLUS THERMAL ANSYS/Multiphysics (Mechanical + Emag 3D+ FLOTRAN) E3 ELECMAG FLOTRAN MULTDISC FULL_ANS LINPLUS THERMAL MULTDISC FULL_ANS LINPLUS LINPLUS LINPLUS THERMAL THERMAL E3 ELECMAG PP FULL_ANS LINPLUS THERMAL E3 ELECMAG FLOTRAN MULTDISC

ANSYS/Mechanical

ANSYS/Structural ANSYS/LinearPlus ANSYS/LinearPlus/Thermal ANSYS/Thermal ANSYS/Emag 3D

ANSYS/PrepPost

ANSYS/University

FULL_ANS LINPLUS THERMAL E3 ELECMAG FLOTRAN MULTDISC FULL_ANS LINPLUS THERMAL E3 ELECMAG FLOTRAN MULTDISC ED FULL_ANS LINPLUS THERMAL E3 ELECMAG FLOTRAN MULTDISC FULL_ANS LINPLUS THERMAL E3 ELECMAG FLOTRAN MULTDISC LSDYNA PP FULL_ANS LINPLUS THERMAL E3 ELECMAG FLOTRAN MULTDISC LSDYNA

ANSYS/ResearchFS

ANSYS/ED

ANSYS/LS-DYNA s (Dyna solver & PrepPost stand-alone)

ANSYS/DYNAPrepPost s (PrepPost stand-alone )

Go to the beginning of this chapter

Appendix D: Testing and Troubleshooting

Go to the Next Appendix Go to the Previous Appendix Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

D.1 Testing and Verification

D.1.1 Testing a Building Block
After a building block is created, you must test it. Follow these testing steps: 1. Create a TEST.GRN control file (see Chapter 1 for control file information). 2. Copy the new building block(s) to TEST2.GRN. 3. Add the name TEST2.GRN to the end of the menulist55.ans file. 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.

D.1.2 Debugging and Keywords

To see the value of keywords, type keyword,stat in the ANSYS Input window. To see the value of product code words, type prdw,stat. To see the values of GUI parameters, type *stat,_parameter. 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 use a ! and a blank on a line without additional characters. Do not edit the control file once it's been indexed by ANSYS. Always edit the clean copy, as described in Chapter 1.

D.1.3 Verifying a Building Block

To verify a building block, examine the ANSYS log file. Make sure that the building block passed the correct information to ANSYS for every option available in that dialog box. 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.

Go to the beginning of this chapter

Appendix E: Additional Help Tools

Go to the Previous Appendix Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Chapter 4 * Chapter 5 * Chapter 6 * Appendix A * Appendix B * Appendix C * Appendix D * Appendix E

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.

E.1 Downloading the Additional Help Tools

1. From a system connected to the Internet, type: ftp ftp.ansys.com Log in as anonymous, and give your E-mail address as the password. 2. Type cd pub/archive/GUI_Tools to access the help tools directory. 3. Type bin and press Enter to set the file type to binary.

4. Type prompt to turn prompting off. 5. Type mget * to download all the files in the GUI_Tools directory. 6. Type quit to close the FTP connection. 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.

Go to the beginning of this chapter

Guide to ANSYS User Programmable Features Table of Contents Preface

Conventions Used in This Guide About the Programmer's Guide Set

1 Using User Programmable Features (UPFs)

1.1 Introduction to UPFs 1.1.1 What Are UPFs? 1.1.2 What You Should Know Before Using UPFs 1.1.3 Planning Your UPFs 1.1.4 Studying the ANSYS User Routines 1.1.5 Programming in Languages Other than FORTRAN 1.1.6 Developing UPFs: a Suggested Strategy 1.1.7 Include Decks 1.1.8 Linking User Routines 1.1.9 Compiling and Linking UPFs on UNIX Systems 1.1.10 Compiling and Linking UPFs on Windows Systems

1.1.11 Activating UPFs 1.1.12 Running Your Custom Executable 1.1.13 Verifying Your Routines 1.1.14 Debugging Commands 1.1.14.1 Tracking the Path of Program Logic 1.1.14.2 Debugging Elements and Solutions 1.1.15 Other Useful Commands 1.1.16 Generating Output 1.2 Reading Large Data Files More Rapidly 1.2.1 EBLOCK Command Format 1.2.2 NBLOCK Command Format 1.3 Routines for Creating New Elements 1.3.1 Input and Output Abbreviations 1.3.2 User Routines 1.3.3 Subroutine uec100 (Defining Characteristics of the usr100 Routine) 1.3.3.1 Subroutines uec101 through uec105 1.3.4 Subroutine uex100 (Overriding Element Characteristic Defaults) 1.3.4.1 Subroutines uex101 through uex105 1.3.5 Subroutine uel100 (Computing Element Matrices, Load Vectors, and Results)

1.3.6 Subroutines uel101 through uel105 1.3.7 Subroutine uep100 (Printing Output for User Elements) 1.3.8 Subroutines uep101 through uep105 1.3.9 Subroutine usertr (Adjusting the Nodal Orientation Matrix) 1.3.10 Subroutine userac (Accessing Element Information) 1.4 Supporting Subroutines for Element Creation 1.4.1 Subroutine nminfo (Returning Element Reference Names) 1.4.2 Subroutine svgidx (Fetching the Index for Saved Variables) 1.4.3 Subroutine svrget (Fetching Saved Variable Data for an Element) 1.4.4 Subroutine svrput (Writing an Element's Saved Variable Set) 1.4.5 Subroutine svpidx (Writing the Saved Variable Element Index to a File) 1.4.6 Subroutine mreuse (Determining Which Element Matrices Can Be Reused) 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.4.9 Subroutine rvrget (Fetching Real Constants for an Element) 1.4.10 Subroutine propev (Evaluating a Group of Material Properties) 1.4.11 Subroutine prope1 (Evaluating One Material Property) 1.4.12 Subroutine pstevl (Evaluating EX, NUXY, GXY, ALPX, and DENS at Element Temperature)

1.4.13 Function gtplop (Retrieving the Start Point for Plastic Data) 1.4.14 Function gtcrop (Retrieving the Start Position for Creep Data) 1.4.15 Function gtswop (Retrieving the Start Position for Swelling Data) 1.4.16 Subroutine tbuser (Retrieving User Table Data) 1.4.17 Subroutine plast1 (Updating an Element's Plastic History) 1.4.18 Subroutine creep1 (Updating an Element's Creep History) 1.4.19 Subroutine swell1 (Updating an Element's Swelling History) 1.4.20 function nlget (Retrieving Material Non-Linear Property Information) 1.4.21 Subroutine usereo (Storing Data in the nmisc Record) 1.4.22 Subroutine eldwrt (Writing Element Data to a File) 1.4.23 Subroutine eldwrn (Writing Element Nonsummable Miscellaneous Data to the Results File) 1.4.24 Subroutine trrot (Computing the Rotation Vector) 1.4.25 Subroutine rottr (Computing the Transformation Matrix) 1.4.26 Subroutine xyzup3 (Updating an Element's 3-D Nodal Coordinates) 1.4.27 Subroutine updrot (Updating the Rotation Pseudovector) 1.4.28 Subroutine tmpget (Defining Current Temperature Loads) 1.4.29 Subroutine prsget (Defining Current Pressure Loads) 1.4.30 Subroutine cnvget (Defining Current Convection Loads) 1.4.31 Subroutine hgnget (Defining Current Heat Generation Loads)

1.5 Routines for Modifying and Monitoring Existing Elements 1.5.1 Subroutine userfd (Computing the Complex Load Vector for Frequency Domain Logic) 1.5.2 Subroutine userou (Storing User-Supplied Element Output) 1.5.3 Subroutine useran (Modifying Orientation of Material Properties) 1.5.4 Subroutine usanly (Modifying Orientation of Material Properties and Stresses of Layers) 1.5.5 Subroutine userrc (Performing User Operations on COMBIN7 and COMBIN37 Parameters) 1.5.6 Function userpe (Calculating Rotation Caused by Internal Pressure) 1.5.7 Subroutine UElMatx (Accessing Element Matrices and Load Vectors) 1.5.8 Subroutine UTHICK (Getting User-defined Initial Thickness) 1.5.9 Subroutine USTRESS (Getting User-defined Initial Stress) 1.6 Routines for Customizing Material Behavior 1.6.1 Subroutine userpl (Writing Your Own Plasticity Laws) 1.6.2 Subroutine usercr (Writing Your Own Creep Laws) 1.6.3 Subroutine usersw (Writing Your Own Swelling Laws) 1.6.4 Subroutine uservp (Updating Nonlinear Strain History for Materials) 1.6.5 Subroutine userck (Checking User-Defined Material Data) 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.6.9 Subroutine usermc (Controlling Hygrothermal Growth) 1.6.10 Subroutine usermu (Supplying a Friction Coefficient for CONTAC48 and CONTAC49) 1.6.11 Subroutine usrfc6 (Defining Custom Failure Criteria) 1.6.12 Subroutines usrfc1 through usrfc5 1.6.13 Subroutine UserVisLaw (Defining Viscosity Laws) 1.6.14 Supporting Function egen 1.7 Routines for Customizing Loads 1.7.1 Subroutine usrefl (Changing Scalar Fields to User-Defined Values) 1.7.2 Subroutine userpr (Changing Element Pressure Information) 1.7.3 Subroutine usercv (Changing Element Face Convection Surface Information) 1.7.4 Subroutine userfx (Changing Element Face Heat Flux Surface Information) 1.7.5 Subroutine userch (Changing Element Face Charge Density Surface Information) 1.7.6 Subroutine useracel (Modifying an Element's Acceleration/Angular Velocity Information) 1.7.7 Examples of Using the Load Customization Routines 1.7.7.1 Example of Using usercv 1.7.7.2 Effect of useracel on Results

1.8 Running ANSYS as a Subroutine 1.9 Defining Your Own Commands 1.9.1 Function user01 1.9.2 Function user02 (Demonstrates Offsetting Selected Nodes) 1.9.3 Function user03 (Demonstrates Using Heap Memory) 1.9.4 Functions user04 through user10 1.10 Supporting Subroutines 1.10.1 Function GetRForce (Getting Nodal Reaction Force values) 1.10.2 Function GetStackDisp (Getting Current Displacement Values) 1.10.3 Subroutine ElResultStrt (Getting Load Data from Analysis Results) 1.10.4 Subroutine ElResultGet (Getting Results Values at Selected Points) 1.10.5 Subroutine ElInterp (Finding Element Coordinates) 1.11 Access at the Beginning and End of Various Operations 1.12 Creating Your Own Optimization Routine 1.12.1 Linking a Custom Optimization Program to ANSYS 1.12.2 Subroutine userop (Defining a Custom Optimization Routine) 1.12.3 Structuring Your Input 1.12.3.1 Example of User Input for Optimization 1.12.4 Using a Stand-Alone Optimization Program

1.12.5 What Does Jobname.OPT Contain? 1.13 Data Handling Routines 1.13.1 Using the Memory Management Routines 1.13.2 Function HeapAllocPtr (Allocating Heap Space and Returning a Pointer) 1.13.3 Subroutine HeapDealloc (Deallocating Heap Space) 1.13.4 Function HeapGetPtr (Returns a Pointer for a Handle) 1.14 Parameter Processing Routines 1.14.1 Subroutine pardim (Creating a Dimensioned Parameter) 1.14.2 Function parevl (Finding and Evaluating a Parameter) 1.14.3 Subroutine pardef (Adding a Parameter) 1.15 Miscellaneous Useful Functions 1.15.1 Using Function runcmd 1.15.2 Using the /UNDO Command 1.15.3 Using the /HOLD command

2 Accessing the ANSYS Database

2.1 What This Chapter Covers 2.2 Inputs and Outputs for Database Access Routines 2.3 Types of Database Access Routines 2.4 Routines for Selecting and Retrieving Nodes and Elements 2.4.1 ndnext Function (Getting the Next Node Number)

2.4.2 ndprev Function (Getting the Number of the Previous Selected Node) 2.4.3 ndnxdf Function (Getting the Number of the Next Defined Node) 2.4.4 ndsel Function (Selecting, Unselecting, Deleting, or Inverting a Node) 2.4.5 elnext Function (Getting the Number of the Next Element) 2.4.6 elprev Function (Getting the Number of the Previous Selected Element) 2.4.7 elnxdf Function (Getting the Number of the Next Defined Element) 2.4.8 elsel Subroutine (Selecting, Unselecting, Deleting, or Inverting an Element) 2.5 Node Information Routines 2.5.1 ndinqr Function (Getting Information About a Node) 2.5.2 getnod Function (Getting a Nodal Point) 2.5.3 putnod Function (Storing a Node) 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.6 Element Attribute Routines 2.6.1 elmiqr Function (Getting Information About an Element) 2.6.2 elmget Function (Getting an Element's Attributes and Nodes) 2.6.3 elmput Subroutine (Storing an Element) 2.6.4 etyiqr Function (Getting a Data Item About an Element Type)

2.6.5 etyget Function (Getting Information About an Element Type) 2.6.6 etyput Subroutine (Storing Element Type Data) 2.6.7 echrtr Subroutine (Getting Information About Element Characteristics) 2.6.8 etysel Subroutine (Selecting, Unselecting, Deleting, or Inverting an Element Type) 2.6.9 mpinqr Function (Getting Information About a Material Property) 2.6.10 mpget Function (Getting a Material Property Table) 2.6.11 mpput Subroutine (Storing a Material Property Table) 2.6.12 mpdel Subroutine (Deleting a Material Property Table) 2.6.13 rlinqr Function (Getting Information About a Real Constant Set) 2.6.14 rlget Function (Getting Real Constant Data) 2.6.15 rlsel Subroutine (Selecting or Deleting a Real Constant Set) 2.6.16 csyiqr Function (Getting Information About a Coordinate System) 2.6.17 csyget Function (Getting a Coordinate System) 2.6.18 csyput Subroutine (Storing a Coordinate System) 2.6.19 csydel Subroutine (Deleting a Coordinate System) 2.6.20 userac Subroutine (Demonstrates Use of Element Attribute Routines) 2.7 Coupling and Constraint Routines 2.7.1 cpinqr Function (Getting Information About a Coupled Set)

2.7.2 cpget Function (Getting a Coupled Set) 2.7.3 cpput Subroutine (Storing a Coupled Set) 2.7.4 cpsel Subroutine (Selecting or Deleting a Coupled Set) 2.7.5 ceinqr Function (Getting Information About a Constraint Equation Set) 2.7.6 ceget Function (Getting an Constraint Equation) 2.7.7 ceput Subroutine (Storing a Constraint Equation) 2.7.8 cesel Subroutine (Deleting or Selecting a Constraint Equation) 2.8 Nodal Loading Routines 2.8.1 disiqr Function (Getting a Information About Constraints) 2.8.2 disget Function (Getting a Constraint from the Database) 2.8.3 disput Subroutine (Storing a Constraint at a Node) 2.8.4 disdel Subroutine (Deleting a Constraint at a Node) 2.8.5 foriqr Function (Getting Information About Nodal Loads) 2.8.6 forget Function (Getting a Constraint from the Database) 2.8.7 forput Subroutine (Storing a Nodal Load at a Node) 2.8.8 fordel Subroutine (Deleting a Nodal Load at a Node) 2.8.9 ntpiqr Function (Getting Information About a Nodal Temperature) 2.8.10 ntpget Function (Getting a Specified Nodal Temperature) 2.8.11 ntpput Subroutine (Storing a Nodal Temperature) 2.8.12 ntpdel Subroutine (Deleting a Nodal Temperature)

2.8.13 nhgiqr Function (Getting Information About Nodal Heat Generations) 2.8.14 nhgget Function (Getting a Nodal Heat Generation) 2.8.15 nhgput Subroutine (Storing Nodal Heat Generation) 2.8.16 nhgdel Subroutine (Deleting a Nodal Heat Generation) 2.8.17 nfuiqr Function (Getting Information About Nodal Fluences) 2.8.18 nfuget Function (Getting a Nodal Fluence) 2.8.19 nfuput Subroutine (Storing a Nodal Fluence) 2.8.20 nfudel Subroutine (Deleting a Nodal Fluence) 2.8.21 ndciqr Function (Getting Information About Nodal Current Densities) 2.8.22 ndcget Function (Getting a Nodal Current Density) 2.8.23 ndcput Subroutine (Storing a Nodal Current Density) 2.8.24 ndcdel Subroutine (Deleting a Nodal Current Density) 2.8.25 nvdiqr Function (Getting Information About Nodal Magnetic Virtual Displacements) 2.8.26 nvdget Function (Getting a Nodal Magnetic Virtual Displacement) 2.8.27 nvdput Subroutine (Storing a Nodal Virtual Displacement) 2.8.28 nvddel Subroutine (Deleting a Nodal Virtual Displacement) 2.9 Element Loading Routines 2.9.1 epriqr Function (Getting Information About Element Pressure/Convection) 2.9.2 eprget Function (Getting an Element Face Pressure)

2.9.3 eprput Subroutine (Storing an Element Face Pressure) 2.9.4 eprdel Subroutine (Deleting an Element Pressure/Convection) 2.9.5 ecviqr Function (Getting Information About Element Convections) 2.9.6 ecvget Function (Getting an Element Face Convection) 2.9.7 ecvput Subroutine (Storing an Element Face Convection) 2.9.8 ecvdel Subroutine (Deleting a Convection on an Element) 2.9.9 etpiqr Function (Getting Information About Element Temperatures) 2.9.10 etpget Function (Getting an Element Temperature) 2.9.11 etpput Subroutine (Storing an Element Temperature) 2.9.12 etpdel Subroutine (Deleting an Element Temperature) 2.9.13 ehgiqr Function (Getting Information About Element Heat Generation) 2.9.14 ehgget Function (Getting an Element Heat Generation) 2.9.15 ehgput Subroutine (Storing an Element Heat Generation) 2.9.16 ehgdel Subroutine (Deleting an Element Heat Generation) 2.9.17 efuiqr Function (Getting Information About Element Fluences) 2.9.18 efuget Function (Getting an Element Fluence) 2.9.19 efuput Subroutine (Storing an Element Fluence) 2.9.20 efudel Subroutine (Deleting an Element Fluence) 2.9.21 edciqr Function (Getting Information About Element Current Densities)

2.9.22 edcget Function (Getting Element Current Densities) 2.9.23 edcput Subroutine (Storing an Element Current Density) 2.9.24 edcdel Subroutine (Deleting an Element Current Density) 2.9.25 evdiqr Function (Getting Information About Element Virtual Displacements) 2.9.26 evdget Function (Getting an Element Virtual Displacement) 2.9.27 evdput Subroutine (Storing an Element Virtual Displacement) 2.9.28 eimiqr Function (Getting Information About Element Impedances) 2.9.29 eimget Function (Getting an Element Face Impedance) 2.9.30 eimput Subroutine (Storing an Element Impedance) 2.9.31 eimdel Subroutine (Deleting an Element Impedance) 2.9.32 esfiqr Function (Getting Information About Element Surface Stress Data) 2.9.33 esfget Function (Getting Element Surface Stress Data) 2.9.34 esfput Subroutine (Storing Element Surface Stress Data) 2.9.35 esfdel Subroutine (Deleting an Element's Surface Stress Data) 2.9.36 efsdel Subroutine (Deleting a Flagged Surface on an Element) 2.9.37 efsget function (Getting Element Face Flagged Surfaces) 2.9.38 efsiqr function (Getting Information About Flagged Surfaces) 2.9.39 efsput Subroutine (Storing an Element Face Flagged Surface)

2.10 Results Information Routines 2.10.1 dspiqr Function (Getting Information About Nodal Results) 2.10.2 dspget Function (Getting a Nodal Result from the Database) 2.10.3 dspput Subroutine (Storing a Constraint at a Node) 2.10.4 dspdel Subroutine (Deleting a Result at a Node) 2.10.5 emsiqr Function (Getting Information About an Element's Miscellaneous Summable Data) 2.10.6 emsget Function (Getting an Element's Miscellaneous Summable Data) 2.10.7 emsput Subroutine (Storing an Element's Miscellaneous Summable Data) 2.10.8 emsdel Subroutine (Deleting an Element's Miscellaneous Summable Data) 2.10.9 enfiqr Function (Getting Information About Element Nodal Forces) 2.10.10 enfget Function (Getting an Element's Nodal Forces) 2.10.11 enfput Subroutine (Storing an Element's Nodal Forces) 2.10.12 enfdel Subroutine (Deleting an Element's Nodal Forces) 2.10.13 ensiqr Function (Getting Information About an Element's Nodal Stresses) 2.10.14 ensget Function (Getting an Element's Nodal Stresses) 2.10.15 ensput Subroutine (Storing Nodal Stresses at an Element) 2.10.16 ensdel Subroutine (Deleting an Element's Nodal Stresses) 2.10.17 engiqr Function (Getting Information About an Element's Energies) 2.10.18 engget Function (Getting an Element's Energies)

2.10.19 engput Subroutine (Storing an Element's Energies and Volume) 2.10.20 engdel Subroutine (Deleting an Element's Energies) 2.10.21 egriqr Function (Getting Information About an Element's Nodal Gradients) 2.10.22 egrget Function (Getting an Element's Nodal Gradients) 2.10.23 egrput Subroutine (Storing an Element's Nodal Gradients) 2.10.24 egrdel Subroutine (Deleting an Element's Nodal Gradients) 2.10.25 eeliqr Function (Getting Information About an Element's Nodal Elastic Strains) 2.10.26 eelget Function (Getting an Element's Nodal Elastic Strains) 2.10.27 eelput Subroutine (Storing an Element's Nodal Elastic Strains) 2.10.28 eeldel Subroutine (Deleting an Element's Nodal Elastic Strains) 2.10.29 epliqr Function (Getting Information About an Element's Nodal Plastic Strains) 2.10.30 eplget Function (Getting an Element's Nodal Plastic Strains) 2.10.31 eplput Subroutine (Storing an Element's Nodal Plastic Strains) 2.10.32 epldel Subroutine (Deleting an Element's Nodal Plastic Strains) 2.10.33 ecriqr Function (Getting Information About an Element's Nodal Creep Strains) 2.10.34 ecrget Function (Getting an Element's Nodal Creep Strains) 2.10.35 ecrput Subroutine (Storing an Element's Nodal Creep Strains) 2.10.36 ecrdel Subroutine (Deleting an Element's Nodal

Creep Strains) 2.10.37 ethiqr Function (Getting Information About an Element's Nodal Thermal Strains) 2.10.38 ethget Function (Getting an Element's Nodal Thermal Stresses) 2.10.39 ethput Subroutine (Storing an Element's Nodal Thermal Stresses) 2.10.40 ethdel Subroutine (Deleting an Element's Thermal, Initial, and Swelling Strains) 2.10.41 euliqr Function (Getting Information About an Element's Euler Angles) 2.10.42 eulget Function (Getting an Element's Nodal Euler Angles) 2.10.43 eulput Subroutine (Storing an Element's Euler Angles) 2.10.44 euldel Subroutine (Deleting an Element's Euler Angles) 2.10.45 efxiqr Function (Getting Information About Element Fluxes) 2.10.46 efxget Function (Getting an Element Flux) 2.10.47 efxput Subroutine (Storing an Element's Fluxes) 2.10.48 efxdel Subroutine (Deleting Element Fluxes) 2.10.49 elfiqr Function (Getting Information About Element Local Forces) 2.10.50 elfget Function (Getting an Element Local Force) 2.10.51 elfput Subroutine (Storing an Element's Local Forces) 2.10.52 elfdel Subroutine (Deleting Element Local Forces) 2.10.53 emniqr Function (Getting Information About Element Miscellaneous Nonsummable Data)

2.10.54 emnget Function (Getting an Element's Miscellaneous Non-summable Data) 2.10.55 emnput Subroutine (Storing an Element's Miscellaneous Non-summable Data) 2.10.56 emndel Subroutine (Deleting an Element's Miscellaneous Non-summable Data) 2.10.57 ecdiqr Function (Getting Information About Element Current Densities) 2.10.58 ecdget Function (Getting an Element Current Density) 2.10.59 ecdput Subroutine (Storing an Element's Current Densities) 2.10.60 ecddel Subroutine (Deleting Element Current Densities) 2.10.61 enliqr Function (Getting Information About Element Nonlinear Tables) 2.10.62 enlget Function (Getting Element Nonlinear Tables) 2.10.63 enlput Subroutine (Storing an Element's Nonlinear Tables) 2.10.64 enldel Subroutine (Deleting Element Nonlinear Tables) 2.10.65 ehciqr Function (Getting Information About Calculated Element Heat Generations) 2.10.66 ehcget Function (Getting a Calculated Element Heat Generation) 2.10.67 ehcput Subroutine (Storing an Element's Calculated Heat Generations) 2.10.68 ehcdel Subroutine (Deleting Element Calculated Heat Generations)

3 Subroutines for Users' Convenience

3.1 What Subroutines Does This Chapter Describe? 3.1.1 Input and Output Abbreviations 3.2 General Subroutines

3.2.1 dptoch Subroutine (Retrieve Eight Characters From a Double Precision Variable) 3.2.2 wrinqr Function (Obtain Information About Output) 3.2.3 erinqr Subroutine (Obtaining Information from the Errors Common) 3.2.4 TrackBegin Subroutine (Beginning Tracking for a Subroutine Call) 3.2.5 TrackEnd Subroutine (Ending Tracking for a Subroutine Call) 3.2.6 erhandler Subroutine (Displaying ANSYS Errors) 3.2.7 intrp Subroutine (Doing Single Interpolation) 3.2.8 tranx3 Subroutine (Processing Geometry for 3-D Line Elements) 3.2.9 systop Subroutine (Stopping an ANSYS Program Run) 3.3 Vector Functions 3.3.1 vdot Function (Computing the Dot Product of Two Vectors) 3.3.2 vsum Function (Summing Vector Components) 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.5 izero Function (Setting an Integer Vector to Zero) 3.3.6 imove Function (Assigning Equal Values to Two Integer Vectors) 3.3.7 vzero Subroutine (Initializing a Vector to Zero)

3.3.8 vmove Subroutine (Moving One Vector into Another) 3.3.9 vimove Subroutine (Moving One Vector into Another Incrementally) 3.3.10 vinit Subroutine (Assigning a Scalar Constant to a Vector) 3.3.11 viinit Subroutine (Assigning a Scalar Constant to a Vector Incrementally) 3.3.12 vapb Subroutine (Setting a Vector to Sum of Two Vectors) 3.3.13 vapb1 Subroutine (Combining Two Vectors in One) 3.3.14 vapcb1 Subroutine (Multiplying a Vector to a Constant) 3.3.15 vamb Subroutine (Gets a Third Vector by Subtracting One Vector from Another) 3.3.16 vamb1 Subroutine (Subtracting One Vector from Another) 3.3.17 vmult Subroutine (Multiplying a Vector by a Constant) 3.3.18 vmult1 Subroutine (Multiplying a Vector by a Constant) 3.3.19 vcross Subroutine (Defining a Vector via a Cross Product) 3.3.20 vnorme Subroutine (Normalizing a Three-Component Vector) 3.3.21 vnorm Subroutine (Normalizing a Vector to Unit Length) 3.3.22 ndgxyz Function (Getting the X,Y,Z Vector for a Node) 3.3.23 ndpxyz Subroutine (Storing X,Y,Z for a Node) 3.4 Matrix Subroutines 3.4.1 maxv Subroutine (Multiplying a Vector by a Matrix) 3.4.2 maxv1 Subroutine (Multiplying a Vector by a Matrix) 3.4.3 matxv Subroutine (Multiplying a Vector by a Full Transposed Matrix)

3.4.4 matxv1 Subroutine (Multiplying a Vector by a Full Transposed Matrix) 3.4.5 matxb Subroutine (Transposing a matrix) 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) 3.4.8 mctac Subroutine (Transposing a symmetric matrix) 3.4.9 tran Subroutine (Transposing a matrix) 3.4.10 symeqn Subroutine (Solving Simultaneous Linear Equations) 3.5 Message Processing Routines 3.5.1 msgdi Subroutine (Conditionally Printing Messages, Scalars, Vectors, or Matrices) 3.5.2 msgdic Subroutine (Conditionally Printing Messages and an Integer Vector) 3.5.3 msgdim Subroutine (Conditionally Printing Messages and Matrices) 3.5.4 msgdir Subroutine (Conditionally Printing Messages, Integers, and Reals) 3.5.5 msgdit Subroutine (Conditionally Printing Messages and a Transposed Integer Matrix) 3.5.6 msgdiv Subroutine (Conditionally Printing Messages and an Integer Vector) 3.5.7 msgdr Subroutine (Conditionally Printing Messages and Reals) 3.5.8 msgdrc Subroutine (Conditionally Printing Messages and Real Vectors) 3.5.9 msgdrm Subroutine (Conditionally Printing Messages and Real Matrices)

3.5.10 msgdrt Subroutine (Conditionally Printing Messages and Real Transposed Matrices) 3.5.11 msgdrv Subroutine (Conditionally Prints Messages and Real Vectors) 3.5.12 msgdt Subroutine (Conditionally Prints Message Text)

Appendix A External Commands

A.1 Introduction to External Commands A.2 Tasks in Creating an External Command A.2.1 Creating Compatible Code A.2.2 Creating a Shared Library A.2.3 Creating an External Table File A.2.4 Setting the ANSYS_EXTERNAL_TABLE Environment Variable A.2.5 Using External Commands A.2.6 Checking External Command Status A.2.7 Resetting External Commands A.2.8 Example External Command

Preface Conventions Used in This Guide

This guide uses the following typographic conventions to indicate various types of information: Convention Indicates ANSYS commands. These are shown as uppercase, bold text (for example, K, DDELE, etc.). In the online documentation, these provide hyperlinks to the appropriate command reference information. Menu paths (sometimes referred to as GUI paths). These are shown as bold text with mixed-case, separated by angle brackets ">". An angle bracket indicates a branch to a new menu item. File names, which may or may not include directory paths. These are shown as lower-case, bold text, unless case is significant. Examples are shown with the UNIX directory separator character "/" (slash); if you are using a Microsoft Windows system, use "\" (backslash) as your directory separator character. Arguments for numeric values (such as VALUE, INC, TIME) in command syntax. These are shown as upper-case italic text. On some commands, non-numeric convenience labels (for example, ALL and P) can also be entered for these arguments. Arguments for alphanumeric values (for example, Lab or Fname) in command syntax. These are shown in mixed-case, italic letters. The guide also uses italic text for emphasis. The name of an ANSYS manual. Command input listings, ANSYS output listings, and text that a user enters are shown in fixed-width font.

COMMAND

Menu > Item

path/filename.ext

ARGUMENT

Argument

ANSYS Guide Title

command,arg1,arg2

Note-

Information that supplements the main topic being discussed, such as important tips or guidelines. Actions or situations that could cause problems, unexpected ANSYS behavior, or unexpected results. Actions or situations that can shut down ANSYS, damage files, cause loss of data, etc.

Caution:

Warning:

About the Programmer's Guide Set

The ANSYS programmer's guide set provides information about the various programming interfaces available to customers. These manuals assume that you have at least a basic knowledge of programming (a working knowledge of Fortran 77 would be very helpful). The set of four manuals includes: The APDL Programmer's Guide 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 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. Guide To ANSYS User Programmable Features 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. Guide to Interfacing with ANSYS

This guide describes the format of the various binary data files that ANSYS creates, as well as routines supplied by ANSYS that allow you to retrieve data from these files. The chapter also discusses the CDWRITEcommand and the .cdbfile that it creates, as well as the format of the neutral graphics file. 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. Chapter 1 * Chapter 2 * Chapter 3 * Appendix A

1.1 Introduction to UPFs

Because the ANSYS program has an open architecture, you can write your own routines or subroutines in C or FORTRAN and either link them to ANSYS or use them as external commands. In fact, some of the ANSYS features you see today as "standard" offerings originated as user programmable features (UPFs). You can take advantage of UPFs if you're licensed for any of the following products:
G G G G G

ANSYS/Multiphysics ANSYS/Mechanical ANSYS/Structural ANSYS/PrepPost ANSYS/ED (Research Faculty/Student version)

Other versions of the ANSYS program don't support UPFs.

1.1.1 What Are UPFs?

User programmable features are ANSYS capabilities you can use to write your own routines. Using UPFs, you can tailor the ANSYS program to your organization's needs. For instance, you may need to define a new material behavior, a special element, or a modified failure criterion for composites. You can even write your own design optimization algorithm that calls the entire ANSYS program as a subroutine. UPFs provide the following capabilities:
G

G G G

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.

1.1.2 What You Should Know Before Using UPFs

Before you do anything with linked UPFs, contact your on-site ANSYS system support person to get the permissions needed to access the appropriate ANSYS files. 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:

G G

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
G

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, sitedependent 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.

1.1.3 Planning Your UPFs

UPFs can range from a simple element output routine for customized output to a complex user optimization. Before you start programming, ask yourself these questions:
G

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.

1.1.4 Studying the ANSYS User Routines

Your ANSYS distribution medium contains the source codes for all user routines:
G G

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.

1.1.5 Programming in Languages Other than FORTRAN

If you access UPFs by compiling and linking a custom version of ANSYS, the preferred method is to design and program your custom routine in FORTRAN 77. Although you can use languages other than FORTRAN 77, in each case FORTRAN 77 must provide the interface to the rest of the ANSYS program. If you do use a language other than FORTRAN 77, such as the C programming language, your code may require a FORTRAN shell. 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.

1.1.6 Developing UPFs: a Suggested Strategy

When developing UPFs by compiling and linking a custom version of ANSYS, you can avoid problems and reduce debugging time by following a gradual, orderly process. Start with a trivial test. Then, add a few changes at a time so that if something goes wrong, the error that caused the problem should be isolated and relatively easy to locate. 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.

1.1.7 Include Decks

In addition to the subroutines and functions described in this chapter, most of the include decks (files with the extension .inc) used by ANSYS are on your ANSYS distribution medium. These include decks, also called commons, contain important but relatively small amounts of data. The ANSYS program also handles large amounts of data using various access routines (GET and PUT), as described elsewhere in this manual. 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: Include File Description acelcm.inc Contains accelerations and angular velocities

ansysdef.inc

Defines general ANSYS parameters. You must include this common to retrieve the parameter values of HEAP_INTEGER, HEAP_DOUBLE, HEAP_COMPLEX, or HEAP_REAL. Contains optimization variables Defines parameters for element characteristics Defines element characteristics (comments only) Contains element-specific information Defines pointers for the element data array Defines the element degree-of-freedom pointers Element type data

cmopt.inc echprm.inc elccmt.inc elecom.inc elparm.inc elucom.inc etycom.inc

impcom.inc Used by all routines and functions in the ANSYS program outpcm.inc soptcm.inc stack.inc stepcm.inc usvrcm.inc Defines output control information Contains solution options and keys Defines stack storage. You must include this common in any routines that access stack space. Contains load step information Defines storage of user-defined variables

1.1.8 Linking User Routines

After you make your changes to the user routines supplied on your ANSYS distribution medium, you can either
G G

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.

1.1.9 Compiling and Linking UPFs on UNIX Systems

As mentioned previously, the source files for the user routines reside in subdirectory /ansys55/customize/user. If you modify any of these subroutines, run the procedure /ansys55/customize/user/ANSCUSTOM to link these changes into the ANSYS program. When you run a user-linked version of the ANSYS program, the output will include the following: NOTE: This ANSYS version was linked by Licensee

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.

1.1.10 Compiling and Linking UPFs on Windows Systems

As mentioned previously, the source files for the user routines reside in subdirectory \ansys55\custom\user\platform. If you modify any of these subroutines, perform the following tasks to link your changes into the ANSYS program: 1. Create and go to a working directory for building ANSYS. 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.

1.1.11 Activating UPFs

The ANSYS program activates many UPFs through a specific user action. This can be through a command option or a user selection. For example, to activate a user element, all you need to do is select it as one of the element types in a model (using either the ET command or menu path Main Menu>Preprocessor>Element Type>Add/Edit/Delete). You then set the element attribute pointer (TYPE command or menu path Main Menu>Preprocessor>-Meshing->Attributes>Default Attribs), and define elements using the solid modeling or direct generation method. UPFs that are not activated by the means described above must be activated by either of the following methods:
G G

Issuing the USRCAL command Choosing menu path Main Menu>Preprocessor>Loads>-Load Step Opts->Other>User Routines or Main Menu>Solution>Load Step Opts->Other>User Routines.

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.

1.1.12 Running Your Custom Executable

You can run your custom executable using a supplied procedure called ansys55cust in UNIX (ansys55cust.exe in Windows). This

procedure/executable resides in the ansys55\bin\platform directory. When run, the procedure searches the current working directory for the custom ANSYS executable (either ansys.e55t or ansys.exe, depending on your platform). If the custom ANSYS executable resides in a separate directory, you can specify the path on the ansys55cust command line, as follows: ansys55cust -custom /pathname/ansys.e55t or, for Windows ansys55cust -custom /pathname/ansys.exe

1.1.13 Verifying Your Routines

After compiling and linking your new user routine, test and verify it using whatever procedures you think are adequate. Remember, verifying that your customized version of the ANSYS program works properly is your responsibility. 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.

1.1.14 Debugging Commands

To debug errors in your user routines, you can use commands and other features not documented in the ANSYS Commands Reference. Use these commands only for extremely small models with few solution iterations (otherwise, they'll generate an excessive amount of output). /TRACK and /DEBUG are described in detail below. Two other useful "undocumented" commands are OUTEQ and /NERR. The command OUTEQ,on can be used to output results from all equilibrium iterations. The command /NERR,,,-1 causes errors to be reported as before, but the run continues anyway, normally terminating with either a) system abort or b) incorrect answers.

1.1.14.1 Tracking the Path of Program Logic

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.

1.1.14.2 Debugging Elements and Solutions

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. 1.1.14.2.1 Solution Debug Format

Issue the command using this format: /DEBUG,-1,F1,F2,F3,F4,F5,F6,F7,F8,F9 For This Argument Choose One of These Values F1 1 (provides basic solution control debugging) 1 (provides transient debugging using Newmark constants) F2 2 (provides transient debugging using velocities and accelerations) 1 (provides element matrix debugging and prints matrix + load vectors) F3 2 (provides element matrix debugging with load vectors only) 3 (provides element matrix debugging with matrix diagonals and load vectors) F4 F5 F6 1 (provides auto time stepping debugging) 1 (provides multifield debugging) 1 (provides arc-length debugging) 1 (provides basic Newton-Raphson debugging) F7 2 (provides Newton-Raphson debugging and prints out-of-balance forces or incremental displacement or each DOF) 3 (provides Newton-Raphson debugging and prints applied loads and n-r restoring force for each DOF) 1,2 (provides displacement vector debugging with displacement pointers) F8 2 (provides displacement vector debugging with incremental displacement) 3 (provides displacement vector debugging with contact database) F9 1 (provides temporary programmer debugging)

1.1.14.2.2 Element Debug Format Issue the command using this format: /DEBUG,-3,G1,G2,G3,G4,G5,G6,G7,G8,G9 For This Argument Choose One of These Values G1 G2 1 (provides basic element pass debugging) 1 (provides element displacement and coordinate debugging)

1 (provides element matrix debugging and prints matrix + load vectors) G3 2 (provides element matrix debugging with load vectors only) 3 (provides element matrix debugging with matrix diagonals and load vectors) G4 G5 G6 1 (provides element load information debugging) 1 (provides element real constant debugging) 1 (provides element saved variable debugging) 1 (provides element material property debugging with linear material properties) G7 2 (provides element material property debugging with nonlinear properties) 1,2 (provides element nonlinear debugging with plasticity) G8 2 (provides element nonlinear debugging with large deformation) 3 (provides element nonlinear debugging with contact database) G9 1 (provides temporary programmer debugging)

1.1.14.2.3 General Debug Format Issue the command using this format: /DEBUG,H1,H2,,H4,H5 For This Argument Choose One of These Values 1 (provides file header record information) H1 2 (provides input line (character)) 3 (provides input line (decoded)) 1 (provides wavefront reordering and element checking debugging) H2 2 (provides meshing debugging) 1 (provides nodal coordinate system transformation debugging) H4 2 (provides displacement updating debugging) H5 1 (provides pre-element debugging, element characteristics debugging, and element field load debugging)

1.1.15 Other Useful Commands

Two other ANSYS commands, NSVR and /UCMD, can help you implement UPFs. (Neither command has an equivalent GUI path.) Use the NSVR command to define the number of extra variables that need to be saved for user programmable element options, such as user

plasticity. Issue the /UCMD command to make a user routine into a custom command. For more information, see section 1.9 later in this chapter.

1.1.16 Generating Output

You can generate output controlled by the /OUTPUT command by using the FORTRAN write statement. The output unit for this statement is usually called IOTT. IOTT may be defined with the function wrinqr. See the discussion on the function wrinqr in Chapter 6 for more details.

1.2 Reading Large Data Files More Rapidly

When files containing ANSYS-related data are large, loading them into the ANSYS program or writing them out to an external file can be a slow process. For example, consider an ANSYS problem file which contains nearly 462,000 lines, 150,000 of which contain nodal data and 97,383 of them containing data for elements. Because many of the lines in this file are in command format, the ANSYS program spends a lot of time reading it. 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.

1.2.1 EBLOCK Command Format

The EBLOCK command requires that you specify a valid format statement for five element attributes followed by the node numbers for each element. The command has the following format: 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 element attributes are: Elnum The element number. Mat Real Type Esys The material number. The real constants associated with this element. The element type number. The system of coordinates this element uses.

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.

1.2.2 NBLOCK Command Format

The NBLOCK command has this format: 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.

1.3 Routines for Creating New Elements

The next few pages describe the user routines and supporting subroutines you use to create new elements. Using these routines, you can create new element types, add them to the ANSYS element library, and use them as "regular" elements. You can create up to six independent element types (names USER100 - USER105). For demonstration purposes, example copies of the routines for MASS21, the structural mass element, and LINK8, the 3-D spar element, are included on the ANSYS distribution medium as uel100 and uel101 respectively.

1.3.1 Input and Output Abbreviations

The descriptions of the routines or functions within this chapter describe both the input arguments and output arguments. Argument information includes the argument's type, size and intent.
G

Argument type is one of the following: int - integer dp - double precision log - logical chr - character dcp - double precision complex

Argument size is one of the following: sc - scalar variable ar(n) - array variable of length n func - functional return value

Argument intent is one of the following: in - input argument out - output argument inout - both an input and an output argument

1.3.2 User Routines

Routines uec100 through uec105 describe the element characteristics. Routine elccmt (on the distribution medium) describes the input for these routines in detail. You can use subroutines uex100 through uex105 to override default logic. Routines uec100 through uec105 define parameters such as:
G G G G

2-D or 3-D geometry Degree-of-freedom set Symmetric or unsymmetric matrix Number of nodes

G G G G G G

Number of body loads (for example, temperatures) Number of surface loads (for example, pressures) Number of real constants Number of variables to be saved Number of rows in element matrices Linear or nonlinear element.

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:
G

G G

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.

1.3.3 Subroutine uec100 (Defining Characteristics of the usr100 Routine)

c c #include "impcom.inc" subroutine uec100 (elcdn,ielc,kerr) ***** this subroutine defines the characteristics of user100.

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

1.3.3.1 Subroutines uec101 through uec105

The input and output arguments for subroutines uec101, uec102, uec103, uec104, and uec105 is identical to the uec100 subroutine listed above.

1.3.4 Subroutine uex100 (Overriding Element Characteristic Defaults)

subroutine uex100 (ielc,kerr) c *** subroutine to override element characteristic defaults *** c *** hence, this routine is needed only in rare cases. 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 #include "impcom.inc" #include "echprm.inc" integer ielc(*),i,kerr c c *** input and output are the same as for uec100, except that this c *** logic is called after the defaulting logic is finished. c *** this defaulting is done in ansys subroutine echdft(not a upf). c *** as indicated above, this routine is rarely needed, but if it is c *** desired to see the effect of echdft, you may print out the ielc array c *** leaving uec100 and print it out again entering this routine. 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 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 *** standard defaults are taken. the final results are given with c *** the debug accessed with /debug,,, ,,1 c c *** dummy logic to use all variables to keep analyzer happy c *** this should be removed by user element programmer

1.3.4.1 Subroutines uex101 through uex105

The source code for subroutines uex101, uex102, uex103, uex104, and uex105 is identical to the code for subroutine uex100 listed above.

1.3.5 Subroutine uel100 (Computing Element Matrices, Load Vectors, and Results)
subroutine uel100 (elem,ielc,elmdat,eomask,nodes,locsvr,kelreq, x kelfil,nr,xyz,u,kelout,zs,zass,damp,gstif,zsc,zscnr,elvol,elmass, x center,elener,edindx,lcerst) --- general lumped mass is demonstrated -------------------------------*** primary function: 1. compute element matrices, load vectors, and results *** secondary functions: 2. maintain element solution data

c c c c c

c c *** user programmable functions may not be used in parallel processing *** c c *** Notice - This file contains ANSYS Confidential information *** c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c input arguments: c elem (int,sc,in) - element label (number) c ielc (int,ar(IELCSZ),in) - array of element type characteristics c (IELCSZ = array size, defined in echprm) c elmdat (int,ar(10),in) - array of element data c eomask (int,sc,in) - bit pattern for element output c (see outpcm) c nodes (int,ar(nnod),in) - array of element node numbers c (nnod = number of nodes; 1 in this case) c locsvr (int,sc,in) - location of the saved variables c on file .esav for this element c kelreq (int,ar(10),in) - matrix and load vector form requests c (indices for kelreq are given with output c arguments below) c kelfil (int,ar(10),in) - keys indicating incoming matrices and c load vectors (indices for kelfil are the c same as given for kelreq with output c arguments below) c nr (int,sc,in) - matrix and load vector size c xyz (dp,ar(6,nnod),in) - nodal coordinates (orig) and rotation angle c u (dp,ar(nr,5),in) - element nodal solution values c c output arguments: c kelout (int,ar(10),out) - keys indicating created matrices and c load vectors (indices for kelout c are the same as for kelreq below, c as well as kelin and kelout later) c zs (dp,ar(nr,nr),inout)- stiffness/conductivity matrix (kelreq(1)) c zass (dp,ar(nr,nr),inout)- mass matrix (kelreq(2)) c damp (dp,ar(nr,nr),inout)- damping/specific heat matrix (kelreq(3)) c gstif (dp,ar(nr,nr),inout)- stress stiffness matrix (kelreq(4)) c zsc (dp,ar(nr),out) - applied f vector (kelreq(5)) c zscnr (dp,ar(nr),out) - n-r restoring f vector (kelreq(6)) c or imaginary f vector (kelreq(7)) c elvol (dp,sc,out - element volume c elmass (dp,sc,out) - element mass c center (dp,ar(3),out) - centroid location c elener (dp,ar(5),out) - element energies c edindx (int,ar(20),out) - element result data file indexes c lcerst (int,sc,inout) - position on result file c

1.3.6 Subroutines uel101 through uel105

The input and output arguments for subroutines uel101, uel102, uel103, uel104, and uel105 is identical to subroutine uel100 listed above.

1.3.7 Subroutine uep100 (Printing Output for User Elements)

x x x c subroutine uep100 (iott,ielc,elem,nodes,mat, kept,ept, kemn,emn, kems,ems, kens,ens, keel,eel, keth,eth, kenl,enl, kepl,epl, kecr,ecr)

c *** primary function: produce printed output for user elements c used typically only for line elements 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 ********** this subroutine is provided for user information ********* c *** user programmable features may not be used in parallel processing *** c c input arguments: c iott (int,sc,in) - output unit number c ielc (int,ar(150),in) - element characteristics c elem (int,sc,in) - element number c nodes (int,ar(2),in) - node numbers c mat (int,sc,in) - material number c kept (int,sc,in) - key to print temperatures c ept (dp,ar(*),in) - element pseudo-node temperatures c kemn (int,sc,in) - key to print misc. non-summed data c emn (dp,ar(*),in) - misc. non-summable data record c kems (int,sc,in) - key to print mmisc. summed data c ems (dp,ar(*),in) - misc. summed data c kens (int,sc,in) - key to print nodal stresses c ens (dp,ar(*),in) - nodal sresses at an element c keel (int,sc,in) - key to print nodal elastic strain c eel (dp,ar(*),in) - element nodal elastic strains c keth (int,sc,in) - key to print thermal,initial, and c swelling strains c eth (dp,ar(*),in) - nodal thermal strains at an element c kenl (int,sc,in) - key set if any nonlinear materials present c enl (dp,ar(*),in) - element nonlinear table c kepl (int,sc,in) - key to print nodal plastic strains c epl (dp,ar(*),in) - nodal plastic strains c kecr (int,sc,in) - key to print nodal creep strains c ecr (dp,ar(*),in) - nodal creep strains c c output arguments: c none

1.3.8 Subroutines uep101 through uep105

The source code for subroutines uep101, uep102, uep103, uep104, and uep105 is identical to subroutine uep100 listed above.

1.3.9 Subroutine usertr (Adjusting the Nodal Orientation Matrix)

subroutine usertr (node,tr) c *** primary function: adjust nodal orientation matrix c secondary function: study nodal orientation matrix c accessed with ielc(notran) = -100 c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. 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 node (int,sc,in) - node number being acted upon c tr (dp,ar(32,32),inout) - nodal to global orientation matrix c

c c c c c c c c c c c

output arguments: variable (typ,siz,intent) description tr (dp,ar(32,32),inout) - nodal to global orientation matrix tr is a matrix that is already defined based on the degrees of freedom selected. it does not normally need to be changed. it may be printed out here to study. its functional size is nr by nr, where nr is the number of degrees of freedom in the element

1.3.10 Subroutine userac (Accessing Element Information)

This subroutine is provided for demonstration purposes. subroutine userac (elem) primary function: To demonstrate user access of element information. Given the element number, all information about the element is avaiable. Starting with elmdat, one can get the element type, real constant number, the material number, the element coordinate system number, as well as the node numbers. Then, one can get more information about any or all of these things. The below demonstrates getting the element type and real constants.

c c c c c c c c c c c c c c c c c c c

*** -------------

*** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 *** ansys, inc. *** Notice - This file contains ANSYS Confidential information *** input arguments: variable (typ,siz,intent) elem (int,sc,in) output arguments: none

description - element number

1.4 Supporting Subroutines for Element Creation

The subroutines described on the next few pages support the user routines used to create new elements.

1.4.1 Subroutine nminfo (Returning Element Reference Names)

subroutine nminfo (ielc,rname) c *** primary function: set element reference names c *** secondary functions: none c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c ielc (int,ar(150),inout) - element characteristic vector c rname (chr,sc,in) - 8 character reference name c c output arguments: c variable (typ,siz,intent) description c ielc (int,ar(150),inout) - element characteristic vector with c element name encoded c

1.4.2 Subroutine svgidx (Fetching the Index for Saved Variables)

subroutine svgidx (locsvr,svindx) c *** primary function: get the index for saved variables c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c locsvr (int,sc,in) - pointer to location of index c c output arguments: c svindx (int,ar(10),out) - the 10 word index of svr variables c 1-starting loc of this eles svr sets c 2-ending loc of this eles svr sets c 3:10-starting loc for each set c 3-structural svrs c 4-thermal/electric/fluid svrs c 5-magnetic svrs c 6-nonlinear svrs c 7-plasticity svrs c 8-creep svrs c 9-coupled svrs c 10-user svrs c

1.4.3 Subroutine svrget (Fetching Saved Variable Data for an Element)

subroutine svrget (svindx,nset,nsvr,svr) c *** primary function: get svr data set for an element c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c c input arguments: svindx (int,ar(10),in) nset (int,sc,in)

nsvr

(int,sc,inout)

- index for svr for this element (see svgidx) - the set number in this index = 1 - structural svrs = 2 - thermal/electric/fluid svrs = 3 - magnetic svrs = 4 - nonlinear svrs = 5 - plasticity svrs = 6 - creep svrs = 7 - coupled svrs = 8 - user svrs - number of dp words expected in this set

output arguments: nsvr (int,sc,inout) svr (dp,ar(nsvr),in)

- number of dp words in this set - data in this set

1.4.4 Subroutine svrput (Writing an Element's Saved Variable Set)

subroutine svrput (svindx,nset,leng,svr) c *** primary function: write out a svr data set for an element c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c svindx (int,ar(10),inout)- the index for svr for this element c nset (int,sc,in) - the set number in this index (see svrget)

c c c c c c

leng svr

(int,sc,in) (dp,ar(leng),in)

- number of dp words in this set - data in this set

output arguments: svindx (int,ar(10),inout)- updated index

1.4.5 Subroutine svpidx (Writing the Saved Variable Element Index to a File)
subroutine svpidx (locsvr,svindx) c *** primary function: write the svr element index onto file c *** secondary functions: update the locsvr pointer to next element c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c locsvr (int,sc,inout) - pointer to start of svr for element c svindx (int,ar(10),in) - index to svr for this element c c output arguments: c locsvr (int,sc,inout) - pointer to start of svr for next element c

1.4.6 Subroutine mreuse (Determining Which Element Matrices Can Be Reused)

c c c c c c c c Second note: this logic is essentially the same as the old c sfrm logic. Hopefully, further simplifications and enhancements c will be made in the future. (Especially in gap elements and in c multilayer elements) c the whole idea of kpheno, a holdover from the sfrm routines, c needs to be looked at and possibly eliminated. c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c kelrqq (int,ar(10),in) - request keys (needed for this analysis) c kelfil (int,ar(10),in) - keys indicating matrices on the file c elem (int,sc,in) - element number c ielc (int,ar(IELCSZ),in) - array of element type characteristics c kmasrt (int,sc,in) - does the mass matrix have rotational DOF? c 0 - no 1 - yes(with nlgeom, sfrm1n) c knlmg (int,sc,in) - nonlinear magnetic curve exists in this c element c 0 - no 1 - yes c kconve (int,sc,in) - key indicating existence of convections c in this element c 0,1 - no 2 or more - yes c must be input as 'i' if not used, as is subroutine mreuse (kelrqq,kelfil,elem,ielc,kmasrt,knlmg,kconve, x kpheno,kprop,nprop,prop,propo,krvro,rvr,rvro,amodo,asymo, kelin) *** primary function: determine which Matrices can be REUSEd and which must be recomputed from iteration to iteration. Note: a few special elements have some supplementary logic to adjust these results further. No attempt as been made to include all such logic in these routines.

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

kpheno

(int,sc,in)

kprop

(int,sc,in)

nprop prop propo krvro =

= =

rvr rvro amodo asymo

(int,sc,in) (dp,ar(nprop),in) (dp,ar(nprop),inout)(int,sc,in) 0 - real constants are used by this element, and the old values(rvro) have been saved; or the element does not use real constants. Any change of real constants causes all matrices to be reformed. 1 - real constants are used by this element and the old values(rvro) have been saved. However, any change of real constants will cause the run to terminate, because the results would be too unpredictable. (e.g. gap elements) 2 - element is nonlinear, so do not bother to check 3 - real constants are used by this element, and the old values(rvro) have been saved. However, no checking is done in this routine because of needed customized logic. 4 - real constants are used by this element, but the old values(rvro) have not been saved because it was decided not to use this much storage. therefore, no check can be made to determine if matrices should be reformed. (e.g. 100 layer elements) 5 - real constants are used by this element, but the old values(rvro) have not been saved because the real constants have no effect on matrix formulation. (e.g. acoustic elements) (dp,ar(*),in) - current real constants (dp,ar(*),inout) - previous real constants (dp,sc,inout) - previous value of mode (dp,sc,inout) - previous value of isym

changed in this routine(for analyzer). i = 0 must be used in calling routine if kpheno = 1. key for type of phenomenon/level of check 0 - structural like old sfrm1n,1s,3n,3s,fl 1 - thermal like old sfrm1c,1t,2t,3t 2 - electrical/magnetic like some of old sfrmpo 3 - general like old sfrmoo key indicating which material properties in the prop vector that need to be checked (see below) number of properties current mat props previous material properties

output arguments: propo (dp,ar(nprop),inout)rvro (dp,ar(*),inout) amodo (dp,sc,inout) asymo (dp,sc,inout) kelin (int,ar(10),out) -

current material properties current real constants current value of mode current value of isym keys indicating matrices to form

1.4.7 Subroutine subrd (Reading Element Load Data for a Substructure Generation Run)
subroutine subrd (iel,key,nd,vect,ka) c *** primary function: read element load data from file for substructure c generation run c *** secondary functions: none c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments:

c c c c c c c c c c c c c c c c c c c c c c c c c

iel key

(int,sc,in) (int,sc,in)

nd

(int,sc,in)

- element number - type of load data = 1 temperature = 2 fluences = 3 heat generation rates = 4 current densities =10 pressures =11 film coefficients =12 bulk temperatures =13 extra displacement shapes =14 thermal strains(eptho in el42) =15 thermal flux (as in el55) =16 initial strains(epino in el01) =17 magnetic virtual displacements =18 calculated source field(hsn in el96) =20 element load vector =30 copy - do not scale(tempev in el42) first load step only - number of data items

output arguments: vect (dp,ar(nd),out) ka (int,sc,out)

- array of load data - load activation key = 0 no load for this data = 1 load is active

1.4.8 Subroutine subwrt (Writing an Element Load Vector to a File for a Substructure Generation Run)
subroutine subwrt (iel,nvect,key,nd,vect,ref) c *** primary function: write element load vect to file for substructure c generation run c *** secondary functions: none c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c iel (int,sc,in) - element number c nvect (int,sc,in) - number of load vectors c (current load step number) c key (int,sc,in) - type of load vect c = 1 temperature c = 2 fluences c = 3 heat generation rates c = 4 current densities c =10 pressures c =11 film coefficients c =12 bulk temperatures c =13 extra displacement shapes c =14 thermal strains(eptho in el42) c =15 thermal flux (as in el55) c =16 initial strains(epino in el01) c =17 magnetic virtual displacements c =18 calculated source field(hsn in el96) c =20 element load vector c =30 copy - do not scale(tempev in el42) c nd (int,sc,in) - number of vect items c vect (dp,ar(nd),in) - array of load data c ref (dp,sc,in) - reference value for zero load c c output arguments: none

1.4.9 Subroutine rvrget (Fetching Real Constants for an Element)

subroutine rvrget (iel,ireal,ielc,nrvr,rvr) c *** primary function: get the real constants for an element 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 iel (int,sc,in) - element number c ireal (int,sc,in) - real constant set number c ielc (int,ar(150),in) - elment type characteristics c c output arguments: c nrvr (int,sc,out) - number of real variables c rvr (dp,ar(*),out) - element real constants

1.4.10 Subroutine propev (Evaluating a Group of Material Properties)

subroutine propev (iel,mtr,lp,tem,prop,n) c *** primary function: to evaluate a group of material properties c c propev is used to pass two or more material property numbers c thru the lp array to determine which temperature dependent c material properties are to be evaluated. c thus, the 3 prope1 calls: c c c c call prope1 (elem,mat, 1,tem,e(1)) call prope1 (elem,mat,10,tem,alpha) call prope1 (elem,mat,13,tem,dens) should be combined as:

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 c c c c c c c c c c c c c c c c c c input arguments: iel (int,sc,in) mtr (int,sc,in) lp (int,ar(n),in)

- element number - material number(input quantity mat, mat comma - keys for which specific value is requested each group must be in ascending order (ex,ey,ez, etc) if negative, a required property if zero, leave prop term unchanged EX = 1, EY = 2, EZ = 3, NUXY= 4, NUYZ= 5, NUXZ= 6, GXY = 7, GYZ = 8 GXZ = 9, ALPX=10, ALPY=11, ALPZ=12, DENS=13, MU =14, DAMP=15, KXX =16 KYY =17, KZZ =18, RSVX=19, RSVY=20, RSVZ=21, C =22, HF =23, VISC=24 EMIS=25, ENTH=26, LSST=27, PRXY=28, PRYZ=29, PRXZ=30, MURX=31, MURY=32 MURZ=33, PERX=34, PERY=35, PERZ=36, MGXX=37, MGYY=38, MGZZ=39, EGXX=40 EGYY=41, EGZZ=42, TGXX=43, TGYY=44, TGZZ=45, SONC=46, (see chapter 2 of the elements volume of the user's manual for a detailed description)) (dp,sc,in) (int,sc,in) - temperature at which to evaluate material - number of properties to be evaluated.

tem n

c c c c c c

(20 maximum) If n = 1, use prope1 instead. output arguments: prop (dp,ar(n),out)

- values of material property

1.4.11 Subroutine prope1 (Evaluating One Material Property)

subroutine prope1 (iel,mtr,icon,tem,prop1) c *** primary function: to evaluate one material property c (if multiple material properties are to c be evaluated, use propev) c *** secondary functions: to ensure that certain required props are present c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c iel (int,sc,in) - element number c mtr (int,sc,in) - material number c icon (int,sc,in) - key for which specific value is requested c (negative if property is required) 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 c tem (dp,sc,in) - temperature at which to evaluate material c c output arguments: c prop1 (dp,sc,out) - value of material property c

1.4.12 Subroutine pstevl (Evaluating EX, NUXY, GXY, ALPX, and DENS at Element Temperature)
subroutine pstev1 (elem,matin,tem,prop) c *** primary function: to evaluate material properites for 1-d elements c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c elem (int,sc,in) - element number (for anserr) c matin (int,sc,in) - material reference number c if negative, no required properties c tem (dp,sc,in) - temperature for evaluation c c output arguments: c prop (dp,ar(5),out) - material properties: ex,nuxy,gxy,alpx,dens 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

1.4.15 Function gtswop (Retrieving the Start Position for Swelling Data)
function gtswop (mat,swopt) c *** primary function: get the swelling 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 swopt (int,sc,out) - swelling option: c 10000*(irrad+1) + 1000*(secondary+1) + c (primary+1)

c c c c c c

gtswop

(int,sc,out)

where: primary - primary swelling (constant C6) secondary - secondary swelling (constant C12) irrad - irradation induced (constant C66) see swelling table documentation (TB command) - virtual starting position of the data

1.4.16 Subroutine tbuser (Retrieving User Table Data)

subroutine tbuser (mat,numitm,tbprop) c *** primary function: return the tb data for the user table c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c mat (int,sc,in) - material property number c numitm (int,sc,in) - the number of data items requested c c output arguments: c tbprop (dp,ar(numitm),out) - array of tb data

1.4.17 Subroutine plast1 (Updating an Element's Plastic History)

subroutine plast1 (option,elem,intpt,mat,kstart,tem,dtem,e,ktform, x dens,flu,dflu,epel,eppl,statev,usvr,epeq,plwork,sigepl,sigrat,et) c *** primary function: to update the plastic history (for 1 component) c *** secondary functions: to compute the material tangent matrix if requested c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c option (int,sc,in) - plasticity option c elem (int,sc,in) - element number (label) c intpt (int,sc,in) - element integration point number c mat (int,sc,in) - material reference number c kstart (int,sc,in) - virtual starting address of the data table c tem (dp,sc,in) - temperature at the end of this substep c dtem (dp,sc,in) - temperature increment over this substep c e (dp,sc,in) - elastic modulus c ktform (int,sc,in) - request key for tangent matrix formation c dens (dp,sc,in) - material density c flu (dp,sc,in) - fluence at the end of this substep c dflu (dp,sc,in) - fluence increment over this substep c epel (dp,sc,inout) - modified total strain (trial strain) c eppl (dp,sc,inout) - plastic strain at previous substep c statev (dp,ar(6),inout) - state variables at previous substep c usvr (dp,ar(*),inout) - user-defined state variables (for userpl) c epeq (dp,sc,inout) - effective plastic strain at prev substep c plwork (dp,sc,inout) - accumulated plastic work at prev substep c c output arguments: c epel (dp,sc,inout) - elastic strain c eppl (dp,sc,inout) - updated plastic strain c statev (dp,ar(6),inout) - updated state variables c usvr (dp,ar(*),inout) - updated user-defined state variables c epeq (dp,sc,inout) - updated effective plastic strain c plwork (dp,sc,inout) - updated accumulated plastic work c sigepl (dp,sc,out) - stress value on stress-strain curve c sigrat (dp,sc,out) - ratio of trial stress to yield stress c et (dp,sc,out) - tangent modulus c

c c

internal variables: deppl (dp,sc)

- equivalent plastic strain increment

1.4.18 Subroutine creep1 (Updating an Element's Creep History)

subroutine creep1 (option,elem,intpt,mat,kstart,epel,e,epcrp, x statev,usvr,tem,dtem,fluen,dflu,sig) c *** primary function: to update the creep history for 1-d elements c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c option (int,sc,in) - creep option c elem (int,sc,in) - element number (label) c intpt (int,sc,in) - element integration point number c mat (int,sc,in) - material reference number c kstart (int,sc,in) - virtual starting address of the data table c epel (dp,sc,inout) - elastic strain c e (dp,sc,in) - elastic modulus c epcrp (dp,sc,inout) - creep strain at previous substep c statev (dp,ar(7),inout) - state variables at previous substep c usvr (dp,ar(*),inout) - user-defined state variables (for usercr) c tem (dp,sc,in) - temperature at the end of this substep c dtem (dp,sc,in) - temperature increment over this substep c fluen (dp,sc,in) - fluence at the end of this substep c dflu (dp,sc,in) - fluence increment over this substep c epel (dp,sc,inout) - elastic strain adjusted for creep increment c sig (dp,sc,inout) - stress (not really used) c c output arguments: c epcrp (dp,sc,inout) - updated creep strain c statev (dp,ar(7),inout) - updated state variables c usvr (dp,ar(*),inout) - updated user-defined state variables c sig (dp,sc,inout) - stress (recomputed if requested)

1.4.19 Subroutine swell1 (Updating an Element's Swelling History)

subroutine swell1 (option,elem,intpt,mat,kstart,epswel,epel,e, x fluen,dfluen,tem,dtem,usvr) c *** primary function: to update the swelling history for 1-d elements c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c option (int,sc,in) - swelling option c elem (int,sc,in) - element number (label) c intpt (int,sc,in) - element integration point number c mat (int,sc,in) - material reference number c kstart (int,sc,in) - virtual starting address of the data table c epswel (dp,sc,inout) - swell strain at previous substep c epel (dp,sc,inout) - elastic strain c e (dp,sc,in) - elastic young'S MODULUS c fluen (dp,sc,in) - fluence at the end of this substep c dfluen (dp,sc,in) - fluence increment over this substep c tem (dp,sc,in) - temperature at the end of this substep c dtem (dp,sc,in) - temperature increment over this substep c usvr (dp,ar(*),inout) - user-defined state variables (for usersw) c c output arguments: c epel (dp,sc,inout) - elastic strain adjusted for swelling inc c epswel (dp,sc,inout) - updated swelling strain c usvr (dp,ar(*),inout) - updated user-defined state variables

1.4.20 function nlget (Retrieving Material Non-Linear Property Information)

function nlget (mat,iprop,prop) c *** primary function: get a material non-linear property (TB) table. c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c mat (int,sc,in) - material number c iprop (int,sc,in) - property number (tbpnum in tblecm) c use 73 for tb,user c use 74 for tb,nl c c output arguments: c variable (typ,siz,intent) description c nlget (int,sc,out) - number of property values c prop (dp,ar(nlget),out) - vector of the property values c

1.4.21 Subroutine usereo (Storing Data in the nmisc Record)

subroutine usereo (elem,iout,nbsvr,bsvr,nnrsvr,nrsvr,npsvr,psvr, x ncsvr,csvr,nusvr,usvr,nnode,nodes,xyz,vol,leng,time, x timinc,nutot,utot,maxdat,numdat,udbdat) c c *** primary function: to call userou, which allows user to store c data in nmisc record c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c elem (int,sc,in) - element number c iout (int,sc,in) - output unit number c nbsvr (int,sc,in) - number of basic element variables c bsvr (dp,ar(nbsvr),in) - basic element variables c nnrsvr (int,sc,in) - number of nonlinear element variables c nrsvr (dp,ar(nnrsvr),in) - nonlinear element variables c npsvr (int,sc,in) - number of plasticity element variables c psvr (dp,ar(npsvr),in) - plasticity element variables c ncsvr (int,sc,in) - number of creep element variables c csvr (dp,ar(ncsvr),in) - creep element variables c nusvr (int,sc,in) - number of user-supplied element variables c usvr (dp,ar(nusvr),in) - user-supplied element variables c nnode (int,sc,in) - number of nodes c nodes (int,ar(nnode),in) - node numbers c xyz (dp,ar(6,nnode),in) - nodal coordinates and rotations (virgin) c vol (dp,sc,in) - element volume (or area if 2-d) c leng (dp,sc,in) - element length (beams,spars,etc) c time (dp,sc,in) - current time c timinc (dp,sc,in) - current sub step time increment c nutot (int,sc,in) - length of dof solution vector utot c utot (dp,ar(nutot),in) - solution vector c maxdat (int,sc,in) - size of user output array (3 x nnode) c actually, = ielc(nmnmup) c c output arguments:

c c c c

variable (typ,siz,intent) numdat (int,sc,out) udbdat (dp,ar(maxdat),out)

description - number of user output items in array udbdat - user output items to be placed at the end of the nmisc record

1.4.22 Subroutine eldwrt (Writing Element Data to a File)

subroutine eldwrt (ielem,edtype,lcerst,edindx,nval,value) c *** primary function: output element data to result file. c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c input arguments: ielem (int,sc,in) edtype (int,sc,in) lcerst (int,sc,inout) edindx (int,ar(25),inout)nval (int,sc,in) -

value

(dp,ar(nval),in)

element number element data type (see elparm) pointer to results file position index to results file data the total number of values if edtype = EDEMS, this should -always- be ielc(nmsmis), unless there is a variable number, as in the layered shell elements. - output values (real)

1.4.23 Subroutine eldwrn (Writing Element Nonsummable Miscellaneous Data to the Results File)
subroutine eldwrn (elem,ielc,lcerst,edindx,nudb,udbdat,nval,value, x ndval) c *** primary function: output element nonsummable miscellaneous data c to result file c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c c c input arguments: elem (int,sc,in) - element number ielc (int,ar(IELCSZ),in) - element characteristic vector defined in elccmt lcerst (int,sc,inout) - pointer to results file position edindx (int,ar(25),inout)- index to results file data nudb (in,sc,in) - size of what the user wants to add udbdat (dp,ar(*),in) - what the user wants to add nval (int,sc,in) - the total number of values to be output(does not include nudb) this should -always- be ielc(NMNMIS), unless there is a variable number, as in the layered shell elements. value (dp,ar(ndval),in) - output values ndval (int,sc,in) - dimension of value - must be no less than ielc(NMNMIS) + ielc(NMNMUP)

1.4.24 Subroutine trrot (Computing the Rotation Vector)

subroutine trrot (tr,rot) c *** primary function: get the rotation vector from a transformation matrix c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c tr (dp,ar(3,3),in) - transformation matrix

c c c c

output arguments: rot (dp,ar(3),out)

- rotation vector

1.4.25 Subroutine rottr (Computing the Transformation Matrix)

subroutine rottr (rot,tr) c primary function: compute transformation matrix from rotation vector ***** c *** Notice - This file contains ANSYS Confidential information *** c c ref(old): eqn. 20(transposed),rankin and brogan, jpvt,108(1986)165-174. c ref(new): eqn. (b.4), simo and vu-quoc, cmame, 58 (1986), 79-116 c c variable descriptions: c input: c rot - rotation pseudovector c output: c tr - transformation matrix corresponding to rot c

1.4.26 Subroutine xyzup3 (Updating an Element's 3-D Nodal Coordinates)

subroutine xyzup3 (nnod,u,nr,xyz,nx,xyzup) c *** primary function: update a 3-d ele nodal coords for large deformation c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c nnod (int,sc,in) - number of nodes c u (dp,ar(nr),in) - displacement vector c nr (int,sc,in) - size of the u vector c xyz (dp,ar(nx,nnod),in) - coordinates to be updated c nx (int,sc,in) - row size of xy c c output arguments: c xyzup (dp,ar(3,nnod),out) - updated coordinates c

1.4.27 Subroutine updrot (Updating the Rotation Pseudovector)

subroutine updrot (v2,w1) c primary function: update the rotation pseudovector for 3-d large rotations ***** c c *** Notice - This file contains ANSYS Confidential information *** c c the updating of the pseudovector uses the mathematics of quarternions c (ref: eqn. a5 of j. h. argyris, cmame, 32(1982)85-155). the c pseudovector uses the nomalization proposed by rankin and brogan (ref: c eqn. 15, jpvt, 108(1986)165-174). c c variable descriptions: c input: c v2 - rotation increment c w1 - previous rotation pseudovector c output: c w1 - updated pseudovector c c v1 = cos(v1/2) + 1/2*w1, w1 = 2*sin(v1/2)*e1

c c c c

v2 = cos(v2/2) + 1/2*w2, w2 = 2*sin(v2/2)*e2 v21 = v2*v1 = cos(v21/2) + 1/2*w21 (quarternion multiplication) w1 =: v21 (w1 is updated)

1.4.28 Subroutine tmpget (Defining Current Temperature Loads)

c 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 iel (int,sc,in) - element number c ielc (int,ar(IELCSZ),in) - array of element type characteristics c nnod (int,sc,in) - number of nodes in the nodes array c nodes (int,ar(nnod),in) - list of nodes c ref (dp,sc,in) - reference temperature c ndat (int,sc,in) - number of data items to get c begdat (dp,ar(ndat),in) - data at the beginning of this load step c c output arguments: c dat (dp,ar(ndat),out) - data at this time point c enddat (dp,ar(ndat),out) - data at end of this load step c iexist (int,sc,out) - flag if temperatures exist c = 0 - no temperatures c = 1 - yes temperatures c subroutine tmpget (iel,ielc,nnod,nodes,ref,ndat,begdat,dat,enddat, x iexist) primary function: define the current temperature loads

1.4.29 Subroutine prsget (Defining Current Pressure Loads)

subroutine prsget (iel,ielc,nfac,ndat,begdat,dat,enddat,iexist) c primary function: define the current pressure loads 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 iel (int,sc,in) - element number c ielc (int,ar(IELCSZ),in) - array of element type characteristics c nfac (int,sc,in) - number of pressure faces c ndat (int,sc,in) - number of pressure values c begdat (dp,ar(ndat),in) - pressure at the beginning of load step c c output arguments: c dat (dp,ar(ndat),out) - pressures at this iteration c enddat (dp,ar(ndat),out) - pressure at end of this load step c iexist (int,sc,out) - flag if pressure exist c = 0 - no pressure c = 1 - yes pressure c

1.4.30 Subroutine cnvget (Defining Current Convection Loads)

subroutine cnvget (iel,ielc,nr,u,nfac,ndat,beghc,begtb,

x hc,tb,endhc,endtb,iexist) c primary function: define the current convection loads 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 iel (int,sc,in) - element number c ielc (int,ar(IELCSZ),in) - array of element type characteristics c nr (int,sc,in) - dimension of u (temperature) vector c u (dp,ar(nr),in) - most current temperatures c nfac (int,sc,in) - number of convection faces c ndat (int,sc,in) - number of convection values c beghc (dp,ar(ndat),in) - hcoef at the beginning of load step c begtb (dp,ar(ndat),in) - tbulk at the beginning of load step c c output arguments: c hc (dp,ar(ndat),out) - hcoef at this substep c tb (dp,ar(ndat),out) - tbulk at this substep c endhc (dp,ar(ndat),in) - hcoef at the end of this load step c endtb (dp,ar(ndat),in) - tbulk at the end of this load step c iexist (int,sc,out) - flag if convection exist c = 0 - no convection c = 1 - constant convection (with time) c does not require new element matrix c = 2 - changing convection (with time) c or deleted convection c requires new element matrix c

1.4.31 Subroutine hgnget (Defining Current Heat Generation Loads)

x c 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 iel (int,sc,in) - element number c ielc (int,ar(IELCSZ),in) - array of element type characteristics c nnod (int,sc,in) - number of nodes in the nodes array c nodes (int,ar(nnod),in) - list of nodes c ndat (int,sc,in) - number of data items to get c begdat (dp,ar(ndat),in) - data at the beginning of this load step c c output arguments: c dat (dp,ar(ndat),out) - data at this time point c enddat (dp,ar(ndat),out) - data at end of this load step c iexist (int,sc,out) - flag if heat generation exist c = 0 - no heat generation c = 1 - yes heat generation c subroutine hgnget (iel,ielc,nnod,nodes,ndat,begdat,dat,enddat, iexist) primary function: define the current heat generation loads

1.5 Routines for Modifying and Monitoring Existing

Elements
The next few pages describe the user routines you use to modify or monitor existing ANSYS elements. These routines enable you to perform tasks including:
G G G G G

Computing load vectors for frequency domain logic Storing element output that users supply Modifying the orientation of material properties and stresses Modifying the orientation of material properties and stresses of layers within an element Performing a user-defined operation on a parameter for the COMBIN7 and COMBIN37 elements. Providing a user-defined initial thickness for SHELL181. Providing a user-defined initial strain for SHELL181. Providing a user-defined fictive temperature relationship for VISCO88 and VISCO99. Provides visco-elastic computation in the stiffness pass for VISCO88 and VISCO99.

G G

G G

1.5.1 Subroutine userfd (Computing the Complex Load Vector for Frequency Domain Logic)
subroutine userfd (nr,kpeak,kcbrm,kpfor,ktrsur,isur, x cd,cm,ct,cb,do,doext,aread,alenv,nuxy,faclen,conac,fluidt,visc, x dprtem,watmot,xyzup,tr,accel,puvel,u,zass, x forl,zsc,zsc2,pdyn,holdwv) c *** primary function: compute complex load vector for frequency domain logic c *** secondary functions: none c -- accessed with keyopt(12) = 2 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 input arguments: c nr (int,sc,in) - matrix size c kpeak (int,sc,in) - keyopt for wave combinations c kcbrm (int,sc,in) - key for reduced matrices/cable option c kpfor (int,sc,in) - keyopt for wave printout c ktrsur (int,sc,in) - keyopt for surface treatment(unfinished) c isur (int,sc,in) - surface flag c cd (dp,sc,in) - normal drag coefficient (real constant) c cm (dp,sc,in) - inertial coefficient (real constant) c ct (dp,sc,in) - tangential drag coefficient (real constant) c cb (dp,sc,in) - buoyancy coefficient (real constant) c do (dp,sc,in) - outside diameter of pipe c doext (dp,sc,in) - outside diameter of insulation c aread (dp,sc,in) - area of displaced water c alenv (dp,sc,in) - length of element c nuxy (dp,sc,in) - poisson'S RATIO c faclen (dp,sc,in) - wetted fraction of pipe c conac (dp,sc,in) - added mass per unit length c fluidt (dp,sc,in) - fluid temperature c visc (dp,sc,in) - viscosity c dprtem (int,sc,in) - size of water motion table c watmot (dp,ar(1278),in) - water motion table c xyzup (dp,ar(3,2),in) - updated coordinates c tr (dp,ar(3,3),in) - local to global transformation matrix c accel (dp,ar(3),in) - acceleration vector c puvel (int,sc,in) - index for velocities in u matrix c u (dp,ar(nr,5),in - displacements and velocities c zass (dp,ar(nr,nr),in) - mass matrix

c c c c c c c c c c c

forl zsc zsc2

(dp,ar(12),inout) - force vector in element coordinates (dp,ar(nr),inout) - real load vector for frequency domain (dp,ar(nr),inout) - complex load vector for frequency domain

output arguments: forl (dp,ar(12),inout) zsc (dp,ar(nr),inout) zsc2 (dp,ar(nr),inout) pdyn (dp,ar(2),out) holdwv (dp,ar(60),out)

force vector in element coordinates real load vector for frequency domain complex load vector for frequency domain dynamic pressure wave information held for printout

1.5.2 Subroutine userou (Storing User-Supplied Element Output)

subroutine userou (elem,iout,nbsvr,bsvr,nnrsvr,nrsvr,npsvr,psvr, x ncsvr,csvr,nusvr,usvr,nnode,nodes,xyz,vol,leng,time, x timinc,nutot,utot,maxdat,numdat,udbdat) c c *** primary function: store user supplied element output c in nmisc record c c in order to activate this user programmable feature, c the user must enter the usrcal command. 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 this routine is called by almost every element c the data is stored on the nmisc record. c warning: other data may be stored between the c documented data and this data. c in order to see the actual information on the nmisc c record, insert the command: c dblist,elp,elnum1,elnum2,elinc,11 c where elnum1 = the first element c elnum2 = the last element c elinc = the element increment number c after a set command in post1. c c input arguments: c variable (typ,siz,intent) description c elem (int,sc,in) - element number c iout (int,sc,in) - output unit number c nbsvr (int,sc,in) - number of basic element variables c bsvr (dp,ar(nbsvr),in) - basic element variables c nnrsvr (int,sc,in) - number of nonlinear element variables c nrsvr (dp,ar(nnrsvr),in) - nonlinear element variables c npsvr (int,sc,in) - number of plasticity element variables c psvr (dp,ar(npsvr),in) - plasticity element variables c ncsvr (int,sc,in) - number of creep element variables c csvr (dp,ar(ncsvr),in) - creep element variables c nusvr (int,sc,in) - number of user-supplied element variables c (= nstv on the nsvr command) c usvr (dp,ar(nusvr),in) - user-supplied element variables c nnode (int,sc,in) - number of nodes c nodes (int,ar(nnode),in) - node numbers c xyz (dp,ar(6,nnode),in) - nodal coordinates and rotations (virgin) c vol (dp,sc,in) - element volume (or area if 2-d) c leng (dp,sc,in) - element length (beams,spars,etc) c time (dp,sc,in) - current time

c c c c c c c c c c c c c c

timinc nutot utot maxdat

(dp,sc,in) (int,sc,in) (dp,ar(nutot),in) (int,sc,in)

current sub step time increment length of dof solution vector utot solution vector size of user output array (3 x nnode)

output arguments: variable (typ,siz,intent) numdat (int,sc,out)

udbdat

(dp,ar(maxdat),out)

description - number of user output items in array udbdat (maximum size of numdat is ielc(NMNMUP) which is usually three times the number of nodes. - user output items to be placed at the end of the nmisc record

1.5.3 Subroutine useran (Modifying Orientation of Material Properties)

subroutine useran (vn,vref,elem,thick,xyzctr,bsangl) c user written routine to modify orientation of material properties c and stresses *************************** c applicable to: shell43,63,91,93,99, solid46,64 c accessed by keyopt 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 **** warning *** do not change any arguments other than bsangl. c if you do, your results are probably wrong. c c input(do not change)--c vn = vector normal to element c vref = unit vector orienting element, essentially edge i-j c elem = element number c thick = total thickness of element at this point (see note below) c xyzctr = location of element centroid or integration point c c output--c bsangl = output from this subroutine. it represents the angle(s) c between vref and the desired orientation. it may have c the default orientation coming in to useran. c This will be combined with the angles derived from c the ESYS command. c use 1 angle for 2-d elements and shells c use 3 angles for 3-d solids c

1.5.4 Subroutine usanly (Modifying Orientation of Material Properties and Stresses of Layers)
subroutine usanly c c c c c c c c (vn,vref,elem,thick,xyzctr,ln,bsangl) user written routine to modify orientation of material properties and stresses of layers within an element ************************** applicable to shell91,99, and solid46 accessed with keyopt(4) *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 *** ansys, inc.

c *** Notice - This file contains ANSYS Confidential information *** c c **** warning *** do not change any arguments other than bsangl. c if you do, your results are probably wrong. c input(do not change)--c vn = vector normal to element c vref = unit vector orienting element, essentially edge i-j c elem = element number c thick = thickness of layer ln at this point (see note below) c xyzctr = location of element centroid or integration point c ln = layer number c c output--c bsangl = output from this subroutine. it represents the angle(s) c between vref and the desired orientation of the layer. c it may have the default orientation coming in to useran. c c this angle does not affect the angle given in the printout. c users may want to add their own angle printout in usanly. c c also, this angle does not affect the angle shown using the c layplot or laylist commands c c use 1 angle for 2-d elements and shells c use 3 angles for 3-d solids c c the programmer of usanly can base their logic on the location c of the point in space, or an element attributes, such as thick c

1.5.5 Subroutine userrc (Performing User Operations on COMBIN7 and COMBIN37 Parameters)
c 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 input arguments: c variable (typ,siz,intent) description c elem (int,sc,in) - element number c ireal (int,sc,in) - element real constant number c type (int,sc,in) - element type number c nusvr (int,sc,in) - number of user-supplied element variables c usvr (dp,ar(nusvr),inout) - user-supplied element variables c parm (dp,sc,in) - current value of the paramater c parmld (dp,sc,in) - value of the parameter at previous time ste c c1 (dp,sc,in) - real constant c1 c c2 (dp,sc,in) - real constant c2 c c3 (dp,sc,in) - real constant c3 c c4 (dp,sc,in) - real constant c4 c c output arguments: c variable (typ,siz,intent) description c usvr (dp,ar(nusvr),inout) - user-supplied element variables c may be sent .rst file with usereo c fcon (dp,sc,out) - result of calculation c subroutine userrc (elem,ireal,type,nusvr,usvr,parm,parmld, x c1,c2,c3,c4,fcon) primary function: user operation on parameter for combin7 and combin37 accessed with keyopt(9) = 1

c c

either c1 or c3 must be nonzero for this logic to be accessed,

1.5.6 Function userpe (Calculating Rotation Caused by Internal Pressure)

function userpe (prs,rvrp,angle,ex,nuxy) c primary function: c c c calculate the rotation caused by internal pressure on an elbow element This function is only called by el18(pipe18) if keyopt(5) = 1

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 *** ansys, inc. typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) prs (dp,ar(5),in) rvrp (dp,ar(11),in) angle (dp,sc,in) ex (dp,sc,in) nuxy (dp,sc,in) output arguments: variable (typ,siz,intent) userpe (dp,sc,out) siz=sc,ar(n) intent=in,out,inout

description pressure vector real constants(see elements manual) subtended angle Young's modulus Poisson's ratio

description rotation caused by internal pressure on the elbow element

1.5.7 Subroutine UElMatx (Accessing Element Matrices and Load Vectors)

x subroutine UElMatx (elem,nr,ls,zs,zsc,uelm,ielc,nodes,edof, elmdat,xyzang,lenu) User routine to access element matrices and load vectors. Needs to have USRCAL,UELMATX to be accessed. Called after the call to the element routine and before the solver. May be used to monitor and/or modify the element matrices and load vectors.

c primary function: c c c c c c c c c c c c c c c c c c

*** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 *** ansys, inc. typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout

input arguments: variable (typ,siz,intent) description elem (int,sc,in) - User element number nr (int,sc,in) - number of rows in element matrix ls (int,ar(nr),in) - Dof Index vector for this element matrix zs (dp,ar(nr,nr,4),inout)- K,M,C,SS matrices for this element zsc (dp,ar(nr,2),inout) - Element load vector and N-R correction vec uelm (dp,ar(nr,5),in) - Nodal displacements for this element ielc (int,ar(150),in) - Element type characteristics nodes (int,ar(*),in) - Nodes for this element

c c c c c c c c c c

edof elmdat xyzang lenu

(int,ar(*),in) (int,ar(10),in) (dp,ar(6,*),in) (int,sc,in)

Dofs per node for this element Element data for this element X,Y,Z,THXY,THYZ,THZX for each element node Length of global displacement vector

output arguments: zs (dp,ar(nr,nr,4),inout)- K,M,C,SS matrices for this element zsc (dp,ar(nr,2),inout) - Element load vector and N-R correction vec WARNING: any CHANGES to these (or any other) arguments will have a direc impact on the solution, possibly giving meaningless results. The normal usage of this routine is simply monitor what is happening.

1.5.8 Subroutine UTHICK (Getting User-defined Initial Thickness)

SUBROUTINE uthick (elemId, elemType, matId, realId, $ numDomIntPts, curCoords, thickness) ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c c *** primary function: get the user defined thickness c c *** ansys(r) copyright(c) 1998 c *** ansys, inc. c c input arguments c =============== c Variable (type,sz,i/o) description c elemId (int,sc,i) element number c elemType (int,sc,i) element TYPE (181 etc.) c matId (int,sc,i) material number c realId (int,sc,i) real constant set number c numDomIntPts (int,sc,i) number of integration points c curCoords (dp,ar(3,numDomIntPts),i) c current coordinates c c output arguments c ================ c thickness (dp,ar(3,numDomIntPts),o) c thickness at the integration points c ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c c --- parameters c #include "impcom.inc" EXTERNAL erhandler c c --- argument list c INTEGER elemId, elemType, numDomIntPts, matId, realId DOUBLE PRECISION curCoords(3,numDomIntPts), $ thickness (numDomIntPts) c c --- local variables c INTEGER i cc COMMON /dummyIniThick/ errFlag ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c --- B E G I N C O D I N G c c --- author of UTHICK.F should remove the following error message c and any unnecessary flags. c

$ $ $ c c c c

CALL erhandler ('uthick', 5000, 2, 'ANSYS, Inc.-supplied version of UTHICK has been used. This works with the COMMENTED EXAMPLE input attached with uthick.F', 0.d0, ' ') --- linearly varying thickness for the cantilever model in the commented example; thick(x=0) = 0.1, thick(x=10) = 0.05 DO i=1,numDomIntPts thickness(i) = 0.1d0*(1.d0-curCoords(1,i)/20.d0) END DO

c 990 c RETURN END cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c c C O M M E N T E D I N P U T F I L E T O B E U S E D W I T H c c T H E A N S Y S S U P P L I E D U T H I C K c cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c!/batch,list c!/verify,ev181-57s c!/title,ev181-57s, Variable thickness shell with UTHICK c!/nolist c!/nopr c!/out,scratch c! c!/prep7 c! c!!!!!!! STANDARD USE OF SHELL 181 with Variable Thickness !!!!! c! c!*dim,thick,,10 c!thick(1) = 0.0975 c!thick(2) = 0.0925 c!thick(3) = 0.0875 c!thick(4) = 0.0825 c!thick(5) = 0.0775 c!thick(6) = 0.0725 c!thick(7) = 0.0675 c!thick(8) = 0.0625 c!thick(9) = 0.0575 c!thick(10)= 0.0525 c! c!*dim,lnodes,,11 c!*dim,unodes,,11 c! c!*do,i,1,11 c! x = (i-1)*1.0 c! n,i,x c! n,i+11,x,1.0 c! lnodes(i) = i c! unodes(i) = i+11 c!*enddo c! c!et,1,181 c!mp,ex,1,1000 c!mp,nuxy,1,0.3 c! c!*do,i,1,10 c! r,i,thick(i) CONTINUE

c! real,i c! e,lnodes(i),lnodes(i+1),unodes(i+1),unodes(i) c!*enddo c! c!!!!!!! USE OF SHELL 181 with Variable Thickness Through UTHICK !!!!! c! c!*dim,l2nod,,11 c!*dim,u2nod,,11 c!*do,i,1,11 c! x = (i-1)*1.0 c! n,i+22,x,2.0 c! n,i+33,x,3.0 c! l2nod(i) = i+22 c! u2nod(i) = i+33 c!*enddo c! c!et,2,181 c!keyopt,2,9,1 c!r,11 c!type,2 c!real,11 c! c!*do,i,1,10 c! e,l2nod(i),l2nod(i+1),u2nod(i+1),u2nod(i) c!*enddo c! c!/out c!elist c!etlist c!/out,scratch c! c!nsel,s,loc,x, c!d,all,ux c!d,all,uz c!d,all,rotx c!d,all,rotz c!d,all,roty c! c!nsel,s,loc,y c!d,all,uy c! c!nsel,s,loc,y,2.0 c!d,all,uy c! c!nsel,s,loc,x,10.0 c!f,all,my,0.004 c!alls c!fini c! c!/solu c!outres,all,all c!nlgeom,on c!solc,on c!nsubst,10,,5 c!eqslv,sparse c!solve c!fini c! c!/post1 c!set,last c!nsel,s,loc,x,10.0 c!/out c!/com

c!/com, ------------------------------------------------------c!/com, | Results of Node # 11 and 22 are from the standard use c!/com, | of SHELL181; the results of Node # 33 and 44 are c!/com, | obtained by using UTHICK (keyopt 9 = 1) and should c!/com, | match the results of node # 11 and 22 c!/com, ------------------------------------------------------c!/com c!prdi c!/out,scratch c!finish c! c!/delete,ev181-57s.emat c!/delete,ev181-57s.err c!/delete,ev181-57s.esav c!/delete,ev181-57s.osav c!/delete,ev181-57s.log c!/delete,ev181-57s.mntr c!/delete,ev181-57s.rst c!/delete,ev181-57s.full c!/golist c!/exit,nosave

| | | |

1.5.9 Subroutine USTRESS (Getting User-defined Initial Stress)

*deck,ustress parallel user smg SUBROUTINE ustress (elemId, elemType, matId, basis, $ curIntPt, curLayer, curSecPt, $ numDirect, numShear, curCoords, $ tLocation, iniData) ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c c *** primary function: get the user supplied stress state for c initial stress analysis c c *** ansys(r) copyright(c) 1998 c *** ansys, inc. c c input arguments c =============== c Variable (type,sz,i/o) description c elemId (int,sc,i) element number c elemType (int,sc,i) element TYPE (42, 181 etc.) c matId (int,sc,i) material number c basis (dp,ar(3,3),i) basis directions (for the element) c curIntPt (int,sc,i) current Integration point c curLayer (int,sc,i) current Layer number (for shell c and layered solids) c curSecPt (int,sc,i) current point through the thickness in the c current layer c numDirect (int,sc,i) number of direct stress comp c (s_xx,s_yy,s_zz) c numShear (int,sc,i) number of shear stress comp c (s_xy,s_yz,s_zx) c curCoords (dp,ar(3),i) current coordinates c tLocation (dp,sc,i) normalized thickness location c (shell elements only) c -1 = bottom or first sec pt c +1 = top or last sec pt c 0 = mid surface c c output arguments c ================

c iniData (dp,ar(numDirect+numShear),o) c user input stress values c ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c c --- parameters c #include "impcom.inc" EXTERNAL erhandler c c --- argument list c INTEGER elemId, elemType, matId, curIntPt, curLayer, $ curSecPt, numDirect, numShear DOUBLE PRECISION curCoords(3), tLocation, basis(3,3), $ iniData(numDirect+numShear) c c --- local variables c INTEGER i,j,k DOUBLE PRECISION dummy (4,5,10) cc COMMON /dummyIniDat/ dummy,errFlag ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c --- B E G I N C O D I N G c c --- author of USTRESS.F should remove the data statement, error msgs c and any unnecessary flags. The data you define here does not c necessarily have to be done with data statement c DATA (((dummy(i,j,k),i=1,4),j=1,5),k=1,2) / $ -0.1200E+02, -0.1249E+01, 0.0000E+00, -0.4003E-04, $ -0.7202E+01, -0.7495E+00, 0.0000E+00, 0.4515E-04, $ 0.1924E-04, -0.6599E-03, 0.0000E+00, 0.1729E-03, $ 0.7202E+01, 0.7481E+00, 0.0000E+00, 0.3007E-03, $ 0.1200E+02, 0.1247E+01, 0.0000E+00, 0.3859E-03, $ -0.1200E+02, 0.3359E+00, 0.0000E+00, 0.1337E-02, $ -0.7201E+01, 0.2019E+00, 0.0000E+00, 0.7683E-03, $ 0.1732E-03, 0.8891E-03, 0.0000E+00, -0.8421E-04, $ 0.7201E+01, -0.2001E+00, 0.0000E+00, -0.9367E-03, $ 0.1200E+02, -0.3341E+00, 0.0000E+00, -0.1505E-02/ DATA (((dummy(i,j,k),i=1,4),j=1,5),k=3,4) / $ -0.1200E+02, -0.9424E-01, 0.0000E+00, -0.1560E-02, $ -0.7202E+01, -0.5653E-01, 0.0000E+00, -0.9405E-03, $ 0.4304E-03, 0.2657E-04, 0.0000E+00, -0.1124E-04, $ 0.7202E+01, 0.5659E-01, 0.0000E+00, 0.9180E-03, $ 0.1200E+02, 0.9429E-01, 0.0000E+00, 0.1537E-02, $ -0.1200E+02, 0.3043E-01, 0.0000E+00, 0.9459E-03, $ -0.7200E+01, 0.1827E-01, 0.0000E+00, 0.5991E-03, $ 0.6953E-03, 0.3727E-04, 0.0000E+00, 0.7890E-04, $ 0.7201E+01, -0.1820E-01, 0.0000E+00, -0.4413E-03, $ 0.1200E+02, -0.3036E-01, 0.0000E+00, -0.7882E-03/ DATA (((dummy(i,j,k),i=1,4),j=1,5),k=5,6) / $ -0.1200E+02, -0.1066E-01, 0.0000E+00, -0.4662E-03, $ -0.7200E+01, -0.6225E-02, 0.0000E+00, -0.3059E-03, $ 0.8873E-03, 0.4321E-03, 0.0000E+00, -0.6545E-04, $ 0.7201E+01, 0.7089E-02, 0.0000E+00, 0.1750E-03, $ 0.1200E+02, 0.1153E-01, 0.0000E+00, 0.3353E-03, $ -0.1200E+02, 0.4769E-02, 0.0000E+00, 0.2606E-03, $ -0.7197E+01, 0.2935E-02, 0.0000E+00, 0.1814E-03, $ 0.9262E-03, 0.1837E-03, 0.0000E+00, 0.6259E-04, $ 0.7199E+01, -0.2568E-02, 0.0000E+00, -0.5620E-04, $ 0.1200E+02, -0.4402E-02, 0.0000E+00, -0.1354E-03/ DATA (((dummy(i,j,k),i=1,4),j=1,5),k=7,8) /

$ $ $ $ $ $ $ $ $ $

-0.1199E+02, -0.2508E-02, 0.0000E+00, -0.7195E+01, -0.1396E-02, 0.0000E+00, 0.7471E-03, 0.2729E-03, 0.0000E+00, 0.7197E+01, 0.1941E-02, 0.0000E+00, 0.1199E+02, 0.3054E-02, 0.0000E+00, -0.1198E+02, 0.3654E-02, 0.0000E+00, -0.7191E+01, 0.2247E-02, 0.0000E+00, 0.2508E-03, 0.1354E-03, 0.0000E+00, 0.7191E+01, -0.1976E-02, 0.0000E+00, 0.1199E+02, -0.3383E-02, 0.0000E+00, DATA (((dummy(i,j,k),i=1,4),j=1,5),k=9,10) / $ -0.1198E+02, -0.4337E-02, 0.0000E+00, $ -0.7186E+01, -0.2616E-02, 0.0000E+00, $ -0.6408E-03, -0.3430E-04, 0.0000E+00, $ 0.7185E+01, 0.2547E-02, 0.0000E+00, $ 0.1198E+02, 0.4269E-02, 0.0000E+00, $ -0.1197E+02, -0.1326E-02, 0.0000E+00, $ -0.7181E+01, -0.8506E-03, 0.0000E+00, $ -0.1444E-02, -0.1371E-03, 0.0000E+00, $ 0.7178E+01, 0.5763E-03, 0.0000E+00, $ 0.1196E+02, 0.1052E-02, 0.0000E+00, c i = 0 j = 0 k = 0 c

-0.3990E-04, -0.3183E-04, -0.1972E-04, -0.7612E-05, 0.4584E-06, 0.2321E-03, 0.1487E-03, 0.2362E-04, -0.1015E-03, -0.1849E-03/ 0.2315E-03, 0.1461E-03, 0.1810E-04, -0.1099E-03, -0.1953E-03, 0.7206E-03, 0.4404E-03, 0.2012E-04, -0.4002E-03, -0.6803E-03/

IF (curIntPt.EQ.1 .AND. curLayer.EQ.1 .AND. curSecPt.EQ.1) THEN CALL erhandler ('ustress', 5000, 2, 'ANSYS, Inc.-supplied $ version of USTRESS has been used. This $ works with the COMMENTED EXAMPLE input $ attached with ustress.F', 0.d0, ' ') END IF c iniData(1) iniData(2) iniData(3) iniData(4) c 990 c RETURN END ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c c C O M M E N T E D I N P U T F I L E T O B E U S E D W I T H c c T H E A N S Y S S U P P L I E D U S T R E S S c ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc c!/batch,list c!/PREP7 c! c!et,1,181 c!keyopt,1,10,1 c!r,1,1.0 c! c!mp,ex,1,1000 c!mp,nuxy,1,0.3 c! c!NBLOCK,6,SOLID c!(3i8,6e16.9) c! 23 0 0 0.000000000E+00 c! 24 0 0 9.90525175 0.000000000E+00 -1.18849741 CONTINUE = = = = dummy(1,curSecPt,elemId) dummy(2,curSecPt,elemId) dummy(3,curSecPt,elemId) dummy(4,curSecPt,elemId)

c! 25 0 c! 26 0 c! 27 0 c! 28 0 c! 29 0 c! 30 0 c! 31 0 c! 32 0 c! 33 0 c! 34 0 c! 35 0 c! 36 0 c! 37 0 c! 38 0 c! 39 0 c! 40 0 c! 41 0 c! 42 0 c! 43 0 c! 44 0 c!N,R5.3,LOC, -1, c!N,R5.1,LOC, -1, c! c!EBLOCK,18,SOLID c!(18i7) c! 1 1 1 25 44 35 c! 1 1 1 26 43 44 c! 1 1 1 27 42 43 c! 1 1 1 28 41 42 c! 1 1 1 29 40 41 c! 1 1 1 30 39 40 c! 1 1 1 31 38 39 c! 1 1 1 32 37 38 c! 1 1 1 33 36 37 c! 1 1 1 24 34 36 c! -1 c!EN,R5.1,ATTR, -1, c! c!nsel,s,loc,x, c!d,all,ux c!d,all,uz c!d,all,rotx c!d,all,rotz c!d,all,roty c! c!nsel,s,loc,y c!d,all,uy c!nall c! c!fini c! c!/solu c!

0 0.999933795 0 1.99930664 0 2.99754302 0 3.99406599 0 4.98830170 0 5.97967935 0 6.96762690 0 7.95157929 0 8.93097304 0 9.90524927 0 0.000000000E+00 0 8.93097042 0 7.95157631 0 6.96762465 0 5.97967659 0 4.98830027 0 3.99406429 0 2.99754103 0 1.99930796 0 0.999931339

0.000000000E+00-1.162898000E-02 0.000000000E+00-4.697524623E-02 0.000000000E+00-0.106378219 0.000000000E+00-0.189702267 0.000000000E+00-0.296924624 0.000000000E+00-0.427972294 0.000000000E+00-0.582764249 0.000000000E+00-0.761199170 0.000000000E+00-0.963156159 1.00000034 -1.18850710 0.999997689 1.00000026 -0.963168610 1.00000006 -0.761213374 1.00000006 -0.582779590 1.00000004 -0.427988151 0.999999775 -0.296940984 1.00000056 -0.189719078 0.999999100 -0.106393013 1.00000069 -4.699745205E-02 1.00000098 -1.163438631E-02

1 2 3 4 5 6 7 8 9 10

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 0 0 0 0 0 0

4 4 4 4 4 4 4 4 4 4

0 0 0 0 0 0 0 0 0 0

23 25 26 27 28 29 30 31 32 33

c!nlgeom,on c!solcontrol,on c!nropt,full,,off c!lnsrch,off c!nsubst,1 c!outres,all,all c!cnvtol,f,,,,1.0e-4 c!cnvtol,m,,,,1.0e-4 c!eqslv,sparse c!solve c! c!/post1 c!set,last c!pres,s c!prdi ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc

1.5.10 Subroutine UsrFictive (Providing User-defined Fictive Temperature Relationship)

subroutine UsrFictive (veinpt,tref,toffst,tem,ftl, ftc) c *** primary function: allow users to write their own c fictive temperature relationship c this logic is accessed with c5 = 11 on the tb,evisc table c *** secondary function: demonstrate the use of a user-written c fictive temperature relationship c c *** notice- this routine contains ansys,inc. confidential information *** c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c input arguments: c variable (type,size,intent) description c c veinpt (dp,ar(95),in) - table from tb,evisc c tref (dp,sc,in) - reference temperature c toffst (dp,sc,in) - temperature offset from absolute zero c tem (dp,sc,in) - temperature at the end of this substep c ftl (dp,sc,in) - previous fictive temperature c c output arguments: c variable (type,size,intent) description c ftc (dp,sc,in) - fictive temperature c

1.5.11 Subroutine UsrViscEl (Performs Visco-elastic Computation)

subroutine UsrViscEl (veinpt,ncomp,tem,dtem,ex,gxy,eex,egxy,phil, x zil,g1l,g2l,hsm,hbm,smcm,bmcm,epsl,epst,ftl,dftl,tref,tvc,dvc, x dsig,rsig,cm,kerr,cml) ****** perform visco-elastic computation - stiffness pass

c c c ***** notice- this routine contains ansys, inc. confidential information **** c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c input arguments: c veinpt (dp,ar(95),in) - viscoelastic input data

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

ncomp tem dtem ex gxy smcm bmcm epsl epst tref

(int,sc,in) (dp,sc,in) (dp,sc,in) (dp,sc,in) (dp,sc,in) (dp,ar(ncomp,ncomp),in) (dp,ar(ncomp,ncomp),in) (dp,ar(ncomp),in) (dp,ar(ncomp),in) (dp,sc,in)

number of components (4 or 6) temperature incremental temperature bulk modulus at infinite time shear modulus at infinite time material matrix for shear modulus material matrix for bulk modulus strain for previous iteration total strain for current iteration reference temperature

output arguments: eex (dp,sc,out) egxy (dp,sc,out) phil (dp,sc,inout) zil (dp,sc,inout) g1l (dp,ar(ncomp,10),out) g2l (dp,ar(ncomp,10),out) hsm (dp,ar(10),out) hbm (dp,ar(10),out) ftl (dp,sc,inout) dftl (dp,ar(10),out) tvc (dp,sc,inout) dvc (dp,sc,out) dsig (dp,ar(ncomp),out) rsig (dp,ar(ncomp),out) cm (dp,ar(ncomp,ncomp),out)kerr (int,sc,out) -

effective bulk modulus effective shear modulus previous shift factor previous pseudo time recursive shear relaxation recursive bulk relaxation recursive shear relaxation recursive bulk relaxation previous fictive temperature incremental fictive temperature total volume change incremental volume change stress change stress relaxation total material matrix error key

argument of convenience: cml (dp,ar(ncomp,ncomp),none)- no value (used only to avoid simplify logic due to variable array sizes)

1.6 Routines for Customizing Material Behavior

This section describes the user routines you use to modify or monitor how materials behave. These routines enable you to perform tasks including:
G G G G G

Writing your own plasticity, creep, or swelling laws Updating the nonlinear strain history for a user-defined material Checking material data you've defined Computing the derivatives of the strain energy density "W" with respect to its invariants Controlling hygrothermal growth.

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.

1.6.1 Subroutine userpl (Writing Your Own Plasticity Laws)

subroutine userpl (elem,intpt,mat,ncomp,kfirst,kfsteq,e,nu,dens, x prop,d,ktform,timval,timinc,tem,dtem,toffst,flu,dflu,epel,eppl, x statev,usvr,epeq,plwork,sigepl,sigrat,depeq,dt) c c *** primary function: c c c allow users to write their own plasticity laws. this logic is accessed with tb,user. the below demonstration logic is the same as using tb,bkin, without adaptive descent (nropt,,,off).

c Other plasticity rules may require internal c iterations and/or the more general definition of c plasticity theory, discussed in the Theory c Manual. c *** secondary function: demonstrate the use of user-written plasticity laws c in this routine: c a. update the nonlinear strain history c b. compute the material tangent matrix if requested c c *** Notice - This file contains ANSYS Confidential information *** c c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c input arguments: c variable (type,size,intent) description c c elem (int,sc,in) - element number (label) c intpt (int,sc,in) - element integration point number c mat (int,sc,in) - material reference number c ncomp (int,sc,in) - no. of stress/strain components (1,4 or 6) c 1 - x c 4 - x,y,z,xy c 6 - x,y,z,xy,yz,xz c kfirst (int,sc,in) - 1 if first time through, 0 otherwise c (useful for initializing state variables c to a non-zero value) c kfsteq (int,sc,in) - 1 if first equilibrium iteration of a c substep, 0 otherwise c c e (dp,sc,in) - average elastic modulus c nu (dp,sc,in) - average poisson ratio c dens (dp,sc,in) - current material density (mass/volume) c prop - linear material property array c (dp,ar(9),in) (ex,ey,ez, gxy,gyz,gxz, nuxy,nuyz,nuxz) c (dp,ar(1),in) if ncomp=1 (ex) c d (dp,ar(ncomp,ncomp),in)- elastic stress-strain matrix c ktform (int,sc,in) - request key for tangent matrix formation c (=1, form tangent =0, do not form) c c timval (dp,sc,in) - current time value c timinc (dp,sc,in) - time increment over this substep c c tem (dp,sc,in) - temperature at the end of this substep c dtem (dp,sc,in) - temperature increment over this substep c toffst (dp,sc,in) - temperature offset from absolute zero c flu (dp,sc,in) - fluence at the end of this substep c dflu (dp,sc,in) - fluence increment over this substep c c epel (dp,ar(ncomp),inout)- modified total strain (trial strain) c epel = eptot - eppl - eptherm - ... c if a large strain analysis, epel is c rotation neutralized and is the hencky c (i.e. log) strain c eppl (dp,ar(ncomp),inout)- plastic strain from previous substep c c statev (dp,ar(ncomp,6),inout)- state variables from previous substep c usvr (dp,ar(nuval,nintp),inout)- additional state variables from c previous equilibrium iteration (saved c if the nsvr command is used) c c epeq (dp,sc,inout) - effective plastic strain from prev substep

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

plwork

(dp,sc,inout)

- accumulated plastic work from prev substep

output arguments: variable (type,size,intent) epel eppl statev usvr epeq plwork sigepl sigrat depeq

description

(dp,ar(ncomp),inout)- elastic strain (dp,ar(ncomp),inout)- updated plastic strain (dp,ar(ncomp,6),inout)- updated state variables (dp,ar(nuval,nintp),inout)- updated additional state variables (dp,sc,inout) (dp,sc,inout) (dp,sc,out) (dp,sc,out) (dp,sc,out) - updated effective plastic strain - updated accumulated plastic work - stress value on stress-strain curve at epeq - ratio of trial stress to yield stress - increment in plastic strain (equivalent) (used for auto time stepping - time step is reduced if it exceeds .05)

dt

(dp,ar(ncomp,ncomp),out)- material tangent modulus

fortran parameters (to be defined by the user): variable (type) description numinp (int) - number of data items in the user-defined data table (tbdat commands) nuval (int) - number of additional state variables per integration point nintp (int) - maximum number of integration points of an element to be used with this routine (14 is the maximum) note: nuval x nintp = nstv(on nsvr command); cannot exceed 840! internal variables: variable (type,size) b (dp,ar(6,6)) c (dp,ar(6,12)) con (dp,sc) deppl (dp,ar(6)) dfds (dp,ar(6)) dlamb (dp,sc) ep (dp,ar(6)) epshfo (dp,ar(6)) epshft (dp,ar(6)) et (dp,sc) h (dp,sc) n2 (int,sc) seqtr (dp,sc) sigtr (dp,ar(6)) sigy (dp,sc) vect (dp,ar(6))

description - 2nd derivative of the yield function - part of deff - temporary variable - plastic strain increment - derivative of the yield function (normal) - plastic multiplier - shifted strain - initial shift strain (center of the yield surf) - shift strain (center of the yield surface) - tangent modulus (stress/total strain) - plastic tangent modulus (stress/plastic strain) - ncomp squared, ncomp*ncomp - equivalent (von mises) trial stress - trial stress - yield stress - temporary vector

1.6.2 Subroutine usercr (Writing Your Own Creep Laws)

subroutine usercr (elem,intpt,mat,ncomp,kfirst,kfsteq,e,posn,d, x proptb,timval,timinc,tem,dtem,toffst,fluen,dfluen,epel,epcrp, x statev,usvr,delcr) c c *** primary function: allow users to write their own creep laws. c this logic is accessed with c6 = 100 c *** secondary function: demonstrate the use of user-written creep laws

c c *** Notice - This file contains ANSYS Confidential information *** c c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c input arguments: c variable (type,size,intent) description c c elem (int,sc,in) - element number (label) c intpt (int,sc,in) - element integration point number c mat (int,sc,in) - material reference number c ncomp (int,sc,in) - no. of stress/strain components (1,4 or 6) c 1 - x c 4 - x,y,z,xy c 6 - x,y,z,xy,yz,xz c kfirst (int,sc,in) - 1 if first time through, 0 otherwise c (useful for initializing state variables c to a non-zero value) c kfsteq (int,sc,in) - 1 if first equilibrium iteration of a c substep, 0 otherwise c c c e (dp,sc,in) - elastic young'S MODULUS c posn (dp,sc,in) - poisson'S RATIO c d (dp,ar(ncomp,ncomp),in)- elastic stress-strain matrix c proptb (dp,ar(72),in) - material properties input on tb commands c c timval (dp,sc,in) - current time value c timinc (dp,sc,in) - time increment over this substep c tem (dp,sc,in) - temperature at the end of this substep c dtem (dp,sc,in) - temperature increment over this substep c toffst (dp,sc,in) - temperature offset from absolute zero c fluen (dp,sc,in) - fluence at the end of this substep c dfluen (dp,sc,in) - fluence increment over this substep c c epel (dp,ar(ncomp),inout)- elastic strain c epcrp (dp,ar(ncomp),inout)- creep strain from previous substep c statev (dp,ar(ncomp*5+2),inout)- state variables from previous substep c usvr (dp,ar(nuval,nintp),inout)- additional state variables from c previous equilibrium iteration (saved c if the nsvr command is used) c c c output arguments: c variable (type,size,intent) description c c epel (dp,ar(ncomp),inout)- elastic strain adjusted for creep increment c epcrp (dp,ar(ncomp),inout)- updated creep strain c statev (dp,ar(ncomp*5+2),inout)- updated state variables c usvr (dp,ar(nuval,nintp),inout)- updated additional state variables c delcr (dp,sc,out) - equivalent creep strain increment (used c for creep ratio calculation) c c fortran parameters (to be defined by the user): c variable (type) description c nuval (int) - number of additional state variables per c integration point c nintp (int) - maximum number of integration points of c an element to be used with this routine c (14 is the maximum) c note: nuval x nintp = nstv(on nsvr command); cannot exceed 840!

c c c c c c c c c c c

internal variables: variable (type,size) con (dp,sc) del (dp,ar(6)) epet (dp,sc) ept (dp,ar(6)) eptot (dp,sc) sigen (dp,sc) temabs (dp,sc)

description - temporary variable - creep strain increments - equivalent elastic strain (before creep) - total strain - equivalent total strain, elastic + creep - equivalent stress (before creep) - temperature on the absolute scale

1.6.3 Subroutine usersw (Writing Your Own Swelling Laws)

subroutine usersw (option,elem,intpt,mat,proptb,ncomp,epswel, x epel,e,nuxy,fluen,dfluen,tem,dtem,toffst,timvll,timvnc,usvr) c c *** primary function: allow users to write their own swelling laws. c this logic is accessed with c72 = 10 c *** secondary function: demonstrate the use of user-written swelling laws 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 input arguments: c option (int,sc,in) swelling option c elem (int,sc,in) element number (label) c intpt (int,sc,in) element integration point number c mat (int,sc,in) material reference number c proptb (dp,ar(*),in) nonlinear material table (tb commands) c ncomp (int,sc,in) number of strain components (=1, 4, or 6) c 1 - truss or beam elements c 4 - 2-d solids and pipe elements c 6 - 3-d solids and most shells c epswel (dp,sc,inout) total accumulated swelling strain c before this substep c epel (dp,ar(ncomp),inout) elastic strain c e (dp,sc,in) elastic modulus c nuxy (dp,sc,in) poisson'S RATIO c fluen (dp,sc,in) total fluence (bf or bfe commands) c dfluen (dp,sc,in) increment in fluence for this substep c tem (dp,sc,in) temperature (bf or bfe commands) c dtem (dp,sc,in) increment in temperature for this substep c toffst (dp,sc,in) offset of temperature scale from absolute zero c (toffst command) c timvll (dp,sc,in) time at the end of this substep c timvnc (dp,sc,in) the increment of time this substep c usvr (dp,ar(*),inout) user-defined state variables(optional) c c output arguments: c epswel (dp,sc,inout) total accumulated swelling strain c after this substep c epel (dp,ar(ncomp),inout) elastic strain adjusted c for swelling increment c usvr (dp,ar(*),inout) updated user-defined state variables c

1.6.4 Subroutine uservp (Updating Nonlinear Strain History for Materials)

subroutine uservp (elem,mat,kfirst,kfsteq,g,prop,timval,timinc, x tem,toffst,delepn,svrn,svri,usvr,epeln,epeli,strn,stri,depdt, x cee,eta,norm) c c *** primary function: update the nonlinear strain history for a c user-defined material for the viscoxxx elements c *** secondary functions: compute the material tangent terms c accessed with tb,user and keyopt(1) = 1 c c *** Notice - This file contains ANSYS Confidential information *** c c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c input arguments: c variable (type,size,intent) description c c elem (int,sc,in) - element number (label) c mat (int,sc,in) - material reference number c kfirst (int,sc,in) - 1 if first time through, 0 otherwise c (useful for initializing state variables c to a non-zero value) c kfsteq (int,sc,in) - 1 if first equilibrium iteration of a c substep, 0 otherwise c c g (dp,sc,in) - shear modulus c prop (dp,ar(13),in) - linear material property array c (ex,ey,ez, gxy,gyz,gxz, nuxy,nuyz,nuxz, c alpx,alpy,alpz, dens) c c timval (dp,sc,in) - current time value c timinc (dp,sc,in) - time increment over this substep c c tem (dp,sc,in) - temperature at the end of this substep c toffst (dp,sc,in) - temperature offset from absolute zero c c delepn (dp,ar(3,3),in) - hencky strain increment over the substep c c svrn (dp,sc,in) - state variable from previous substep c svri (dp,sc,inout) - state variable from previous iteration c usvr (dp,ar(*),inout) - additional state variables from previous c iteration (saved if the nsvr command is c used) c c epeln (dp,ar(3,3),in) - elastic strain from previous substep c epeli (dp,ar(3,3),inout) - elastic strain from previous iteration c c strn (dp,ar(3,3),in) - stress from previous substep c stri (dp,ar(3,3),inout) - stress from previous iteration c c depdt (dp,sc,inout) - effective inelastic deformation rate c (d(deppl)/dt) from previous iteration c c output arguments: c variable (type,size,intent) description c c svri (dp,sc,inout) - updated state variable c usvr (dp,ar(*),inout) - updated additional state variables c c epeli (dp,ar(3,3),inout) - updated elastic strain c stri (dp,ar(3,3),inout) - updated stress c

c c c c c c c c c c c c c c c c c

depdt cee eta norm

(dp,sc,inout) (dp,sc,out) (dp,sc,out) (dp,ar(3,3),out)

- effective inelastic deformation rate - scalar linearization modulus (see below) - radial return factor (see below) - direction of plastic flow

fortran parameters (to be defined by the author): variable (type) description numinp (int) - number of data items in the user-defined data table (tbdat commands) nuval (int) - number of additional state variables per integration point nintp (int) - maximum number of integration points of an element to be used with this routine (8 is the maximum) note: nuval x nintp cannot exceed 840!

1.6.5 Subroutine userck (Checking User-Defined Material Data)

subroutine userck (curmat,ntb,tb) c *** primary function: check the user-defined material data, c input with the TB,user command. c *** secondary functions: none 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 input arguments: c curmat (int,sc,in) - current material number c ntb (int,sc,in) - dimension of tb c tb (dp,ar(ntb),in) - input table c c output arguments: c none c

1.6.6 Subroutine usrmooeny (Computing Derivatives of Strain Energy Density with Respect to Invariants)
subroutine usrmooney (mat,xnu,xiii,ndf,wi,wij,wini,pi,pij,prs,bm) c c *** primary function: c c this is a user subroutine to compute the derivatives of the c strain energy density 'W' with respect to its invariants. c the user can modify this subroutine in order to incorporate c their own material law. c accessed with keyopt(7) = 1 and tb,mooney c c *** Notice - This file contains ANSYS Confidential information *** c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c *** comments: c c by definition, a material is said to be hyperelastic, if there c exists a strain energy density function, which is a scalar c function of one of the strain or deformation tensors, whose

c derivative with respect to a strain component determines the c corresponding stress component. c c these strain energy density functions are functions of c invariants of strain tensors and a set of constants determined c in the laboratory tests. the user can specify their own form c of the strain energy density functions in terms of the invariants c of the cauchy-green tensors and a number of laboratory-determined c constants. c c in this subroutine the user is provided with (1) the invariants c 'XIII' of the cauchy-green strain tensor and (2) a flag 'NDF' c identifying the dimensionality of the problem. c c the subroutine first computes the distortion-only invariants c 'XJJJ'. the material constants that were specified by the user c through the 'TB' table are now put into local variables, e.g., c 'AI' and 'BI' in the mooney-rivlin example. the user then c defines the expression for the strain energy density function. c the term of 'W' involving 'BM' must remain intact; the c user will have their own expression for the first part of 'W', c e.g., terms involving constants 'AI' and 'BI' of the example of the c mooney-rivlin material. the expression for the distortion-based c pressure 'PRS' remains the same. 'PRS' along with 'BM' control c the degree of incompressibility of the material. c c the user will have to find the expressions for the derivatives c of 'W' (derivatives of 'PRS' remaining the same), i.e., 'WI' c and 'WIJ'. the subroutine returns the values of 'WINI', 'WI', c 'WIJ', 'PRS', 'PI', 'PIJ' and 'BM'. c c ---------------------------------------------------------------------c c input arguments: c xiii (dp,ar(3),in) - invariants of the cauchy-green tensor c mat (int,sc,in) - material reference number c xnu (dp,sc,in) - input possions ratio c ndf (int,sc,in) - dimensionality of the problem c (2 for plane strain) c (3 for 3d/axisymmetric) c c output arguments: c wi (dp,ar(3),out) - first derivatives of strain energy density c with respect to invariants c wij (dp,ar(3,3),out) - second derivatives of strain energy density c with respect to invariants c wini (dp,sc,out) - strain energy density c c pi (dp,ar(3),out) - first derivatives of pressure c with respect to invariants c pij (dp,ar(3,3),out) - second derivatives of pressure c with respect to invariants c prs (dp,sc,out) - pressure c bm (dp,sc,out) - bulk modulus c c ---------------------------------------------------------------------c c definitions : c -------------------------------------------c wi(1) = d(w)/d(xiii(1)) c wi(2) = d(w)/d(xiii(2)) c wi(3) = d(w)/d(xiii(3)) c

c c c c c c c c c c c c c c c c c c c c c

wij(1,1) = d**2(w)/d(xiii(1))*d(xiii(1)) wij(1,2) = d**2(w)/d(xiii(1))*d(xiii(2)) wij(1,3) = d**2(w)/d(xiii(1))*d(xiii(3)) wij(2,2) = d**2(w)/d(xiii(2))*d(xiii(2)) wij(2,3) = d**2(w)/d(xiii(2))*d(xiii(3)) wij(3,3) = d**2(w)/d(xiii(3))*d(xiii(3)) -------------------------------------------pi(1) = d(prs)/d(xiii(1)) pi(2) = d(prs)/d(xiii(2)) pi(3) = d(prs)/d(xiii(3)) pij(1,1) = d**2(prs)/d(xiii(1))*d(xiii(1)) pij(1,2) = d**2(prs)/d(xiii(1))*d(xiii(2)) pij(1,3) = d**2(prs)/d(xiii(1))*d(xiii(3)) pij(2,2) = d**2(prs)/d(xiii(2))*d(xiii(2)) pij(2,3) = d**2(prs)/d(xiii(2))*d(xiii(3)) pij(3,3) = d**2(prs)/d(xiii(3))*d(xiii(3)) --------------------------------------------

1.6.7 Subroutine usermc (Controlling Hygrothermal Growth)

subroutine usermc (elem,time,msci,dmsci,mscr,mscra) c *** primary function: user control of hygrothermal growth c *** secondary functions: none c presently, called only by shell91 c c in order to activate this user programmable feature, c the user must enter the usrcal command. 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 input arguments: c elem (int,sc,in) - element number c time (dp,sc,in) - time c msci (dp,sc,in) - moisture content c dmsci (dp,sc,in) - change of moisture content c mscr (dp,ar(3),in) - input material properties for growth c c output arguments: c mscra (dp,ar(3),out) - output material properties for growth c

1.6.8 Subroutine usermu (Supplying a Friction Coefficient for CONTAC48 and CONTAC49)
subroutine usermu (elem,type,mat,area,gap,loc,fn,nusvr,usvr, x time,timinc,vel,temp,stat,oldst,prevst,oldmu,prevmu,mu) c c *** primary function: user supplied coefficient of friction c called only by contac48,49 c accessed by keyopt(9) > 0 c c *** Notice - This file contains ANSYS Confidential information *** c c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

*** ansys, inc. input arguments: variable (typ,siz,intent) elem (int,sc,in) type (int,sc,in) mat (int,sc,in) area (dp,sc,in) gap loc (dp,sc,in) (dp,ar(2),in)

fn nusvr usvr time timinc vel temp oldst

(dp,sc,in) (int,sc,in) (dp,ar(nusvr),in) (dp,sc,in) (dp,sc,in) (dp,ar(2),in) (dp,sc,in) (int,sc,in)

prevst

(int,sc,in)

stat

(int,sc,in)

oldmu prevmu

(dp,sc,in) (dp,sc,in)

description element number element type number material number element area (contac49) or length (contac48) - present gap or penetration - location of the contact node projected to the target surface - in dimensionless element coordinates - current contact force normal to the target plane - number of user-supplied element variables - user-supplied element variables - current time - current substep time increment - contact node velocity components in the target plane - average temperature - status of previous time step (3,4: open; 2: closed and sliding; (1: closed and stuck) - status of previous iteration (3,4: open; 2: closed and sliding; (1: closed and stuck) - current status (3,4: open; 2: closed and stickslide status undetermined) - friction coefficient used in the previous time step - friction coefficient used in the previous iteration -

output arguments: variable (typ,siz,intent) mu (dp,sc,out)

description - friction coefficient to be used this time step and iteration

1.6.9 Subroutine usrfc6 (Defining Custom Failure Criteria)

c c c c c c c c c c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c *** Notice - This file contains ANSYS Confidential information *** c subroutine usrfc6 (elem,matlay,iott,keyer,tem,elim,slim,eps,sig, x fc6) primary function: user subroutine for defining your own failure criterion *** secondary functions: none --- accessed with c6 = -1 *** user programmable functions may not be used in parallel processing *** this is currently only available with shell99, the multilayer shell element solid46, the multilayer solid element shell91, the multilayer shell element

c input arguments: c variable (typ,siz,intent) c elem (int,sc,in) c elim (dp,ar(9),in) c c slim (dp,ar(12),in) c c c eps (dp,ar(6),in) c sig (dp,ar(6),in) c tem (dp,sc,in) c matlay (int,sc,in) c iott (int,sc,in) c keyer (int,sc,in) c c output arguments: c variable (typ,siz,intent) c fc6 (dp,sc,out) c c #include "impcom.inc" external erhandler c

description - element number - failure strains at the current temperature (tbdata items 1-9) - failure stresses and coupling coefficients at the current temperature (tbdata items 10-21) - vector of strains - vector of stresses - temperature at this point in the model - material number - unit number for writing - error flag (0 = ok, 1 = error)

description - failure criterion to be processed by solid46, shell91, or shell99

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

1.6.10 Subroutines usrfc1 through usrfc5

The source code for subroutines usrfc1, usrfc2, usrfc3, usrfc4, and usrfc5 is identical to subroutine usrfc6 shown above.

1.6.11 Subroutine UserVisLaw (Defining Viscosity Laws)

subroutine UserVisLaw x (dudx,dudy,dudz, x dvdx,dvdy,dvdz, x dwdx,dwdy,dwdz, x u,v,w,x,y,z,kGeom, x Vis,Temp,Tref,Pres,Pref,Cf, x MFrac,DfNSpec,Time,VisNew) C C C C C C C C C C C C C C C C Primary function: to provide a user defined viscosity relationship in terms of the following: pressure, temperature, position, time, velocity, & velocity-gradient In order to activate this subroutine the user must issue FLDA,PROT,VISC,USRV command. In addition the initial value of viscosity must be specified via FLDA,PROP,IVIS,value. This value is not available in this routine. Optionally the user may specify 4 additional coefficients which are available in this routine by the commands: FLDA,NOMI,VISC,value1 FLDA,COF1,VISC,value1 FLDA,COF2,VISC,value2

C C c c C C C C C C C C C C C C C C C C C C C C C C C C C C C C C C C C C

FLDA,COF3,VISC,value3 *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 *** ansys, inc. input arguments: variable (typ,siz,intent) dudx (dp,sc,in) dudy (dp,sc,in) dudz (dp,sc,in) dvdx (dp,sc,in) dvdy (dp,sc,in) dvdz (dp,sc,in) dwdx (dp,sc,in) dwdy (dp,sc,in) dwdz (dp,sc,in) u (dp,sc,in) v (dp,sc,in) w (dp,sc,in) x (dp,sc,in) y (dp,sc,in) z (dp,sc,in) kGeom (int,sc,in) Vis (dp,sc,in) Temp (dp,sc,in) Tref (dp,sc,in) Pres (dp,sc,in) Pref (dp,sc,in) Cf (dp,ar(4),in) Mfrac (dp,ar(6),in) DfNSpec (int,sc,in) Time (dp,sc,in) output arguments: variable (typ,siz,intent) VisNew (dp,sc,out)

description velocity gradient component velocity gradient component velocity gradient component velocity gradient component velocity gradient component velocity gradient component velocity gradient component velocity gradient component velocity gradient component velocity component velocity component velocity component position component position component position component analysis type old viscosity temperature reference temperature pressure reference pressure input coefficients species mass fractions defined number of species time

description new viscosity

1.6.12 Supporting Function egen

The function egen (kcomp,ep,nuxy) (function) combines kcomp strain components (ep) per: function egen (kcomp,ep,posn) c primary function: combines strain components to give an "overall" strain c used in creep and plasticity calculations c secondary functions: none c c c c c c c formulation of overall value is by: ___________________________________________________________________ /1 2 2 2 1 2 2 2 \ / -*((ep - ep ) + (ep - ep ) + (ep - ep ) + -*(ep + ep + ep )) \/ 2 1 2 2 3 3 1 2 4 5 6 -----------------------------------------------------------------------(1 + posn)

c *** Notice - This file contains ANSYS Confidential information *** c c c c typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) kcomp (int,sc,in) siz=sc,ar(n) intent=in,out,inout

description - number of components of strain

c c c c c

ep posn

(dp,ar(6),in) (dp,sc,in)

- the strain components - poisson's ratio

output arguments: egen (dp,func,out)

- the combined strain value

1.7 Routines for Customizing Loads

This section describes the user routines you use to modify or monitor existing ANSYS elements. These routines enable you to perform tasks including:
G G G G G G G

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.

1.7.1 Subroutine usrefl (Changing Scalar Fields to User-Defined Values)

subroutine usrefl (key,iel,ielc,nnod,nodes,time,defalt,nd,dat) c *** primary function: change the scalar fields (temperatures, fluences, c heat generation, etc.) to what user desires. c *** secondary functions: none c c in order to activate this user programmable feature, c the user must enter the usrcal command. c c this routine is called at each substep of each load step c for which element or nodal temperatures(etc) are used. c it is called for each equilibrium iteration. c the call to get the standard ansys input element or nodal values c is made just before entering this routine. c c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. 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 data desired c = 1 temperatures c = 2 fluences c = 3 heat generation rates c = 4 moisture contents c = 5 magnetic virtual displacements c iel (int,sc,in) - element number c ielc (int,ar(IELCSZ),in) - array of element type characteristics c nnod (int,sc,in) - number of nodes c nodes (int,ar(nnod),in) - list of nodes c time (dp,sc,in) - time of current substep c defalt (dp,sc,in) - default value (e.g. tunif)

c c c c c c c c c c c c c c c c

nd dat

(int,sc,in) - size of dat array (dp,ar(nd),inout) - array of data as normally computed by element as selected by key

output arguments: variable (typ,siz,intent) description dat (dp,ar(nd),inout) - array of data passed back to element this data represents values at the end of the load step the input argument dat may be used in one of three ways: 1. it may be simply passed thru 2. it may be used as a flag(e.g. if dat(1) = -3.0, use a certain set of logic) 3. it may be completely ignored and instead defined with new logic

1.7.2 Subroutine userpr (Changing Element Pressure Information)

subroutine userpr (ielc,ielem,time,ndat,dat) c *** primary function: change element pressure information. c c in order to activate this user programmable feature, c the user must enter the usrcal command. c c this routine is called at each substep of each load step for which c pressures are used. it is called for each equilibrium iteration. c it is called once per element. c the call to get the standard ansys input pressures is made just before c entering this routine. 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 input arguments: c variable (typ,siz,intent) description c ielc (int,ar(IELCSZ),in) - array of element type characteristics c ielem (int,sc,in) - element number for operation. c time (dp,sc,in) - time of current substep c ndat (int,sc,in) - number of pressure items for this element c dat (dp,ar(ndat),inout) - the element pressure vector c (has input values for each corner c of each face) c c output arguments: c variable (typ,siz,intent) description c dat (dp,ar(ndat),inout) - the element pressure vector c (defines input values for each corner c of each face) c c the input array dat may be used in one of three ways: c 1. it may be simply passed thru c 2. it may be used as a flag(e.g. if dat(1) = -3.0, use c a certain set of logic) c 3. it may be completely ignored and instead defined with new logic

1.7.3 Subroutine usercv (Changing Element Face Convection Surface Information)

subroutine usercv (elem,ielc,time,nr,u, ndat,hc,tb)

c *** primary function: change element face convection surface info c c in order to activate this user programmable feature, c the user must enter the 'usrcal,usercv' command. c c *** ansys(r) copyright(c) 1998 c *** ansys, inc. c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c elem (int,sc,in) - element number for operation. c ielc (int,ar(IELCSZ),in) - array of element type characteristics c time (dp,sc,in) - time of current substep c nr (int,sc,in) - number of nodal temperatures c of the element c u (dp,ar(nr),in) - vector of most recent values of the c temperatures c ndat (int,sc,in) - number of data points per element c hc (dp,ar(ndat),inout) - film coefficients c (has input values for each corner c of each face) c tb (dp,ar(ndat),inout) - bulk temperature c (has input values for each corner c of each face) c c output arguments: c variable (typ,siz,intent) description c hc (dp,ar(ndat),inout) - film coefficients c (defines input values for each corner c of each face) c tb (dp,ar(ndat),inout) - bulk temperature c (defines input values for each corner c of each face) c c the input arguments hc and tb 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 hc(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 c c c c c c c c c c c c this routine is called during each substep of each load step. it is called for each equilibrium iteration. it is called once per element. it is called only during the heat flow load vector formulation stage, and not during the heat flow evaluation stage. the call to get the standard ansys input convection surfaces is made just before entering this routine, so this information is available to be modified, if desired. velocity-dependent film coefficients can be computed by inputting the velocity as the input film coefficient or bulk temperature or by inputting the velocity as a function of location in space. this routine could then compute the effective film coefficient.

1.7.4 Subroutine userfx (Changing Element Face Heat Flux Surface Information)
subroutine userfx (ielc,ielem,time,nr,u, ndat,dat) c *** primary function: change element face heat flux surface info

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

in order to activate this user programmable feature, the user must enter the usrcal command. this routine is called during each substep of each load step. it is called for each equilibrium iteration. it is called once per element. it is called only during the heat flow load vector formulation stage, and not during the heat flow evaluation stage. the call to get the standard ansys input heat flux surfaces is made just before entering this routine, so this information is available to be modified, if desired. *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 *** ansys, inc. input arguments: variable (typ,siz,intent) ielc (int,ar(IELCSZ),in) ielem (int,sc,in) time (dp,sc,in) nr (int,sc,in) u ndat dat

description array of element type characteristics element number for operation. time of current substep number of nodal temperatures of the element (dp,ar(nr),in) - vector of most recent values of the temperatures (int,sc,in) - number of data points per element (dp,ar(ndat),inout) - fluxes (has input values for each corner of each face) -

output arguments: variable (typ,siz,intent) description dat (dp,ar(ndat),inout) - fluxes (defines input values for each corner of each face)

the input argument dat may be used in one of three ways: 1. they may be simply passed thru. 2. they may be used as a flag(e.g. if dat(2) = -3.0, use a certain set of logic). 3. they may be completely ignored. and instead redefined with new logic

1.7.5 Subroutine userch (Changing Element Face Charge Density Surface Information)
subroutine userch (ielc,ielem,time,nr,u, ndat,dat) c *** primary function: change element face charge density surface info c c in order to activate this user programmable feature, c the user must enter the usrcal command. c c this routine is called during each substep of each load step. c it is called once per element. it is called only during the heat c flow load vector formulation stage, and not during the heat flow c evaluation stage. c the call to get the standard ansys input charge densities of surfaces c is made just before entering this routine, so this information is c available to be modified, if desired. c

c c c c c c c c c c c c c c c c c c c c c c c c c

*** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 *** ansys, inc. input arguments: variable (typ,siz,intent) ielc (int,ar(IELCSZ),in) ielem (int,sc,in) time (dp,sc,in) nr (int,sc,in) u ndat dat

description array of element type characteristics element number for operation. time of current substep number of nodal temperatures of the element (dp,ar(nr),in) - vector of most recent values of the temperatures (int,sc,in) - number of data points per element (dp,ar(ndat),inout) - fluxes -

output arguments: variable (typ,siz,intent) description dat (dp,ar(ndat),inout) - fluxes the input argument dat may be used in one of three ways: 1. they may be simply passed thru. 2. they may be used as a flag(e.g. if dat(2) = -3.0, use a certain set of logic). 3. they may be completely ignored. and instead redefined with new logic

1.7.6 Subroutine useracel (Modifying an Element's Acceleration/Angular Velocity Information)

subroutine useracel (key,elem,vect) c primary function: c c c c keywords: Modify the acceleration/angular velocity information for an element. Currently(5.3), only works with angular velocities used by spin softening.

user subroutine to return acceleration field

c object/library: c current - acel c *** Notice - This file contains ANSYS Confidential information *** c *** ansys(r) copyright(c) 1971,78,82,83,85,87,89,92,94-97 c *** ansys, inc. c c c c c c c c c vc c c input arguments: key (int,sc,in)

- Key 0 1 2 3 4 5 -

to desired acceleration components Translational acceleration Angular Velocity Angular Acceleration Angular Velocity around C.G. Angular Acceleration arount C.G. C.G. Location in global coord. system

NOTE: elem

Only key=1 for spin softening is currently implemented (int,sc,in) - Element number

output arguments: vect (dp,ar(3),out)

- Return value as given by key

1.7.7 Examples of Using the Load Customization Routines

This section presents examples of how two of the load customization UPFs, the usercv subroutine and the useracel subroutine, can affect analysis results.

1.7.7.1 Example of Using usercv

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 et,2,19,1,, ,1,1 keyo,2,8,2 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

! flag to save values ! temp DOF, no midside nodes, has extra node ! flag for convection surface

Now, look at the results from this example analysis (shown below). Note that the FLOW RATE magnitude for FLUID66 matches the HFILM for SURF19.

***** uelEMENT SOLUTION ***** LOAD STEP= 2 SUBSTEP = uel= 1 NODES= 1 2 0.00000E+00 FLOW RATE= -4.4721 HT COND RATE= 128.60 0.00000E+00 HT TRANSP RATE= 0.00000E+00 FRICTION FACTOR= 0.100000E-01 0.00000E+00

1 0

TIME = CUM. ITER.= 0 MAT=

2.0000 3 1 PUMP HD= 0.00000E+00 RE=

FLUID66 HT CONV RATES(I,J)= 0.00000E+00

CONV AREAS(I,J)=

0.00000E+00

HFILM=

0.00000E+00 0 FLUID66 HT CONV RATES(I,J)= 0.00000E+00 0 MAT= 1 PUMP HD= 0.00000E+00 RE=

uel= 2 NODES= 2 3 0.00000E+00 FLOW RATE= -4.4721 HT COND RATE= -80.801 0.00000E+00 HT TRANSP RATE= 0.00000E+00 FRICTION FACTOR= 0.100000E-01 0.00000E+00 HFILM= 0.00000E+00 uel= 3 NODES= 3 4 0.00000E+00 FLOW RATE= -4.4721 HT COND RATE= -80.801 0.00000E+00 HT TRANSP RATE= 0.00000E+00 FRICTION FACTOR= 0.100000E-01 0.00000E+00 HFILM= 0.00000E+00

CONV AREAS(I,J)=

0.00000E+00

0 FLUID66

0 MAT=

1 PUMP HD= 0.00000E+00

RE=

HT CONV RATES(I,J)=

0.00000E+00

CONV AREAS(I,J)=

0.00000E+00

*** WARNING *** CP= 0.800 TIME= 17:23:49 ANSYS,INC.-supplied version of coding for USERCV has been used. Using getvel66, the velocity from node 2 is 0.4472E+01 uel= VOLUME= 4 SURFACE NODES= 30.000 12 EXTRA NODE= 2 MAT= 1 AREA= 30.000 SURF19 HFILM= 4.4721 4.4721 TBULK= 10.299 10.299 CONV. HEAT RATE= -209.40 CONV. HEAT RATE/AREA= -6.9801 11

TAVG=

8.7381

*** WARNING *** CP= 0.800 TIME= 17:23:49 ANSYS,INC.-supplied version of coding for USERCV has been used. uel= 5 NODES= -0.2753 11 13 14 MAT= PLANE55 -0.6346 0.6917 12 1 VOL= 90.00 3.029 6.980

TG(X,Y,SUM)= 7.609 1

TF(X,Y,SUM)=

1.7.7.2 Effect of useracel on Results

This example uses a two-dimensional model based on element PLANE42: c c c c c

Two Dimensional model (plane42) component rotation FAST OMGFAST SLOW OMGSLOW external cmpcheck, parevl logical cmpcheck double precision parevl integer kerr double precision subc(3) data subc / 3*0.0d0 / if (key .eq. 1) then --- see if element is a member of component FAST: if (cmpcheck('FAST ',elem)) then vect(2) = parevl('OMGFAST ',0,subc(1),1,kerr) --- see if element is a member of component SLOW:

elseif (cmpcheck('SLOW ',elem)) then vect(2) = parevl('OMGSLOW ',0,subc(1),1,kerr) endif endif return end

The ANSYS input used for this model is as follows: /bat,list /title, demonstrate /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 cm,FAST,elem eall esel,s,elem,,21,30 cm,SLOW,elem eall omega,0,0,0,1 OMGFAST = 1000 OMGSLOW = 500 ! note that first 10 finish /solu /title, BASE CASE /title, DEMONSTRATE

use of useracel

! define FAST component

! define SLOW component

! turn on spin softening ! define parameter for use in useracel ! define parameter for use in useracel elements will be stationary

STANDARD VERSION 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: *** FREQUENCIES FROM BLOCK LANCZOS ITERATION *** MODE FREQUENCY (HERTZ) 1 287.3798632612 2 287.3798632612 3 287.3798632612 4 869.2433944257 5 869.2433944257 6 869.2433944259

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: *** FREQUENCIES FROM BLOCK LANCZOS ITERATION *** MODE FREQUENCY (HERTZ) 1 239.2841196099 2 276.1423760135 3 287.3798632612 4 854.5488768013

5 6

865.5931519918 869.2433944258

1.8 Running ANSYS as a Subroutine

To call the ANSYS program, use the following: 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.9 Defining Your Own Commands

ANSYS, Inc. supplies a set of user routines, named user01 through user10, which you can use to define custom ANSYS commands. To do so, follow these steps: 1. Insert the code for the functions you want to perform into routine user01 (or user02, etc.). 2. Link the routine into the ANSYS program. 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.

1.9.1 Function user01

*deck,user01 user parallel c sid 5.1 copy of file s.user01.F last changed by jtm on 98/03/09 function user01 (intin,dpin,ch4in,ch8in) c *** primary function: user routine number 01 ANSYS,INC

c c *** ansys(r) copyright(c) 1998 c *** ansys, inc. c *** Notice - This file contains ANSYS Confidential information *** c c /*******************************************************************\ c | this is a user routine that may be used by users to include their | c | special coding. accesss to this routine is by the command usr1. | c | usr1 may be changed by the user using the command /ucmd. the | c | user may then use this routine to call his/her special routines. | c | ansys routines to access information in the ansys database may be | c | found in the "ansys programmer's manual", available from ansys,inc| c | see user02 for a simple example usage. | C | routines user03 to user10 are also available. | C \*******************************************************************/ 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 If the usage had been set up with a /ucmd,aaaa,1 , c user01 could be activated by the command aaaa,ln,6,all c where ln = lab4in(2) c 6 = intin(3) c all = lab4in(4) c c output arguments: none c user01 (int,sc,out) - result code (should be zero) c (which is ignored for now) c c ************************************************************** c intin(2), dpin(2), ch4in(2), and ch8in(2) are all representations c of the contents of the second field on the command line c (the field after the command label) c ************************************************************** c external wrinqr integer wrinqr c integer user01,intin(12), iott double precision dpin(12) character*4 ch4in(12) character*8 ch8in(12) c iott = wrinqr(2) c c ***** user'S CODE IS INSERTED HERE ***** write (iott,2000) 2000 format (//' ***** CALL TO ANSYS,INC DUMMY USER01 *****'//) c c ***** do not return this result code in a real user routine user01 = -654321 c ***** instead return a zero ***** c user01 = 0 c return end

1.9.2 Function user02 (Demonstrates Offsetting Selected Nodes)

*deck,user02 user ANSYS,INC c sid 5.1 copy of file s.user02.F last changed by jtm on 98/03/09 function user02 (intin,dpin,ch4in,ch8in) c *** primary function: user routine number 02 c --- This demonstration offsets selected nodes with the command: c usr2,dx,dy,dz c *** ansys(r) copyright(c) 1998 c *** ansys, inc. c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c c c c /*******************************************************************\ | see user01 for additional information on user routines | \*******************************************************************/ input arguments: variable (typ,siz,intent) intin (int,ar(12),in) dpin (dp,ar(12),in) ch4in (ch*4,ar(12),in) ch8in (ch*8,ar(12),in) output arguments: none user02 (int,sc,out)

description integers from command line double precision from command line upper case 4 characters from command as input 8 characters from command

- result code (should be zero) (which is ignored for now)

************************************************************** intin(2), dpin(2), ch4in(2), and ch8in are all representations of the contents of the second field on the command line (the field after the command label) ************************************************************** external integer wrinqr,ndinqr,ndgxyz,ndpxyz,erhandler wrinqr,ndinqr,ndgxyz

integer user02,intin(12), iott, maxnp,i,ksel double precision dpin(12),xyz(3) character*4 ch4in(12) character*8 ch8in(12) #include "ansysdef.inc" maxnp = ndinqr (0,DB_MAXDEFINED) 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 c ***** write to output file iott = wrinqr(WR_OUTPUT) write (iott,2000) 2000 format (/' NODE OFFSET COMPLETE *****

'/)

***** write to GUI window ***** call erhandler ('user02',3000, x 2,'NODE OFFSET COMPLETE',0.0d0,' ')

***** user02 = 0 return end

required return value

*****

1.9.3 Function user03 (Demonstrates Using Heap Memory)

*deck,user03 user ANSYS,INC c sid 5.1 copy of file s.user03.F last changed by jtm on 98/03/09 function user03 (intin,dpin,ch4in,ch8in) c *** primary function: user routine number 03. Gives example of c Heap usage c c *** ansys(r) copyright(c) 1998 c *** ansys, inc. c *** Notice - This file contains ANSYS Confidential information *** c c /*******************************************************************\ c | see user01 for additional information on user routines | c \*******************************************************************/ 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 output arguments: none c user03 (int,sc,out) - result code (should be zero) c (which is ignored for now) c 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 ************************************************************** c #include "impcom.inc" external wrinqr,ndinqr,ndgxyz,ndnext,HeapAllocPtr, x HeapDealloc,erhandler integer wrinqr,ndinqr,ndgxyz,ndnext,HeapAllocPtr user03, intin(12), iott, i, ksel, xcptr, hXcptr, ycptr, hYcptr, zcptr, hZcptr, numnp, node double precision dpin(12),xyz(3), xmean, ymean, zmean, stdxyz(3), x sodx, sody, sodz character*4 ch4in(12) character*8 ch8in(12) x #include "ansysdef.inc" #include "stack.inc" c c c c c integer

Get nodal xyz locations and calculate standard deviation of x coordinates, y coordinates, & z coordinates

get number of currently selected nodes numnp = ndinqr (0,DB_NUMSELECTED)

if (numnp .le. 0) go to 999 c allocate memory for x, y, & z coordinates of nodes xcptr = HeapAllocPtr(numnp,'XCoords ',HEAP_DOUBLE,hXcptr) ycptr = HeapAllocPtr(numnp,'YCoords ',HEAP_DOUBLE,hYcptr) zcptr = HeapAllocPtr(numnp,'ZCoords ',HEAP_DOUBLE,hZcptr) loop through all selected nodes i=1 node = 0 xmean = 0.0d0 ymean = 0.0d0 zmean = 0.0d0 node = ndnext(node) if (node .gt. 0) then c get xyz coordinates ksel = ndgxyz (node,xyz(1)) store this node's dstack(xcptr + i) dstack(ycptr + i) dstack(zcptr + i) while xmean ymean zmean xyz coordinates = xyz(1) = xyz(2) = xyz(3)

10

we're looping, accumulate sums to calculate means = xmean + xyz(1) = ymean + xyz(2) = zmean + xyz(3)

increment index i = i + 1 loop back up for next selected node goto 10 endif

c c

node = 0, at the end of node list calculate mean of xyz coordinates xmean = xmean / numnp ymean = ymean / numnp zmean = zmean / numnp calculate standard deviation for xyz coordinates sodx = 0 sody = 0 sodz = 0 do i=1, numnp sodx = sodx + (dstack(xcptr+i) - xmean)**2 sody = sody + (dstack(ycptr+i) - ymean)**2 sodz = sodz + (dstack(zcptr+i) - zmean)**2 enddo stdxyz(1) = sqrt(sodx / (numnp-1)) stdxyz(2) = sqrt(sody / (numnp-1)) stdxyz(3) = sqrt(sodz / (numnp-1))

***** write to output file ***** iott = wrinqr(WR_OUTPUT) write (iott,2000) stdxyz(1),stdxyz(2),stdxyz(3) 2000 format (/' STD FOR X COORDINATES:',G12.5,/, X ' STD FOR Y COORDINATES:',G12.5,/, X ' STD FOR Z COORDINATES:',G12.5)

***** write to GUI window ***** call erhandler ('user03',5000,2, x 'STD FOR X COORDINATES: %G %/ STD FOR Y x COORDINATES: %G %/ STD FOR Z COORDINATES: %G',stdxyz(1),' ') release dynamically allocated memory call HeapDealloc(hXcptr) call HeapDealloc(hYcptr) call HeapDealloc(hZcptr) ***** required return value user03 = 0 return end *****

c 999

1.9.4 Functions user04 through user10

The source code for user routines user04, user05, user06, user07, user08, user09, and user10 is identical to function user01 shown above.

1.10 Supporting Subroutines

1.10.1 Function GetRForce (Getting Nodal Reaction Force values)
function user03 (intin,dpin,ch4in,ch8in) c *** primary function: user routine number 03. Gives example of c Heap usage 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 /*******************************************************************\ c | see user01 for additional information on user routines | c \*******************************************************************/ 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 output arguments: none c user03 (int,sc,out) - result code (should be zero) c (which is ignored for now) c 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 ************************************************************** c

1.10.2 Function GetStackDisp (Getting Current Displacement Values)

function GetStackDisp (Node,Label,Value) 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 *** Notice - This file contains ANSYS Confidential information *** c Prolog is not CONFIDENTIAL INFORMATION c c c c c c c c c c c c c c typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) Node (int,sc,in) Label (ch*4,sc,in) siz=sc,ar(n) intent=in,out,inout

description - Node Number (User) - DOF Label (Upper Case) 'UX ','UY ','TEMP','VOLT','ROTY', etc

output arguments: variable (typ,siz,intent) GetStackDisp (int,sc,out)

Value

(dp,sc,out)

description - status/pointer = 0 - data not valid > 0 - dstack pointer to data for fast access see comments below - Solution value for Node,Label

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 c c ptr = GetStackDisp (Node2,'UY ',Value)

later... Value = dstack(ptr)

1.10.3 Subroutine ElResultStrt (Getting Load Data from Analysis Results)

subroutine ElResultStrt (Label,Comp,LabAvg,TypeData,nVal,Loc) c *** primary function: (post1) Load data for later ElResultGet c *** Notice - This file contains ANSYS Confidential information *** c (prolog is not confidential) c c c c c c c c c c input arguments: variable (typ,siz,intent) Label (ch*4,sc,in) Comp (ch*4,sc,in) LabAvg (ch*4,sc,in) output arguments: TypeData (int,sc,out) nVal (int,sc,out) Loc (int,sc,out)

description - Result Type - Result Component (8 char for ESTR) - 'AVG ' or 'NOAV' ('AVG ' default)

- Code for data type - Number of values per point If 0, no data - Location of Comp in values

1.10.4 Subroutine ElResultGet (Getting Results Values at Selected Points)

subroutine ElResultGet (nPoints,ebest,elcord,TypeData,Loc, nVal,result) c *** primary function: (post1) Get results at selected points x c *** Notice - This file contains ANSYS Confidential information *** c (prolog is not confidential) c c c c c c c c c c c c input arguments: variable (typ,siz,intent) description nPoints (int,sc,in) - Number of evaluation points *** from ElInterp *** ebest (int,ar(nPoints),in) - Element(s) containing points elcord (dp,ar(3,nPoints),in) - Element coordinates *** from ElResultStrt *** TypeData (int,sc,in) - Data type code Loc (int,sc,in) - Start of selected data nVal (int,sc,in) - Number of results per point output arguments: Result (dp,ar(nvar,nPoints),out)

- Array of results

1.10.5 Subroutine ElInterp (Finding Element Coordinates)

x subroutine ElInterp (nPoints,xyzPoints,tolInside,tolOutside, ebest,elcord)

c primary function: Find element numbers containing xyz points c secondary functions: Find element coordinates of these points c object/library: upf c *** Notice - This file contains ANSYS Confidential information *** c (Prolog is not CONFIDENTIAL INFORMATION) c typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout

c input arguments: c variable (typ,siz,intent) c nPoints (int,sc,in) c xyzPoints(dp,ar(3,nPoints),in)c tolInside(dp,sc,in) c c tolOutside(dp,sc,in) c c output arguments: c variable (typ,siz,intent) c ebest (int,ar(nPoints),out) c elcord (dp,ar(3,nPoints),out)

description Number of points to find (do in one group) XYZ coordinates of each point Tolerance for point inside element (0.0d0 defaults to 1.0d-4) Maximum distance outside to be associated with an element (0.0d0 defaults to 0.25) description - Best element number for each point - Element coordinates of the point

1.11 Access at the Beginning and End of Various Operations

You can access the logic just before an ANSYS run begins or just after a run ends, and at many other intermediate points, by using the ANSYS routines listed below. These routines can perform actions such as evaluating results or performing calculations. (None of the routines have input or output arguments.) Issue the USRCAL command (or use an equivalent menu path) to activate or deactivate these routines.

User Subroutine Is Called UAnBeg USolBeg ULdBeg USsBeg UltBeg UltFin USsFin ULdFin USolFin UAnFin At ANSYS start-up Before solution Before a load step Before a substep Before an iteration After an iteration After a substep After a load step After solution At the end of an ANSYS run

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. /COM, SAMPLE ussfin.mac a=5 b=nx(1) *get,c,active,solu,Time,cpu *dim,array,,6 array(1) = 1 array(2) = 2 array(3) = 3 array(4) = 4 array(5) = 5 array(6) = 6

! *get function is ok ! *get is ok ! array parameters are ok

*vleng,3 *vfun,array(4),copy,array(1) *stat *stat,array(1) array(1)= nnode = ndinqr(0,14) *dim,array,,nnode *vget,array(1),NODE,1,NSEL *stat,array(1) array(1)= /eof

! vector operations are ok

/COM, COMMANDS BELOW THIS LINE ARE KNOWN TO NOT WORK p,1,6,2000 d,1,uy,.1 *msg,note THIS IS A TEST MESSAGE *vwrite,array(1) (/ b = ,f10.4) ! commands DO NOT work

1.12 Creating Your Own Optimization Routine

One way to customize the ANSYS program for your site's specific needs is to substitute your own external optimization for the standard ANSYS optimization algorithm. You can do so using either of these methods:
G G

Link a user routine within the ANSYS program. Run a stand-alone optimization program using the ANSYS optimization "save" file, Jobname.OPT.

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.

1.12.1 Linking a Custom Optimization Program to ANSYS

If you're performing iterative analyses for design optimization, and you wish to use the standard ANSYS optimizer, you simply choose GUI path Main Menu>Design Opt or issue the ANSYS command /OPT. (You must do either from the Begin level.) 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.

1.12.2 Subroutine userop (Defining a Custom Optimization Routine)

Instead of creating your custom design optimization routine from scratch, you can simply tailor the userop routine available on your ANSYS distribution medium. Defined within this routine are a number of variables to which you assign the values you want. Below is a listing of the inputs and outputs for userop and the comments of common block cmopt: subroutine userop (iott,nterm) c primary purpose: user-supplied optimization routine c accessed with optype,user c other input comes from the opuser command c c *** ansys copyright 1971,78,82,83,85,87,89,92,94,95,96 c *** ansys, inc. c c******************************************************************************** c incoming arguments: * c * c * c Iott is the ansys output unit * c * c Nterm is passed back to routine opterm. You should set this variable * c as follows: * c nterm = 0 if optimization looping should stop * c nterm - 1 if optimization looping should continue * c * c******************************************************************************** c contents of optimization common block cmopt: c (only variables that are of interest or useful are documented) c c cmopt variable descriptions c --------------------------c c dopspr - (not used - spares) c dv(I) - design vector, I = 1 to maxdv

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c C c c c c

iopspr kconv kopusr

- (not used - spares) - convergence flag (kconv = 0 indicates convergence) - flag choosing optimizer (0 = ansys, 1 = user-supplied opt) (issuing the command optype,user sets kopusr = 1) lopt - incrementing lopt iteration counter maxdv - maximum number of design variables allowed in ansys optimization (= 60) maxpar - maximum number of parameters allows in ansys optimization (= 400) maxopt - maximum number of design sets allowed in optimization (= 130) nobj - flag for objective function defined (0=no, 1=yes) ntdv - total number of design variables ntsv - total number of state variables numopt - total number of design sets nsets - highest design set number setnum(1) - the actual design set number of the ith design set oplim(j,I) - Lower limit (j=1) and upper limit (j=2) of ith optimization parameter (opvar). (I = 1 to 160.) The state variables are stored first, then the design variables, and then the objective function optol(I) - tolerance of ith optimization parameter (opvar) (I = 1 to 160.) The state variables are stored first, then the design variables. optvar(I,j) - The ith parameter of the jth design set (I = 1 to maxpar, j = 1 to maxopt) The state variables are stored first, then the design variables, then the objective function, and finally all remaining scalar parameter values. maxusr - user-specified, maximum allowed optimization iterations on the opuser command opus(I) - user-specified, double precision parameters on the opuser command (I = 1,8) objtol - objective function tolerance

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.

1.12.3 Structuring Your Input

When your userop optimization routine finishes executing, program control returns to the ANSYS design optimizer, so that the ANSYS commands on Jobname.LOOP can execute for the next optimization loop. To use your own customization routine, you should issue the following ANSYS commands (in the order shown): /OPT OPTYPE,USER OPUSER, OPVAR . . . OPEXE

! ANSYS optimization logic bypassed ! user-defined optimization to be done ! design and state variables & objective function values defined

! looping begins

1.12.3.1 Example of User Input for Optimization

The commented example below shows you sample ANSYS command input for design optimization, done with a user-customized version of the userop routine:

c!!!---c!!! --c!!! --c!!! --c c c c c c c c c c c c c c c c c

minimize y = x1**2 + x2**2 subject to: 1 < x1 < 10 1 < x2 < 10 g = x1 - x2 > 1 ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! use batch mode initial value for dv x1 initial value for dv x2 enter the ANSYS preprocessor define function y define function g finish prep finish preprocessing define first dv (range 1 to 10) define second dv (range 1 to 10) define objective function (tol = 1) define state variable (lower limit 1) user user-defined optimization logic define user opt. Modifiers (max iterations=10) execute userop routine list results

/batch,list x1=5 x2=5 /prep7 y = x1*x1 + x2*x2 g = x1 - x2 finish /opt opvar,x1,dv,1,10 opvar,x2,dv,1,10 opvar,y,obj,,,1 opvar,g,sv,1 optype,user opuser,10,1.1,2.0 opexe oplist,all finish

1.12.4 Using a Stand-Alone Optimization Program

If you can't link a customized version of the userop optimization routine, you can call a stand-alone optimization program that you've created. To do so, issue the ANSYS command /SYS (it has no equivalent menu path). Your external optimization program then uses the ANSYS optimization save file, Jobname.OPT, to pass data to and from the ANSYS program. You should structure your input to ANSYS as shown below, and you must run the program in batch mode: /OPT OPTYPE,USER OPUSER, OPVAR . . . OPSAVE /SYS OPRESU OPEXE

! ANSYS optimization logic bypassed ! user-defined optimization to be done ! design and state variables & objective function values defined

! ! ! !

jobname.opt written for use by user-supplied program run the user-supplied program read results of user-supplied program from jobname.out 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.

1.12.5 What Does Jobname.OPT Contain?

The list below describes all of the relevant variables printed in Jobname.OPT. 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 actopt Active optimization method

andir anext annam bestsave bestset con1 con2 delfst delgr dvloop facexp facfst faclst factq fstfst fstpnt gradq(I) grdfst grdlst grdpnt grdtyp icongr ilamda inopt iobjxp

Analysis file directory Analysis file extension Analysis file name Key to save the best database and results file Number of the current best optimization set Minimum parameter value Maximum parameter value Forward difference for first order optimization (delta on opfrst) Forward difference for gradient optimization tool (delta on opgrad) Indicates how to treat design variables on the loop file Fractional exponent for factorial optimization First design set number in the range of factored sets Last design set number in the range of factored sets Factor applied to penalty functions (first order optimization only) First design set number in the range of first order sets Reference design set number for first order optimization Vector saved for first order optimization First design set number in the range of gradient sets Last design set number in the range of gradient sets Reference design set number for gradient evaluation Reference design set type (best, last, or number) for gradient Key for selecting conjugate direction method Exponent that controls the resolution (sharpness) of the unconstrained objective function (in first order optimization) Reserved for internal ANSYS use Reserved for internal ANSYS use

iopexe(I) Executable keys indicating which method or tool was run isvxp jobnam kconv kfit1 kfit2 kopusr kwght labx(k) loopct lpot looptl loptlp maxfac maxfst maxinf maxrnd maxsub mxpmrs nbest0 nfeas ninfes nmswps nobj noqv Reserved for internal ANSYS use Current name for file creation or use Convergence flag (kconv = 0 indicates convergence) Reserved for internal ANSYS use Reserved for internal ANSYS use Flag choosing optimizer (0 = ansys, 1 = user optimization) Reserved for internal ANSYS use Current parameter names Incrementing loop counter (for *GET command) Maximum number of design loops (from OPRUN command) Total number of optimization loops executed (using all methods) Saved value of lopt variable after each execution Maximum allowed number of loops for factorial optimization analysis Maximum allowed number of iterations for first order optimization Maximum allowed sequential infeasible solutions (subp) Maximum allowed number of iterations for random optimization Maximum allowed number of iterations for sub. prom. approx. Used for restart purposes (to reset mxparm in parmcm) Best design set this first order evaluation Desired number of feasible solutions (random optimization) Counter for consecutive infeasible solutions The number of sweep evaluations to be made in each design variable dir. Number of objective functions (must be 1) Reserved for internal ANSYS use

nrandm nsqv nsets ntdv ntfdf ntline ntmax ntsv numopt opam opdir opext opnam optlab optlab(I) optol(I)

Reserved for internal ANSYS use Reserved for internal ANSYS use Current number of sets that were made Total number of design variables Finite difference counter for first order optimization Line search counter for first order optimization Maximum number of parameters that have ever been defined Total number of state variables Total number of design sets Random settings (related to routine VRAND) Optimization file directory Optimization file extension Optimization file name All labels used in optimization (optimization labels and extras) Optimization labels Tolerance

optvar(I,j) Ith parameter of the jth design set opus(n) psobj0 rdfrom refobj User parameters specified on OPUSER command (n = 1:8) Best unconstrained objective value this first order evaluation Indicates where to begin reading the analysis file (0 = top, 1 = after /Prep7) Reference objective function for first order optimization

savoutunit Saved output unit number seed Reserved for internal ANSYS use

setnum(I) Set numbers sizeq Line search step size

sq(j)

Vector saved for first order optimization

stmapmax Reserved for internal ANSYS use svparm swpfst swplst swppnt swptyp userp(n) vect(k) Indicates which type of parameters to save during looping First design set number in the range of sweep sets Last design set number in the range of sweep sets Reference design set number for sweep evaluation Reference design set type (best, last, or number) for sweep Reserved for internal ANSYS use Current scalar parameter values

1.13 Data Handling Routines

ANSYS provides UPF routines you can use for memory management and parameter processing.

1.13.1 Using the Memory Management Routines

ANSYS 5.4 allocates all dynamic memory in a large data space area called the Heap. Previous ANSYS releases (before the Heap was implemented) used a data space called STACK to allocate dynamic memory. For this reason, you access the Heap space using variables names ISTACK, DSTACK, CSTACK, and RSTACK, which are included via the STACK include deck. 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. 2. Initialize the "handle" or "block number" to zero, as follows: iHandle = 0, for integers dHandle = 0, for double precision numbers cHandle = 0, for complex numbers rHandle = 0, for real numbers. 3. Allocate Heap space for an array or arrays, as follows: For integer numbers: prti =HeapAllocPtr(ileng,'C8Label ',HEAP_INTEGER,iHandle) For double precision numbers: ptrdp =HeapAllocPtr(dleng,'C8Label ',HEAP_DOUBLE, dHandle)

For complex numbers: ptrcp =HeapAllocPtr(cleng,'C8Label ',HEAP_COMPLEX,cHandle) For real numbers: ptrr =HeapAllocPtr(rleng,'C8Label ',HEAP_REAL ,rHandle)

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:
G G

G G

C8Label (argument 2) is a character*8 block name. HEAP_xxx (argument 3) is the word size based on integer words. (The HEAP_xxx definitions are parameters in the ansysdef.inc common). Handle (argument 4) is returned as the block number. The block number is used to deallocate the space. Ptr (the function result) is the starting location of the data space, minus 1. 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: If the Array Contains Integer numbers The First Data Entry Begins at istack(ptri+1)

Double precision numbers dstack(ptrdp+1) Complex numbers Real numbers cstack(ptrcp+1) rstack(ptrr+1)

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) This location is the same as the location described in Step 4. 6. Deallocate the stack space using the HeapDealloc subroutine, as follows: For integer numbers: call HeapDealloc(iHandle) For double precision numbers: call HeapDealloc(dHandle) For complex numbers: 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.

1.13.2 Function HeapAllocPtr (Allocating Heap Space and Returning a Pointer)

function HeapAllocPtr (nValues, c16Label, flagAlloc, hHeapHandle) c primary function: Get A Block of Space from Heap and Return Pointer c keywords: integer function for heap allocate heap

c object/library:

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c input arguments: nValues (int,sc,in) c16Label (ch*16,sc,in) flagAlloc(int,sc,in)

- Number of Values needed in Block - 16 character name for the Block - Flags describing this block (See ANSYSDEF and heapcom for more information)

output arguments: hHeapHandle (int,sc,out) HeapAllocPtr (int,sc,out)

- Handle (Block number) for this block - Pointer to this data block (Use Ptr+i) for reference to ith value in the block

1.13.3 Subroutine HeapDealloc (Deallocating Heap Space)

subroutine HeapDealloc (hHeapHandle) c primary function: Unlock and Free a Heap Data Block c keywords: subroutine to free heap data heap

c object/library:

c *** Notice - This file contains ANSYS Confidential information *** c c c c Note: See heapcom.inc for information on use of Heap

input arguments: hHeapHandle (int,sc,out) output arguments: none

- Handle (Block number) for this block

1.13.4 Function HeapGetPtr (Returns a Pointer for a Handle)

function HeapGetPtr (hHandle) c primary function: return pointer for an existing handle

c keywords: integer function for heap pointer return c object/library: c current - heap c *** Notice - This file contains ANSYS Confidential information ***

c c c c c c

NOTE:

See heapcom.inc for documentation on heap usage

input arguments: hHandle (int,sc,in) output arguments: HeapGetPtr (int,sc,out)

- A heap handle

- The corresponding pointer

1.14 Parameter Processing Routines

The ANSYS distribution medium contains three routines you can use for parameter processing: pardim, parevl, and pardef.

1.14.1 Subroutine pardim (Creating a Dimensioned Parameter)

subroutine pardim (label8,labl4,nxyz,names) c *** primary function: create a dimensioned parameter c *dim,parm8,type,d1,d2,d3,name1,name2,name3

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: label8 (chr*8,sc,in) labl4 (chr*4,sc,in) nxyz (int,ar(3),in) names (chr*8,ar(3),in) output arguments: none

the name of the parameter to create 'TABL' or 'ARRA' or 'CHAR' the dimensions of the array Names for x,y,z directions in table

1.14.2 Function parevl (Finding and Evaluating a Parameter)

function parevl (label8,nval,subc,lvl,kerr) c *** primary function: find and evaluate a parameter c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c input arguments: label8 (chr*8,sc,in) nval subc lvl (int,sc,in) (dp,ar(3),in) (int,sc,in)

- the name of the parameter (must be upper case, left justified) - the number of subscripts (0,scaler) - values for the subscripts (if any) - 0,1 no error output 2, report error -1, set kerr flag with no anserr call

output arguments: parevl (dp,sc,out) kerr (int,sc,out)

- the value of the parameter (may be a packed character*8 - error flag (0,ok -1,output is packed 0=ok, 1=error, 2=error but TINY is used

1.14.3 Subroutine pardef (Adding a Parameter)

subroutine pardef (label8,ctype,nval,subc,value,kerr) c *** primary function: add a parameter to parameter list c *** Notice - This file contains ANSYS Confidential information *** c c c c input arguments: label8 (chr*8,sc,in) - name of parameter label 8 is a character*8 variable that contains the name of the parameter that

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

is to be defined. ctype (int,sc,in) - 0, dp 1,character ctype is an integer key which describes the type of data that the parameter data holds. This would also indicate the contents of "value" (arg 5). 0=double precision data 1=character data - number of subscripts nval is the number of subscripts that the "label8" (arg 1) contains. 1=single dimensioned variable (ex. x(10)) 2=double dimensioned variable (ex. y(10,3)) 3=triple dimensioned variable (ex. z(10,3,2)) -1=delete this parameter from the internal tables. - values of subscripts subc is a double precision vector that contains the subscripts of "label8" (arg 1). There should be enough values defined to match "nval" (arg 3). For example if "x" was dimensioned as "x(10,3,2)" and you wanted to set "x(5,1,1)=123.0", then "nval" (arg 3) should be set to 3, and "subc" should be set to 5.0, 1.0, 1.0, and "value" (arg 5) should be 123.0. Another example is if "y" was dimensioned to as "y(20,20)" and you were setting "y(5,8)=987", then "nval" (arg 3) should be set to 2 and "subc" should be set to 5.0, 8.0, 0.0, and "value" (arg 5) should be 987.0. Remember subroutine "pardef" is only storing a data value of "label8" or "label8(x,y,z)". The proper dimensions were set by a "*dim" command. Please note that although the values of "subc" should be double precision, subroutine "pardef" uses the intrinsic "nint" (nearest integer) function to get and use the integer equivalent. You should also note the "nval" (arg 3) and "subc" (arg 4) must fall within the range that was set with a "*dim" or "*set" command or an error will occur. value (dp,sc,in) - the value for this parameter (should be a packed character*8 if ctype=1. To pack a char into a dp variable use "call chtodp(ch8,dp)". To unpack a dp variable into a char use "call dptoch(dp,ch8)" ) Value is the data value that is to be stored for "label8" (arg 1). If "ctype=1" (arg 2) then this value would be a "packed character" data from the "chtodp" Ansys function.

nval

(int,sc,in)i

subc (dp,ar(3),in)

output arguments: kerr (int,sc,out)

- error flag (0=ok, 1=error) kerr is an integer error flag that is returned to the calling subroutine. Any

c c

non zero number would indicate an error 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.

1.15 Miscellaneous Useful Functions

The ANSYS program has several miscellaneous functions you may find useful for working with UPFs:
G G G G G G

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.

1.15.1 Using Function runcmd

This function enables you to execute an ANSYS command from within a user routine. Inputs and outputs for runcmd are as follows: function runcmd (command) c primary function: c object/library: upf c *** Notice - This file contains ANSYS Confidential information *** c c c c c input arguments: command (ch*128,sc,in) Execute an ansys command from a user routine

- A character string containing a valid ANSYS command, up to 128 char

output arguments: none runcmd (int,sc,out)

- An internally defined value, ignore

1.15.2 Using the /UNDO Command

The "undo" file you create by issuing the /UNDO command is similar to the File.DB file created when you issue the SAVE command. The /UNDO command format is: Action is one of the following:
G G G G

ON, to write the undo file OFF, to prevent the undo file from being written PROMPT, to have ANSYS ask permission before writing the file STATUS, to restore the file as it existed after executing the last command issued before the /UNDO command.

1.15.3 Using the /HOLD command

Issue the /HOLD command to synchronize tasks in ANSYS. The ANSYS program can synchronize tasks at the end of each results file set. The command format is:

G G

Filename is the eight-character name of a message file. If the named file exists, the ANSYS program reads a command from the file and then deletes the file. TimeInterval is the length of time, in seconds, that ANSYS waits before trying to read the message file again. Timeout is the maximum length of time, in seconds, that ANSYS can wait between attempts to read the file.

Go to the beginning of this chapter

Chapter 2: Accessing the ANSYS Database

Go to the Next Chapter Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Appendix A

2.1 What This Chapter Covers

This chapter describes how you can retrieve information in the ANSYS database (or store information in the database) by linking subroutines you create into the ANSYS program. 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).

2.2 Inputs and Outputs for Database Access Routines

The descriptions of the database access routines or functions within this chapter describe both the input arguments and output arguments. Argument information includes the argument's type, size and intent.
G

Argument type is one of the following: int - integer dp - double precision log - logical chr - character dcp - double precision complex

Argument size is one of the following: sc - scalar variable ar(n) - array variable of length n func - functional return value

Argument intent is one of the following: in - input argument out - output argument

inout - both an input and an output argument

2.3 Types of Database Access Routines

The rest of this chapter describes the functions and subroutines available for accessing information in the ANSYS database. The function and subroutine descriptions are grouped into sets: nodal information functions, element attribute information functions, etc.

2.4 Routines for Selecting and Retrieving Nodes and Elements

2.4.1 ndnext Function (Getting the Next Node Number)
function ndnext (next) c *** primary function: get the number of the next selected node 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 next (int,sc,in) - the last node number used c = 0 - use for initial value c c output arguments: c ndnext (int,func,out) - the next selected node number c = 0 - no more nodes c

2.4.2 ndprev Function (Getting the Number of the Previous Selected Node)
function ndprev (next) c *** primary function: get the number of the previous selected node 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 next (int,sc,in) - the next node number used c = 0 - use for initial value c c output arguments: c ndprev (int,func,out) - the previous selected node number c = 0 - no more nodes c

2.4.3 ndnxdf Function (Getting the Number of the Next Defined Node)
function ndnxdf (next) c *** primary function: get the number of the next defined node 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 next (int,sc,in) - the last node number used c = 0 - use for initial value c c output arguments: c ndnxdf (int,func,out) - the next defined node number c = 0 - no more nodes c

2.4.4 ndsel Function (Selecting, Unselecting, Deleting, or Inverting a Node)

subroutine ndsel (ndmi,ksel) c *** primary function: to select, unselect, delete, or invert a node. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ndmi (int,sc,in) - node number c = 0 - all nodes c < 0 - do not delete CPs and CEQNs c (merge/offset/compress) c ksel (int,sc,in) - type of operation to be performed. c ksel = 0 - delete node. c = 1 - select node. c =-1 - unselect node. c = 2 - invert select status of node. c c output arguments: c none. c

2.4.5 elnext Function (Getting the Number of the Next Element)

function elnext (next) c *** primary function: get the number of the next selected element

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 next (int,sc,in) - the last element number used c = 0 - use for initial value c c output arguments: c elnext (int,func,out) - the next selected element c = 0 - no more elements

2.4.6 elprev Function (Getting the Number of the Previous Selected Element)
function elprev (prev) c *** primary function: get the number of the previous selected element 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 prev (int,sc,in) - the last element used c = 0 - use for initial value c c output arguments: c elprev (int,func,out) - the previous selected element c = 0 - no more elements c

2.4.7 elnxdf Function (Getting the Number of the Next Defined Element)
function elnxdf (next) c *** primary function: get the number of the next defined element 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 next (int,sc,in) - the last element used c = 0 - use for initial value c c output arguments: c elnxdf (int,func,out) - the next defined element c = 0 - no more elements c

2.4.8 elsel Subroutine (Selecting, Unselecting, Deleting, or Inverting an Element)

subroutine elsel (ielei,ksel) c *** primary function: to select, unselect, delete, or invert an element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielei (int,sc,in) - element number c = 0 - all elements c ksel (int,sc,in) - type of operation to be performed. c = 0 - delete element. c = 1 - select element. c =-1 - unselect element. c = 2 - invert select status for element c c output arguments: c none. c

2.5 Node Information Routines

2.5.1 ndinqr Function (Getting Information About a Node)
The primary function of ndinqr is getting information about a node. You can also use this function to set the current node pointer to this node. function ndinqr (node,key) c *** primary function: get information about a node. c *** secondary functions: set current node pointer to this node. 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 node (int,sc,in) - node number c Should be 0 for key=11, DB_NUMDEFINED, c DB_NUMSELECTED, DB_MAXDEFINED, and c DB_MAXRECLENG c key (dp,sc,in) - key as to information needed about c the node. c = DB_SELECTED - return select status: c ndinqr = 0 - node is undefined. c =-1 - node is unselected. c = 1 - node is selected. c = DB_NUMDEFINED - return number of defined nodes c = DB_NUMSELECTED - return number of selected nodes

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

= DB_MAXDEFINED - return highest node number defined = DB_MAXRECLENG - return maximum record length (dp words) = 2, return length (dp words) = 3, = 11, return void percent (integer) = -1, = -2, superelement flag = -3, master dof bit pattern = -4, active dof bit pattern = -5, solid model attachment = -6, pack nodal line parametric value = -7, constraint bit pattern = -8, force bit pattern = -9, body force bit pattern = -10,internal node flag = -11, = -12, =-101, pointer to node data record =-102, pointer to angle record =-103, pointer to attached elements =-104, pointer to attached couplings =-105, pointer to attacted constraint equations =-106, pointer to nodal stresses =-107, pointer to specified disp'S =-108, pointer to specified forces =-109, pointer to x/y/z record =-110, =-111, =-112, pointer to nodal temperatures =-113, pointer to nodal heat generations =-114, =-115, pointer to calculated displacements =-116, output arguments: ndinqr (int,func,out)

- the returned value of ndinqr is based on setting of key.

2.5.2 getnod Function (Getting a Nodal Point)

subroutine getnod (node,v,kerr,kcrot) c *** primary function: get a nodal point 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c node (int,sc,in) - node number c kerr (int,sc,inout) - message flag c = 0 - print no message if node is unselected c or undefined c = 1 - print message if node is undefined c = 2 - print message if node is undefined c or unselected

c c c c c c c c c c c c

kcrot

(int,sc,in)

- output coordinates in this coordinate system. if kcrot is negative, output theta and phi coordinates in radians

output arguments: v (dp,ar(6),out) kerr (int,sc,inout)

- Coordinates (first 3 values) and rotation angles (last 3 values) - select status = 0 - node is selected = 1 - node is not defined =-1 - node is unselected

2.5.3 putnod Function (Storing a Node)

subroutine putnod (node,vctn,kcrot) c *** primary function: store a node c *** secondary functions: display node if in immediate mode. c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) node (int,sc,in) vctn (dp,ar(6),in) kcrot (int,sc,in) siz=sc,ar(n),func intent=in,out,inout

description - node number - array of 3 nodal 3 nodal - local coordinate coordinates and

coordinates and rotation angles. system in which the nodal angles are defined

output arguments: none.

2.5.4 ndgall Function (Getting the XYZ/Rotation Coordinates Vector for a Node)
function ndgall (node,xyz) c *** primary function: get x,y,z,rotx,roty,rotz vector for a node. c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c node (int,sc,in) - node number for operation. c c output arguments: c ndgall (int,sc,out) - status of node. c 0=node is undefined. c -1=node is unselected. c 1=node is selected. c xyz (dp,ar(6),out) - vector containing x,y,z,rotx,roty,rotz c

2.5.5 ndspgt Subroutine (Getting the Nodal Solution for a

Node of an Element)
subroutine ndspgt (node,dofs,ndof,nrot,xyzang,nuvect,unode) c *** primary function: get the nodal solution for a node of an element c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c node (int,sc,in) - The node number c dofs (int,sc,in) - The dofs to retrieve for the node. c dof = degree of freedom c This is an integer representation using c bit pattern logic of the dof or the dof c set. This is normally done using the c parameters defined in echprm. Then c you could use dofs = UX + UY in the c calling routine, for example. c ndof (int,sc,in) - The number of node dofs (1, 2 or 3). c nrot (int,sc,in) - Key to rotate dofs from nodal to global c coordinate systems. c if 0, none. if 2, 2-d. if 3, 3-d c if > 0, dof set must include and only c include all terms of the vector (e.g. c UX,UY,UZ, or AX,AY,AZ). c xyzang (dp,ar(6),in) - The xyz virgin node coordinates c (including angles). Not used if c nrot = 0 or ndof < 2. c nuvect (int,sc,in) - Number of vectors to retrieve. Can vary c between 1 and 5. Normally 1 is what is c wanted. Other vectors include previous c values and/or velocities. See elucom for c all possibilites. Contents are analysis c type dependent. c c output arguments: c unode (dp,ar(ndof,nuvect),out) - Element nodal solution vectors in c the global coordinate system. c

2.6 Element Attribute Routines

2.6.1 elmiqr Function (Getting Information About an Element)
function elmiqr (ielem,key) c *** primary function: get information about an element. c *** secondary functions: set current element pointer to this element. 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 ielem (int,sc,in) - element number c should be zero for key=11, DB_NUMDEFINED,

c DB_NUMSELECTED, or DB_MAXDEFINED c key (int,sc,in) - information flag. c = DB_SELECTED - return select status: c elmiqr = 0 - element is undefined. c =-1 - element is unselected. c = 1 - element is selected. c = DB_NUMDEFINED - return number of defined elements c = DB_NUMSELECTED - return number of selected elements c = DB_MAXDEFINED - return maximum element number used c = DB_MAXRECLENG - return maximum record length c (int words) c = 2 - return length (int words) c = 3 - return layer number c (for cross reference files return number of entities) c = 4 - return address of first data word c = 5 - return length (in record type units) c = 6 - return compressed record number. c = 11 - return void percent (integer) c = 16 - return location of next record c (this increments the next record count) c = 18 - return type of file. c elmiqr = 0 - integer c = 1 - double precision c = 2 - real c = 3 - complex c = 4 - character*8 c = 7 - index c = 19 - return virtual type of file. c elmiqr = 0 - fixed length (4.4 form) c = 1 - indexed variable length (layer data) c = 2 - xref data tables c = 3 - bitmap data (for 32 data item packed records) c = 4 - data tables (three dimensional arrays) c = -1 - material number etc. (see elmcmx) c =-101 - pointer to element integers etc. (see elmcmx) c c output arguments: c elmiqr (int,func,out) - the returned value of elmiqr is based on c setting of key. c #include "impcom.inc" c external vminqr,virtrd integer vminqr c integer elmiqr, ielem, key, j, iloc(2) c

2.6.2 elmget Function (Getting an Element's Attributes and Nodes)

function elmget (ielem,elmdat,nodes) c *** primary function: get element attributes and nodes. c c *** Notice - This file contains ANSYS Confidential information *** c

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) ielem (int,sc,in)

siz=sc,ar(n),func

intent=in,out,inout

description - element number

output arguments: elmget (int,func,out)

elmdat

- status of element. = 0 - element undefined < 0 - number of nodes on unselected element > 0 - number of nodes on selected element (int,ar(10),out) - element attributes. elmdat(1) - material number (2) - element type (3) - real constant number (4) - element number (obsolete, do not use) (5) - coordinate system number (6) - death flag if 0 - alive if 1 - dead (7) - solid model reference (8) - 100*shape + specific shape (9) - reserved (10) - p element include flag if 0 - include if 1 - exclude (int,ar(*),out) - node numbers for element.

nodes

2.6.3 elmput Subroutine (Storing an Element)

subroutine elmput (ielem,elmdat,nnod,nodes) c *** primary function: store element attributes and node numbers. c *** secondary functions: set current element pointer to this element. 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 ielem (int,sc,in) - element number c elmdat (int,ar(10),in) - element attributes. c elmdat(1) - material number c (2) - element type c (3) - real constant number c (4) - element number (obsolete, do not use) c (5) - coordinate system number c (6) - death flag c if 0 - alive c if 1 - dead c (7) - solid model reference c (8) - 100*shape + specific shape c (9) - reserved c (10) - p element include flag

c c c c c c c c

nnod nodes

(int,sc,in) (int,ar(*),in)

if 0 - include if 1 - exclude - number of nodes for this element. - node numbers for this element.

output arguments: none.

2.6.4 etyiqr Function (Getting a Data Item About an Element Type)

function etyiqr (itype,key) c *** primary function: get information about an element type. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c itype (int,sc,in) - element type number c Should be 0 for key=11, DB_NUMDEFINED, c DB_NUMSELECTED, DB_MAXDEFINED, and c DB_MAXRECLENG c key (int,sc,in) - information flag. c = DB_SELECTED - return select status: c etyiqr = 0 - element type is undefined. c =-1 - element type is unselected. c = 1 - element type is selected. c = DB_NUMDEFINED - return number of defined element types c = DB_NUMSELECTED - return number of selected element types c = DB_MAXDEFINED - return highest element type number defined c = DB_MAXRECLENG - return maximum record length (int words) c = 2 - return length (int words) c = 3 - return layer number c (for cross reference files return c number of entities) c = 4 - return address of first integer word c = 5 - return length (int words) c = 6 - return compressed record number. c = 11 - return void percent (integer) c = 16 - return location of next record c (this increments the next record count) c = 18 - return type of file. c etyiqr = 0 - integer c = 1 - double precision c = 2 - real c = 3 - complex c = 4 - character*8 c = 7 - index c = 19 - return virtual type of file. c etyiqr = 0 - fixed length (4.4 form) c = 1 - indexed variable length c (layer data)

c c c c c c c c c c c c c c c

= 2 - xref data tables = 3 - bitmap data (for 32 data item packed records) = 4 - data tables (three dimensional arrays) = -n, return element characteristic n from etycom for element type itype. n is correlated to the parameter names in echprm. see elccmt for definitions of element characteristics. note- this will not overwrite the current setting of etycom. output arguments: etyiqr (int,func,out)

- the returned value of etyiqr is based on setting of key.

2.6.5 etyget Function (Getting Information About an Element Type)

function etyget (itype,ielx) c *** primary function: get element type data. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c itype (int,sc,in) - element type number c c output arguments: c etyget (int,func,out) - status of element type. c = 0 - element type is undefined. c < 0 - number of data items on unselected c element type. c > 0 - number of data items on selected c element type. c ielx (int,ar(*),out) - element type data. see elccmt for c description of data. c

2.6.6 etyput Subroutine (Storing Element Type Data)

subroutine etyput (itype,n,ielx) c *** primary function: store element type data. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description

c c c c c c c c

itype n ielx

(int,sc,in) (int,sc,in) (int,ar(*),in)

- element type number for operation. - length of data vector to store. - element type data. see elccmt for description.

output arguments: none.

2.6.7 echrtr Subroutine (Getting Information About Element Characteristics)

c c subroutine echrtr (iott,elcdn,ielc,kerr) primary function: collect all element characteristics based on ityp,jtyp, and keyopts

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 iott (int,sc,in) - printout file c ielc (int,ar(150),inout) - input element characteristics c in positions 1 to 20. c (itype, jstif, keyopts, etc.) c c output arguments: c elcdn (chr,sc,out) - element descriptive name as character c string c ielc (int,ar(150),inout) - output element characteristics c in positions 21 to 150. c (kdim, ishap, idegen, etc.) c see elccmt for a full list c kerr (int,sc,out) - error flag c = 0 - no errors c = 1 - errors c

2.6.8 etysel Subroutine (Selecting, Unselecting, Deleting, or Inverting an Element Type)

subroutine etysel (itypi,ksel) c *** primary function: to select, unselect, delete, or invert an c element type. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c itypi (int,sc,in) - element type number

c c c c c c c c c c

ksel

(int,sc,in)

= 0 - all element types - type of operation to be performed. = 0 - delete element type. = 1 - select element type. =-1 - unselect element type. = 2 - invert element type.

output arguments: none.

2.6.9 mpinqr Function (Getting Information About a Material Property)

function mpinqr (mat,iprop,key) c *** primary function: get information about a material property. 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 mat (int,sc,in) - material number c should be 0 for key=11, DB_NUMDEFINED, c DB_MAXDEFINED, and DB_MAXRECLENG c c iprop (int,sc,in) - property reference number: c if iprop = 0, test for existence of any material property with this c material number (with key = DB_SELECTED) 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 ORTH=54, CABL=55, RIGI=56 c HGLS=57, BM =58, QRAT=59, REFT=60, PLAS=61, CREE=62, FAIL=63, BH =64 c PIEZ=65, SWEL=66, WATE=67, CONC=68, PFLO=69, ANEL=70, ACOU=71, EVIS=72 c USER=73, NL =74, HYPE=75, NNEW=76, MOON=77, OGDE=78, SUTH=79, WIND=80 c (see mpinit for uncommented code) c c key (int,sc,in) - key as to the information needed c about material property. c = DB_SELECTED - return select status: c mpinqr = 0 - material prop is undefined. c = 1 - material prop is selected. c = DB_NUMDEFINED - return number of defined material properties c = DB_MAXDEFINED - return highest material property number defined c = DB_MAXRECLENG - return maximum record length (dp words) c = 2 - return length (dp words) c = 3 - return number of temp. values c = 11 - return void percent (integer) c c output arguments: c mpinqr (int,func,out) - returned value of mpinqr is based on

c c

setting of key.

2.6.10 mpget Function (Getting a Material Property Table)

function mpget (mat,iprop,temp,prop) c *** primary function: get a material property table. 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 mat (int,sc,in) - material number c iprop (int,sc,in) - property reference number: 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 ORTH=54, CABL=55, RIGI=56 c HGLS=57, BM =58, QRAT=59, REFT=60, PLAS=61, CREE=62, FAIL=63, BH =64 c PIEZ=65, SWEL=66, WATE=67, CONC=68, PFLO=69, ANEL=70, ACOU=71, EVIS=72 c USER=73, NL =74, HYPE=75, NNEW=76, MOON=77, OGDE=78, SUTH=79, WIND=80 c (see mpinit for uncommented code) c c output arguments: c mpget (int,func,out) - number of temperature values c temp (dp,ar(mpget),out) - vector of the temperature values c prop (dp,ar(mpget),out) - vector of the property values c

2.6.11 mpput Subroutine (Storing a Material Property Table)

subroutine mpput (mat,iprop,ntab,temp,prop) c *** primary function: store material property tables. 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 mat (int,sc,in) - material number. c iprop (int,sc,in) - property reference number: c EX = 1, EY = 2, EZ = 3, NUXY= 4, NUYZ= 5, NUXZ= 6, GXY = 7, c GXZ = 9, ALPX=10, ALPY=11, ALPZ=12, DENS=13, MU =14, DAMP=15, c KYY =17, KZZ =18, RSVX=19, RSVY=20, RSVZ=21, C =22, HF =23, c EMIS=25, ENTH=26, LSST=27, PRXY=28, PRYZ=29, PRXZ=30, MURX=31, c MURZ=33, PERX=34, PERY=35, PERZ=36, MGXX=37, MGYY=38, MGZZ=39, c EGYY=41, EGZZ=42, TGXX=43, TGYY=44, TGZZ=45, SONC=46, c ORTH=54, CABL=55, c HGLS=57, BM =58, QRAT=59, REFT=60, PLAS=61, CREE=62, FAIL=63, c PIEZ=65, SWEL=66, WATE=67, CONC=68, PFLO=69, ANEL=70, ACOU=71,

GYZ = 8 KXX =16 VISC=24 MURY=32 EGXX=40 RIGI=56 BH =64 EVIS=72

c c c c c c c c c c c

USER=73, NL

=74, HYPE=75, NNEW=76, MOON=77, OGDE=78, SUTH=79, WIND=80 (see mpinit for uncommented code) - number of entries in the table (1 to 100) - temperature vector (ascending) - property vector

ntab tem prp

(int,sc,in) (dp,ar(ntab),in) (dp,ar(ntab),in)

output arguments: none.

2.6.12 mpdel Subroutine (Deleting a Material Property Table)

subroutine mpdel (mat,iprop) c *** primary function: delete material property tables. 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 mat (int,sc,in) - material number. c iprop (int,sc,in) - property reference number: c (0 = all properties) 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 ORTH=54, CABL=55, RIGI=56 c HGLS=57, BM =58, QRAT=59, REFT=60, PLAS=61, CREE=62, FAIL=63, BH =64 c PIEZ=65, SWEL=66, WATE=67, CONC=68, PFLO=69, ANEL=70, ACOU=71, EVIS=72 c USER=73, NL =74, HYPE=75, NNEW=76, MOON=77, OGDE=78, SUTH=79, WIND=80 c (see mpinit for uncommented code) c c output arguments: c none. c

2.6.13 rlinqr Function (Getting Information About a Real Constant Set)

function rlinqr (nreal,key) c *** primary function: get information about a real constant set 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

nreal

(int,sc,in)

key

- real constant table number should be 0 for key=11, DB_NUMDEFINED, DB_NUMSELECTED, DB_MAXDEFINED, and DB_MAXRECLENG (int,sc,in) - information flag. = DB_SELECTED - return select status rlinqr = 0 - real constant table is undefined. =-1 - real constant table is unselected. = 1 - real constant table is selected = DB_NUMDEFINED - return number of defined real constant tables = DB_NUMSELECTED - return number of selected real constant tables = DB_MAXDEFINED - return highest real constant table defined = DB_MAXRECLENG - return maximum record length (dp words) = 2 - return length (dp words) = 3 - return layer number (for cross reference files return number of entities) = 4 - return address of first data word = 5 - return length (in record type units) = 6 - return compressed record number. = 11 - return void percent (integer) = 16 - return location of next record (this increments the next record count) = 18 - return rlinqr = = = = = = = 19 - return rlinqr = = = = = type of file. 0 - integer 1 - double precision 2 - real 3 - complex 4 - character*8 7 - index virtual type of file. 0 - fixed length (4.4 form) 1 - indexed variable length (layer data) 2 - xref data tables 3 - bitmap data (for 32 data item packed records) 4 - data tables (three dimensional arrays)

output arguments: rlinqr (int,func,out)

- the returned value of rlinqr is based on

2.6.14 rlget Function (Getting Real Constant Data)

function rlget (nreal,rtable) c *** primary function: get real constant data 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c nreal (int,sc,in) - real constant table number c c output arguments: c rlget (int,func,out) - number of real constant data obtained

c c

rtable

(dp,ar(*),out)

- real constant data obtained

2.6.15 rlsel Subroutine (Selecting or Deleting a Real Constant Set)

subroutine rlsel (nreai,ksel) c *** primary function: select or delete a real constant set 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c nreai (int,sc,in) - real constant table c = 0 - all real constant tables c ksel (int,sc,in) - type of operation to be performed. c = 0 - delete real constant table. c = 1 - select real constant table. c =-1 - unselect real constant table. c = 2 - invert real constant table. c c output arguments: c none c

2.6.16 csyiqr Function (Getting Information About a Coordinate System)

function csyiqr (ncsy,key) c *** primary function: get information about a coordinate system 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ncsy (int,sc,in) - coordinate system reference number c should be zero for key= DB_NUMDEFINED c or DB_MAXDEFINED c key (int,sc,in) - information flag. c = DB_SELECTED - return status: c csyiqr = 0 - coordinate system is not defined c -1 - coordinate system is not selected c 1 - coordinate system is selected c = DB_NUMDEFINED - number of defined coordinate systems c = DB_MAXDEFINED - maximum coordinate system reference c number used. c c output arguments:

c c c

csyiqr

(int,func,out)

- the returned value of csyiqr is based on setting of key.

2.6.17 csyget Function (Getting a Coordinate System)

function csyget (ncsy,csydpx,csyinx) c *** primary function: get a coordinate system c *** secondary functions: none c c *** Notice - This file contains ANSYS Confidential information *** c c NOTE: As a time-saving device, this routine will not fetch the coordinate c system data from the database (an expensive operation) c if ncsy = csyinx(4), as this would indicate that the data is current. c If you wish to force this routine to fetch coordinate system data (in c the case of loading a local array, for example), you MUST set c ncsy != csyinx(4) before function call. 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 csycom name c ncsy (int,sc,in) - coordinate system number c csyinx(4) (int,sc,inout) - coordinate system number csyact c c output arguments: c csydpx (dp,ar(18),out) c csydpx(1-9) - transformation matrix c (10-12) - origin (XC, YC, ZC) c (13-14) - coordinate system parameters cparm c cparm2 c (15) - spare c (16-18) - defining angles c csyinx (int,ar(6),out) c csyinx(1-2) - theta, phi singularity keys c (3) - coordinate system type icdsys c (csyinx(4) is inout) (4) - coordinate system number csyact c (5) - spare c (6) - spare c csyget (int,func,out) - status of coordinate system c = 0 - coordinate system exists c = 1 - coordinate system doesn't exist c

2.6.18 csyput Subroutine (Storing a Coordinate System)

subroutine csyput (ncsy,csydpx,csyitx) c *** primary function: store a coordinate system 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),func intent=in,out,inout c c input arguments:

c c c c c c c c c c c c c c c c c c c c

variable (typ,siz,intent) description csycom name ncsy (int,sc,in) - coordinate system number csydpx (dp,ar(18),out) csydpx(1-9) - transformation matrix (10-12) - origin (XC, YC, ZC) (13-14) - coordinate system parameters cparm cparm2 (15) - spare (16-18) - defining angles csyinx (int,ar(6),out) csyinx(1-2) - theta, phi singularity keys (3) - coordinate system type icdsys (4) - coordinate system number csyact (5) - spare (6) - spare

output arguments: none

2.6.19 csydel Subroutine (Deleting a Coordinate System)

subroutine csydel (ncsy) c *** primary function: delete a coordinate system c *** secondary functions: none c c typ=int,dp,log,chr,dcp siz=sc,ar(n),func intent=in,out,inout c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c ncsy (int,sc,in) - coordinate system number c c output arguments: c none c

2.6.20 userac Subroutine (Demonstrates Use of Element Attribute Routines)

See Chapter 4 for an example that demonstrates how to use the userac subroutine to extract information about an element type and element real constants from the ANSYS database. You can find this subroutine on your ANSYS distribution medium.

2.7 Coupling and Constraint Routines

2.7.1 cpinqr Function (Getting Information About a Coupled Set)
function cpinqr (nce,key) c *** primary function: get information about a coupled set

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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c nce (int,sc,in) - coupled set number c key (int,sc,in) - inquiry key: c should be zero for key=11, DB_NUMDEFINED, c DB_NUMSELECTED, DB_MAXDEFINED, and c DB_MAXRECLENG c = DB_SELECTED - return select status c cpinqr = 1 - coupled set is selected c = 0 - coupled set in undefined c =-1 - coupled set in unseleted c = DB_NUMDEFINED - return number of defined coupled sets c = DB_NUMSELECTED - return number of selected coupled sets c = DB_MAXDEFINED - return the number of the highest numbered c coupled set c = DB_MAXRECLENG - return length of largest coupled set record c (max record length) c = 2 - return length (data units) c = 3 - return layer number c = 4 - return address of first data word c = 11 - return void percent (integer) c = 16 - return location of next record c c output arguments: c cpinqr (int,func,out) - the returned value of cpinqr is based on c setting of key c

2.7.2 cpget Function (Getting a Coupled Set)

function cpget (ncp,ieqn) c *** primary function: get a coupled set 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ncp (int,sc,in) - coupled set number c c output arguments: c cpget (int,func,out) - number of nodes in list c ieqn (int,ar(cpget+2),out) - coupled set info: c ieqn(1:cpget) - list of coupled nodes c ieqn(cpget+1) - set degree of freedom c ieqn(cpget+2) - number of nodes in list c (copy of return value) c

2.7.3 cpput Subroutine (Storing a Coupled Set)

subroutine cpput (ncp,n,ieqn) c *** primary function: store a coupling set 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ncp (int,sc,in) - coupled set number c n (int,sc,in) - number of nodes in coupled set c ieqn (int,ar(n+2),in) - info for storage c ieqn(1:n) - list of coupled nodes c ieqn(n+1) - degree of freedom label for set c (ieqn(n+2) is inout) ieqn(n+2) - number of nodes in coupled set c (copy of n) c c output arguments: c ieqn(n+2) (int,sc,inout) - number of nodes in coupled set c (another copy of n) c

2.7.4 cpsel Subroutine (Selecting or Deleting a Coupled Set)

subroutine cpsel (ncpi,ksel) c *** primary function: select or delete a coupled set 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ncpi (int,sc,in) - coupled set number c ksel (int,sc,in) - select/delete flag c = 0 - delete coupled set c = 1 - select coupled set c output arguments: c none c

2.7.5 ceinqr Function (Getting Information About a Constraint Equation Set)

function ceinqr (nce,key) c *** primary function: get information about a constraint equation set 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 c c c c c c c c c c c c c c c c c c c c c c c c c c c

input arguments: variable (typ,siz,intent) nce (int,sc,in) key (int,sc,in)

= DB_SELECTED

= DB_NUMDEFINED = DB_NUMSELECTED = DB_MAXDEFINED = DB_MAXRECLENG = 2 = 3 = 4 = 11 = 16 = -1 -

description - constraint equation number - inquiry key: should be zero for key=11, DB_NUMDEFINED, DB_NUMSELECTED, DB_MAXDEFINED, and DB_MAXRECLENG return select status ceinqr = 1 - equation is selected = 0 - equation is undefined =-1 - equation is unselected return number of defined contraint equations return number of selected contraint equations return number of highest numbered constraint equation defined return length of longest contraint equation set (max record length) return length (data units) return layer number address of first data word return void percent (integer) return location of next record return master dof for this eqn

output arguments: ceinqr (int,func,out)

- the returned value of ceinqr is based on setting of key

2.7.6 ceget Function (Getting an Constraint Equation)

function ceget (nce,ieqn,deqn) c *** primary function: get a constraint equation 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 nce (int,sc,in) - constraint equation number c c c c c c c c c output arguments: ceget (int,func,out) - number of dof in equation ieqn (int,ar(ceget+1),out) - integer info ieqn(1:ceget) - list of node*32+dof ieqn(ceget+1) - number of dof in equation (copy of return value) deqn (dp,ar(ceget+1),out) - dp info deqn(1:ceget) - list of coefficients deqn(ceget+1) - constant term

2.7.7 ceput Subroutine (Storing a Constraint Equation)

subroutine ceput (nce,n,ieqn,deqn) c *** primary function: store a constraint equation c *** secondary functions: none c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c input arguments: nce (int,sc,in) - constraint equation set number n (int,sc,in) - number of degrees of freedom in set ieqn (int,ar(n+1),in) - integer info ieqn(1:n) - node*32+dof for each dof in set ieqn(n+1) - number of dof in set (copy of n above) deqn (dp,ar(n+1),in) - dp info deqn(1:n) - coefficients of each dof in set deqn(n+1) - constant term output arguments: none

2.7.8 cesel Subroutine (Deleting or Selecting a Constraint Equation)

subroutine cesel (ncei,ksel) c *** primary function: select or delete a constraint equation 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ncei (int,sc,in) - constraint equation number c ksel (int,sc,in) - select/delete flag c = 0 - delete equation c = 1 - select equation c c output arguments: c none c

2.8 Nodal Loading Routines

2.8.1 disiqr Function (Getting a Information About Constraints)
function disiqr (node,key) c *** primary function: get information about constraints 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 c c c c c c c c c c c

variable (typ,siz,intent) description node (int,sc,in) - node number for inquire. key (int,sc,in) - key as to the information needed = 1 - return constraint mask = DB_MAXDEFINED, DB_NUMDEFINED - return number of nodal constraints NOTE: both DB_MAXDEFINED and DB_NUMDEFINED produce the same functionality output arguments: disiqr (int,func,out)

- the returned value of disiqr is based on

2.8.2 disget Function (Getting a Constraint from the Database)

function disget (inode,idf,value) c *** primary function: get a constraint from the data base 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c inode (int,sc,in) - node number (negative value for no c partabeval) c idf (int,sc,in) - reference number for the DOF: (1-32) c UX = 1, UY = 2, UZ = 3, ROTX= 4, ROTY= 5, ROTZ= 6, AX = 7, AY = 8 c AZ = 9, VX =10, VY =11, VZ =12 c PRES=19, TEMP=20, VOLT=21, MAG =22, ENKE=23, ENDS=24 c EMF =25, CURR=26 SP01=27, SP02=28, SP03=29, SP04=30, SP05=31, SP06=32 c (missing entries are spares) c c output arguments: c disget (int,func,out) - status of constraint. c = 0 - no constraint on this node c for this DOF c = 4 - this node has a constraint c defined for this DOF c value (dp,ar(4),out) - constraint values c value(1-2) - (real,imag) values of present settings c

2.8.3 disput Subroutine (Storing a Constraint at a Node)

subroutine disput (node,idf,value) c *** primary function: store a constraint at a node. 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),func intent=in,out,inout c c input arguments:

c c c c c c c c c c c c c

variable (typ,siz,intent) description node (int,sc,in) - node number idf (int,sc,in) - reference number of DOF: (1-32) UX = 1, UY = 2, UZ = 3, ROTX= 4, ROTY= 5, ROTZ= 6, AX = 7, AY = 8 AZ = 9, VX =10, VY =11, VZ =12 PRES=19, TEMP=20, VOLT=21, MAG =22, ENKE=23, ENDS=24 EMF =25, CURR=26 (missing entries are spares) value (dp,ar(2),in) - (real,imag) values for constraint

output arguments: none.

2.8.4 disdel Subroutine (Deleting a Constraint at a Node)

subroutine disdel (node,idf) c *** primary function: delete a constraint at a node 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c node (int,sc,in) - node number. c idf (int,sc,in) - reference number of DOF: (1-32) c UX = 1, UY = 2, UZ = 3, ROTX= 4, ROTY= 5, ROTZ= 6, AX = 7, AY = 8 c AZ = 9, VX =10, VY =11, VZ =12 c PRES=19, TEMP=20, VOLT=21, MAG =22, ENKE=23, ENDS=24 c EMF =25, CURR=26 (missing entries are spares) c c output arguments: c none.

2.8.5 foriqr Function (Getting Information About Nodal Loads)

function foriqr (node,key) c *** primary function: get information about nodal loads. 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 node (int,sc,in) - number of node being inquired about. c should be 0 for key=DB_MAXDEFINED or c DB_NUMDEFINED c key (dp,sc,in) - key as to information needed c = 1 - return force mask for node c = DB_MAXDEFINED, c DB_NUMDEFINED - return number of nodal loadings c in model

c c c c c c

NOTE: both DB_MAXDEFINED and DB_NUMDEFINED produce the same functionality output arguments: foriqr (int,func,out)

- the returned value of foriqr is based on

2.8.6 forget Function (Getting a Constraint from the Database)

function forget (inode,idf,value) c *** primary function: get a constraint from the data base 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c inode (int,sc,in) - node number (negative value for no c partabeval) c idf (int,sc,in) - reference number for the DOF: (1-32) c FX = 1, FY = 2, FZ = 3, MX = 4, MY = 5, MZ = 6, CSGX= 7, CSGY= 8 c CSGZ= 9, VFX =10, VFY =11, VFZ =12 c FLOW=19, HEAT=20, AMPS=21, FLUX=22, NPKE=23, NPDS=24 c CURT=25, VLTG=26 (missing entries are spares) c c output arguments: c forget (int,func,out) - status of constraint. c = 0 - no loading on this node for this DOF c = 4 - this node has a loading for this DOF c value (dp,ar(4),out) c value(1-2) - (real,imag) values of present settings c value(3-4) - (real,imag) values of previous settings

2.8.7 forput Subroutine (Storing a Nodal Load at a Node)

subroutine forput (node,idf,value) c *** primary function: store a nodal load at a node 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c node (int,sc,in) - node number c idf (int,sc,in) - reference number for the DOF: (1-32) c FX = 1, FY = 2, FZ = 3, MX = 4, MY = 5, MZ = 6, CSGX= 7, CSGY= 8 c CSGZ= 9, VFX =10, VFY =11, VFZ =12 c FLOW=19, HEAT=20, AMPS=21, FLUX=22, NPKE=23, NPDS=24 c CURT=25, VLTG=26 (missing entries are spares) c c value (dp,ar(2),in) - (real,imag) values of force c

c c c

output arguments: none.

2.8.8 fordel Subroutine (Deleting a Nodal Load at a Node)

subroutine fordel (node,idf) c *** primary function: delete a nodal load at a node 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c node (int,sc,in) - node number c idf (int,sc,in) - reference number for the DOF: (1-32) c FX = 1, FY = 2, FZ = 3, MX = 4, MY = 5, MZ = 6, CSGX= 7, CSGY= 8 c CSGZ= 9, VFX =10, VFY =11, VFZ =12 c FLOW=19, HEAT=20, AMPS=21, FLUX=22, NPKE=23, NPDS=24 c CURT=25, VLTG=26 (missing entries are spares) c c output arguments: c none. c

2.8.9 ntpiqr Function (Getting Information About a Nodal Temperature)

function ntpiqr (node,key) c *** primary function: get information about a nodal temperature 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 node (int,sc,in) - node number c should be zero for key=2 c key (int,sc,in) - key for operation c = 1 - return temperature status c ntpiqr = 0 - node has no temperature c constraint defined c = 1 - node has a temperature c constraint defined c = 2 - return total number of nodal c temperatures defined in model c c output arguments: c ndinqr (int,func,out) - the returned value of ndinqr is based on c

2.8.10 ntpget Function (Getting a Specified Nodal Temperature)

function ntpget (node,temp) c *** primary function: get specified nodal temperature. 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 node (int,sc,in) - node number c c output arguments: c ntpget (int,func,out) - temperature status of node. c = 0 - node has no temperature constraint c = 1 - node has a temperature constraint c temp (dp,ar(2),out) - the node temperature (new,old).

2.8.11 ntpput Subroutine (Storing a Nodal Temperature)

subroutine ntpput (node,temp) c *** primary function: store nodal temperature. 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 node (int,sc,in) - node number c temp (dp ,sc,in) - nodal temperature c c output arguments: c none.

2.8.12 ntpdel Subroutine (Deleting a Nodal Temperature)

subroutine ntpdel (node) c *** primary function: delete node temperatures. 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 node (int,sc,in) - node number c c output arguments: c none.

2.8.13 nhgiqr Function (Getting Information About Nodal Heat Generations)

function nhgiqr (node,key) c *** primary function: get information about nodal heat generations 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 node (int,sc,in) - node number c should be 0 for key=2 c key (int,sc,in) - key for operation c = 1 - return whether node has a heat generation rate c defined c nhgiqr = 0 - no heat generation defined for node c = 1 - heat generation is defined for node c = 2 - return total number of nodal heat generation c rates defined in model c c output arguments: c nhgiqr (int,func,out) - the returned value of nhgiqr is based on c

2.8.14 nhgget Function (Getting a Nodal Heat Generation)

function nhgget (node,hg) c *** primary function: get specified nodal heat generation. 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 node (int,sc,in) - node number c c output arguments: c nhgget (int,func,out) - heat generation status of node. c = 0 - nodal heat generation undefined c = 1 - nodal heat generation is defined c hg (dp,ar(2),out) - the nodal heat generation (new,old).

2.8.15 nhgput Subroutine (Storing Nodal Heat Generation)

subroutine nhgput (node,hg) c *** primary function: store nodal heat generation. 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 c c c c c

input arguments: variable (typ,siz,intent) node (int,sc,in) hg (dp ,sc,in) output arguments: none.

description - node number - nodal heat generation

2.8.16 nhgdel Subroutine (Deleting a Nodal Heat Generation)

subroutine nhgdel (node) c *** primary function: delete nodal heat generations. 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 node (int,sc,in) - node number c c output arguments: none.

2.8.17 nfuiqr Function (Getting Information About Nodal Fluences)

function nfuiqr (node,key) c *** primary function: get information about nodal fluences 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 node (int,sc,in) - node number c should be zero for key=2 c key (int,sc,in) - key for operation c = 1 - return status: c nfuiqr = 0 - node does not have a fluence constraint c = 1 - node has a fluence constraint c = 2 - return total number of nodal fluences defined on c model c c c output arguments: c nfuiqr (int,func,out) - the returned value of nfuiqr is based on c

2.8.18 nfuget Function (Getting a Nodal Fluence)

function nfuget (node,fluen) c *** primary function: get specified nodal fluence. 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 node (int,sc,in) - node number c c output arguments: c nfuget (int,func,out) - fluence status of node. c = 0 - node has no fluence constraint c = 1 - node has a fluence constaint c fluen (dp ,ar(2),out) - the nodal fluences (new,old).

2.8.19 nfuput Subroutine (Storing a Nodal Fluence)

subroutine nfuput (node,fluen) c *** primary function: store nodal fluence. 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 node (int,sc,in) - node number c fluen (dp ,sc,in) - nodal fluence c c output arguments: none.

2.8.20 nfudel Subroutine (Deleting a Nodal Fluence)

subroutine nfudel (node) c *** primary function: delete node fluences. 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 node (int,sc,in) - node number c c output arguments: c none. c

2.8.21 ndciqr Function (Getting Information About Nodal Current Densities)

function ndciqr (node,key) c *** primary function: get information about nodel current densities 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 node (int,sc,in) - node number c should be zero for key=2 c key (int,sc,in) - key for operation c = 1 - return nodal current status: c ndciqr = 0 - no current density defined for this node c = 1 - node has a current density defined c = 2 - total number of nodal current densities defined c on model c c c output arguments: c ndciqr (int,func,out) - the returned value of ndciqr is based on c

2.8.22 ndcget Function (Getting a Nodal Current Density)

function ndcget (node,currd) c *** primary function: get specified nodal current density. 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 node (int,sc,in) - node number c c output arguments: c ndcget (int,func,out) - current density status of node. c = 0 - node has no current density defined c = 1 - node has a current density defined c currd (dp,ar(4,2),out) - the node current density (new,old).

2.8.23 ndcput Subroutine (Storing a Nodal Current Density)

subroutine ndcput (node,currd) c *** primary function: store nodal current density. 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 node (int,sc,in) - node number c currd (dp ,ar(4),in) - nodal current densities

c c c

output arguments: none.

2.8.24 ndcdel Subroutine (Deleting a Nodal Current Density)

subroutine ndcdel (node) c *** primary function: delete nodal current densities 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 node (int,sc,in) - node number c c output arguments: c none.

2.8.25 nvdiqr Function (Getting Information About Nodal Magnetic Virtual Displacements)
function nvdiqr (node,key) c *** primary function: get information about nodal mag virtual disps 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 node (int,sc,in) - node number c should be zero for key=2 c key (int,sc,in) - key for operation c = 1 - return magnetic virtual displacement status c nvdiqr = 0 - no mag. virt. disps defined for this node c = 1 - node has mag. virt. disps defined c = 2 - return total number of nodal magnetic virtual c displacements defined on model c c output arguments c nvdiqr (int,func,out) - the returned value of nvdiqr is based on c

2.8.26 nvdget Function (Getting a Nodal Magnetic Virtual Displacement)

function nvdget (node,virtd) c *** primary function: get specified nodal magnetic virtual displacement c *** Notice - This file contains ANSYS Confidential information ***

c c c c c c c c c c c c c c

typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) node (int,sc,in)

siz=sc,ar(n),func

intent=in,out,inout

description - node number

output arguments: nvdget (int,func,out)

virtd

(dp ,sc,out)

- virtual disp status of node. = 0 - node has no magnetic virtual displacement = 1 - node has a magnetic virtual displacement - the nodal virtual displacement value

2.8.27 nvdput Subroutine (Storing a Nodal Virtual Displacement)

subroutine nvdput (node,virtd) c *** primary function: store nodal virtual displacement 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 node (int,sc,in) - node number c virtd (dp ,sc,in) - nodal virtual displacement c c output arguments: none.

2.8.28 nvddel Subroutine (Deleting a Nodal Virtual Displacement)

subroutine nvddel (node) c *** primary function: delete nodal virtual displacements. 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 node (int,sc,in) - node number c c output arguments: c none.

2.9 Element Loading Routines

2.9.1 epriqr Function (Getting Information About Element Pressure/Convection)

function epriqr (ielem,iface,key) c *** primary function: get information about element pressure/convection 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 ielem (int,sc,in) - element number c should be zero for key=DB_NUMDEFINED or c DB_MAXRECLENG c iface (int,sc,in) - face number for inquire (0-6) c face number is needed for key=5. for c other values of key, iface has different c meaning (see below) c key (int,sc,in) - key as to the information needed c = 1 - return pressure mask for element c = 5 - return number of pressures for this c element face c = DB_NUMDEFINED, c = DB_MAXDEFINED - return value is based on setting of iface c NOTE: both DB_NUMDEFINED and c DB_MAXDEFINED produce the same c functionality c iface = 0 - return number of surface loads defined c = 1-6 - return number of pressure loads c defined for this element. c NOTE: only 1-6 is valid, but this c routine simply checks that iface is in c the range. The actual value of iface c does not matter in this case. c = DB_MAXRECLENG - return the maximum number of element c pressures on any element (max record c length) c c output arguments: c epriqr (int,func,out) - the returned value of epriqr is based on c

2.9.2 eprget Function (Getting an Element Face Pressure)

function eprget (elem,iface,value) c *** primary function: get an element face pressure 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 elem (int,sc,in) - element number (negative value for

c c c c c c c c c c c

iface

(int,sc,in)

no partabeval) - face number (1-6)

output arguments: eprget (int,func,out)

value

(dp ,ar(*),out)

- status of element. =-1 - element has no pressures = 0 - this element face has no pressures > 0 - number of values defined - the element pressures (real,imag) at each face

2.9.3 eprput Subroutine (Storing an Element Face Pressure)

subroutine eprput (ielem,iface,nval,value) c *** primary function: store an element face pressure. 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 ielem (int,sc,in) - element number for operation. c iface (int,sc,in) - face number (1-6) c nval (int,sc,in) - number of values to put c value (dp ,ar(nval),in) - the element pressures (real,imag) at each c face c c output arguments: c none. c

2.9.4 eprdel Subroutine (Deleting an Element Pressure/Convection)

subroutine eprdel (ielem,iface) c *** primary function: delete a pressure/convection on an element 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 ielem (int,sc,in) - element number c iface (int,sc,in) - face number c = 0 - delete all pressures on this c element c = 1-6 - delete pressure on this face c c output arguments: c none. c

2.9.5 ecviqr Function (Getting Information About Element Convections)

function ecviqr (ielem,iface,key) c *** primary function: get information about element convections 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 ielem (int,sc,in) - element number for inquire c should be zero for key=DB_NUMDEFINED or c DB_MAXRECLENG c iface (int,sc,in) - face number for inquire (0-6) c face number is needed for key=5. for c other values of key, iface has different c meaning (see below) c key (int,sc,in) - key as to the information needed c = 1 - return convection mask for element c = 5 - return number of convections for this c element face c = DB_NUMDEFINED, c = DB_MAXDEFINED - return value is based on setting of iface c NOTE: both DB_NUMDEFINED and c DB_MAXDEFINED produce the same c functionality c iface = 0 - return number of surface loads c defined (rec length) c = 1-6 - return number of convection loads c defined for this element. c NOTE: only 1-6 is valid, but this c routine simply checks that iface is in c the range. The actual value of iface c does not matter in this case. c = DB_MAXRECLENG - return the maximum number of convections c on any element (max rec length) c c output arguments: c ecviqr (int,func,out) - the returned value of ecviqr is based on c

2.9.6 ecvget Function (Getting an Element Face Convection)

function ecvget (elem,iface,value) c *** primary function: get an element face convection 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 elem (int,sc,in) - element number (negative value for no

c c c c c c c c c c c c c c c c c c c c

iface

(int,sc,in)

partabeval) - face number (1-6)

output arguments: ecvget (int,func,out)

value

(dp ,ar(*),out)

- status of element. =-1 - element has no convections/heat fluxes = 0 - this element face has no convections/heat fluxes > 0 - number of values defined - the element convections NOTE: Two values at each node of an element face: if loading is a convection, the first first value is the film coefficient and the second value is the bulk temperature. If loading is a heat flux, the first value is the heat flux, and the second value is a large number

2.9.7 ecvput Subroutine (Storing an Element Face Convection)

subroutine ecvput (ielem,iface,nval,value) c *** primary function: store an element face convection. 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 ielem (int,sc,in) - element number c iface (int,sc,in) - face number (1-6) c nval (int,sc,in) - number of values to put c value (dp ,ar(nval),in) - the element convections. c NOTE: Two values at each node of an c element face: if loading is a convection, c the first first value is the film c coefficient and the second value is the c bulk temperature. If loading is a heat c flux, the first value is the heat flux, c and the second value is a large number c (2**100) c output arguments: c none. c

2.9.8 ecvdel Subroutine (Deleting a Convection on an Element)

subroutine ecvdel (ielem,iface) c *** primary function: delete a convection on an element 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 c c c c c c c c c c

input arguments: variable (typ,siz,intent) ielem (int,sc,in) iface (int,sc,in)

description - element number. - face number = 0 - delete all convections on this element = 1-6 - delete convections on this face

output arguments: none.

2.9.9 etpiqr Function (Getting Information About Element Temperatures)

function etpiqr (ielem,key) c *** primary function: get information about element temperatures. 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 ielem (int,sc,in) - element number c Should be 0 for key=11, DB_NUMDEFINED, c DB_MAXDEFINED, and DB_MAXRECLENG c key (int,sc,in) - information flag. c = DB_SELECTED - return status: c etpiqr = 0 - element has no temperatures c = 1 - element has temperatures defined c = DB_NUMDEFINED - return number of temperatures defined for c this element (rec length) c = DB_MAXDEFINED - return number of temperatures defined in c model c = DB_MAXRECLENG - return maximum number of temperatures c defined for any element (max rec length) c = 2 - return length (dp words) c = 3 - return layer number (for cross reference files return c number of entities) c = 4 - return address of first data word c = 5 - return length (dp words) c = 6 - return compressed record number. c = 11 - return void percent (integer) c = 16 - return location of next record (this increments the c next record count) c = 18 - return type of file. c etpiqr = 0 - integer c = 1 - double precision c = 2 - real c = 3 - complex c = 4 - character*8 c = 7 - index c = 19 - return virtual type of file. c etpiqr = 0 - fixed length (4.4 form)

c c c c c c c c c c c

= 1 - indexed variable length (layer data) = 2 - xref data tables = 3 - bitmap data (for 32 data item packed records) = 4 - data tables (three dimensional arrays)

output arguments: etpiqr (int,func,out)

- the returned value of etpiqr is based on

2.9.10 etpget Function (Getting an Element Temperature)

function etpget (ielem,temp) c *** primary function: get element temperatures. 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 ielem (int,sc,in) - element number c c output arguments: c etpget (int,func,out) - status of element. c = 0 - this element has no element c temperatures c > 0 - number of element temperatures c retrieved c temp (dp,ar(n,2),out) - the element temperatures (new,old). c c NOTE: If a value is not defined (i.e., c defaults to TUNIF), value will be a c very small number (2**-100)

2.9.11 etpput Subroutine (Storing an Element Temperature)

subroutine etpput (ielem,n,temp) c *** primary function: store element temperatures. 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 ielem (int,sc,in) - element number c n (int,sc,in) - number of element temperature values c temp (dp ,ar(n),in) - element temperatures. c c output arguments: c none. c NOTE: If a value is not defined (i.e.,

c c c

defaults to TUNIF), a very small number should be used (2**-100)

2.9.12 etpdel Subroutine (Deleting an Element Temperature)

subroutine etpdel (ielem) c *** primary function: delete element temperatures. 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 ielem (int,sc,in) - element number c c output arguments: c none. c

2.9.13 ehgiqr Function (Getting Information About Element Heat Generation)

function ehgiqr (ielem,key) c *** primary function: get information about element heat generations. 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 ielem (int,sc,in) - element number c should be 0 for key=11, DB_NUMDEFINED, c DB_MAXDEFINED, and DB_MAXRECLENG c key (int,sc,in) - information flag. c = DB_SELECTED - return status: c ehgiqr = 0 - heat generation is undefined c = 1 - heat generation is defined c = DB_NUMDEFINED - return number of defined heat generations c in model c = DB_MAXRECLENG - return maximum number of heat generations c on any element (max rec length) c = 2 - return length (dp words) c = 3 - return layer number (for cross reference files return c number of entities) c = 4 - return address of first data word c = 5 - return length (record type units) c = 6 - return compressed record number. c = 11 - return void percent (integer) c = 16 - return location of next record (this increments the c next record count) c = 18 - return type of file. c ehgiqr = 0 - integer

c c c c c c c c c c c c c c c c c c c c

= = = = = = 19 - return ehgiqr = =

1 - double precision 2 - real 3 - complex 4 - character*8 7 - index virtual type of file. 0 - fixed length (4.4 form) 1 - indexed variable length (layer data) = 2 - xref data tables = 3 - bitmap data (for 32 data item packed records) = 4 - data tables (three dimensional arrays)

output arguments: ehgiqr (int,func,out)

- the returned value of ehgiqr is based on setting of key.

2.9.14 ehgget Function (Getting an Element Heat Generation)

function ehgget (ielem,qgen) c *** primary function: get element heat generations. 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 ielem (int,sc,in) - element number c c output arguments: c ehgget (int,func,out) - status of element. c = 0 - heat generations undefined for this c element c > 0 - number of heat generations defined c qgen (dp ,ar(*),out) - the element heat generations. c c NOTE: If a value is not defined, it will c be a very small number (2**-100)

2.9.15 ehgput Subroutine (Storing an Element Heat Generation)

subroutine ehgput (ielem,n,qgen) c *** primary function: store element heat generations 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 c c c c c c c c

variable (typ,siz,intent) ielem (int,sc,in) n (int,sc,in) qgen (dp ,ar(n),in) output arguments: none

description - element number - number of element heat generation values - element heat generations

NOTE: If a value is not defined, a very

2.9.16 ehgdel Subroutine (Deleting an Element Heat Generation)

subroutine ehgdel (ielem) c *** primary function: delete element heat generations. 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 ielem (int,sc,in) - element number c c output arguments: c none c

2.9.17 efuiqr Function (Getting Information About Element Fluences)

function efuiqr (ielem,key) c *** primary function: get information about element fluences 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 ielem (int,sc,in) - element number or zero (see below) c key (int,sc,in) - key as to the information needed c = 1 or DB_MAXRECLENG - return element fluences info c for ielem > 0 - return number of fluences for this c element (record length) c = 0 - return maximum number of fluences c defined for any element c (max rec length) c = DB_NUMDEFINED, c = DB_MAXDEFINED - return number of defined fluences c in model c NOTE: both DB_NUMDEFINED and DB_MAXDEFINED c produce the same functionality c

c c c c

output arguments: efuiqr (int,func,out)

- the returned value of efuiqr is based on setting of key

2.9.18 efuget Function (Getting an Element Fluence)

function efuget (ielem,value) c *** primary function: get element fluences. 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 ielem (int,sc,in) - element number c c output arguments: c efuget (int,func,out) - status of element. c = 0 - element has no fluences defined c > 0 - number of element fluences defined c value (dp,ar(*),out) - element fluences. c c NOTE: If a value is not defined, it will

2.9.19 efuput Subroutine (Storing an Element Fluence)

subroutine efuput (ielem,n,value) c *** primary function: store element fluences 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 ielem (int,sc,in) - element number c n (int,sc,in) - the number of values to store c value (dp,ar(n),in) - element fluences. c c output arguments: c none c c NOTE: If a value is not defined, a very c

2.9.20 efudel Subroutine (Deleting an Element Fluence)

subroutine efudel (ielem) c *** primary function: delete element fluences c c *** Notice - This file contains ANSYS Confidential information *** c

c c c c c c c c c

typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) ielem (int,sc,in) output arguments: none

siz=sc,ar(n),func

intent=in,out,inout

description - element number

2.9.21 edciqr Function (Getting Information About Element Current Densities)

function edciqr (ielem,key) c *** primary function: get information about element current densities 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 ielem (int,sc,in) - element number or zero (see below) c key (int,sc,in) - key as to the information needed c = 1 or DB_MAXRECLENG - return element densities info c for ielem > 0 - number of current densities for this c element (rec length) c = 0 - maximum number of current densities c defined for any element c (max rec length) c = DB_NUMDEFINED, c = DB_MAXDEFINED - return total number of current densities c defined in model c NOTE: both DB_NUMDEFINED and DB_MAXDEFINED c produce the same functionality c c output arguments: c edciqr (int,func,out) - the returned value of edciqr is based on c

2.9.22 edcget Function (Getting Element Current Densities)

function edcget (ielem,value) c *** primary function: get element current densities 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 ielem (int,sc,in) - element number c c output arguments: c edcget (int,func,out) - status of element.

c c c c c c c c

value

(dp,ar(*),out)

= 0 - element has no current densities defined > 0 - number of element current densities defined - element current densities NOTE: If a value is not defined, it will

2.9.23 edcput Subroutine (Storing an Element Current Density)

subroutine edcput (ielem,n,value) c *** primary function: store element current densities 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 ielem (int,sc,in) - element number c n (int,sc,in) - the number of current densities to store c value (dp,ar(n),in) - element current densities c c output arguments: c none c NOTE: If a value is not defined, a very

2.9.24 edcdel Subroutine (Deleting an Element Current Density)

subroutine edcdel (ielem) c *** primary function: delete element current densities 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 ielem (int,sc,in) - element number c c output arguments: c none c

2.9.25 evdiqr Function (Getting Information About Element Virtual Displacements)

function evdiqr (ielem,key) c *** primary function: get information about element virt disps c c *** Notice - This file contains ANSYS Confidential information ***

c c c c c c c c c c c c c c c c c c c c c

typ=int,dp,log,chr,dcp

siz=sc,ar(n),func

intent=in,out,inout

input arguments: variable (typ,siz,intent) description ielem (int,sc,in) - element number or zero (see below) key (int,sc,in) - key as to the information needed = 1 or DB_MAXRECLENG - return element virt disps info for ielem > 0 - number of virt disps defined for this element (rec length) = 0 - maximum number of virt disps defined for any element (max rec length) = DB_NUMDEFINED, = DB_MAXDEFINED - return total number of virt disps defined in model NOTE: both DB_NUMDEFINED and DB_MAXDEFINED produce the same functionality output arguments: evdiqr (int,func,out)

- the returned value of evdiqr is based on

2.9.26 evdget Function (Getting an Element Virtual Displacement)

function evdget (ielem,value) c *** primary function: get element virtual displacements 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 ielem (int,sc,in) - element number c c output arguments: c evdget (int,func,out) - status of element. c = 0 - no virt disps defined for this c element c > 0 - number of element virtual c displacements c value (dp,ar(*),out) - element virtual displacements c c NOTE: If a value is not defined, it will c

2.9.27 evdput Subroutine (Storing an Element Virtual Displacement)

subroutine evdput (ielem,n,value) c *** primary function: store element virtual displacements c *** Notice - This file contains ANSYS Confidential information *** c

c c c c c c c c c c c c

typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) ielem (int,sc,in) n (int,sc,in) value (dp,ar(n),in) output arguments: none

siz=sc,ar(n),func

intent=in,out,inout

description - element number - the total number of values - element virtual displacments

NOTE: If a value is not defined, a very

2.9.28 eimiqr Function (Getting Information About Element Impedances)

function eimiqr (ielem,iface,key) c *** primary function: get information about element impedences 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 ielem (int,sc,in) - element number for inquire. c should be zero for key=DB_NUMDEFINED, c DB_MAXDEFINED or DB_MAXRECLENG c iface (int,sc,in) - face number for inquire (0-6) c face number is needed for key=5. for c other values of key, iface has different c meaning (see below) c key (int,sc,in) - key as to the information needed c = 1 - return impedence mask for element c = 5 - return number of impedences for this c element face c = DB_NUMDEFINED, c = DB_MAXDEFINED - return value is based on setting of iface c NOTE: both DB_NUMDEFINED and c DB_MAXDEFINED produce the same c functionality c iface = 0 - return number of surface loads defined c in model c = 1-6 - return number of pressure loads c defined for this element. (rec length) c NOTE: only 1-6 is valid, but this c routine simply checks that iface is in c the range. The actual value of iface c does not matter in this case. c = DB_MAXRECLENG - return the maximum number of element c impedences defined for any element c (max rec length) c c output arguments: c eimiqr (int,func,out) - the returned value of eimiqr is based on c

2.9.29 eimget Function (Getting an Element Face Impedance)

function eimget (ielem,iface,value) c *** primary function: get an element face impedence 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 ielem (int,sc,in) - element number c iface (int,sc,in) - face number (1-6) c c output arguments: c eimget (int,func,out) - status of element. c =-1 - element has no impedences c = 0 - this element face has no impedences c > 0 - number of values defined c value (dp ,ar(*),out) - the element impedences (real,imag) c

2.9.30 eimput Subroutine (Storing an Element Impedance)

subroutine eimput (ielem,iface,nval,value) c *** primary function: store an element face impedence. 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 ielem (int,sc,in) - element number c iface (int,sc,in) - face number (1-6) c nval (int,sc,in) - number of values to put c value (dp ,ar(nval),in) - the element impedences (real,imag) c c output arguments: c none c

2.9.31 eimdel Subroutine (Deleting an Element Impedance)

subroutine eimdel (ielem,iface) c *** primary function: delete an impedence on a element 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 ielem (int,sc,in) - element number

c c c c c c c

iface

(int,sc,in)

- face number = 0 - delete all impedences on this element = 1-6 - delete impedence on this face

output arguments: none

2.9.32 esfiqr Function (Getting Information About Element Surface Stress Data)
function esfiqr (ielem,key) c *** primary function: get information about element surface stress data 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about surface stress c ielem > 0 - return number of surface stresses on this c element (rec length) c = 0 - return maximum number of surface stresses c on any element (max rec length) c = DB_NUMDEFINED - return the number of surface stresses c defined in model c c output arguments: c esfiqr (int,func,out) - the returned value of esfiqr is based on c setting of key c c

2.9.33 esfget Function (Getting Element Surface Stress Data)

function esfget (ielem,value) c *** primary function: get element surface stress data. 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 ielem (int,sc,in) - element number c c output arguments: c esfget (int,func,out) - status of element. c = 0 - element undefined c > 0 - number of values returned c value (dp,ar(*),out) - element surface stress data.

2.9.34 esfput Subroutine (Storing Element Surface Stress Data)

subroutine efsdel (ielem,iface) c *** primary function: delete a flagged surface on an element 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 ielem (int,sc,in) - element number c iface (int,sc,in) - face number c = 0 - all flagged surfaces c = 1-6 - this flagged surface c c output arguments: c none. c

2.9.35 esfdel Subroutine (Deleting an Element's Surface Stress Data)

subroutine esfdel (ielem) c *** primary function: delete element surface stress data 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.9.36 efsdel Subroutine (Deleting a Flagged Surface on an Element)

subroutine efsdel (ielem,iface) c *** primary function: delete a flagged surface on an element 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 c c c c c c c c c

input arguments: variable (typ,siz,intent) ielem (int,sc,in) iface (int,sc,in)

description - element number - face number = 0 - all flagged surfaces = 1-6 - this flagged surface

output arguments: none.

2.9.37 efsget function (Getting Element Face Flagged Surfaces)

function efsget (ielem,iface,value) c *** primary function: get element face flagged surfaces 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 ielem (int,sc,in) - element number c iface (int,sc,in) - face number (1-6) c c output arguments: c variable (typ,siz,intent) description c efsget (int,func,out) - status of element. c =-1 - no values for this element c = 0 - zero flagged surfaces defined c > 0 - number of values defined c value (dp ,ar(*),out) - the element flagged surfaces c

2.9.38 efsiqr function (Getting Information About Flagged Surfaces)

function efsiqr (ielem,iface,key) c *** primary function: get information about flagged surfaces c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number for inquire. c should be zero for key=DB_NUMDEFINED, c DB_MAXDEFINED or DB_MAXRECLENG c iface (int,sc,in) - face number for inquire (0-6) c face number is needed for key=5. for c other values of key, iface has different c meaning (see below) c key (int,sc,in) - key as to the information needed

c c c c c c c c c c c c c c c c c c c c c c c

= =

1 5

- return flagged surfaces mask for element - return number of flagged surfaces for this element face

= DB_NUMDEFINED, = DB_MAXDEFINED - return value is based on setting of iface NOTE: both DB_NUMDEFINED and DB_MAXDEFINED produce the same functionality iface = 0 - return total number of pressures, convections, etc defined in model = 1-6 - return number of flagged surfaces defined for this element. (rec length) NOTE: only 1-6 is valid, but this routine simply checks that iface is in the range. The actual value of iface does not matter in this case. = DB_MAXRECLENG - return maximum number of flagged surfaces for any element (max rec length) output arguments: variable (typ,siz,intent) efsiqr (int,func,out)

description - the returned value of efsiqr is based on

2.9.39 efsput Subroutine (Storing an Element Face Flagged Surface)

subroutine efsput (ielem,iface,nval,value) c *** primary function: store an element face flagged surface. 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 ielem (int,sc,in) - element number c iface (int,sc,in) - face number (1-6) c nval (int,sc,in) - number of values to put c value (dp ,ar(nval),in) - the element flagged surface values c c output arguments: c none. c

2.10 Results Information Routines

2.10.1 dspiqr Function (Getting Information About Nodal Results)
function dspiqr (node,key) c *** primary function: get information about nodal results 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 node (int,sc,in) - node number c > 0 - return result mask at this node c = 0 - return number of calculated c displacements in model c key (int,sc,in) - key as to the information needed c At this time, key should always = 1 c c output arguments: c dspiqr (int,func,out) - the returned value of dspiqr is based on

2.10.2 dspget Function (Getting a Nodal Result from the Database)

function dspget (node,ndf,idf,value) c *** primary function: get a nodal result from the data base 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 node (int,sc,in) - node number c ndf (int,sc,in) - number of results requested c idf (int,ary(ndf),in) - reference number for the DOF: (1-32) c UX = 1, UY = 2, UZ = 3, ROTX= 4, ROTY= 5, ROTZ= 6, AX = 7, AY = 8 c AZ = 9, VX =10, VY =11, VZ =12 c PRES=19, TEMP=20, VOLT=21, MAG =22, ENKE=23, ENDS=24 c EMF =25, CURR=26 SP01=27, SP02=28, SP03=29, SP04=30, SP05=31, SP06=32 c (missing entries are spares) c c output arguments: c dspget (int,func,out) - number of actual results c value (dp,ar(ndf),out) - result values

2.10.3 dspput Subroutine (Storing a Constraint at a Node)

subroutine dspput (node,ndf,idf,value) c *** primary function: store a result at a node. c *** Notice - This file contains ANSYS Confidential information *** c c c c c input arguments: node (int,sc,in) ndf (int,sc,in) idf (int,ary(ndf),in) value (dp,ar(ndf),in)

- node number - number of results to be stored - reference number for the DOF: (1-32) - displacement values

output arguments:

none

2.10.4 dspdel Subroutine (Deleting a Result at a Node)

subroutine dspdel (node,ndf,idf) c *** primary function: delete a result at a node 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 node (int,sc,in) - node number. (0 to delete DOF at all c nodes) c ndf (int,sc,in) - number of DOFs to delete (0 to delete c all DOFs) c idf (int,ar(*),in) - reference number for the DOF: (1-32) c UX = 1, UY = 2, UZ = 3, ROTX= 4, ROTY= 5, ROTZ= 6, AX = 7, AY = 8 c AZ = 9, VX =10, VY =11, VZ =12 c PRES=19, TEMP=20, VOLT=21, MAG =22, ENKE=23, ENDS=24 c EMF =25, CURR=26 (missing entries are spares) c c output arguments: c none c

2.10.5 emsiqr Function (Getting Information About an Element's Miscellaneous Summable Data)
function emsiqr (ielem,key) c *** primary function: get information about element misc summable data 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about misc summed data records c ielem > 0 - return number of misc summed c data items for this element c (record length) c = 0 - return maximum number of misc c summed data items on any c element (max record length) c = DB_NUMDEFINED - return total number of misc summed data c items defined in model c c output arguments: c emsiqr (int,func,out) - the returned value of emsiqr is based on c setting of key

2.10.6 emsget Function (Getting an Element's Miscellaneous Summable Data)

function emsget (ielem,value) c *** primary function: get element misc summable data. 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 ielem (int,sc,in) - element number c c output arguments: c emsget (int,func,out) - status of element. c = 0 - element is undefined c > 0 - number of data items returned c value (dp,ar(*),out) - element misc summed data. c c NOTE: the contents of this record is element c dependent. See SMISC on ETABLE command c

2.10.7 emsput Subroutine (Storing an Element's Miscellaneous Summable Data)

subroutine emsput (ielem,nval,value) c *** primary function: store misc. summable data for an element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - number of values to be stored c value (dp,ar(nval),in) - the misc summed data values c c output arguements: c none c NOTE: the contents of this record is element c dependent. See SMISC on ETABLE command c

2.10.8 emsdel Subroutine (Deleting an Element's Miscellaneous Summable Data)

subroutine emsdel (ielem)

c *** primary function: delete element misc summable data 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete data for all defined elements c c output arguments: c none c

2.10.9 enfiqr Function (Getting Information About Element Nodal Forces)

function enfiqr (ielem,key) c *** primary function: get information about element nodal forces 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element nodal forces c ielem > 0 - return number of element nodal c forces for this element c (record length) c = 0 - return maximum number of element c nodal forces on any element c (max record length) c = DB_NUMDEFINED - return total number of element nodal c forces defined in model c c output arguments: c enfiqr (int,func,out) - the returned value of enfiqr is based on c setting of key c

2.10.10 enfget Function (Getting an Element's Nodal Forces)

function enfget (ielem,value) c *** primary function: get element nodal forces. 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 c c c c c c c c

variable (typ,siz,intent) ielem (int,sc,in) output arguments: enfget (int,func,out)

description - element number

value

(dp,ar(*),out)

- status of element. = 0 - element has no nodal forces > 0 - number of nodal forces returned - element nodal forces

2.10.11 enfput Subroutine (Storing an Element's Nodal Forces)

subroutine enfput (ielem,nval,value) c *** primary function: store nodal force results at an element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c NOTE: There may be a maximum of 3 sets of c nodal forces in the record: static c forces, inertia forces, and damping forces c value (dp,ar(nval),in) - nodal force results c c output arguments: c none c

2.10.12 enfdel Subroutine (Deleting an Element's Nodal Forces)

subroutine enfdel (ielem) c *** primary function: delete element nodal forces data 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none c

2.10.13 ensiqr Function (Getting Information About an

Element's Nodal Stresses)

function ensiqr (ielem,key) c *** primary function: get information about element nodal stresses 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element nodal stresses c ielem > 0 - return number of element nodal c stresses for this element c (record length) c = 0 - return maximum number of element c nodal stresses on any element c (max record length) c = DB_NUMDEFINED - return total number of element nodal stresses c defined in model c c output arguments: c ensiqr (int,func,out) - the returned value of ensiqr is based on c setting of key c

2.10.14 ensget Function (Getting an Element's Nodal Stresses)

function ensget (ielem,value) c *** primary function: get element nodal stresses. 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 ielem (int,sc,in) - element number c c output arguments: c ensget (int,func,out) - status of element. c = 0 - element undefined c > 0 - number of nodal stresses c returned c value (dp,ar(*),out) - element nodal stresses c c NOTE: Stresses at each corner node in the order c X, Y, Z, XY, YZ, XZ c For solid elements, stresses at each c corner node c For shell elements, stresses at each c corner node (first top durface, then c bottom) c For layered elements (w/KEYOPT(8)=0),

c c c c c c c c c c c c c c c c c c c

stresses for "first" layer at each corner node (first at the bottom surface of the bottom layer, then the top surface of the top layer). Stresses for "second" layer at each corner node (first the bottom surface, then the top surface for the layer with the largest failure criteria). The second layer is not present if failure criteria were not used or are not appropriate For layered elements (w/KEYOPT(8)=1), stresses for each layer at each corner node (first at the bottom surface, then the top surface) For beam elements, the contents of this record is element depenent. See LS item of ETABLE command.

2.10.15 ensput Subroutine (Storing Nodal Stresses at an Element)

subroutine ensput (ielem,nval,value) c *** primary function: store nodal stresses at an element. 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 ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c (6*nnod*nface) c value (dp,ar(nval),in) - the stress values c c output arguments: c none c c NOTE: Stresses at each corner node in the order c X, Y, Z, XY, YZ, XZ c For solid elements, stresses at each c corner node c For shell elements, stresses at each c corner node (first top durface, then c bottom) c For layered elements (w/KEYOPT(8)=0), c stresses for "first" layer at each c corner node (first at the bottom c surface of the bottom layer, then the c top surface of the top layer). c Stresses for "second" layer at each c corner node (first the bottom surface, c then the top surface for the layer with c the largest failure criteria).

c c c c c c c c c c c

The second layer is not present if failure criteria were not used or are not appropriate For layered elements (w/KEYOPT(8)=1), stresses for each layer at each corner node (first at the bottom surface, then the top surface) For beam elements, the contents of this record is element depenent. See LS item of ETABLE command.

2.10.16 ensdel Subroutine (Deleting an Element's Nodal Stresses)

subroutine ensdel (ielem) c *** primary function: delete element nodal stresses 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.17 engiqr Function (Getting Information About an Element's Energies)

function engiqr (ielem,key) c *** primary function: get information about element energies 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element energies c ielem > 0 - return number of element energies on c this element (rec length) c = 0 - return maximum number of element c energies on any element c (max rec length) c = DB_NUMDEFINED - return the number of element energies c defined in model

c c c c c c

output arguments: engiqr (int,func,out)

- the returned value of engiqr is based on setting of key

2.10.18 engget Function (Getting an Element's Energies)

function engget (ielem,value) c *** primary function: get element energies. 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 ielem (int,sc,in) - element number c c output arguments: c engget (int,func,out) - status of element. c = 0 - element undefined c = 6 - energies returned c value (dp,ar(6),out) c value(1) = volume of element c (2) = strain energy c (3) = dissipation energy c (4) = kinetic energy c (5-6) = spares c

2.10.19 engput Subroutine (Storing an Element's Energies and Volume)

subroutine engput (ielem,nval,value) c *** primary function: store volume and energies for an element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values to be stored c Must be 6! c value (dp,ar(6),in) - volume and energies c value(1) = volume of element c (2) = strain energy c (3) = dissipation energy c (4) = kinetic energy c (5-6) = spares c

c c c

output arguments: none

2.10.20 engdel Subroutine (Deleting an Element's Energies)

subroutine engdel (ielem) c *** primary function: delete element energies 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.21 egriqr Function (Getting Information About an Element's Nodal Gradients)

function egriqr (ielem,key) c *** primary function: get information about element nodal gradients 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about nodal gradients c for ielem > 0 - return number of nodal gradients on c this element (record length) c = 0 - return maximum number of nodal c gradients on any element c (maximum record length) c = DB_NUMDEFINED - return the number of nodal gradients defined c in model c c output arguments: c egriqr (int,func,out) - the returned value of egriqr is based on c

2.10.22 egrget Function (Getting an Element's Nodal Gradients)

function egrget (ielem,value) c *** primary function: get element nodal gradients. 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 ielem (int,sc,in) - element number c c output arguments: c egrget (int,func,out) - status of element. c = 0 - element undefined c > 0 - number of nodal gradients c returned c value (dp,ar(*),out) - element nodal gradients c c Note: If a coupled field, a set of c gradients are stored in the following c order (as available): fluid, thermal, c electric, magnetic c

2.10.23 egrput Subroutine (Storing an Element's Nodal Gradients)

subroutine egrput (ielem,nval,value) c *** primary function: store nodal gradients at an element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c (ndir*nnod*nscalr) c value (dp,ar(nval),in) - the gradient values c c Note: If a coupled field, a set of c gradients are stored in the following c order (as appropriate): fluid, thermal, c electric, magnetic c output arguments: c none c

2.10.24 egrdel Subroutine (Deleting an Element's Nodal Gradients)

subroutine egrdel (ielem)

c *** primary function: delete element nodal gradients 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.25 eeliqr Function (Getting Information About an Element's Nodal Elastic Strains)
function eeliqr (ielem,key) c *** primary function: get information about element nodal elastic strains 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about elastic strains c ielem > 0 - return number of nodal elasic strains c on this element (rec length) c = 0 - return maximum number of nodal elastic c strains on any element c (max rec length) c = DB_NUMDEFINED - return the number of nodal elastic strains c defined in model c c output arguments: c eeliqr (int,func,out) - the returned value of eeliqr is based on c

2.10.26 eelget Function (Getting an Element's Nodal Elastic Strains)

function eelget (ielem,value) c *** primary function: get element nodal elastic strains. 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 c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

variable (typ,siz,intent) ielem (int,sc,in) output arguments: eelget (int,func,out)

description - element number

value

(dp,ar(*),out)

- status of element. = 0 - element undefined > 0 - number of nodal elastic strains returned - element nodal elastic strains

NOTE: Strains at each corner node in the order X, Y, Z, XY, YZ, XZ For solid elements, strains at each corner node For shell elements, strains at each corner node (first top durface, then bottom) For layered elements (w/KEYOPT(8)=0), strains for "first" layer at each corner node (first at the bottom surface of the bottom layer, then the top surface of the top layer). Strains for "second" layer at each corner node (first the bottom surface, then the top surface for the layer with the largest failure criteria). The second layer is not present if failure criteria were not used or are not appropriate For layered elements (w/KEYOPT(8)=1), strains for each layer at each corner node (first at the bottom surface, then the top surface) For beam elements, the contents of this record is element depenent. See LEPEL item of ETABLE command.

2.10.27 eelput Subroutine (Storing an Element's Nodal Elastic Strains)

subroutine eelput (ielem,nval,value) c *** primary function: store nodal elastic strains at an element. 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 ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c (6*nnod*nface) c value (dp,ar(nval),in) - nval strain values

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

output arguments: none NOTE: Strains at each corner node in the order X, Y, Z, XY, YZ, XZ For solid elements, strains at each corner node For shell elements, strains at each corner node (first top durface, then bottom) For layered elements (w/KEYOPT(8)=0), strains for "first" layer at each corner node (first at the bottom surface of the bottom layer, then the top surface of the top layer). Strains for "second" layer at each corner node (first the bottom surface, then the top surface for the layer with the largest failure criteria). The second layer is not present if failure criteria were not used or are not appropriate For layered elements (w/KEYOPT(8)=1), strains for each layer at each corner node (first at the bottom surface, then the top surface) For beam elements, the contents of this record is element depenent. See LEPEL item of ETABLE command.

2.10.28 eeldel Subroutine (Deleting an Element's Nodal Elastic Strains)

subroutine eeldel (ielem) c *** primary function: delete element elastic strains 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.29 epliqr Function (Getting Information About an Element's Nodal Plastic Strains)

function epliqr (ielem,key) c *** primary function: get information about element nodal plastic strains 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about plastic strains c ielem > 0 - return number of nodal plastic strains c on this element c (record length) c = 0 - return maximum number of nodal plastic c strains on any element c (max record length) c = DB_NUMDEFINED - return the number of nodal plastic strains c defined in model c c output arguments: c epliqr (int,func,out) - the returned value of epliqr is based on c setting of key c

2.10.30 eplget Function (Getting an Element's Nodal Plastic Strains)

function eplget (ielem,value) c *** primary function: get element nodal plastic strains. 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 ielem (int,sc,in) - element number c c output arguments: c eplget (int,func,out) - status of element. c = 0 - element undefined c > 0 - number of nodal plastic strains c returned c value (dp,ar(*),out) - element nodal plastic strains c c NOTE: Strains at each corner node in the order c X, Y, Z, XY, YZ, XZ c For solid elements, strains at each c corner node c For shell elements, strains at each c corner node (first top durface, then c bottom) c For layered elements (w/KEYOPT(8)=0), c strains for "first" layer at each

c c c c c c c c c c c c c c c c c c

corner node (first at the bottom surface of the bottom layer, then the top surface of the top layer). Strains for "second" layer at each corner node (first the bottom surface, then the top surface for the layer with the largest failure criteria). The second layer is not present if failure criteria were not used or are not appropriate For layered elements (w/KEYOPT(8)=1), strains for each layer at each corner node (first at the bottom surface, then the top surface) For beam elements, the contents of this record is element depenent. See LEPPL item of ETABLE command.

2.10.31 eplput Subroutine (Storing an Element's Nodal Plastic Strains)

subroutine eplput (ielem,nval,value) c *** primary function: store nodal plastic strains at a element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c (6*nnod*nface) c value (dp,ar(nval),in) - the strain values c c output arguments: c none c NOTE: Strains at each corner node in the order c X, Y, Z, XY, YZ, XZ c For solid elements, strains at each c corner node c For shell elements, strains at each c corner node (first top durface, then c bottom) c For layered elements (w/KEYOPT(8)=0), c strains for "first" layer at each c corner node (first at the bottom c surface of the bottom layer, then the c top surface of the top layer). c Strains for "second" layer at each c corner node (first the bottom surface, c then the top surface for the layer with c the largest failure criteria). c The second layer is not present if

c c c c c c c c c c

failure criteria were not used or are not appropriate For layered elements (w/KEYOPT(8)=1), strains for each layer at each corner node (first at the bottom surface, then the top surface) For beam elements, the contents of this record is element depenent. See LEPPL item of ETABLE command.

2.10.32 epldel Subroutine (Deleting an Element's Nodal Plastic Strains)

subroutine epldel (ielem) c *** primary function: delete element plastic strains 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.33 ecriqr Function (Getting Information About an Element's Nodal Creep Strains)
function ecriqr (ielem,key) c *** primary function: get information about element nodal creep strains 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about creep strains c ielem > 0 - return number of nodal creep strains c on this element c (record length) c = 0 - return maximum number of nodal creep c strains on any element c (max record length) c = DB_NUMDEFINED - return the number of nodal creep strains c defined in model

c c c c

output arguments: ecriqr (int,func,out)

- the returned value of ecriqr is based on

2.10.34 ecrget Function (Getting an Element's Nodal Creep Strains)

function ecrget (ielem,value) c *** primary function: get element nodal creep strains. 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 ielem (int,sc,in) - element number c c output arguments: c ecrget (int,func,out) - status of element. c = 0 - element undefined c > 0 - number of nodal creep strains c returned c value (dp,ar(*),out) - element nodal creep strains c c NOTE: Strains at each corner node in the order c X, Y, Z, XY, YZ, XZ c For solid elements, strains at each c corner node c For shell elements, strains at each c corner node (first top durface, then c bottom) c For layered elements (w/KEYOPT(8)=0), c strains for "first" layer at each c corner node (first at the bottom c surface of the bottom layer, then the c top surface of the top layer). c Strains for "second" layer at each c corner node (first the bottom surface, c then the top surface for the layer with c the largest failure criteria). c The second layer is not present if c failure criteria were not used or are c not appropriate c For layered elements (w/KEYOPT(8)=1), c strains for each layer at each corner c node (first at the bottom surface, then c the top surface) c For beam elements, the contents of this c record is element depenent. See LEPCR c item of ETABLE command. c

2.10.35 ecrput Subroutine (Storing an Element's Nodal Creep

Strains)
subroutine ecrput (ielem,nval,value) c *** primary function: store nodal creep strains at an element. 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 ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c (6*nnod*nface) c value (dp,ar(nval),in) - the strain values c c output arguments: c none c NOTE: Strains at each corner node in the order c X, Y, Z, XY, YZ, XZ c For solid elements, strains at each c corner node c For shell elements, strains at each c corner node (first top durface, then c bottom) c For layered elements (w/KEYOPT(8)=0), c strains for "first" layer at each c corner node (first at the bottom c surface of the bottom layer, then the c top surface of the top layer). c Strains for "second" layer at each c corner node (first the bottom surface, c then the top surface for the layer with c the largest failure criteria). c The second layer is not present if c failure criteria were not used or are c not appropriate c For layered elements (w/KEYOPT(8)=1), c strains for each layer at each corner c node (first at the bottom surface, then c the top surface) c For beam elements, the contents of this c record is element depenent. See LEPCR c item of ETABLE command. c

2.10.36 ecrdel Subroutine (Deleting an Element's Nodal Creep Strains)

subroutine ecrdel (ielem) c *** primary function: delete element creep strains c *** secondary functions: none. c c *** Notice - This file contains ANSYS Confidential information *** c

c c c c c c c c c c

typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) ielem (int,sc,in)

siz=sc,ar(n),func

intent=in,out,inout

description - element number = 0 - delete for all defined elements

output arguments: none.

2.10.37 ethiqr Function (Getting Information About an Element's Nodal Thermal Strains)
function ethiqr (ielem,key) c *** primary function: get information about element nodal thermal strains 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about thermal strains c ielem > 0 - return number of nodal thermal strains c on this element c (record length) c = 0 - return maximum number of nodal thermal c strains on any element c (max record length) c = DB_NUMDEFINED - return the number of nodal thermal strains c defined in model c c output arguments: c ethiqr (int,sc,out) - the returned value of ethiqr is based on c

2.10.38 ethget Function (Getting an Element's Nodal Thermal Stresses)

function ethget (ielem,value) c *** primary function: get element nodal thermal strains. 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 ielem (int,sc,in) - element number c c output arguments:

c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c

ethget

(int,func,out)

value

(dp,ar(*),out)

- status of element. = 0 - element undefined > 0 - number of nodal thermal strains returned - element nodal thermal strains NOTE: Strains at each corner node in the order X, Y, Z, XY, YZ, XZ For solid elements, strains at each corner node For shell elements, strains at each corner node (first top durface, then bottom) For layered elements (w/KEYOPT(8)=0), strains for "first" layer at each corner node (first at the bottom surface of the bottom layer, then the top surface of the top layer). Strains for "second" layer at each corner node (first the bottom surface, then the top surface for the layer with the largest failure criteria). The second layer is not present if failure criteria were not used or are not appropriate For layered elements (w/KEYOPT(8)=1), strains for each layer at each corner node (first at the bottom surface, then the top surface) For beam elements, the contents of this record is element depenent. See LEPTH item of ETABLE command.

2.10.39 ethput Subroutine (Storing an Element's Nodal Thermal Stresses)

subroutine ethput (ielem,nval,value) c *** primary function: store nodal thermal strains at an element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c (6*nnod*nface) c value (dp,ar(nval),in) - the strain values c c output arguments: c none c NOTE: Strains at each corner node in the order

c c c c c c c c c c c c c c c c c c c c c c c c c c c

X, Y, Z, XY, YZ, XZ For solid elements, strains at each corner node For shell elements, strains at each corner node (first top durface, then bottom) For layered elements (w/KEYOPT(8)=0), strains for "first" layer at each corner node (first at the bottom surface of the bottom layer, then the top surface of the top layer). Strains for "second" layer at each corner node (first the bottom surface, then the top surface for the layer with the largest failure criteria). The second layer is not present if failure criteria were not used or are not appropriate For layered elements (w/KEYOPT(8)=1), strains for each layer at each corner node (first at the bottom surface, then the top surface) For beam elements, the contents of this record is element depenent. See LEPTH item of ETABLE command.

2.10.40 ethdel Subroutine (Deleting an Element's Thermal, Initial, and Swelling Strains)
subroutine ethdel (ielem) c *** primary function: delete element thermal, initial, and c swelling strains 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.41 euliqr Function (Getting Information About an Element's Euler Angles)

function euliqr (ielem,key) c *** primary function: get information about element euler angles

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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element euler angles c ielem > 0 - return number of euler angles on this c element c (record length) c = 0 - return maximum number of euler angles c on any element c (max record length) c = DB_NUMDEFINED - return the number of element euler angles c defined in model c c output arguments: c euliqr (int,func,out) - the returned value of euliqr is based on c

2.10.42 eulget Function (Getting an Element's Nodal Euler Angles)

function eulget (ielem,value) c *** primary function: get element nodal euler angles. 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 ielem (int,sc,in) - element number c c output arguments: c eulget (int,func,out) - status of element. c = 0 - element undefined c > 0 - number of euler angle values c returned c value (dp,ar(*),out) - element euler angles c c NOTE: For lower-ordered elements, rotations c at centroid c For higher-ordered elements, rotations c at each corner node c For layered shells, rotations at each c corner node, plus layer rotation angle c for each layer (real constant THETA) c For layered solids, rotation angles at c centroid, plus layer rotation angle c for each layer (real constant THETA) c

2.10.43 eulput Subroutine (Storing an Element's Euler Angles)

subroutine eulput (ielem,nval,value) c *** primary function: store nodal euler angles for an element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c (3 * number of display nodes) c value (dp,ar(nval),in) - the euler angle values c c output arguments: c none c NOTE: For lower-ordered elements, rotations c at centroid c For higher-ordered elements, rotations c at each corner node c For layered shells, rotations at each c corner node, plus layer rotation angle c for each layer (real constant THETA) c For layered solids, rotation angles at c centroid, plus layer rotation angle c for each layer (real constant THETA) c

2.10.44 euldel Subroutine (Deleting an Element's Euler Angles)

subroutine euldel (ielem) c *** primary function: delete element euler angles 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.45 efxiqr Function (Getting Information About Element Fluxes)

function efxiqr (ielem,key)

c *** primary function: get information about element fluxes 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element fluxes c ielem > 0 - return number of fluxes on this c element c (record length) c = 0 - return maximum number of fluxes c on any element c (max record length) c = DB_NUMDEFINED - return the number of element fluxes defined c in model c c output arguments: c efxiqr (int,func,out) - the returned value of efxiqr is based on c

2.10.46 efxget Function (Getting an Element Flux)

function efxget (ielem,value) c *** primary function: get element nodal fluxes. 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 ielem (int,sc,in) - element number c c output arguments: c efxget (int,func,out) - status of element. c = 0 - element undefined c > 0 - number of nodal fluxes returned c value (dp,ar(*),out) - element nodal fluxes c c Note: If a coupled field, a set of fluxes is c stored in the following order (as c available): fluid, thermal, c electric, magnetic c

2.10.47 efxput Subroutine (Storing an Element's Fluxes)

subroutine efxput (ielem,nval,value) c *** primary function: store nodal fluxes at an element. c *** secondary functions: none. c c *** Notice - This file contains ANSYS Confidential information ***

c c c c c c c c c c c c c c c c c

typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) ielem (int,sc,in) nval (int,sc,in) value

siz=sc,ar(n),func

intent=in,out,inout

(dp,ar(nval),in)

description - element number - the total number of values (ndir*nnod*nscalr) - the flux values

output arguments: none Note: If a coupled field, a set of fluxes is stored in the following order (as available): fluid, thermal, electric, magnetic

2.10.48 efxdel Subroutine (Deleting Element Fluxes)

subroutine efxdel (ielem) c *** primary function: delete element nodal fluxes 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.49 elfiqr Function (Getting Information About Element Local Forces)

function elfiqr (ielem,key) c *** primary function: get information about elem local forces 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element local forces c ielem > 0 - return number of local forces on this c element c (record length)

c c c c c c c c c c

= 0 - return maximum number of local forces on any element (max record length) = DB_NUMDEFINED - return the number of element local forces defined in model output arguments: elfiqr (int,func,out)

- the returned value of elfiqr is based on setting of key

2.10.50 elfget Function (Getting an Element Local Force)

function elfget (ielem,value) c *** primary function: get element local nodal forces. 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 ielem (int,sc,in) - element number c c output arguments: c elfget (int,func,out) - status of element. c = 0 - element has no local nodal forces c > 0 - number of nodal forces returned c value (dp,ar(*),out) - element local nodal forces. c

2.10.51 elfput Subroutine (Storing an Element's Local Forces)

subroutine elfput (ielem,nval,value) c *** primary function: store element local nodal forces. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c NOTE: There may be a maximum of 3 sets of c nodal forces in the record: static c forces, inertia forces, and damping forces c value (dp,ar(nval),in) - element local nodal forces c c output arguments: c none c

2.10.52 elfdel Subroutine (Deleting Element Local Forces)

subroutine elfdel (ielem) c *** primary function: delete element local forces 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.53 emniqr Function (Getting Information About Element Miscellaneous Non-summable Data)
function emniqr (ielem,key) c *** primary function: get information about element misc non-summable c data 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element misc non-summed data c ielem > 0 - return number of data items on this c element c (record length) c = 0 - return maximum number of data items c on any element c (max record length) c = DB_NUMDEFINED - return the number of element misc non-summed c data items defined in model c c output arguments: c emniqr (int,func,out) - the returned value of emniqr is based on c setting of key c

2.10.54 emnget Function (Getting an Element's Miscellaneous Non-summable Data)

function emnget (ielem,value) c *** primary function: get misc non-summable data. c c *** Notice - This file contains ANSYS Confidential information ***

c c c c c c c c c c c c c c c c c

typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) ielem (int,sc,in)

siz=sc,ar(n),func

intent=in,out,inout

description - element number

output arguments: emnget (int,func,out)

value

(dp,ar(*),out)

- status of element. = 0 - no non-summed misc data at this element > 0 - number of data items returned - element misc non-summed data. NOTE: the contents of this record is element dependent. See NMISC on ETABLE command

2.10.55 emnput Subroutine (Storing an Element's Miscellaneous Non-summable Data)

subroutine emnput (ielem,nval,value) c *** primary function: store misc. non-summable data for an element. 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c value (dp,ar(nval),in) - the misc. non-summed data items c c output arguments: c none c NOTE: the contents of this record is element c dependent. See NMISC on ETABLE command c

2.10.56 emndel Subroutine (Deleting an Element's Miscellaneous Non-summable Data)

subroutine emndel (ielem) c *** primary function: delete element misc non-summable data 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description

c c c c c c

ielem

(int,sc,in)

- element number = 0 - delete for all defined elements

output arguments: none.

2.10.57 ecdiqr Function (Getting Information About Element Current Densities)

function ecdiqr (ielem,key) c *** primary function: get information about element current c densities 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element current densities c ielem > 0 - return number of current densities on c this element c (record length) c = 0 - return maximum number of current c densities on any element c (max record length) c = DB_NUMDEFINED - return the number of element current c densities defined in model c c output arguments: c ecdiqr (int,func,out) - the returned value of ecdiqr is based on c setting of key c

2.10.58 ecdget Function (Getting an Element Current Density)

function ecdget (ielem,value) c *** primary function: get calculated element current densities. 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 ielem (int,sc,in) - element number c c output arguments: c ecdget (int,func,out) - status of element. c = 0 - element has no current densities c > 0 - number of calculated element c current densities

c c c c

value

(dp,ar(*),out)

- calculated element current densities. NOTE: current densities are in the order

2.10.59 ecdput Subroutine (Storing an Element's Current Densities)

subroutine ecdput (ielem,nval,value) c *** primary function: store calculated element current densities 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c value (dp,ar(nval),in) - calculated element current densities. c c output arguments: c none c NOTE: current densities are in the order c

2.10.60 ecddel Subroutine (Deleting Element Current Densities)

subroutine ecddel (ielem) c *** primary function: delete element current densities 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.61 enliqr Function (Getting Information About Element Nonlinear Tables)

function enliqr (ielem,key) c *** primary function: get information about element nonlinear tables 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed c = 1 - return info about element nonlinear tables c ielem > 0 - return number of nonlinear tables for c this element c (record length) c = 0 - return maximum number of nonlinear c tables for any element c (max record length) c = DB_NUMDEFINED - return the number of element nonlinear c tables defined in model c c output arguments: c enliqr (int,func,out) - the returned value of enliqr is based on c setting of key

2.10.62 enlget Function (Getting Element Nonlinear Tables)

function enlget (ielem,value) c *** primary function: get element nonlinear tables. 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 ielem (int,sc,in) - element number c c output arguments: c enlget (int,func,out) - status of element. c = 0 - nonlinear tables undefined c > 0 - number of nonlinear tables defined c value (dp ,ar(n),out) - the element nonlinear tables. c c NOTE: Nonlinear data at each node are in the c order SEPL, SRAT, HPRES, EPEQ, PSV, c PLWK, and 4 spares c For beam elements, the contents and c number of information is element c dependent. See NLIN on ETABLE c command c

2.10.63 enlput Subroutine (Storing an Element's Nonlinear Tables)

subroutine enlput (ielem,n,temp) c *** primary function: store element nonlinear tables

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 ielem (int,sc,in) - element number c n (int,sc,in) - number of element nonlinear table values c temp (dp ,ar(6),in) - element nonlinear table,etc. c c output arguments: c none. c NOTE: Nonlinear data at each node are in the c order SEPL, SRAT, HPRES, EPEQ, PSV, c PLWK, and 4 spares c For beam elements, the contents and c number of information is element c dependent. See NLIN on ETABLE c command c

2.10.64 enldel Subroutine (Deleting Element Nonlinear Tables)

subroutine enldel (ielem) c *** primary function: delete element nonlinear tables 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

2.10.65 ehciqr Function (Getting Information About Calculated Element Heat Generations)
function ehciqr (ielem,key) c *** primary function: get information about calculated elem heat generations 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 ielem (int,sc,in) - element number (or zero, see below) c key (int,sc,in) - key as to the information needed

c c c c c c c c c c c c c c

1 - return info about calculated element heat gens for ielem > 0 - return number of heat gens for this element (record length) = 0 - return maximum number of heat gens for any element (max record length) = DB_NUMDEFINED - return the number of calculated element heat generations defined in model output arguments: ehciqr (int,func,out)

- the returned value of ehciqr is based on setting of key

2.10.66 ehcget Function (Getting a Calculated Element Heat Generation)

function ehcget (ielem,value) c *** primary function: get calculated element heat generations. 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 ielem (int,sc,in) - element number c c output arguments: c ehcget (int,func,out) - status of element. c = 0 - element undefined c > 0 - number of calculated element c heat generations c value (dp,ar(*),out) - calculated element heat generations. c

2.10.67 ehcput Subroutine (Storing an Element's Calculated Heat Generations)

subroutine ehcput (ielem,nval,value) c *** primary function: store calculated element heat generations 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 ielem (int,sc,in) - element number c nval (int,sc,in) - the total number of values c value (dp,ar(nval),in) - calculated element heat generations. c c output arguments:

c c

none

2.10.68 ehcdel Subroutine (Deleting Element Calculated Heat Generations)

subroutine ehcdel (ielem) c *** primary function: delete calculated element heat generations 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),func intent=in,out,inout c c input arguments: c variable (typ,siz,intent) description c ielem (int,sc,in) - element number c = 0 - delete for all defined elements c c output arguments: c none. c

Go to the beginning of this chapter

Chapter 3: Subroutines for Users' Convenience

Go to the Next Appendix Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Appendix A

3.1 What Subroutines Does This Chapter Describe?

This chapter describes ANSYS routines available to you for use in programming. Using these routines isn't required, but may make your life easier. These routines include a set of general routines that perform utility-type functions, a set of routines supporting vector functions, a set of routines supporting matrix functions, and routines supporting message processing options.

3.1.1 Input and Output Abbreviations

The descriptions of inputs and outputs for the routines discussed in this chapter use the following abbreviations:
G

Argument type is one of the following: int - integer dp - double precision log - logical chr - character dcp - double precision complex

Argument size is one of the following: sc - scalar variable ar(n) - array variable of length n func - functional return value

Argument intent is one of the following: in - input argument

out - output argument inout - both an input and an output argument

3.2 General Subroutines

3.2.1 dptoch Subroutine (Retrieve Eight Characters From a Double Precision Variable)
subroutine dptoch (dp8,ch8) c *** primary function: retreive 8 characters from a dp variable c *** Notice - This file contains ANSYS Confidential information *** c c c c input arguments: dp8 (dp,sc,in) output arguments: ch8 (ch*8,sc,out)

- dp variable containing characters

- characters retreived from the dp word

3.2.2 wrinqr Function (Obtain Information About Output)

c c c c c c c c c c c c c c c c c c c c c c c c c c c function wrinqr (key) *** primary function: obtain information about output *** Notice - This file contains ANSYS Confidential information *** --- caution: the following variables are "saved/resumed". --key=WR_COLINTER thru WR_SUPCOLMAX in "wrinqr/wrinfo" --(data for "/fmt,/page,/header" commands). --note that the whole common cannot be "saved/resumed". typ=int,dp,log,chr,dcp siz=sc,ar(n),func intent=in,out,inout

cwa

input arguments: variable (typ,siz,intent) description wrcom name key (int,sc,in) = WR_PRINT - print flag (kprint) prtkey wrinqr = 0 - no output = 1 - print = WR_OUTPUT - current output unit number (iott) outfil = WR_MASTEROUT - master output file frstot = WR_COLINTER - interactive columns per page intcol = WR_COLBATCH - batch columns per page batcol = WR_LINEINTER - interactive lines per page intlin = WR_LINEBATCH - batch lines per page batlin = WR_CHARITEM - characters per output item chrper = WR_CHARDECIMAL - characters past decimal chrdec = WR_CHARINTEGER - characters in leading integer chrint = WR_CHARTYPE chrtyp

c c c c c c c c c c c c

= = = = = =

wrinqr = 1 - using E format in output = 2 - using F format in output = 3 - using G format in output WR_SUPTITLE - tlabel supress key WR_SUPSUBTITLE - subtitle supress key WR_SUPLSITER - ls,iter id supress key WR_NOTELINE - note line supress key WR_SUPCOLHEADER - column header supress key WR_SUPCOLMAX - column maximum supress key

keyhed keytit keyid keynot keylab keysum

output arguments: wrinqr (int,func,out)

- the value corresponding to key

3.2.3 erinqr Subroutine (Obtaining Information from the Errors Common)

function erinqr (key) c *** primary function: obtain information from errors common c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c key (int,sc,in) - item to be returned c 1=keyerr, 2=errfil, 3=numnot, 4=numwrn, c 5=numerr, 6=numfat, 7=maxmsg, 8=lvlerr c 9=mxpcmd,10=nercmd,11=nertim,12=nomore c 13=eropen, 14=ikserr, 15=kystat, 16=mxr4r5 c 17=mshkey, 19=opterr, 20=flowrn c 21=errhpi c c ---- below definitions copied from errcom 7/92 for user information c c *** key number= .......................... c (see ansysdef for parameter definitions) | c \/ c co keyerr - master error flag (ER_ERRORFLAG) co errfil - errors file unit number (ER_ERRORFILE) co numnot - total number of notes displayed (ER_NUMNOTE) co numwrn - total number of warnings displayed (ER_NUMWARNING) co numerr - total number of errors displayed (ER_NUMERROR) co numfat - total number of fatals displayed (ER_NUMFATAL) co maxmsg - max allowed number of displayed messages before abort(ER_MAXMESSAGE) co lvlerr - used basicly in solution (from cnvr command.) (ER_ERRORLEVEL) co -1=do not set keyerr for notes/errors/warnings. co -2=same as -1 but do not display message either. co mxpcmd - maximum number of messages allowed per command (ER_MAXCOMMAND) co nercmd - number of messages displayed for any one command (ER_NUMCOMMAND) co nertim - key as to how message cleared from u/i pop-up (ER_UICLEAR) co (as per rsg/pft 5/1/92 - only for "info" calls co -1=message is timed before removal co 0=message needs pick or keyboard before removal co 1=message stays up untill replaced by another message

co nomore display any more messages (ER_NOMOREMSG) co 0=display messages co 1=display discontinue message and stop displaying co eropen - 0=errors file is closed (ER_FILEOPEN) co 1=errors file is opened co ikserr - 0=if interactive do not set keyerr (ER_INTERERROR) c - 1=if interactive set keyerr (used by mesher and tessalation) co kystat - flag to bypass keyopt tests in the elcxx routines (ER_KEYOPTTEST) c associated with status/panel info inquiries. c 0=do not bypass keyopt tests c 1=perform all keyopt tests co mxr4r5 - mixed rev4-rev5 input logic (*do,*if,*go,*if-go) (ER_MIXEDREV) c (used in chkmix called from rdmac) c 1=rev5 found (*do,*fi-then-*endif) c 2=rev4 found (*go,:xxx,*if,....,:xxx) c 3=warning printed. do not issue any more. co mshkey - cpu intensive meshing etc. this will cause (ER_MESHING) c "nertim (11)" to be set to -1 for "notes", 1 for "warnings", c and 0 for "errors". checking of this key is done in "anserr". c 0=not meshing or cpu intensive c 1=yes, meshing or cpu intensive co syerro - systop error code. read by anserr if set. (18) co opterr - 0=no error in main ansys during opt looping (ER_OPTLOOPING) c 1=an error has happened in main ansys during opt looping co flowrn - flag used by "floqa" as to list floqa.ans (20) c 0=list "floqa.ans" c 1="floqa.ans" has been listed. do not list again. co espare - spare integer variables c c --- end of information from errcom c c output arguments: c erinqr (int,sc,out) - value corresponding to key c #include "impcom.inc" c integer key, erinqr

3.2.4 TrackBegin Subroutine (Beginning Tracking for a Subroutine Call)

subroutine TrackBegin (sub16) c *****function: mark beginning of track ansys call c *** Notice - This file contains ANSYS Confidential information *** c c c c input arguments: sub16 (char*(*),sc,in)

- name of subroutine being entered and left (16 characters max)

output arguments:

none

3.2.5 TrackEnd Subroutine (Ending Tracking for a Subroutine Call)

subroutine TrackEnd (sub16) c *****function: mark end of track ansys call c *** Notice - This file contains ANSYS Confidential information *** c c c c input arguments: subname (char*(*),sc,in)

- name of subroutine being left (16 characters max)

output arguments:

none

3.2.6 erhandler Subroutine (Displaying ANSYS Errors)

subroutine erhandler (filein,msgid,msglvl,messg,dperr,cherr) c primary function: Display ANSYS error messages

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c c c c c c c c c c c c c typ=int,dp,log,chr,dcp input arguments: variable (typ,siz,intent) filein (ch*16,sc,in) siz=sc,ar(n) intent=in,out,inout

msgid

msglvl

messg

dperr

cherr

description - Filename used for character portion of message ID (this is the file name of the file which contains the source for this routine) (int,sc,in) - Numeric portion of the message ID 1 - 9999, unique for each erhandler call in the FILE. Recommend using a sequence, similar to format conventions, i.e., 3010, 3020, 3030 (int,sc,in) - level of error (same as anserr) 0=no label (used for u/i pop-ups) -1=no label (used for u/i pop-ups) timed as a note message 1=note, 2=warning, 3=error, 4=fatal (ch*256,sc,in) - error message to display. use keywords of %i %g %c %/ for formating (same as anserr) (dp,ar(*),in) - vector of data to display. contains both integer and double precision data. (same as anserr) (ch*(*),ar(*),in) - vector of character data to display max length of character data is 32 characters 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

3.2.8 tranx3 Subroutine (Processing Geometry for 3-D Line

Elements)
subroutine tranx3 (nnod,xyz,nx,tr) c *** primary function: geometric processor for 3-d line elements c with or without a 3rd node c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c nnod (int,sc,in) - number of nodes (2 or 3) c xyz (dp,ar(nx,*),in) - coordinates (x,y,z down) c nx (int,sc,in) - row dimension of xyz array c c output arguments: c tr (dp,ar(3,3),in) - transformation matrix c

3.2.9 systop Subroutine (Stopping an ANSYS Program Run)

subroutine systop (icode) c *** primary function: stop an ansys run c *** secondary functions: pass an error code to the system c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c icode (int,sc,in) - stop error code (0<icode<127) c 0 - normal exit c 1 - stack overflow error c 2 - stack level overflow c 3 - stack pop below zero c 4 - names do not match in stkpxp c 5 - command line argument error c 6 - accounting file error c 7 - auth file verification error c 8 - indicated error or end-of-run c 11 - error in user routine c 12 - macro stop command c 14 - untrapped xox error c 15 - anserr fatal error c 16 - possible full disk c 17 - possible corrupted or missing file c 18 - Error in VM routines (corrupt db?) c 21 - unauthorized code section entered c 25 - unable to open x11 server c 30 - quit signal c 31 - failure to get signal in max time c (syhold) c >32 - system dependent error c c output arguments: none

3.3 Vector Functions

3.3.1 vdot Function (Computing the Dot Product of Two Vectors)
function vdot (v1,v2,n) c *** primary function: compute dot product of vectors v1 and v2 c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: v1 (dp,ar(n),in) v2 (dp,ar(n),in) n (int,sc,in) output arguments: vdot (dp,sc,out)

- vector v1 - vector v2 - length of vectors v1 and v2

- dot product of v1 and v2

3.3.2 vsum Function (Summing Vector Components)

function vsum (va,n) c *** primary function: sum the components of a vector c *** Notice - This file contains ANSYS Confidential information *** c c c c c input arguments: va (dp,ar(n),in) n (int,sc,in) output arguments: vsum (dp,sc,out)

- vector va - length of vector va

- vector sum

3.3.3 vmax Function (Retrieving the Maximum Vector Value at a Given Location)
function vmax (v,n,locmax) c *** primary function: return the max value and location in a vector c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: v (dp,ar(n),in) n (int,sc,in) output arguments: locmax (int,sc,out) vmax (dp,sc,out)

- vector v - length of vector v

- location of max value in vector v - 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 c output arguments: lastv (dp,sc,out)

- the position of the last non-zero term

3.3.5 izero Function (Setting an Integer Vector to Zero)

function izero (ivect,n) c *** primary function: set an integer vector to zero c c input arguments: c v (int,ar(n),in) - vector V c n (int,sc,in) - the number of items in the vector

3.3.6 imove Function (Assigning Equal Values to Two Integer Vectors)

function imove (i1,i2,n) c *** primary function: move one vector to another vector c c input arguments: c i1 (int,ar(*),in) - vector i1 c n (int,sc,in) - length of vectors v1, v2 C c output arguments: v2 (int,ar(*),out) - vector v2

3.3.7 vzero Subroutine (Initializing a Vector to Zero)

subroutine vzero (v,n) c *** primary function: initialize a vector to zero c *** Notice - This file contains ANSYS Confidential information *** c c c c c input arguments: v (dp,ar(n),inout) n (int,sc,in) output arguments: v (dp,ar(n),inout)

- vector to zero out - number of words to zero out

- 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

3.3.9 vimove Subroutine (Moving One Vector into Another Incrementally)

subroutine vimove (v1,inc1,v2,inc2,n) c *** primary function: move one vector into another c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c v1 (dp,ar(inc1,n),in) - vector v1 c inc1 (int,sc,in) - increment on vector v1 c inc2 (int,sc,in) - increment on vector v2 c n (int,sc,in) - number of items to be moved c c output arguments: c v2 (dp,ar(inc2,n),in) - vector v2

3.3.10 vinit Subroutine (Assigning a Scalar Constant to a Vector)

subroutine vinit (v,n,const) c *** primary function: initialize a vector to a constant c *** Notice - This file contains ANSYS Confidential information *** c c c c c input arguments: n (int,sc,in) const (dp,sc,in) output arguments: v (dp,ar(n),out)

- length of vector v - constant to set vector v to

- vector v

3.3.11 viinit Subroutine (Assigning a Scalar Constant to a Vector Incrementally)

subroutine viinit (v,inc,n,const) c *** primary function: set the components of vector v to const by increments c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c inc (int,sc,in) - increment (first dimension) of vector v c n (int,sc,in) - length (second dimension) of vector v c const (dp,sc,in) - constant to set components of vector v to c c output arguments: c v (dp,ar(inc,n),out) - vector v

3.3.12 vapb Subroutine (Setting a Vector to Sum of Two Vectors)

subroutine vapb (a,b,c,n) c *** primary function: add vector a to vector b to get vector c c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: a (dp,ar(n),in) b (dp,ar(n),in) n (int,sc,in) output arguments: c (dp,ar(n),out)

- a vector - b vector - length of vectors a,b,c

- c vector

3.3.13 vapb1 Subroutine (Combining Two Vectors in One)

subroutine vapb1 (a,b,n) c *** primary function: add vector a to vector b and store in vector a c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: a (dp,ar(n),inout) b (dp,ar(n),in) n (int,sc,in) output arguments: a (dp,ar(n),inout)

- a vector - b vector - length of vectors a,b

- a vector

3.3.14 vapcb1 Subroutine (Multiplying a Vector to a Constant)

subroutine vapcb1 (a,b,n,const) c *** primary function: multiply vector b to constant, add to vector a, c and store in vector a

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c input arguments: a (dp,ar(n),inout) b (dp,ar(n),in) n (int,sc,in) const (dp,sc,in) output arguments: a (dp,ar(n),inout)

- vector a - vector b - length of vectors a,b - constant to multiply b

- vector a

3.3.15 vamb Subroutine (Gets a Third Vector by Subtracting One Vector from Another)
subroutine vamb (a,b,c,n) c *** primary function: subtract vector b from vector a to get vector c c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: a (dp,ar(n),in) b (dp,ar(n),in) n (int,sc,in) output arguments: c (dp,ar(n),out)

- vector a - vector b - length of vectors a,b,c

- vector c

3.3.16 vamb1 Subroutine (Subtracting One Vector from Another)

subroutine vamb1 (a,b,n) c *** primary function: subtract vector b from vector a and save in vector a c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: a (dp,ar(n),inout) b (dp,ar(n),in) n (int,sc,in) output arguments: a (dp,ar(n),inout)

- a vector - b vector - length of vectors a,b

- a vector

3.3.17 vmult Subroutine (Multiplying a Vector by a Constant)

subroutine vmult (v1,v2,n,const) c *** primary function: multiply a vector by a constant c *** Notice - This file contains ANSYS Confidential information ***

c c c c c c

input arguments: v1 (dp,ar(n),in) n (int,sc,in) const (dp,sc,in) output arguments: v2 (dp,ar(n),out)

- vector v1 - length of vectors v1, v2 - constant to multiply v1

- vector v2

3.3.18 vmult1 Subroutine (Multiplying a Vector by a Constant)

subroutine vmult1 (v1,n,const) c *** primary function: multiply a vector by a constant c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: v1 (dp,ar(n),inout) n (int,sc,in) const (dp,sc,in) output arguments: v1 (dp,ar(n),inout)

- vector v1 - length of vector n - constant to multiply v1

- vector v1

3.3.19 vcross Subroutine (Defining a Vector via a Cross Product)

subroutine vcross (a,b,c) c primary function: calculate c = a x b c *** Notice - This file contains ANSYS Confidential information *** c c c c c c typ=int,dp,log,chr,dcp input arguments: a (dp,ar(3),in) b (dp,ar(3),in) output arguments: c (dp,ar(3),out) siz=sc,ar(n) intent=in,out,inout

- first vector to be cross-multiplied - second vector to be cross-multiplied

- resulting vector

3.3.20 vnorme Subroutine (Normalizing a ThreeComponent Vector)

c c c c c subroutine vnorme (iel,v) primary function: normalize a vector to unit length this routine is to be called only from the elements. it is only for a three component vector(i.e. processing geometry). this routine also differs from vnorm in that an error message is called if the vector length is zero.

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c input arguments: iel (int,sc,inout) v (dp,ar(3),inout) output arguments: iel (int,sc,inout) v (dp,ar(3),inout)

- element number - vector to be normalized

- if 0, vector has zero length - normalized vector

3.3.21 vnorm Subroutine (Normalizing a Vector to Unit Length)

subroutine vnorm (v,n) c *** primary function: normalize a vector to unit length c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c v (dp,ar(n),inout) - vector v c n (int,sc,inout) - dimension length of vector v c c output arguments: c v (dp,ar(n),inout) - normalized vector v c n (int,sc,inout) - n = 0 if error in operation c

3.3.22 ndgxyz Function (Getting the X,Y,Z Vector for a Node)

function ndgxyz (node,xyz) c *** primary function: get x,y,z vector for a node. c *** secondary functions: set current node pointer to this node. c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c node (int,sc,in) - node number for operation. c c output arguments: c variable (typ,siz,intent) description c ndgxyz (int,sc,out) - status of node. c 0=node is undefined. c -1=node is unselected. c 1=node is selected. c xyz (dp,ar(3),out) - vector containing x,y,z

3.3.23 ndpxyz Subroutine (Storing X,Y,Z for a Node)

subroutine ndpxyz (node,xyz) c *** primary function: store x,y,z vector for a node. c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c node (int,sc,in) - node number for operation. c xyz (dp,ar(3),in) - vector containing x,y,z c (vector should be in global system) c c output arguments: c none.

3.4 Matrix Subroutines

3.4.1 maxv Subroutine (Multiplying a Vector by a Matrix)
subroutine maxv (a,v,w, nr,nc) c *** primary function: multiply a vector by a matrix c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c input arguments: a (dp,ar(nr,*),in) v (dp,ar(*),in) nr (int,sc,in) nc (int,sc,in) output arguments: w (dp,ar(*),out)

matrix vector number number

a v of rows in matrix a of columns to multiply in matrix a

- product vector w

3.4.2 maxv1 Subroutine (Multiplying a Vector by a Matrix)

subroutine maxv1 (a,v, nr,nc) c *** primary function: multiply a vector by a matrix c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c input arguments: a (dp,ar(nr,nc),in) - matrix a v (dp,ar(nc),inout) - vector v nr (int,sc,in) - number of rows in matrix a *** nr limited to 60 *** nc (int,sc,in) - number of columns to multiply in matrix a output arguments: v (dp,ar(nr),inout) - product, stored in vector v

3.4.3 matxv Subroutine (Multiplying a Vector by a Full Transposed Matrix)

subroutine matxv (a,v,w, nr,nc) c *** primary function: multiply vector by full transposed matrix c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c c input arguments: a (dp,ar(nr,*),in) v (dp,ar(nv),in) nr (int,sc,in)

nc

(int,sc,in)

- matrix a (first dimension must = nr) - vector v (nv must be greater or equal to nr) - first dimension and number of active rows of the untransposed matrix a (also the number of active rows of vector v) - number of columns of the untransposed matrix a (also the number of computed items in the product vector w) if negative, accumulate

output arguments: w (dp,ar(na,*),out)

- product vector w

3.4.4 matxv1 Subroutine (Multiplying a Vector by a Full Transposed Matrix)

subroutine matxv1 (a,v, nr,nc) c *** primary function: multiply vector by full transposed matrix c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c input arguments: a (dp,ar(nr,*),in) v (dp,ar(nr),inout) nr (int,sc,in) nc (int,sc,in)

matrix vector number number *** nc

a v of rows in matrix (un-transposed) of columns in matrix (un-transposed) limited to 60 ***

output arguments: v (dp,ar(nc),inout)

- product, stored in vector v

3.4.5 matxb Subroutine (Transposing a matrix)

subroutine matxb (a,b,c, na,nb,nc, n1,n2,n3) c *** primary function: (a)t * (b) = (c) t means transpose c *** Notice - This file contains ANSYS Confidential information *** c c c c c input arguments: a (dp,ar(na,*),in) b (dp,ar(nb,*),in) na (int,sc,in) nb (int,sc,in)

matrix matrix number number

a b of rows in matrix a of rows in matrix b

c c c c c c c c c

nc n1 n2 n3

(int,sc,in) (int,sc,in) (int,sc,in) (int,sc,in)

number of rows in matrix c number of rows in matrix c to fill number of columns in matrix c to fill number of columns in matrix a and number of rows of matrix b to work with (the two need to be the same for the inner product)

output arguments: c (dp,ar(nc,*),out)

- product matrix c

3.4.6 maat Subroutine (Changing a Matrix Value via Addition, Multiplication, and Transposition)
subroutine maat(a,c, nc,n, con) c primary function: does con*a*at and sums the result onto c (a is a vector) c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c typ=int,dp,log,chr,dcp input arguments: a (dp,ar(*),in) siz=sc,ar(n) intent=in,out,inout

c nc n con

- vector to be multiplied by itself to generate an nxn square matrix (a by a-transposed) (dp,ar(nc,*),inout) - matrix to be accumulated onto (int,sc,in) - number of rows in the c matrix (int,sc,in) - size of square matrix (dp,sc,in) - multiplier on above square matrix

output arguments: c (dp,ar(nc,*),inout) - matrix to be accumulated onto only the lower triangular matrix is done Note: this routine is usually followed by matsym, to do the complete matrix

3.4.7 matsym Subroutine (Filling the Lower Triangle from the Upper Triangle)
subroutine matsym (a,nd,n) c primary function: fill upper triangle from lower triangle c *** Notice - This file contains ANSYS Confidential information *** c c c c c c typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout

input arguments: a (dp,ar(nd,*),inout) - matrix to have copied to its nd (int,sc,in) - number of rows n (int,sc,in) - size of matrix

its lower triangular part upper triangular part of the a matrix to be processed

c c c

output arguments: a (dp,ar(nd,*),inout) - matrix that has its lower triangular part copied to its upper triangular part

3.4.8 mctac Subroutine (Transposing a symmetric matrix)

c subroutine mctac (a,na,c,nc,nold,nnew) **** function: do a = c(transpose) * a * c , where a is symmetric **

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c c c input arguments: a (dp,ar(na,na),inout) matrix to be pre and post multiplied (part operated on must be square(nold x nold) and symmetric) na (int,sc,in) first dimension of the a matrix c (dp,ar(nc,nnew),in) matrix to pre and post multiply a by (part used may be rectangular(nold x nnew)) nc (int,sc,in) first dimension of the c matrix nold (int,sc,in) size of part of 'A' matrix that is to be processed(input size). maximum = 64 nnew (int,sc,in) size of part of 'A' matrix that results from this operation(output size). maximum = 64 output arguments: a (dp,ar(na,na),inout) resulting matrix (still square(nnew x nnew) and symmetric).

3.4.9 tran Subroutine (Transposing a matrix)

subroutine tran (zs,tr,nz,ntr,nrow,irot) c primary function: perform tr-transpose * zs * tr ************ c c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout

input arguments: variable (typ,siz,intent) description zs (dp,ar(nz,nz),inout) - matrix to be transformed tr (dp,ar(ntr,ntr),in) - transformation matrix nz (int,sc,in) - dimensioned size of zs matrix ntr (int,sc,in) - dimensioned size of tr matrix nrow (int,sc,in) - number of rows of zs matrix to transform irot (int,sc,in) - block size to transform(size of tr matrix) output arguments: variable (typ,siz,intent) description zs (dp,ar(nz,nz),inout) - transformed matrix

3.4.10 symeqn Subroutine (Solving Simultaneous Linear Equations)

c c c c subroutine symeqn (a,nd,n,nc) primary function: solve a set of simultaneous linear equations secondary functions: invert a matrix this routine assumes that the matrix to be solved or inverted is positive definite

c *** Notice - This file contains ANSYS Confidential information *** c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c c typ=int,dp,log,chr,dcp siz=sc,ar(n) intent=in,out,inout

input arguments: variable (typ,siz,intent) description a (dp,ar(nd,*),inout) - matrix to be solved or inverted second dimension must be at least: n + abs(nc) nd (int,sc,in) - first dimension of the a matrix n (int,sc,in) - number of equations nc (int,sc,in) - number of additional columns. if nc = +n or -n, invert n x n matrix and put result in the n+1 to 2xn columns. if nc is 0 or negative, nc will be reset to n and then symeqn will set up identity matrix after the input matrix, where the result of the inversion will be put. if nc is positive and less than n, do a partial inversion. see example 1 below. output arguments: variable (typ,siz,intent) description a (dp,ar(nd,*),inout) - results or inverted matrix. starts in column n+1. note: original information is destroyed. example 1: Solve three simultaneous linear equations: call symeqn (a(1,1),3,3,1) calling routine has a dimensioned as a(3,4) each equation has its 3 coefficents in the first 3 columns, and the constant term is in the fourth column. solution is in fourth column. Invert a 3x3 matrix: call symeqn (a(1,1),3,3,-3) calling routine has a dimensioned as a(3,6) input matrix was input in first 3 columns output matrix in ouput in last 3 columns

example 2:

3.5 Message Processing Routines

3.5.1 msgdi Subroutine (Conditionally Printing Messages, Scalars, Vectors, or Matrices)

subroutine msgdi (msg,i) c *** primary function: write text & integer to output if 10th debug key c is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c i (int,sc,in) - integer to print c c output arguments: c none

3.5.2 msgdic Subroutine (Conditionally Printing Messages and an Integer Vector)

subroutine msgdic (msg,k,n,inc) c *** primary function: write text & integer vector (with incrementing) to c output if 10th debug key is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c k (int,ar,in) - integer vector to print c n (int,sc,in) - size of vector c inc (int,sc,in) - increment c

c c

output arguments: none

3.5.3 msgdim Subroutine (Conditionally Printing Messages and Matrices)

subroutine msgdim (msg,k,n,m) c *** primary function: write text & integer matrix to debug file if 10th debug c key is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c k (int,ar,in) - integer matrix to print c n (int,sc,in) - row size of vector c m (int,sc,in) - column size of vector c c output arguments: c none

3.5.4 msgdir Subroutine (Conditionally Printing Messages, Integers, and Reals)

subroutine msgdir (msg,i,r) c *** primary function: write text, integer & real to output if 10th debug key c is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description

c c c c c c

msg i r

(ch*256,sc,in) (int,sc,in) (dp,sc,in)

- message to print - integer to print - real to print

output arguments: none

3.5.5 msgdit Subroutine (Conditionally Printing Messages and a Transposed Integer Matrix)
subroutine msgdit (msg,k,n,m) c *** primary function: write text & transposed integer matrix to output if c 10th debug key is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c k (int,ar,in) - integer matrix to print c n (int,sc,in) - row size of vector c m (int,sc,in) - column size of vector c c output arguments: c none

3.5.6 msgdiv Subroutine (Conditionally Printing Messages and an Integer Vector)

subroutine msgdiv (msg,k,n) c *** primary function: write text & integer vector to output if 10th debug key c is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c

c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c k (int,ar,in) - integer vector to print c n (int,sc,in) - size of vector c c output arguments: c none

3.5.7 msgdr Subroutine (Conditionally Printing Messages and Reals)

subroutine msgdr (msg,r) c *** primary function: write text & real to output if 10th debug key c is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c r (dp,sc,in) - real to print c c output arguments: c none

3.5.8 msgdrc Subroutine (Conditionally Printing Messages and Real Vectors)

subroutine msgdrc (msg,r,n,inc) c *** primary function: write text & real vector (with increment) to output if c 10th debug key is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c

c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c r (dp,ar,in) - real vector to print c n (int,sc,in) - size of vector c inc (int,sc,in) - increment c c output arguments: c none

3.5.9 msgdrm Subroutine (Conditionally Printing Messages and Real Matrices)

subroutine msgdrm (msg,r,n,m) c *** primary function: write text & real matrix to output if 10th debug key c is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c r (dp,ar,in) - real matrix to print c n (int,sc,in) - row size of vector c m (int,sc,in) - column size of vector c c output arguments: c none

3.5.10 msgdrt Subroutine (Conditionally Printing Messages and Real Transposed Matrices)
subroutine msgdrt (msg,r,n,m) c *** primary function: write text & real transposed c debug key is greater than or c c At source development, you may wish conditionally c scalars, vectors or matrices to monitor the code. matrix to output if 10th equal to 3 to print-out messages, Once the program

c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c r (dp,ar,in) - real matrix to print c n (int,sc,in) - row size of vector c m (int,sc,in) - column size of vector c c output arguments: c none

3.5.11 msgdrv Subroutine (Conditionally Prints Messages and Real Vectors)

subroutine msgdrv (msg,r,n) c *** primary function: write text & real vector to output if 10th debug key c is greater than or equal to 3 c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c r (dp,ar,in) - real vector to print c n (int,sc,in) - size of vector c c output arguments: c none

3.5.12 msgdt Subroutine (Conditionally Prints Message Text)

subroutine msgdt (msg) c *** primary function: write text to output if 10th debug key

c is greater than or equal to 3 c c *** secondary function: set debug level c c At source development, you may wish conditionally to print-out messages, c scalars, vectors or matrices to monitor the code. Once the program c runs OK, there is no need for these print-outs. This feature can be achieved c with the programmers debug utilities. c c To invoke this utility insert the following line in ANSYS input deck: c c /DEBUG,,, ,,, ,,, ,3 c c *** Notice - This file contains ANSYS Confidential information *** c c input arguments: c variable (typ,siz,intent) description c msg (ch*256,sc,in) - message to print c c output arguments: c none

Go to the beginning of this chapter

Appendix A: External Commands

Go to the Previous Chapter Go to the Table of Contents for This Manual. Chapter 1 * Chapter 2 * Chapter 3 * Appendix A

A.1 Introduction to External Commands

New with ANSYS 5.4, you can add your own customized extensions to ANSYS without relinking the program. You can create custom routines in either C or FORTRAN, and access any of the ANSYS functions and subroutines listed in this manual, link these into shared libraries using the supplied utilities, and execute these routines via the "external command" feature within ANSYS. In addition, ANSYS provides special commands that list all available external commands and allow you to reset all currently referenced external commands. External command capability is available on the following UNIX platforms:
G G G G G

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).

A.2 Tasks in Creating an External Command

To create a functional external command, you'll need to complete the following general steps:
G G

Create compilable source code (either in C or FORTRAN). Create a shared library. This is facilitated by the gen_share utility and your system's make capability. 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 following sections detail each of these tasks.

A.2.1 Creating Compatible Code

You can create your functions using any of the user-programmable features, database access functions and subroutines, or file access functions provided by ANSYS. (While it is technically feasible to use USR1 through USRn and USER01 through USER10, it is not supported in this release and no examples are provided.) The following are two code segments that demonstrate, at a minimal level, how to create functions that can be used as an entry point into a custom coded shared library. The most important points in the following two examples are:
G G

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; ----------------------------- End Function Description -------------------*/ int extfnc(char* uecmd) { char *cmdsend = {"/COM, COMMAND SEND FROM extfnc"}; int intsend[80]; int i, ilen; for (i=0;i<80;i++) { intsend[i] = 32; } ilen = 0; for (i=0;(cmdsend[i] != '\0');i++) { intsend[i] = (int)cmdsend[i];

ilen++; } /* Echo back the given external command and its args */ writeoutc(uecmd,1); /* Send ANSYS a comment command */ icmdan_(&ilen,intsend); return(i); }

c------------------------------ Function Description ----------------------c newsub c integer function newsub(i1) c integer i1 c c Purpose: c Demonstrate FORTRAN API entry function for an external command. c c Parameters: c Input c ----------------------------c i1 Not used c Output c ----------------------------c c Return Value: c The return value is ignored by the calling function; c c ----------------------------- End Function Description -------------------c function newsub(i1) c #include "impcom.inc" #include "ansysdef.inc" c external wrinqr, ndinqr integer wrinqr, ndinqr c integer i1, nout, nnodes, newsub c c get output unit number nout = wrinqr(WR_OUTPUT) c c get number of currently defined nodes nnodes = ndinqr(0,DB_NUMDEFINED) c c put out message write (nout,1000) nnodes 1000 format(1x,'I am in newsub. There are ',i12,/, x 'nodes defined in this model.') c newsub = 0 return end

A.2.2 Creating a Shared Library

Once you have written the source code for your functions, you can create a Makefile (using the gen_share utility) to build a shared library. The utility creates the Makefile in the current directory. The Makefile incorporates all the interdependencies of the FORTRAN and C source files it encounters in that current directory. The gen_share utility is meant to setup the basic build. The user may need to make modifications to the Makefile depending on the situation. The gen_share utility has the following syntax: gen_share [-h] [-64] shared_object_name where -h Produces command help. -64 Configures the Makefile to use the -mips4option for IRIX64 6.1 and 6.2. shared_object_name The name that will be given to the shared library. 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.

A.2.3 Creating an External Table File

The external table file (ans_ext.tbl) can reside in any directory (but you must specify that directory in the ANSYS_EXTERNAL_TABLE environment variable). The file contains an entry for each shared library function you wish ANSYS to access. There is no limit to the number of entries. The file entries have the following format: /shared/library/path/library.so ~cm_name function_name 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: /home/mydir/mylibs/myobject.so ~myobj myobject_ 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 loads external commands in the following order:
G

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. setenv ANSYS_EXTERNAL_TABLE /home/mydir

A.2.5 Using External Commands

To call an external command, simply enter it as you would any other ANSYS command in the ANSYS command window. You can also call external commands through either an APDL macro or UIDL routine. Note-Avoid recursive external commands; that is, avoid situations where an external command calls another external command.

A.2.6 Checking External Command Status

You can check what shared libraries are currently accessible by entering the ~DEBUG command in the command input window. The following figure shows an example of ~DEBUG command output. External Command Mappings: Command Library Function Accessed? *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*~excmd /home/mydir/mycode/mycommand.so excmd YES

Note that the output lists the command, the related shared library, the function, and if the command has been accessed.

A.2.7 Resetting External Commands

You can
G G

Close all shared libraries Free memory associated with external commands

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.

A.2.8 Example External Command

The following example function can be built into a shared library on your system as a "hello, world" type of test. This example is shown in FORTRAN; however, you can use this as a template for a similar C function. The example exploits two of the functions available to programmers: wrinqr and ndinqr. The related external command will provide a listing of any defined nodes in the output window. subroutine newsub(i1) external wrinqr, ndinqr integer wrinqr, ndinqr integer i1, nout, nnodes c get output unit number nout = wrinqr(WR_OUTPUT) get number of currently defined nodes nnodes = ndinqr(0,DB_NUMDEFINED) put out message write (nout,1000) nnodes 1000 format(1x,'Now in newsub. There are ',i12,/, x 'nodes defined in this model.') return end

You can create a Makefile for this function by issuing the following command: % gen_share ecmd.so You can then build the shared library by issuing % 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: Now in newsub. There are nodes defined in this model. 1

*** NOTE *** CP= 4.950 TIME= 10:46:23 Command= ~ECMD was processed as an external command which is a non-standard use of the ANSYS program.

Go to the beginning of this chapter