MSC.Patran PCL Handbook
In a Nutshell
What is PCL?
What can PCL be used for?
How does PCL work?
All you really need to know is on this page!
Documentation
PCL for Everyone
Entering Equations
Entering Data
Session Files
Rebuilding Models
PCL for the More Adventurous
Parametric Modeling
Adding a Graphical User Interface, GUI
Exercise 1: Session Files
PCL Programming Basics
Overview
PCL Expressions
Expressions, Comments, Syntax Tips
Identifiers
Naming Conventions
Variable / Function Scope
Structure of a PCL Function
Function Basics
Simple PCL function Example
Exercise 2: Hello World!
Exercise 3: Effective PCL
PCL Operators
String comparisons
PCL Variables and Constants
Datatypes
Variable Scope
Directly Allocated Arrays
Virtual arrays
Virtual strings
Loop Control Statements
For Loop
While Loop
Repeat Loop
BREAK
CONTINUE
Exercise 4: Writing Files
Exercise 5: Reading Files
Conditional Control Statements
IF Statement
SWITCH Statement
Structure of a PCL Function
Compiling and Linking PCL Functions
Primary PCL Directives
Compiling PCL outside of MSC.Patran
Linking Compiled Libraries
Other PCL Directives
Start Up Files
Exercise 6: p3epilog.pcl
Debugging
Debugging Compile Errors
Debugging Runtime Errors
Accessing PCL Functions
From The Command Line
From Any MSC.Patran Form
PCL Functions with Field Variables
MSC.Patran Built-In Functions
Naming Conventions for Applications
Naming Conventions for Other Operations
Exercise 7: Group Elements By Shape
Graphical User Interface
The PCL Class Statement
PCL Widgets
Required Functions for Building/Displaying a Form
The init() Function
The display() Function
Widget Callbacks
What Are They?
What Are They Used For?
Callback Arguments (Widget Function Data)
Widget Placement
Widget Variables
Modifying Widgets
Getting Data from Widgets
Putting it all Together (Example)
Exercise 8: Simple Form
The C-Preprocessor and Include Files
Make Files
Exercise 9: Callbacks
Handling Errors and Messaging
Errors from Built-In Functions
Custom Error Messages
Using User Messages Database
Without a Messages Database
Taking Advantage of the UNDO Feature
Select Mechanism
Select Mechanism GUI Mechanics
Select Databoxes, Select Frames, and Select Menus
GUI PCL Example
List Processor
List Processor Mechanics
All You Really Need to Know
Exercise 10: Form to Group Elms By Shape
Executing Programs Outside of MSC.Patran
Spawning Remote Processes
Locking a database
Using C and Fortran executables to access a MSC.Patran database directly.
External Access of an MSC.Patran Database
Special Widgets
File Widget
Spreadsheet Widget
Exercise 11: File Widget
Adding Help/Description to your PCL
Percent Complete
Functions
Example
Event Manager
General
Functions
Example
Primitive Graphics
Graphic Objects
Graphic Segments
Example
Another Example
Exercise 12: Primitive Graphics
MSC.Patran Customization
Adding Utility Programs to the Main Menu
Example
Example: p3_user_menu.my_menu.def
Customizing the MSC.Patran Toolbar
Exercise 13: Pulldown Menu
Exercise 14: Toolbar
Some Final Thoughts
Appendix A
Built-in Function Examples
Documentation for a typical MSC.Patran built-in function.
To get all the nodes and their global coordinates
To get the topology of every element
To get the shape of every element
To get all the element connectivity for all elements
To get the elements associated to a particular element property set
To get an element property value (shell thickness) for a specific element
To get a material property value
To get a list of all groups
To get the nodes and elements associated to the current group
To get result values for specified elements
Appendix B
Strings & String Functions
Declaration
Initialization
String Comparisons
Functions
Appendix C
Noteworthy Functions
sys_move_raw(…)
mth_array_search(…)
mth_sort(…)
mth_sort_row(…)
mth_sort_column(…)
fem_geom_edge_length(…)
fem_geom_face_area(…)
fem_geom_elem_volume(…)
fem_geom_elem_location(…)
Appendix D
Form Spacing Parameters (appforms.p)
* SPACING
Appendix E
MSC.Patran Architecture
Appendix F
Shareware Compiling Functions
Appendix G
Parametric Patran
Appendix H
Additional List Processor Notes
List Processor Mechanics
List Processor Functions
List Processor Sublist Functions
List Processor Attribute Functions
Miscellaneous List Processor Functions
List Processor Examples
Easy to Use List Processor Functions
Appendix I
Key Mapping
Appendix J
Widget Classification
Appendix K
User Defined AOM
MSC.Patran PCL Workshop Notes01/11/19
1/237
In a Nutshell
What is PCL?
PCL stands for Patran Command Language
Comprehensive, fully functional computer programming language
Specifically and uniquely suited for MCAE applications
Delivered as a part of MSC.Patran
Versatile and easy to use
In a Nutshell
What can PCL be used for?
Integrate application or site-specific programs with the MSC.Patran user interface and database
Generate parametric/variational models for design/optimization
Integrate commercial and/or in-house analysis codes with MSC.Patran
Display custom graphics
Access the MSC.Patran database
Create new and/or enhanced MSC.Patran functionality
Database management for analysis files
Eliminate tedious, repetitive procedures
In a Nutshell
How does PCL work?
All MSC.Patran commands are first interpreted by the PCL command interpreter
PCL expressions are interpreted by a C program
PCL functions can be compiled into libraries (more efficient binary representation) and “linked” with a MSC.Patran session
“Built-in” PCL functions are written in C or FORTRAN
MSC.Patran forms and menus can be created via PCL calls to Xlib, the X-window function library
FORTRAN and C functions can be “linked” with MSC.Patran through PCL
In a Nutshell
All you really need to know is on this page!
Documentation
PCL and Customization - General programming guide for PCL. How to build forms, compile, manage libraries, access the database, read/write files, etc.
PCL Reference – Description of functions written to the session file.
Develop: The MSC.Patran Toolkit – Documentation of additional functions for database access, etc.
Programming Task / Documentation / CommentsBasic programming / PCL & Customization, chapters 2 & 3 / Math functions, string functions, file access functions, compiling, library management, etc.
Graphical user interface / PCL & Customization, chapter 5 / Functions for creating forms
List processor / PCL & Customization, chapter 5.5 / Functions for parsing a string or picklist, i.e., “Elm 1:9:2”
Applications, session file, result utilities / PCL Reference Guide / All functions written to the session file
Graphics / PCL & Customization, chapter 3.2 / Functions for drawing graphic primitives such as lines, arrows, text, etc.
Database functions / PCL & Customization, chapter 8 / Functions to access data in the database (i.e., node coordinates, element connectivity, element properties, etc.)
Architecture / PCL & Customization, chapters 6 & 7 / Functions for creating analysis preferences
PCL for Everyone
Entering Equations
Use of PCL when creating spatial fields:
‘X + ‘X**2 – sinr(‘X)
The PCL interpreter interprets anything immediately following a ‘ symbol as a field variable as opposed to a PCL function, such as, sinr().
PCL for Everyone
Entering Data
Use of PCL when entering geometric coordinates:
[ `5./16.` 0 0 ]
The PCL interpreter “evaluates” expressions enclosed in back tics, “`”.
Other examples:
[ `radius/length` 0 0 ]
< `cosr(theta)` 1 1 >
[ `MyFunction(radius)` 0 1 ]
PCL for Everyone
Session Files
Session and journal files are comprised entirely of PCL commands. Model changes (dimensions, mesh density, etc.) can be made quickly by editing and then replaying the session or journal files.
$# Session file patran.ses.01 started recording at 16-Aug-01 14:33:54
$# Recorded by: MSC.Patran 2001
STRING asm_create_patch_xy_created_ids[VIRTUAL]
asm_const_patch_xyz( "1", "<10 10 0>", "[0 0 0]", "Coord 0", @
asm_create_patch_xy_created_ids )
$# 1 Patch created: Patch 1
STRING sgm_edit_surface_add_h_edit_ids[VIRTUAL]
sgm_edit_surface_add_hole( 1, 1., TRUE, "", "[5 5 0]", "", "Surface 1", @
sgm_edit_surface_add_h_edit_ids )
$# 1 Surface Edited: Surface 1
$# Session file patran.ses.01 stopped recording at 16-Aug-01 14:34:52
PCL for Everyone
Rebuilding Models
The following session file creates a trimmed surface, 10” x10” with a 1” diameter hole at the center. Note that the parameter that controls the diameter of the hole is indicated below.
$# Session file patran.ses.01 started recording at 16-Aug-01 14:33:54
$# Recorded by: MSC.Patran 2001
STRING asm_create_patch_xy_created_ids[VIRTUAL]
asm_const_patch_xyz( "1", "<10 10 0>", "[0 0 0]", "Coord 0", @
asm_create_patch_xy_created_ids )
$# 1 Patch created: Patch 1
STRING sgm_edit_surface_add_h_edit_ids[VIRTUAL]
sgm_edit_surface_add_hole( 1, 1., TRUE, "", "[5 5 0]", "", "Surface 1", @
sgm_edit_surface_add_h_edit_ids )
$# 1 Surface Edited: Surface 1
$# Session file patran.ses.01 stopped recording at 16-Aug-01 14:34:52
PCL for Everyone
In the session file below, the previous session file is edited to change the hole diameter from 1” to 4”
$# Session file patran.ses.01 started recording at 16-Aug-01 14:33:54
$# Recorded by: MSC.Patran 2001
STRING asm_create_patch_xy_created_ids[VIRTUAL]
asm_const_patch_xyz( "1", "<10 10 0>", "[0 0 0]", "Coord 0", @
asm_create_patch_xy_created_ids )
$# 1 Patch created: Patch 1
STRING sgm_edit_surface_add_h_edit_ids[VIRTUAL]
sgm_edit_surface_add_hole( 1, 4., TRUE, "", "[5 5 0]", "", "Surface 1", @
sgm_edit_surface_add_h_edit_ids )
$# 1 Surface Edited: Surface 1
$# Session file patran.ses.01 stopped recording at 16-Aug-01 14:34:52
PCL for Everyone
Session files can be executed or “played” by selecting File/Session/Play … from the top menu.
PCL for the More Adventurous
Parametric Modeling
Session files can be parameterized by defining and using variables during the MSC.Patran session
First, variables are declared and initialized via the MSC.Patran command line
PCL for the more Adventurous
Second, the variables are used as input into the appropriate MSC.Patran forms (note the use of ` `, back tics)
PCL for the more Adventurous
Upon application, the PCL interpreter evaluates `radius` (i.e., sets it equal to 1.0 in this example) and creates the curve. Note that the variable is passed to the session file in its unevaluated form.
PCL for the more Adventurous
By using variables as parameters during MSC.Patran input, it is very easy to edit and change dimensions, mesh parameters, etc. in the session file.
PCL for the more Adventurous
Adding a Graphical User Interface, GUI
The next step might be to create a user interface to run the plate session file!
Exercise 1: Session Files
Use MSC.Patran to create a parameterized session file that creates a rectangular surface with an arbitrarily located hole.
1)Create variables for the dimensions shown below.
2)Steps:
a)Create variables using MSC.Patran’s command line
b)Create/Surface/XYZ (use variables length and width)
c)Edit/Surface/Add Hole (use x_center, y_center, and diameter)
Extra credit:Include error checking, i.e., it doesn’t make sense for the hole to be outside the surface boundary.
IF (x_center + diameter/2.0 > length) THEN RETURN
Extra credit:Include meshing, boundary conditions, element properties, etc.
Extra credit:Use ui_read_real(prompt) to enter the variable values interactively
Extra credit:Turn your session file into a PCL FUNCTION.
Exercise 1
Below is an image showing an MSC.Patran form allowing the interactive creation of the model for this exercise.
NB – See Appendix G for notes about Parametric Patran.
1)Variables and macros are defined interactively via a GUI
2)Variables and macros are persistent
3)Plus, more. See Appendix G for the details
PCL Programming Basics
Overview
PCL is a full-featured programming language.
Operators for arithmetic, relational, and string expressions. Examples include:
multiplication / *
string concatenation / //
logical or / ||
logical equal / ==
logical not equal / !=
Variables with type, scope, and dimension attributes
INTEGER i, j, status, NodeIds(1000)
LOGICALflag
REALxyz(1000, 3), pressure(100), time
GLOBAL STRINGmy_group[32], all_groups[32](100)
Dynamically allocated virtual strings and arrays
INTEGERnode_ids(VIRTUAL)
STRINGgroups[32](VIRTUAL), MyString[VIRTUAL]
Intrinsic functions for math, string manipulation, etc.
sinr(angle)
cosd(angle)
mth_abs(MyVal)
mth_sort(MyArray, CompactDuplicates, NumLeft)
mth_array_search(MyArray, Look4, Sorted)
str_length(MyString)
str_substr(MyString, Position, SubStringLength)
str_index(StringToSearchIn, StringToSearchFor)
str_token(MyString, Delimiter, TokenNumber, [Compress])
PCL Programming Basics
Loop control features, such as, WHILE, FOR, REPEAT, and LIST
Conditional control structure, such as, IF-THEN-ELSE and SWITCH-CASE
Subroutine (procedure) and function (command) calls
Class grouping of related functions
Read/write access to external ASCII and/or binary files
text_open(FileName, Options, 0, 0, FileId)
text_read_string(FileId, InString, InStringLength)
text_write_string(FileId, OutString)
text_read(FileId, Format, MyIntegers, MyReals, MyChar)
text_write(FileId, Format, MyIntegers, MyReals, MyChar)
text_close(FileId, Options)
file_exists(FileSpec, Options)
file_delete(FileSpec)
Access to MSC.Patran “built-in” functions that allow for direct access to the MSC.Patran database, geometry creation, drawing graphic primitives,
db_count_nodes(NumNodes)
db_get_node_ids(NumNodes, NodeIds)
asm_const_grid_xyz(output_ids, coordinates_list, coord_frame, @
created_ids)
PCL Expressions
Expressions, Comments, Syntax Tips
Sample PCL expressions include:
theta = 360.0 – MTH_ASIND(MyAngle)
IF (radius >= 20.0) THEN radius = 20.0
length = str_length(MyString)
build_gear_geometry(30., 56., 3)
PCL comments begin with a “/*” and end with a “*/”
/*
This is a comment.
Look Ma, I’m making comments in PCL!
Has anyone seen or heard from Elvis lately?
*/
a = 2 /* set mysterious factor equal to 2 */
Alternatively, single line comments may begin with “$”
$ Don’t you just hate to comment your programs?
More than one PCL expression can co-exist on a line using a semi-colon, “;”
alpha = 30.0; beta = 120.0
PCL expressions can be continued on subsequent lines by using the “@” symbol
ui_wid_set(main_form, @
“HEIGHT”, @
NewHeight)
ui_wid_set( /* widget_id */ main_form, @
/* parameter */ “HEIGHT”, @
/* value */ NewHeight)
PCL Expressions
Don’t break expressions in the middle of a keyword, constant, or identifier
Multiple blanks are the same as a single blank space
Lines beginning with “!” (bang operator) are echoed to the xterm (UNIX) or command window (NT), but are not executed
In MSC.Patran type: !`i` nodes created
In the xterm you see: %27 nodes created
PCL expressions beginning with “” are echoed to the session file
PCL expressions can be typed directly into MSC.Patran at the command line
PCL expressions may also be created with an editor in a text file and directed into MSC.Patran as a session file or by using the PCL directive !!INPUT
Identifiers
Naming Conventions
Function names and/or variable names are called identifiers
Can be up to 32 characters long
Must begin with a non-digit
Case insensitive (as is all of PCL)
Cannot be a reserved keyword, i.e., FOR, IF, etc.
Valid identifiers
current_group
CurrentGroup
MyString
Invalid identifiers
a_very_very_very_very_very_very_very_very_long_name
95abc
list
Identifiers
Variable / Function Scope
Global variable names and functions share the same name space
When two function names or two variable names conflict, the most recent addition supercedes the previous
When function names and variable names conflict, the variable name takes precedence
When compiling functions, PCL will indicate if a function name is superceded by writing “Cleared memory function” to the history window
Hint: Use a unique prefix to keep function definitions separate, i.e au_do_this_and_that.pcl
Structure of a PCL Function
Function Basics
PCL functions begin with a FUNCTION statement and end with an END FUNCTION statement.
The FUNCTION statement may contain an argument list to be passed in or out of the function.
An optional RETURN statement can be used to return a calculated value from the function to the calling statement.
Processing of the function terminates at either the END FUNCTION statement or a RETURN statement.
There may be multiple RETURN statements within a single function.
Structure of a PCL Function
Simple PCL function Example
Structure of a PCL Function
Another simple PCL function
another_simple_function(29)
$#My favorite number is 29
$#My least favorite number is 13
Exercise 2: Hello World!
Write and execute a PCL function that accepts a single real number argument and echoes
Hello World, my favorite number is ….
to the MSC.Patran session file and history window.
Your function will use either the ui_write(…),ui_writef(…), or ui_writec(…) functions.
If you use the ui_writef(…) and ui_writec(…) functions, refer to the documentation for the correct format specifiers.
Extra credit:How would this function change if you wanted to echo your favorite 10 numbers to the session file?
Extra credit:How would this function change if you wanted to echo your favorite color to the session file?
Exercise 3: Effective PCL
Write an essay on how the effective use of PCL could:
a)Help create a lasting world peace
b)Eliminate world hunger
c)Conquer the common cold
d)Stop global warming
Extra credit: How could PCL be used to find Elvis?
PCL Operators
Operators / Comments+ / - / ! / Unary plus, minus, logical not
** / Exponentiation
* / / / Multiplication and division
+ / - / Additions and subtraction
// / String concatenation
<= / >= / == / != / Relational operators
|| / Logical or, logical and
+= / -= / = / Increment, decrement, assignment
Examples
Dist = mth_sqrt((x2-x1)**2 + (y2-y1)**2 + (z2-z1)**2)
MyString3 = MyString2//”hijk”
IF (a == b) THEN c = d
IF (a == b & a == c) THEN ui_write(“Equilibrium”)
x += 1 (this is equivalent to x = x +1)
String comparisons
The string comparison operators are special in that they ignore trailing blanks and uppercase and lowercase. Therefore, all of the following expressions are TRUE
“ABC” == “ABC “
“ABC” == “abc”
Leading blanks are compared, i.e., “TEST” != “ TEST”
To perform case sensitive comparisons use the str_equal() function, i.e.,
IF (str_equal(GroupName1, GroupName2)) THEN RETURN 0
PCL Variables and Constants
Datatypes
LOGICALBoolean value: TRUE or FALSE
LOGICAL done, created
INTEGERValue between +/- (231-1)
INTEGER i, num_nodes, node_id
REALSingle precision floating value between 1.0E-30 and 1.0E+30 (positive or negative)
REAL x, y, z, force, pressure
STRINGCharacter string surrounded by double quotes, “Have you seen Elvis?”. Size or string length is defined with brackets, [ ]
STRING FileName[80], GroupName[32]
WIDGETValue is assigned by calls toUI_WIDGET_NAME_CREATE(…), used to create and manipulate forms, etc.
WIDGET main_form, MyButton, group_lbox
PCL Variables and Constants
Variable Scope
GLOBALAvailable to all functions during the MSC.Patran session
LOCALDefault, only visible within the defining function
STATICSame as LOCAL, but retains its value between calls
CLASSWIDEAvailable to all functions in the CLASS and retains its value during the MSC.Patran session
PCL Variables and Constants
Directly Allocated Arrays
Directly allocated arrays can have any number of subscripts (dimensions), defined within parentheses ()
Assigned upper and lower bounds, ArrayName(Lower:Upper)
INTEGER MyArray(2:10)
Default lower bound is 1 (not 0)
Available for all datatypes
Row major (unlike Fortran which is column major)
INTEGER MyArray(2, 3) = 1, 2, 3, 4, 5, 6