MSC.Patran PCL Handbook: An Introduction to Programming with PCL

MSC.
Patran PCL Handbook
FUNCTION init()
WIDGET id
INTEGER i, status
REAL x_loc, y_loc, form_width, form_height

REAL frame_width
REAL f_width, half_space
STRING version[3]
STRING method_opt[NAME_LENGTH], method[NAME_LENGTH]
form_width = FORM_WID_SML
frame_width = form_width - FORM_L_MARGIN - FORM_R_MARGIN
f_width = frame_width - FRAME_L_MARGIN - @
FRAME_R_MARGIN - FRAME_2EDGE
half_space = INTER_WIDGET_SPACE/2.0
settings.pcl
p3prolog.pcl
p3midilog.pcl
p3epilog.pcl
.Patran.EventMaps
In a Nutshell...................................................................................................................................6
What is PCL?........................................................................................................................................................ 6
What can PCL be used for?................................................................................................................................ 7
How does PCL work?.......................................................................................................................................... 8
All you really need to know is on this page!...................................................................................................... 9
Documentation......................................................................................................................................................................9
PCL for Everyone........................................................................................................................10

Entering Equations............................................................................................................................................ 10
Entering Data...................................................................................................................................................... 11
Session Files...................................................................................................................................................... 12
Rebuilding Models............................................................................................................................................. 13
PCL for the More Adventurous..................................................................................................16

Parametric Modeling.......................................................................................................................................... 16
Adding a Graphical User Interface, GUI........................................................................................................... 20
Exercise 1: Session Files...........................................................................................................21
PCL Programming Basics..........................................................................................................23

Overview............................................................................................................................................................. 23
PCL Expressions........................................................................................................................25
Expressions, Comments, Syntax Tips............................................................................................................. 25
Identifiers.....................................................................................................................................27
Naming Conventions......................................................................................................................................... 27
Variable / Function Scope................................................................................................................................. 28
Structure of a PCL Function......................................................................................................29

Function Basics................................................................................................................................................. 29
Simple PCL function Example.......................................................................................................................... 30
Exercise 2: Hello World!.............................................................................................................32
Exercise 3: Effective PCL...........................................................................................................33
PCL Operators.............................................................................................................................34
String comparisons........................................................................................................................................... 34
PCL Variables and Constants....................................................................................................35

Datatypes............................................................................................................................................................ 35
Variable Scope................................................................................................................................................... 36
Directly Allocated Arrays................................................................................................................................... 37
Virtual arrays...................................................................................................................................................... 38
Virtual strings..................................................................................................................................................... 40
Loop Control Statements...........................................................................................................41

MSC.Patran PCL Workshop Notes 05/05/17
2/252
For Loop............................................................................................................................................................. 41
While Loop.......................................................................................................................................................... 41
Repeat Loop....................................................................................................................................................... 42
BREAK................................................................................................................................................................ 43
CONTINUE.......................................................................................................................................................... 44
Exercise 4: Writing Files............................................................................................................45
Exercise 5: Reading Files..........................................................................................................47
Conditional Control Statements................................................................................................48

IF Statement....................................................................................................................................................... 48
SWITCH Statement............................................................................................................................................ 49
Structure of a PCL Function......................................................................................................50
Compiling and Linking PCL Functions....................................................................................53

Primary PCL Directives..................................................................................................................................... 54
Compiling PCL outside of MSC.Patran............................................................................................................ 58
Linking Compiled Libraries............................................................................................................................... 59
Other PCL Directives......................................................................................................................................... 60
Start Up Files...................................................................................................................................................... 61
Exercise 6: p3epilog.pcl.............................................................................................................62
Debugging...................................................................................................................................63
Debugging Compile Errors............................................................................................................................... 63
Debugging Runtime Errors............................................................................................................................... 64
Accessing PCL Functions.........................................................................................................66

From The Command Line.................................................................................................................................. 66
From Any MSC.Patran Form............................................................................................................................. 67
PCL Functions with Field Variables.................................................................................................................. 68
MSC.Patran Built-In Functions..................................................................................................69

Naming Conventions for Applications............................................................................................................. 70
Naming Conventions for Other Operations..................................................................................................... 71
Exercise 7: Group Elements By Shape....................................................................................73
Graphical User Interface............................................................................................................74

The PCL Class Statement.................................................................................................................................. 75
PCL Widgets....................................................................................................................................................... 76
Required Functions for Building/Displaying a Form......................................................................................77
The init() Function.........................................................................................................................................................77
The display() Function...............................................................................................................................................78
Widget Callbacks............................................................................................................................................... 81
What Are They?..................................................................................................................................................................81
What Are They Used For?..................................................................................................................................................82

3/252
Callback Arguments (Widget Function Data).....................................................................................................................82
Widget Placement.............................................................................................................................................. 84
Widget Variables................................................................................................................................................ 86
Modifying Widgets............................................................................................................................................. 87
Getting Data from Widgets................................................................................................................................ 88
Putting it all Together (Example)...................................................................................................................... 89
Exercise 8: Simple Form............................................................................................................91
The C-Preprocessor and Include Files.....................................................................................92

Make Files........................................................................................................................................................... 93
Exercise 9: Callbacks.................................................................................................................95
Handling Errors and Messaging...............................................................................................97

Errors from Built-In Functions.......................................................................................................................... 97
Custom Error Messages.................................................................................................................................... 98
Using User Messages Database..........................................................................................................................................98
Without a Messages Database............................................................................................................................................99
Taking Advantage of the UNDO Feature........................................................................................................ 101
Select Mechanism.....................................................................................................................102
Select Mechanism GUI Mechanics................................................................................................................. 102
Select Databoxes, Select Frames, and Select Menus........................................................................................................102
GUI PCL Example............................................................................................................................................................104
List Processor.................................................................................................................................................. 105
List Processor Mechanics.................................................................................................................................................105
All You Really Need to Know..........................................................................................................................................106
Exercise 10: Form to Group Elms By Shape.........................................................................109
Executing Programs Outside of MSC.Patran.........................................................................111

Spawning Remote Processes......................................................................................................................... 111
Locking a database.......................................................................................................................................... 113
Using C and Fortran executables to access a MSC.Patran database directly............................................114
External Access of an MSC.Patran Database................................................................................................ 115
Special Widgets.........................................................................................................................117
File Widget........................................................................................................................................................ 117
Spreadsheet Widget......................................................................................................................................... 120
Exercise 11: File Widget...........................................................................................................121
Adding Help/Description to your PCL....................................................................................122
Percent Complete.....................................................................................................................123
Functions.......................................................................................................................................................... 123
Example............................................................................................................................................................ 123
Event Manager..........................................................................................................................124
4/252
General............................................................................................................................................................. 124
Functions.......................................................................................................................................................... 125
Example............................................................................................................................................................ 125
Primitive Graphics....................................................................................................................126
Graphic Objects............................................................................................................................................... 126
Graphic Segments........................................................................................................................................... 127
Example............................................................................................................................................................ 128
Another Example............................................................................................................................................. 129
Exercise 12: Primitive Graphics..............................................................................................130
MSC.Patran Customization......................................................................................................131
Adding Utility Programs to the Main Menu.................................................................................................... 131
Example............................................................................................................................................................................132
Example: p3_user_menu.my_menu.def...........................................................................................................................133
Customizing the MSC.Patran Toolbar............................................................................................................ 134
Exercise 13: Pulldown Menu...................................................................................................137
Exercise 14: Toolbar.................................................................................................................138
Some Final Thoughts...............................................................................................................140
Appendix A................................................................................................................................143
Built-in Function Examples............................................................................................................................. 143
Documentation for a typical MSC.Patran built-in function...........................................................................144
To get all the nodes and their global coordinates.........................................................................................145
To get the topology of every element............................................................................................................. 146
To get the shape of every element.................................................................................................................. 147
To get all the element connectivity for all elements......................................................................................148
To get the elements associated to a particular element property set.........................................................149
To get an element property value (shell thickness) for a specific element.................................................150
To get a material property value..................................................................................................................... 152
To get a list of all groups................................................................................................................................. 153
To get the nodes and elements associated to the current group................................................................153
To get result values for specified elements................................................................................................... 154
Appendix B................................................................................................................................163
Strings & String Functions.............................................................................................................................. 163
Declaration....................................................................................................................................................... 164
Initialization...................................................................................................................................................... 164
String Comparisons......................................................................................................................................... 164
Functions.......................................................................................................................................................... 165
Appendix C................................................................................................................................173
Noteworthy Functions..................................................................................................................................... 173
sys_move_raw()........................................................................................................................................... 174
mth_array_search()...................................................................................................................................... 175
mth_sort()...................................................................................................................................................... 176
mth_sort_row()............................................................................................................................................. 177
mth_sort_column()....................................................................................................................................... 177

5/252
fem_geom_edge_length()............................................................................................................................ 178
fem_geom_face_area()................................................................................................................................. 178
fem_geom_elem_volume().......................................................................................................................... 178
fem_geom_elem_location()......................................................................................................................... 179
Appendix D................................................................................................................................180
Form Spacing Parameters (appforms.p)........................................................................................................ 180
* SPACING.................................................................................................................................................. 181
Appendix E................................................................................................................................206
MSC.Patran Architecture................................................................................................................................. 206
Appendix F................................................................................................................................208
Shareware Compiling Functions.................................................................................................................... 208
Appendix G................................................................................................................................211
Parametric Patran............................................................................................................................................ 211
Appendix H................................................................................................................................217
Additional List Processor Notes..................................................................................................................... 217
List Processor Mechanics.................................................................................................................................................218
List Processor Functions...................................................................................................................................................219
List Processor Sublist Functions.......................................................................................................................................220
List Processor Attribute Functions...................................................................................................................................221
Miscellaneous List Processor Functions...........................................................................................................................222
List Processor Examples...................................................................................................................................................223
Easy to Use List Processor Functions...............................................................................................................................227
Appendix I..................................................................................................................................228
Key Mapping..................................................................................................................................................... 228
Appendix J.................................................................................................................................231
Widget Classification....................................................................................................................................... 231
Appendix K................................................................................................................................234
User Defined AOM............................................................................................................................................ 234

6/252
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

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

8/252
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
You
MSC.Patran
PCL
C, C++ Fortran Other

9/252
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 Comments

Basic programming PCL & Customization, chapters 2 Math functions, string
&3 functions, file access
functions, compiling, library
management, etc.
Graphical user interface PCL & Customization, chapter 5 Functions for creating forms
List processor PCL & Customization, chapter Functions for parsing a string
5.5 or picklist, i.e., Elm 1:9:2
Applications, session file, PCL Reference Guide All functions written to the
result utilities session file
Graphics PCL & Customization, chapter Functions for drawing graphic
3.2 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 Functions for creating analysis
&7 preferences

10/252
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().

11/252
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 ]

12/252
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

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

A.
B. $# 1 Patch created: Patch 1
A. Create/Surface/XYZ
B. Edit/Surface/Add Hole

14/252
PCL for Everyone
In the session file below, the previous session file is edited to

change the hole diameter from 1 to 4


15/252
PCL for Everyone
Session files can be executed or played by selecting

File/Session/Play from the top menu.
If Single Step is selected, each command in the session file is written

to the MSC.Patran command line. You must hit the enter key to execute
the command. If it is not selected, then all of the PCL commands in the
session file are executed automatically.
If Commit Commands is selected, then each command in the session

file being executed is also written to the session file which is currently
being recorded. Otherwise, only the sf_play() command is written to
the session file being recorded.

16/252
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
The variable radius declared as

a REAL number
The variable radius is initialized to 1

17/252
PCL for the more Adventurous
Second, the variables are used as input into the appropriate

MSC.Patran forms (note the use of ` `, back tics)

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

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

REAL radius
radius = 1.0
sgm_edit_surface_add_hole( 1, `radius` , TRUE, "", "[5 5 0]", @
"", "Surface 1", sgm_edit_surface_add_h_edit_ids )

20/252
Adding a Graphical User Interface, GUI
The next step might be to create a user interface to run the

plate session file!
#include appforms.p
CLASS plate_hole
/* classwide variables */
CLASSWIDE WIDGET main_form, description_btn, radius_dbox
CLASSWIDE WIDGET sep1, apply_btn, cancel_btn
FUNCTION init()
REAL x_loc, y_loc
main_form = ui_form_create( @
/* callback */ , @
/* x location */ FORM_X_LOC, @
/* y location */ FORM_Y_LOC, @
...
END FUNCTION /* init */
FUNCTION display()
ui_form_display(plate_hole)
Hitting the*/Apply button executes the function: apply_button_cb()

END FUNCTION /* display
FUNCTION apply_button_cb()
GLOBAL REAL radius
ui_wid_get(radius_dbox, VALUE, radius)
sf_play(plate_hole.ses)
END FUNCTION /* apply_button_cb */
END CLASS /* plate_hole */

21/252
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.Patrans 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 doesnt 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.
22/252
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

23/252
PCL Programming Basics
Overview
PCL is a full-featured programming language.

Operators for arithmetic, relational, and string expressions.
Examples include:
addition +
multiplication *
string concatenation //
logical or ||
logical equal ==
logical not equal !=
Variables with type, scope, and dimension attributes

INTEGER i, j, status, NodeIds(1000)
LOGICAL flag
REAL xyz(1000, 3), pressure(100), time
GLOBAL STRING my_group[32], all_groups[32](100)
Dynamically allocated virtual strings and arrays

INTEGER node_ids(VIRTUAL)
STRING groups[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])

24/252
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)

25/252
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, Im 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 $

$ Dont 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)

26/252
PCL Expressions
Dont 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: !ì` 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

27/252
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

28/252
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

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

30/252
Simple PCL function Example
Function declaration Function arguments (null)
FUNCTION a_very_simple_function()
/* This is a simple function that writes: Comments (Who we

$# My favorite number is 29 kidding? We all know
in the MSC.Patran history window using 3 different that everyone loathes
write or print statements. commenting their
code!)
*/
/* This is a comment. */
$ This is also a comment.
Variable declaration
INTEGER MyFavoriteNumber
MyFavoriteNumber = 29 Variable initialization
ui_writec(My favorite number is %d \n, MyFavoriteNumber)
ui_writef(A21,1X,I3, My favorite number is, MyFavoriteNumber)
ui_write(My favorite number is //STR_FROM_INTEGER(MyFavoriteNumber))
END FUNCTION /* a_very_simple_function */

Statements or
expressions
Function terminator

31/252
Sample output. The ui_write functions write

text to the history window, the session file
(patran.ses.##), and the journal file
(model.db.jou)
Calling statement
Another simple PCL function
Note all variables must be

Calling statement
another_simple_function(29) Function argument
declared, including function
arguments
FUNCTION another_simple_function(MyFavoriteNumber)
INTEGER MyFavoriteNumber
INTEGER MyLeastFavoriteNumber
MyLeastFavoriteNumber = 13
ui_write(My favorite number is //str_from_integer(MyFavoriteNumber))
ui_write(My least favorite number is // @
str_from_integer(MyLeastFavoriteNumber))
END FUNCTION /* another_simple_function */
$#My favorite number is 29

Sample output
$#My least favorite number is 13

32/252
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?

33/252
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?

34/252
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

35/252
PCL Variables and Constants
Datatypes
LOGICAL Boolean value: TRUE or FALSE
LOGICAL done, created
INTEGER Value between +/- (231-1)
INTEGER i, num_nodes, node_id
REAL Single precision floating value between 1.0E-30 and

1.0E+30 (positive or negative)
REAL x, y, z, force, pressure
STRING Character string surrounded by double quotes,

Have you seen Elvis?. Size or string length is defined with
brackets, [ ]
STRING FileName[80], GroupName[32]
WIDGET Value is assigned by calls to

UI_WIDGET_NAME_CREATE(), used to create and manipulate
forms, etc.
WIDGET main_form, MyButton, group_lbox

36/252
Variable Scope
GLOBAL Available to all functions during the MSC.Patran

session
LOCAL Default, only visible within the defining function
STATIC Same as LOCAL, but retains its value between
calls
CLASSWIDE Available to all functions in the CLASS and
retains its value during the MSC.Patran session
GLOBAL REAL a, b, c
FUNCTION FindElvis() FUNCTION WheresWaldo(x)

GLOBAL REAL b GLOBAL REAL a
STATIC INTEGER c REAL c, d, e
INTEGER x
CLASS training
CLASSWIDE REAL d, e
FUNCTION MyFunc(q, r) FUNCTION init()

INTEGER f INTEGER c, f, g
GLOBAL REAL a, b, c
REAL q, r
If you are going to change the value of a

Note that variables passed as global variable within a function, you must
arguments must be declared declare the global variable within your
function.

37/252
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)
1 2 3
INTEGER MyArray(2, 3) = 1, 2, 3, 4, 5, 6 4 5 6
Array dimensions are inherited from the argument list, i.e., PCL
passes by reference
FUNCTION MyFunc()
STRING MyString[32](32)
FUNCTION YourFunc(MyVal)
YourFunc(MyString)
STRING MyVal[]()
END FUNCTION
END FUNCTION
Declaration Examples
REAL displacements(6, 200)

STRING group_names[32](20)
INTEGER ids(0:2, 0:4, 0:10)
LOGICAL exists(12)

38/252
Virtual arrays
Any variable can be defined as a VIRTUAL array instead of a

directly allocated array. Virtual arrays do not have storage
locations assigned to them at program initialization. The size
and amount of storage is allocated as requested and can be
reused for other virtual arrays.
To declare a virtual array, use the keyword VIRTUAL in place of
the subscripts for the declaration, i.e.,
REAL MyVals(VIRTUAL)
INTEGER NodeIds(VIRTUAL)
Storage is allocated using the function, sys_allocate_array(), or

sys_allocate_array(MyVals, 1, 300)
sys_allocate_array(MyVals, 1, 300, 1, 3)
sys_allocate_array(MyVals, 1, 300, 1, 3, 0, 5)
etc.
Storage may be reallocated using the function,

sys_reallocate_array(),
sys_reallocate_array(MyVals, 1, 300, 1, 3)
Storage may be freed using the function, sys_free_array(),

sys_free_array(MyVals)

39/252
Virtual array example

FUNCTION CompareNodes(num_nodes, node_ids)
INTEGER i, j, status
INTEGER num_nodes, node_ids()
INTEGER num_db_nodes, db_node_ids(VIRTUAL)
LOGICAL found_node
$ Determine the total number of nodes in the database

status = db_count_nodes(num_db_nodes)
IF (status != 0) THEN RETURN status
/* If no nodes in the db, then dont compare */

IF (num_db_nodes == 0) THEN RETURN 1
$ Allocate array to hold the Ids of all nodes in the db

status = sys_allocate_array(db_node_ids, 1, num_db_nodes)
$ Get all of the nodes in the db

status = db_get_node_ids(num_db_nodes, db_node_ids)
$ Compare node_ids() to node Ids in the database, db_node_ids()

$ Note: This is an inefficient way to compare nodes
FOR (i = 1 to num_nodes)
found_node = FALSE
FOR (j = 1 to num_db_nodes)
IF (node_ids(i) == db_node_ids(j)) THEN
found_node = TRUE
BREAK
END IF
END FOR
IF (!found_node) THEN
ui_write(Node //str_from_integer(node_ids(i))// not found!)
END IF
END FOR
RETURN 0
END FUNCTION /* CompareNodes */

40/252
Virtual strings
Any string variable can be defined as a VIRTUAL length string

instead of a fixed length string. Virtual length strings do not
have storage locations assigned to them at program
initialization. The string length is allocated as requested and
can be reused.
To declare a virtual length string, use the keyword in place of
the subscripts for the declaration, i.e.,
STRING picklist[VIRTUAL]
The string length is allocated using the sys_allocate_string()

function
sys_allocate_string(picklist, 1000)
The string length may be modified using the

sys_reallocate_string() function
sys_reallocate_string(picklist, 2000)
The string storage may be freed using the sys_free_string()

function
sys_free_string(picklist)
A virtual length string can also be a virtual array, i.e.,

STRING picklists[VIRTUAL](VIRTUAL)

41/252
Loop Control Statements
For Loop
Syntax
FOR (var=numeric_expr TO numeric_expr [BY numeric_expr]) [label]
statements
END FOR
Example Square braces [ ], denotes optional
AvgTemp = 0.0
FOR (i = 1 TO NumNodes)
AvgTemp += NodalTemp(i)
END FOR
AvgTemp = AvgTemp/NumNodes
While Loop
Syntax
WHILE (logical_expression) [label]
statements
END WHILE
Example
AvgTemp = 0.0
i = 1
WHILE (i <= NumNodes)
i += 1
END WHILE

42/252
Repeat Loop
This is similar to a WHILE Loop except that it will always be

executed at least once. Only use REPEAT loops if you want to
ALWAYS execute the loop at least once, otherwise us a WHILE
loop.
Syntax
REPEAT [label]
statements
UNTIL (logical_expression)
Example
AvgTemp = 0.0
i = 1
REPEAT
i += 1
UNTIL (i > NumNodes)

43/252
BREAK
The BREAK statement is used to exit a loop prior to its normal

termination. It can be used in any of the loop statements.
Syntax If status is not equal to
zero, then the end of
the file has been
BREAK [label] reached. Execution
then breaks out of the
Example 1(reading a text file) WHILE loop to the
statements
immediately following
WHILE (TRUE)
the loop.
status = text_read_string()
IF (status != 0) THEN BREAK
END WHILE
statements

Example 2 (nested loops, using labels)
WHILE (i <= NumNodes) MainLoop
WHILE (j <= 100) AnotherLoop
WHILE (k <= 200) InnerLoop
IF (status != 0) THEN BREAK MainLoop

IF (status != 0) THEN BREAK AnotherLoop
IF (status != 0) THEN BREAK
IF (status != 0) THEN BREAK InnerLoop
END WHILE
statements
END WHILE
statements
END WHILE
statements

44/252
CONTINUE
The CONTINUE statement is used to skip to the end of the loop
Syntax
CONTINUE [label]
Example 1 (reading a text file)

INTEGER file_id, length
STRING read_str[80]
/* read grid information */

WHILE (text_read_string(file_id, read_str, length) == 0)
IF (str_index(read_str, GRID) == 0) THEN CONTINUE
statements
END WHILE
Example 2 (nested loop, using labels)

WHILE (i <= NumNodes) MainLoop
REPEAT InnerLoop
CONTINUE MainLoop
BREAK InnerLoop
CONTINUE
CONTINUE InnerLoop
UNTIL (j > 1000)

statements
END WHILE
statements

45/252
Exercise 4: Writing Files
Create a PCL function to write nodal data to a user-defined file.

1) The function should have a single argument, the filename to be
created, i.e., FUNCTION write_nodes_to_file(FileName)
2) The data should be written to the file as a table, i.e.,
Node Id x-coordinate y-coordinate z-coordinate
3) Use virtual arrays

4) Use the following built-in functions:
db_get_nodes(NumNodes, NodeIds, rcids, acids, NodeXYZ)
text_open(FileName, Options, idum, idum, FileId)
text_write(FileId, Format, Ints, Reals, Chars)
text_write_string(FileId, OutString)
5) Use the documentation if you have questions about the

arguments to the built-in functions.
6) Think about your choice for the format argument in the
text_write() function. Will your file be comma or space
delimited? Will it be fixed or free format?
7) Sample code outline:
a) Declare variables
b) Count nodes in the database
c) Allocate arrays
d) Get node Ids
e) Get node coordinates
f) Open file
g) Write data to the file with a loop
h) Close file
i) Be sure to include a message that the file output is complete

46/252
Writing Files
Extra credit: Include a header line at the top of the file that
includes the filename and the total number of nodes
written to the file.

47/252
Exercise 5: Reading Files
Write a function to read the file created in Exercise 4.

1) The function should accept a single argument, i.e., the filename
to be read.
FUNCTION ReadFile(FileName)
2) Use the data in the file to create nodes with the following built-
in function from the PCL Reference Manual:
fem_create_nodes_1(RefCIDList, AnalysisCIDList, GeomFlag, @
NodeIDList, XYZList, NodesCreatedList)

text_open(FileName, Options, idum, idum, FileId)
text_read(FileId, Format, Ints, Reals, Chars)

b) Open the file
c) Read the file within a loop
d) Create new nodes as the file is read within the loop
e) Close the file
Extra credit: What if a node ID to be created already exists in the

database?
Extra credit: What if the file to be read doesnt exist? What
function can be used to determine if a file exists?
Extra credit: Searching the documentation reveals another
function that can be used to create nodes, i.e.,
db_create_nodes(num_nodes, rcids, acids, xyz, group_id,
node_ids, node_exists).Why might you use this
function versus fem_create_nodes_1()?
48/252
Conditional Control Statements
IF Statement
Syntax
IF (logical_expression) THEN
statements
ELSE IF (logical_expression) THEN
statements
ELSE
statements
END IF
Example
IF (MyKeyWord == CBAR || MyKeyWord == CBEAM) THEN
statements
ELSE IF (MyKeyWord == CTRIA || MyKeyWord == CQUAD) THEN
statements
ELSE IF (MyKeyWord == GRID) THEN
statements
ELSE
statements
END IF

49/252
Conditional Control Statements
SWITCH Statement
This is often used in place of an IF statement when many

comparisons will be made.
Syntax
SWITCH (expression) [label]

CASE (expression1, expression2, )
statements
CASE (expression3, expression 4, )
statements
DEFAULT
statements
END SWITCH
Example
Note that this SWITCH
SWITCH (EntityType) statement is equivalent to the
CASE (CBAR, CBEAM) IF statement on the previous
page.
statements
CASE (CTRIA, CQUAD)
statements
CASE (GRID)
statements
DEFAULT
statements
END SWITCH

50/252
Example 1 (subroutine or procedure example)
FUNCTION calling_function()
REAL Var1, Var2

Var1 = 5.0
still_another_function(Var1, Var2)
ui_write(Var2 = //STR_FROM_REAL(Var2))
END FUNCTION /* calling_subroutine */
Input argument (NumIn)
FUNCTION still_another_function(NumIn, NumOut)
REAL NumIn, NumOut

Output argument (NumOut)
NumOut = NumIn + 3.14
ui_write(NumIn = //STR_FROM_REAL(NumIn))
ui_write(NumOut = //STR_FROM_REAL(NumOut))
END FUNCTION /* still_another_function */
calling_function() Calling statement
$#NumIn = 5.0
$#NumOut = 8.14 Sample output
$#Var2 = 8.14

51/252
Example 2 (function or command example)
FUNCTION calling_subroutine2()
REAL MyVal Variable declaration

REAL a(3) = [1.0, 1.0, 2.0]
REAL b(3) Variable declaration
and initialization
b(1) = 2.0
b(2) = 2.0
b(3) = 1.0
MyVal = DotProduct(a, b)
ui_write(Dot product = //STR_FROM_REAL(MyVal))
END FUNCTION /* calling_subroutine2 */
All variables must be declared, including

function arguments. Note the use of dummy
FUNCTION DotProduct(a, b) parentheses to indicate that the argument is
an array. The array dimensions within the
function DotProduct is inherited (3 in this
REAL a(), b() case) from the array dimensions within the
REAL val calling function (calling_subroutine2 in
this case).
val = a(1)*b(1) + a(2)*b(2) + a(3)*b(3)
RETURN val
END FUNCTION /* DotProduct */
Calling statement
calling_subroutine2()
$#Dot product = 6.0 Sample output

52/252
Example 3. In this example, the PCL function acts both as a

procedure and a command. The result of the calculation is
returned as an argument for the function. The return value is
used to indicate if the function calculation was successful or
not. This methodology is very common in PCL functions
written by the MSC.Software development staff.
FUNCTION calling_subroutine3()
INTEGER status
REAL NumIn, NumOut
status = MySqrt(NumIn, NumOut)

IF (status == 0) THEN
ui_write(The square root of //STR_FROM_REAL(NumIn)// is //@
STR_FROM_REAL(NumOut))
ELSE
ui_write(STR_FROM_REAL(NumIn)// does not have a square root!)
END IF
RETURN status
END FUNCTION /* calling_subroutine3 */
FUNCTION MySqrt(NumIn, NumOut)
REAL NumIn, NumOut
IF (NumIn <= 0.0) THEN RETURN 1
NumOut = MTH_SQRT(NumIn)
RETURN 0
END FUNCTION /* MySqrt */

53/252
Day 2
Compiling and Linking PCL Functions
Compiling and linking is accomplished with PCL Directives.

Directives begin with !! and are processed immediately. In
addition to compiling, directives are used for debugging,
library management, etc.
PCL is an interpretive language (a.k.a., BASIC). Compiling PCL
functions is different than compiling C or FORTRAN. In PCL,
compiling simply reformats the data into a more efficient
binary form.
In C or FORTRAN, linking implies the process of linking your
functions with pre-built libraries of standard functions, i.e.,
externally referenced functions are resolved. This is not true
for PCL. For PCL, the term linking simply means that the
functions are available for use within the current MSC.Patran
session. No checking of any kind is performed.

54/252
Primary PCL Directives
!!INPUT redirects input to come from a specified file instead of

the keyboard.
Does not necessarily take place immediately. Only
when the heartbeat turns green.
!!INPUT filename
If the file contains PCL CLASS and FUNCTION statements,

these classes and functions are compiled and linked.
Functions compiled with !!INPUT only exist within memory
during the current MSC.Patran session. If you want to access
the functions in subsequent MSC.Patran sessions, you must
recompile (!!INPUT) these functions during the session.
Example usage
!!INPUT was typed at the command line
The file (test.pcl) contained a FUNCTION statement. Therefore, MSC.Patran compiled the statements
between the FUNCTION statement and the END FUNCTION statement.
$# Compiling: test Indicates that MSC.Patran is compiling the function, test

$# Compiled: test Indicates that the function, test, has been successfully compiled
Statements between Compiling/Compiled are compilation warnings. If the Compiled message is

not present then the statements following the Compiling message are compilation errors. If the
Compiled message is missing, then the PCL function did not compile and is not accessible.

55/252
!!COMPILE (!!COMP) Reads a file containing PCL classes

and/or functions and compiles these into a PCL library.
!!COMPILE filename [INTO] PCL_library_file
Typically, the filename will have a .pcl extension and the PCL
library file will have a .plb extension. If you do not specify a
library file, MSC.Patran will compile the filename into a library
file with the same name as the input file and a .plb extension.
Example usage

56/252
!!LIBRARY (!!LIB) directive links the PCL library with the

current MSC.Patran session. Linking simply means that the
functions in the library file are accessible from within
MSC.Patran. No checking is performed.
In addition to linking PCL libraries to the current MSC.Patran
session, the !!LIB directive is used for library management
functions.
!!LIB ADD file links file with the

current MSC.Patran session
!!LIB REMOVE file unlinks file from the
current MSC.Patran session
!!LIB MERGE source_file dest_file Merges functions from
source_file into dest_file
!!LIB DELETE file function [function] Deletes the specified
functions from the file
!!LIB LIST file Lists all functions in file
!!LIB Lists all PCL libraries
linked with the current
MSC.Patran session
Example usage

57/252
!!PATH Defines the order in which a set of directories is

searched to find files needed by PCL. In other words, this is
the path that MSC.Patran uses to search for PCL libraries and
other files. The current directory is always searched first.
Other directories to be searched are defined in the init.pcl
file. The format of the PATH directive is:
!!PATH [ADD] directory [directory ]
In addition to adding directories to the search path, the PATH
directive can also be used to:
!!PATH REMOVE directory [directory] Removes the specified directories
from the search path
!!PATH NONE Removes all directories from the
search path
!!PATH Lists all directories currently in the
search path
The last !!PATH statement is searched first. Within a !!PATH

statement, the directories are searched first to last.
!!PATH /abc /def /hij

!!PATH /klm
In this example, /klm would be searched for files first, /abc next,
/def next, and /hij last.
The !!PATH directive is typically included in either the
p3midilog.pcl or p3epilog.pcl files startup files.

58/252
Compiling PCL outside of MSC.Patran
PCL functions may be compiled into libraries outside of the

MSC.Patran environment using the MSC.Patran PCL compiler,
p3pclcomp. A sample session might look as follows:
Unix prompt% p3pclcomp
P3/PCL compiler Version 9.0
Exit or ctrl-d to quit
-> !!comp my_function.pcl my_library.plb
Compiling: my_function
Compiled: my_function
-> exit
Unix prompt%
p3pclcomp can also be used to check for syntax errors,

compile functions into a library, or perform PCL library
management operations.

59/252
Linking Compiled Libraries
Once the PCL functions have been debugged, it is best to use

MSC.Patran startup files (p3epilog.pcl) to automatically link your
library each time you start MSC.Patran.!
$ Sample p3epilog.pcl file

!!PATH /msc/patran_common
!!PATH ~/patran_pcl, ~/patran_pcl/plb, ~/patran_pcl/icons
!!LIB MyFunctions.plb
!!LIB YourFunctions.plb

60/252
Other PCL Directives
The !!DEBUG directive causes the compiler to save the line

numbers with the compiled code.
Must be invoked prior to compiling.
Must use the !!TRACE LINES directive to see the line numbers
as the PCL function executes.
!!DEBUG [ON, OFF]
!!TRACE directive is often used for debugging

!!TRACE [CALLS/NOCALLS, EXITS/NOEXITS, LINES/NOLINES, STDOUT/NOSTDOUT]
The LINES/NOLINES option is used in conjunction with the

DEBUG directive. If set to LINES, will echo lines as they
execute
!!DEBUG ON
!!INPUT write_number.pcl
!!TRACE LINES
write_number(5)
[38:status = file_build_fname(, records, out, NV, fname)]
[40:IF (status != 0) THEN RETURN status]
The CALLS/NOCALLS option causes MSC.Patran to write the

function name to STDOUT each time it enters (calls) a function.
This is often useful if MSC.Patran is crashing during the
execution of your PCL. Thus, you will be able to know in which
function the crash is occurring. !!TRACE CALLS enables
this action whereas !!TRACE NOCALLS disables this feature.
The EXITS/NOEXITS option is similar to the CALLS/NOCALLS
option. But instead of writing the function name each time it
calls the function, it writes the function name each time it exits
the function.

61/252
Start Up Files
Once the PCL functions have been compiled, it is best to use

MSC.Patran startup files (p3prolog.pcl, p3midilog.pcl,
p3epilog.pcl) to automatically link your library each time you
start MSC.Patran.!
They are all called by the mother of all MSC.Patran startup
files, init.pcl which is called first during MSC.Patran startup.
The startup files are called in a specific order. Below is a
simplified listing of the init.pcl showing how and when the
startup files are called.
/* simplified init.pcl example */
!!INPUT p3prolog.pcl NOERROR
$ define p3_home and default MSC.Patran paths..

$ define MSC.Patran and Insight libraries.
!!INPUT p3midilog.pcl NOERROR
$ bring up main MSC.Patran form..
!!INPUT p3patran.pcl NOERROR
!!INPUT p3epilog.pcl NOERROR
The contents of these files are usually very simple and often
just contain a few !!PATH and !!LIB directives.
$ Sample p3epilog.pcl file
!!PATH /msc/patran_common
!!PATH ~/patran_pcl, ~/patran_pcl/plb, ~/patran_pcl/icons
!!LIB MyFunctions.plb
!!LIB YourFunctions.plb

62/252
Exercise 6: p3epilog.pcl
Compile all of the previous 3 PCL functions:

a) Exercise 2: Hello World
b) Exercise 4: Writing Files
c) Exercise 5: Reading Files
into a PCL library called pat304.plb. Create a p3epilog.pcl or
p3patran.pcl file in you home directory to automatically link this
PCL library with the MSC.Patran session.
1) The p3epilog.pcl (or p3patran.pcl) file should be in either your
home directory/folder or the current directory/folder.
2) The pat304.plb file can be in any directory/folder. If it is not in
your current or home directory/folder, you will need to include
the path in your p3epilog.pcl/p3patran.pcl file as either:
a)!!lib /some/other/location/pat304.plb
b) !!path /some/other/location
!!lib pat304.plb
3) Be sure to compile all subsequent PCL functions into this
library as well.

63/252
Debugging
Debugging Compile Errors
Adequate information is given to fix common errors such as

typos and undeclared variables. The cause of the error,
file/line number, and offending line will normally be called out.
Compiling: msc_explore_xyplot_tic_mark.display
Type of ERROR
Compiled: msc_explore_xyplot_tic_mark.display
Compiling: msc_explore_xyplot_tic_mark.refresh Location of ERROR
***Error: (PCL) Undeclared variable: SVALUE
*** File: msc_explore_xyplot_tic_mark.pcl, Line: 204
*** Line is " svalue = FALSE"
***Error: Compilation aborted Offending line
Compiling: msc_explore_xyplot_tic_mark.refresh_ps
Compiled: msc_explore_xyplot_tic_mark.refresh_ps
===(PCL) Variable is declared but is not used: REALTICS
Compiling: msc_explore_xyplot_tic_mark.colorbox_select
Some errors can be harder to debug due to more ambiguous

error messages. Some examples are: incomplete comment
syntax (/* */), missing THEN in an IF () THEN condition, or an
extra comma at the end of a declaration line. These can show
up as any of the following errors.
***Error: (PCL) Invalid/unknown statement.
***Error: (PCL) Not currently defining a function.
***Error: (PCL) Extra characters after statement end.

Note: For these types of errors, the actual problem may be well above
the called out line number.

64/252
Debugging
Debugging Runtime Errors
The best debugging tool is the dump function. This function

dumps variable name, variable type, and variable value to the
MSC.Patran session file
FUNCTION my_function()
INTEGER i, j
INTEGER a(3)
FOR (i = 1 to 3)
a(i) = i
END FOR
j = 9
dump j, a
END FUNCTION
Sample to the history window (session file)
$# INTEGER j = 9
$# INTEGER a(3) = [1, 2, 3]

65/252
Debugging
A common type of run time error is a call traceback. It shows

up in your message window and looks like this:
$# Call traceback...
$# Function UI_ITEM_DELETEALL
$# Function MSC_EXPLORE.REFRESH, Line Number 294
$# Function MSC_EXPLORE.DISPLAY, Line Number 269
$# Function UI_EXEC_FUNCTION
$# Function MSC_EXPLORE_XYPLOT_DISP_GRAPH.LEGEND_CB, Line Number 694
This can be used to find the line where the error occurred, but
there is no information about what the error is. In this example,
the error occurred with the built in function UI_ITEM_DELETEALL
on line 294 in function MSC_EXPLORE.REFRESH().
If the PCL function failure causes a MSC.Patran crash, then the
only debugging tools that can be used are ones that write to
the background window or STDOUT. These are !!DEBUG and
!!TRACE as mentioned before and another write statement that
outputs to STDOUT.
!I am about to call my_function and i = ì`
The line starts with a single ! and any variable between the
` marks are evaluated.

66/252
Accessing PCL Functions
When a PCL function is called, MSC.Patran searches through the

PCL library list starting with the last library added. If it is found it
executes it, if not it returns the error:
$# (PCL) Function does not exist: function_name()
$# Execution aborted
PCL functions can be called in may different ways.
From The Command Line
Any built-in function or user defined can be called from the

command line:
My_function(radius, sind(90))
REAL radius
radius = 2.5
My_function(radius, sind(90))

67/252
From Any MSC.Patran Form
Any built-in function or user created can be called from a standard

or user created form as long as it is surrounded by back ticks `.
Use back ticks `

68/252
PCL Functions with Field Variables
In this case the function does not get surrounded with back ticks,
but the field variables are each prefixed with a forward tick .
FUNCTION max_pressure(x,y,z,t)
REAL x,y,z,t
REAL pressure
Pressure = x y*2 + z**3 - .1783

Pressure = t * pressure
RETURN pressure
END FUNCTION

69/252
MSC.Patran Built-In Functions
Built-In functions are those that are predefined by MSC.Patran.

Some represent high level functionality such as creating a mesh
on a surface, and others are low-level functions such as opening a
file for reading. Some examples of these are:
ga_group_current_set(name) Sets the current group.
ga_display_vector_set(name,style) Sets the way vector lengths
are displayed.
asm_construct_grid_xyz() Creates a geometric point a the
specified location.
fem_create_mesh_surface() Creates a plate mesh on the
specified surface.
loadsbcs_modify() Modifies a LBC set.
list_create_surface_ass_group() Creates a list of surfaces that
are members of a group.
db_get_element_ids(num_elem, elem_ids) Returns an array of all
elements in the database.
ui_form_create() Creates a MSC.Patran form.
utl_process_spawn() Spawns a background process.
file_exists() Determines whether an external file exists.
sys_time() Returns the current system time.
sys_get_user() Returns the user name.
text_open() Opens a text file for reading or writing.

70/252
Naming Conventions for Applications
Prefix Application
asm_ or sgm_ Geometry
fem_ or mesh_ Finite Elements
loadsbcs_ Loads/BCs
res_ Results
insight_ Insight
xy_ XY Plot
list_ Tools/List
ga_ Graphics (Groups, Viewports, Viewing, Display)
pref_ Preferences
mat_ material_ Materials
fields_ Fields
loadcase_ Loadcases
elementprops_ Element Properties

71/252
Naming Conventions for Other Operations
Prefix Operations
db_ add and retrieve from the MSC.Patran database
file_ operating system file and path manipulation
fio_, io_, file reading and writing

virtual_,
record,
text_,
stream_
gm_ drawing graphic primatives
str_ string manipulation functions
mth_ math functions
sys_ system and memory operations
lp_, app_, list processor functions

fem_u_
ui_ form and widget creation and manipulation

Note: Not all categories are covered here and some functions do
not follow the conventions.
Elation after finding just the

Sigh, I give up!!! right function!!!
I cant find the

function but I know
one exists
somewhere!
Which function do I Aaaarrgghhhh! Relief is in sight!

use?

72/252
Refer to Appendices A through C for examples of using

MSC.Patran built-in functions.
Appendix A shows how to perform several common PCL tasks
such as getting nodes for selected elements, getting property
data for selected elements, or extracting element results
Appendix B describes commonly used string manipulation
functions
Appendix C describes some noteworthy functions, i.e.,
functions used to sort arrays, search arrays, or calculate
common element data such as length, area, volume or centroid
location

73/252
Exercise 7: Group Elements By Shape
Write a PCL function to create a group of elements based on

element shape.
1) The function should have 2 arguments; the name of the group
to be created and the element shape code, i.e.,
FUNCTION GroupElmsByShape(GroupName, ElmShapeId)

ga_group_create(GroupName)
db_count_elems(NumElms)
db_get_elem_ids(NumElms, ElmIds)
db_get_elem_etop(NumElms, ElmIds, ElmTops)
db_get_elem_topology_data(NumElms, ElmTops, ElmShapes, NodesPerElm)
ga_group_entity_add(GroupName, ElmString)

b) Count the elements in the database
c) Get the element Ids
d) Get the element topology codes
e) Use the element topology codes to get the element shape codes
f) Create the group
g) LOOP: If an elements shape code matches the selected shape code then add it
to the group
Extra Credit: For each element of the correct shape, automatically

include its associated nodes in the group as well.
Extra Credit: Modify the function to create a group for each of
several selected element shapes.
Extra Credit: Write a PCL function to create groups based on
element topology (i.e., quad4, tria3, hex8, hex20,
etc.) instead of element shape.
74/252
Graphical User Interface
Nearly all forms and widgets that are contained in MSC.Patran

were created in PCL
PCL can be used to customize the MSC.Patran interface by
adding menus to the top menu bar.
Each menu item will reference a PCL function that is referred

to as a callback function. Typically, this callback function
will perform an operation (such as, delete groups, etc.) or open
a form.

75/252
The PCL Class Statement
The Class is a way of grouping functions for a common task.

Classes in PCL are similar (but not equivalent) to Classes in C.
Classes allow variables to be visible or Global among a
limited set of functions.
CLASSWIDE REAL global_tol
At least one class is required for each form.

Only one class should be defined per file and the file name
should match the class name.
Generally, only functions related to managing forms and form
data are defined within a class.
A class structure consists of a CLASS class_name statement
near the beginning of the file and a END CLASS statement at
the end of the file.
CLASS I_have_class
CLASSWIDE WIDGET main_form
FUNCTION init()
END FUNCTION /* init /
.
.
FUNCTION display()
END FUNCTION /* display */
.
.
END CLASS /* end of I_have_class */

76/252
PCL Widgets
Graphical objects for displaying and accepting user supplied data.
Based on Motif Xlib and Xtlib intrinsics (UNIX) and Windows GUI (NT).
Subset of the OSF/Motif and Windows widget library specialized to MCAE

applications.
Examples include: forms, menus, databoxes, labels, switches, buttons, etc.
Form Label
Select Frame Label Frame Label
Select databox1 label Menu Label: Menu item
Select databox2 label Menu Label: Menu item
Databox Label
Button 1 Button 2

77/252
Required Functions for Building/Displaying a Form
Every form is defined within a class and has at least two, but
usually more specific functions; init(), display(). Sometimes the
refresh() function is also required.
The init() Function
The init() function is user defined, but must be called init().

It is the first function defined in the class and is the function
that defines the form and all of its widgets.
It is also used to initialize any classwide variables that need
initializing the first time the form is opened.
The built-in functions for defining widgets will only be called in
this function. Below are examples to build a form and place a
button:
main_form = ui_form_create(, @
/* x position */ FORM_X_LOC, @
/* y position */ FORM_Y_LOC, @
/* relative to */ UL, @
/* width */ FORM_WID_SML, @
/* height */ FORM_HGT_QTR, @
/* label */ My_Form_Label, @
/* unused */ )
my_button = ui_button_create( @
/* parent */ main_form, @
/* callback */ my_button_cb, @
/* x position */ FORM_L_MARGIN, @
/* y position */ y_loc, @
/* width */ BUTTON_WID_FULL, @
/* height */ BUTTON_HGT, @
/* label */ My Button, @
/* unused */ , @
/* highlight */ FALSE)

78/252
The display() Function
The display() function is simple, but required. A complete

function may only contain the following:
FUNCTION display()
ui_form_display(my_class)
END FUNCTION
The only required element is the built-in function

ui_form_display(classname). Classname is the name of the
class that these functions are members of.
Once the display() function is called it will display the form and
all widgets that are currently visible.
The display() function may also contain function calls to get
data from the database or from external files to initialize the
form with proper data.
sys_get_user(user_name)
ui_wid_set(databox_user_name, VALUE, user_name)
It is also used to hide and display widgets that are not always
visible:
IF (flag_advanced == TRUE) THEN
ui_wid_set(frame_advanced, DISPLAY, TRUE)
END IF

79/252
The refresh() Function

This optional function is used to keep forms up-to-date. Any
time a function changes the contents of the database, it should
make a call to ui_wid_refresh(). This causes the refresh()
function, if it exists, to be called in every displayed form/class.
An example function is given below:
FUNCTION refresh()
INTEGER db_status
STRING current_analysis_code[32]
db_status_ = db_get_default_anal_code(current_analysis_code)
IF (db_status != 0) THEN RETURN
ui_wid_set(analysis_code,LABEL,current_analysis_code)
END FUNCTION
It is the responsibility of the author of each form to write a

refresh() function to update the form if the contents of the form
are based on information in the database.
The refresh() function is also typically called by the display()
function to initialize the form properly.

80/252
Widget Heirarchy
Widgets are created in a hierarchical manner. Every widget
has a parent except the form.
/* callback */ "", @
/* relative to */ "UL", @
/* height */ FORM_HGT_QTR, @
/* label */ "Form Label", @
/* unused */ "")
/* callback */ "my_button_cb", @
/* y position */ y_location, )
All widgets could be children of the form, but widgets can also
be children of other widgets.
my_frame = ui_frame_create( @
/* callback */ , @
/* x position */ x_loc, @
/* width */ FORM_WID_SML, )
inner_button = ui_button_create( @
/* parent */ my_frame, @
/* callback */ "inner_button_cb", @
/* x position */ FRAME_L_MARGIN, @
/* height */ BUTTON_HGT, )
If a widget is hidden or disabled, all of its child widgets do the

same.
All widgets are placed relative to their parents.

81/252
Widget Callbacks
What Are They?
A callback is a PCL function that is called when an "event"

happens in a particular widget.
An event is an action performed on a widget. The action is
typically via user interaction such as a mouse click. However,
it could also be from another PCL function.
Every widget has a unique set of event possibilities, or none at
all. For example, a button can just be pushed, but databoxes
can gain focus, lose focus, or its contents can be changed.
Labels and frames are examples of widgets that have no
events that will register a callback.
The callback function is named when the widget is defined in
the init() function.
/* callback */ "my_button_cb", @
The callback function must be defined within the same class as

the init() function.

82/252
What Are They Used For?
Callbacks can be used to do anything including dance a jig,

sing a tune, or perhaps display another form as the function
below does.
FUNCTION my_button_cb()
ui_exec_function("another_form", display)
END FUNCTION
Callbacks are NOT required and most of the time they are not
used. When no immediate action is required, put an empty
string () for the callback name.
Callbacks are usually used to make changes to the form or
bring up another form based on user interaction.
Callback Arguments (Widget Function Data)
When a callback is made, information may be passed to the

callback function. Each widget type has a unique set of
callback information that is passed.

83/252
Widget Type Data Type Description of Callback data
button No arguments passed
buttonicon No arguments passed
cascadeitem Does not register events
colorbar Widget Widget Id of the colorbar
Integer User data
Integer Selected color Id
colormenu Widget Widget Id of the colorbar
Integer User data
Integer Selected color Id
databox String[] GAIN, LOSE, CR, or WIDSET (if
appropriate ui_wid_set() call has been
made) depending on which event initiated
the callback
file String[] Complete pathname of the selected file
String[] OPEN or CANCEL
form Does not register events
frame Does not register events
graph Does not register events
item Does not register events
itemicon Does not register events
label Does not register events
labelicon Does not register events
listbox Integer Number of selected items
String[]() Label of the selected items in the
listbox
menu String[] Name of the selected menu item
menubar Does not register events
modalform Does not register events
optionmenu String[] Name of the currently selected item
scrollframe Does not register events
selectdatabox String[] GAIN, LOSE, CR, or WIDSET (if
appropriate ui_wid_set() call has been
made) depending on which event initiated
the callback
selectframe Does not register events
separator Does not register events
slidebar Real Current value of the slidebar
String[] VALUE_CHANGED or DRAG
spreadsheet String[] SELECTED
Integer starting selected column
Integer starting selected row
Integer ending selected column
Integer ending selected row
selected layer
switch String[] Name of the switch item changed

84/252
String[] ON or OFF
text Does not register events
toggle Logical Value of the toggle, TRUE or FALSE
toggleicon Logical Value of the toggleicon, TRUE or FALSE

85/252
Widget Placement
Widgets are placed on the form using predefined constants

defined in the appforms.p file (see Appendix D). This file is
found in the patranXX/customization directory.
The predefined constants are used to maintain a consistent
spacing between different hardware platforms and between
different MSC.Patran applications.
FORM_T_MARGIN
FORM LABEL
FRAME_LABEL_HGT
FRAME_1EDGE Frame Label

FRAME_T_MARGIN
OPT_MENU_HGT
Menu Label: Menu item
INTER_WIDGET_SPACE
OPT_MENU_HGT
Menu Label: Menu item
FRAME_B_MARGIN
FRAME_1EDGE
INTER_WIDGET_SPACE
Databox Label
DBOX_HGT_LABOVE
INTER_WIDGET_SPACE
BUTTON_HGT
Button 1 Button 2
FORM_B_MARGIN
FORM_L_MARGIN FORM_R_MARGIN

86/252
These constants should be used in conjunction with a position

or placement variable to keep track of your location on the
form. For example a portion of the code to create the form on
the preceding would look like:
dbox_id = ui_databox_create( @
/* y position */ y_loc,)
y_loc += DBOX_HGT_LABOVE + INTER_WIDGET_SPACE
apply_btn = ui_button_create( @
/* callback */ "apply_btn_cb", @
/* width */ BUTTON_WID_HALF, @
/* height */ 0, )
This strategy allows widgets to be added and removed in the

middle of the form without causing any placement problems.
Each widget is simply placed relative to the widget above it by
always referencing the y_loc variable.

87/252
Widget Variables
Widget variables are typically defined as either classwide or in

the init() function and are used to store the widget Id, i.e., an
internal pointer to the widget.
CLASS my_class
CLASSWIDE WIDGET my_frame
FUNCTION init()
.
.
my_frame = ui_frame_create( @
/* callback */ , @
/* x position */ x_loc, @
/* width */ "FORM_WID_SML, )
Widget variables are only needed if the widget will be

referenced. There are 3 situations when a widget might be
referenced, i.e.,
a) if it will be modified
b) if data will be retrieved from it
c) if it will be a parent to another widget.
Buttons, labels, and item widgets are examples of widgets that
often do not need to be referenced for any reason and hence
do not require a widget variable
ui_button_create( @
/* callback */ "apply_cb", @

88/252
Note: It is a good practice to always use widget variables even if the
widget is not referenced. It is also good practice to always declare
widget variables as classwide.

89/252
Modifying Widgets
Most of the attributes describing a widget can be modified after

it has been created in the init() function, including whether they
are visible or not.
Modifications are made with the ui_wid_set() function.
Common modifications are described below:
DISPLAY displays or hides a widget.
ui_wid_set(group_lst_frame, DISPLAY, FALSE)
ENABLE enables or disables the widgets use (ghosting).

ui_wid_set(button_post_curve, ENABLE, FALSE)
LABEL modifies a particular attribute of a widget such as a

label above a databox.
ui_wid_set(button_post_curve, LABEL, Unpost Current Curve)
VALUE modifies the current value of a widget such as the

contents of a databox, current menu item, or slidebar value.
ui_wid_set(slider_line_thk, VALUE, new_thickness)
X or Y modifies the position of a widget on the form.

ui_wid_set(button_apply, Y, new_bottom_location)

90/252
Getting Data from Widgets
Most data is retrieved from widgets using the ui_wid_get()

function. The example below gets the current setting or value
from a slidebar widget.
FUNCTION apply_btn_cb()
REAL shrink_value
ui_wid_get(slidbar_element_shrink, VALUE, shrink_value)
ga_display_shrfem_set(general, shrink_value)
END FUNCTION
In this example the value represents an element shrink factor. As

soon as the data is gathered, the graphical display is updated
using the ga_display_shrfem_set() function.
Usually widget data is retrieved after the user hits the Apply
button on the form. The Apply button references a callback
function, typically called apply_cb(), that contains the
ui_wid_get() function calls. Once the data is gathered, action
can be taken to reflect the user input, such as, updating the
element display to reflect the new shrink factor.
If it is desired to update the element shrink factor immediately
as the slidebar is being moved, then the data would need to be
retrieved from the widgets callback function. This is only
required if an immediate action needs to be performed based
on an event. For this case, the slidebar callback function
would look like this:
FUNCTION slider_cb(slider_value, change_type)
REAL slider_value
STRING change_type[]
ga_display_shrfem_set(general, shrink_value)

91/252
END FUNCTION

92/252
Putting it all Together (Example)

#include appforms.p
CLASS first_class
CLASSWIDE WIDGET main_form

CLASSWIDE WIDGET my_dbox
CLASSWIDE WIDGET apply_btn, cancel_btn
FUNCTION init()
REAL y_loc
/* relative to */ "UL", @
/* height */ 0, @
/* label */ "Form Label", @
/* unused */ "")
y_loc = FORM_T_MARGIN
my_dbox = ui_databox_create( @
/* label length */ 0, @
/* box length */ DBOX_WID_SINGLE, @
/* label */ "Enter a Value", @
/* value */ "", @
/* label above */ TRUE, @
/* datatype */ "REAL", @
/* number of values */ 1)
y_loc += DBOX_HGT_LABOVE + INTER_WIDGET_SPACE
apply_btn = ui_button_create( @
/* callback */ "apply_btn_cb", @
/* x position */ BUTTON_THIRD_X_LOC1, @
/* width */ BUTTON_WID_THIRD, @
/* height */ 0, @
/* label */ "Apply", @
/* unused */ TRUE, @
/* highlight */ TRUE)

93/252
cancel_btn = ui_button_create( @
/* callback */ "cancel_btn_cb", @
/* x position */ BUTTON_THIRD_X_LOC3, @
/* width */ BUTTON_WID_THIRD, @
/* height */ 0, @
/* label */ "Cancel", @
/* unused */ TRUE, @
/* highlight */ FALSE)
y_loc += BUTTON_DEF_HGT + FORM_B_MARGIN
ui_wid_set(main_form,"HEIGHT",y_loc)
FUNCTION display()
ui_form_display("first_class")
FUNCTION refresh()
/* For this example this function is not necessary

but is included for completeness */
END FUNCTION /* refresh */
REAL dbox_value, answer
ui_wid_get(my_dbox, "VALUE", dbox_value)
> crunch_numbers(dbox_value, answer)
ui_write("The answer is: "//str_from_real(answer))
END FUNCTION /* apply_btn_cb */
FUNCTION cancel_btn_cb()
ui_form_hide("first_class")
END FUNCTION /* cancel_btn_cb */
END CLASS /* first_class */

94/252
Exercise 8: Simple Form
Write a PCL class that creates a simple form with a single button
on it. Pressing the button should display a message in the
MSC.Patran history window, e.g., Help me Im being pushed
around!
1) Built-in functions:
ui_form_create(callback, x_loc, y_loc, position, width, @
height, label, iconname)
ui_button_create(parent, callback, x_loc, y_loc, width, @
height, label, flag, highlight)
ui_form_display(classname)
2) Your class should contain the following functions:

init(), display(), button_cb()
Extra credit: Using ui_wid_set() in the button callback function,

have the label on the button change after it has been
pressed to Push Me Again!
Extra credit: Add a Cancel button to hide the form. In its
callback function use the ui_form_hide()
function to hide the form.

95/252
Day 3
The C-Preprocessor and Include Files
The constants to define the standard widget sizes and spacing are
defined in the include file appforms.p (see Appendix D). These
definitions are linked into your file by using the C-preprocessor
statement #include.
#include appforms.p
The substitutions are made using the C-preprocessor program

cpp.
Only PCL programs that build forms need these constants and
therefore need to run this program.
The C-preprocessor is run with the following syntax:
cpp I<patran_directory>/customization C P filename.pcl filename.pob
Where <patran_directory>/customization is the path to the

directory where the appforms.p file resides. The output of this
operation (filename.pob) can then be compiled using !!input or
!!compile.
Generally, you will want to use make and Makefiles to
automatically execute cpp. A sample Makefile is included on
the next page.
Additionally, the MSC.Patran shareware utilities also include
some functions for compiling that automatically execute cpp.
See Appendix F for the details on these functions.

96/252
Make Files
Make file are typically used to compile PCL programs when

many functions or forms are involved.
Make files are a UNIX utility used for compiling programs.
Make files will automatically run cpp and then compile the PCL
into a library.
Make only recompiles the files that were edited.
Make will work with many different files and functions in a
single Makefile.
A sample make file can be found in the customization
directory:
# Name of the target pcl library
PclLibrary = hole.plb
# List of .pob files that go into the library

# Each of these files should have a corresponding .pcl file
PclObjects = insert_hole.pob \
update_props.pob
# List of possible include files

# If any of these is touched, all .pcl files will be blindly recompiled
IncludeFiles = /msc/patran2001/customization
# Script for invoking the standalone pcl compiler

PCLCOMP = /msc/patran2001/customization/Pclcomp
# Command for compiling a single preprocessed pcl source file

COMPILE = $(PCLCOMP) $(PCFLAGS) -pob $*.CPP
# Possible locations for finding the executable for cpp

CPPLIST = /usr/lang/cpp /usr/ccs/lib/cpp /lib/cpp /usr/lib/cpp
# cpp arguments for preprocessing a single pcl source file

CPPARGS = -I$(IncludeFiles) -C $*.pcl >$*.CPP
# Define the possible file suffixes

.SUFFIXES: .pcl .pob .plb
# Make sure that the bourne shell is used to invoke subcommands

97/252
SHELL = /bin/sh
# Define a rule for converting a .pcl source file to a .pob object.

# This rule is somewhat ugly because 1) it attempts to intelligently
# locate the cpp executable given that it often is not on the default
# search path and 2) we need to make sure that the .pob file gets
# deleted if the compilation fails! We use "@" carefully so as to not
# clutter the screen while make is running.
.pcl.pob:
@ rm -f $*.ERROR
@ CPP='' ; \
for i in $(CPPLIST) ; do \
if [ -f $$i ] ; then \
CPP="$$i" ; \
fi ; \
done ; \
echo "$$CPP $(CPPARGS)" ; \
$$CPP $(CPPARGS)
@echo $(COMPILE)
-@ $(COMPILE) ; \
if [ $$? -ne 0 ] ; then \
rm -rf $*.pob ; \
touch $*.ERROR ; \
else \
# rm -rf $*.CPP ; \
exit 0 ; \
fi
@ echo
@ if [ -f $*.ERROR ] ; then \
rm -f $*.ERROR ; \
exit 1 ; \
else \
exit 0 ; \
fi
# Merge all .pobs into the target

$(PclLibrary): $(PclObjects)
$(PCLCOMP) $(PCFLAGS) -m tmp.plb $(PclObjects) ;\
mv tmp.plb $(PclLibrary) ;\
rm -f tmp.plb *.pob
# Define the include file dependencies

$(PclObjects): $(IncludeFiles)
# Finally, define a "clean" rule

clean:
rm -f $(PclObjects) $(PclLibrary) *.CPP Makefile.log tmp.plb

98/252
Exercise 9: Callbacks
Write a PCL function that creates a form with 3 toggles and 2

databoxes that accept football scores. Hitting the Apply button
writes the scores to the session file.
1) Only 1 toggle should be selected at a time. That is, selecting
one toggle should deselect any other toggle that is selected.
2) The toggles should be in a frame.
3) Selecting a particular toggle should update the team names
(labels) on the databoxes.
4) Built-in functions:
ui_form_create(callback, x_loc, y_loc, position, width, height, label, iconname)
ui_frame_create(parent, callback, x_loc, y_loc, width, height, label)
ui_toggle_create(parent, callback, x_loc, y_loc, label)
ui_databox_create(parent, callback, x_loc, y_loc, label_length, box_length, @
label, value, label_above, datatype, num_vals)
ui_button_create(parent, callback, x_loc, y_loc, width, height, label, flag, @
highlight)
ui_separator_create(parent, callback, x_loc, y_loc, width, horizontal_flag)
ui_wid_set(widget, parameter, value)
5) Your class should contain the following functions:

init(), display(), cancel_btn_cb(), apply_btn_cb(), multiple toggle_cb()
Extra credit: A better way to create

this form would be to use a switch
instead of toggles. Replace the
toggles with a switch using the
ui_switch_create() and
ui_item_create() functions.

99/252
Exercise 9
FORM_X_LOC, FORM_Y_LOC

100/252
Handling Errors and Messaging
Errors from Built-In Functions
Error messages for most built in functions are stored in a

message database.
These error messages are accessed through the use of the
following functions: msg_to_form() and msg_to_string().
Each message in the message database is associated with a
unique number between 1 and 999,999,999. This number is
returned as a non-zero status when a function fails to execute
properly.
status = db_count_elems(num_elems)
IF (status != 0) THEN
msg_to_form(status, MSG_FATAL, appcode(status) 0, 0.,"")
RETURN -1
END IF
This PCL code would bring up a form displaying the error

message and it would be listed in the message window and
session file.
The severity of the message is controlled by the second
argument in the function msg_to_form(). Valid options are:
MSG_FATAL (= 4), MSG_WARNING, MSG_ACKNOWLEDGE,
MSG_CRASH, and MSG_INFO. These constants can be found
in the include file, pdamsg.h
The severity shows up as part of the feedback to the user so
they can be alerted to the severity of the error.

101/252
Custom Error Messages

Using User Messages Database
Custom (user-defined) messages can be created and accessed

with the same msg_to_form() used for MSC.Patran built-in
functions.
This is done by creating a text file with the following format:
#******** NEW APPCODE
1001000000 FEM_TOOLS3
#define form text labels
1001000001 Tools.write_nodes
1001000002 Special String
#define messages
1001000100 Invalid entry in databox
With the above user message database, the following line

could produce this form:
msg_to_form(1001000100,MSG_FATAL,1001000001,0,0.,)
Message
Error reported in application Tools.write_nodes by application FEM_TOOLS3
Invalid entry in databox
OK

102/252
Without a Messages Database
If it is not desired to create a message database, then the

user_message() function can be used to report errors or other
user information.
status = db_count_elems(num_elms)
msg_to_form(status, 4, appcode(status), 0, 0., )
RETURN -1
END IF
IF (num_elems == 0) THEN
user_message(Warn, 0, My PCL, No elements in the database!)
RETURN 0
END IF
user_message(WARN,0,MY PCL,No elements in the database!)
Message
Warning reported in application My PCL
No elements in the database

103/252
Several message types are supported, some of those include:

WARN, FATAL, INFO, ACK, Q_YN, Q_YN_Y,
C_YN, C_YNY, C_YNYN, C_YNYN_Y, etc.
C_YN = Critical decision with Yes and No buttons
C_YNY = Critical decision with Yes, No, and YesForAll
buttons
C_YNYN = Critical decision with Yes, No, YesForAll, and
NoForAll buttons
C_YN_Y = Critical decision with Yes and No buttons. The
Yes button is the default action.
C_YN_N = Critical decision with Yes and No buttons. The
No button is the default action.
The return value for user_message() indicates which
button was selected: 1 = Yes, 2 = No, 3 = Yes for all, 4 =
Abort, 5 = No for all
IF (file_exists(fname, )) THEN
status = user_message(C_YN, 0, PCL: Field Tool, @
Selected file already exists! Overwrite?)
IF (status != 1) THEN RETURN -1
file_delete(fname)
END IF

104/252
Taking Advantage of the UNDO Feature
The UNDO feature of MSC.Patran operates like a fence.

Nothing is actually saved to the database until a
uil_db_commit() operations is performed. When a user selects
the Undo icon, everything since the last uil_db_commit() is
Un-done.
The uil_db_commit() function works in conjunction with the
uil_db_undo() function.
uil_db_commit(STRING)
uil_db_undo()
Any function that changes the contents of a MSC.Patran

database should perform a uil_db_commit() prior to
performing the operation.
If an error is detected during the operation, a uil_db_undo()
should be performed. Example:
INTEGER status
REAL force_val
STRING lbc_name[32]
STRING node_list[VIRTUAL]
ui_wid_get_vstring(node_sdbox, VALUE, node_list)
ui_wid_get(force_dbox, VALUE, force_val)

ui_wid_get(lbc_name_dbox, VALUE, lbc_name)
uil_db_commit(Create force at nodes)

status = CreateForceAtNodes(lbc_name, force_val, node_list)
uil_db_undo()
END IF
END FUNCTION

105/252
Select Mechanism
PCL offers a set of widgets and functions to enable the selection of

entities from the Viewport. These tools are typically referred to
collectively as the MSC.Patran Select Mechanism. The Select
Mechanism includes the use of Select Frame, Select Databox widgets,
and MSC.Patrans List processor PCL calls.
Select Mechanism GUI Mechanics

Select Databoxes, Select Frames, and Select Menus
The Select Databox is used to interact with the model by letting

the user select different types of entities, i.e., curves, surfaces,
elements, element faces, nodes, etc.
The resulting data in the Select Databox is referred to as a
Picklist
A Picklist is a character string that appears in the Select Databox as a
result of a user selection or user entered data.
The Picklist is processed by MSC.Patrans List Processor

A Select Menu is associated with a Select Databox. There is a
predefined, finite set of Select Menus available in MSC.Patran.
Select Menus are used to filter which entity types are selected.
The parent widget of a Select Databox must be a Select Frame.
The Select Mechanism can be made to Auto Execute by
labeling the Select Frame Auto Execute or using the #define
AUTO_EXECUTE statement defined by the appstrings.p define
file.
Auto Execute is the action of automatically running the Apply
function when the last Select Databox within the Select Frame is filled.

106/252
Select Mechanism
The Select Menu is displayed when focus is given to a Select

Databox.
Focus policy can be controlled within PCL by using the
ui_set_focus(MyWidget) and the select_focus.exit() functions.
The widget callback of a Select Databox is a string indicating
the action of GAIN or LOSE.
Other less often-used callback returns include CR and WIDSET
To close the Select Menu a select_focus.exit() is

executed.
a) When another Select Databox gains focus the new Select
Menu is automatically displayed.
b) When closing a form, it is necessary to run
select_focus.exit() to close the Select Menu. Otherwise the
Select Menu form will remain on the screen.
FUNCTION cancel_cb()
select_focus.exit()
ui_form_hide( CLASSNAME )
END FUNCTION
Together, the Select Databox, Select Frame, and Select Menu
are referred to as the select mechanism. The PCL widget
functions for a select mechanism are:
ui_selectframe_create(), ui_selectdatabox_create()

107/252
Select Mechanism
GUI PCL Example

sframe_id = ui_selectframe_create ( @
/* parent */ form_id, @
/* callback */ "apply_cb", @
/* Left_margin */ FORM_L_MARGIN, @
/* Y Location */ yloc, @
/* col_width */ SFRAME_WID_SINGLE, @
/* height */ SFRAME_1SDB_HGT_LABOVE,@
/* Label */ Auto Execute, @
/* recycle */ TRUE )
sdbox_width= SDBOX_WID_SINGLE - 2*SFRAME_R_MARGIN
select_data_box1 = ui_selectdatabox_create ( @
/* parent_frame */ sframe_id, @
/* Left_margin */ SFRAME_L_MARGIN, @
/* Y Location */ SDBOX_Y_LOC1_LABOVE, @
/* label_length */ 0.0, @
/* Box_length */ sdbox_width, @
/* label */ "Curve List", @
/* default_value */ "" , @
/* label_above */ TRUE, @
/* data_type */ "CURVE", @
/* prompt */ "select a filter" )
yloc += SFRAME_1SDB_HGT_LABOVE + SFRAME_2EDGE +

INTER_WIDGET_SPACE
Auo Execute
Select Frame
Curve Select Menu Select Databox

108/252
Select Mechanism
List Processor
List Processor Mechanics
The List Processor evaluates or parses a Picklist for

information that the application needs.
The Picklist is retrieved from the specified Select Databox

using the ui_wid_get_vstring() command. This command
automatically sizes a virtual string to store the picklist data.
The low level, more flexible List Processor functions begin

with the prefix, lp_. In addition to these functions, there are
other more "user friendly" functions which perform more
specific tasks.
The user friendly functions also offer another benefit. Most

lp_ functions make calls to the database to obtain information
about the Picklist. The more user-friendly functions, such as
the fem_u_ functions, only evaluate for ids and do not require
querying the database. This gives the benefit of improved
performance.
When using the List Processor functions it is necessary to

#include the lpenums.p file with the C Preprocessor (cpp). This
file contains all the keywords used to define the evaluation
methods for interpreting the Picklist with the various List
Processor functions.

109/252
Select Mechanism
A Picklist may be comprised of one or more sublists. Each

sublist in a Picklist has a type and attributes associated to it.
If a user is selecting nodes and elements, each of the entity types
would comprise a sublist. The Picklist, Node 1 2 45 Element 2 4 6
contains two sublists based on use of the lp_sublist_node and
lp_sublist_element sublist filters.
All You Really Need to Know
Although the low-level lp_ functions offer the most flexibility

and are more complete than the fem_u functions, they are also
generally more complicated to use.
Refer to Appendix H for a more complete description of the lp_

functions
The most popular list processor functions are:
fem_u_count_id_list() This function counts how

many entities (nodes, elements, surfaces, etc.) have been
selected.
fem_u_get_id_list() This function extracts the

entities Ids from the picklist and places them in an integer
array.
fem_u_get_subid_list() This function extracts

subentities, i.e., element edge or face Ids.

110/252
Select Mechanism
Usage: fem_u_count_id_list()
num_ids = fem_u_count_id_list(sublist_type, picklist, @
do_message, status)
INPUT:
sublist_type INTEGER See note below
picklist STRING
do_message LOGICAL
status INTEGER
OUTPUT:
num_ids INTEGER
Usage: fem_u_get_id_list()
fem_u_get_id_list(sublist_type, picklist, num_ids, @
do_message, ids)
Argument definitions are similar to above
The sublist types can be any of the following:

LP_SUBLIST_FINITE_ELEMENT, LP_SUBLIST_NODE,
LP_SUBLIST_ELEMENT, LP_SUBLIST_MPC,
LP_SUBLIST_GEOMETRY, LP_SUBLIST_POINT,
LP_SUBLIST_CURVE, LP_SUBLIST_SURFACE,
LP_SUBLIST_SOLID, LP_SUBLIST_ANY
The sublist types are defined in the lpenums.p file

111/252
Select Mechanism
Example
FUNCTION apply_cb()
INTEGER status
STRING node_list[VIRTUAL]
ui_wid_get_vstring(node_sdbox, VALUE, node_list)
status = do_something_spectacular(node_list)
END FUNCTION /* apply_cb */
FUNCTION do_something_spectacular(node_list)
INTEGER status
INTEGER num_nodes, node_ids(VIRTUAL)
STRING node_list[]
num_nodes = fem_u_count_id_list(LP_SUBLIST_NODE, @
node_list, FALSE, status)
IF (num_nodes == 0) THEN RETURN (-1)
sys_allocate_array(node_ids, 1, num_nodes)
fem_u_get_id_list(LP_SUBLIST_NODE, node_list, @
num_nodes, FALSE, node_ids)
RETURN (0)
END FUNCTION /* do_something_spectacular */

112/252
Exercise 10: Form to Group Elms By Shape
Create a form that will allow you to create a group based on

element shape from selected elements.
1) You should modify the function from Exercise 7 to accept a
string of selected elements, i.e., the function arguments will be:
FUNCTION GroupElmsByShape(ElmList, GroupName, ElmShapeId)
In Exercise 7, this function created groups using all elements in

the database. Now this function will created groups from only the
selected elements.
In order to create groups based on the selected elements rather
than all the database elements, the db_count_elems()
statement will be replaced with fem_u_count_id_list() and
the db_get_elem_ids() function will be replaced with
fem_u_get_id_list().
2) Use either a switch, ui_switch_create(), or an
optionmenu, ui_optionmenu_create()
to select the element shape.
3) Be sure to echo your function call to the
session file via the > symbol.

113/252
Form to Group Elms By Shape
4) Built-in functions
ui_form_create(callback, x_loc, y_loc, position, width, height, label, iconnme)
ui_frame_create(parent, callback, x_loc, y_loc, label)
ui_switch_create(parent, callback, x_loc, y_loc, num_cols, label, always_one)
ui_item_create(parent, name, label, toggleable)
ui_databox_create(parent, callback, x_loc, y_loc, label_length, box_length, @
label, value, label_above, datatype, num_vals)
ui_selectframe_create(parent, callback, x_loc, y_loc, width, height, @
label, recycle)
ui_selectdatabox_create(parent, callback, x_loc, y_loc, label_length, @
box_length, label, value, label_above, datatype, prompt)
ui_separator_create(parent, name, x_loc, y_loc, length, horizontal)
ui_button_create(parent, callback, x_loc, y_loc, width, height, label, @
flag, highlight)
ui_wid_get(widget_id, parameter, value)
ui_wid_get_vstring(widget_id, parameter, value)
NumElms = fem_u_count_id_list(SublistType, PickList, DoMsg, Status)
fem_u_get_id_list(SublistType, PickList, NumElms, DoMsg, ElmIds)
ga_group_exist_get(GroupName, IntegerFlag)
ga_group_create(GroupName)
db_get_elem_etop(NumElms, ElmIds, ElmTops)
db_get_elem_topology_data(NumElms, ElmTops, ElmShapes, NodesPerElm)
ga_group_entity_add(GroupName, ElmList)
Extra credit: Include Auto Execute functionality

Extra credit: Include error checking via the msg_to_form() and
user_message() functions
Extra credit: Include the ability to undo the creation of your
group
Extra credit: Use the ui_wid_refresh() function to
automatically update other displayed forms that might list group
names.
Extra credit: Include a callback to the element shape switch that
automatically provides a default group name based on the
selected shape.

114/252
Day 4
Executing Programs Outside of MSC.Patran
Application developers may have the need to execute other programs in

order to perform certain operations. Programs that execute other
programs are said to be spawning a process.
Spawning Remote Processes

Spawning a remote process is one method of performing
customized functionality. The PCL function
utl_process_spawn() is used by MSC/PATRAN to spawn a
process.
PCL process commands
Functions Description
utl_process_spawn(command,wait) Spawns a process. The return
value of the command is either
an error code or the process id
if wait = FALSE.
utl_process_wait(pid) Wait for the process to complete
before continuing
utl_display_process_error(errcode, Display an error message based
severity) on the return value of
utl_process_spawn.
utl_process_error(errcode) Returns True or False given the
errcode (status) of the
utl_process_spawn or _wait
command.
utl_process_kill(pid) Kill a process
Code Example
stat = utl_process_spawn( read_results.exe, TRUE )

IF( utl_process_error( stat ) ) THEN
utl_display_process_error( stat, 3 )
END IF

115/252
External Processes
Redirection cannot be used in the utl_process_spawn()

command. If redirection is required then a shell script should
be created, then executed by the utl_process_spawn
command.
Invalid utl_process_spawn(runscript > outfile,TRUE)
To support multiple platforms a shell script can be setup to

query machine type information and then run the appropriate
executable.
Example Script
utl_process_spawn("executable_home_dir/bin/script_name",TRUE)
Script:
#! /bin/sh
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Provides a front-end for external executables and scripts
# in support of MSC/PATRAN PCL.
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
# Extract command name from the $0 string

CmdName=ècho $0 | sed 's;^.*/;;'`
echo $CmdName
CmdDir=` echo $0 | sed -e 's;^$.*$/.*;\1;' -e 's;/*bin$;;'`

if [ "ècho "$CmdDir" | sed 's;^$.$.*$;\1;'`" != / ] ; then
CmdDir=`pwd`/$CmdDir # ensure non-relative path
fi
echo $CmdDir
case ùname` in
SunOS) Machine=SUN ;;
IRIX*) Machine=SGI ;;
AIX) Machine=IBM ;;
HP-UX) Machine=HP700 ;;
OSF1) Machine=DECA ;;
esac
if [ $# -eq 0 ] ; then
exec $CmdDir/bin/exe/$Machine/$CmdName
else
exec $CmdDir/bin/exe/$Machine/$CmdName "$@"
fi

116/252
External Processes
Locking a database
Having more than one process access a database

simultaneously can damage the database.
In order to prevent this, MSC/PATRAN locks the database while it is in
use. Any executable that accesses the database (e.g., translator, solver,
etc.) should also perform a file lock to guarantee secure access of that
database. If a database is locked, a message will be relayed indicating
that the database is in use.
The stand-alone utility lockfile gives an application

developer the ability to lock databases.
If this utility is run for a database that is already locked, it will wait five
minutes and retry. It will not lock a database until an existing database
lock has been cleared.
The lockfile utility requires the name of the database to lock

and a command string to execute. The lock will remain active
as long as the command executes.
The syntax for the lockfile utility is as follows:
lockfile <dbname> <cmd> <cmd_arg1> <cmd_arg2>
FUNCTION start_mytrans(dbname, count)

str_formatc(cmd,lockfile %s %s -db %s -cnt %d, @
dbname, mytrans, dbname, count)
/* Spawn the process and continue; do not wait for completion.
If a process spawning error occurs, display it as severity
2 (WARNING) */
status = utl_process_spawn(cmd, FALSE)
IF ( utl_process_error( status ) ) THEN utl_display_error( status, 2)
END FUNCTION /* start_mytrans */
Using this example, this will execute the following command:
lockfile my.db mytranslator -db my.db -cnt 542

117/252
External Processes
Using C and Fortran executables to access a

MSC.Patran database directly.
External C and Fortran programs can access Patran databases

using the C or Fortran versions of PCL database function calls.
An example link script is delivered in the Patran customization
directory that includes all the libraries needed to satisfy any
reference to the PCL database functions. The scripts are
CAccessCalls.c and fort_access_calls.f.
The PCL and Customization Patran Library document has more
information on accessing the Patran database from external
programs, Section 8.3 (V9.0 of Patran).
Multiple simultaneous transactions on a Patran database is not
permitted. All transactions should be completed prior to
performing an external operation. The db_commit_raw()
function should be used to commit all previous operations that
have occurred in the database.
If you are only extracting information, the database does not
need to be closed
If you are modifying the contents of a database then the
database must be closed prior to running the external process.

118/252
External Processes
External Access of an MSC.Patran Database
There cannot be multiple simultaneous transactions on an

MSC.Patran database.
If an external program accesses a database which is currently opened
by MSC.Patran, MSC.Patran must first end the transaction with the
database with the db_commit_raw function. Only when the
external program is finished accessing the database should
MSC.Patran resume a translation within the database using the
db_start_transaction_raw function.
When accessing the database only to extract information,

MSC.Patran need not close the database but should end the
current transaction and restart it only after the external
program is finished.
Example of PCL code which would spawn an external process to
extract information.
FUNCTION my_spawn()
INTEGER status
status = db_commit_raw()
status = utl_process_spawn ( process arg1, TRUE )
IF ( utl_process_error ( status ) ) THEN
utl_display_process_error( status, 3 )
END IF
status = db_start_transaction_raw()
END FUNCTION

119/252
External Process
When an external program is modifying or adding data to a

database which is currently open, the database must first be
closed and then re-opened by MSC.Patran after the external
program has finished.
The database must be closed and re-opened because there is no
mechanism for informing MSC.Patran of external changes to an already
opened database.
Example of PCL code which would spawn an external forward

translator.
FUNCTION my_spawn()
INTEGER status
STRING database_name[256]
status = db_name_get ( database_name )
status = uil_file_close.go()
status = utl_process_spawn ( process arg2, TRUE )
IF ( utl_process_error ( status ) ) THEN
utl_display_process_error( status, 3 )
END IF
status = uil_file_open.go( database_name )
END FUNCTION

120/252
Special Widgets
A number of specialized widgets exist in MSC.Patran. These

widgets are for often-used operations or to perform specialized
tasks. Two such widgets are the File widget and the Spreadsheet
widget.
File Widget
The file widget is used whenever a system filename is needed

for importing or exporting data.
The File widget is built up of many standard widgets and
allows for customization of databox labels, listbox labels and
file type filtering.

121/252
Special Widgets
The headers and filter labels are customizable allowing for

adaptation to the specific file type.
file_widget=ui_file_create( @
/* parent */ form_id, @
/* callback */ "file_cb", @
/* x */ FORM_L_MARGIN, @
/* y */ FORM_T_MARGIN, @
/* width */ FILE_WID_DOUBLE, @
/* rows */ 6, @
/* filterlabel */ "Filter", @
/* filter mask */ "*.db", @
/* Dir label */ "Directories", @
/* files label */ "Database List", @
/* Select label*/ "Existing Database Name",@
/* Selection */ "", @
/* OK label */ "OK", @
/* filt btn lab*/ "Filter", @
/* Cancel label*/ "Cancel")
(filter label)
(filter mask)
(directory label) (files label)
(selection label)
(default selection)
(ok button label) (filter button label)

(cancel button label)
Note: The height of a file widget with 6 rows (lines) is FILE_6L_HGT.

122/252
Special Widgets
The File widget callback function is executed when the

Ok/Apply or Cancel button is selected.
The callback sends two string arguments, filename and status. If the
Ok/Apply button is selected then any text in the filename databox is
sent as a string and the status will be set to "OPEN". If the Cancel
button is selected then the status is set to "CANCEL".
Sample File Widget callback function

FUNCTION file_cb(filename, file_status)
STRING filename[], file_status[]
IF (file_status == "CANCEL") THEN

ui_form_hide("file_widgets_class") /* close the form */
RETURN
ELSE
/* Send the filename back to the calling function */
Calling_Class.put_filename(filename)
END IF
ui_form_hide("file_widgets_class")
END FUNCTION

123/252
Special Widgets
Spreadsheet Widget
The Spreadsheet widget was developed by MSC.Software for

use in MSC.Patran. The spreadsheet widget can be used for
displaying or entering data.
The spreadsheet widget performs a callback when a cell or
group of cells is selected. The starting and ending columns
and rows, and the layer if 3 dimensional, are returned as
callback function arguments.
To enter data into a spreadsheet, you will need to create a
databox.
Use the ui_spread_set_cell(s) functions to set the cells of
a particular spreadsheet.

124/252
Exercise 11: File Widget
Create a form with a file widget for use with your function that
writes nodal data (Exercise 4). Do the same for your function to
read nodal data (Exercise 5).
Extra Credit: Suppose your form with a file widget is a secondary
form, i.e., it is opened from a button on a primary or
main form. Typically, action occurs or a command is
executed when the Apply button on the main form
is pressed. How do you transfer the filename
information from the secondary form to the primary
form?

125/252
Adding Help/Description to your PCL
One way to add help to your PCL is to create your own form
which contains a text widget (ui_text_create).
An easier way is to use the shareware help functions
FUNCTION description_cb()
shareware_help.set_alltext(Aero Preference, @
PURPOSE:\n//@
For comments/remarks, send an email to:\n//@
elvis.mscsoftware.com)
END FUNCTION
Or, to read the help text from a file, use:

shareware_help.set_allinfile(Aero Preference, aero_help.txt)
126/252
Percent Complete
Functions
MSC.Patran provides PCL functions to allow the user to create,

update, and manage the percent complete form.
uil_pcntcomplete.initlz() is used to initialize the
percent complete form.
uil_pcntcomplete.update() is used to update the percent
complete form
uil_pcntcompete.close() is used to close the form. Dont
forget to close the form!
Example
FUNCTION calc_elm_normals(num_elms, elm_ids, normal_vec)
INTEGER i, num_elms, elm_ids()

REAL normal_vec()
STRING msg[80]
msg = Processing //str_from_integer(num_elms)// elements

uil_pcntcomplete.initlz(msg)
FOR (i = 1 to num_elms)
/* functions that calculate element normals */
uil_pcntcomplete.update(i*100.0/num_elms)
END FOR
uil_pcntcomplete.close()
RETURN (0)
END FUNCTION /* calc_elm_normals */

127/252
Event Manager
General
MSC.Patrans event manager performs the following functions:

Oversees program execution including coordination between
MSC.Patrans four functional areas, i.e., a) user interface, b)
applications, c) database, and d) graphics
First in first out
Controls heartbeat
From a PCL programming perspective, the event manager
primarily allows the programmer the ability to halt execution in
the event that the MSC.Patran user selects the Abort icon
during PCL execution
These functions are typically used in loops, i.e., FOR, WHILE,

or REPEAT.
It is up to the PCL programmer to decide what to do once the
user has elected to abort execution. In general, you may want
to execute the uil_db_undo() command to clean up any
created items, i.e., nodes, elements, property sets, etc.

128/252
Event Manager
Functions
em_proceed_normal() Returns FALSE if the user wants to

abort and TRUE if the user wants to continue. The user signals
his abort request by clicking the Abort icon and confirming his
abort request on the Abort Confirmation Window. Note that
this function allows the system to update/refresh graphics and
forms.
em_proceed_quick() Same as em_proceed_normal()

except that it doesnt allow the system to update/refresh
graphics.
em_synchronize() Synchronizes events and graphics
making sure everthing is uptodate. Does not handle aborts.
Example
FOR (i = 1 to num_elms)
IF (!em_proceed_normal()) THEN RETURN (-1)
/* statements that do something */
END FOR

129/252
Primitive Graphics
MSC.Patran provides a set of functions that can be used to

draw graphical primitives or objects (e.g., lines, arrows, text,
etc.) in the graphic viewports.
These routines allow PCL programmers the ability to provide
graphical feedback to the user.
Graphic Objects
At the present time, MSC.Patran provides functions for

drawing 5 graphical objects: lines, text, markers, arrows, and
result arrows.
gm_draw_line(SegmentId, ColorId, StartXYZ, EndXYZ)
gm_draw_text(SegmentId, ColorId, LocationXYZ, TextString)
gm_draw_marker(SegmentId, ColorId, LocationXYZ, MarkerType, @
MarkerSize)
gm_draw_arrow(SegmentId, ColorId, BaseXYZ, TipXYZ, HeadSize)
gm_draw_result_arrow(SegmentId, ColorId, LocationXYZ, Direction, @
ArrowSize, AnchorStyle, LabelString)
These graphic objects can be used to:

a) display/annotate results, LBCs, or other information
b) create a PCL function to perform labeling operations
c) create sketches of objects
All coordinates referenced by the graphics routines are
specified in world space, i.e., MSC.Patran global coordinates.
Each graphic object is added to a graphic segment. These
graphic segments are used to group, display, and delete the
graphic objects.

130/252
Primitive Graphics
Graphic Segments
Each graphic object is added to a graphic segment. These

graphic segments are used to group, display, and delete the
graphic objects.
There is no limit to how many graphic objects can be added to
a graphic segment.
Graphic objects are grouped into graphic segments by using a
common segment Id. Segments are created using the
gm_segment_create(SegmentId) function. Note that you do
not specify the SegmentId, but it is assigned by MSC.Patran.
Graphic objects are removed or deleted from the display by
deleting the appropriate graphic segment with the
gm_segment_delete(SegmentId) function.
The gm_segment_flush() function draws or flushes all
currently defined graphic segments to all viewports that
contain the current group (of the current viewport).
Graphic segments are automatically updated by MSC.Patran to
reflect changes in the orientation or position of the model in
the graphic viewport.
Using the MSC.Patran reset graphics or refresh graphics icons
will not remove primitive graphics. Only the
gm_segment_delete(SegmentId) function will remove
primitive graphics from MSC.Patran viewports.

131/252
Primitive Graphics
Example
INTEGER SegmentId
gm_segment_create(SegmentId)
gm_draw_line(SegmentId, 5, [0 0 0], [1 0 0])

gm_draw_text(SegmentId, 12, [0.5, 0.5, 0], Box)
gm_segment_flush()
Note that 2 different types of graphic

objects (lines and text) are both
included in the same graphic segment.
Very primitive
MSC.Patran PCL Workshop Notes graphics 05/05/17
132/252
Primitive Graphics
Another Example
FUNCTION Draw2DBox(ColorId, UpperLeft, LowerRight, SegmentId)
/*
Input ColorId INTEGER
UpperLeft(2) REAL
LowerRight(2) REAL
Output SegmentId INTEGER
<return value> INTEGER
*/
INTEGER ColorId, SegmentId

INTEGER status
REAL UpperLeft(), LowerRight()

REAL BoxCorners(4, 3)
IF (ColorId < 0 || ColorId > 15) THEN RETURN -1
BoxCorners(1, 1) = UpperLeft(1)
BoxCorners(1, 2) = LowerRight(2)
BoxCorners(1, 3) = 0.0
BoxCorners(2, 1:2) = LowerRight(1:2)

BoxCorners(3, 1) = LowerRight(1)
BoxCorners(3, 2) = UpperLeft(2)
BoxCorners(4, 1:2) = UpperLeft(1:2)

status = gm_segment_create(SegmentId)
status = gm_draw_line(SegmentId, ColorId, BoxCorners(1, 1:3), BoxCorners(2, 1:3))


133/252
status = gm_segment_flush()
RETURN 0
END FUNCTION /* Draw2DBox */

134/252
Exercise 12: Primitive Graphics
Create a form that uses primitive graphics to either:

a) Draw a line between two points, or
b) Label individual nodes.
Be sure to:
1) Use ui_colormenu_create() to allow the user to change
the color of the lines or labels
2) Use a select frame with an Auto Execute toggle
3) Have a Reset Graphics button that calls
gm_segment_delete() to erase the graphics.
You will use the following primitive graphic functions:
a) gm_segment_create()
b) Either gm_draw_line() or gm_draw_text()
c) gm_segment_flush()
d) gm_segment_delete()

135/252
MSC.Patran Customization
Adding Utility Programs to the Main Menu
Pulldown menus can be added to MSC.Patrans top menubar.

Individual items on the pulldown menu can be used to open
user-defined forms or other PCL functions.
Menubar on MSC.Patrans main or primary form.

Includes File, Group, etc. The widget Id is obtained via
uil_primary.get_menubar_id()
User-defined menu. This menu widget is a child

of MSC.Patrans main menubar widget. This
widget is created with the ui_menu_create()
function
Menu items are children of the user-defined menu

widget. These are added to the user-defined menu
with the ui_item_create() function. Functions are
executed based on item name passed to the menu
callback function.

136/252
Example
CLASS my_pulldown_menu
CLASSWIDE WIDGET user_menu
FUNCTION init()
WIDGET menubar
menubar = uil_primary.get_menubar_id()
user_menu = ui_menu_create(menubar, user_menu_cb, My_Menu)
ui_item_create(user_menu, hello_world, Hello World!, FALSE)

ui_item_create(user_menu, dump_nodes, Write Nodal Data, FALSE)
ui_item_create(user_menu, , , FALSE)
ui_item_create(user_menu, push_me, Push Me , FALSE)
ui_item_create(user_menu, football, Football Scores , FALSE)
ui_item_create(user_menu, group_by_shape, Group Elms By Shape , FALSE)
FUNCTION display()
/* Dummy display function. The display function is not really necessary
since the menubar is automatically displayed by MSC.Patran. */
The item name parameter is passed as an

FUNCTION user_menu_cb(item) argument to the callback function (user_menu_cb)
of the menu.
STRING item[]
SWITCH (item)
CASE (hello_world)
hello_world()
CASE (dump_nodes)
DumpNodes(MyFile.dat)
CASE (push_me)
ui_exec_function(push_me_form, display)
CASE (football)
ui_exec_function(football_scores, display)
CASE (group_by_shape)
ui_exec_function(group_elms_by_shape, display)
END SWITCH
END FUNCTION /* user_menu_cb */

137/252
END CLASS /* my_pulldown_menu */

138/252
If the Shareware, i.e., Utilities is loaded, adding user-defined

pulldown menus is even easier!
The Utilities pulldown menu is defined in a file called,
p3_user_menu.def.
In addition to adding the contents of the p3_user_menu.def file
to MSC.Patrans top menubar, the shareware will add additional
pulldown menus defined in files named, p3_user_menu.*.def,
i.e., p3_user_menu.4me.def.
Up to 3 additional pulldown menus can be defined.
The shareware looks for p3_user_menu.*.def files in your
current directory, home directory, MSC.Patran installation
directory, and the shareware directory.
Example: p3_user_menu.my_menu.def
Menu label
*MENU LABEL = My_Menu
*CLASS = -NA-
*FUNCTION = hello_world Executes a function that is not
*LABEL = Hello World! contained within a PCL Class. The
*LOAD ITEM function cannot have any
arguments.
*SEPARATOR
*CLASS = push_me_form
*FUNCTION = display
*LABEL = Push Me Opens a form via the
*LOAD ITEM ui_exec_function(classname, function) command.
*CLASS = football_scores Example:

*FUNCTION = display ui_exec_function(football_scores, display)
*LABEL = Football Scores
*LOAD ITEM
*CLASS = group_elms_by_shape
*FUNCTION = display
*LABEL = Group Elms By Shape
*LOAD ITEM Pulldown menus are designed to
open forms. This is why selecting a
menu item executes:
ui_exec_function()
139/252
140/252
Customizing the MSC.Patran Toolbar
MSC.Patrans toolbar is controlled by a file called

p3toolbar.def.
MSC.Patran looks for this file first in your home directory and
then in the MSC.Patran installation directory.
The file format is very similar to the format used for the
p3_user_menu.def file.
PCL function that will be executed is:
*ICON = tbrotatexy.28.icon uil_toolbar.rotate_xy()
*CLASS = uil_toolbar
*FUNCTION = rotate_xy Toolbar icons are designed to
*HELP = Mouse rotate XY perform an action. This is why
*LOAD ITEM selecting an icon executes the
classname.function() instead of
ui_exec_function()
*ICON = tbploterase.icon
*CLASS =
*FUNCTION = tbd(uil_imaging_plot_erase)
*HELP = Plot/Erase form (Display menu)
*LOAD ITEM
Executes the function tbd(classname). The tbd functon in turn

executes: ui_exec_function(classname, display), i.e.,
the tbd function is used to open a form from the toolbar.

141/252
If you use an icon that is not in the MSC.Patran icons directory

then you will need to define the location of the icon file in the
p3midilog.pcl file. Typically, the p3midilog.pcl file would be
located in your home directory.
Toolbar icons can be any size. However, all icons on the
default toolbar are 28x28 (pixels) on UNIX and 16x16 on NT.
For UNIX (i.e., Motif), the icons are in xbm format. For NT, the
icons can be in either xbm format or bmp format (bitmap).
On UNIX, the icons must be black and white. On NT, the icons
can be color if the bmp format is used.
On UNIX workstations, a program like bitmap can be used to
create the icons.
On a PC, a program like Microsoft Windows Paint can be used
to create the icons.

142/252
To add your own toolbar function/icon

1)Create the PCL function and compile it into a library if it
does not exist.
2)Make sure there are proper entries in your p3epilog.pcl file
that tell MSC.Patran where to find the library that contains
your function.
3)Create an icon by editing one of the existing toolbar icons
using bitmap or its equivalent.
4)Add appropriate statements to your p3toolbar.def file.
5)Add a !!PATH statement to your p3midilog.pcl file telling
MSC.Patran where to look for the icon file.

143/252
Exercise 13: Pulldown Menu
Create a p3_user_menu.pat304.def file in your home directory that

adds a pulldown menu to MSC.Patran called PAT304 that allows
you to access all of the PCL programs that you have written in this
class.
The p3_user_menu.pat304.def file should use the following lines:

a) *MENU LABEL = PAT304
b) *ALWAYS ENABLED = FALSE
c) *CLASS
d) *FUNCTION
e) *LABEL
f) *END FUNCTION
Optionally, you may include:

a) *CASCADE MENU
b) *CASCADE END
c) *SEPARATOR

144/252
Exercise 14: Toolbar
Add a toolbar icon to MSC.Patrans toolbar that lets you toggle

between 2 views.
You will use the ga_view_aa_set(rot_x, rot_y, rot_z)

function to define the views. This function sets the view by
defining the absolute x, y, and z angles of rotation about the
MSC.Patran global model axes. The variables, rot_x, etc. are in
degrees.
You can define an icon if you like. However, MSC.Patran will use a
default icon if you supply an icon filename that MSC.Patran cannot
find in the p3toolbar.def file, i.e., this_does_not_exist.icon.
Basically, this exercise consists of:
1) Writing PCL code to toggle between 2 views (see next
page).
2) Compile this code into your pat304.plb PCL library.
3) Create an icon (optional).
4) If the icon file is not in your home directory, you will need to
create a p3midilog.pcl file that contains:
!!PATH /my/path/to/the/icons
5) Edit your p3toolbar.def file, adding lines for the definition
of:
*ICON, *CLASS, *FUNCTION, *HELP, and *LOAD ITEM.

145/252
CLASS pat304_toolbar_view
CLASSWIDE LOGICAL flag /* flag will initially be FALSE */
FUNCTION toggle_view()
/* these represent rotations in degrees */

REAL rot_x, rot_y, rot_z
IF (flag) THEN
/* aircraft front view */
rot_x = -90.0
rot_y = 0.0
rot_z = 90.0
ELSE
/* aircraft rhs view */
rot_x = -90.0
rot_y = 0.0
rot_z = 180.0
END IF
/* echo this to the session file */

> ga_view_aa_set(rot_x, rot_y, rot_z)
flag = !flag
/* flag is remembered between calls because it is

a classwide variable */
END FUNCTION /* toggle_view */
END CLASS /* pat304_toolbar_view */

146/252
147/252
Some Final Thoughts
1) Remember that there are exceptions to all rules and sometimes

there are even exceptions to the exceptions.
2) Remember that PCL is not a compiled language (like C or
FORTRAN) but is an interpretive language (like BASIC).
3) In real estate it is location, location, location. However, to
increase the performance of your PCL it is minimize database
hits, minimize database hits, minimize database hits. The best
way to increase the performance of your PCL function is to
minimize database hits. The best way to minimize database hits
is to move db_get_xxxx() or db_create_yyyy() statements
outside of loops. Instead of getting data or creating entities one
at time, it is better to get data for all selected entities with one
database call and hold the data in an array until needed.
Likewise, if you are creating entities, it is generally better to
gather data in arrays and then create the entities all at once
instead of creating them one at a time.
4) Utilize the PCL built-in functions. These functions are written in
C or FORTRAN and are fast. As an example, instead of
calculating beam element length by hand (get beam element
nodes, get nodal coordinates, calculate length), utilize the
fem_geom_edge_length() function instead.
5) If all else fails, see rule (1).

148/252
Some Final Thoughts
FUNCTION good_function(num_bars, bar_ids, bar_len)
/* This function calculates the length of 2-noded bar elements. */
/* This function is perfectly acceptable but is not very efficient

from a PCL programming point of view because it accesses the
database 2*num_bars times (once for each bar to get the bar nodes
and then once for each bar to get the bar node coordinates). Note
that this function may actually access the same nodal coordinate
data many times if the bars all connect at the same node.*/
INTEGER i, j, status
INTEGER num_bars, bar_ids()
INTEGER elm_connect(1, 2)
INTEGER rcids(1), acids(1)
REAL bar_len()
REAL xyz(2, 3)
REAL sum
FOR (i = 1 to num_bars)
status = db_get_node_for_elems(1, 2, bar_ids(i:i), elm_connect)
IF (status != 0) THEN RETURN (status)
status = db_get_nodes(2, elm_connect(1, 1:2), rcids, acids, xyz)

sum = 0.0
FOR (j = 1 to 3)
sum += (xyz(2, j) xyz(1, j))**2
END FOR
IF (sum > 0.0) THEN

bar_len(i) = mth_sqrt(sum)
ELSE
bar_len(i) = 0.0
END IF
END FOR
RETURN (0)
END FUNCTION

149/252
Some Final Thoughts
FUNCTION better_function(num_bars, bar_ids, bar_len)
/* This function calculates the length of 2-noded bar elements. */
/* This function is better than the previous function because it

only accesses the database 2 times regardless of how many
bar elements are entered.*/
INTEGER i, j, p1, p2, status

INTEGER num_bars, bar_ids()
INTEGER elm_connect(VIRTUAL)
INTEGER num_nodes, node_ids(VIRTUAL)
INTEGER idum(VIRTUAL)
REAL bar_len()
REAL xyz(VIRTUAL)
REAL sum
sys_allocate_array(elm_connect, 1, num_bars, 1, 2)
status = db_get_node_for_elems(num_nodes, 2, bar_ids, elm_connect)

sys_allocate_array(node_ids, 1, 2*num_bars)
sys_move_raw(elm_connect, node_ids)
mth_sort(node_ids, TRUE, num_nodes)

sys_reallocate_array(node_ids, 1, num_nodes)
sys_allocate_array(idum, 1, num_nodes)
sys_allocate_array(xyz, 1, num_nodes, 1, 3)
status = db_get_nodes(num_nodes, node_ids, idum, idum, xyz)

FOR (i = 1 to num_bars)
p1 = mth_array_search(node_ids, elm_connect(i, 1), TRUE)
p2 = mth_array_search(node_ids, elm_connect(i, 2), TRUE)
sum = 0.0
FOR (j = 1 to 3)
sum += (xyz(p2, j) xyz(p1, j))**2
END FOR

150/252
IF (sum > 0.0) THEN
bar_len(i) = mth_sqrt(sum)
ELSE
bar_len(i) = 0.0
END IF
END FOR
RETURN (0)
END FUNCTION

151/252
Appendix A
Built-in Function Examples

152/252
Appendix A
Documentation for a typical MSC.Patran built-in

function.
db_get_nodes(num_nodes, node_ids, rcids, acids, global_xyz)
This function gets nodal coordinate frames and coordinates for the
requested nodes.
Input
INTEGER num_nodes Number of nodes to get
information for
INTEGER ARRAY node_ids(num_nodes) Node Ids of nodes to get
information for
Output
INTEGER ARRAY rcids(num_nodes) Reference coordinate frame Ids
INTEGER ARRAY acids(num_nodes) Analysis coordinate frame Ids
REAL ARRAY global_xyz(num_nodes, 3) Global coordinates for each
node
INTEGER <return value> The function returns a value of 0
when executed successfully and
a non-zero value to indicate a
change in status or an error
Notes: The C name differs. It is DbFGetNodes.

int DbFGetNodes(num_nodes, node_ids, rcids, acids, global_xyz)
int num_nodes
int *node_ids
int *rcids
int *acids
float *global_xyz

153/252
Appendix A
To get all the nodes and their global coordinates
INTEGER NumNodes, NodeIds(VIRTUAL), rcids(VIRTUAL), acids(VIRTUAL)

REAL NodeXYZ(VIRTUAL)
IF (NumNodes == 0) THEN RETURN 1
sys_allocate_array(NodeIds, 1, NumNodes)
sys_allocate_array(rcids, 1, NumNodes)
sys_allocate_array(acids, 1, NumNodes)
sys_allocate_array(NodeXYZ, 1, NumNodes, 1, 3)
db_get_nodes(NumNodes, NodeIds, rcids, acids, NodeXYZ)
Essentially, the MSC.Patran database is comprised of a series

of tables. Hence, the db_get_nodes() function is simply
accessing data from a nodal data table, i.e.,
Node
RC ID RCID
AC ACID X Y Z
2 0 0 0.00 0.00 0.00
5 0 2 5.12 -6.34 4.90
25 1 1 56.20 9.01 -1.10

154/252
Appendix A
To get the topology of every element
INTEGER NumElms, ElmIds(VIRTUAL), ElmTopoCodes(VIRTUAL)
IF (NumElms == 0) THEN RETURN 1
sys_allocate_array(ElmIds, 1, NumElms)
sys_allocate_array(ElmTopoCodes, 1, NumElms)
db_get_elem_etop(NumElms, ElmIds, ElmTopoCodes)
An elements topology is a term used to describe the combination

of the elements shape and the number of nodes used to define the
element connectivity, i.e., 4-node and 8-node quadrilateral
elements have the same shape but have different topologies.
To determine the MSC.Patran topology Ids for a particular element
shape and connectivity, use the fem_get_patran25_etop()
function, i.e.,
INTEGER ShapeCode, NumNodesPerElm, ElmTopoCode
fem_get_patran25_etop(ShapeCode, NumNodesPerElm, ElmTopoCode)
Elm Shape Shape Code Elm Shape Shape Code

Point 1 Tet 5
Bar 2 Pyramid NA
155/252
Tria 3 Wedge 7
Quad 4 Hex 8

156/252
Appendix A
To get the shape of every element

INTEGER ElmShapeCodes(VIRTUAL), NumNodesPerElm(VIRTUAL)
sys_allocate_array(ElmShapeCodes, 1, NumElms)
sys_allocate_array(NumNodesPerElm, 1, NumElms)
db_get_elem_topology_data(NumElms, ElmTopoCodes, ElmShapeCodes, @

NumNodesPerElm)

157/252
Appendix A
To get all the element connectivity for all elements

INTEGER ElmShapeCodes(VIRTUAL), NumNodesPerElm(VIRTUAL)
INTEGER MaxNodesPerElm, ElmConnect(VIRTUAL)
sys_allocate_array(ElmShapeCodes, 1, NumElms)
sys_allocate_array(NumNodesPerElm, 1, NumElms)
db_get_elem_topology_data(NumElms, ElmTopoCodes, ElmShapeCodes, @

NumNodesPerElm)
sys_free_array(ElmTopoCodes)
sys_free_array(ElmShapeCodes)
mth_sort(NumNodesPerElm, FALSE, NumElms)
MaxNodesPerElm = NumNodesPerElm(NumElms)
sys_free_array(NumNodesPerElm)
sys_allocate_array(ElmConnect, 1, NumElms, 1, MaxNodesPerElm)
db_get_nodes_for_elems(NumElms, MaxNodesPerElm, ElmIds, @

ElmConnect)

158/252
Appendix A
To get the elements associated to a particular

element property set
FUNCTION GetElmsForPropSet(MyPropertySetName, NumElms, ElmIds)
INTEGER i
INTEGER NumElms, ElmIds()
INTEGER NumRegions, RegionIds(VIRTUAL)
INTEGER MyRegionId
LOGICAL match
STRING MyPropertySetName[]
STRING RegionNames[32](VIRTUAL)
db_count_region_ids(NumRegions)
sys_allocate_array(RegionNames, 1, NumRegions)
sys_allocate_array(RegionIds, 1, NumRegions)
db_get_region_ids_and_names(NumRegions, RegionIds, RegionNames)
match = FALSE
FOR (i = 1 to NumRegions)
IF (str_equal(MyPropertySetName, RegionNames(i))) THEN
match = TRUE
MyRegionId = RegionIds(i)
BREAK
END IF
END FOR
sys_free_array(RegionIds)
sys_free_array(RegionNames)
IF (!match) THEN RETURN 1
db_count_elements_in_region(MyRegionId, NumElms)

159/252
db_get_elements_in_region(MyRegionId, NumElms, ElmIds)
RETURN 0
END FUNCTION

160/252
Appendix A
To get an element property value (shell thickness) for

a specific element
Many people loosely refer to an element property set as simply the element
properties. Internally, MSC.Patran distinguishes between the property set
and the properties by calling the property set a region. Hence a region is a
collection of elements (physical region of the model) and their associated
properties (shell thickness, material, orientation, etc.).
FUNCTION get_shell_thickness(ElmId, ElmThick)
INTEGER p
INTEGER ElmId
INTEGER ElmIds(1), ElmRegionIds(1)
INTEGER MaterialId, DataType, IntegerVal, CoordId, NodeId, FieldId
REAL ElmThick, ThickVals(VIRTUAL)
REAL RealVals(3)
STRING CharVal[80]
ElmIds(1) = ElmId
db_get_region_for_elements(1, ElmIds, ElmRegionIds) 36 is the property word Id for
thickness. Other property words
and their associated Ids can be
db_count_prop(ElmRegionIds, NumWords) found listed in the table of generic
property words in Chapter 7 of the
IF (NumWords == 0) THEN RETURN 1 PCL and Customization
documentation.
sys_allocate_array(WordIds, 1, NumWords)
db_get_props_by_region(NumWords, ElmRegionIds, WordIds)
p = mth_array_search(WordIds, 36, FALSE)

IF (p == 0) THEN RETURN 1
db_get_prop_value(ElmRegionIds(1), 36, MaterialId, DataType, @

IntegerVal, RealVals, CharVal, CoordId, NodeId, FieldId)
IF (DataType == 1) THEN /* real scalar at elm centroid */

ElmThick = RealVals(1)
ELSE IF (DataType == -1) THEN /* real scalar field at elm centroid */
MyFunc_EvalScalarFieldCentroid(ElmId, FieldId, ElmThick)
ELSE IF (DataType == -7) THEN /* real scalar field at elm nodes */
MyFunc_EvalScalarFieldNodes(ElmId, FieldId, ElmThick)
ELSE
RETURN -1 1 Real scalar at elem centroid 6 List of real values
END IF 2 Real vector 7 Real scalar at elem nodes
3 Integer 8 Node reference
4 Character string 9 Coordinate frame reference
MSC.Patran PCL Workshop Notes 5 Material reference 11 05/05/17
Section ID (dimensions)
12 161/252
Section ID (properties)
Negative datatypes denote field reference.

RETURN 0
END FUNCTION

162/252
Appendix A
There are many other ways to accomplish this same task. The
preceding function is very general and very detailed. If the
element property set references a field for the shell thickness
definition, then functions to evaluate the fields
(MyFunc_EvalScalarFieldCentroid() and
MyFunc_EvalScalarFieldNodes()) will need to be written. If the
shell thickness is only defined at the element centroid, then the
ep_word_val_at_el_cen() function can be used. This function has
an advantage over the previous example in that this function
automatically evaluates any field reference.
FUNCTION get_shell_thickness(ElmId, ElmThick)
INTEGER ElmId, ElmIds(1)

INTEGER NumFoundElms, FoundElmIds(VIRTUAL)
See note on previous page
REAL ElmThick, ThickVals(VIRTUAL)
ElmIds(1) = ElmId
ep_word_val_at_el_cen(36, 1, 1, ElmIds, NumFoundElms, @

FoundElmIds, ThickVals)
IF (NumFoundElms == 0) THEN RETURN -1
p = mth_array_search(FoundElmIds, ElmId, FALSE)

IF (p == 0) THEN RETURN -1
ElmThick = ThickVals(p)
RETURN 0
END FUNCTION

163/252
164/252
Appendix A
To get a material property value
FUNCTION get_elastic_modulus(MatlName, ElasticModulus)
INTEGER MatlId
REAL ElasticModulus
STRING MatlName[]
db_get_material_id_from_name(MatlName, MatlId)
db_get_matl_prop_value_count(MatlId, NumWords)
IF (NumWords == 0) THEN RETURN 1
sys_allocate_array(WordIds, 1, NumWords)
sys_allocate_array(FieldIds, 1, NumWords)
sys_allocate_array(WordVals, 1, NumWords)
db_get_matl_prop_value(MatlId, WordIds, FieldIds, WordVals)
p = mth_array_search(WordIds, 2, FALSE)
IF (p == 0) THEN RETURN 1
2 is the material property
word Id for the Elastic
IF (FieldIds(p) != 0) THEN Modulus. Other material
/* Elastic Modulus is defined property word Ids can be
by a field */ found in the table of Material
ELSE Property Words in Chapter 7
of the PCL and Customization
ElasticModulus = WordVals(p) documentation.
END IF
RETURN 0
END FUNCTION

165/252
An alternate method of extracting the Elastic Modulus for a
material makes use of the db_get_matl_prop_value2()
function. The advantage of using this function is that it will
automatically evaluate any field references.

166/252
Appendix A
To get a list of all groups
INTEGER NumGroups
STRING GroupNames[32](VIRTUAL)
ga_group_ngroups_get(NumGroups)
/* There is always at least one group */
sys_allocate_array(GroupNames, 1, NumGroups)
ga_group_groups_get(Group_names)
To get the nodes and elements associated to the

current group
INTEGER GroupId
INTEGER NumNodes, NodeIds(VIRTUAL), NumElms, ElmIds(VIRTUAL)
STRING CurrentGroup[32]
ga_group_current_get(CurrentGroup)
db_get_group_id(CurrentGroup, GroupId)
db_count_nodes_in_group(GroupId, NumNodes)
IF (NumNodes > 0) THEN

sys_allocate_array(NodeIds, 1, NumNodes)
db_get_all_node_ids_in_group(NumNodes, GroupId, NodeIds)
END IF
db_count_elems_in_group(GroupId, NumElms)

167/252
IF (NumElms > 0) THEN
db_get_elem_ids_in_group(NumElms, GroupId, ElmIds)
END IF

168/252
Appendix A
To get result values for specified elements
To access elemental results you need to know:

1) Element Ids
2) Resultcase
3) Result type
4) Position or Layer
5) Result quantity
6) Location within the element
7) Coordinate reference

169/252
Appendix A
Before looking at the PCL command to extract results,

lets correlate items 1-7 with the MSC.Patran result forms.
This correlation is not quite one-to-one. However, it
hopefully provides a familiar reference.
Resultcase
Result type
Position or layer
Result quantity

170/252
Appendix A
Element Ids
Coordinate reference

171/252
Appendix A
Element results are calculated at various points within the

element depending on the analysis code, element type, etc.
Generally element results are calculated at either the element:
Centroid
Integration or Gauss points
Nodes

172/252
Appendix A
Resultcase names are comprised of 2 components, a loadcase

name and a subcase name. Each of these has an associated
internal Id. These are called the loadcase Id and subcase Id,
respectively.
db_get_load_case_title(lc_id, lc_name)
INPUT: lc_id INTEGER
OUTPUT: lc_name STRING
db_get_load_case_id(lc_name, lc_id)
INPUT: lc_name STRING
OUTPUT: lc_id INTEGER
db_get_sub_case_title(lc_id, sc_id, sc_name)

db_get_sub_case_id(lc_id, sc_name, sc_id)
res_utl_get_loadcases(num_rc, lc_ids, num_sc_per_lc)
INPUT: num_rc INTEGER
lc_ids INTEGER ARRAY
OUTPUT: num_sc_per_lc INTEGER ARRAY
res_utl_get_subcases(lc_id, num_sc, sc_ids)

OUTPUT: num_sc INTEGER
sc_ids INTEGER ARRAY
res_data_bulk_get_loadcases(num_rc, lc_ids, sc_ids, @

coordinates, rc_names)
INPUT: <None>
OUTPUT: num_rc INTEGER
coordinates INTEGER_ARRAY
rc_names STRING ARRAY
Alternately, many functions refer to the resultcase via a

resultcase Id.
res_db_cget_rescases(num_rc, lc_ids, sc_ids, rc_ids)
OUTPUT: rc_ids INTEGER ARRYA

173/252
Appendix A
Result type names are also comprised ot 2 components, a

primary and a secondary label. Each of these has an
associated internal Id. These are called the primary label Id
and the secondary label Id.
db_get_primary_res_label(prim_id, prim_label)
INPUT: prim_id INTEGER
OUTPUT: prim_label STRING
db_get_primary_res_id(prim_label, prim_id)
INPUT: prim_label STRING
OUTPUT: prim_id INTEGER
db_get_secondary_res_label(prim_id, sec_id, sec_label)

sec_id INTEGER
OUTPUT: sec_label STRING
db_get_secondary_res_id(prim_id, sec_label, sec_id)

sec_label STRING
OUTPUT: sec_id INTEGER
res_data_get_result_names(prim_id, sec_id, @
prim_label, sec_label)
sec_id INTEGER
OUTPUT: prim_label STRING
sec_label STRING
res_data_get_result_ids(prim_label, sec_label, @
prim_id, sec_id)
res_utl_get_result_ids(num_rc, lc_ids, sc_ids, @
num_res, prim_ids, sec_ids)
OUTPUT: num_res INTEGER
prim_ids INTEGER ARRAY
sec_ids INTEGER ARRAY

174/252
Appendix A
Alternately, some functions refer to the result type via the

result type Id instead of the primary and secondary Ids
rt_id = vki_db_getresid(lc_id, prim_id, sec_id)
prim_id INTEGER
sec_id INTEGER
OUTPUT: rt_id INTEGER
res_data_get_restype_ids(rt_id, prim_id, sec_id)

INPUT: rt_id INTEGER
OUTPUT: prim_id NTEGER
sec_id INTEGER
Layers or positions can be accessed via the following

functions
res_utl_get_result_types(res_ids, num_layers, @
layer_ids, layer_labels)
INPUT: res_ids(4) INTEGER ARRAY, lc_id, sc_id, prim_id, sec_id
OUTPUT: num_layers INTEGER
layer_ids INTEGER ARRAY
layer_labels STRING ARRAY
res_data_get_layerpos_name(layer_id, layer_name)
INPUT: layer_id INTEGER
OUTPUT: layer_name STRING
res_data_get_layerpos_id(layer_name, layer_id)

175/252
Appendix A
Following is a description of the function used to extract

element results. Similar functions exist for extracting nodal
results and/or creating either element or nodal results.
res_utl_extract_elem_results(ResIds, ElmList, Derivation, Location, @

CID, DataType, ResLoc, Nres, Ids, @
Nresults, ResVals, MinLoc, MaxLoc)
INPUT
INTEGER ResIds(5) MSC.Patran internal loadcase ID,
subcase ID, primary result ID,
secondary result ID, and layer ID.
STRING ElmList[] List of elements to extract results
for.
STRING Derivation[10] Derivation specifier if the results
are to be derived, i.e., VONM,
MAJOR, etc. A null value () will
leave the result as is.
STRING Location[] Location at which to extract the
results. Null () or A=as is,
C=element centroid, and
N=element nodes.
STRING CID[] Coordinate system for vector and
tensor transformations. A null
string () is used to leave the
coordinate specification as is.
OUTPUT
INTEGER DataType Datatype for extracted results.
Valid values are: 1=scalar,
2=vector, and 3=tensor. Note that
the Derivation parameter determines
what this value should be, i.e., if
the Derivation is VONM for the
VonMises stress then the DataType
will be 1 for a scalar value.
INTEGER ResLoc Location within the element for the
extracted results. Valid values
are: 1=centroid, 2=nodal, and

176/252
3=multiple. Note that the Location
parameter essentially determines
what this value should be. If the
Location is specified as C for
centroid, then the ResLoc parameter
should return as 1. ResLoc is most
useful if the requested Location is
A or As is. In this case,
ResLoc will indicate where
MSC.Patran has results stored for
this particular set of elements,
i.e., if Location=A and ResLoc=2
then you know that these elements
have element nodal results.
INTEGER Nres Number of returned element
identifiers
INTEGER Ids(VIRTUAL) Array of element identifiers
INTEGER Nresults(VIRTUAL) Number of results per element
REAL ResVals(VIRTUAL) Result values at the specified
element locations
INTEGER MinLoc(12) Offsets within the ResVals array
for each minimum result component.
INTEGER MaxLoc(12) Offsets within the ResVals array
for each maximum result component.

177/252
Appendix B
Strings & String Functions

178/252
Appendix B
Declaration
STRING GroupName[32], Filename[256]
STRING GroupNames[32](VIRTUAL)
STRING Names[80](3)
STRING picklist[VIRTUAL]
Initialization
GroupName = MyGroup
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

179/252
Appendix B
Functions
str_length(MyString)
DESCRIPTION
Returns the current length of a PCL string.
INPUT
MyString String[] String for which to
return the length.
OUTPUT
<return value> Integer Length of MyString.
EXAMPLE
length = str_length(abcde)
length -> 5

180/252
Appendix B
str_substr(MyString, Position, Length)
DESCRIPTION
Return a portion of the input string from the specified
position of the specified length.
INPUT
MyString String[] String to extract the
substring from. The input
string is not modified.
Position Integer Starting position in the
string where 1 is the
first position.
Length Integer Number of characters to
extract
OUTPUT
<return value> String[] Extracted substring of the
input string.
EXAMPLES
NewString = str_substr(abcde, 1, 2)
NewString -> ab
NewString2 = str_substr(abcde, 4, 10)
NewString2 -> de

181/252
Appendix B
str_assign(MyString, Position, Length, MyString2)
DESCRIPTION
Replace a portion of a string with another string.
INPUT
MyString String[] Original string to be
modified. This parameter will
be modified.
Position Integer Starting position within
MyString where insertion will
take place.
Length Integer Number of characters to be
replaced.
MyString2 String[] String that will be
substituted into MyString.
OUTPUT
MyString String[] The original string (MyString)
with a portion of MyString
replaced by MyString2.
EXAMPLES
MyString = abxyzf
str_assign(MyString, 3, 3, cde)
MyString -> abcdef

182/252
Appendix B
str_index(MyString1, MyString2)
DESCRIPTION
Return the position where a string is found within another
string.
INPUT
MyString1 String[] String within which to find an
occurrence of the second
string.
MyString2 String[] String to look for within the
first string.
OUTPUT
<return value> Integer Position where MyString2 was
found within MyString1 where 1
is the first position. Zero is
returned if the string is not
found
EXAMPLES
Position = str_index(abcdef, cde)
Position -> 3
Position = str_index(abcdef, xyz)
Position -> 0

183/252
Appendix B
str_token(MyString, Delimiter, Ntoken[, Compress])
DESCRIPTION
Extracts a token (a sequence of characters) marked off by a
delimiting character from a string.
INPUT
MyString String[] Source string from which the
string tokens will be
extracted.
Delimiter String[1] Single character token string.
Ntoken Integer Which token to extract. This
must be at least 1.
Compress Logical Optional. If TRUE then empty
tokens will be ignored.
OUTPUT
<return value> String[] Extracted token string from
the input string. Leading and
trailing spaces are deleted if
the delimiter is not a space.
EXAMPLE
TmpString = str_token(abc, def, hij, ,, 2)
TmpString -> def
TmpString2 = str_token(*CLASS = MyClass, =, 2)
TmpString2 -> MyClass

184/252
Appendix B
str_strip_lead(MyString)
DESCRIPTION
Return a copy of the string with the leading spaces removed.
INPUT
MyString String[] Input string with
leading spaces.
OUTPUT
<return value> String[] Output string with no
leading spaces.
EXAMPLE
MyString2 = str_strip_lead( a b c)
MyString2 -> a b c
str_strip_trail(MyString)
DESCRIPTION
Return a copy of the string with the trailing spaces
removed.
INPUT
MyString String[] Input string with
trailing spaces.
OUTPUT
<return value> String[] Output string with no
trailing spaces.
EXAMPLE
MyString2 = str_strip_trail( a b c )
MyString2 -> a b c

185/252
Appendix B
str_to_integer(MyString[, status])
DESCRIPTION
Convert a string to an integer.
INPUT
MyString String[] Input string.
OUTPUT
status Integer Optional. Zero for
success or the position
within MyString where
the first invalid
character occurs.
<return value> Integer Integer value.
EXAMPLE
ival = str_to_integer(12)
ival -> 12
str_from_integer(ival)
DESCRIPTION
Convert an integer to a string.
INPUT
ival Integer Input integer value.
OUTPUT
<return value> String[] String value.
EXAMPLE
MyString = str_from_integer(12)
MyString -> 12

186/252
Appendix B
str_datatype(MyString)
DESCRIPTION
Attempt to decipher the datatype contained in a string.
INPUT
MyString String Input string.
OUTPUT
<return value> String[] String representing the
datatype, i.e.,
INTEGER, REAL,
LOGICAL, or STRING.
OTHER FUNCTIONS
str_to_real(MyString[, status])
str_from_real(RealValue)
str_to_logical(MyString)
str_from_logical(LogicalValue)

187/252
Appendix C
Noteworthy Functions

188/252
Appendix C
sys_move_raw()
sys_move_raw(source, destination)
DESCRIPTION
Move one raw PCL variable to another. This is a great
function to use when transferring the contents of one array
to another array. It is significantly faster than a loop.
INPUT
source Any Source variable to copy.
OUTPUT
destination Any Destination variable to receive
the copy of the source variable.
EXAMPLE
INTEGER a(12), b(12), c(6, 12), d(24)
sys_move_raw(a, b)
sys_move_raw(a, c(1, 1:))
sys_move_raw(a, c(1, 1:12))
sys_move_raw(a(1:), c(1, 1:))
sys_move_raw(a, c(2, 1:12))
sys_move_raw(a, d(1:12))
sys_move_raw(a, d(13:))

189/252
Appendix C
mth_array_search()
mth_array_search(IntegerArray, Look4, Sorted)
DESCRIPTION
Search an integer array for a value.
INPUT
IntegerArray Integer array Integer array of values
to search.
Look4 Integer Value to look for within
the IntegerArray
Sorted Logical TRUE if the input array
is sorted. This makes
the search faster.
OUTPUT
<return value> Integer Array index indicating
the position within
IntegerArray where the
Look4 value was found.
Zero if the value was
not found
EXAMPLES
INTEGER p
INTEGER a(4) = [1, 5, 2, 3]
p = mth_array_search(a, 2, FALSE)
p -> 3, i.e., a(3) = 2
p = mth_array_search(a, 12, FALSE)
p -> 0, i.e., a(i) != 12

190/252
Appendix C
mth_sort()
mth_sort(Array, RemoveDuplicates, NumLeft)
DESCRIPTION
This function will sort an array of integers into ascending
order, optionally removing all duplicates.
INPUT
Array Integer array Integer array to be
sorted. This argument
is used for both input
and output. The
contents of the
original array are
destroyed and replaced
by the sorted values.
RemoveDuplicates Logical When set to TRUE,
duplicate values are
removed.
OUTPUT
Array Integer array Input array in sorted
order.
NumLeft Integer Number of items in the
sorted array.
EXAMPLE
INTEGER a(4) = [5, 1, 9, 8]
INTEGER NumLeft
mth_sort(a, TRUE, NumLeft)
a(1:4) -> 1, 5, 8, 9
NumLeft -> 4

191/252
Appendix C
mth_sort_row()
mth_row_sort(Array, Row, Ascend)
DESCRIPTION
Sorts a two-dimensional integer or real array by one of its
rows.
INPUT
Array Integer or Real Matrix of values to sort.
array This is both the input and
output array.
Row Integer Row Id to sort on.
Ascend Logical If TRUE, then sort in
ascending order.
OUTPUT
Array Integer or Real Matrix is sorted in place.
array
EXAMPLE
INTEGER a(2, 3) = [3, 1, 2, 4, 5, 6]
mth_row_sort(a, 1, TRUE)
a() -> [1, 2, 3, 5, 6, 4]
mth_sort_column()
mth_sort_column(Array, Column, Ascend)
DESCRIPTION
Sorts a two-dimensional integer or real array by one of its
columns.

192/252
Appendix C
fem_geom_edge_length()
fem_geom_edge_length(PickList, Lengths, NumLengths)
DESCRIPTION
Determines the length of bar elements and/or element edges.
INPUT
PickList String[] String of bar element Ids
or element edges (elm 1.1).
OUTPUT
Lengths(virtual) Real array Length of each entity in
PickList.
NumLengths Integer Number of entities
contained in PickList.
<return value> Integer Zero for success
fem_geom_face_area()
fem_geom_face_area(PickList, Areas, NumAreas)
DESCRIPTION
Returns the face area of 2D elements or 3D element faces.
fem_geom_elem_volume()
fem_geom_elem_volume(PickList, Volumes, NumVolumes)
DESCRIPTION
Returns the volumes of 3D elements.

193/252
Appendix C
fem_geom_elem_location()
fem_geom_elem_location(PickList, Locations, NumLocations)
DESCRIPTION
Returns the location of the centroid of elements, element
edges, etc.

194/252
Appendix D
Form Spacing Parameters

(appforms.p)

195/252
Appendix D
* SPACING
*
*
* Spacing should be done relative to the active font height in system.
* A "single_space" is simply one font height. The "inter_widget_space"
* should be used as the spacing between widgets in a frame. It is
* three quarters of a font height.
*
*
* Spacing variables:
*
* INTER_WIDGET_SPACE - 3/4 of a font height
* INTER_GROUP_SPACE - Twice the size of a "inter_widget_space"
*
* SINGLE_SPACE - A font height in inches
* QTR_SPACE - 1/4 of a font height
* HALF_SPACE - 1/2 of a font height
* THREE_QTR_SPACE - 3/4 of a font height
* ONE_AND_HALF_SPACE - 1.5 times a font height
* DOUBLE_SPACE - 2.0 times a font height
*
* FONT_HGT - Font height in inches
* TEXT_FONT_HGT - Text font height in inches
* SS_FONT_HGT - Spreadsheet font height in inches
*
* LINE_THICKNESS - Thickness of a separator
* FRAME_1EDGE - Thickness of a frame edge
* FRAME_2EDGE - Thickness of both frame edges
* SFRAME_1EDGE - Thickness of a select frame edge
* SFRAME_2EDGE - Thickness of both select frame edges
* SCROLL_FRAME_1EDGE - Thickness of a scroll frame edge
* SCROLL_FRAME_2EDGE - Thickness of both scroll frame edges
* SPREADSHEET_1EDGE - Thickness of a spreadsheet edge
* SPREADSHEET_2EDGE - Thickness of both spreadsheet edges
* HIGHLITE_1EDGE - Thickness of a highlight border around widgets
* HIGHLITE_2EDGE - Thickness of both highlight borders
*
* ICON_HGT - Height of an icon
*
* LOGO_ICON_WID - Width of a logo icon
* LOGO_ICON_HGT - Height of a logo icon
*
* BUTTON_ICON_1EDGE - Thickness of a button icon border
* BUTTON_ICON_2EDGE - Thickness of a both button icon borders
* LABEL_ICON_1EDGE - Thickness of a label icon border
* LABEL_ICON_2EDGE - Thickness of a both label icon borders
* ITEM_ICON_1EDGE - Thickness of a item icon border
* ITEM_ICON_2EDGE - Thickness of a both item icon borders
* TOGGLE_ICON_1EDGE - Thickness of a toggle icon border
* TOGGLE_ICON_2EDGE - Thickness of a both toggle icon borders
*
* COLOR_MENU_WID - Width of a color menu
* COLOR_MENU_HGT - Height of a color menu
* COLOR_MENU_LABEL_Y_OFFSET - Y offset for centering a label next to
* a color menu
196/252
Appendix D
* COLOR_MENU_TOGGLE_Y_OFFSET - Y offset for centering a toggle next to
* a color menu
*
* COLOR_BOX_WID - Width of a color box
* COLOR_BOX_HGT - Height of a color box
* COLOR_BOX_LABEL_Y_OFFSET - Y offset for centering a label next to
* a color box
* COLOR_BOX_TOGGLE_Y_OFFSET - Y offset for centering a toggle next to
* a color box
* COLOR_BAR_WID - Width of a color bar
*
* INCREMENTAL_ICON_WID - Width of an incremental button icon
* INCREMENTAL_ICON_HGT - Height of an incremental button icon
*
*************************************************************************
* FORMS
*
*
* Create an application form. Note that all forms should use the "UL"
* screen position, since the values returned by these variables are
* based on that assumption.
*
* ui_form_create( "", FORM_X_LOC, @
* FORM_Y_LOC, "UL", @
* FORM_WID_SML, @
* FORM_HGT_TALL, "Label", "Icon" )
*
*
* Create a medium width form next to an application form, and don't
* cover the command window. Use the "Full" height form.
*
* ui_form_create( "", FORM_X_LOC_MED_NX2_SML, @
* FORM_WID_MED, @
* FORM_HGT_FULL, "Label", "Icon" )
*
*
* Create a centered, half height, medium width modal form.
*
* ui_modalform_create( "", FORM_X_LOC_MED_CEN, @
* FORM_Y_LOC_HALF_CEN, "UL", @
* FORM_WID_MED, @
* FORM_HGT_HALF, "Label" )
*
*
* Form Placement - X Location:
*
* FORM_X_LOC - Normal form X location
*
* FORM_X_LOC_SML - Normal form X location (same as FORM_X_LOC)
* FORM_X_LOC_SPL - Special form X location (width is 1.5
* times a normal or small form)
* FORM_X_LOC_MED - Medium form (medium width) X location
* FORM_X_LOC_LRG - Large form (large width) X location
*

197/252
Appendix D
* FORM_X_LOC_SML_NX2_SML - Small form next to a small form
* FORM_X_LOC_SPL_NX2_SML - Special form next to a small form
* FORM_X_LOC_MED_NX2_SML - Medium form next to a small form
* FORM_X_LOC_LRG_NX2_SML - Large form next to a small form
*
* FORM_X_LOC_SML_NX2_SPL - Small form next to a special form
* FORM_X_LOC_SPL_NX2_SPL - Special form next to a special form
* FORM_X_LOC_MED_NX2_SPL - Medium form next to a special form
* FORM_X_LOC_LRG_NX2_SPL - Large form next to a special form
*
* FORM_X_LOC_SML_NX2_MED - Small form next to a medium form
* FORM_X_LOC_SPL_NX2_MED - Special form next to a medium form
* FORM_X_LOC_MED_NX2_MED - Medium form next to a medium form
* FORM_X_LOC_LRG_NX2_MED - Large form next to a medium form
*
* FORM_X_LOC_SML_NX2_LRG - Small form next to a large from
* FORM_X_LOC_SPL_NX2_LRG - Special form next to a large form
* FORM_X_LOC_MED_NX2_LRG - Medium form next to a large form
* FORM_X_LOC_LRG_NX2_LRG - Large form next to a large form
*
* FORM_X_LOC_2ND_SML_NX2_SML - Small form next to a small form which is
* next to a small form
* FORM_X_LOC_2ND_SPL_NX2_SPL - Special form next to a special form
* which is next to a special form
*
* FORM_X_LOC_SML_NX2_SPL_NX2_SML - Small form next to a special form
* which is next to a small form
*
* FORM_X_LOC_SPL_NX2_SPL_NX2_SML - Special form next to a special form
* which is next to a small form
*
* FORM_X_LOC_SML_CEN - Small form centered on screen
* FORM_X_LOC_SPL_CEN - Special form centered on screen
* FORM_X_LOC_MED_CEN - Medium form centered on screen
* FORM_X_LOC_LRG_CEN - Large form centered on screen
*
* FORM_X_LOC_SML_CEN_AB_COM - Small form centered above the command
* window
* FORM_X_LOC_SPL_CEN_AB_COM - Special form centered above the command
* window
* FORM_X_LOC_MED_CEN_AB_COM - Medium form centered above the command
* window
* FORM_X_LOC_LRG_CEN_AB_COM - Large form centered above the command
* window
*
* FORM_X_LOC_OFFSET_CASCADE_1 - X offset for cascade position 1
*
*
* Form Placement - Y Location:
*
* FORM_Y_LOC - Y Location for form under Main Menu
*
* FORM_Y_LOC_HALF_CEN - 1/2 Height form centered on screen
* FORM_Y_LOC_QTR_CEN - 1/4 Height form centered on screen

198/252
Appendix D
* FORM_Y_LOC_3_8THS_CEN - 3/8 Height form centered on screen
* FORM_Y_LOC_5_8THS_CEN - 5/8 Height form centered on screen
* FORM_Y_LOC_3_QTRS_CEN - 3/4 Height form centered on screen
*
* FORM_Y_LOC_OFFSET_CASCADE_1 - Y offset for cascade position 1
*
*
* Form Widths and Heights:
*
* FORM_WID_SML - Width of a small form
* FORM_WID_SPL - Width of a "special" form (1.5 times
* a small form)
* FORM_WID_MED - Width of a medium form (medium size)
* FORM_WID_LRG - Width of a large form (large size)
*
* FORM_HGT_TALL - Height of a tall form (Main Menu to
* bottom of screen)
* FORM_HGT_FULL - Height of a full form (Main Menu to
* top of Command Window)
* FORM_HGT_HALF - Half of a full form
* FORM_HGT_QTR - One Quarter of a full form
* FORM_HGT_3_8THS - Three Eighths of a full form
* FORM_HGT_5_8THS - Five Eighths of a full form
* FORM_HGT_3_QTRS - Three Quarters of a full form
*
*
* Form Margins:
*
* FORM_L_MARGIN - Inside Left Margin for widgets in form
* FORM_R_MARGIN - Inside Right Margin for widgets in form
* FORM_T_MARGIN - Inside Top Margin above first widget
* FORM_B_MARGIN - Inside Bottom Margin below last widget
* FORM_B_MARGIN_NO_BUTTON - Inside Bottom Margin below last widget
* when last widget is not a button
*
* FORM_2H_MARGIN - Both horizontal margins
* FORM_2V_MARGIN - Both vertical margins
* FORM_2V_MARGIN_NO_BUTTON - Both vertical margins (when last widget
* is not a button)
*
*
* Form Borders (the colored areas outside the form):
*
* FORM_L_BORDER - Left Border of the form
* FORM_R_BORDER - Right Border of the form
* FORM_T_BORDER - Top Border of the form (including the label)
* FORM_B_BORDER - Bottom Border of the form
* FORM_T_BORDER_NO_LABEL - Top Border of the form without a label
*
* FORM_2H_BORDER - Both horizontal borders
* FORM_2V_BORDER - Both vertical borders (with label)
* FORM_2V_BORDER_NO_LABEL - Both vertical borders (without label)
*
* FORM_X_ISFRAME - Compensation for X location of forms

199/252
Appendix D
* if they are 'user placed' rather than
* appforms placed
* FORM_Y_ISFRAME - Compensation for Y location
* FORM_Y_ISFRAME_NO_LABEL - Compensation for Y location for forms
* with no label
*************************************************************************
* ACTION - OBJECT - METHOD MENUS

*
*
* Create the Application Action, Object, Method menus and place the
* separator underneath them.
*
* FORM_WID_MED, @
* ui_optionmenu_create( form_id, "callback", @
* AOM_MENU_X_LOC, @
* ACTION_MENU_Y_LOC, @
* AOM_MENU_LABEL_LEN, @
* ACTION, FALSE )
*
* AOM_MENU_X_LOC, @
* OBJECT_MENU_Y_LOC, @
* OBJECT, FALSE )
*
* AOM_MENU_X_LOC, @
* METHOD_MENU_Y_LOC, @
* METHOD, FALSE )
*
* ui_separator_create ( form_id, "", 0.0, @
* AOM_SEPARATOR_Y_LOC, @
* FORM_WID_SML, TRUE )
*
*
* AOM Menu Placement:
*
* AOM_MENU_X_LOC - X Location of the AOM menus (margin included)
* AOM_MENU_LABEL_LEN - Label length for AOM menus (language dependent)
* ACTION_MENU_Y_LOC - Y Location for the Action menu (margin included)
* OBJECT_MENU_Y_LOC - Y Location for the Object menu (margin included)
* METHOD_MENU_Y_LOC - Y Location for the Method menu (margin included)
* AOM_SEPARATOR_Y_LOC - Y Location for separator under the AOM menus
* APP_FORM_FIRST_Y_LOC - Y Location for the first widget in an
* application form
*
*************************************************************************
* FRAMES
*
*
* Create a frame in an application form. Assume this is the first

200/252
Appendix D
* widget in the form and that the frame contains a three line listbox
* with a label and a databox with a label. Then locate the Y position
* for an unframed databox under the frame. Note that the frame's label
* must be considered in determining the next widget location as does
* the thickness of the frame edges.
*
* Since this is an application form, the first Y location is the
* variable "app_form_first_y_loc".
*
* y_loc = APP_FORM_FIRST_Y_LOC
*
* height = FRAME_T_MARGIN + @
* LBOX_3L_HGT_LABOVE + @
* INTER_WIDGET_SPACE + @
* DBOX_HGT_LABOVE + @
* FRAME_B_MARGIN
*
* ui_frame_create ( form_id, "", @
* FORM_L_MARGIN, @
* y_loc, @
* FRAME_WID_SINGLE, @
* height, "Label" )
*
* ui_listbox_create ( frame_id, "callback", @
* FRAME_L_MARGIN, @
* FRAME_T_MARGIN, @
* LBOX_WID_SINGLE, @
* 3, "Listbox Label", @
* selection_type, sort_flag )
*
* y_frame_loc = FRAME_T_MARGIN + @
* INTER_WIDGET_SPACE
*
* ui_databox_create ( frame_id, "", @
* FRAME_L_MARGIN, @
* y_frame_loc, 0.0, @
* DBOX_WID_SINGLE, @
* "Databox Label", value, @
* TRUE, datatype, num_vals )
*
* y_loc = y_loc + @
* FRAME_LABEL_HGT + @
* height + @
* FRAME_2EDGE + @
*
* UNFRAMED_L_MARGIN, @
* y_loc, 0.0, @
* "Second Databox Label", value, @
*
*
* Create two single width frames in a medium form that is
* next to a small application form. These frames will be
* at the top of the form. Their heights are the same as

201/252
Appendix D
* in the above example.
*
* ui_form_create( "", FORM_X_LOC_MED_NX2_SML, @
* FORM_WID_MED, @
* FORM_HGT_FULL, "Label", "Icon" )
*
*
* FRAME_X_LOC_COL1, @
* FORM_Y_MARGIN, @
* height, "Left Label" )
*
* FRAME_X_LOC_COL2, @
* FORM_Y_MARGIN, @
* height, "Right Label" )
*
*
* Frame Widths and Heights:
*
* FRAME_WID_SINGLE - Width of a single width frame
* FRAME_WID_SPECIAL - Width of a special width frame
* FRAME_WID_DOUBLE - Width of a double width frame
* FRAME_WID_TRIPLE - Width of a triple width frame
*
* FRAME_LABEL_HGT - Height of the label above a frame
*
*
* Frame Margins:
*
* FRAME_L_MARGIN - Inside left margin for widgets in the frame
* FRAME_R_MARGIN - Inside right margin for widgets in the frame
* FRAME_T_MARGIN - Inside top margin above first widget
* FRAME_B_MARGIN - Inside bottom margin below last widget
*
* FRAME_2H_MARGIN - Both horizontal margins
* FRAME_2V_MARGIN - Both vertical margins
*
*
* Frame Placement:
*
* FRAME_X_LOC_COL1 - X Location for a frame in column 1
* (same as "form_l_margin")
*
*
* Unframed Widget Placement:
*
* UNFRAMED_L_MARGIN - Left margin for an unframed widget
* UNFRAMED_R_MARGIN - Right margin for an unframed widget
*
* UNFRAMED_X_LOC_COL1 - X Location of an unframed widget in column 1

202/252
Appendix D
*
*************************************************************************
* SELECT FRAMES
*
*
* Create a select frame in an application form. Put two select databoxes
* in the select frame. Then compute the Y location for the next widget.
* Note the use of the supplied Y locations for the select databoxes as
* well as the height of the select frame.
*
*
* ui_selectframe_create( form_id, "callback", @
* FORM_L_MARGIN, @
* y_loc, @
* SFRAME_WID_SINGLE, @
* SFRAME_2SDB_HGT_LABOVE, @
* "Select Frame Label", @
* recycle_flag )
*
* ui_selectdatabox_create ( sel_frame_id, "", @
* SFRAME_L_MARGIN, @
* SDBOX_Y_LOC1, 0.0, @
* SDBOX_WID_SINGLE, @
* "Select Databox One", @
* value, TRUE, datatype, @
* prompt )
*
* SDBOX_Y_LOC2, 0.0, @
* "Select Databox One", @
* prompt )
*
* y_loc = y_loc + SFRAME_LABEL_HGT + @
* SFRAME_2SDB_HGT_LABOVE + @
* SFRAME_2EDGE + @
*
*
* Select Frame Widths and Heights:
*
* SFRAME_WID_SINGLE - Width of a single width select frame
* SFRAME_WID_SPECIAL - Width of a special width select frame
* SFRAME_WID_DOUBLE - Width of a double width select frame
* SFRAME_WID_TRIPLE - Width of a triple width select frame
*
* SFRAME_LABEL_HGT - Height of the label above a select frame
*
* SFRAME_1SDB_HGT_LABOVE - Height of a select frame with
* 1 select databox with a label
* 2 select databoxes with labels

203/252
Appendix D
*
* SFRAME_HGT_LABOVE_INCR - Increment for making select frames with
* more than 5 select databoxes with labels
*
* SFRAME_1SDB_HGT_NO_LABOVE - Height of a select frame with
* 1 select databox without a label
* 2 select databoxes without labels
*
* SFRAME_HGT_NO_LABOVE_INCR - Increment for making select frames with
* more than 5 select databoxes without labels
*
*
* Select Frame Margins:
*
* SFRAME_L_MARGIN - Inside left margin for select databoxes
* SFRAME_R_MARGIN - Inside right margin for select databoxes
* SFRAME_T_MARGIN - Inside top margin for select databoxes
* SFRAME_B_MARGIN - Inside bottom margin for select databoxes
*
* SFRAME_2H_MARGIN - Both horizontal margins
* SFRAME_2V_MARGIN - Both vertical margins
*
*
* Select Frame Placement:
*
* SFRAME_X_LOC_COL1 - X Location for a select frame in column 1
* (same as "form_l_margin")
*
*************************************************************************
* SCROLL_FRAMES
*
*
* Create a scroll frame in a form.
*
*
* Scroll Frame Widths and Heights:
*
* SCROLL_FRAME_WID_SINGLE - Width of a single width scroll frame
* SCROLL_FRAME_WID_SPECIAL - Width of a special width scroll frame
* SCROLL_FRAME_WID_DOUBLE - Width of a double width scroll frame

204/252
Appendix D
* SCROLL_FRAME_WID_TRIPLE - Width of a triple width scroll frame
*
*
* SCROLL_FRAME_WORK_WID_SINGLE - Working width of a single width
* scroll frame
* SCROLL_FRAME_WORK_WID_SPECIAL - Working width of a special width
* scroll frame
* SCROLL_FRAME_WORK_WID_DOUBLE - Working width of a double width
* scroll frame
* SCROLL_FRAME_WORK_WID_TRIPLE - Working width of a triple width
* scroll frame
*
* SCROLL_FRAME_DBOX_WID_SINGLE - Width of a single width scroll frame
* databox
* SCROLL_FRAME_DBOX_WID_SPECIAL - Width of a special width scroll frame
* databox
* SCROLL_FRAME_DBOX_WID_DOUBLE - Width of a double width scroll frame
* databox
* SCROLL_FRAME_DBOX_WID_TRIPLE - Width of a triple width scroll frame
* databox
*
* SCROLL_FRAME_LABEL_HGT - Height of the label above a
* scroll frame
*
* SCROLL_FRAME_1DBOX_HGT - Scroll frame height with 1 databox
* SCROLL_FRAME_2DBOX_HGT - Scroll frame height with 2 databoxes
*
* SCROLL_FRAME_DBOX_HGT_INCR - Scroll frame height increment
*
* SCROLL_FRAME_1DBOX_WORK_HGT - Scroll frame work height for 1 databox
* SCROLL_FRAME_2DBOX_WORK_HGT - Scroll frame work height for 2 databoxes
*
* SCROLL_FRAME_DBOX_WORK_HGT_INCR - Scroll frame working height increment
*
* SCROLL_FRAME_SLIDER_WID - Width of the slider on the right
* of a scroll frame
* SCROLL_FRAME_SLIDER_HGT - Height of the slider at the bottom
* of a scroll frame
*
* Frame Margins:
*
* SCROLL_FRAME_L_MARGIN - Inside left margin for widgets in
* a scroll frame
* SCROLL_FRAME_R_MARGIN - Inside right margin for widgets in
* a scroll frame
* SCROLL_FRAME_T_MARGIN - Inside top margin above first widget
* SCROLL_FRAME_B_MARGIN - Inside bottom margin below last widget
*
* SCROLL_FRAME_2H_MARGIN - Both horizontal margins
* SCROLL_FRAME_2V_MARGIN - Both vertical margins
*

205/252
Appendix D
*************************************************************************
* BUTTONS
*
*
* Create two buttons in a small form. The button on the left is a
* default button. Use "half" size buttons.
*
* ui_button_create ( form_id, "callback", @
* BUTTON_HALF_X_LOC1, @
* y_loc, @
* BUTTON_WID_HALF, @
* 0.0, "Left Button", @
* TRUE, TRUE )
*
* y_loc = y_loc + BUTTON_Y_OFFSET
*
* ui_button_create ( form_id, "callback", @
* BUTTON_HALF_X_LOC2, @
* y_loc, @
* BUTTON_WID_HALF, @
* 0.0, "Right Button", @
* TRUE, FALSE )
*
* y_loc = y_loc + BUTTON_Y_OFFSET + @
* BUTTON_HGT + @
*
*
* Button Widths and Heights:
*
* BUTTON_WID_FULL - Width of a wide button on a small form
* BUTTON_WID_HALF - Width of a medium button on a small form
* BUTTON_WID_THIRD - Width of a small button on a small form
*
* BUTTON_WID_FULL_NT - Width of a non_troughed wide button on
* a small form
* BUTTON_WID_HALF_NT - Width of a non_troughed medium button on
* a small form
* BUTTON_WID_THIRD_NT - Width of a non_troughed small button on
* a small form
*
* BUTTON_HGT - Button height
* BUTTON_DEFAULT_HGT - Default button height (includes top and
* bottom borders)
* BUTTON_HGT_NT - Button height of non_troughed button
*
* BUTTON_DEFAULT_BORDER_WID - Default button border width
* BUTTON_DEFAULT_BORDER_HGT - Default button border height
*
*
* Button Location Offsets:
*
* BUTTON_IN_FRAME_X_OFFSET - X offset for placing buttons inside
* frames using the X Positions defined
* below
*

206/252
Appendix D
* BUTTON_1XTRA_WID - X width for one trough for user placement
* of troughed buttons.
* BUTTON_2XTRA_WID - X width for two troughs for user placement
* of troughed buttons.
*
* BUTTON_Y_OFFSET - Y offset for placing a non-highlighted
* button next to a highlighted button
* BUTTON_Y_OFFSET_NT - Y offset for placing a non-highlighted
* button next to a highlighted button
*
* BUTTON_LABEL_Y_OFFSET - Y offset for placing a label to the right
* of a button
* BUTTON_DEFAULT_LABEL_Y_OFFSET - Y offset for placing a label to the right
* of a default button
* BUTTON_LABEL_Y_OFFSET_NT - Y offset for placing a label to the right
* of a non_troughed button
*
*
* Button X Positions:
*
* BUTTON_FULL_X_LOC1 - Wide button on the left
* BUTTON_HALF_X_LOC1 - Medium button on the left
* BUTTON_HALF_X_LOC2 - Medium button on the right
* BUTTON_THIRD_X_LOC1 - Small button on the left
* BUTTON_THIRD_X_LOC2 - Small button centered
* BUTTON_THIRD_X_LOC3 - Small button on the right
*
* BUTTON_FULL_X_LOC1_COL2 - Wide button on the left of column 2
* BUTTON_HALF_X_LOC1_COL2 - Medium button on the left of column 2
* BUTTON_HALF_X_LOC2_COL2 - Medium button on the right of column 2
* BUTTON_THIRD_X_LOC1_COL2 - Small button on the left of column 2
* BUTTON_THIRD_X_LOC2_COL2 - Small button centered of column 2
* BUTTON_THIRD_X_LOC3_COL2 - Small button on the right of column 2
*
* BUTTON_FULL_X_LOC1_COL3 - Wide button on the left of column 3
* BUTTON_HALF_X_LOC1_COL3 - Medium button on the left of column 3
* BUTTON_HALF_X_LOC2_COL3 - Medium button on the right of column 3
* BUTTON_THIRD_X_LOC1_COL3 - Small button on the left of column 3
* BUTTON_THIRD_X_LOC2_COL3 - Small button centered of column 3
* BUTTON_THIRD_X_LOC3_COL3 - Small button on the right of column 3
*
* BUTTON_FULL_X_LOC1_SPL - Wide button centered on a special form
* BUTTON_HALF_X_LOC1_SPL - Medium button on the left of a special form
* BUTTON_HALF_X_LOC2_SPL - Medium button on the right of a special form
* BUTTON_THIRD_X_LOC1_SPL - Small button on the left of a special form
* BUTTON_THIRD_X_LOC2_SPL - Small button centered of a special form
* BUTTON_THIRD_X_LOC3_SPL - Small button on the right of a special form
*
* BUTTON_FULL_X_LOC_CEN - Centered wide button on a small form
* BUTTON_HALF_X_LOC_CEN - Centered medium button on a small form
* BUTTON_THIRD_X_LOC_CEN - Centered small button on a small form
*
* BUTTON_FULL_X_LOC_CEN_MED - Centered wide button on a medium form
* BUTTON_HALF_X_LOC_CEN_MED - Centered medium button on a medium form
* BUTTON_THIRD_X_LOC_CEN_MED - Centered small button on a medium form
*
* BUTTON_FULL_X_LOC_CEN_LRG - Centered wide button on a large form
* BUTTON_HALF_X_LOC_CEN_LRG - Centered medium button on a large form

207/252
Appendix D
* BUTTON_THIRD_X_LOC_CEN_LRG - Centered small button on a large form
*
* BUTTON_FULL_X_LOC_CEN_SPL - Centered wide button on a special form
* BUTTON_HALF_X_LOC_CEN_SPL - Centered medium button on a special form
* BUTTON_THIRD_X_LOC_CEN_SPL - Centered small button on a special form
*
*************************************************************************
* DATABOXES
*
*
* Create a framed databox with a label above the databox. Then
* compute the Y location for the next widget inside the frame.
*
* y_frame_loc = FRAME_T_MARGIN
*
* FRAME_L_MARGIN, @
* y_frame_loc, 0.0, @
*
* y_frame_loc = y_frame_loc + @
* DBOX_HGT_LABOVE + @
*
*
* Create a framed databox with a label to the side. Use the
* default label length for a single column databox and compute
* the databox width.
*
*
* wid = DBOX_WID_SINGLE - @
* DBOX_LABEL_LEN_SINGLE
*
*
* FRAME_L_MARGIN, @
* y_frame_loc, @
* DBOX_LABEL_LEN_SINGLE, @
* wid, @
* FALSE, datatype, num_vals )
*
*
* Databox Width and Height:
*
* DBOX_WID_SINGLE - Width of a single width databox
* DBOX_WID_SPECIAL - Width of a special width databox
* DBOX_WID_DOUBLE - Width of a double width databox
* DBOX_WID_TRIPLE - Width of a triple width databox
*
* DBOX_HGT_LABOVE - Height of a databox with a label on the top
* (even if the label is blank)

208/252
Appendix D
* DBOX_HGT_NO_LABOVE - Height of a databox with a label to the side
*
* DBOX_LABEL_LEN_SINGLE - Default label length for a single width databox
* (used when "label_above" is false)
* DBOX_LABEL_LEN_SPECIAL - Default label length for a special width databox
* DBOX_LABEL_LEN_DOUBLE - Default label length for a double width databox
* DBOX_LABEL_LEN_TRIPLE - Default label length for a triple width databox
*
* DBOX_LABEL_X_OFFSET - REMOVED
* DBOX_LABEL_Y_OFFSET - Y offset for placing a label to the right of
* a databox with "labelabove" false.
*
*************************************************************************
* FILES
*
*
* Create a form centered under the main menu that has a file
* widget inside the a frame. The file widget is placed at
* ( 0.0, 0.0 ) inside the frame (a top margin is not needed).
* The height of the file widget includes a bottom margin
* and therefore can be used as the height of the frame that
* contains the file widget. The file widget has 5 lines in
* the list boxes.
*
* form_hgt = FILE_5L_HGT + FORM_2V_MARGIN + FRAME_2EDGE
* x_loc = WINDOW_CEN_X_LOC - 0.5 * ( wid + FORM_2H_BORDER )
* y_loc = WINDOW_CEN_Y_LOC - 0.5 * ( form_hgt + FORM_2V_BORDER )
*
* form_id = ui_form_create( "", x_loc, y_loc, "UL", @
* wid, form_hgt, @
* "Form Label", "" )
*
* frame_id = ui_frame_create( form_id, "", @
* FORM_L_MARGIN, @
* FORM_T_MARGIN, @
* FRAME_WID_SPECIAL, @
* FILE_5L_HGT, "" )
*
* file_id = ui_file_create( frame_id, "", @
* 0.0, 0.0, @
* FILE_WID_SPECIAL, 5, @
* "Filter Label", @
* "Filter Mask", @
* "Files Label", @
* "Directory Label", @
* "Files Label", @
* "Selection Label", @
* "Default Selection", @
* "Left Button Label", @
* "Right Button Label" )
*
*
* File Width:
*
* FILE_WID_SINGLE - Width of a single width file widget

209/252
Appendix D
* FILE_WID_SPECIAL - Width of a special width file widget
* FILE_WID_DOUBLE - Width of a double width file widget
* FILE_WID_TRIPLE - Width of a triple width file widget
*
* File Height:
*
* FILE_1L_HGT - Height of a 1 line file widget
* FILE_HGT_INCR - Increment for making bigger file widgets
*
*************************************************************************
* LABELS and INFO INDENTS

*
*
* Create a label inside a frame and then compute the y location
* of the next widget inside the frame.
*
*
* ui_label_create ( frame_id, "", @
* FRAME_L_MARGIN, @
* y_frame_loc, @
* "A Label" )
*
* LABEL_HGT + @
*
*
* Label Height:
*
* LABEL_HGT - Height of a label
* LABEL_Y_OFFSET - Y offset of label
* LABEL_HGT_TIGHT - Height of a label when showing multiple
* labels
*
* INFO_INDENT - X location of information label
* INFO_INDENT_COL1 - X location of information label in column 1
*
*************************************************************************
* LISTBOXES
*
*

210/252
Appendix D
* Create a framed three line listbox with a label above the listbox. Note
* that the widths and heights include the vertical and horizontal sliders.
*
*
* ui_listbox_create ( frame_id, "callback", @
* FRAME_L_MARGIN, @
* y_frame_loc, @
* LBOX_WID_SINGLE, @
* 3, "Listbox Label", @
* selection_type, sort_flag )
*
*
*
* To determine the height for a six line listbox, add the variable
* LBOX_HGT_LABOVE_INCR to LBOX_5L_HGT_LABOVE.
*
*
* Listbox Width and Height:
*
* LBOX_WID_SINGLE - Width of a single width listbox
* LBOX_WID_SPECIAL - Width of a special width listbox
* LBOX_WID_DOUBLE - Width of a double width listbox
* LBOX_WID_TRIPLE - Width of a triple width listbox
*
* LBOX_1L_HGT_LABOVE - Height of a 1 line listbox with a top label
*
* LBOX_HGT_LABOVE_INCR - Increment for computing a listbox height that
* has more than 5 lines in it
*
* LBOX_1L_HGT_NO_LABOVE - Height of a 1 line listbox with no label
* (label is blank)
*
* LBOX_HGT_NO_LABOVE_INCR - Increment for computing a listbox height that
*
* LBOX_SELBTNS_HGT, LBOX_SELBTNS_WID - Height and combined width of
* (Un)Select All buttons
*
*************************************************************************
* OPTION MENUS
*

211/252
Appendix D
*
* Create an option menu with a label to the side. Then set the
* Y location for the next widget. Assume this is an unframed widget.
*
*
* UNFRAMED_L_MARGIN, @
* y_loc, @
* OPT_MENU_LABEL_LEN, @
* "Label", FALSE )
*
* y_loc = y_loc + OPT_MENU_HGT_NO_LABOVE + @
*
*
* Option menu Placement:
*
* OPT_MENU_LABEL_LEN - Default label length for an option menu
* with a label to the side
*
* OPT_MENU_HGT_LABOVE - Height of an option menu with a label
* on the top
* OPT_MENU_HGT_NO_LABOVE - Height of an option menu with a label
* on the side
*
* OPT_MENU_Y_OFFSET - Y offset for placing a label to the
* right of a select databox with
* "labelabove" false
*
*************************************************************************
* SELECT DATABOXES
*
*
* Create a framed select databox with a label above the select databox.
* Then compute the Y location for the next widget.
*
* y_sframe_loc = SFRAME_T_MARGIN
*
* y_sframe_loc, 0.0, @
* "Select Databox Label", @
* prompt )
*
* y_sframe_loc = y_sframe_loc + @
* SDBOX_HGT_LABOVE + @
*
*
* Create a framed select databox with a label to the side. Use the
* default label length for a single column select databox and compute
* the select databox width.

212/252
Appendix D
*
* y_sframe_loc = SFRAME_T_MARGIN
*
* wid = SDBOX_WID_SINGLE - @
* SDBOX_LABEL_LEN_SINGLE
*
*
* y_sframe_loc, @
* SDBOX_LABEL_LEN_SINGLE, @
* wid, @
* "Select Databox Label", @
* value, FALSE, datatype, @
* prompt )
*
* y_sframe_loc = y_sframe_loc + @
* SDBOX_HGT_NO_LABOVE + @
*
*
* Select Databox Width and Height:
*
* SDBOX_WID_SINGLE - Width of a single width select databox
* SDBOX_WID_SPECIAL - Width of a special width select databox
* SDBOX_WID_DOUBLE - Width of a double width select databox
* SDBOX_WID_TRIPLE - Width of a triple width select databox
*
* SDBOX_HGT_LABOVE - Height of a select databox with a top label
* SDBOX_HGT_NO_LABOVE - Height of a select databox with a side label
*
* SDBOX_Y_LOC1_LABOVE - Y location of select databox 1 in a selectframe
* (select databox has a label above)
*
* SDBOX_Y_LABOVE_INCR - Increment for creating the Y location for than
* than 5 select databoxes with labels in a select
* frame
*
* SDBOX_Y_LOC1_NO_LABOVE - Y location of select databox 1 in a selectframe
* (select databox does not have a label above)
*
* SDBOX_Y_NO_LABOVE_INCR - Increment for creating the Y location for than

213/252
Appendix D
* than 5 select databoxes without labels in a
* select frame
*
* SDBOX_LABEL_LEN_SINGLE - Default label length for a single width select
* databox (used when "label_above" is false)
* SDBOX_LABEL_LEN_SPECIAL- Default label length for a special width select
* databox
* SDBOX_LABEL_LEN_DOUBLE - Default label length for a double width select
* databox
* SDBOX_LABEL_LEN_TRIPLE - Default label length for a triple width select
* databox
*
* SDBOX_LABEL_X_OFFSET - REMOVED
* SDBOX_LABEL_Y_OFFSET - Y offset for placing a label to the right
* of a select databox with "labelabove" false.
*
*************************************************************************
* SLIDEBARS
*
*
* Create a slidebar inside a frame and then compute the y location
* of the next widget inside the frame. The slidebar has a label
* as well as min/max labels above the displayed values.
*
*
* ui_slidebar_create ( frame_id, "callback", @
* FRAME_L_MARGIN, @
* y_frame_loc, @
* SLIDER_WID_SINGLE, @
* "Slidebar Label", value, @
* num_digits, TRUE, "Min", "Max", @
* TRUE, 0, 10 ) @
*
* SLIDER_HGT_COMPLETE + @
*
*
* Sliderbar Width and Height:
*
* SLIDER_WID_SINGLE - Width of a single width slidebar
* SLIDER_WID_SPECIAL - Width of a special width slidebar
* SLIDER_WID_DOUBLE - Width of a double width slidebar
* SLIDER_WID_TRIPLE - Width of a triple width slidebar
*
* SLIDER_HGT_COMPLETE - Height of slidebar with min/max labels,
* the values shown and a label below the
* slidebar
* SLIDER_HGT_MINMAX - Height of slidebar with min/max labels only
* SLIDER_HGT_VALUES - Height of slidebar with values only
* SLIDER_HGT_LABEL - Height of slidebar with label only (values
* not shown and no min/max labels)
* SLIDER_HGT_MINMAX_VALUES - Height of slidebar with min/max labels and
* values shown (no label)

214/252
Appendix D
* SLIDER_HGT_MINMAX_LABEL - Height of slidebar with min/max labels and
* a label below slidebar (values not shown)
* SLIDER_HGT_VALUES_LABEL - Height of slidebar with values shown and
* a label below the slidebar (no min/max
* labels)
* SLIDER_HGT_BAR_ONLY - Height of just the slidebar
*
* SLIDER_LABEL_Y_LOC_MM_VAL - Location of label to side of slidebar when
* the slidebar has both min/max labels and
* values
* SLIDER_LABEL_Y_LOC_MINMAX - Location of label to side of slidebar when
* the slidebar has only min/max labels
* SLIDER_LABEL_Y_LOC_VALUES - Location of label to side of slidebar when
* the slidebar has only values
* SLIDER_LABEL_Y_LOC_BAR_ONLY - Location of label to side of slidebar when
* the slidebar has neither min/max labels
* nor values
*
*************************************************************************
* SPREADSHEETS
*
*
* Create a spreadsheet in a form.
*
*
* Spreadsheet Widths and Heights:
*
* SPREADSHEET_WID_SINGLE - Width of a single width select frame
* SPREADSHEET_WID_SPECIAL - Width of a special width select frame
* SPREADSHEET_WID_DOUBLE - Width of a double width select frame
* SPREADSHEET_WID_TRIPLE - Width of a triple width select frame
*
* SPREADSHEET_LABEL_HGT - Height of the spreadsheet label (to be
* subtracted from the following heights
* in the case that a label is NOT used)
*
* SPREADSHEET_HGT_2D_1ROW - Height of a 2D spreadsheet with 1 row
* SPREADSHEET_HGT_2D_2ROW - Height of a 2D spreadsheet with 2 rows
* SPREADSHEET_HGT_2D_INCR - Height increment for 2D spreadsheet
*
* SPREADSHEET_HGT_3D_1ROW - Height of a 3D spreadsheet with 1 row

215/252
Appendix D
* SPREADSHEET_HGT_3D_INCR - Height increment for 3D spreadsheet
*
*************************************************************************
* SWITCHES
*
*
* Create a framed two row switch with a label. Note that the
* number of rows is a function of the "num_cols" variable and the
* number of items created for the switch.
*
*
* ui_switch_create( frame_id, "callback", @
* FRAME_L_MARGIN, @
* y_frame_loc, @
* num_cols, "Switch Label", @
* alwaysone_flag )
*
* SWITCH_2R_HGT_LABEL + @
*
*
* Switch Height:
*
*
* SWITCH_1R_HGT_LABEL - Height of a 1 row switch with a label
*
* SWITCH_HGT_LABEL_INCR - Increment for creating a switch height with
* more than 4 rows in it
*
* SWITCH_1R_HGT_NO_LABEL - Height of a 1 row switch with no label
*
* SWITCH_HGT_NO_LABEL_INCR - Increment for creating a switch height with
* more than 4 rows in it
*
*************************************************************************
* TEXTBOXES
*
*
* Create a framed three line textbox with a label. Note that the
* widths and heights include the vertical and horizontal sliders.
*

216/252
Appendix D
*
* ui_text_create ( frame_id, "", @
* FRAME_L_MARGIN, @
* y_frame_loc, @
* TBOX_WID_SINGLE, @
* 3, "Textbox Label", @
* "This is text", editable_flag )
*
* TBOX_3L_HGT_LABOVE + @
*
*
* To determine the height for a six line textbox, add the value
* of "TBOX_HGT_LABOVE_INCR" to "TBOX_5L_HGT_LABOVE".
*
*
* Textbox Width and Height:
*
* TBOX_WID_SINGLE - Width of a single width textbox
* TBOX_WID_SPECIAL - Width of a special width textbox
* TBOX_WID_DOUBLE - Width of a double width textbox
* TBOX_WID_TRIPLE - Width of a triple width textbox
*
* TBOX_1L_HGT_LABOVE - Height of a 1 line textbox with a top label
*
* TBOX_HGT_LABOVE_INCR - Increment for computing a textbox height that
*
* TBOX_1L_HGT_NO_LABOVE - Height of a 1 line textbox with no label
* (label is blank)
*
* TBOX_HGT_NO_LABOVE_INCR - Increment for computing a textbox height that
*
*************************************************************************
* TOGGLES
*
*
* Create a toggle inside a frame and then compute the y location
* of the next widget in the frame.
*
*
* ui_toggle_create ( frame_id, "callback", @
* FRAME_L_MARGIN, @

217/252
Appendix D
* y_frame_loc, @
* "Toggle Label" )
*
* TOGGLE_HGT + @
*
*
* Toggle Height:
*
* TOGGLE_HGT - Height of a toggle
* TOGGLE_Y_OFFSET - Y offset for placing a label to the side
* of a toggle
*
*************************************************************************
* LANGUAGE
*
*
* Language variables:
*
* ENGLISH - "English"
* GERMAN - "German"
* SPANISH - "Spanish"
* FRENCH - "French"
* KANJI - "Kanji"
*
* LANGUAGE - Current language (see above)
* HANDEDNESS - Determines whether forms appear on right of left side
* of screen
*
*************************************************************************
* SCREEN
*
*
* Screen variables:
*
* PIXEL_WID - Width of a pixel (in inches)
* PIXEL_HGT - Height of a pixel (in inches)
*
* SCREEN_WID - Width of logical screen (in inches)
* SCREEN_HGT - Height of logical screen (in inches)
*
*************************************************************************
* BASIC LAYOUT
*
*
* Basic layout variables:
*
* MAIN_MENU_X_LOC - Main menu X location

218/252
Appendix D
* MAIN_MENU_Y_LOC - Main menu Y location
* MAIN_MENU_WID - Main menu width
* MAIN_MENU_HGT - Main menu height
* MAIN_MENU_L_EDGE - Left edge of main menu (incl border)
* MAIN_MENU_R_EDGE - Right edge of main menu (incl border)
* MAIN_MENU_T_EDGE - Top edge of main menu (incl border)
* MAIN_MENU_B_EDGE - Bottom edge of main menu (incl border)
* MAIN_MENU_SWITCH_Y_LOC - Switch Y location
* MAIN_MENU_ICON_Y_LOC - Icon Y location
* MAIN_MENU_ICON_HGT - Main Menu Icon Height
* MAIN_MENU_ICON_WID - Main Menu Icon Width
* MAIN_MENU_LOGO_ICON_WID - Main Menu Logo Icon Width
* MAIN_MENU_HEART_ICON_WID - Main Menu Heartbeat Icon Width
* MAIN_MENU_HEART_ICON_HGT - Main Menu Heartbeat Icon Height
* MAIN_MENU_MARGIN - Main menu switch margin
* MAIN_MENU_ICON_MARGIN - Main menu margin between icons
* MAIN_MENU_HEART_MARGIN - Main menu margin between last icon and
* heartbeat icon
* MAIN_MENU_HEART_X_LOC - Heartbeat icon X location
* MAIN_MENU_HEART_Y_LOC - Heartbeat icon Y location
*
* COMMAND_WINDOW_X_LOC - Command window X location
* COMMAND_WINDOW_Y_LOC - Command window Y location
* COMMAND_WINDOW_WID - Command window width
* COMMAND_WINDOW_HGT - Command window height
* COMMAND_WINDOW_NUM_ROWS - Number of history rows in the command window
* COMMAND_WINDOW_L_EDGE - Left edge of command window (incl border)
* COMMAND_WINDOW_R_EDGE - Right edge of command window (incl border)
* COMMAND_WINDOW_T_EDGE - Top edge of command window (incl border)
* COMMAND_WINDOW_B_EDGE - Bottom edge of command window (incl border)
*
* GRAPHICS_WINDOW_X_LOC - Graphics window X location
* GRAPHICS_WINDOW_Y_LOC - Graphics window Y location
* GRAPHICS_WINDOW_WID - Graphics window width
* GRAPHICS_WINDOW_HGT - Graphics window height
* GRAPHICS_WINDOW_L_EDGE - Left edge of graphics window (incl border)
* GRAPHICS_WINDOW_R_EDGE - Right edge of graphics window (incl border)
* GRAPHICS_WINDOW_T_EDGE - Top edge of graphics window (incl border)
* GRAPHICS_WINDOW_B_EDGE - Bottom edge of graphics window (incl border)
*
* SHOW_SPREADSHEET_NUM_ROWS - Number of rows in the show spreadsheet widget
*
* GRAPHICS_WINDOW_WID_QTR - Quarter width graphics window
* GRAPHICS_WINDOW_HGT_QTR - Quarter width graphics window
*
* GRAPHICS_WINDOW_X_LOC_UL - Quarter size graphics window upper left X loc
* GRAPHICS_WINDOW_Y_LOC_UL - Quarter size graphics window upper left Y loc
* GRAPHICS_WINDOW_X_LOC_UR - Quarter size graphics window upper right X loc
* GRAPHICS_WINDOW_Y_LOC_UR - Quarter size graphics window upper right Y loc
* GRAPHICS_WINDOW_X_LOC_LL - Quarter size graphics window lower left X loc
* GRAPHICS_WINDOW_Y_LOC_LL - Quarter size graphics window lower left Y loc
* GRAPHICS_WINDOW_X_LOC_LR - Quarter size graphics window lower right X loc
* GRAPHICS_WINDOW_Y_LOC_LR - Quarter size graphics window lower right Y loc
*
* GRAPHICS_CEN_X_LOC - Center of graphics area X location
* GRAPHICS_CEN_Y_LOC - Center of graphics area Y location
*
* WINDOW_CEN_X_LOC - Center of area beneath main menu X location

219/252
Appendix D
* WINDOW_CEN_Y_LOC - Center of area beneath main menu Y location
*
* MAIN_MENU_SWITCH_COLS - Number of columns for main menu switch
*
* ENABLE_MAIN_MENU_SWITCH - Hidden code to enable the main menu switch
* without having to open a database
*

220/252
Appendix E
MSC.Patran Architecture

221/252
Appendix E
MSC.Patran is architected into 5 major areas:

UIMS User interface
Applications Converts user input into suitable format for
database storage
Database Includes functionality for data persistence,
embedded SQL, data integrity, simultaneous access, undo
Graphics Provides functions to display database contents in
the viewport, picking, graphical user feedback
Event Manager Coordinates the other 4 areas

222/252
Appendix F
Shareware Compiling Functions

223/252
Appendix F
The MSC.Patran Utilities or Shareware library contains several

useful functions for compiling PCL that augment the basic !!
COMPILE functionality. In addition to compiling the function into a
PCL library, these functions first pass the function to be compiled
through the C-preprocessor. Thus, these functions are useful in
the event that it is impossible or inconvenient to use make and a
Makefile.
The functions are contained in the bv_pcl class and can be
executed at the MSC.Patran command line. The compile()
function compiles a single PCL file into a PCL library while the
compile_all() function compiles all files in the current
directory/folder with a .pcl extension into a PCL library.
Complete function descriptions and argument lists are given
below.
bv_pcl.compile(file_name, plb_name)
DESCRIPTION
Same as !!COMPILE file_name plb_name except that the
file_name is passed through the C-preprocessor (cpp) prior
to compiling. Thus, by using this function you do not need
to use make and a makefile prior to compiling. Note
that if the PCL library does not exist, it is created.
INPUT
file_name String[] File containing PCL to
be compiled
plb_name String[] Name of PCL library
file.
OUTPUT
<None>
EXAMPLE
bv_pcl.compile(My_very_own_pcl.pcl, My_pcl_library.plb)

224/252
Appendix F
bv_pcl.compile_all(plb_name)
DESCRIPTION
Same as bv_pcl.compile() except that all files with a
.pcl extension in the current directory/folder are
compiled. Note that special MSC.Patran files such as
settings.pcl or p3epilog.pcl are not compiled.
INPUT
plb_name String[] Name of PCL library
file.
OUTPUT
<None>
EXAMPLE
bv_pcl.compile_all(My_pcl_library.plb)
The following function makes use of the bv_pcl class as well.
au_make_all()
DESCRIPTION
Same as bv_pcl.compile_all() except the PCL library
filename is specified via a file called au_makefile.dat
instead of as a function argument. The au_makefile.dat
file contains a single line which is the name of the PCL
library file, i.e., NT_break_elms.plb
INPUT
<None>
OUTPUT
<None>
EXAMPLE
au_make_all()
225/252
Appendix G
Parametric Patran

226/252
Appendix G
A goal of MSC.Patran Parametric Modeling is to make it

possible for the user to use names and default values for
variables (parameters) in every entry point on
every form that can be accessed for modeling
purposes
Provides an automated method of parametric
analysis in support of complex
models/processes
Allows users to parametrically investigate and
assess a number of different designs via batch
submittal of a number of different design studies
Permits the use of named variables to replace the usual fixed
numerical values of modeling parameters
The values of these parameters are provided by an external
configuration file

227/252
Appendix G
Parametric parameters incude:

Variables
Macros
Outputs
Variable definition
Variable name
Optional description
Datatypes include: Integer, Real, String, Integer array, Real
array, or String array (note that strings do not require
quotation marks)
Current value
Macro definition
Combination of variables and/or other macros, i.e.,
mesh_size = ~length~*~width~
Variable names are enclosed
by ~ symbols

228/252
Appendix G
Output definition
An analysis response or result

229/252
Appendix G
Notes
Parametric parameters are saved with the database
A configuration file can be used to supply new parameter
values. This allows automation, i.e., a driving program
could execute MSC.Patran batch jobs with different
configuration files to generate several model variations
automatically
Configuration file can be selected via:
An environment variable:
PARAMETRIC_MODELING_CONFIG_FILE
This must be set prior to the MSC.Patran session.

A PCL function:
parametric_modeling_util.define_user_config_file(config_file)
Sample session file with parameters:
parametric_modeling_util.create_variable( "length", "Real", "", "", "12", "" )

Real length = 12; em_sf_comment_previous_line()
$# Real length = 12; em_sf_comment_previous_line()
parametric_modeling_util.reset_variable( "length" )
parametric_modeling_util.create_variable( "height", "Real", "", "", "5", "" )
Real height = 5; em_sf_comment_previous_line()
$# Real height = 5; em_sf_comment_previous_line()
parametric_modeling_util.reset_variable( "height" )
parametric_modeling_util.create_macro( "mesh_density", @
"mth_min(~height~,~length~)*~mesh_factor~", "" )
FUNCTION mesh_density(); GLOBAL Real length; GLOBAL Real height; GLOBAL Real @
mesh_factor; RETURN( mth_min(height,length)*mesh_factor );END FUNCTION
$# Compiling: mesh_density
$# Compiled: mesh_density

230/252
Appendix G
The configuration file is simply a listing of the variable names

and corresponding values. An exclamation mark (!) denotes a
comment, i.e.,
variable_name= value ! comment
A sample configuration file:

length = 40
height = 10
hole_dia = 5
x_hole = 30
y_hole = 4
elastic_modulus = 30e6
applied_load = 120
thickness = .5
Another sample configuration file

maximum = 1000 ! this is an integer
three = 1, 2, 3 ! this is a 3 word integer array
data = 37.655 ! this is a real
moredata = 1.0, 2.0, 3.0, 4.0 ! this is a 4 word real array
name = mat1 ! this is a string variable, note no quotes
names = one, two, three ! this is a string array, again no quotes

231/252
Appendix H
Additional List Processor Notes

232/252
Appendix H
List Processor Mechanics
The List Processor evaluates or parses a Picklist for

information that the application needs.
The Picklist is retrieved from the specified Select Databox

using the ui_wid_get_vstring() command. This command
automatically sizes a virtual string to store the picklist data.
The low level, more flexible List Processor functions begin

with the prefix, lp_. In addition to these functions, there are
other more "user friendly" functions which perform more
specific tasks.
The user friendly functions also offer another benefit. Most

lp_ functions make calls to the database to obtain information
about the Picklist. The more user-friendly functions, such as
the fem_u_ functions, only evaluate for ids and do not require
querying the database. This gives the benefit of improved
performance.
When using the List Processor functions it is necessary to

#include the lpenums.p file with the C Preprocessor (cpp). This
file contains all the keywords used to define the evaluation
methods for interpreting the Picklist with the various List
Processor functions.
A Picklist may be comprised of one or more sublists. Each

sublist in a Picklist has a type and attributes associated to it.
If a user is selecting nodes and elements, each of the entity types
would comprise a sublist. The Picklist, Node 1 2 45 Element 2 4 6
contains two sublists based on use of the lp_sublist_node and
lp_sublist_element sublist filters.

233/252
Appendix H
List Processor Functions
The first lp_ function used is the lp_eval function. The lp_eval
command:
Evaluates the Picklist using a filter method, (lpenums.i)

A Picklist is evaluated for specific information. If a Picklist is
evaluated for GEOMETRY, then all FEM entities are skipped over.
Establishes an anchor or reference point in the Picklist
Returns a handle for identification of the Picklist.

The handle is used in all other lp_ functions.
Most common evaluation filters are:

LP_EVAL_FOR_ID
LP_EVAL_FOR _LABEL
LP_EVAL_FOR_GEOMETRY
LP_EVAL_FOR _FEM_DEFINITION
/* Evaluation methods for LpEval */

#define LP_EVAL_BARE_PARSE
#define LP_EVAL_PARSE_AND_EXPAND
#define LP_EVAL_FOR_TOKENS
#define LP_EVAL_FOR_ID
#define LP_EVAL_FOR_LABEL For retrieving label / ID info
#define LP_EVAL_FOR_GEOMETRY
#define LP_EVAL_FOR_FEM_DEFINITION For retrieving atttribute info
#define LP_EVAL_FOR_PICKLIST_ENUMERATION
#define LP_EVAL_FOR_PICKLIST_NORMALIZATION
#define LP_EVAL_FOR_PICKLIST_ADD
#define LP_EVAL_FOR_PICKLIST_DELETE

234/252
Appendix H
List Processor Sublist Functions
lp_sublist functions evaluate the Picklist for type and count

information, and moves the list pointer (Anchor) to the next
position.
lp_sublist_count(picklist, LP_SUBLIST_POINT, count) /* Count Points in List */
lp_sublist_ Function Use

lp_sublist_type() To get the current sublist type being
referenced.
lp_sublist_count() Counts the number of items in a given
sublist based on the sublist filter.
(The return count for LP_SUBLIST_POINT includes
finite element nodes and geometric points)
Set the list anchor position to the
/* lpenums.i SublistType filters for LpSublistType */
next sublist.
#define LP_SUBLIST_POINT_IMMEDIATE
#define LP_SUBLIST_VECTOR_IMMEDIATE
#define LP_SUBLIST_POINT
#define LP_SUBLIST_CURVE
#define LP_SUBLIST_SURFACE
#define LP_SUBLIST_SOLID
#define LP_SUBLIST_GEOMETRY \
(LP_SUBLIST_POINT_IMMEDIATE+LP_SUBLIST_VECTOR_IMMEDIATE+\
LP_SUBLIST_POINT+LP_SUBLIST_CURVE+LP_SUBLIST_SURFACE+\
LP_SUBLIST_SOLID+LP_SUBLIST_PLANE+LP_SUBLIST_VECTOR+\
LP_SUBLIST_PLANE_IMMEDIATE)
#define LP_SUBLIST_COORD_FRAME
#define LP_SUBLIST_VECTOR
#define LP_SUBLIST_AXIS
#define LP_SUBLIST_NODE
#define LP_SUBLIST_ELEMENT
#define LP_SUBLIST_MPC
#define LP_SUBLIST_FINITE_ELEMENT \
(LP_SUBLIST_NODE+LP_SUBLIST_ELEMENT+LP_SUBLIST_MPC)
#define LP_SUBLIST_PLANE
#define LP_SUBLIST_ANY
lp_sublist_next()

235/252
Appendix H
List Processor Attribute Functions
lp_sublist_attribute_ functions evaluate the Picklist based on a

sublist attribute filter.
lp attribute Functions Use
Return an integer value from a
lp_sublist_attribute_get_int() Picklist with a specified
attribute.
lp_sublist_attribute_get_float() Return a real value of integer

values from a Picklist with a
specified attribute.
lp_sublist_attribute_get_string() Return a string from a Picklist

with a specified attribute.
lp_sublist_attribute_get_inta() Return an array of integers from

a Picklist with a specified
attribute.
lp_sublist_attribute_get_floata() Return a real array from a

Picklist with a specified
attribute.
/* lpenum.i Attribute names for LpSublistAttributeGet */

#define LP_ATTRIBUTE_ID #define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS
#define LP_ATTRIBUTE_LABEL #define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS_ID
#define LP_ATTRIBUTE_GEOMETRY #define LP_ATTRIBUTE_GEOMETRY_IN_NATIVE_FORM
#define LP_ATTRIBUTE_GEOMETRY_TYPE #define LP_ATTRIBUTE_U_VALUE
#define LP_ATTRIBUTE_GEOMETRY_FORMAT #define LP_ATTRIBUTE_V_VALUE
#define LP_ATTRIBUTE_GEOMETRY_COMPANY_OF_ORIGIN #define LP_ATTRIBUTE_TOKEN_VALUE
#define LP_ATTRIBUTE_ORIGIN #define LP_ATTRIBUTE_EVALUATED_POINT
#define LP_ATTRIBUTE_ROTATION_MATRIX #define LP_ATTRIBUTE_POINT_COUNT
#define LP_ATTRIBUTE_COORDINATE_FRAME_TYPE #define LP_ATTRIBUTE_CURVE_COUNT
#define LP_ATTRIBUTE_LOCATION #define LP_ATTRIBUTE_SURFACE_COUNT
#define LP_ATTRIBUTE_DISPLACEMENT #define LP_ATTRIBUTE_SOLID_COUNT
#define LP_ATTRIBUTE_BASE #define LP_ATTRIBUTE_POINT_LIST
#define LP_ATTRIBUTE_TIP #define LP_ATTRIBUTE_CURVE_LIST
#define LP_ATTRIBUTE_CLASS_NAME #define LP_ATTRIBUTE_SURFACE_LIST
#define LP_ATTRIBUTE_TOPOLOGY_ID #define LP_ATTRIBUTE_SOLID_LIST
#define LP_ATTRIBUTE_DIMENSIONALITY #define LP_ATTRIBUTE_SIDE_NUMBER
#define LP_ATTRIBUTE_FACE_NUMBER #define LP_ATTRIBUTE_NORMAL
#define LP_ATTRIBUTE_EDGE_NUMBER #define LP_ATTRIBUTE_PLANE_COUNT
#define LP_ATTRIBUTE_VERTEX_NUMBER #define LP_ATTRIBUTE_PLANE_LIST
#define LP_ATTRIBUTE_NODE_COUNT #define LP_ATTRIBUTE_VECTOR_COUNT
#define LP_ATTRIBUTE_NODE_LIST #define LP_ATTRIBUTE_VECTOR_LIST
#define LP_ATTRIBUTE_ORIGINAL_PARSE_CLASS
#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS_TOPOLOGICAL_CONTEXT

236/252
Appendix H
Miscellaneous List Processor Functions
Other List Processor functions.

Functions Use
Print the entire Picklist from the
lp_print_list() anchor block to standard out.
Prints to stdout.
Print the sublist prepared by

lp_print_sublist()
lp_sublist_type from the anchor
block to standard out. Good for
determining the attributes
associated with a sublist item.
Frees allocated memory for list

lp_eval_cleanup()
processor operations. This should
be performed after lp_ operations
are complete
Reset the sublist parser to resume

lp_sublist_reset()
parsing the original Picklist.
Quick function to count the

fem_u_count_id_list() entities of a specified list
processor sublist type without
having to use all the other lp_
commands.
Quick function to extract the array

fem_u_extract_node_ids() of nodes IDs from a Picklist.
Quick function to return the

fem_u_get_id_list() entities ids of a specified list
processor sublist type without
having to use all the other lp_
commands.
Count the entities of a specified

app_count_id_list() list processor type in a list using
the picklist decoder routines.

237/252
Appendix H
List Processor Examples
Sublist Evaluation for Attributes
Attributes may be extracted from an item in a sublist.

Attribute information varies based on the sublist type
Attribute Examples
SubList Attribute Definition
Point Sublist Eval: LP_EVAL_FOR_GEOMETRY
Label 2 LP_ATTRIBUTE_LABEL
Id 2 LP_ATTRIBUTE_ID
GeometryInNativeForm [0. 0. 0. 0. 1. 0.] LP_ATTRIBUTE_GEOMETRY_IN_NATIVE_FORM
GeometryType CartesianPoint LP_ATTRIBUTE_GEOMETRY_TYPE
GeometryCompanyOfOrigin PATRAN LP_ATTRIBUTE_GEOMETRY_COMPANY_OF_ORIGIN
EvaluatedPoint [0.0 1.0 0.0] LP_ATTRIBUTE_EVALUATED_POINT
Element Sublist Eval: LP_EVAL_FOR_FEM_DEFINITION

Id 50 LP_ATTRIBUTE_LABEL
ClassName Bar2 LP_ATTRIBUTE_CLASS_NAME
TopologyId 2 LP_ATTRIBUTE_TOPOLOGY_ID
Dimensionality 1 LP_ATTRIBUTE_DIMENSIONALITY
NodeCount 2 LP_ATTRIBUTE_NODE_COUNT
NodeList [58 57] LP_ATTRIBUTE_NODE_LIST
Node Sublist Eval: LP_EVAL_FOR_FEM_DEFINITION

Id 12 LP_ATTRIBUTE_LABEL
Location [0.428571 0.142857 0.000000] LP_ATTRIBUTE_LOCATION
Code example
lp_sublist_attribute_get_int(handle,LP_ATTRIBUTE_LABEL,id)
Returns the label of the current item based on anchor position
lp_sublist_attribute_get_floata(handle_fem,
LP_ATTRIBUTE_LOCATION,BYTES_PER_REAL*3,xyz,size)
Returns Node or Point coordinates as a real array
lp_sublist_attribute_get_inta(handle_fem,
LP_ATTRIBUTE_NODE_LIST,BYTES_PER_INTEGER*cnt(1),nodes,size)
Returns an integer array of nodes associated to an element.

238/252
Appendix H
List Processor PCL Function
Sample PCL, retrieving a list of node labels and the count from a select databox.
FUNCTION get_n_ids(sdbox_wid, num_nodes, node_labels)
/*
* This function returns the node labels and count
* from the picklist of a select databox.
*
* INPUT: select databox widget ID
*
* OUTPUT: node_labels INTEGER ARRAY Node labels
* num_nodes INTEGER Number of nodes found
*
* This function is the equivalent of fem_u_extract_nodes_ids
*
* Equivalent procedure:
*
* ui_wid_get(sdbox,"VALUE",picklist)
* num_nodes = fem_u_count_id_list(LP_SUBLIST_NODE,picklist,TRUE)
* sys_allocate_array(node_labels,1,num_nodes)
* fem_u_extract_node_ids(picklist,num_nodes,node_labels)
*
*/
#include "lpenums.p"
WIDGET sdbox_id
INTEGER num_nodes, node_labels()
INTEGER i, status
INTEGER list_type, handle, id(1), ints(2)
INTEGER node_ids(VIRTUAL)
LOGICAL end_of_list = FALSE
REAL reals(2)
STRING picklist[VIRTUAL], str[10](2)
ui_wid_get_vstring(sdbox_wid, VALUE, picklist)
$ This line evaluates the pick list for labels and returns a handle
lp_eval(picklist, LP_EVAL_FOR_LABEL, handle)
$ Count the number of items of type node.

lp_sublist_count(handle, LP_SUBLIST_NODE, num_nodes)
IF (num_nodes > 0) THEN

sys_allocate_array(node_ids, 1, num_nodes)
write("Node count = "//str_from_integer(num_nodes))
ELSE
RETURN 1 /* Zero nodes found, exit function */
END IF

239/252
Appendix H
i = 0
REPEAT
/* Retrieve the sublist type */
status = lp_sublist_type(handle, LP_SUBLIST_ANY, list_type)
/* Print the sublist */

lp_print_sublist(handle)
IF(list_type == LP_SUBLIST_NODE) THEN
status = lp_sublist_attribute_get_int(handle, LP_ATTRIBUTE_LABEL, id)
IF(status != 0 ) THEN /* If error, print the error message and exit */

msg_to_form(status, 3, 0, ints, reals, str)
RETURN (-1)
END IF
i += 1
node_ids(i) = id
END IF
/* Get the next node */

status = lp_sublist_next(handle)
IF (status != 0 ) then
end_of_list = TRUE
END IF
UNTIL(i == num_nodes || end_of_list)
write(node_ids)
/* Set return variables to captured values */

sys_allocate_array(node_labels, 1, num_nodes)
sys_move_raw(node_ids, node_labels)
RETURN 0 /* Return zero for success */
END FUNCTION

240/252
Appendix H
List Processor Example, Pointer, (Anchor) Mechanics
The lp_sublist_next() command moves the list pointer to the

next item in the list.
The evaluation filter used with the lp_eval has no effect on the
lp_sublist_next() command. The next item in the list is always the next
pointer position.
Example
Picklist:"Elm 1 4 Point 55 56 Node 34 36"
Elm 1 4 Point 55 56 Node 34
1 2 3
4
lp_eval(picklist,LP_EVAL_LABEL,handle)
Evaluate the Picklist for Labels
l lp Anchor Points to Element 1
lp_sublist_next(handle)
2 lp Anchor Points to Element 4
lp_sublist_next(handle)
3 lp Anchor Points to Geometric Point 55
lp_sublist_reset(handle)
Resets to beginning of picklist
4 lp Anchor Points to element 1
lp_eval_cleanup(handle)
Terminates parsing for handle

241/252
Appendix H
Easy to Use List Processor Functions
The fem_u_count_id_list() function can be used to count

the number of entities in a sublist.
num_ids = fem_u_count_id_list(sublist_type, picklist, @
do_message, status)
The fem_u_get_id_list() function can be used to extract

the entity ids from the picklist based on the sublist type.
fem_u_get_id_list(sublist_type, picklist, num_ids, @
do_message, ids)
Example
#include lpenums.p
FUNCTION get_selected_elms(picklist, num_elms, elm_ids)
INTEGER status
INTEGER num_elms, elm_ids()
STRING picklist[]
num_elms = FEM_U_COUNT_ID_LIST(LP_SUBLIST_ELEMENT, @
picklist, FALSE, status)
IF (num_elms == 0) THEN
UI_WRITE(No elements selected!); RETURN (-1)
END IF
SYS_ALLOCATE_ARRAY(elm_ids, 1, num_elms)
status = FEM_U_GET_ID_LIST(LP_SUBLIST_ELEMENT, picklist, @

num_elms, FALSE, elm_ids)
RETURN (status)
END FUNCTION

242/252
Appendix H

243/252
Appendix I
Key Mapping

244/252
Appendix I
Key mapping is defined in a file named .Patran.EventMaps

(UNIX) or just Patran.EventMaps (PC)
MSC.Patran searches for this file 1st in the current
directory/folder, then in the users home directory/folder, and
finally in the MSC.Patran home directory/folder.
A sample Patran.EventMaps file
None<Key>F2: MouseRotateXY()
None<Key>F3: MouseRotateZ()
None<Key>F4: MousePanXY()
None<Key>F5: MouseZoom()
None<Key>F6: SelectCorners()
None<Key>F8: SelectCenter()
None<Key>F9: FitView()
None<Key>x: PanRight()
Shift<Key>x: PanLeft()
None<Key>y: PanUp()
Shift<Key>y: PanDown()
None<Key>z: ZoomIn()
Shift<Key>z: ZoomOut()
Ctrl<Key>x: RotPosX()
Alt<Key>x: RotNegX()
Ctrl<Key>y: RotPosY()
Alt<Key>y: RotNegY()
Ctrl<Key>z: RotNegZ()
Alt<Key>z: RotPosZ()
None<Key>l: LabelsOn()
Shift<Key>l: LabelsOff()
Ctrl<Key>s: SpectrumOnOff()
<Key>osfUp:PanUp()
<Key>osfDown:PanDown()
<Key>osfLeft:PanLeft()
<Key>osfRight:PanRight()
None<Key>1: RearView()
None<Key>2: BottomView()
None<Key>3: Iso1View()
None<Key>4: LeftSideView()
None<Key>6: RightSideView()
None<Key>7: FrontView()
None<Key>8: TopView()

245/252
Appendix I
Key modifiers can be either None, Ctrl, Alt, or Shift

The functions are pre-defined, i.e., TopView(),
FrontView(), etc. Custom functions can be access via the
CallPCL() function, i.e.,
None<Key>a: CallPCL(my_function)

246/252
Appendix J
Widget Classification

247/252
Appendix J
Widgets can be loosely classified into several categories

Those that register events (i.e., databoxes, buttons) and
those that dont (i.e., frames, forms). Essentially those
widgets that register events will have a callback functions.
Those that dont register events dont have callback
functions.
Simple widgets (i.e., toggles, buttons, databoxes) and
compound widgets (i.e., option menus, listboxes, switches)
Simple widgets are widgets that require only a single function
call to create. Examples include:
Buttons
Databoxes
Toggles
Compound widgets are widgets that require multiple function
calls to create. Generally the initial function call creates a
menu into which options or items are placed. In this sense the
initial call creates a placeholder and the additional function
calls add items. Examples include:
Optionmenus. The function ui_optionmenu_create()
creates the option menu while multiple calls to
ui_item_create() adds the menu items.
Switches
Listboxes

248/252
Appendix J
Of note is that the value of the compound widget that is

passed to the widgets callback function or extracted with
ui_wid_get() is name argument specified on the
ui_item_create() function call.
Example (excerpted, abbreviated)
CLASS my_class
CLASSWIDE WIDGET main_form, my_opt_menu
FUNCTION init()
my_opt_menu = ui_optionmenu_create(main_form, @
my_opt_menu_cb, x_loc, y_loc, 0, @
Action:, TRUE)
ui_item_create(my_opt_menu, C, Create, FALSE)
ui_item_create(my_opt_menu, E, Edit, FALSE)
ui_item_create(my_opt_menu, D, Delete, FALSE)
$ ui_item_create(parent, name, label, toggleable)
END FUNCTION
FUNCTION my_opt_menu_cb(value)
STRING value[]
SWITCH (value)
case (C)
/* display create options */
case (E)
/* display edit options */
case (D)
/* display delete options */
END SWITCH
END FUNCTION
END CLASS

249/252
Appendix J

250/252
Appendix K
User Defined AOM

251/252
Appendix K

252/252

MSC.Patran PCL Handbook: An Introduction to Programming with PCL

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MSC.Patran PCL Handbook: An Introduction to Programming with PCL

Uploaded by

Copyright:

Available Formats

MSC.

Patran PCL Handbook

REAL x_loc, y_loc, form_width, form_height

PCL for Everyone........................................................................................................................10

PCL for the More Adventurous..................................................................................................16

Exercise 1: Session Files...........................................................................................................21

PCL Programming Basics..........................................................................................................23

Structure of a PCL Function......................................................................................................29

Exercise 2: Hello World!.............................................................................................................32

Exercise 3: Effective PCL...........................................................................................................33

PCL Variables and Constants....................................................................................................35

Loop Control Statements...........................................................................................................41

Exercise 4: Writing Files............................................................................................................45

Exercise 5: Reading Files..........................................................................................................47

Conditional Control Statements................................................................................................48

Structure of a PCL Function......................................................................................................50

Compiling and Linking PCL Functions....................................................................................53

Accessing PCL Functions.........................................................................................................66

MSC.Patran Built-In Functions..................................................................................................69

Exercise 7: Group Elements By Shape....................................................................................73

Graphical User Interface............................................................................................................74

MSC.Patran PCL Workshop Notes 05/05/17

Exercise 8: Simple Form............................................................................................................91

The C-Preprocessor and Include Files.....................................................................................92

Handling Errors and Messaging...............................................................................................97

Exercise 10: Form to Group Elms By Shape.........................................................................109

Executing Programs Outside of MSC.Patran.........................................................................111

Exercise 11: File Widget...........................................................................................................121

Adding Help/Description to your PCL....................................................................................122

Exercise 12: Primitive Graphics..............................................................................................130

Exercise 13: Pulldown Menu...................................................................................................137

Exercise 14: Toolbar.................................................................................................................138

Some Final Thoughts...............................................................................................................140

MSC.Patran PCL Workshop Notes 05/05/17

MSC.Patran PCL Workshop Notes 05/05/17

PCL stands for Patran Command Language

MSC.Patran PCL Workshop Notes 05/05/17

What can PCL be used for?

Integrate application or site-specific programs with the

MSC.Patran PCL Workshop Notes 05/05/17

How does PCL work?

All MSC.Patran commands are first interpreted by the PCL

C, C++ Fortran Other

MSC.Patran PCL Workshop Notes 05/05/17

All you really need to know is on this page!

PCL and Customization - General programming guide for PCL.

Programming Task Documentation Comments

MSC.Patran PCL Workshop Notes 05/05/17

Use of PCL when creating spatial fields:

The PCL interpreter interprets anything

MSC.Patran PCL Workshop Notes 05/05/17

Use of PCL when entering geometric coordinates:

The PCL interpreter evaluates expressions enclosed in back

MSC.Patran PCL Workshop Notes 05/05/17

Session and journal files are comprised entirely of PCL

MSC.Patran PCL Workshop Notes 05/05/17

The following session file creates a trimmed surface, 10 x10

$# Session file patran.ses.01 started recording at 16-Aug-01 14:33:54

MSC.Patran PCL Workshop Notes 05/05/17

In the session file below, the previous session file is edited to

$# Session file patran.ses.01 started recording at 16-Aug-01 14:33:54

MSC.Patran PCL Workshop Notes 05/05/17