5626 PCLWorkshopNotes.11!18!04

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

frame_width
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
01/22/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
init() Function.........................................................................................................................................................77
The display() Function...............................................................................................................................................78
The
Widget Callbacks............................................................................................................................................... 81
What Are They?..................................................................................................................................................................81
What Are They Used For?..................................................................................................................................................82
01/22/17
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
01/22/17
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
01/22/17
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
01/22/17
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
01/22/17
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
01/22/17
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
01/22/17
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

5.5
Functions for parsing a string

or picklist, i.e., Elm 1:9:2
Applications, session file,

result utilities
PCL Reference Guide
All functions written to the

session file
Graphics
PCL & Customization, chapter

3.2
Functions for drawing graphic

primitives such as lines,
arrows, text, etc.
Database functions
PCL & Customization, chapter 8
Functions to access data in

the database (i.e., node
coordinates, element
connectivity, element
properties, etc.)
Architecture
PCL & Customization, chapters 6 Functions for creating analysis

&7
preferences
01/22/17
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().
01/22/17
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 ]
01/22/17
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
01/22/17
13/252
PCL for Everyone
Rebuilding Models
A.
B.
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.
sgm_edit_surface_add_hole( 1,
1.,
TRUE, "", "[5 5 0]", "", "Surface 1",
A. Create/Surface/XYZ
B. Edit/Surface/Add Hole
01/22/17
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
sgm_edit_surface_add_hole( 1,
4.,
TRUE, "", "[5 5 0]", "", "Surface 1",
01/22/17
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.
01/22/17
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
01/22/17
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)
01/22/17
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.
01/22/17
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
asm_const_patch_xyz( "1", "<10 10 0>", "[0 0 0]", "Coord 0",
sgm_edit_surface_add_hole( 1, `radius` , TRUE, "", "[5 5 0]", @
"", "Surface 1", sgm_edit_surface_add_h_edit_ids )
01/22/17
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)
END FUNCTION /* display
Hitting the*/Apply button executes the function: apply_button_cb()
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 */
01/22/17
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.
01/22/17
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
01/22/17
23/252
PCL Programming Basics

Overview
PCL is a full-featured programming language.
Operators for arithmetic, relational, and string expressions.

Examples include:
multiplication
string concatenation
//
logical or
||
logical equal
==
logical not equal
!=
i, j, status, NodeIds(1000)
flag
xyz(1000, 3), pressure(100), time
my_group[32], all_groups[32](100)
Dynamically allocated virtual strings and arrays

INTEGER
STRING
Variables with type, scope, and dimension attributes

INTEGER
LOGICAL
REAL
GLOBAL STRING
addition
node_ids(VIRTUAL)
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])
01/22/17
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)
01/22/17
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)
01/22/17
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
01/22/17
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
01/22/17
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
01/22/17
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.
01/22/17
30/252
Simple PCL function Example

Function declaration
Function arguments (null)
FUNCTION a_very_simple_function()
/* This is a simple function that writes:
$# My favorite number is 29
in the MSC.Patran history window using 3 different
write or print statements.
*/
/* This is a comment. */
This is also a comment.
Comments (Who we
kidding? We all know
that everyone loathes
commenting their
code!)
Variable declaration
INTEGER MyFavoriteNumber
Variable initialization
MyFavoriteNumber = 29
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
01/22/17
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
another_simple_function(29)
Note all variables must be

Calling statement
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

$#My least favorite number is 13
Sample output
01/22/17
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?
01/22/17
33/252
Exercise 3: Effective PCL

Write an essay on how the effective use of PCL could:
a)
b)
c)
d)
Help create a lasting world peace

Eliminate world hunger
Conquer the common cold
Stop global warming
Extra credit: How could PCL be used to find Elvis?
01/22/17
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 !=
To perform case sensitive comparisons use the str_equal()

function, i.e.,
TEST
IF (str_equal(GroupName1, GroupName2)) THEN RETURN 0

01/22/17
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
01/22/17
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()
GLOBAL REAL
b
STATIC INTEGER c
FUNCTION WheresWaldo(x)
GLOBAL REAL a
REAL
c, d, e
INTEGER
x
CLASS training
CLASSWIDE REAL d, e
FUNCTION MyFunc(q, r)
INTEGER
f
GLOBAL REAL a, b, c
REAL
q, r
Note that variables passed as

arguments must be declared
FUNCTION init()
INTEGER c, f, g
If you are going to change the value of a

global variable within a function, you must
declare the global variable within your
function.
01/22/17
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)

INTEGER MyArray(2, 3) = 1, 2, 3, 4, 5, 6
1
4
2
5
3
6
Array dimensions are inherited from the argument list, i.e., PCL
passes by reference
FUNCTION MyFunc()
STRING MyString[32](32)
YourFunc(MyString)
END FUNCTION
FUNCTION YourFunc(MyVal)
STRING MyVal[]()
END FUNCTION
Declaration Examples
REAL
STRING
INTEGER
LOGICAL
displacements(6, 200)
group_names[32](20)
ids(0:2, 0:4, 0:10)
exists(12)
01/22/17
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)
01/22/17
39/252

Virtual array example
FUNCTION CompareNodes(num_nodes, node_ids)
INTEGER
INTEGER
INTEGER
LOGICAL
i, j, status
num_nodes, node_ids()
num_db_nodes, db_node_ids(VIRTUAL)
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 */
01/22/17
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)
01/22/17
41/252
Loop Control Statements

For Loop
Syntax
FOR (var=numeric_expr TO
statements
END FOR
numeric_expr
[BY
Example
numeric_expr])
[label]
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
01/22/17
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)
01/22/17
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
reached. Execution
then breaks out of the
WHILE loop to the
statements
immediately following
the loop.
BREAK [label]
Example 1(reading a text file)

WHILE (TRUE)
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
IF
IF
IF
(status
(status
(status
(status
!=
!=
!=
!=
0)
0)
0)
0)
THEN
THEN
THEN
THEN
BREAK MainLoop
BREAK AnotherLoop
BREAK
BREAK InnerLoop
END WHILE
statements
END WHILE
statements
END WHILE
statements
01/22/17
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
01/22/17
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
01/22/17
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.
01/22/17
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 builtin 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)

a) Declare variables
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()?
01/22/17
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
01/22/17
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
SWITCH (EntityType)
CASE (CBAR, CBEAM)
statements
CASE (CTRIA, CQUAD)
statements
CASE (GRID)
statements
DEFAULT
statements
END SWITCH
Note that this SWITCH

statement is equivalent to the
IF statement on the previous
page.
01/22/17
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
NumOut = NumIn + 3.14
ui_write(NumIn = //STR_FROM_REAL(NumIn))
ui_write(NumOut = //STR_FROM_REAL(NumOut))
Output argument (NumOut)
END FUNCTION /* still_another_function */
calling_function()
$#NumIn = 5.0
$#NumOut = 8.14
$#Var2 = 8.14
Calling statement
Sample output
01/22/17
51/252
Example 2 (function or command example)

FUNCTION calling_subroutine2()
REAL MyVal
REAL a(3) = [1.0, 1.0, 2.0]
REAL b(3)
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
parentheses to indicate that the argument is
an array. The array dimensions within the
function DotProduct is inherited (3 in this
case) from the array dimensions within the
calling function (calling_subroutine2 in
this case).
FUNCTION DotProduct(a, b)
REAL a(), b()
REAL val
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
01/22/17
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 */
01/22/17
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.
01/22/17
54/252
Primary PCL Directives
!!INPUT redirects input to come from a specified file instead of

the keyboard.
!!INPUT filename
Does not necessarily take place immediately. Only

when the heartbeat turns green.
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
$# Compiled: test
Indicates that MSC.Patran is compiling the function, 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.
01/22/17
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
01/22/17
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
!!LIB REMOVE file
!!LIB MERGE source_file dest_file
!!LIB DELETE file function [function]
!!LIB LIST file
!!LIB
links file with the

current MSC.Patran session
unlinks file from the
current MSC.Patran session
Merges functions from
source_file into dest_file
Deletes the specified
functions from the file
Lists all functions in file
Lists all PCL libraries
linked with the current
MSC.Patran session
Example usage
01/22/17
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]
!!PATH NONE
!!PATH
Removes the specified directories

from the search path
Removes all directories from the
search path
Lists all directories currently in the
search path
The last !!PATH statement is searched first. Within a

statement, the directories are searched first to last.
!!PATH /abc
/def
!!PATH
/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.
01/22/17
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.
01/22/17
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
01/22/17
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.
01/22/17
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
01/22/17
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.
01/22/17
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"
Offending line
***Error: Compilation aborted
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.
01/22/17
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]
01/22/17
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.
01/22/17
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))
01/22/17
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 `
01/22/17
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
01/22/17
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.
01/22/17
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
01/22/17
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_,
virtual_,
record,
text_,
stream_
file reading and writing
gm_
drawing graphic primatives
str_
string manipulation functions
mth_
math functions
sys_
system and memory operations
lp_, app_,
fem_u_
list processor functions
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

right function!!!
Sigh, I give up!!!

I cant find the
function but I know
one exists
somewhere!
Which function do I
use?
Aaaarrgghhhh!
Relief is in sight!
01/22/17
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
01/22/17
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)

a)
Declare variables
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.
01/22/17
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.
01/22/17
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 */
01/22/17
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
Frame Label
Select Frame Label

Select databox1 label
Menu Label:
Menu item
Select databox2 label
Menu Label:
Menu item
Databox Label
Button 1
Button 2
01/22/17
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)
@
@
@
@
@
@
@
@
@
@
@
@
@
@
@
01/22/17
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
01/22/17
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.
01/22/17
80/252
Widget Heirarchy
Widgets are created in a hierarchical manner. Every widget

has a parent except the form.
main_form = ui_form_create(
/* callback
*/
/* x position */
/* y position */
/* relative to */
/* width
*/
/* height
*/
/* label
*/
/* unused
*/
"",
FORM_X_LOC,
FORM_Y_LOC,
"UL",
FORM_WID_SML,
FORM_HGT_QTR,
"Form Label",
"")
my_button = ui_button_create(
/* parent
*/ main_form,
/* callback
*/ "my_button_cb",
/* x position */ FORM_L_MARGIN,
/* 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(
/* parent
*/
/* callback
*/
/* x position */
/* y position */
/* width
*/
@
main_form,
@
,
@
x_loc,
@
y_loc,
@
FORM_WID_SML, )
inner_button = ui_button_create(
/* parent
*/ my_frame,
/* callback
*/ "inner_button_cb",
/* x position */ FRAME_L_MARGIN,
/* y position */ y_loc,
/* width
*/ BUTTON_WID_FULL,
/* 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.
01/22/17
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.
my_button = ui_button_create(
/* parent
*/ my_frame,
/* callback
*/ "my_button_cb",
/* width
*/ BUTTON_WID_FULL,
/* height
*/ BUTTON_HGT,
)
@
@
@
@
@
@
The callback function must be defined within the same class as

the init() function.
01/22/17
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.
01/22/17
83/252

Widget Type
Data Type
Description of Callback data
button
No arguments passed
buttonicon
No arguments passed
cascadeitem
Does not register events
colorbar
form
Widget Id of the colorbar

User data
Selected color Id
Widget Id of the colorbar
User data
Selected color Id
GAIN, LOSE, CR, or WIDSET (if
appropriate ui_wid_set() call has been
made) depending on which event initiated
the callback
Complete pathname of the selected file
OPEN or CANCEL
frame
graph
item
itemicon
label
labelicon
colormenu
databox
file
Widget
Integer
Integer
Widget
Integer
Integer
String[]
String[]
String[]
listbox
Integer
String[]()
menu
menubar
String[]
modalform
Number of selected items

Label of the selected items in the
listbox
Name of the selected menu item
optionmenu
scrollframe
String[]
Name of the currently selected item

selectdatabox
String[]
selectframe
GAIN, LOSE, CR, or WIDSET (if

appropriate ui_wid_set() call has been
made) depending on which event initiated
the callback
separator
slidebar
spreadsheet
switch
Real
String[]
String[]
Integer
Integer
Integer
Integer
String[]
Current value of the slidebar

VALUE_CHANGED or DRAG
SELECTED
starting selected column
starting selected row
ending selected column
ending selected row
selected layer
Name of the switch item changed
01/22/17
84/252
String[]
ON or OFF
Logical
Logical
Value of the toggle, TRUE or FALSE

Value of the toggleicon, TRUE or FALSE
text
toggle
toggleicon
01/22/17
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
FRAME_LABEL_HGT
FRAME_1EDGE
FRAME_T_MARGIN
OPT_MENU_HGT
INTER_WIDGET_SPACE
OPT_MENU_HGT
FORM LABEL
Frame Label
Menu Label:
Menu item
Menu Label:
Menu item
FRAME_B_MARGIN
FRAME_1EDGE
INTER_WIDGET_SPACE
DBOX_HGT_LABOVE
Databox Label
INTER_WIDGET_SPACE
BUTTON_HGT
FORM_B_MARGIN
Button 1
FORM_L_MARGIN
Button 2
FORM_R_MARGIN
01/22/17
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(
/* parent
*/
/* callback
*/
/* x position */
/* y position */
my_frame,
"",
FORM_L_MARGIN,
y_loc,)
@
@
@
@
y_loc += DBOX_HGT_LABOVE + INTER_WIDGET_SPACE

apply_btn = ui_button_create(
/* parent
*/ my_frame,
/* 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.
01/22/17
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(
/* parent
*/
/* callback
*/
/* x position */
/* y position */
/* width
*/
@
main_form,
@
,
@
x_loc,
@
y_loc,
@
"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(
/* parent
*/ my_frame,
/* callback
*/ "apply_cb",
/* width
*/ BUTTON_WID_FULL,
/* height
*/ BUTTON_HGT,
)
@
@
@
@
@
@
01/22/17
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.
01/22/17
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)
01/22/17
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)
01/22/17
91/252
END FUNCTION
01/22/17
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
main_form = ui_form_create(
/* callback
*/
/* x position */
/* y position */
/* relative to */
/* width
*/
/* height
*/
/* label
*/
/* unused
*/
@
@
@
@
@
@
@
@
"",
FORM_X_LOC,
FORM_Y_LOC,
"UL",
FORM_WID_SML,
0,
"Form Label",
"")
y_loc = FORM_T_MARGIN
my_dbox = ui_databox_create(
/* parent
/* callback
/* x position
/* y position
/* label length
/* box length
/* label
/* value
/* label above
/* datatype
/* number of values
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
main_form,
"",
FORM_L_MARGIN,
y_loc,
0,
DBOX_WID_SINGLE,
"Enter a Value",
"",
TRUE,
"REAL",
1)
@
@
@
@
@
@
@
@
@
@
@
y_loc += DBOX_HGT_LABOVE + INTER_WIDGET_SPACE

apply_btn = ui_button_create(
/* parent
*/ main_form,
/* callback
*/ "apply_btn_cb",
/* x position */ BUTTON_THIRD_X_LOC1,
/* width
*/ BUTTON_WID_THIRD,
/* height
*/ 0,
/* label
*/ "Apply",
/* unused
*/ TRUE,
/* highlight */ TRUE)
@
@
@
@
@
@
@
@
@
01/22/17
93/252

cancel_btn = ui_button_create(
/* parent
*/ main_form,
/* 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 */
01/22/17
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.
01/22/17
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.
01/22/17
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
01/22/17
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
01/22/17
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.
01/22/17
99/252
Exercise 9
FORM_X_LOC, FORM_Y_LOC
01/22/17
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.
01/22/17
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
01/22/17
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
01/22/17
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
01/22/17
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
01/22/17
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.
01/22/17
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()
01/22/17
107/252
Select Mechanism
GUI PCL Example
sframe_id = ui_selectframe_create
/* parent
*/
/* callback
*/
/* Left_margin
*/
/* Y Location
*/
/* col_width
*/
/* height
*/
/* Label
*/
/* recycle
*/
(
@
form_id,
@
"apply_cb",
@
FORM_L_MARGIN,
@
yloc,
@
SFRAME_WID_SINGLE,
@
SFRAME_1SDB_HGT_LABOVE,@
Auto Execute,
@
TRUE )
sdbox_width= SDBOX_WID_SINGLE - 2*SFRAME_R_MARGIN

select_data_box1 = ui_selectdatabox_create (
/* parent_frame
*/ sframe_id,
/* callback
*/ "",
/* 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
01/22/17
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.
01/22/17
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.
01/22/17
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
picklist
do_message
status
INTEGER
STRING
LOGICAL
INTEGER
OUTPUT:
num_ids
INTEGER
See note below
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
01/22/17
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 */
01/22/17
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.
01/22/17
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.
01/22/17
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
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
utl_process_spawn(command,wait)
Code Example
stat = utl_process_spawn( read_results.exe, TRUE )
IF( utl_process_error( stat ) ) THEN
utl_display_process_error( stat, 3 )
END IF
01/22/17
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
01/22/17
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
01/22/17
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.
01/22/17
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
01/22/17
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
01/22/17
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.
01/22/17
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
*/
/* callback
*/
/*
x
*/
/*
y
*/
/*
width
*/
/*
rows
*/
/* filterlabel */
/* filter mask */
/* Dir label */
/* files label */
/* Select label*/
/* Selection */
/* OK label
*/
/* filt btn lab*/
/* Cancel label*/
@
form_id,
@
"file_cb",
@
FORM_L_MARGIN,
@
FORM_T_MARGIN,
@
FILE_WID_DOUBLE, @
6,
@
"Filter",
@
"*.db",
@
"Directories",
@
"Database List", @
"Existing Database Name",@
"",
@
"OK",
@
"Filter",
@
"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.
01/22/17
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
01/22/17
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.
01/22/17
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?
01/22/17
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)
01/22/17
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 */
01/22/17
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.
01/22/17
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
01/22/17
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.
01/22/17
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.
01/22/17
131/252
Primitive Graphics
Example
INTEGER SegmentId
gm_segment_create(SegmentId)
gm_draw_line(SegmentId,
5,
5,
5,
5,
[0
[1
[1
[0
0
0
1
1
0],
0],
0],
0],
[1
[1
[0
[0
0
1
1
0
0])
0])
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
graphics
01/22/17
132/252
Primitive Graphics
Another Example
FUNCTION Draw2DBox(ColorId, UpperLeft, LowerRight, SegmentId)
/*
Input
Output
*/
ColorId
UpperLeft(2)
LowerRight(2)
SegmentId
<return value>
INTEGER
REAL
REAL
INTEGER
INTEGER
INTEGER ColorId, SegmentId

INTEGER status
REAL
REAL
UpperLeft(), LowerRight()
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(2, 3)
= 0.0
BoxCorners(3, 1) = LowerRight(1)
BoxCorners(3, 2) = UpperLeft(2)
BoxCorners(3, 3) = 0.0
BoxCorners(4, 1:2) = UpperLeft(1:2)
BoxCorners(4, 3)
= 0.0
status = gm_segment_create(SegmentId)
status = gm_draw_line(SegmentId, ColorId,
BoxCorners(1, 1:3), BoxCorners(2, 1:3))

01/22/17
133/252
status = gm_segment_flush()
RETURN 0
END FUNCTION /* Draw2DBox */
01/22/17
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()
01/22/17
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.
01/22/17
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,
dump_nodes,
,
push_me,
football,
group_by_shape,
Hello World!,
Write Nodal Data,
,
Push Me ,
Football Scores ,
Group Elms By Shape ,
FALSE)
FALSE)
FALSE)
FALSE)
FALSE)
FALSE)
FUNCTION display()
/* Dummy display function. The display function is not really necessary
since the menubar is automatically displayed by MSC.Patran. */
FUNCTION user_menu_cb(item)
The item name parameter is passed as an

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 */
01/22/17
137/252
END CLASS /* my_pulldown_menu */
01/22/17
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 = My_Menu
*CLASS
= -NA*FUNCTION = hello_world
*LABEL
= Hello World!
*LOAD ITEM
Menu label
Executes a function that is not

contained within a PCL Class. The
function cannot have any
arguments.
*SEPARATOR
*CLASS
= push_me_form
*FUNCTION = display
*LABEL
= Push Me
*LOAD ITEM
*CLASS
= football_scores
*FUNCTION = display
*LABEL
= Football Scores
*LOAD ITEM
*CLASS
= group_elms_by_shape
*FUNCTION = display
*LABEL
= Group Elms By Shape
*LOAD ITEM
Opens a form via the

ui_exec_function(classname, function) command.
Example:
ui_exec_function(football_scores, display)
Pulldown menus are designed to

open forms. This is why selecting a
menu item executes:
ui_exec_function()
01/22/17
139/252
01/22/17
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.
*ICON = tbrotatexy.28.icon
*CLASS = uil_toolbar
*FUNCTION = rotate_xy
*HELP = Mouse rotate XY
*LOAD ITEM
PCL function that will be executed is:

uil_toolbar.rotate_xy()
*ICON = tbploterase.icon
*CLASS =
*FUNCTION = tbd(uil_imaging_plot_erase)
*HELP = Plot/Erase form (Display menu)
*LOAD ITEM
Toolbar icons are designed to

perform an action. This is why
selecting an icon executes the
classname.function() instead of
ui_exec_function()
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.
01/22/17
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.
01/22/17
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.
01/22/17
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
01/22/17
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.
01/22/17
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 */
01/22/17
146/252
01/22/17
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).
01/22/17
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
INTEGER
INTEGER
INTEGER
i, j, status
num_bars, bar_ids()
elm_connect(1, 2)
rcids(1), acids(1)
REAL
REAL
REAL
bar_len()
xyz(2, 3)
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
01/22/17
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
INTEGER
INTEGER
INTEGER
INTEGER
i, j, p1, p2, status

num_bars, bar_ids()
elm_connect(VIRTUAL)
num_nodes, node_ids(VIRTUAL)
idum(VIRTUAL)
REAL
REAL
REAL
bar_len()
xyz(VIRTUAL)
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
01/22/17
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
01/22/17
151/252
Appendix A
Built-in Function Examples
01/22/17
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
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
Output
Notes: The C name differs. It is DbFGetNodes.

int DbFGetNodes(num_nodes, node_ids, rcids, acids, global_xyz)
int
int
int
int
float
num_nodes
*node_ids
*rcids
*acids
*global_xyz
01/22/17
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
0.00
0.00
0.00
5.12
-6.34
4.90
25
56.20
9.01
-1.10
01/22/17
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
Tet
Bar
Pyramid
NA
01/22/17
155/252
Tria
Wedge
Quad
Hex
01/22/17
156/252
Appendix A
To get the shape of every element

INTEGER ElmShapeCodes(VIRTUAL), NumNodesPerElm(VIRTUAL)
1, NumElms)
sys_allocate_array(ElmTopoCodes, 1, NumElms)
sys_allocate_array(ElmShapeCodes, 1, NumElms)
sys_allocate_array(NumNodesPerElm, 1, NumElms)
db_get_elem_topology_data(NumElms, ElmTopoCodes, ElmShapeCodes, @
NumNodesPerElm)
01/22/17
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(ElmTopoCodes,
sys_allocate_array(ElmShapeCodes,
sys_allocate_array(NumNodesPerElm,
1,
1,
1,
1,
NumElms)
NumElms)
NumElms)
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)
01/22/17
158/252
Appendix A
To get the elements associated to a particular

element property set
FUNCTION GetElmsForPropSet(MyPropertySetName, NumElms, ElmIds)

INTEGER
INTEGER
INTEGER
INTEGER
i
NumElms, ElmIds()
NumRegions, RegionIds(VIRTUAL)
MyRegionId
LOGICAL match
STRING
STRING
MyPropertySetName[]
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)
sys_allocate_array(ElmIds, 1, NumElms)
01/22/17
159/252
db_get_elements_in_region(MyRegionId, NumElms, ElmIds)

RETURN 0
END FUNCTION
01/22/17
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
INTEGER
INTEGER
INTEGER
REAL
REAL
STRING
p
ElmId
ElmIds(1), ElmRegionIds(1)
MaterialId, DataType, IntegerVal, CoordId, NodeId, FieldId
ElmThick, ThickVals(VIRTUAL)
RealVals(3)
CharVal[80]
ElmIds(1) = ElmId
db_get_region_for_elements(1, ElmIds, ElmRegionIds)
db_count_prop(ElmRegionIds, NumWords)
IF (NumWords == 0) THEN RETURN 1
36 is the property word Id for

thickness. Other property words
and their associated Ids can be
found listed in the table of generic
property words in Chapter 7 of the
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
01/22/17
Material reference
11
Section ID (dimensions)
161/252
12
Section ID (properties)
Negative datatypes denote field reference.
RETURN 0
END FUNCTION
01/22/17
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)
REAL
ElmThick, ThickVals(VIRTUAL)
See note on previous page
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
01/22/17
163/252
01/22/17
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
IF (FieldIds(p) != 0) THEN
/* Elastic Modulus is defined
by a field */
ELSE
ElasticModulus = WordVals(p)
END IF
2 is the material property

word Id for the Elastic
Modulus. Other material
property word Ids can be
found in the table of Material
Property Words in Chapter 7
of the PCL and Customization
documentation.
RETURN 0
END FUNCTION
01/22/17
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.
01/22/17
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)
01/22/17
167/252
IF (NumElms > 0) THEN

sys_allocate_array(ElmIds, 1, NumElms)
db_get_elem_ids_in_group(NumElms, GroupId, ElmIds)
END IF
01/22/17
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
01/22/17
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
01/22/17
170/252
Appendix A
Element Ids
Coordinate reference
01/22/17
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
01/22/17
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:
OUTPUT:
lc_id
lc_name
INTEGER
STRING
db_get_load_case_id(lc_name, lc_id)
INPUT:
OUTPUT:
lc_name
lc_id
STRING
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:
OUTPUT:
num_rc
lc_ids
num_sc_per_lc
INTEGER
INTEGER ARRAY
INTEGER ARRAY
res_utl_get_subcases(lc_id, num_sc, sc_ids)

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

coordinates, rc_names)
INPUT:
OUTPUT:
<None>
num_rc
lc_ids
sc_ids
coordinates
rc_names
INTEGER
INTEGER ARRAY
INTEGER ARRAY
INTEGER_ARRAY
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)
INPUT:
OUTPUT:
num_rc
lc_ids
sc_ids
rc_ids
INTEGER
INTEGER ARRAY
INTEGER ARRAY
INTEGER ARRYA
01/22/17
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:
OUTPUT:
prim_id
prim_label
INTEGER
STRING
db_get_primary_res_id(prim_label, prim_id)
INPUT:
OUTPUT:
prim_label
prim_id
STRING
INTEGER
db_get_secondary_res_label(prim_id, sec_id, sec_label)

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

INPUT:
OUTPUT:
prim_id
sec_label
sec_id
INTEGER
STRING
INTEGER
res_data_get_result_names(prim_id, sec_id, @
prim_label, sec_label)
INPUT:
OUTPUT:
prim_id
sec_id
prim_label
sec_label
INTEGER
INTEGER
STRING
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)
INPUT:
OUTPUT:
num_rc
lc_ids
sc_ids
num_res
prim_ids
sec_ids
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
ARRAY
ARRAY
ARRAY
ARRAY
01/22/17
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)
INPUT:
OUTPUT:
lc_id
prim_id
sec_id
rt_id
INTEGER
INTEGER
INTEGER
INTEGER
res_data_get_restype_ids(rt_id, prim_id, sec_id)

INPUT:
OUTPUT:
rt_id
prim_id
sec_id
INTEGER
NTEGER
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:
OUTPUT:
res_ids(4)
num_layers
layer_ids
layer_labels
INTEGER ARRAY, lc_id, sc_id, prim_id, sec_id

INTEGER
INTEGER ARRAY
STRING ARRAY
res_data_get_layerpos_name(layer_id, layer_name)
INPUT:
OUTPUT:
layer_id
layer_name
INTEGER
STRING
res_data_get_layerpos_id(layer_name, layer_id)
01/22/17
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)
STRING
ElmList[]
STRING
Derivation[10]
STRING
Location[]
STRING
CID[]
MSC.Patran internal loadcase ID,

subcase ID, primary result ID,
secondary result ID, and layer ID.
List of elements to extract results
for.
Derivation specifier if the results
are to be derived, i.e., VONM,
MAJOR, etc. A null value () will
leave the result as is.
Location at which to extract the
results. Null () or A=as is,
C=element centroid, and
N=element nodes.
Coordinate system for vector and
tensor transformations. A null
string () is used to leave the
coordinate specification as is.
OUTPUT
INTEGER
DataType
INTEGER
ResLoc
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.
Location within the element for the
extracted results. Valid values
are: 1=centroid, 2=nodal, and
01/22/17
176/252
INTEGER
Nres
INTEGER
INTEGER
REAL
Ids(VIRTUAL)
Nresults(VIRTUAL)
ResVals(VIRTUAL)
INTEGER
MinLoc(12)
INTEGER
MaxLoc(12)
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.
Number of returned element
identifiers
Array of element identifiers
Number of results per element
Result values at the specified
element locations
Offsets within the ResVals array
for each minimum result component.
Offsets within the ResVals array
for each maximum result component.
01/22/17
177/252
Appendix B
Strings & String Functions
01/22/17
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
01/22/17
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.
Integer
Length of MyString.
OUTPUT
<return value>
EXAMPLE
length = str_length(abcde)
length -> 5
01/22/17
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
String[]
Extracted substring of the

input string.
OUTPUT
<return value>
EXAMPLES
NewString = str_substr(abcde, 1, 2)
NewString -> ab
NewString2 = str_substr(abcde, 4, 10)
NewString2 -> de
01/22/17
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.
String[]
The original string (MyString)

with a portion of MyString
replaced by MyString2.
OUTPUT
MyString
EXAMPLES
MyString = abxyzf
str_assign(MyString, 3, 3, cde)
MyString -> abcdef
01/22/17
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.
Integer
Position where MyString2 was

found within MyString1 where 1
is the first position. Zero is
returned if the string is not
found
OUTPUT
<return value>
EXAMPLES
Position = str_index(abcdef, cde)
Position -> 3
Position = str_index(abcdef, xyz)
Position -> 0
01/22/17
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.

must be at least 1.
Compress
Logical
Optional. If TRUE then empty

tokens will be ignored.
String[]
Extracted token string from

the input string. Leading and
trailing spaces are deleted if
the delimiter is not a space.
This
OUTPUT
<return value>
EXAMPLE
TmpString = str_token(abc, def, hij, ,, 2)
TmpString -> def
TmpString2 = str_token(*CLASS = MyClass, =, 2)
TmpString2 -> MyClass
01/22/17
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.
String[]
Output string with no

leading spaces.
OUTPUT
<return value>
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.
String[]
Output string with no

trailing spaces.
OUTPUT
<return value>
EXAMPLE
MyString2 = str_strip_trail(
MyString2 ->
a b c
a b c
01/22/17
185/252
Appendix B
str_to_integer(MyString[, status])
DESCRIPTION
Convert a string to an integer.
INPUT
MyString
String[]
Input string.
status
Integer
Optional. Zero for

success or the position
within MyString where
the first invalid
character occurs.
<return value>
Integer
Integer value.
OUTPUT
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.
String[]
String value.
OUTPUT
<return value>
EXAMPLE
MyString = str_from_integer(12)
MyString -> 12
01/22/17
186/252
Appendix B
str_datatype(MyString)
DESCRIPTION
Attempt to decipher the datatype contained in a string.
INPUT
MyString
String
Input string.
String[]
String representing the

datatype, i.e.,
INTEGER, REAL,
LOGICAL, or STRING.
OUTPUT
<return value>
OTHER FUNCTIONS
str_to_real(MyString[, status])
str_from_real(RealValue)
str_to_logical(MyString)
str_from_logical(LogicalValue)
01/22/17
187/252
Appendix C
Noteworthy Functions
01/22/17
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.
Any
Destination variable to receive

the copy of the source variable.
OUTPUT
destination
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:))
01/22/17
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.
Integer
Array index indicating

the position within
IntegerArray where the
Look4 value was found.
Zero if the value was
not found
OUTPUT
<return value>
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
01/22/17
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.
Array
Integer array
Input array in sorted

order.
NumLeft
Integer
Number of items in the

sorted array.
OUTPUT
EXAMPLE
INTEGER a(4) = [5, 1, 9, 8]
INTEGER NumLeft
mth_sort(a, TRUE, NumLeft)
a(1:4) -> 1, 5, 8, 9
NumLeft -> 4
01/22/17
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
array
Matrix of values to sort.

This is both the input and
output array.
Row
Integer
Row Id to sort on.
Ascend
Logical
If TRUE, then sort in

ascending order.
Integer or Real
array
Matrix is sorted in place.
OUTPUT
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.
01/22/17
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).
Lengths(virtual)
Real array
Length of each entity in

PickList.
NumLengths
Integer
Number of entities
contained in PickList.
<return value>
Integer
Zero for success
OUTPUT
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.
01/22/17
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.
01/22/17
194/252
Appendix D
Form Spacing Parameters
(appforms.p)
01/22/17
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
INTER_GROUP_SPACE
- 3/4 of a font height

- Twice the size of a "inter_widget_space"
SINGLE_SPACE
QTR_SPACE
HALF_SPACE
THREE_QTR_SPACE
ONE_AND_HALF_SPACE
DOUBLE_SPACE
FONT_HGT
TEXT_FONT_HGT
SS_FONT_HGT
- Font height in inches

- Text font height in inches
- Spreadsheet font height in inches
LINE_THICKNESS
FRAME_1EDGE
FRAME_2EDGE
SFRAME_1EDGE
SFRAME_2EDGE
SCROLL_FRAME_1EDGE
SCROLL_FRAME_2EDGE
SPREADSHEET_1EDGE
SPREADSHEET_2EDGE
HIGHLITE_1EDGE
HIGHLITE_2EDGE
ICON_HGT
- Height of an icon
LOGO_ICON_WID
LOGO_ICON_HGT
- Width of a logo icon

- Height of a logo icon
BUTTON_ICON_1EDGE
BUTTON_ICON_2EDGE
LABEL_ICON_1EDGE
LABEL_ICON_2EDGE
ITEM_ICON_1EDGE
ITEM_ICON_2EDGE
TOGGLE_ICON_1EDGE
TOGGLE_ICON_2EDGE
A font height in inches

1/4 of a font height
1.5 times a font height
2.0 times a font height
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
Thickness
of
of
of
of
of
of
of
of
of
of
of
of
of
of
of
of
of
of
of
a separator
a frame edge
both frame edges
a select frame edge
both select frame edges
a scroll frame edge
both scroll frame edges
a spreadsheet edge
both spreadsheet edges
a highlight border around widgets
both highlight borders
a
a
a
a
a
a
a
a
button icon border

both button icon borders
label icon border
both label icon borders
item icon border
both item icon borders
toggle icon border
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
01/22/17
196/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
COLOR_MENU_TOGGLE_Y_OFFSET - Y offset for centering a toggle next to

a color menu
COLOR_BOX_WID
COLOR_BOX_HGT
COLOR_BOX_LABEL_Y_OFFSET
- Width of a color box

- Height of a color box
- 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
INCREMENTAL_ICON_HGT
- Width of an incremental button icon

- 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_Y_LOC, "UL",
@
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
FORM_X_LOC_SPL
- Normal form X location (same as FORM_X_LOC)

- Special form X location (width is 1.5
times a normal or small form)
- Medium form (medium width) X location
- Large form (large width) X location
FORM_X_LOC_MED
FORM_X_LOC_LRG
01/22/17
197/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
FORM_X_LOC_SML_NX2_SML
FORM_X_LOC_SPL_NX2_SML
FORM_X_LOC_MED_NX2_SML
FORM_X_LOC_LRG_NX2_SML
- Small form next to a

- Special form next to
- Medium form next to a
- Large form next to a
small form
a small form
small form
small form
FORM_X_LOC_SML_NX2_SPL
FORM_X_LOC_SPL_NX2_SPL
FORM_X_LOC_MED_NX2_SPL
FORM_X_LOC_LRG_NX2_SPL
Small form next to a special form

Special form next to a special form
Medium form next to a special form
Large form next to a special form
FORM_X_LOC_SML_NX2_MED
FORM_X_LOC_SPL_NX2_MED
FORM_X_LOC_MED_NX2_MED
FORM_X_LOC_LRG_NX2_MED
Small form next to a medium form

Special form next to a medium form
Medium form next to a medium form
Large form next to a medium form
FORM_X_LOC_SML_NX2_LRG
FORM_X_LOC_SPL_NX2_LRG
FORM_X_LOC_MED_NX2_LRG
FORM_X_LOC_LRG_NX2_LRG
Small form next to a large from

Special form next to a large form
Medium form next to a large form
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
FORM_X_LOC_SPL_CEN
FORM_X_LOC_MED_CEN
FORM_X_LOC_LRG_CEN
FORM_X_LOC_SML_CEN_AB_COM
- Small form centered above the command

window
- Special form centered above the command
window
- Medium form centered above the command
window
- Large form centered above the command
window
FORM_X_LOC_SPL_CEN_AB_COM
FORM_X_LOC_MED_CEN_AB_COM
FORM_X_LOC_LRG_CEN_AB_COM
FORM_X_LOC_OFFSET_CASCADE_1
Small form centered on screen

Special form centered on screen
Medium form centered on screen
Large form centered on screen
- 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
FORM_Y_LOC_QTR_CEN
- 1/2 Height form centered on screen

01/22/17
198/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
FORM_Y_LOC_3_8THS_CEN
FORM_Y_LOC_5_8THS_CEN
FORM_Y_LOC_3_QTRS_CEN

FORM_Y_LOC_OFFSET_CASCADE_1
Y
Y
Y
Y
Y
offset
offset
offset
offset
offset
for
for
for
for
for
cascade
cascade
cascade
cascade
cascade
position
position
position
position
position
1
2
3
4
5
Form Widths and Heights:

FORM_WID_SML
FORM_WID_SPL
FORM_WID_MED
FORM_WID_LRG
FORM_HGT_TALL
FORM_HGT_FULL
FORM_HGT_HALF
FORM_HGT_QTR
FORM_HGT_3_8THS
FORM_HGT_5_8THS
FORM_HGT_3_QTRS
- Width of a small form

- Width of a "special" form (1.5 times
a small form)
- Width of a medium form (medium size)
- Width of a large form (large size)
- Height of a tall form (Main Menu to
bottom of screen)
- Height of a full form (Main Menu to
top of Command Window)
- Half of a full form
- One Quarter of a full form
- Three Eighths of a full form
- Five Eighths of a full form
- Three Quarters of a full form
Form Margins:
FORM_L_MARGIN
FORM_R_MARGIN
FORM_T_MARGIN
FORM_B_MARGIN
FORM_B_MARGIN_NO_BUTTON
Inside Left Margin for widgets in form

Inside Right Margin for widgets in form
Inside Top Margin above first widget
Inside Bottom Margin below last widget
Inside Bottom Margin below last widget
when last widget is not a button
FORM_2H_MARGIN
FORM_2V_MARGIN
FORM_2V_MARGIN_NO_BUTTON
- Both horizontal margins

- Both vertical margins
- Both vertical margins (when last widget
is not a button)
Form Borders (the colored areas outside the form):

FORM_L_BORDER
FORM_R_BORDER
FORM_T_BORDER
FORM_B_BORDER
FORM_T_BORDER_NO_LABEL
FORM_2H_BORDER
FORM_2V_BORDER
FORM_2V_BORDER_NO_LABEL
- Both horizontal borders

- Both vertical borders (with label)
- Both vertical borders (without label)
FORM_X_ISFRAME
- Compensation for X location of forms
Left Border of the form

Right Border of the form
Top Border of the form (including the label)
Bottom Border of the form
Top Border of the form without a label
01/22/17
199/252
Appendix D
*
*
*
*
*
FORM_Y_ISFRAME
FORM_Y_ISFRAME_NO_LABEL
if they are 'user placed' rather than

appforms placed
- Compensation for Y location
- 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,
AOM_MENU_LABEL_LEN,
OBJECT, FALSE )
@
@
@
@

AOM_MENU_X_LOC,
METHOD_MENU_Y_LOC,
AOM_MENU_LABEL_LEN,
METHOD, FALSE )
@
@
@
@
ui_separator_create ( form_id, "", 0.0,

AOM_SEPARATOR_Y_LOC,
FORM_WID_SML, TRUE )
@
@
AOM Menu Placement:

AOM_MENU_X_LOC
AOM_MENU_LABEL_LEN
ACTION_MENU_Y_LOC
OBJECT_MENU_Y_LOC
METHOD_MENU_Y_LOC
AOM_SEPARATOR_Y_LOC
APP_FORM_FIRST_Y_LOC
X Location of the AOM menus (margin included)

Label length for AOM menus (language dependent)
Y Location for the Action menu (margin included)
Y Location for the Object menu (margin included)
Y Location for the Method menu (margin included)
Y Location for separator under the AOM menus
Y Location for the first widget in an
application form
*************************************************************************
*
*
*
*
FRAMES
Create a frame in an application form.
Assume this is the first

01/22/17
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 +
INTER_WIDGET_SPACE
UNFRAMED_L_MARGIN,
y_loc, 0.0,
DBOX_WID_SINGLE,
"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
01/22/17
201/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
in the above example.

ui_form_create( "", FORM_X_LOC_MED_NX2_SML,
@
FORM_Y_LOC, "UL",
@
FORM_WID_MED,
@
FORM_HGT_FULL, "Label", "Icon" )
FRAME_X_LOC_COL1,
FORM_Y_MARGIN,
FRAME_WID_SINGLE,
height, "Left Label" )
@
@
@
@

FRAME_X_LOC_COL2,
FORM_Y_MARGIN,
FRAME_WID_SINGLE,
height, "Right Label" )
@
@
@
@
Frame Widths and Heights:

FRAME_WID_SINGLE
FRAME_WID_SPECIAL
FRAME_WID_DOUBLE
FRAME_WID_TRIPLE
Width
Width
Width
Width
of
of
of
of
a
a
a
a
single width frame

special width frame
double width frame
triple width frame
FRAME_LABEL_HGT
- Height of the label above a frame
Frame Margins:
FRAME_L_MARGIN
FRAME_R_MARGIN
FRAME_T_MARGIN
FRAME_B_MARGIN
Inside
Inside
Inside
Inside
left margin for widgets in the frame

right margin for widgets in the frame
top margin above first widget
bottom margin below last widget
FRAME_2H_MARGIN
FRAME_2V_MARGIN

Frame Placement:
FRAME_X_LOC_COL1
FRAME_X_LOC_COL2
FRAME_X_LOC_COL3
- X Location for a frame in column 1

(same as "form_l_margin")
Unframed Widget Placement:

UNFRAMED_L_MARGIN
UNFRAMED_R_MARGIN
- Left margin for an unframed widget

- Right margin for an unframed widget
UNFRAMED_X_LOC_COL1 - X Location of an unframed widget in column 1

01/22/17
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 )
@
@
@
@
@
@

SFRAME_L_MARGIN,
SDBOX_Y_LOC2, 0.0,
SDBOX_WID_SINGLE,
"Select Databox One",
prompt )
@
@
@
@
@
@
y_loc = y_loc + SFRAME_LABEL_HGT +

SFRAME_2SDB_HGT_LABOVE +
SFRAME_2EDGE +
INTER_WIDGET_SPACE
@
@
@
Select Frame Widths and Heights:

SFRAME_WID_SINGLE
SFRAME_WID_SPECIAL
SFRAME_WID_DOUBLE
SFRAME_WID_TRIPLE
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
- Height of a select frame with
2 select databoxes with labels
Width
Width
Width
Width
of
of
of
of
a
a
a
a
single width select frame

special width select frame
double width select frame
triple width select frame
01/22/17
203/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
SFRAME_HGT_LABOVE_INCR
- Height of a select
3 select databoxes
4 select databoxes
5 select databoxes
frame with
with labels
frame with
with labels
frame with
with labels
- 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
SFRAME_R_MARGIN
SFRAME_T_MARGIN
SFRAME_B_MARGIN
Inside
Inside
Inside
Inside
left margin for select databoxes

right margin for select databoxes
top margin for select databoxes
bottom margin for select databoxes
SFRAME_2H_MARGIN
SFRAME_2V_MARGIN

Select Frame Placement:

SFRAME_X_LOC_COL1
SFRAME_X_LOC_COL2
SFRAME_X_LOC_COL3
- 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
SCROLL_FRAME_WID_SPECIAL
SCROLL_FRAME_WID_DOUBLE
- Width of a single width scroll frame

- Width of a special width scroll frame
- Width of a double width scroll frame
01/22/17
204/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
SCROLL_FRAME_WID_TRIPLE
- Width of a triple width scroll frame
SCROLL_FRAME_WORK_WID_SINGLE
- Working width
scroll frame
SCROLL_FRAME_WORK_WID_SPECIAL - Working width
scroll frame
SCROLL_FRAME_WORK_WID_DOUBLE - Working width
scroll frame
SCROLL_FRAME_WORK_WID_TRIPLE - Working width
scroll frame
SCROLL_FRAME_DBOX_WID_SINGLE
- Width of
databox
SCROLL_FRAME_DBOX_WID_SPECIAL - Width of
databox
SCROLL_FRAME_DBOX_WID_DOUBLE - Width of
databox
SCROLL_FRAME_DBOX_WID_TRIPLE - Width of
databox
of a single width
of a special width
of a double width
of a triple width
a single width scroll frame

a special width scroll frame
a double width scroll frame
a triple width scroll frame
SCROLL_FRAME_LABEL_HGT
- Height of the label above a

scroll frame
SCROLL_FRAME_1DBOX_HGT
SCROLL_FRAME_DBOX_HGT_INCR
- Scroll frame height increment
SCROLL_FRAME_1DBOX_WORK_HGT
Scroll
Scroll
Scroll
Scroll
Scroll
frame
frame
frame
frame
frame
height
height
height
height
height
with
with
with
with
with
1
2
3
4
5
databox
databoxes
databoxes
databoxes
databoxes
- Scroll frame work height for 1 databox

- Scroll frame work height for 2 databoxes
SCROLL_FRAME_DBOX_WORK_HGT_INCR - Scroll frame working height increment

SCROLL_FRAME_SLIDER_WID
SCROLL_FRAME_SLIDER_HGT
- Width of the slider on the right

of a scroll frame
- Height of the slider at the bottom
of a scroll frame
Frame Margins:
SCROLL_FRAME_L_MARGIN
SCROLL_FRAME_T_MARGIN
SCROLL_FRAME_B_MARGIN
- Inside left margin for widgets in

a scroll frame
- Inside right margin for widgets in
a scroll frame
- Inside top margin above first widget
- Inside bottom margin below last widget
SCROLL_FRAME_2H_MARGIN
SCROLL_FRAME_2V_MARGIN

SCROLL_FRAME_R_MARGIN
01/22/17
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 +
INTER_WIDGET_SPACE
@
@
Button Widths and Heights:

BUTTON_WID_FULL
BUTTON_WID_HALF
BUTTON_WID_THIRD
- Width of a wide button on a small form

- Width of a medium button on a small form
- Width of a small button on a small form
BUTTON_WID_FULL_NT
- Width of a non_troughed wide button on

a small form
- Width of a non_troughed medium button on
a small form
- Width of a non_troughed small button on
a small form
BUTTON_WID_HALF_NT
BUTTON_WID_THIRD_NT
BUTTON_HGT
BUTTON_DEFAULT_HGT
BUTTON_HGT_NT
- Button height
- Default button height (includes top and
bottom borders)
- Button height of non_troughed button
BUTTON_DEFAULT_BORDER_WID
BUTTON_DEFAULT_BORDER_HGT
- Default button border width

- 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
01/22/17
206/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
BUTTON_1XTRA_WID
BUTTON_2XTRA_WID
BUTTON_Y_OFFSET
BUTTON_Y_OFFSET_NT
- X width for
of troughed
- X width for
of troughed
one trough for user placement

buttons.
two troughs for user placement
buttons.
- Y offset for placing a non-highlighted

button next to a highlighted button
- 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
of a non_troughed button
Button X Positions:
BUTTON_FULL_X_LOC1
BUTTON_HALF_X_LOC1
BUTTON_HALF_X_LOC2
BUTTON_THIRD_X_LOC1
BUTTON_THIRD_X_LOC2
BUTTON_THIRD_X_LOC3
Wide button on the left

Medium button on the left
Medium button on the right
Small button on the left
Small button centered
Small button on the right
BUTTON_FULL_X_LOC1_COL2
BUTTON_HALF_X_LOC1_COL2
BUTTON_THIRD_X_LOC1_COL2
Wide button on the left of column 2

Medium button on the left of column 2
Medium button on the right of column 2
Small button on the left of column 2
Small button centered of column 2
Small button on the right of column 2
BUTTON_FULL_X_LOC1_COL3
Wide button on the left of column 3

Medium button on the left of column 3
Medium button on the right of column 3
Small button on the left of column 3
Small button centered of column 3
Small button on the right of column 3
BUTTON_FULL_X_LOC1_SPL
BUTTON_HALF_X_LOC1_SPL
BUTTON_HALF_X_LOC2_SPL
BUTTON_THIRD_X_LOC1_SPL
Wide button centered on a special form

Medium button on the left of a special form
Medium button on the right of a special form
Small button on the left of a special form
Small button centered of a special form
Small button on the right of a special form
BUTTON_FULL_X_LOC_CEN
BUTTON_HALF_X_LOC_CEN
BUTTON_THIRD_X_LOC_CEN
- Centered wide button on a small form

- Centered medium button on a small form
- Centered small button on a small form
BUTTON_FULL_X_LOC_CEN_MED
BUTTON_HALF_X_LOC_CEN_MED
BUTTON_THIRD_X_LOC_CEN_MED
- Centered wide button on a medium form

- Centered medium button on a medium form
- Centered small button on a medium form
BUTTON_FULL_X_LOC_CEN_LRG
BUTTON_HALF_X_LOC_CEN_LRG
- Centered wide button on a large form

- Centered medium button on a large form
01/22/17
207/252
Appendix D
*
*
*
*
*
*
BUTTON_THIRD_X_LOC_CEN_LRG
- Centered small button on a large form
BUTTON_FULL_X_LOC_CEN_SPL
BUTTON_HALF_X_LOC_CEN_SPL
BUTTON_THIRD_X_LOC_CEN_SPL
- Centered wide button on a special form

- Centered medium button on a special form
- 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,
DBOX_WID_SINGLE,
@
@
@
@
@
y_frame_loc = y_frame_loc +
DBOX_HGT_LABOVE +
INTER_WIDGET_SPACE
@
@
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
DBOX_WID_SPECIAL
DBOX_WID_DOUBLE
DBOX_WID_TRIPLE
DBOX_HGT_LABOVE
- Height of a databox with a label on the top

(even if the label is blank)
Width
Width
Width
Width
of
of
of
of
a
a
a
a
single width databox

special width databox
double width databox
triple width databox
01/22/17
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

(used when "label_above"
DBOX_LABEL_LEN_SPECIAL - Default label length for
DBOX_LABEL_LEN_DOUBLE - Default label length for
DBOX_LABEL_LEN_TRIPLE - Default label length for
DBOX_LABEL_X_OFFSET
DBOX_LABEL_Y_OFFSET
a single width databox

is false)
a special width databox
a double width databox
a triple width databox
- REMOVED
- 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
01/22/17
209/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
FILE_WID_SPECIAL
FILE_WID_DOUBLE
FILE_WID_TRIPLE
- Width of a special width file widget

- Width of a double width file widget
- Width of a triple width file widget
File Height:
FILE_1L_HGT
FILE_2L_HGT
FILE_3L_HGT
FILE_4L_HGT
FILE_5L_HGT
FILE_6L_HGT
FILE_7L_HGT
FILE_8L_HGT
FILE_9L_HGT
FILE_HGT_INCR
Height of
Height of
Height of
Height of
Height of
Height of
Height of
Height of
Height of
Increment
a 1
a 2
a 3
a 4
a 5
a 6
a 7
a 8
a 9
for
line file widget

line file widget
line file widget
line file widget
line file widget
line file widget
line file widget
line file widget
line file widget
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 +
INTER_WIDGET_SPACE
@
@
Label Height:
LABEL_HGT
LABEL_Y_OFFSET
LABEL_HGT_TIGHT
- Height of a label
- Y offset of label
- Height of a label when showing multiple
labels
INFO_INDENT
INFO_INDENT_COL1
INFO_INDENT_COL2
INFO_INDENT_COL3
X
X
X
X
location
location
location
location
of
of
of
of
information
information
information
information
label
label in column 1
label in column 2
label in column 3
*************************************************************************
*
*
*
LISTBOXES
01/22/17
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 )
@
@
@
@
@
INTER_WIDGET_SPACE
@
@
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
LBOX_WID_SPECIAL
LBOX_WID_DOUBLE
LBOX_WID_TRIPLE
Width
Width
Width
Width
LBOX_1L_HGT_LABOVE
LBOX_2L_HGT_LABOVE
LBOX_3L_HGT_LABOVE
LBOX_4L_HGT_LABOVE
LBOX_5L_HGT_LABOVE
LBOX_8L_HGT_LABOVE
Height
Height
Height
Height
Height
Height
LBOX_HGT_LABOVE_INCR
- Increment for computing a listbox height that

has more than 5 lines in it
LBOX_1L_HGT_NO_LABOVE
- Height
(label
- Height
- Height
- Height
- Height
- Height
of
of
of
of
of
of
of
of
of
of
a
a
a
a
of
is
of
of
of
of
of
single width listbox

special width listbox
double width listbox
triple width listbox
a
a
a
a
a
a
1
2
3
4
5
8
line
line
line
line
line
line
a 1 line
blank)
a 2 line
a 3 line
a 4 line
a 5 line
a 8 line
listbox
listbox
listbox
listbox
listbox
listbox
with
with
with
with
with
with
a
a
a
a
a
a
top
top
top
top
top
top
label
label
label
label
label
label
listbox with no label

listbox
listbox
listbox
listbox
listbox
with
with
with
with
with
no
no
no
no
no
label
label
label
label
label
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
01/22/17
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 +

INTER_WIDGET_SPACE
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
on the
- Height
on the
OPT_MENU_HGT_NO_LABOVE
OPT_MENU_Y_OFFSET
of an option menu with a label

top
of an option menu with a label
side
- 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
SFRAME_L_MARGIN,
y_sframe_loc, 0.0,
SDBOX_WID_SINGLE,
"Select Databox Label",
prompt )
@
@
@
@
@
@
y_sframe_loc = y_sframe_loc +
SDBOX_HGT_LABOVE +
INTER_WIDGET_SPACE
@
@
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.
01/22/17
212/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
y_sframe_loc = SFRAME_T_MARGIN
wid = SDBOX_WID_SINGLE SDBOX_LABEL_LEN_SINGLE

SFRAME_L_MARGIN,
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 +
INTER_WIDGET_SPACE
@
@
Select Databox Width and Height:

SDBOX_WID_SINGLE
SDBOX_WID_SPECIAL
SDBOX_WID_DOUBLE
SDBOX_WID_TRIPLE
SDBOX_HGT_LABOVE
SDBOX_HGT_NO_LABOVE
- Height of a select databox with a top label

- Height of a select databox with a side label
SDBOX_Y_LOC1_LABOVE
- Y location of select databox 1 in a

(select databox has a label above)
SDBOX_Y_LOC2_LABOVE
SDBOX_Y_LOC3_LABOVE
SDBOX_Y_LOC4_LABOVE
SDBOX_Y_LOC5_LABOVE
SDBOX_Y_LABOVE_INCR
Width
Width
Width
Width
of
of
of
of
a
a
a
a
single width select databox

special width select databox
double width select databox
triple width select databox
selectframe
selectframe
selectframe
selectframe
selectframe
- 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

(select databox does
databox 1 in a selectframe
not have a label above)
SDBOX_Y_NO_LABOVE_INCR - Increment for creating the Y location for than
01/22/17
213/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
than 5 select databoxes without labels in a

select frame
SDBOX_LABEL_LEN_SINGLE - Default
databox
SDBOX_LABEL_LEN_SPECIAL- Default
databox
SDBOX_LABEL_LEN_DOUBLE - Default
databox
SDBOX_LABEL_LEN_TRIPLE - Default
databox
SDBOX_LABEL_X_OFFSET
SDBOX_LABEL_Y_OFFSET
label length for a single width select

(used when "label_above" is false)
label length for a special width select
label length for a double width select
label length for a triple width select
- REMOVED
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 +
INTER_WIDGET_SPACE
@
@
Sliderbar Width and Height:

SLIDER_WID_SINGLE
SLIDER_WID_SPECIAL
SLIDER_WID_DOUBLE
SLIDER_WID_TRIPLE
SLIDER_HGT_COMPLETE
- Height of slidebar with min/max labels,

the values shown and a label below the
slidebar
- Height of slidebar with min/max labels only
- Height of slidebar with values only
- Height of slidebar with label only (values
not shown and no min/max labels)
- Height of slidebar with min/max labels and
values shown (no label)
SLIDER_HGT_MINMAX
SLIDER_HGT_VALUES
SLIDER_HGT_LABEL
SLIDER_HGT_MINMAX_VALUES
Width
Width
Width
Width
of
of
of
of
a
a
a
a
single width slidebar

special width slidebar
double width slidebar
triple width slidebar
01/22/17
214/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
SLIDER_HGT_MINMAX_LABEL
- Height of slidebar with min/max labels and

a label below slidebar (values not shown)
- Height of slidebar with values shown and
a label below the slidebar (no min/max
labels)
- Height of just the slidebar
SLIDER_HGT_VALUES_LABEL
SLIDER_HGT_BAR_ONLY
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
the slidebar has only min/max labels
SLIDER_LABEL_Y_LOC_VALUES
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
SPREADSHEET_WID_SPECIAL
SPREADSHEET_WID_DOUBLE
SPREADSHEET_WID_TRIPLE
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
SPREADSHEET_HGT_2D_INCR
Height
Height
Height
Height
Height
Height
Height
Height
Height
Height
Height
of a 2D spreadsheet with 1 row

of a 2D spreadsheet with 2 rows
increment for 2D spreadsheet
Height
Height
Height
Height
Height
Height
Height
of
of
of
of
of
of
of
Width
Width
Width
Width
of
of
of
of
a
a
a
a
single width select frame

special width select frame
double width select frame
triple width select frame
a
a
a
a
a
a
a
3D
3D
3D
3D
3D
3D
3D
spreadsheet
spreadsheet
spreadsheet
spreadsheet
spreadsheet
spreadsheet
spreadsheet
with
with
with
with
with
with
with
1
2
3
4
5
6
7
row
rows
rows
rows
rows
rows
rows
01/22/17
215/252
Appendix D
*
*
*
*
*
SPREADSHEET_HGT_3D_INCR
Height
Height
Height
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 +
INTER_WIDGET_SPACE
@
@
Switch Height:
SWITCH_1R_HGT_LABEL
SWITCH_2R_HGT_LABEL
SWITCH_3R_HGT_LABEL
SWITCH_4R_HGT_LABEL
Height
Height
Height
Height
SWITCH_HGT_LABEL_INCR
- Increment for creating a switch height with

more than 4 rows in it
SWITCH_1R_HGT_NO_LABEL
Height
Height
Height
Height
of
of
of
of
of
of
of
of
a
a
a
a
a
a
a
a
1
2
3
4
1
2
3
4
row
row
row
row
row
row
row
row
switch
switch
switch
switch
switch
switch
switch
switch
with
with
with
with
with
with
with
with
a
a
a
a
no
no
no
no
label
label
label
label
label
label
label
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.
01/22/17
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 +
INTER_WIDGET_SPACE
@
@
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
TBOX_WID_SPECIAL
TBOX_WID_DOUBLE
TBOX_WID_TRIPLE
Width
Width
Width
Width
TBOX_1L_HGT_LABOVE
TBOX_2L_HGT_LABOVE
TBOX_3L_HGT_LABOVE
TBOX_4L_HGT_LABOVE
TBOX_5L_HGT_LABOVE
Height
Height
Height
Height
Height
TBOX_HGT_LABOVE_INCR
- Increment for computing a textbox height that

TBOX_1L_HGT_NO_LABOVE
- Height
(label
- Height
- Height
- Height
- Height
of
of
of
of
of
of
of
of
of
a
a
a
a
of
is
of
of
of
of
single width textbox

special width textbox
double width textbox
triple width textbox
a
a
a
a
a
1
2
3
4
5
line
line
line
line
line
a 1 line
blank)
a 2 line
a 3 line
a 4 line
a 5 line
textbox
textbox
textbox
textbox
textbox
with
with
with
with
with
a
a
a
a
a
top
top
top
top
top
label
label
label
label
label
textbox with no label

textbox
textbox
textbox
textbox
with
with
with
with
no
no
no
no
label
label
label
label
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,
@
@
01/22/17
217/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
y_frame_loc,
"Toggle Label" )
TOGGLE_HGT +
INTER_WIDGET_SPACE
@
@
@
Toggle Height:
TOGGLE_HGT
TOGGLE_Y_OFFSET
- Height of a toggle
- Y offset for placing a label to the side
of a toggle
*************************************************************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
LANGUAGE
Language variables:
ENGLISH
GERMAN
SPANISH
FRENCH
KANJI
"English"
"German"
"Spanish"
"French"
"Kanji"
LANGUAGE
HANDEDNESS
- Current language (see above)

- Determines whether forms appear on right of left side
of screen
*************************************************************************
*
*
*
*
*
*
*
*
*
*
*
SCREEN
Screen variables:
PIXEL_WID
PIXEL_HGT
- Width of a pixel (in inches)

- Height of a pixel (in inches)
SCREEN_WID
SCREEN_HGT
- Width of logical screen (in inches)

- Height of logical screen (in inches)
*************************************************************************
*
*
*
*
*
*
BASIC LAYOUT
Basic layout variables:
MAIN_MENU_X_LOC
- Main menu X location

01/22/17
218/252
Appendix D
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
MAIN_MENU_Y_LOC
MAIN_MENU_WID
MAIN_MENU_HGT
MAIN_MENU_L_EDGE
MAIN_MENU_R_EDGE
MAIN_MENU_T_EDGE
MAIN_MENU_B_EDGE
MAIN_MENU_SWITCH_Y_LOC
MAIN_MENU_ICON_Y_LOC
MAIN_MENU_ICON_HGT
MAIN_MENU_ICON_WID
MAIN_MENU_LOGO_ICON_WID
MAIN_MENU_HEART_ICON_WID
MAIN_MENU_HEART_ICON_HGT
MAIN_MENU_MARGIN
MAIN_MENU_ICON_MARGIN
MAIN_MENU_HEART_MARGIN
MAIN_MENU_HEART_X_LOC
MAIN_MENU_HEART_Y_LOC
Main menu Y location

Main menu width
Main menu height
Left edge of main menu (incl border)
Right edge of main menu (incl border)
Top edge of main menu (incl border)
Bottom edge of main menu (incl border)
Switch Y location
Icon Y location
Main Menu Icon Height
Main Menu Icon Width
Main Menu Logo Icon Width
Main Menu Heartbeat Icon Width
Main Menu Heartbeat Icon Height
Main menu switch margin
Main menu margin between icons
Main menu margin between last icon and
heartbeat icon
- Heartbeat icon X location
- Heartbeat icon Y location
COMMAND_WINDOW_X_LOC
COMMAND_WINDOW_Y_LOC
COMMAND_WINDOW_WID
COMMAND_WINDOW_HGT
COMMAND_WINDOW_NUM_ROWS
COMMAND_WINDOW_L_EDGE
COMMAND_WINDOW_R_EDGE
COMMAND_WINDOW_T_EDGE
COMMAND_WINDOW_B_EDGE
Command window X location

Command window Y location
Command window width
Command window height
Number of history rows in the command window
Left edge of command window (incl border)
Right edge of command window (incl border)
Top edge of command window (incl border)
Bottom edge of command window (incl border)
GRAPHICS_WINDOW_X_LOC
GRAPHICS_WINDOW_Y_LOC
GRAPHICS_WINDOW_WID
GRAPHICS_WINDOW_HGT
GRAPHICS_WINDOW_L_EDGE
GRAPHICS_WINDOW_R_EDGE
GRAPHICS_WINDOW_T_EDGE
GRAPHICS_WINDOW_B_EDGE
Graphics window X location

Graphics window Y location
Graphics window width
Graphics window height
Left edge of graphics window (incl border)
Right edge of graphics window (incl border)
Top edge of graphics window (incl border)
Bottom edge of graphics window (incl border)
SHOW_SPREADSHEET_NUM_ROWS - Number of rows in the show spreadsheet widget

GRAPHICS_WINDOW_WID_QTR
GRAPHICS_WINDOW_HGT_QTR
- Quarter width graphics window

- Quarter width graphics window
GRAPHICS_WINDOW_X_LOC_UL
GRAPHICS_WINDOW_Y_LOC_UL
GRAPHICS_WINDOW_X_LOC_UR
GRAPHICS_WINDOW_Y_LOC_UR
GRAPHICS_WINDOW_X_LOC_LL
GRAPHICS_WINDOW_Y_LOC_LL
GRAPHICS_WINDOW_X_LOC_LR
GRAPHICS_WINDOW_Y_LOC_LR
GRAPHICS_CEN_X_LOC
GRAPHICS_CEN_Y_LOC
- Center of graphics area X location

- Center of graphics area Y location
WINDOW_CEN_X_LOC
- Center of area beneath main menu X location
Quarter
Quarter
Quarter
Quarter
Quarter
Quarter
Quarter
Quarter
size
size
size
size
size
size
size
size
graphics
graphics
graphics
graphics
graphics
graphics
graphics
graphics
window
window
window
window
window
window
window
window
upper
upper
upper
upper
lower
lower
lower
lower
left X loc
left Y loc
right X loc
right Y loc
left X loc
left Y loc
right X loc
right Y loc
01/22/17
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
01/22/17
220/252
Appendix E
MSC.Patran Architecture
01/22/17
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
01/22/17
222/252
Appendix F
Shareware Compiling Functions
01/22/17
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)
01/22/17
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()
01/22/17
225/252
Appendix G
Parametric Patran
01/22/17
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
01/22/17
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
01/22/17
228/252
Appendix G
Output definition
An analysis response or result
01/22/17
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
01/22/17
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
three = 1, 2, 3
! this
data = 37.655
! this
moredata = 1.0, 2.0, 3.0, 4.0 ! this
name = mat1
! this
names = one, two, three
! this
is
is
is
is
is
is
an integer
a 3 word integer array
a real
a 4 word real array
a string variable, note no quotes
a string array, again no quotes
01/22/17
231/252
Appendix H
Additional List Processor Notes
01/22/17
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.
01/22/17
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
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
LP_EVAL_BARE_PARSE
LP_EVAL_PARSE_AND_EXPAND
LP_EVAL_FOR_TOKENS
LP_EVAL_FOR_ID
For retrieving label / ID info
LP_EVAL_FOR_LABEL
LP_EVAL_FOR_GEOMETRY
For retrieving atttribute info
LP_EVAL_FOR_FEM_DEFINITION
LP_EVAL_FOR_PICKLIST_ENUMERATION
LP_EVAL_FOR_PICKLIST_NORMALIZATION
LP_EVAL_FOR_PICKLIST_ADD
LP_EVAL_FOR_PICKLIST_DELETE
01/22/17
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
lp_sublist_type()
lp_sublist_count()
Use
To get the current sublist type being
referenced.
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
#define
#define
#define
#define
#define
LP_SUBLIST_POINT_IMMEDIATE
LP_SUBLIST_VECTOR_IMMEDIATE
LP_SUBLIST_POINT
LP_SUBLIST_CURVE
LP_SUBLIST_SURFACE
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
#define
#define
#define
#define
#define
LP_SUBLIST_COORD_FRAME
LP_SUBLIST_VECTOR
LP_SUBLIST_AXIS
LP_SUBLIST_NODE
LP_SUBLIST_ELEMENT
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()
01/22/17
235/252
Appendix H
List Processor Attribute Functions
lp_sublist_attribute_ functions evaluate the Picklist based on a

sublist attribute filter.
lp attribute Functions
lp_sublist_attribute_get_int()
Use
Return an integer value from a
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
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
LP_ATTRIBUTE_ID
#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS
LP_ATTRIBUTE_LABEL
#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS_ID
LP_ATTRIBUTE_GEOMETRY
#define LP_ATTRIBUTE_GEOMETRY_IN_NATIVE_FORM
LP_ATTRIBUTE_GEOMETRY_TYPE
#define LP_ATTRIBUTE_U_VALUE
LP_ATTRIBUTE_GEOMETRY_FORMAT
#define LP_ATTRIBUTE_V_VALUE
LP_ATTRIBUTE_GEOMETRY_COMPANY_OF_ORIGIN
#define LP_ATTRIBUTE_TOKEN_VALUE
LP_ATTRIBUTE_ORIGIN
#define LP_ATTRIBUTE_EVALUATED_POINT
LP_ATTRIBUTE_ROTATION_MATRIX
#define LP_ATTRIBUTE_POINT_COUNT
LP_ATTRIBUTE_COORDINATE_FRAME_TYPE
#define LP_ATTRIBUTE_CURVE_COUNT
LP_ATTRIBUTE_LOCATION
#define LP_ATTRIBUTE_SURFACE_COUNT
LP_ATTRIBUTE_DISPLACEMENT
#define LP_ATTRIBUTE_SOLID_COUNT
LP_ATTRIBUTE_BASE
#define LP_ATTRIBUTE_POINT_LIST
LP_ATTRIBUTE_TIP
#define LP_ATTRIBUTE_CURVE_LIST
LP_ATTRIBUTE_CLASS_NAME
#define LP_ATTRIBUTE_SURFACE_LIST
LP_ATTRIBUTE_TOPOLOGY_ID
#define LP_ATTRIBUTE_SOLID_LIST
LP_ATTRIBUTE_DIMENSIONALITY
#define LP_ATTRIBUTE_SIDE_NUMBER
LP_ATTRIBUTE_FACE_NUMBER
#define LP_ATTRIBUTE_NORMAL
LP_ATTRIBUTE_EDGE_NUMBER
#define LP_ATTRIBUTE_PLANE_COUNT
LP_ATTRIBUTE_VERTEX_NUMBER
#define LP_ATTRIBUTE_PLANE_LIST
LP_ATTRIBUTE_NODE_COUNT
#define LP_ATTRIBUTE_VECTOR_COUNT
LP_ATTRIBUTE_NODE_LIST
#define LP_ATTRIBUTE_VECTOR_LIST
LP_ATTRIBUTE_ORIGINAL_PARSE_CLASS
LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS_TOPOLOGICAL_CONTEXT
01/22/17
236/252
Appendix H
Miscellaneous List Processor Functions
Other List Processor functions.

Functions
lp_print_list()
lp_print_sublist()
lp_eval_cleanup()
lp_sublist_reset()
fem_u_count_id_list()
fem_u_extract_node_ids()
fem_u_get_id_list()
app_count_id_list()
Use
Print the entire Picklist from the
anchor block to standard out.
Prints to stdout.
Print the sublist prepared by
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
processor operations. This should
be performed after lp_ operations
are complete
Reset the sublist parser to resume
parsing the original Picklist.
Quick function to count the
entities of a specified list
processor sublist type without
having to use all the other lp_
commands.
Quick function to extract the array
of nodes IDs from a Picklist.
Quick function to
entities ids of a
processor sublist
having to use all
commands.
return the
specified list
type without
the other lp_
Count the entities of a specified

list processor type in a list using
the picklist decoder routines.
01/22/17
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
Label 2
Id 2
GeometryInNativeForm [0. 0. 0. 0. 1. 0.]
GeometryType CartesianPoint
GeometryCompanyOfOrigin PATRAN
EvaluatedPoint [0.0 1.0 0.0]
Sublist Eval: LP_EVAL_FOR_GEOMETRY

LP_ATTRIBUTE_LABEL
LP_ATTRIBUTE_ID
LP_ATTRIBUTE_GEOMETRY_IN_NATIVE_FORM
LP_ATTRIBUTE_GEOMETRY_TYPE
LP_ATTRIBUTE_GEOMETRY_COMPANY_OF_ORIGIN
LP_ATTRIBUTE_EVALUATED_POINT
Element
Id 50
ClassName Bar2
TopologyId 2
Dimensionality 1
NodeCount 2
NodeList [58 57]
Sublist Eval: LP_EVAL_FOR_FEM_DEFINITION

LP_ATTRIBUTE_LABEL
LP_ATTRIBUTE_CLASS_NAME
LP_ATTRIBUTE_TOPOLOGY_ID
LP_ATTRIBUTE_DIMENSIONALITY
LP_ATTRIBUTE_NODE_COUNT
LP_ATTRIBUTE_NODE_LIST
Node
Id 12
Location [0.428571 0.142857 0.000000]
Sublist Eval: LP_EVAL_FOR_FEM_DEFINITION

LP_ATTRIBUTE_LABEL
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.
01/22/17
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
INTEGER
INTEGER
INTEGER
INTEGER
LOGICAL
REAL
STRING
sdbox_id
num_nodes, node_labels()
i, status
list_type, handle, id(1), ints(2)
node_ids(VIRTUAL)
end_of_list = FALSE
reals(2)
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
01/22/17
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
01/22/17
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
1
Point 55 56 Node 34
2
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
01/22/17
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
01/22/17
242/252
Appendix H
01/22/17
243/252
Appendix I
Key Mapping
01/22/17
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()
01/22/17
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)
01/22/17
246/252
Appendix J
Widget Classification
01/22/17
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
01/22/17
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
01/22/17
249/252
Appendix J
01/22/17
250/252
Appendix K
User Defined AOM
01/22/17
251/252
Appendix K
01/22/17
252/252

5626 PCLWorkshopNotes.11!18!04

Uploaded by

Document Information

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

5626 PCLWorkshopNotes.11!18!04

Uploaded by

Copyright:

Available Formats

MSC.

Patran PCL Handbook

x_loc, y_loc, form_width, form_height

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

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

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

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

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

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

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

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

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

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

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

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

Callback Arguments (Widget Function Data).....................................................................................................................82

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

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

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

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

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

MSC.Patran PCL Workshop Notes

PCL stands for Patran Command Language

Comprehensive, fully functional computer programming

Specifically and uniquely suited for MCAE applications

Delivered as a part of MSC.Patran

Versatile and easy to use

MSC.Patran PCL Workshop Notes

What can PCL be used for?

Integrate application or site-specific programs with the

Generate parametric/variational models for design/optimization

Integrate commercial and/or in-house analysis codes with

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

MSC.Patran PCL Workshop Notes

How does PCL work?

All MSC.Patran commands are first interpreted by the PCL

PCL expressions are interpreted by a C program

PCL functions can be compiled into libraries (more efficient

Built-in PCL functions are written in C or FORTRAN

MSC.Patran forms and menus can be created via PCL calls to

FORTRAN and C functions can be linked with MSC.Patran

MSC.Patran PCL Workshop Notes

All you really need to know is on this page!

PCL and Customization - General programming guide for PCL.

PCL Reference Description of functions written to the

Develop: The MSC.Patran Toolkit Documentation of

PCL & Customization, chapters 2 Math functions, string

Graphical user interface

PCL & Customization, chapter 5

Functions for creating forms

PCL & Customization, chapter

Functions for parsing a string

Applications, session file,

PCL Reference Guide

All functions written to the

PCL & Customization, chapter

Functions for drawing graphic

PCL & Customization, chapter 8

Functions to access data in

PCL & Customization, chapters 6 Functions for creating analysis