patran 2010 pcl and customization

918
Patran 2010 PCL and Customization

Upload: don

Post on 18-Nov-2014

141 views

Category:

Documents


7 download

DESCRIPTION

This manual describes how to use PCL to customize Patran by adding new functionalities.

TRANSCRIPT

Patran 2010

PCL and Customization

Worldwide Webwww.mscsoftware.com

DisclaimerThis documentation, as well as the software described in it, is furnished under license and may be used only in accordance with the terms of such license.

MSC.Software Corporation reserves the right to make changes in specifications and other information contained in this document without prior notice.

The concepts, methods, and examples presented in this text are for illustrative and educational purposes only, and are not intended to be exhaustive or to apply to any particular engineering problem or design. MSC.Software Corporation assumes no liability or responsibility to any person or company for direct or indirect damages resulting from the use of any information contained herein.

User Documentation: Copyright 2010 MSC.Software Corporation. Printed in U.S.A. All Rights Reserved.

This notice shall be marked on any reproduction of this documentation, in whole or in part. Any reproduction or distribution of this document, in whole or in part, without the prior written consent of MSC.Software Corporation is prohibited.

The software described herein may contain certain third-party software that is protected by copyright and licensed from MSC.Software suppliers. Contains IBM XL Fortran for AIX V8.1, Runtime Modules, (c) Copyright IBM Corporation 1990-2002, All Rights Reserved.

MSC, MSC/, MSC Nastran, MD Nastran, MSC Fatigue, Marc, Patran, Dytran, and Laminate Modeler are trademarks or registered trademarks of MSC.Software Corporation in the United States and/or other countries.

NASTRAN is a registered trademark of NASA. PAM-CRASH is a trademark or registered trademark of ESI Group. SAMCEF is a trademark or registered trademark of Samtech SA. LS-DYNA is a trademark or registered trademark of Livermore Software Technology Corporation. ANSYS is a registered trademark of SAS IP, Inc., a wholly owned subsidiary of ANSYS Inc. ACIS is a registered trademark of Spatial Technology, Inc. ABAQUS, and CATIA are registered trademark of Dassault Systemes, SA. EUCLID is a registered trademark of Matra Datavision Corporation. FLEXlm is a registered trademark of Macrovision Corporation. HPGL is a trademark of Hewlett Packard. PostScript is a registered trademark of Adobe Systems, Inc. PTC, CADDS and Pro/ENGINEER are trademarks or registered trademarks of Parametric Technology Corporation or its subsidiaries in the United States and/or other countries. Unigraphics, Parasolid and I-DEAS are registered trademarks of UGS Corp. a Siemens Group Company. All other brand names, product names or trademarks belong to their respective owners.

P3:V2010:Z:CUS:Z: DC-USR-PDF

Corporate Europe Asia Pacific

MSC.Software Corporation2 MacArthur PlaceSanta Ana, CA 92707 USATelephone: (800) 345-2078Fax: (714) 784-4056

MSC.Software GmbHAm Moosfeld 1381829 Munich, GermanyTelephone: (49) (89) 43 19 87 0Fax: (49) (89) 43 61 71 6

MSC.Software Japan Ltd.Shinjuku First West 8F23-7 Nishi Shinjuku1-Chome, Shinjuku-Ku Tokyo 160-0023, JAPANTelephone: (81) (3)-6911-1200Fax: (81) (3)-6911-1201

C o n t e n t sPCL and Customization

PCL and Custotion,

1 Introduction to Customization

Understanding PCL 2

Steps to Adding a New Functionality to Patran 3

2 The PATRAN Command Language (PCL) Introduction

Introduction 6

Basic Concepts 7Patran and PCL 7PCL Commands 7PCL Comments 7PCL Embedded in NOODL Commands and Databoxes 8Identifiers 8Directives 9

PCL Variables and Constants 10Data Types 10Scope 12Arrays 13Variable Initialization 17Argument Declaration 18

PCL Operators and Expressions 19Hierarchy of Operators 19

Control Statements 21Branching 21Break and Continue 21Simple If Then 21If Then Else 21Switch and Case 22Looping 23For 23While 23Repeat 24

PCL and Customization

4

List 24

PCL Functions 25Structure of a PCL Class 25Structure of a PCL Function 26Accessing PCL Functions 28Libraries 28Path Directive 29

The C Preprocessor 31

Finding Programming Errors with PCL 33Trace Directive 33Debug Directive 33

Initializing the Session 35PCL Start-Up File 35Session Files Support in PCL 35

3 Basic Functions

Intrinsic Functions 44Math Functions 44String Functions 59Block I/O Functions 78File Utility Functions 81Record I/O Utility Functions 97Stream I/O File Utility Functions 110String I/O Conversion Utility Functions 120Text File I/O Utility Functions 126Virtual I/O Scratch File Utility Functions 136Console I/O Functions 144Message System Functions 155Event Manager 161Session File Functions 163Obsolete File I/O Functions 169

Graphics Functions 175Graphics Manager 175Retained Graphics 175

4 System and Utility Functions

Spawning a Process 186

5CONTENTS

Database Locking 187

System Functions 188

5 User Interface and List Processor Functions

Introduction 220

General Form Style 225General Forms 225General Widgets 229Box Widgets 239Switch 244

Creating Forms and Widgets Using PCL 246

widget Function Descriptions 256

List Processor 258File lpenums.i 259Example: Creating a Simple Customized Menu and Form 293

User Interface Functions 297

6 Creating New Analysis Forms Using PCL

Introduction 422

Updating Patran Release 1.1 Analysis Forms 423

Naming Convention 424

The Analysis PCL Library 425

Contents of the Analysis Library 426

The Main Analysis Form 427

Main Analysis Form Functions 429Changing the Appearance 429<analysis_code>_load_aom_data 432Subordinate Analysis Forms and Functions 437The <apply_class> Class 438Fetching Data From “analysis_main” 440

PCL and Customization

6

7 Modifying the Database Using PCL

Introduction 446

Querying the Patran Database 447

Loading Definitions for MSC Supported Preferences 451

Loading Definitions for User Defined Preferences 452

Loading Basic Definitions 453

Adding A New Analysis Preference 454Custom Data and Application Region Sub-Forms 459

Adding New Element Types/Properties 468

Adding the New Material Properties 517

Adding New Loads and Boundary Conditions 540

Adding Custom General Field Functions 567Adding Functions to the Database 568Evaluator PCL 570An Example Case 574

Adding New Multi-Point Constraint Definitions 577

Adding Element Verification Parameters 582

Examples of Modifying the Database 586

8 Accessing the Patran Database

Introduction 591

Syntax of Documented Calls 592

Calling the Database Access Functions from C and FORTRAN 593

External Access of the Patran Database 595

Miscellaneous Database Functions 596

Groups 600

Nodes 602Exporting Node Data 602Importing Node Data 607

7CONTENTS

Coordinate Frames 609Exporting Coordinate Frame Data 609Importing Coordinate Frame Data 609

Patran Element Topology Codes 613

Elements 615Exporting Element Data 615Importing Element Data 622

Element Properties 625Exporting Element Property Data 625Importing Element Property Data 635

Association between Elements and Element Properties 640Extracting Association between Elements and Element Properties 640

Data Fields 643Importation of Data Fields 653

Material Properties 672Exportation of Material Data 672Importation of Material Data 683Exportation of Composite Material Creation Data 687

Load Cases 692Exportation of Load Case Definitions 692

Loads 700Evaluation of Loads on Finite Element Entities 700Exportation of Load Data 700Importation of Load Data 729

Multi-point Constraints 751Exportation of Multi-point Constraint Data 751

Importing Results 767Drop Results Indexing 767Create/Find Loadcases 768Associate Global Variables 770Create Result Types 770

Examples of Translation 790Results Reader 790Extracting Temperature Dependent and/or Non-Linear Material Data 797Extracting Transient Load Histories 812Forward Moldflow Translator 816

PCL and Customization

8

9 PATRAN 2.5 Database Compatibility

Introduction 822

PATRAN 2.5 Compatible Database Functions 823

10 Broken, Obsolete, Modified and New Functions

Introduction 842

Basic Functions (Chapter 3) 843

System and Utility Functions (Chapter 4) 844

User Interface and List Processor Functions (Chapter 5) 847Possible parm names: 854

Creating New Analysis Forms Using PCL (Chapter 6) 865

Modifying the Database Using PCL (Chapter 7) 866

Accessing the Patran Database (Chapter 8) 873

PATRAN 2.5 Database Compatibility (Chapter 9) 879

Chapter 1: Introduction to CustomizationPCL and Customization

1 Introduction to Customization

Understanding PCL

Steps to Adding a New Functionality to Patran

PCL and CustomizationUnderstanding PCL

2

Understanding PCLThe PATRAN Command Language, or PCL, is central to all Patran customization. PCL is used to:

• Create functions to be called directly from Patran.

• Create forms and widgets.

• Call functions from all areas of Patran including all applications, graphics, the user interface, and the database.

• Spawn individual remote processes outside of Patran.

The chapters listed below will present information covering all of these topics.

• The PATRAN Command Language (PCL) Introduction

• User Interface and List Processor Functions

• System and Utility Functions

For more information concerning a particular function, refer to the Introduction (p. 9) in the PCL Reference Manual.

Important:As with any powerful programming language, the user is encouraged to take formalized training available from the MSC Institute of Technology to best exploit the underlying functionality and to minimize resulting problems.

3Chapter 1: Introduction to CustomizationSteps to Adding a New Functionality to Patran

Steps to Adding a New Functionality to PatranIn order to add a new analysis code to Patran three steps must be performed. First, modify the database to contain data about the new analysis code. This is done through PCL function calls. The resulting database will possess the information needed to display the new analysis code on the analysis preferences form. The preferences form allows the creation of element property, material property, loads and boundary condition, and multi-point constraint forms specific to the new analysis code. Also, element verification parameters specific to the new analysis code can be employed. This first step is fully described in Modifying the Database Using PCL.

Second, specific PCL functions to control the Analysis forms used for the new analysis code must be created. These routines will be used to create a PCL library which will be brought into Patran automatically when the analysis preference is set to the new analysis code. These forms can be as simple or as complex as desired. Creation of these Analysis forms is described in detail in Creating New Analysis Forms Using PCL.

Third, a translator must be created to import and export data to and from the Patran database. The functions used to extract, add or evaluate data stored in a database are discussed in the final two chapters. Accessing the Patran Database (Ch. 8) describes the standard Patran database interface, and PATRAN 2.5 Database Compatibility (Ch. 9) discusses database functions which are compatible with PATRAN 2.5.

PCL and CustomizationSteps to Adding a New Functionality to Patran

4

Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL and Customization

2 The PATRAN Command Language (PCL) Introduction

Introduction 6

Basic Concepts 7

PCL Variables and Constants 10

PCL Operators and Expressions 19

Control Statements 21

PCL Functions 25

The C Preprocessor 31

Finding Programming Errors with PCL 33

Initializing the Session 35

PCL and CustomizationIntroduction

6

IntroductionThe PATRAN Command Language (PCL) is a programming language which is an integral part of the Patran system. It can be used to write application or site specific commands and forms, perform variational or connatural modeling, and completely integrate commercial or in-house programs. The entire Patran user interface is driven by PCL.

PCL is a high level block structured language. It provides many features found in traditional programming languages including:

• Operators for arithmetic, relational, and string expressions.

• Intrinsic functions for math, string, and other operations.

• Variables with type, scope, and dimension attributes.

• Dynamically allocated virtual strings and arrays.

• Loop control structures such as WHILE, FOR, LIST, and REPEAT.

• Conditional control such as IF-THEN-ELSE and SWITCH-CASE.

• Subroutine and function calls from within PCL functions.

• Class grouping of related functions.

• Read/write access to external files.

• Support for PATRAN 2.5 NOODL rule.

• Preference to user interfaces, applications, databases, and graphics.

• PCL specific start-up files.

• Text output to the history window, session file, or TTY terminal.

PCL is a complete MCAE programming environment that greatly enhances the versatility of the Patran system.

Some of the benefits of PCL include:

• Application specific commands provide more accurate modeling. For example, pressure applied as a function of chord length along a turbine blade.

• In-line expressions make Patran more versatile for the everyday user.

• Allows Patran to be integrated more easily and completely with other commercial or in-house codes.

• Provides a mechanism for parametric design studies.

• Patran may be customized to service specific customer requirements.

7Chapter 2: The PATRAN Command Language (PCL) IntroductionBasic Concepts

Basic Concepts

Patran and PCLPCL is tightly coupled with Patran. The user interface system is integrated with PCL via callbacks. What this means is whenever a menu item is selected or a button clicked on, a PCL function is called to process the operation. In a similar fashion, after entering a line into the command line, that line is sent to PCL for processing. If a session file for processing is selected, the session file manager passes to PCL any lines that it does not handle itself.

PCL CommandsPCL statements come in many forms. Some examples of PCL statements include:

theta = 360.0 - MTH_ASIND( value )IF ( radius > 20.0 ) THEN radius = 20.0make_gear ( 30, 100 )

PCL commands may be entered interactively through the command line, or processed in a session file or retrieved from an external PCL file or library.

A PCL statement is normally terminated by a carriage return. A statement can be continued across multiple lines by using an at sign “@” as the last non-blank character of the line to be continued. It is not permissible to break a statement in the middle of an identifier, keyword, or constant value. It is possible to have multiple statements on a single line by separating them with a semicolon “;”. In general, break a line at a space, comma, or operator. Multiple spaces and/or tabs are treated as a single space.

Example:

IF( str_length( mystring ) >= 100 || @bigarray(n) < bigarray(n+1) ) THEN quit = TRUEx = 5; y = 10; z = x * ( y + 5 )

PCL CommentsIn PCL a comment is specified by starting with the sequence /* and ending with the sequence */. Comments may appear anywhere within a PCL statement except in the middle of a string constant. A comment may span multiple lines. A one line comment can also be specified by a dollar or pound sign as the first non-blank character. Examples of PCL comments include:

FillRadius = 5.0 /* Outside fillet radius */

and the following sequence:

/** A typical header block comment might look like this*/

Important:Examples in the following sections are excerpts from working PCL functions. By themselves, they are incomplete and will not execute properly.

PCL and CustomizationBasic Concepts

8

or a one line comment with:

$ This is a comment.# This is a comment too.

PCL Embedded in NOODL Commands and DataboxesA PCL expression can be embedded within any NOODL command by enclosing it in a set of backquote characters, ( ` ). Also PCL expressions can be embedded within most of the user interface databoxes in the same manner.

An example use of PCL within a NOODL would be:

LI,3#,ARC,5(0)/1/`30 + offset`,10

To use Patran as a calculator for example, enter:

!$` SQRT(250.) * 12.4`

and the response is made into the originating TTY window:

$ 196.0612

Be sure to preface any calculator directives with the “!$” sequence so that Patran does not attempt to process the line as a Patran command.

Another way to use Patran as a calculator is to use the write function.

WRITE (SQRT(250.) *12.4)

And the response is made into the command line:

$# 196.0612

In a user interface databox, use the backquote syntax such as:

Angle: ‘360/5‘

IdentifiersAn identifier is a one to thirty-one character name containing letters, digits, and underscores and beginning with a non-digit character. Variable names and function names are identifiers. PCL is not sensitive to uppercase and lowercase for all uses of identifiers and keywords. String contents are retained as case sensitive, but string comparisons are case insensitive.

Keywords are identifiers reserved for use by PCL. These cannot be used as variable or function names. Current PCL keywords include:

9Chapter 2: The PATRAN Command Language (PCL) IntroductionBasic Concepts

Some examples of valid identifiers are:

a, b, c, X1, x_2, InnerRadiusTryAgain, not_done

While the following are invalid:

_status, 10b(Variable names must begin with a letter.)

real, list(Variable names must not be reserved.)

This_is_Much_Much_Much_Much_too_long(Variable names may contain up to 31 characters.)

DirectivesDirectives begin with “!!” and are processed differently than regular PCL statements. Directives are processed immediately when encountered. Do not embed directives into PCL functions. Unexpected results may occur. Directive key words are:

BREAK BY CASE CLASS CLASSWIDE

CONTINUE DEFAULT DUMP ELSE END

FALSE FOR FUNCTION GLOBAL

IF INFORMATIVE INTEGER LIST

LOCAL LOGICAL ON READONLY REAL

REPEAT RETURN STATIC STRING SWITCH

THEN TO TRUE UNTIL VIRTUAL

WHILE WIDGET WIDGET_NULL

!!INPUT file Direct Patran to process all further input from the specified file.

!!LIBRARY file Access PCL libraries.

!!PATH Directory Specific directory search path for opening files.

!!TRACE option PCL execution verification.

!!DEBUG option Store PCL line contents in file for future reference when debugging PCL code.

!!COMPILE file into library

Compiles a PCL text file into library format.

!!OPTIONS option PCL environment options setting.

!!SIZE CODE newsize Set new size for compiler code area.

!!CLEAR GLOBAL name Erase definition of global variable.

!!CLEAR FUNCTION name Erase definition of a function.

PCL and CustomizationPCL Variables and Constants

10

PCL Variables and ConstantsPCL variables have the attributes of type, scope, and dimension. All variables must be defined before they are used. Variable names may be 1 to 31 characters in length. Valid variable types are integer, real, logical, string, and widget. Scope defines a variable's visibility and lifetime.

Data TypesAll PCL variables must be declared before they are used. The declaration specifies the variable's type, scope and dimension.

Dynamic

A dynamic data type is a data type that is used to describe an input argument, output argument, or return value from a built in PCL function that can be any combination of an integer, logical, real, string, or widget data type.

This data type is denoted in a PCL function description in this manual using an acronym: DYNAMIC_ILRSW. The ILRSW component in the acronym will be used to denote the exact data types that can be used with that value where I is used for an integer, L is used for logical, R is used for a real, S is used for a string, and W is used for a widget data type.

The dynamic data type is not supported by the PCL language and trying to declare a variable with a dynamic data type will generate an error. While it is possible for built in functions to use the dynamic data type, it is not possible to write a PCL function that uses this data type.

An example of a PCL function that returns a dynamic data type is the function sys_eval, 200.

Integers

An integer variable is defined by prefixing the variable name with the keyword INTEGER.

Example:

INTEGER a, b, c

An integer constant is represented by an optional plus or minus sign followed by a set of digits. The range of an integer is machine dependent but will always be able to represent a number between -2147483647 and 2147483647. It is also acceptable to use a hexadecimal constant by having the prefix 0x or 0X followed by hexadecimal digits in uppercase or lowercase.

Examples:

11Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL Variables and Constants

Logicals

A logical variable is defined by prefixing the variable name with the keyword LOGICAL.

Example:

LOGICAL exit_flag

A logical constant is represented by the reserved identifiers TRUE and FALSE.

Examples:

exit_flag = TRUE

or

exit_flag = FALSE

Reals

A real variable is defined by prefixing the variable name with the keyword REAL.

Example:REAL x, y, z, height

A real constant is represented by an optional plus or minus sign followed by an optional set of digits, a required decimal point, another optional set of digits, and an optional “E” followed by an optional plus or minus sign and a set of digits. There always needs to be at least one digit before or after the decimal point. The range and precision of real numbers is machine dependent, but count on 5 digits of accuracy and an exponent range of 1.E-30 through 1.E30.

Examples:

x = 4100.06; y = -22.E-4; z = -1.0E3

Strings

A string variable is defined by prefixing the variable name with the keyword STRING and appending the maximum string length as a positive integer within square brackets.

Example:

STRING name[20], option[130]

A character string constant is represented by a double quote, a string of characters, and another double quote. A character string which spans lines should do so by splitting it into smaller pieces and

4510, -17, 0X11E0 (The first two examples show positive and negative integer constants. In the third example, the prefix 0X indicates that 11E0 is a hexadecimal constant.)

PCL and CustomizationPCL Variables and Constants

12

concatenating the pieces together. A character string has both a maximum length and a current length. The current length of a character string can be anywhere from zero up to its maximum length.

Examples:

name = “I”multiplier = “23*A”option = “A CHARACTER STRING WHICH SPANS LINES SHOULD DO SO “// @ “BY SPLITTING IT INTO SMALLER PIECES AND “// @ “CONCATENATING THE PIECES TOGETHER.”

PCL strings are variable length up to the maximum size that they are declared. Therefore, the series of statements:

STRING line[40]line = “ABC”line = line // “ ”line = line // “DEF”

produces the variable line defined as “ABC DEF” with no trailing blanks. This is quite different than the way FORTRAN strings work.

Widgets

A widget variable is defined by prefixing the variable name with the keyword WIDGET and is used only for working with the user interface routines. A widget can be assigned from a user interface function or other widget or can be compared against another widget.

Example:

WIDGET myform, mybutton

The only widget constant defined is WIDGET_NULL. If a user interface routine fails to operate sucessfully, the widget value returned will normally be WIDGET_NULL. To initialize widget variables, initialize them to WIDGET_NULL.

Examples:

IF ( myform == WIDGET_NULL ) THEN WRITE (“Form not initialized”)

ScopeScope defines a variable's visibility and lifetime. Variables that are not assigned a scope behave like LOCAL variables if declared within a function definition or like GLOBAL variables if declared outside of a function. PCL variables may have the scope of global, local, static, or classwide. These scopes are defined below.

13Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL Variables and Constants

Examples:

Arrays

Directly Allocated Arrays

Any variable, regardless of its data type, can be made into an array. Arrays can have any number of subscripts. Subscripts are contained in parentheses separated by commas appended to the variable identifier. Each subscript may have a lower and upper bound separated by a colon. If the subscript range

GLOBAL Variable definition is available to all functions. Global variables become undefined when Patran terminates.

LOCAL Variable definition is local to a single function. A local definition temporarily overrides any global definition. Local variables become undefined when the function exits.

STATIC Variable definition is local to a single function. A Static variable retains its value between function calls. Static variables become undefined when Patran terminates.

CLASSWIDE Variable definition is local to a group of functions. A classwide variable retains its value between function calls. Classwide variables become undefined when Patran terminates.

Important: PCL uses a flat name space for both function names and variable names. The user should be careful not to use conflicting names for PCL variables and functions.

GLOBAL LOGICAL flag. Flag is defined global and since outside of a function definition is defined for use in the command line and in databoxes.

CLASS my_classCLASSWIDE STRING line[80]

The string line is defined within all the functions within the class my_class.

FUNCTION MY_FUNCTION (arg_list)STATIC INTEGER entries

The value established for entries in MY_FUNCTION remains the same between function calls.

LOCAL REAL x,y,z. These variables are only defined within my_function.

REAL arg_list () Since arg_list is an argument to the function, its scope is inherited from the calling function.

GLOBAL LOGICAL flag. Even though flag is defined GLOBAL outside the function, within each function definition it needs to be declared the same way. All references to flag affect the same global value.

END FUNCTIONEND CLASS

PCL and CustomizationPCL Variables and Constants

14

is not specified with a lower and upper bound, the lower bound is assumed to be one (not zero as in the C programming language). Subscript bounds may be negative or zero.

Arrays are stored in sequential order starting from the subscript to the right and moving to the left. This is opposite to the way FORTRAN stores array data, see Figure 2-1

LOCAL arrays are only allocated when the function is called and the memory is freed up when the function exits. Memory for arrays of other scopes remains allocated for the duration of the program’s execution.

Examples:

An array constant can be specified by enclosing a set of constant values in square brackets. The following examples will best illustrate the syntax.

STATIC INTEGER entries(100)

The subscript 100 creates a STATIC array of 100 integers referenced by 1 to 100.

REAL table(-5:10, 20, 5:7)

The first subscript of table, -5:10, allocates 16 rows which are referenced by the bounds of -5 to 10. The second subscript allocates 20 rows. The third subscript allocates three sets of data referenced by 5 to 7. The total array occupies 16*20*3 or 960 storage locations.

GLOBAL LOGICAL flags(0:8192)

The logical array flags occupies 8193 storage locations referenced by 0 to 8192.

STRING line[80](100),

ch[1](10,5) 100 strings of variable line, 80 characters each and 10 x 5 strings of variable ch, one character each.

INTEGER I(3,5) The integer array I occupies 15 storage locations arranged in order where the rightmost subscript varies most rapidly.

15Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL Variables and Constants

Figure 2-1 PCL Array Storage

When referencing arrays, a portion of the array may be specified by using a colon to separate the upper and lower bound.

Examples:

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. For example:

REAL mydata(VIRTUAL)

To allocate storage and specify lower and upper bounds, use the function SYS_ALLOCATE_ARRAY( array, lb1, hb1, lb2, hb2, lb3, hb3, lb4, hb4) passing 3, 5, 7, or 9 arguments depending on whether to allocate a virtual array to be one, two, three, or four dimensional. Once allocated, a virtual array can be used interchangeably with a non-virtual array. A different size array can be re-allocated with a subsequent SYS_ALLOCATE_ARRAY call, but the original contents of the array are lost. A different size array can be re-allocated to retain the old contents of the array with the SYS_REALLOCATE_ARRAY function. Storage can be freed with a SYS_FREE_ARRAY call. A virtual array with LOCAL scope is automatically freed when the function it is declared in exits. SYS_ALLOCATE_ARRAY returns a zero status on success and a non-zero if the allocation failed.

Or, to allocate a two dimensional array, enter:

[1, 2, 3] A three element integer array.

[“Ace”, “King”, “Queen”,“Jack”] A string array constant.

[1.1, 2.2], [17,5], [-8,0]] A real array constant dimensioned (3,2).

my_function( node_list(10:30) )

In this example, elements 10 through 30 of the node_list array are passed to my_function.

err = SYS_ALLOCATE_ARRAY (mydata, 1, 1000 ) Allocate a one dimensional array.

PCL and CustomizationPCL Variables and Constants

16

err = SYS_ALLOCATE_ARRAY (mydata, 1, 1000, 1, 20000)

Or, to re-allocate the two dimensional array, enter:

err = SYS_REALLOCATE_ARRAY (mydata, 1, 30, 1, 20000)

To find out the dimension associated with any array, use the PCL command SYS_ARRAY_NBOUND( array ).

The lower and upper bounds of an array are found by using the commands, SYS_ARRAY_LBOUND( array, bound ) and SYS_ARRAY_HBOUND( array, bound ).

Virtual Strings

A string can be defined as a virtual string instead of directly declaring the size of the string. Virtual strings 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 data. To declare a virtual string, use the keyword VIRTUAL in place of the string size for the declaration. For example:

STRING line[VIRTUAL]

To allocate storage and specify the maximum size of the string, use the function SYS_ALLOCATE_STRING( string, maxsize). Currently, the string size must be between one and 32767. Once allocated, a virtual string can be used interchangeably with a non-virtual string. A different size string can be re-allocated with a subsequent SYS_ALLOCATE_STRING function, but the original contents of the string will be lost. A different size string can be re-allocated to retain the old contents of the string with a SYS_REALLOCATE_STRING function. Storage can be freed with the SYS_FREE_STRING function. A virtual string with LOCAL scope is automatically freed when the function it is declared in exits. SYS_ALLOCATE_STRING returns a zero status on success and a non-zero if the allocation failed. Virtual strings arrays are allowed, but currently a SYS_REALLOCATE_STRING may not be performed on one.

SYS_FREE_ARRAY (mydata) Free up the array storage space.

err = SYS_ALLOCATE_ARRAY (moredata, -200, 200, 0, 20)

Allocate a two dimensional array.

SYS_FREE_ARRAY (moredata) Free up the array storage space.

17Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL Variables and Constants

To find out the maximum size of any string, use the PCL function STR_MAXLENGTH(string).

Variable InitializationVariables may be initialized with a value when they are declared. Initializations are specified by following the variable declaration with an equal sign (“=”) and then a constant of the correct type for the item being declared. If an array is being declared, there must be enough constants to initialize the entire array, separated by blanks or commas optionally enclosed in square brackets.

GLOBAL variables defined within a FUNCTION definition cannot be initialized. CLASSWIDE variables also cannot be initialized currently. If a STATIC variable is initialized, the initialization takes place at compile time, and any modification to the value of the variable remains intact for the duration of the session. When GLOBAL or LOCAL variables are initialized, the initialization is identical to including the assignments following the declaration. This means that a LOCAL variable with initialization will be re-initialized on each entry into the FUNCTION in which it is defined.

Some example initializations are:

REAL TABLE(2,3) = [ 10, 20, 30, 11, 21, 31 ]STRING PROMPT[20] = “This is a prompt”INTEGER I = 0, J = 17

err = SYS_ALLOCATE_STRING (line, 500) Allocate a 500 character string.

err = SYS_REALLOCATE_STRING(line, 800) Now reallocated as a 800 character string.

SYS_FREE_STRING (line) Free up the string storage space.

STRING lines1[VIRTUAL](20), lines2[VIRTUAL](VIRTUAL)

err = SYS_ALLOCATE_STRING(lines1,100)

Allocate the array to have strings of 100 characters.

err = SYS_ALLOCATE_STRING(lines2,80)

err = SYS_ALLOCATE_ARRAY (lines2,1,20)

Allocate a 20 element array of strings of 80 characters.

SYS_FREE_STRING (lines1)

SYS_FREE_STRING (lines2)

SYS_FREE_ARRAY (lines2)

Important:Multi-dimension arrays are stored in row major order. This is opposite of FORTRAN's definition. Virtual arrays and virtual strings can not be initialized.

PCL and CustomizationPCL Variables and Constants

18

Argument DeclarationThe input and output parameters that are passed back and forth to a function are called arguments. Arguments to a function must be declared and must match the datatypes used within the function.

Within a function, it is permissible and recommended that the values within an array or string definition be omitted. The function uses the dimension values of the arrays or strings specified in the calling argument in any case so it can be misleading to specify values for dimensions for the arguments. Some examples are:

REAL ENTRY(5,20), ELEMTABLE(20,40)STRING ENTRYTITLE[40] = “This is the title for the Entry Table”STRING ELEMTITLE[15] = “Type of Element”INTEGER N, K...R = MY_FUNCTION (ENTRY, N, ENTRYTITLE )...R = MY_FUNCTION (ELEMTABLE, K, ELEMTITLE )...FUNCTION MY_FUNCTION (TABLE, POINTER, TITLE )REAL TABLE()STRING TITLE[]INTEGER POINTER

19Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL Operators and Expressions

PCL Operators and Expressions

Hierarchy of OperatorsPCL supports a wide range of operators including basic math and Booleans. Expressions are built from a set of operators, constants, variables, and functions. User functions and intrinsic functions can be used as operands. Uniary operators take a single operand to the right, and binary operators are placed between two operands. Numeric, logical and string operators are provided.

Certain operators take precedence over others (i.e., multiplication is done before addition). The precedence can be overridden by use of parentheses. The following list gives the operators in order of precedence from highest to lowest.

The following table is list of operators giving the datatypes that they can operate on and the result datatype for the operation. In the table, the letters I, R, S, L, and W stand for INTEGER, REAL, STRING, LOGICAL, and WIDGET respectively.

Table 2-1

Operators Definitions

+ - Uniary Plus or Minus, Logical Not

** Exponentiation

* / Multiplication and Division

+ - Addition and Subtraction

// String Concatenation

< > <= >= == != Relational Operators

|| && Logical Or, Logical And

+= -= = Increment, Decrement, Assignment

PCL and CustomizationPCL Operators and Expressions

20

.

Examples:

An example of using operators to find the two real roots of a quadratic equation in PCL:

IF ( b**2 > 4.0 * a * c && ABS(a) >= 1.0E-7) THEN root(1) = ( -b + SQRT( b**2 - 4.0 * a * c )) / (2.0*a) root(2) = ( -b - SQRT( b**2 - 4.0 * a * c )) / (2.0*a)END IF

String Comparisons:

The string comparison operators are special in that they ignore trailing blanks and uppercase and lowercase. Therefore, all the following expressions are TRUE.

“ABC” == “ABC”“ABC” == “abc”“TEST” == “TEST”“HELLO” < “help”“hello” < “HELP”

Table 2-2

Operators Operands Result

** * / + - += -= I,R I,R

// S S

< > <= >= I,R,S L

== != I,R,S,L,W L

= I,R,S,L,W I,R,S,L,W

|| && L L

Note: Expressions with a mixture of INTEGER and REAL data types are valid and will be converted to the assigned data type. Real to integer conversion truncates the fraction. All arithmetic expression evaluations are done in single precision.

IVAL += 4 * SIND( MYANGLE )

IVAL is incremented by the integer value resulting from the calculation of (4 x sin(MYANGLE) and the truncation of all digits after the decimal point.

MYFUNC( ) >= (A+1)*2 && STR1 // STR2 == “TESTING”

Test for MYFUNC( ) greater or equal to (A+1)*2 and the concatenation of STR1 with STR2 logically equal to the string “TESTING”.

21Chapter 2: The PATRAN Command Language (PCL) IntroductionControl Statements

Control StatementsControl statements are used to transfer control to another section of the program. The following syntax conventions are observed in the following examples:

REQUIRED KEYWORDSAll required keywords are identified in bold Courier font.entryItems in plain Courier font are descriptions of the expected entry.[label]Items enclosed in brackets are optional.

BranchingPCL is a block structured language. Language elements that control branching and skipping are the IF THEN ELSE, SWITCH CASE, BREAK and CONTINUE statements.

Break and ContinueThe BREAK and CONTINUE statements are only allowed within the body of FOR, WHILE, REPEAT, SWITCH and LIST statements. In addition, if the optional label field is given, the label must match one of the above block structures the statement is within. The CONTINUE statement causes transfer to the END statement processing for the block structure indicated by the label field or the most current block structure if no label is provided. This essentially causes the loop to repeat. The BREAK statement is similar except that it transfers control past the END statement, thereby terminating execution of the loop. The format of the two statements is as follows:

BREAK [ label ]CONTINUE [ label ]

Examples:

CONTINUE active_set_loop

BREAK

Simple If ThenThe simple IF statement evaluates the logical expression in the clause. If the result is TRUE, the single statement immediately following the THEN keyword is executed. If the result is FALSE, then nothing happens. The IF statement structure is as follows:

IF( logical_expression ) THEN statement

If Then ElseThe IF statement evaluates the expression in the clause. If the result is TRUE, the group of statements immediately following is executed and then control skips to the matching END IF clause. If the result is FALSE, then if there is an ELSE IF clause, it is evaluated and the preceding logic is repeated. If all results evaluate to FALSE, then the statements following the ELSE are executed. Multiple ELSE IF clauses are allowed. The IF statement structure is as follows:

PCL and CustomizationControl Statements

22

IF( logical_expression ) THENstatements...ELSE IF( logical_expression ) THENstatements ...ELSEstatements ...END IF

The program statements within a conditional structure are normally indented to make it easier to read. PCL and Patran ignore all leading blanks in a line.

Examples:

In the following example of the IF THEN statement, a patch model is being adaptively meshed based on the previously evaluated strain energy density for the region defined by the patches in patch_list:

IF ( strain_energy > max_threshold ) THEN

el_length = el_length / 2.0do_my_mesh( patch_list, “QUAD”, I,el_length )

ELSE IF ( strain_energy < min_threshold) THEN

el_length = 2.0 * el_lengthdo_my_mesh( patch_list, “QUAD”, I,el_length )

ELSE

BREAK adapting /* Break out of loop called adapting */

END IF

Switch and CaseThe SWITCH statement starts by evaluating the expression in the clause. It then scans for each CASE statement in turn. Upon reaching the CASE statement, each expression in the CASE is evaluated. If there is an equality match of the CASE expression result and the SWITCH expression result, the statements up to the next CASE or DEFAULT are executed, and then control passes to the statement after the END SWITCH. If the DEFAULT is reached with no CASE expressions matching, then the statements following the DEFAULT will be executed. The DEFAULT clause is optional. See the Break and Continue, 21 statement for a description of the SWITCH label. The SWITCH statement structure is as follows:

SWITCH(expression) [ label ]CASE(expression1,expression2,...)statements ...CASE(expression1,expression2,...)statements ...DEFAULTstatements ...END SWITCH

As an example of using the SWITCH statement, a PCL function is used to interactively construct the element property cards based on the element configuration code. The function UI_READ_REAL prompts the user with the argument string and returns the real value input from the keyboard.

SWITCH (el_config) CASE (2)

23Chapter 2: The PATRAN Command Language (PCL) IntroductionControl Statements

midm = UI_READ_REAL(“ENTER MEMBRANE MATERIAL ID:”)CASE (3)mids = UI_READ_REAL(“ENTER SHELL MATERIAL ID:”)CASE (mconfig)mass = UI_READ_REAL(“ENTER TOTAL MASS:”)CASE (sconfig)spring = UI_READ_REAL(“ENTER SPRING CONSTANT:”)DEFAULTWRITE_LINE(“WARNING: ELEMENT CONFIG”, el_config,“UNDEFINED”)END SWITCH

LoopingA loop is a repeated execution of a particular segment or group of statements. Loops include initialization, incrementation, execution and test. Loops may be nested within one another. Block structures used for looping in PCL are WHILE, REPEAT, LIST and FOR statements.

ForThe FOR statement begins by evaluating the first numeric expression and assigning it to the variable. Next, the second expression is evaluated and saved as the TO result. The third expression is evaluated and saved as the BY result. If the BY result is zero, an error occurs. If the BY result is positive and the variable value is greater than the TO result, control passes to the statement following the matching END FOR. If the BY result is negative and the variable value is less than the TO result, control also passes to the statement following the matching END FOR. Otherwise the statements in the body are executed. When the END FOR is reached, the variable is incremented by the BY result. The preceding logic is then repeated starting at the point after the expressions were evaluated. Also see the description of the Break and Continue, 21 statements. The FOR statement structure is as follows:

FOR(variable=numeric_expr.TO numeric_expr. [ BY numeric_expr. ]) [ label ]statements...END FOR

WhileThe WHILE statement evaluates the expression in the clause. If the result is FALSE, control passes to the point after the matching END WHILE. Otherwise, the statements are executed and the preceding logic is repeated. Also see the description of the Break and Continue (p. 2-21) statements. The WHILE statement structure is as follows:

WHILE( logical_expression ) [ label ]statements...END WHILE

The program statements within a loop structure are normally indented to make it easier to read.

The following is an example of the use of WHILE and FOR statements. A text file containing node displacements in FORTRAN format 6E16.9 is read and stored in array “node_disp” with library utility function TEXT_READ. The file “fid” has previously been opened with a call to the library function TEXT_OPEN. The integer function TEXT_READ returns the value 0 for a successful read and non-zero otherwise.

PCL and CustomizationControl Statements

24

count = 0WHILE ( TEXT_READ ( fid, “%OF%%6E16.9%”, O, node_dis ( count +1, 1:6)) == 0)count += 1IF ( count > 10000) THENWRITE_LINE(“* DISCONTINUED READING FILE AT” // @“10,000 RECORDS”)BREAK END IFEND WHILE

RepeatThe REPEAT statement starts by executing the statements up to the matching UNTIL clause. Then the expression in the clause is evaluated. If the result is FALSE, the preceding logic is repeated. Otherwise, execution continues with the statement after the UNTIL. Also see the description of the Break and Continue, 21 statements. The REPEAT statement structure is as follows:

REPEAT [ label ]statements ...UNTIL( logical_expression )

As an example of the REPEAT structure, the user is requested to input a grid ID. If an invalid ID is entered, the user is prompted until a valid ID is entered.

REPEATgrid_id = UI_READ_INTEGER( “ INPUT GRID ID ”)UNTIL ( VALID_GID(grid_id) )

ListThe LIST statement executes the statements in the body for each expression in the expression list. Each expression is evaluated in turn and assigned to the variable. For each assignment done, the statements in the body are executed. Also see the description of the Break and Continue, 21 statements. The LIST statement structure is as follows:

LIST( variable=expression1 [,expression2, ...] ) [ label ]statements ...END LIST

In the following example of a LIST statement, the variable “diameter” is used to create both the inside and outside surface of a sphere. The variables x0, y0 and z0 are the global coordinates of the sphere’s origin.

LIST ( diameter = inside_diameter, inside_diameter + thickness )!GR,#,,`x0`,`y0 - diameter`,`z0`!LIN,2#,ARC,`x0`/`y0`/`z0`/`x0`/`y0`/`z0 + 1`/180,#!PA,8#,ARC,`x0`/`y0`/`z0`/`x0`/`y0 + 1`/`z0`/360,2#END LIST!HP,8#,2P,,`maxpid + 1`T`maxpid + 8`,`maxpid + 9`T`maxpid + 16`

25Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL Functions

PCL FunctionsA PCL function is a self-contained program unit consisting of PCL statements. It can perform as a subroutine, breaking programs into logical modules and passing arguments back and forth to other PCL functions or to the main program. Or, it can return a calculated output quantity for the function. In addition, a PCL function can be used to perform both tasks.

PCL functions are defined in files which can be created and modified with system level text editors. PCL functions are then compiled during a Patran session. A PCL function can call other functions. PCL functions can be called recursively.

PCL provides the ability to group functions into named libraries using the LIBRARY command with options to ADD, REMOVE CREATE, DELETE and LIST. An extensive Patran library of functions is also available. The library contains the following categories of functions:

Structure of a PCL ClassPCL functions may optionally be grouped into PCL classes. A PCL class is simply a group of functions that may share a common set of variables. PCL classes are used primarily for working with the user interface routines.

The first statement in a PCL class must contain the word CLASS and the name of the class. The last statement in a PCL class must be an END CLASS statement.

Patran Function Type Function Prefix

Mathematical MTH_

String STR_

System Utility SYS_, UTL_

Block I/O BLOCK_

File I/O FILE_

Record I/O RECORD_

Stream I/O STREAM_

String I/O STRING_

Text I/O TEXT_

Virtual I/O VIRTUAL_

Miscellaneous XF_, UI_, IO_, MSG_, EM_

Session File SF_

PCL and CustomizationPCL Functions

26

A PCL class may have a set of “classwide” variables. These variables are declared the same as other variables but must specify the scope CLASSWIDE and must appear between the CLASS statement and the first function definition.

The syntax of a PCL class definition is:

CLASS classnameCLASSWIDE declarations...functions (see Structure of a PCL Function, 26)... END CLASS

Where classname is the name given to the class.

To refer to a function that resides in a class, specify the classname, a period, and then the function name, i.e., classname.functionname.

Structure of a PCL FunctionThe first statement in a PCL function must start with the word FUNCTION. The last statement in a PCL function must be an END FUNCTION statement.

A PCL function may have an argument list and may also calculate an output quantity for the function. If an argument list is present, it may contain input parameters from the calling program and/or output parameters which pass values back to the calling program or function. The RETURN [value] statement is used to return a calculated output quantity for the function.

Since a FUNCTION may have more than one logical ending, the RETURN [value] statement can appear more than once. The optional value associated with the RETURN statement is the calculated output quantity of the function.

The syntax of a PCL function definition is:

FUNCTION fname( arglist ) declarations... statements... (and/or) NOODL commandsEND FUNCTION

Where fname is the function identifier. arglist is the argument list passed by the function. For the function to return a value, the following statement must be contained in the function:

RETURN value

Whenever the statement RETURN is encountered in a PCL function, processing of the current function terminates and control is passed to the calling function. The return value is optional.

The WHILE loop discussed in a previous example is shown in the context of a complete function. The array “node_disp” is a GLOBAL variable which will hold the node displacement data for use later on

Important:Variable names and function names conflict in PCL. PCL uses a flat name space for both.

27Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL Functions

during the Patran session. The function TEXT_OPEN opens a file and returns the integer value -1 when it is finished reading a file. The following listing is the complete PCL function:

FUNCTION DISP_READ( file_name)

/* ABSTRACT: Read a file containing node displacements** INPUT:* file_nameOS level name of file containing*formatted records* SIDE EFFECTS:* GLOBALnode_dispNode displacements read and stored here*/

GLOBAL REAL node_disp(10000,6)INTEGER count, i, fidSTRING file_name[80]REAL nodes (6)

/* Open file containing node displacements*/

IF ( TEXT_OPEN( file_name, “or”, 0, 0, fid) == 0 ) THENcount = 0

/* Read and store the data in the global variable “node_disp”*/

WHILE(TEXT_READ ( fid, “%OF%%6E16.7%”, O, nodes, “ ”) == 0 ) count += 1

/* File is too large */

IF ( COUNT > 10000 ) THENWRITE_LINE(“* DISCONTINUED READING”, file_name, @“AT 10,000 RECORDS” )BREAK END IF

/* Each record contains six entries, three displacements* and three rotations. file is formatted FORTRAN 6E16.7 */

node_disp (count, 1:6) = nodesEND WHILE

/* Close the file */

TEXT_CLOSE(fid, “ ”)ELSEWRITE_LINE(“* CANNOT FIND FILE”, file_name)END IFEND FUNCTION

To use the DISP_READ function during a Patran session, the following command is entered in the command line.

DISP_READ(“displacements.dat”)

If, for example, the file displacements.dat contains the desired data, DISP_READ accesses the file to read the displacement data into variable “node_disp.” To access the array “node_disp,” it must be defined as GLOBAL in the session by entering:

GLOBAL REAL node_disp(10000,6)

PCL and CustomizationPCL Functions

28

Accessing PCL FunctionsOnce a text file has been created which defines the function, the file must be read into Patran so that it is accessible. There are two directives for achieving this:

!!INPUT file

!!COMPILE file [INTO] library_file

A directive is recognized by the two “!!” exclamation marks at the start of the line. Unlike a PCL statement, which is first compiled making it available for execution, PCL directives are executed immediately.

The INPUT directive allows selection of an input file for further PCL or Patran commands. After receipt of an INPUT directive, commands will now be read from the specified operating system text file. When the end of that file is reached, input will return to the previous file or to the user. Input files can be nested several layers deep. This allows INPUT directives to be used similarly to the concept of including files found in other programming languages.

PCL functions are always compiled into a binary format before being executed. If a function is simply entered or !!INPUT, the compile takes place “on the fly.” The COMPILE directive allows the function to be compiled into the binary format in advance and save the compiled form in a library file with other compiled PCL functions. Using this method the user avoids having to compile the function each time Patran is used.

For the previous two function examples, the directives:

!!INPUT nx !!INPUT disp_read

read the files nx.pcl and disp_read.pcl and allow access to the functions during the session in which the directives are issued. If the file type is not specified .pcl is assumed.

To put the same two functions into the library my_library.plb, issue the directives:

!!COMPILE nx my_library!!COMPILE disp_read my_library

If the library my_library does not exist in the current directory, executing the COMPILE directive will create it with maximum entries set to 256, otherwise, the files will be placed in the existing my_library. If a function by the same name exists in the library, it will be replaced and a message will be issued to the history window.

LibrariesA LIBRARY is a binary file containing any number of compiled PCL functions. A library provides a convenient mechanism for accessing and organizing compiled PCL functions. Whenever PCL is requested to execute a PCL function, it will search the set of libraries that have been specified in LIBRARY directives. The format of the LIBRARY directive is:

!!LIBRARY [ ADD ] file [ file ....]!!LIBRARY REMOVE file [ file ....]!!LIBRARY NONE

29Chapter 2: The PATRAN Command Language (PCL) IntroductionPCL Functions

!!LIBRARY!!LIBRARY CREATE file [ max_entries ]!!LIBRARY MERGE sourcefile destfile!!LIBRARY SORT file!!LIBRARY REHASH !!LIBRARY KEEPOPEN file [ file ....]!!LIBRARY DELETE file function [ function ...]!!LIBRARY LIST file [ function ... ]

Where file is the operating system name of a library to include in future searches. LIBRARY ADD directives are cumulative. Each one adds an additional library for which to search. The libraries are searched in the reverse order from when specified. The REMOVE option removes a library from the search. The NONE option clears the library search list. A null library command displays the current library search list.

The CREATE option creates a new library which can contain up to the number of functions specified by max_entries, or if max_entries is zero, a “growable” library is created. (If max_entries is not specified it defaults to 256.)

The MERGE option allows the entries to be merged or added from one library into another library. This operation can also be used to compress a library by creating a new library, merging the old library into the new library, and then replacing the original library with the new library.

The SORT option allows the entries in the library to be sorted alphabetically to obtain a nicer listing.

The REHASH option is rarely used but, it can recognize that the contents of the libraries in the library list may have been changed by another user or process and causes Patran to rebuild its optimization tables for all libraries.

The KEEPOPEN option can be used for any library that is already in the library list and attempts to increase performance of accessing frequently used PCL libraries by keeping the operating system library file open all the time.

The DELETE option is used to delete functions from a library. The LIST option lists the contents of a library providing date and size for each function.

To access the library, my_library, issue the directive:

!!LIBRARY my_library

The functions NX and DISP_READ may now be used at any time during the session. To eliminate the need for compiling functions each time they are used, try creating and saving libraries. Use the start-up files to issue the LIBRARY directive.

The sys_library (option, data) function also allows access to the library functions and can be compiled into PCL functions or used within IF statements in PCL start-up scripts. Generally, the “option” is a string containing the operation such as “ADD” and the “data” is a string with the file or function names.

Path DirectiveTo exercise more control over the use of PCL files, the PATH directive defines the order in which a set of directories is searched to find files needed by PCL. These include the files referenced by the other directives as well as files used by many of the PCL intrinsic functions. Examples of files are libraries,

PCL and CustomizationPCL Functions

30

INPUT files, start-up files, and files opened by the file I/O utilities. The current directory is always searched first. The default PATH is often configured by the init.pcl file but normally contains the user’s home directory followed by any needed Patran system directories. The format of the PATH directive is:

!! PATH [ ADD ] directory [directory ...]!! PATH REMOVE directory [directory ...]!! PATH NONE!! PATH

where directory is the operating system name of a directory to search. The directories are searched in order. The latest ADD is used first. Within an ADD, the directories are searched first to last. REMOVE will remove entries from the PATH. NONE will clear the PATH. A null PATH command will list the current PATH setting.

The sys_path (option, data) function also allows access to the path and can be compiled into PCL functions or used within IF statements in PCL start-up scripts. Generally, the option is a string such as “ADD” and the data is a string with the directory name(s).

31Chapter 2: The PATRAN Command Language (PCL) IntroductionThe C Preprocessor

The C PreprocessorDuring the development of Patran, the C preprocessor is used with C, FORTRAN and PCL source code. In other words, our source files are automatically sent through the C preprocessor prior to being sent to the specific compiler.

Use of the C preprocessor has many advantages. It allows for substitutions which make the source much more readable. For example, with the C preprocessor a section of code could be written like this:

#define NODE 1#define ELEMENT 2 IF ( entity == NODE ) THEN xxx ELSE IF ( entity == ELEMENT ) THEN xxx END IF

instead of like this:

IF ( entity == 1 ) THEN xxx ELSE IF ( entity == 2 ) THEN xxx END IF

Furthermore, these substitutions can be placed into an include file which would allow for centralization of the “#define” statements. Centralization of definitions into include files allows for cleaner and simpler code, ensures consistency and allows for changes throughout the code to be made very simply. If the two “#define” statements mentioned above were put into an include file called “entity_codes.p” then the above piece of code would be as follows:

#include “entity_code.p” IF ( entity == NODE ) THEN xxx ELSE IF ( entity == ELEMENT ) THEN xxx END IF

If the “entity_codes.p” include file were used consistently through out all source then the element entity code could change from 2 to 3 by simply changing one line in the “entity_code.p” file. The same idea applies to character strings. If all character strings used in code are placed into include files then changing the text strings is a simple task. If the name of an application changed from “in-house-code 5.3” to “in-house-code 5.4” it would only require one change in one file.

The naming convention for include files in Patran is that PCL include files are suffixed with a “.p,” FORTRAN include files are suffixed with a “.i” and C include files are suffixed with a “.h.” An include file is only used for one language, so if the same type of file is to be used in FORTRAN, C and PCL there would be three files. In such a case there is always one master include file and then slave files which merely “#include” the master file. Continuing with our “entity_code.p” example, if this file were to be used in PCL, FORTRAN and C then there would be three include files (entity_codes.p, entity_codes.i and entity_codes.h) whose contents would be:

-------- Contents of entity_codes.p -------------- /* Include file containing entity codes */ #define NODE 1 #define ELEMENT 2

PCL and CustomizationThe C Preprocessor

32

-------- Contents of entity_codes.i -------------- /* Include file containing entity codes */ #include “entity_codes.p”

-------- Contents of entity_codes.h -------------- /* Include file containing entity codes */ #include “entity_codes.p”

Such exclusiveness of include files allows the developer to easily accommodate for the different requirements of different computer languages.

Standard C compilers automatically send source files through the C preprocessor, so C source files do not need to be preprocessed prior to compilation. But, whenever C preprocessor commands are imbedded in FORTRAN or PCL source the source file must first be sent through the C preprocessor and the resulting file sent to the appropriate compiler. A typical C preprocessor command would be:

cpp -P -I$P3_HOME/customization <input_file_name> <output_file_name>

See any C language manual for more on the C preprocessor.

There are many PCL include files which are delivered with Patran in the $P3_HOME/customization directory: appforms.p, appstrings.p, uistrings.p, etc. Two of these include files, appforms.p and uiforms.p, are heavily used in the PCL functions which create Patran forms. The contents of these files are discussed in User Interface and List Processor Functions (Ch. 5).

33Chapter 2: The PATRAN Command Language (PCL) IntroductionFinding Programming Errors with PCL

Finding Programming Errors with PCLThere are two features in PCL that track the PCL program as it is processed: TRACE and DEBUG. These “Debugging tools” can be very useful when finding and correcting errors in the program logic. The first of these tools is the TRACE directive.

Trace DirectiveThe TRACE directive allows specification of tracing options during execution of PCL functions. The TRACE should normally be set to NONE. There are three options that can be enabled in TRACE; they are CALLS, EXITS, and LINES. When CALLS is set, each time a PCL function is called, a message is output. When EXITS is set, messages are output when PCL functions return control to their calling functions. When LINES is set, the current statement numbers are displayed as a function executes. In addition, if DEBUG was ON when the function was compiled, the source statements themselves will be displayed when LINES is set. The format of the TRACE directive is:

!! TRACE NONE(disable tracing)!! TRACE CALLS(enable tracing of function calls)!! TRACE NOCALLS(disable tracing of function calls)!! TRACE EXITS(enable tracing of function exits)!! TRACE NOEXITS(disable tracing of function exits)!! TRACE LINES(enable tracing of function statements)!! TRACE NOLINES(disable tracing of function statements)...

!! TRACE CALLS LINES!! TRACE level mask is CALLS NOEXITS LINES...

Debug DirectiveThe second directive that is useful for debugging PCL programs is the DEBUG directive. The DEBUG directive allows specification of a debugging flag which affects future compilations. With DEBUG ON, the original source lines of the file are compiled into the function. This allows the TRACE command to display the source during execution. The DEBUG option should only be used during development as it creates much larger and slower code. The format of the DEBUG directive is:

!!DEBUG ON(enable DEBUG lines during compile)!!DEBUG OFF(disable DEBUG lines during compile)

Don't forget to set TRACE to LINES when using the debug mode or compiling the function with DEBUG set to ON.

Another feature provided by PCL is the DUMP command. The format of the DUMP command is:

DUMP variable

Where variable is any currently declared variable.

PCL and CustomizationFinding Programming Errors with PCL

34

When the DUMP statement is encountered during execution of any PCL function, the contents of the variable is displayed in the alpha buffer. For an example, we examine the variable xyz by putting the following statement in function NX.

DUMP xyz

When the function NX is executed with a node located at the x=1,y=0,z=0 location, the following is displayed in the alpha buffer:

Array: ( 3 )Data: 1.0, 0.0, 0.0

35Chapter 2: The PATRAN Command Language (PCL) IntroductionInitializing the Session

Initializing the Session

PCL Start-Up FilePCL provides a means to control the session environment by reading the init.pcl file in the current directory when beginning a Patran session.

The init.pcl file does not usually have to be modified. Instead, the init.pcl as delivered will execute the additional start-up files p3prolog.pcl and p3epilog.pcl. These files, if they exist, are executed at the start(p3prolog) and end (p3eiplog) of the init.pcl processing and are a good place to place user or site specific commands.

Typical commands in the start-up files are custom !!PATH and !!LIBRARY settings. In addition, !!INPUT statements can be added to the start-up files to provide additional user or site start-up file capabilities.

Session Files Support in PCLThe purpose of adding session file support to PCL code is to allow a Patran session to be recreated when the session file is played. The sections below describe how an application developer may indicate the PCL commands that need to be recorded and played to duplicate a session. These PCL commands are known as “events of interest.”

Controlling recording file contents

There are tools available to the application developer to control the contents of a session file. They are described in the following sections. In general, it is desired that a session file only contains PCL function calls that affect the database (e.g., open/new/close database, create/modify/delete geometry, etc.). The following sections describe the tools which allow the application developer to control which function calls are recorded and how their parameters should be written to a session file (evaluated or symbolically). Additionally, the issue of recording user rotation events is addressed.

PCL recording directive (>)

The “>” directive is used to indicate that the function call on a line of PCL is an “event of interest.” When these events are executed, they are usually written to the session file. They are also sent to the history window at execution time. In situations where nested “events of interest” occur, only the first/top level event will be written to the session file. This prevents the recording of nested events, which would cause undesirable results. This directive should be placed in column one of a PCL statement.

The intent of this directive is to allow an application that is not invoked from the command line (e.g., forms) to record only those PCL commands that affect the database. In this way, playback can suppress all application dependent user interfacing. Consider the following simple example of PCL code that operates the form to build a grid.

asm_const_grid_xyz( “1”,“[0 0 0]”, “CF 0”,create_grid_xyz_created_ids))

PCL and CustomizationInitializing the Session

36

the > directive is placed on the line containing the call to be recorded as shown:

> asm_const_grid_xyz( “1”, “[0 0 0]”, “CF 0”,create_grid_xyz_created_ids))

If the function is called from the command line or a session file, all the ">" in the function will be ignored. For example,

FUNCTION simpoint() > STRING asm_create_grid_xyz_created_ids[VIRTUAL] > asm_const_grid_xyz( "#", "[1 0 0]", "Coord 0", asm_create_grid_xyz_created_ids ) END FUNCTION

Then execute at the command prompt (or via a session file)

simpoint()

The asm command will not be written to the session file. The reason is that "simpoint( )" is already being written to the session file. If the asm line were written, it would be run twice; once by the simpoint function being called again, and once by the session file itself.

The ">" directive only works if the function is called by a GUI. That is, if an "Apply" button, callback etc. is used in a custom form, then "simpoint()" is not written to the session file, so asm_... is.

Variables in session files

Occasionally, it is desirable to use more than one PCL function call with variables being passed from one function to another. There are two methods to allow this mechanism to work within the confines of a session file.

Combining separate functions

The first method requires the application developer to create a parent function which handles the variable passing from one function to another. This new parent function would be marked as the “event of interest” in the PCL code. For example, assume two functions PCLF1 and PCLF2 are being used. The parameter returned from PCLF1 is passed to PCLF2. This is handled as follows:

FUNCTION PCLF1AND2REAL arg1to2PCLF1 (arg1to2, 45.5, 60, “TRUE”)PCLF2 (arg1to2)END FUNCTION /* PCLF1AND2 */

Variable substitution by name

An alternate method causes Patran to automatically substitute the name of the variable rather than the value of the variable. This is accomplished with the $ directive. By placing the $ before any variable, the variable declaration is automatically written to the session file and the reference is symbolic (the name is used as opposed to its value). The variable declaration is automatically output to the session file. The following example illustrates another technique to handle the previous example.

37Chapter 2: The PATRAN Command Language (PCL) IntroductionInitializing the Session

> PCLF1 ($arg1to2, 45.5, 60, “TRUE”)> PCLF2 ($arg1to2)

Direct writes to the Session File

There are two PCL functions which allow the PCL applications developer to write directly to the session file. They are:

sf_write( string )sf_force_write( string )

The first function writes the string into the session file if session file recording. The second function forces the string into the current session file, assuming one is open and not paused, even if recording would not normally occur, i.e., nested function calls. This second function is probably most useful for either debugging PCL functions or adding comments to session files.

Conditional recording of rotation function calls

Sometimes it is not desirable to record every PCL function call. Some workstations that have hardware graphic accelerators may actually generate hundreds or thousands of function calls for a single user action (e.g., geometry scaling or rotations using a dial). For situations such as these, it is desirable to avoid recording these function calls, as they expand the session file without adding particularly interesting information. There are, however, situations where recording these function calls is desirable. The following PCL function allows the user to optionally record these rotation function calls:

sf_rotation( )

This function call must be executed immediately before the call which performs the rotation. For example:

IF( doit ) THEN sf_rotation()>gm_rot_x( .5 )ENDIF

If the record rotations toggle on the Session File Record form is set, then the call to gm_rot_x is recorded. If the toggle is not set, the function call is not recorded. See Session File Functions, 163 for the location of this toggle.

User controlled conditional recording

There is also a PCL function to allow the user to control recording of the session file. This function allows the user to prevent the next function call from being recorded, based upon the value of its logical argument. The function is:

sf_write_disable ( donext )

If the value of donext is TRUE, then the next function call to be recorded is executed normally, but is not recorded. For example:

sf_write_disable ( not_completed )

Note: Do not start a line with a $ before a variable. Patran recognizes lines that begin with $ as comment lines.

PCL and CustomizationInitializing the Session

38

> asm_create_patch_xyz ( arg1, arg2 )

In this example, if the value of not_completed is TRUE, then the call to asm_create_patch_xyz is not recorded.

Function calls used as arguments

Although it is sometimes convenient to use the return value from a function as an argument to another function, when using the > directive this should generally be avoided. For example, consider:

> funcx( funcy( x, y, z) )

If session file recording has not been disabled, both funcx and funcy are output. If one level is suppressed, then only funcx is recorded, (funcy recording is suppressed). Note also, that normally funcy gets recorded first, followed by funcx.

Undo support

In order to support the undo feature, applications should insure that all commands that can be written to a session file do not perform any database commits (uil_db_commit) either directly or indirectly (as a consequence of any command). The corresponding PCL code that handles the user interface is expected to perform the commit, passing a string that describes the operation that is about to take place.

Sample PCL Functions with > directive

The following PCL file contains three functions which demonstrate all of the available session file recording controls:

1 FUNCTION sftest2 STRING string1[256], string2[256], string3[256]34 string1 = “FIRST string”5 string2 = “The 2nd string”6 string3 = “This is string 3”78/* Write a line to the session file */9sf_write(“/* Written by ‘sf_write’ */”)1011/* Next function call records in session file */12> sub1 ( string1, string2 )1314/* Record Arg 1 of next func as variable NAME, not VALUE 15> sub1( $string3, string1 )1617/* Record Arg 2 of next func as variable NAME, not VALUE 18> sub2( string2, $string3 )1920/* Demonstrate how nested >’s act */21string3 = “String 3 assigned by sftest”22 sub2 (string2, string3)2324 /* Disable session file recording for the next line */25 sf_write_disable(TRUE)26> sub1 ($string3, string1)27 sf_force_write(“/* Written no matter what!”)2829/* test record rotation functionality */30 sf_rotation()31> ui_writec(“!Recorded only if record rotations is ON”)

39Chapter 2: The PATRAN Command Language (PCL) IntroductionInitializing the Session

32 END FUNCTION /* sftest */3334 FUNCTION sub1 (c, d)35 STRING c[256], d[256]36> UI_WRITEC (“SUB1: Arg1:%s - Arg2:%s\n”, c, d)37 END FUNCTION /* sub1 */3839 FUNCTION sub2 (e, f)40 STRING e[256], f[256]41> sub3 (e, f)42 f = “SUB2 set this string!”43 END FUNCTION /* sub2 */4445 FUNCTION sub3 (g, h)46 STRING g[256], h[256]47 sub3 (g, h)48> UI_WRITEC (“SUB3: Arg1:%s - Arg2:%s\n”, g, h)49 END FUNCTION /* sub3 */

Notes

1. Line 25 prevents line 26 from being recorded in the session file. Line 26 executes normally.

2. Line 30 prevents line 31 from being recorded in the session file if record rotations is off. The default condition is record rotations off. Line 31 always executes normally.

3. Line 36 never appears in the session file because function sub1() is always called from a line which contain the > directive.

4. Line 41 is recorded when function sub2() is called from line 22, but it is not recorded when function sub2 is called from line 18.

The following text is the session file created by the execution of the PCL function sftest() documented above.

1/# Session file recording started: 01/01/1991 00:00:00 2/* Written by ‘sf_write’ */ 3sub1( “FIRST string”, “The 2nd string” ) 4STRING string3[256] 5sub1( string3, “FIRST string” ) 6sub2( “The 2nd string”, string3 ) 7sub3( “The 2nd string”, “String 3 assigned by sftest” ) 8/* Written no matter what! ** 9/# Session file recording stopped: 05/01/1991 12:05:39

Lines 1 and 9 are created by the Session File init and exit functions. They are not passed from one session file to another when playing and recording at the same time.

Line 2 is recorded at execution of SFTEST line 9.

Line 3 is recorded at execution of SFTEST line 12.

Line 4 is recorded at execution of SFTEST line 15. Because this is the first use of argument ‘string3’ it is declared before it is used as an argument to the call.

Line 5 is also recorded at execution of SFTEST line 15. Note that the first arg is recorded as ‘string3’ rather than the value of ‘string3’ -- this is activated by the $ directive immediately preceding ‘string3’ on line 15.

PCL and CustomizationInitializing the Session

40

Line 6 is recorded at execution of SFTEST line 18. Note that the second argument is recorded as ‘string3’ rather than the value of ‘string3.’

Line 7 is recorded at execution of line 41 in function sub2. Since sub2 was executed without a > directive, > directives within sub2 are recorded.

Line 8 is recorded at execution of SFTEST line 27.

The following text is the output created by the execution of the PCL function sftest() documented above.

Output from the PCL function to the startup window:

1. SUB1: Arg1:FIRST string - Arg2:The 2nd string

2. SUB1: Arg1:This is string3 - Arg2:FIRST string

3. SUB3: Arg1:The 2nd string - Arg2:This is string 3

4. SUB3: Arg1:The 2nd string - Arg2:String 3 set by sftest

5. SUB1: Arg1:SUB2 set this string! - Arg2:FIRST string

6. /* Recorded only if record rotations is ON

Line 1 is printed from SUB1 when called from SFTEST line 12.

Line 2 is printed from SUB1 when called from SFTEST line 15.

Line 3 is printed from SUB3 when called from SUB2 line 41, which is called from SFTEST line 18.

Line 4 is printed from SUB3 when called from SUB2 line 41, which is called from SFTEST line 22.

Line 5 is printed from SUB1 when called from SFTEST line 26. Note that SUB1 is called, even though it is not recorded.

Line 6 is printed from SFTEST line 31, but the ui_write call is not recorded in the session file, because the default condition is NOT to record rotations, and the sf_rotation() call on line 30 indicates that line 31 is a rotation function.

The PCL Command Line Interpreter P3PCLCOMP

The executable p3pclcomp provides an interface to a PCL interpreter that can be executed from the command line of a UNIX shell or a Windows NT command processor.

The p3pclcomp executable functions exactly as the command line for Patran with two main differences. There is no graphics capability, and there is no access to databases. The runtime paths and libraries for p3pclcomp are also different, but this is simply because at start time, $P3_HOME/init.pcl is read by Patran and not by p3pclcomp.

Commands that are supported by p3pclcomp include:

!!input [all known options] !!compile [all known options] !!library [all known options] !!path [all known options]

and most PCL functions that do not deal with graphics or the database.

41Chapter 2: The PATRAN Command Language (PCL) IntroductionInitializing the Session

Possible uses of p3pclcomp include:

Test compiles of PCL function code to check for syntax errors.

Text execution of PCL functions that work without database or graphics, for example, file input and output functions.

The creation and manipulation of PCL function libraries or .plb files.

The p3pclcomp provides a good way to make libraries. A library named make_library.plb can be created using the following commands.

!!compile test.pcl into my_library.plb

The p3pclcomp executable can then be used with input from make_library.plb file.

$P3_HOME/bin/p3pclcomp < make_library.plb

The p3pclcomp executable can also be used to execute PCL commands provided through standard input, listing the results through standard output, allowing p3pclcomp to be used in script and batch files:

echo "!!LIBRARY LIST "make_library.plb | $P3_HOME/bin/p3pclcomp > make_library.lst

This command line will pass the PCL command "!!LIBRARY LIST make_library.plb" through the p3pclcomp executable. The p3pclcomp will create a list of all of the PCL functions included in the make_library.plb file to standard output. Standard output will then be redirected to the file "make_library.lst"

PCL and CustomizationInitializing the Session

42

Chapter 3: Basic FunctionsPCL and Customization

3 Basic Functions

Intrinsic Functions 6

Graphics Functions 130

PCL and CustomizationIntrinsic Functions

44

Intrinsic FunctionsPCL has an extensive library of intrinsic functions accessible at any time. Each function name is prefixed with a several letter mnemonic which specifies the category.

Most--but not all--PCL functions return a value. In the descriptions below, the definition of the return value is shown under the output parameters by using the name of the function as the variable name to be returned.

PCL intrinsic functions are more flexible than normal PCL functions when it comes to passing simple integers and reals. If an intrinsic function calls for a non-array input only integer or real value, pass either an integer or a real for that argument and PCL will convert automatically to the needed type.

Many PCL intrinsic functions are specific to the Patran environment and allow sophisticated control of the database and user interface. These PCL functions are documented elsewhere. The PCL functions documented here represent a core set of routines to perform many general operations such as math, string manipulation, and file input/output. The following documentation breaks down the intrinsic functions by categories.

Math FunctionsPCL contains a large number of intrinsic mathematical functions. Since the math functions are used so often, the prefix MTH_ is optional when referring to the Math Functions (unless otherwise specified in the documentation).

45Chapter 3: Basic FunctionsIntrinsic Functions

.

mth_sind ( angle )

Description:

Return trigonometric sine value of the argument specified in degrees.

Input:

REAL angle The angle in degrees for which to compute the sine

Output:

REAL <Return Value>

The sine value.

Error Conditions:

None.

mth_asind ( value )

Description:

Return angle in degrees which corresponds to the trigonometric sine contained in the argument.

Input:

REAL value The sine value for which to find the angle.

Output:

REAL <Return Value> The angle in degrees for the sine.

Error Conditions:

None.

mth_cosd ( angle )

Description:

Return trigonometric cosine value of the argument specified in degrees.

Input:

REAL angle The angle in degrees for which to compute the cosine.

Output:

REAL <Return Value> The cosine value.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

46

mth_acosd ( value )

Description:

Return angle in degrees which corresponds to the trigonometric cosine contained in the argument.

Input:

REAL value The cosine value for which to find the angle.

Output:

REAL <Return Value>

The angle in degrees for the cosine.

Error Conditions:

None.

mth_tand ( angle )

Description:

Return trigonometric tangent value of the argument specified in degrees.

Input:

REAL angle The angle in degrees for which to compute the tangent.

Output:

REAL <Return Value> The tangent value.

Error Conditions:

None.

mth_atand ( value )

Description:

Return angle in degrees which corresponds to the trigonometric tangent contained in the argument.

Input:

REAL value The tangent value for which to find the angle.

Output:

REAL <Return Value> The angle in degrees for the tangent.

Error Conditions:

None.

47Chapter 3: Basic FunctionsIntrinsic Functions

mth_atan2d ( y, x )

Description:

Return angle in degrees which corresponds to the trigonometric tangent represented by the specified x and y components.

Input:

REAL y The y component of the tangent.

REAL x The x component of the tangent.

Output:

REAL <Return Value> The angle in degrees for the tangent.

Error Conditions:

None.

mth_sinr ( angle )

Description:

Return trigonometric sine value of the argument specified in radians.

Input:

REAL angle The angle in radians for which to compute the sine.

Output:

REAL <Return Value> The sine value.

Error Conditions:

None.

mth_asinr ( value )

Description:

Return angle in radians which corresponds to the trigonometric sine contained in the argument.

Input:

REAL value The sine value for which to find the angle.

Output:

REAL <Return Value> The angle in radians for the sine.

PCL and CustomizationIntrinsic Functions

48

Error Conditions:

None.

49Chapter 3: Basic FunctionsIntrinsic Functions

mth_cosr ( angle )

Description:

Return trigonometric cosine value of the argument specified in radians.

Input:

REAL angle The angle in radians for which to compute the cosine.

Output:

REAL <Return Value>

The cosine value.

Error Conditions:

None.

mth_acosr ( value )

Description:

Return angle in radians which corresponds to the trigonometric cosine contained in the argument.

Input:

REAL value The cosine value for which to find the angle.

Output:

REAL <Return Value> The angle in radians for the cosine.

Error Conditions:

None.

mth_tanr ( angle )

Description:

Return trigonometric tangent value of the argument specified in radians.

Input:

REAL angle The angle in radians for which to compute the tangent.

Output:

REAL <Return Value> The tangent value.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

50

mth_atanr ( value )

Description:

Return angle in radians which corresponds to the trigonometric tangent contained in the argument.

Input:

REAL value The tangent value for which to find the angle.

Output:

REAL <Return Value>

The angle in radians for the tangent.

Error Conditions:

None.

mth_atan2r ( y, x )

Description:

Return angle in degrees which corresponds to the trigonometric tangent represented by the specified x and y components.

Input:

REAL y The y component of the tangent.

REAL x The x component of the tangent.

Output:

REAL <Return Value>

The angle in radians for the tangent.

Error Conditions:

None.

mth_sqrt ( value )

Description:

Return square root of the argument.

Input:

REAL value The value for which to obtain the square root.

Output:

51Chapter 3: Basic FunctionsIntrinsic Functions

REAL <Return Value>

The square root.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

52

mth_ln ( value )

Description:

Return natural logarithm of the argument.

Input:

REAL value The value for which to obtain the natural logarithm.

Output:

REAL <Return Value>

The natural logarithm.

Error Conditions:

None.

mth_log ( value )

Description:

Return common logarithm of the argument.

Input:

REAL value The value for which to obtain the common logarithm.

Output:

REAL <Return Value>

The common logarithm.

Error Conditions:

None.

mth_exp ( value )

Description:

Return power function of natural logarithm base, e to the x power.

Input:

REAL value The raising power

Output:

REAL <Return Value>

The result of the power of the input argument.

53Chapter 3: Basic FunctionsIntrinsic Functions

Error Conditions:

None.

mth_abs ( value )

Description:

Return the absolute value of the input argument.

Input:

NUMERIC value The value to get the absolute value of, integer or real.

Output:

NUMERIC <Return Value> The absolute value of the input argument. The datatype will match that of the input argument.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

54

mth_sign ( value )

Description:

Return a sign, -1, 0, or 1 for the input argument.

Input:

REAL value The value of which to get the sign.

Output:

INTEGER <Return Value> The sign value of the input argument, -1 for a negative argument, 0 for zero, and 1 for a positive argument.

Error Conditions:

None.

mth_nint ( value )

Description:

Return the nearest integer value for the input argument.

Input:

REAL value The value for which to obtain the nearest integer.

Output:

INTEGER <Return Value> The nearest integer value, rounding off the input argument.

Error Conditions:

None.

55Chapter 3: Basic FunctionsIntrinsic Functions

mth_max ( val1, val2, ... )

Description:

Return the largest value of a set of input values.

Input:

NUMERIC valnnn Input values to check, INTEGER or REAL. There may be one or more input values specified.

Output:

NUMERIC <Return Value>

The largest value of the input arguments. If all input arguments are INTEGER, then this result is also INTEGER. Otherwise, this result is REAL.

Error Conditions:

None.

mth_min ( val1, val2, ... )

Description:

Return the smallest value of a set of input values.

Input:

NUMERIC valnnn Input values to check, INTEGER or REAL. There may be one or more input values specified.

Output:

NUMERIC <Return Value>

The smallest value of the input arguments. If all input arguments are INTEGER, then this result is also INTEGER. Otherwise, this result is REAL.

Error Conditions:

None.

mth_mod ( value, divisor )

Description:

Return remainder of a number after dividing by a divisor.

Input:

NUMERIC value The value to be divided by the divisor.

PCL and CustomizationIntrinsic Functions

56

Example:

mth_round( 12.34567, 2 ) yields 12.35mth_round( 12.34567, 0 ) yields 12.0mth_round( 12.3457, -1 ) yields 10.0mth_round( 3.3715, 1 ) yields 3.4000001

NUMERIC divisor The divisor value.

Output:

NUMERIC <Return Value> The remainder after dividing value by the divisor an integral number of times. If both input arguments are INTEGER, then this result is also INTEGER. Otherwise, this result is REAL.

Error Conditions:

None.

mth_round ( value, ndecimals )

Description:

Return a value rounded to a specified number of decimals.

Input:

REAL value The value to be rounded.

INTEGER ndecimals Number of decimals.

Output:

REAL <Return Value> The input value rounded to the specified number of decimals. Note that with round-off errors, the value may not get exactly rounded.

Error Conditions:

None.

57Chapter 3: Basic FunctionsIntrinsic Functions

mth_sort ( array, dupflag, nleft )

Description:

This function will sort an array of integers, optionally removing all duplicate values.

Input:

INTEGER() array( ) This value specifies the items to be sorted. This value is used as both an input and an output. The original values passed into the function will be destroyed.

LOGICAL dupflag This value specifies, when set to TRUE, that duplicate sorted values will be removed. When this value is set to FALSE, duplicate values will not be removed.

Output:

INTEGER() array( ) This value returns the sorted items. This value is used as both an input and an output to this function, allowing the original values to be destroyed.

INTEGER nleft Number of integers that are in the final sort. Values in the array past this point are undefined. If DUPFLAG is FALSE then this will be the same as the size of the array.

Error Conditions:

None.

mth_sort_column ( matrix, column, ascend )

Description:

Sort a two dimensional integer or real array by one of its columns. The mth_ prefix is required for this routine.

Input:

NUMERIC() matrix Matrix of values to sort.

INTEGER column Column number within the matrix to sort by. Note that this column number starts from 1 even if the matrix is not based at a lowest dimension of 1.

LOGICAL ascend TRUE for an ascending order sort, FALSE for a descending order sort

Output:

NUMERIC() <Return Value> Matrix is sorted in place.

PCL and CustomizationIntrinsic Functions

58

Error Conditions:

None.

mth_sort_row ( matrix, row, ascend )

Description:

Sort a two dimensional integer or real array by one of its columns. The mth_ prefix is required for this routine.

Input:

NUMERIC() matrix Matrix of values to sort.

INTEGER row Row number within the matrix to sort by. Note that this row number starts from 1 even if the matrix is not based at a lowest dimension of 1.

LOGICAL ascend TRUE for an ascending order sort, FALSE for a descending order sort

Output:

NUMERIC() <Return Value> Matrix is sorted in place.

Error Conditions:

None.

59Chapter 3: Basic FunctionsIntrinsic Functions

Example:

Some examples of using PCL math functions:

max_shear = SQRT( ( sigma_x - sigma_y ) / 2.0)**2 + shear**2 )eigenroot = n * pi / length y = SINR( eigenroot * x ) * ( a * COSR( k * t ) + @ b * SINR( k * t ))thru_the_thickness = NINT( thickness/edge)

Note that the trigonometric functions operate on either degrees or radians depending on the last character (D for degrees and R for radians) in the function name. It is a simple matter to write a set of functions which operate in the manner preferred:

FUNCTION SIN( x )/* ABSTRACT: Return the SIN of x, where x is in degrees*/REAL xRETURN MTH_SIND( x ) END FUNCTION

String FunctionsThe String functions test, convert, and manipulate PCL strings. String functions are useful for user interface applications and parsing.

mth_array_search ( array, look4, sorted )

Description:

Search an integer array for a value. The mth_ prefix is required for this routine.

Input:

INTEGER() array Integer array of values to search.

INTEGER look4 Value to find in the array.

LOGICAL sorted TRUE if input array is already in ascending sort order. If FALSE then a complete search of the array will be necessary.

Output:

INTEGER <Return Value> Position in the array from 1 to n or zero if the value was not found in the array.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

60

.

Example:

string line[40]line = “ ”str_length( line ) is now 0line = line // “testing”str_length( line ) is now 7

str_length ( string )

Description:

Return the current length of a PCL string.

Input:

STRING string The string for which to return the length.

Output:

INTEGER <Return Value> The current length of the string. Remember that PCL strings are variable length.

Error Conditions:

None.

61Chapter 3: Basic FunctionsIntrinsic Functions

str_maxlength ( string )

Description:

Return the maximum length of a PCL string.

Input:

STRING string The string for which to return the maximum length.

Output:

INTEGER <Return Value> The maximum length of the string. For a virtual string, this returns the current maximum length. For an unallocated virtual string, the result is currently undefined.

Error Conditions:

None.

str_to_lower ( string )

Description:

Return a copy of the input string with all characters converted to lower case letters.

Input:

STRING string The string to convert to lower case. The input string argument is not modified by this call.

Output:

STRING <Return Value> The input string converted to lower case.

Error Conditions:

None.

str_to_upper ( string )

Description:

Return a copy of the input string with all characters converted to upper case letters.

Input:

STRING string The string to convert to upper case. The input string argument is not modified by this call.

Output:

STRING <Return Value> The input string converted to upper case.

PCL and CustomizationIntrinsic Functions

62

Error Conditions:

None.

63Chapter 3: Basic FunctionsIntrinsic Functions

str_strip_lead ( string )

Description:

Return a copy of the input string with leading blank characters removed.

Input:

STRING string The string to strip leading blanks from. The input string argument is not modified by this call.

Output:

STRING <Return Value>

The input string without any leading blanks.

Error Conditions:

None.

str_strip_trail ( string )

Description:

Return a copy of the input string with trailing blank characters removed.

Input:

STRING string The string to strip trailing blanks from. The input string argument is not modified by this call.

Output:

STRING <Return Value> The input string without any trailing blanks.

Error Conditions:

None.

str_substr ( string, position, length )

Description:

Return a portion of the input string from the specified position for the specified length.

Input:

STRING string The string to extract the substring from. The input string argument is not modified by this call.

INTEGER position Starting position in the string where 1 is the first position.

PCL and CustomizationIntrinsic Functions

64

INTEGER length Number of characters to extract. If less than or equal to zero, then an empty string is extracted. If more characters are requested than are available in the string from the specified position, only the available characters will be returned.

Output:

STRING <Return Value> The extracted substring of the input string.

Error Conditions:

None.

65Chapter 3: Basic FunctionsIntrinsic Functions

str_assign ( mystring, position, length, substring )

Description:

This function will replace a portion of a string with a another string.

Input:

STRING mystring[ ] This value specifies the original string to be modified. This value is used as both an input and output value. The original string will not be preserved.

INTEGER position This value specifies the starting place in the input value mystring where the substitution will take place. The first character in the string is at position 1.

INTEGER length This value specifies the number of characters to be replaced.

STRING substring[ ] This value specifies the string that will be substituted into the input value mystring.

Output:

STRING mystring[ ] This value returns the original input value mystring with a portion of the string being replaced with the input value substring. This value is used as both an input and an output value. The original input value mystring will be overwritten.

Error Conditions:

None.

str_index ( string1, string2 )

Description:

Return the position where a string is found within another string.

Input:

STRING string1 The string within which to find an occurrence of the second string.

STRING string2 The string to look for within the first string.

Output:

INTEGER <Return Value> The position where string2 was found within string1 where 1 is the first position. Zero is returned if the string was not found.

Error Conditions:

None.

str_find_match ( string, chars )

PCL and CustomizationIntrinsic Functions

66

Description:

Return the position where any of a set of characters is found within another string.

Input:

STRING string The string within which to find an occurrence of any character in the second string.

STRING chars A list of characters to search for within the first string.

Output:

INTEGER <Return Value> The position where one of the characters was found within the string where 1 is the first position. Zero is returned if the non of the characters occurred in the string.

Error Conditions:

None.

str_find_nomatch ( string, chars )

Description:

Return the position where any character other than those in a set of characters is found within another string.

Input:

STRING string The string within which to find an occurrence of any character not in the second string.

STRING chars A list of characters not to search for within the first string.

Output:

INTEGER <Return Value>

The position where a character was found within the string which is not in the chars string, where 1 is the first position. Zero is returned if the string is only made up of characters within the chars string.

Error Conditions:

None.

67Chapter 3: Basic FunctionsIntrinsic Functions

str_equal ( string1, string2 )

Description:

Check for an exact match between two strings including exact character case and trailing blanks. Normally the standard PCL == operator would be used which ignores character case and trailing blanks.

Input:

STRING string1 First string to compare.

STRING string2 Second string to compare.

Output:

LOGICAL <Return Value> TRUE if strings match exactly, FALSE otherwise.

Error Conditions:

None.

str_to_integer ( string [, stat] )

Description:

Convert a string to an integer.

Input:

STRING string String to convert to integer value.

Output:

INTEGER stat Optional status, zero for success, or the position within the input string which contains the first invalid character.

INTEGER <Return Value> Integer value from conversion. Usually zero if the conversion fails.

Error Conditions:

None.

str_to_real ( string [, stat] )

Description:

Convert a string to a real.

Input:

STRING string String to convert to real value.

PCL and CustomizationIntrinsic Functions

68

Output:

INTEGER stat Optional status, zero for success, or the position within the input string which contains the first invalid character.

REAL <Return Value>

Real value from conversion. Usually zero if the conversion fails.

Error Conditions:

None.

69Chapter 3: Basic FunctionsIntrinsic Functions

str_to_logical ( string )

Description:

Convert a string to a logical.

Input:

STRING string String to convert to logical value.

Output:

LOGICAL <Return Value> Logical value from conversion. This will be TRUE if the first non-blank character of the string is a T, Y, or 1, regardless of case. Otherwise, the value will be FALSE.

Error Conditions:

None.

str_from_integer ( ival )

Description:

Convert an integer to a string.

Input:

INTEGER ival Integer to convert to string representation.

Output:

STRING <Return Value> String that represents the integer value.

Error Conditions:

None.

str_from_real ( rval )

Description:

Convert a real to a string.

Input:

REAL rval Real to convert to string representation.

Output:

STRING <Return Value> String that represents the real value. The string may end up being in decimal or in exponential notation.

PCL and CustomizationIntrinsic Functions

70

Error Conditions:

None.

71Chapter 3: Basic FunctionsIntrinsic Functions

str_from_logical ( lval )

Description:

Convert a logical to a string.

Input:

LOGICAL lval Logical to convert to string representation.

Output:

STRING <Return Value> String that represents the logical value. The string will be either “TRUE” or “FALSE”.

Error Conditions:

None.

str_datatype ( string )

Description:

Attempt to decipher the type of representation in a string.

Input:

STRING string String to decipher.

Output:

STRING <Return Value>

String representing datatype. Either “INTEGER,” “REAL,” “LOGICAL,” or “STRING.”

Error Conditions:

None.

str_formatc ( string, format, args... )

Description:

Perform a limited C style format conversion into a string. This routine is obsolete but exists for special purposes. Use STRING_WRITE instead.

Input:

STRING string Input string.

STRING format C Format string with handling of \n, \r, \t, %d, %f, %e, %g, %x, %s, %c, and %%.

PCL and CustomizationIntrinsic Functions

72

unknown args Appropriate datatype for format specifiers. Incorrect specifications may cause a crash.

Output:

STRING <Return Value>

Resultant string from processing format.

Error Conditions:

None.

73Chapter 3: Basic FunctionsIntrinsic Functions

str_formatf ( string, format, args... )

Description:

Perform a limited C style format conversion into a string. This routine is obsolete but exists for special purposes. Use STRING_WRITE instead.

Input:

STRING string Input string.

STRING format FORTRAN format string with handling of /, 'string', X, I, F, E, G, and A formats.

unknown args Appropriate datatype for format specifiers. Incorrect specifications may cause a crash. Array arguments are allowed.

Output:

STRING <Return Value> Resultant string from processing format.

Error Conditions:

None.

str_token ( string, delim, num [, compress ] )

Function;

This function will extract a token or a sequence of characters marked off by a delimiting character or a set of characters from a string.

Input:

STRING string[ ] This value specifies the source string from which tokens will be extracted.

STRING delim[1] This value specifies the single character token delimiter.

INTEGER num This value specifies the ordinal of the token to return from the input value string. This value must be set to at least one. If there are five tokens in the input value string, setting this value to three will cause this function to return the third token.

LOGICAL compress This value specifies, when set to TRUE, that empty tokens will be ignored. When this value is set to FALSE, empty tokens caused by multiple delimiters will not be ignored. This value is optional and has a default value of FALSE.

Output:

PCL and CustomizationIntrinsic Functions

74

STRING <Return Value>

This function returns the token extracted from the input value string. Leading and trailing spaces will be deleted if the delimiter character is not a space.

Error Conditions:

None.

75Chapter 3: Basic FunctionsIntrinsic Functions

str_abbreviation ( input, abbrev, minmatch )

Description:

Check if a string is a valid abbreviation of another string.

Input:

STRING input Input string to check as a valid abbreviation.

STRING abbrev String to check input string against.

INTEGER minmatch Minimum number of characters that must match for the abbreviation to be considered valid.

Output:

LOGICAL <Return Value> TRUE if abbreviation is valid, FALSE otherwise.

Error Conditions:

None.

str_to_ascii ( string [, position ] )

Description:

Return the ASCII integer value for a character within a string.

Input:

STRING string String which contains character for which to return ASCII value.

INTEGER position Optional position of the character. Default is one for the first character in the string.

Output:

INTEGER <Return Value> ASCII integer value or zero if string too small.

Error Conditions:

None.

str_from_ascii ( ascii )

Description:

Return the character represented by an ASCII value.

Input:

INTEGER ascii Integer ASCII value to convert to a character.

PCL and CustomizationIntrinsic Functions

76

Output:

STRING <Return Value>

Single character represented by ASCII value.

Error Conditions:

None.

77Chapter 3: Basic FunctionsIntrinsic Functions

str_pattern ( string, pattern, options )

Description:

Compare a string against a pattern and return match results.

Input:

STRING string String to compare against the pattern.

STRING pattern Pattern to check against with wildcards as defined by the options parameter.

INTEGER options 1 = Unix file type compare where “*” matches any number of characters and “?” matches a single character. 2= VMS file type compare where “*” matches any number of characters other than a period and “%” matches any single character. 0 = use 1 for unix systems and 2 for VMS systems.

Output:

LOGICAL <Return Value> TRUE if the pattern match succeeds. FALSE otherwise.

Error Conditions:

None.

string_newline_count (string, count)

Description:

This function counts the number of newline characters ( \n ) in a string.

Input:

STRING string[] This value specifies the string to look for newline characters.

Output:

INTEGER count The number of newline characters in the string.

Error Conditions:

None.

string_newline_position (string, position)

Description:

This function returns the newline character ( \n ) positions in a string.

PCL and CustomizationIntrinsic Functions

78

Block I/O FunctionsThe block I/O package gives access to operating system files in a very efficient manner. The files that block I/O operate on are viewed as fixed record files of a specific block size which is usually some multiple of the file system's disk block size. The block I/O package is often cumbersome to use and is normally not called directly by an application. The Record, Stream, and Virtual I/O utilities all use the Block I/O package. The format of a block I/O file is an MSC proprietary format. A Fortran or other application created file using the block I/O package cannot be accessed.

Input:

STRING string[] This value specifies the string to look for newline characters.

Output:

INTEGER position[] The newline character positions in the string.

Error Conditions:

None.

79Chapter 3: Basic FunctionsIntrinsic Functions

block_open ( filename, options, nwpb, chan, fsize )

Description:

Open a binary block oriented proprietary format file for access.

Input:

STRING filename Operating system name of file.

STRING options File open flags. Some set of R, W, N, O, P, and V. See File Utility Functions, 81.

INTEGER nwpb Number of words per block to use for the file.

Output:

INTEGER chan Channel number to use for subsequent block I/O operations.

INTEGER fsize Current file size in bytes if determinable.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

block_close ( chan, options )

Function;

Close a file that was opened for block I/O.

Input:

INTEGER chan Channel from a previous block_open call.

STRING options Close flags. If “D” is specified, then the file will be deleted after closing.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

block_read ( chan, blknum, nwords, buffer, numread )

Description:

Read a block or blocks from a file opened for block oriented I/O.

PCL and CustomizationIntrinsic Functions

80

Input:

INTEGER chan Channel from a previous block_open call.

INTEGER blknum Block number to read from the file where zero is the first block.

INTEGER nwords Number of words to be read. Normally this is a multiple of the number of words per block.

Output:

INTEGER() buffer Buffer area into which data is read. More than NWORDS of data may be returned if NWORDS is not a multiple of the number of words per block.

INTEGER numread Number of words actually read.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

81Chapter 3: Basic FunctionsIntrinsic Functions

File Utility FunctionsThe file utility functions provide access to the operating system file structure. These functions can look up, delete, and copy files. There are also routines to help parse file specifications into component pieces. The file utility also maintains a path list which is a set of directories that is often used for searching for a file. The PCL !!PATH list is built on top of the file utility path routines.

block_write ( chan, blknum, nwords, buffer )

Description:

Write a block or blocks to a file opened for block oriented I/O.

Input:

INTEGER chan Channel from a previous block_open call.

INTEGER blknum Block number to write from the file where zero is the first block.

INTEGER nwords Number of words to write.

INTEGER() buffer Buffer area from which data is written.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

block_get_name ( chan, fspec, lenfspec )

Description:

Get the operating system filename of a file open for block oriented I/O.

Input:

INTEGER chan Channel from a previous block_open call.

Output:

STRING fspec File specification of open file.

INTEGER lenfspec Length of name returned in FSPEC.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

82

Several of the file utilities and also the text, record, stream, and block I/O utility open and close routines request an option string for how to find, open, or delete a file. The option string is a set of characters, each of which specifies an option. The order and case of the characters does not matter. Below are the options that can be specified. Many of these options only make sense for certain operations.

The file and I/O utilities also have a limited amount of support for file version numbers. For UNIX and Windows NT systems, a version number is specified by appending a period and a number, one or greater, to the filename. If the version number is less than 10, a leading zero is added to provide better sorting for UIMS and UNIX file sorting. The version utilities will recognize a versioned file with or without the leading zero.

An example of an open options specification for opening an already existing file for read access only is given below.

status = text_open (filename, “OR”, 0, 0)

N Create a new file.

O Open an existing file. If N is given also, the file will be created if it does not already exist.

R Open the file for read access.

W Open the file for write access. If R is given also, the file is opened for both reading and writing.

A Open the file for appending at the end of the file (text_open only).

V Use version numbers for searching for or creating the file.

P Search the file utilities path to find the file.

L Lock the file for exclusive access (not yet implemented).

S Use scratch directory (file_unique_name only).

D Delete the file after close (close routines only).

83Chapter 3: Basic FunctionsIntrinsic Functions

file_add_path ( where, newpath )

Description:

Add a path to the path list.

Input:

INTEGER where Position to insert path. Zero inserts at the start (after current directory), 1 inserts after the first path, and so on.

STRING newpath New directory specification to add to the path list.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

file_append_version ( version, nzeros, fspec )

Description:

Append a version number to a file specification only if there is not already a version number in the specification. This is a utility routine which will not normally be called by the user. Use file_build_fname instead.

Input:

INTEGER version Version number or zero for no version.

INTEGER nzeros Number of leading zeros to add to version number.

STRING fspec Original file specification.

Output:

STRING fspec Modified file specification.

Error Conditions:

None.

file_build_fname ( dir, base, ext, options, filespec )

Description:

Create a full file specification given its component parts.

Input:

STRING dir Directory portion of file specification.

PCL and CustomizationIntrinsic Functions

84

STRING base Base filename portion.

STRING ext Extension for filename.

STRING options Options of N, O, P, or V. See File Utility Functions, 81.

Output:

STRING filespec Resultant file specification.

Error Conditions:

None.

file_create_directory ( dirname, access )

Description:

Create a directory.

Input:

STRING dirname Path to directory to create. If multiple directories need to be created for the path, they will be.

INTEGER access Unix style access permissions for new directories. This value is normally an octal number which is hard to represent in PCL. The easiest way to specify a protection such as 755 is to use the expression (7*64+5*8+5). Using zero gives no access to the directory, using 7*64+7*8+7 gives full access to the directory.

Output:

INTEGER <Return Value> Zero for success. If the directory already exists, the call is considered successful.

Error Conditions:

None.

85Chapter 3: Basic FunctionsIntrinsic Functions

file_delete ( filespec )

Description:

Delete an operating system file.

Input:

STRING filespec File to delete. The path will not be searched for the file.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

file_delete_path ( oldpath )

Description:

Remove a path from the path list.

Input:

STRING oldpath Directory specification to remove from the path.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

file_executable ( filespec )

Description:

Return whether or not a specified file has execute permission.

Input:

STRING filespec File specification to check.

Output:

LOGICAL <Return Value>

True for execute permission, False if no execute permission.

Error Conditions:

PCL and CustomizationIntrinsic Functions

86

None.

Side Effects:

Warning. If the operating system can’t determine execute permission, this function will normally return True.

87Chapter 3: Basic FunctionsIntrinsic Functions

file_exists ( filespec, options )

Description:

Check to see if a file exists.

Input:

STRING filespec File to look up.

STRING options Option flags of P or V. See File Utility Functions, 81.

Output:

LOGICAL <Return Value> TRUE if file exists. FALSE if file could not be found.

Error Conditions:

None.

file_exists_local ( filespec )

Description:;

Check to see if a file exists in the current directory. Normally, the “file_exists” function should be used with empty options instead of this routine.

Input:

STRING filespec File to look up.

Output:

LOGICAL <Return Value>

TRUE if file exists. FALSE if file could not be found.

Error Conditions:

None.

file_exists_version ( filespec, version, nzeros )

Description:

Find the highest version of a file in the current directory.

Input:

STRING filespec File to look up without version specified.

Output:

PCL and CustomizationIntrinsic Functions

88

INTEGER version Version number found or zero if no versions exists but the file exists without any version.

INTEGER nzeros Number of leading zeros that were found in the version number.

LOGICAL <Return Value>

TRUE if file exists. FALSE if file could not be found.

Error Conditions:

None.

89Chapter 3: Basic FunctionsIntrinsic Functions

file_expand_home ( inspec, outspec )

Description:

Expand any “~” home directory syntax in the file specification.

Input:

STRING inspec Input file specification.

Output:

STRING outspec File specification with expanded home syntax.

Error Conditions:

None.

file_get_bfname ( filespec, basename )

Description:

Extract the base filename given a file specification (without versions).

Input:

STRING filespec Input file specification.

Output:

STRING basename Base filename.

Error Conditions:

None.

file_get_dfname ( filespec, directory )

Description:

Extract the directory specification given a file specification.

Input:

STRING filespec Input file specification.

Output:

STRING directory Directory specification.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

90

file_get_efname ( filespec, extension )

Description:

Extract the extension specification given a file specification (without versions).

Input:

STRING filespec Input file specification.

Output:

STRING extension Extension specification.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

file_get_filespec ( inspec, options, outspec )

Description:

Get a file specification that matches the specified input specification and options.

Input:

STRING inspec Input file specification.

STRING options Option string containing any of N, O, P, or V. See File Utility Functions, 81.

Output:

STRING outspec Output file specification.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

file_get_next_path ( ipath, path )

Description:

Iteratively retrieve entries from the path list.

Input:

91Chapter 3: Basic FunctionsIntrinsic Functions

INTEGER ipath Set to zero on first call. Pass return result back in on subsequent calls.

Output:

STRING path Next entry from the path list. The current directory path is returned as an empty string.

INTEGER <Return Value> Minus one if no more paths left. Otherwise use this value for the next call to file_get_next_path.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

92

file_get_p3_home ( path )

Description:

Return directory path for Patran “home” directory.

Input:

None.

Output:

STRING path Path to Patran “home” directory.

INTEGER <Return Value> Status, zero for success.

Error Conditions:

None.

file_init_path ( option )

Description:

Initialize the path list for use.

Input:

INTEGER option Zero to initialize if not already done. One to clear all entries from the path. Two to reset the path back to the initial default path setting.

Output:

None.

Error Conditions:

None.

file_list_end ( chan )

Description:

Iteratively retrieve entries from the path list.

Input:

INTEGER chan Value from file_list_start.

Output:

INTEGER <Return Value>

Status, zero for success, else error code.

93Chapter 3: Basic FunctionsIntrinsic Functions

Example:

INTEGER status, chanSTRING fname [256]status = file_list_start ( “/tmp”, “patran.ses.*”, chan )IF ( status == 0 ) THENWHILE ( file_list_next ( chan, fname ) == 0 )xf_write_comment ( fname )END WHILEfile_list_end ( chan )END IF

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

94

file_list_next ( chan, fname )

Description:

Iteratively retrieve entries from the directory using the optional filter specified in file_list_start.

Input:

INTEGER chan Value from file_list_start that indicates the directory and filter..

Output:

STRING fname The next file in the indicated directory that matches the specified filter.

INTEGER <Return Value> Status, zero for success, -1 for end of list, else error code.

Error Conditions:

None.

file_list_start ( directory, filter, chan )

Description:

Initialize a file directory search for files matching a pattern. This routine initializes the search, file_list_next gets each name, and file_list_end cleans up.

Input:

STRING directory Name of directory to search. A “.” will cause the current directory to be searched.

STRING filter File name qualifier. Only * and ? are guaranteed to work.

Output:

INTEGER chan Return value to use on subsequent calls to file_list_next and file_list_end.

INTEGER <Return Value> Status, zero for success, else error code.

Error Conditions:

None.

Side Effects:

Memory. Be sure to call file_list_end to match file_list_start or memory structures may not be freed.

file_readable ( filespec )

95Chapter 3: Basic FunctionsIntrinsic Functions

Description:

Check if read access is possible to a file.

Input:

STRING filespec File to check for read access.

Output:

LOGICAL <Return Value>

TRUE if reading is possible, otherwise FALSE.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

96

file_writeable ( filespec )

Description:

Check if write access is possible to a file.

Input:

STRING filespec File to check for write access.

Output:

LOGICAL <Return Value> TRUE if writing is possible, otherwise FALSE.

Error Conditions:

None.

file_unique_name ( prefix, options, outspec )

Description:

Generate a unique name for a file (usually a scratch work file).

Input:

STRING prefix Prefix string for file, may be empty.

STRING options Option “S” for create in temp directory, or empty for create in current directory.

Output:

STRING outspec Output file specification.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

file_copy ( source, dest )

Description:

Copy an operating system file.

Input:

STRING source Name of existing source file.

STRING dest Name of new destination file which must not exist.

97Chapter 3: Basic FunctionsIntrinsic Functions

Record I/O Utility FunctionsThe record input/output package provides a set of routines to read and write files consisting of complex records of variable length mixed data types. Integers, logicals, reals, strings, and 1, 4, or 8 bit integers are all supported. Record I/O files are self defining with the data in the file specifying the datatypes and lengths of the data in the file. This means that a Record I/O file can be processed by a program which does not know the contents of the file, and makes it easy to expand the capabilities of an application without obsoleting existing files. The Record I/O package is built on top of the Stream I/O package.

Each record is defined as having a typecode followed by any combination of datatypes. A typecode is a positive integer that is defined by the application which usually denotes what kind of data is represented by the record. An example record might have a typecode of 100 followed by 3 integers, 100 reals, 2 more integers, 20 characters, and a logical. When reading in a record, the application can query the next datatype and data count in the record.

Since the Record I/O package is built on top of the Stream I/O package, the creation and modification dates of the file are retained. The file also has a file type code and a character description. The performance of the Record I/O should be good since at the bottom layer buffered block I/O is performed.

Generally, to create a Record I/O file, first call record_open_new to create the file. Next, start a new record with record_begin_write passing the typecode for the record. Then call record_write_rechead passing the datatype and count for the next field in the record. Then call the appropriate record_write_xxx routine for the datatype that is being written. Repeat the record_write_rechead and record_write_xxx

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

file_query_remote ( filename )

Description:

Determine whether or not a file resides on a remote file system.

Input:

STRING filename File to check.

Output:

INTEGER <Return Value> Zero for file is remote, otherwise message code for file local or does not exist.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

98

calls for each field in the record, and then call record_end_rw to terminate the record. Continue writing records as desired, and call record_close when with the file. For several simple record types, there are routines of the name record_write_rec_xxx which will do much of the work automatically.

To read a Record I/O file, first call record_open_old to open the file, then read the next record header with record_begin_read which will return the typecode of the record. Now call record_read_rechead which returns the datatype and count of the next field in the record followed by a call the appropriate record_read_xxx routine to read the data. Close the file with record_close when done.

99Chapter 3: Basic FunctionsIntrinsic Functions

record_open_new ( filename, options, filecode, description, chan )

Description:

Create and open a new record I/O file.

Input:

STRING filename Name of file to open.

STRING options Open options of R, W, P, or V. See File Utility Functions, 81.

INTEGER filecode Integer value for the filetype of the new file. Ideally this should be a unique number for each kind of file that is created.

STRING description A informational text description of the file.

Output:

INTEGER chan Value to use for subsequent operations to this file.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

record_open_old ( filename, options, chan, filecode, description )

Description:

Open an existing record I/O file.

Input:

STRING filename Name of file to open.

STRING options Open options of R, W, P, or V. See File Utility Functions, 81.

Output:

INTEGER chan Value to use for subsequent operations to this file.

INTEGER filecode Integer value that represents kind of file and is set by the record_open_new routine.

STRING description Description of the file.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

100

record_close ( chan, options )

Description:

Close a file opened for record I/O.

Input:

INTEGER chan Channel from the record I/O open routine.

STRING options Close options. Either “D” to delete the file after close or an empty string.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

record_get_name ( chan, fspec, lenfspec )

Description:

Return the file specification for an open record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

Output:

STRING fspec Filename of open record I/O file.

INTEGER lenfspec Length of the file specification.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

record_writerec_chars ( chan, typecode, count, buffer )

Description:

Write a record containing only character data to the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER typecode Typecode for the record.

INTEGER count Number of characters to write from the string.

CSTRING buffer String to write to record file.

101Chapter 3: Basic FunctionsIntrinsic Functions

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

102

record_writerec_intchr ( chan, typecode, icount, ibuffer, ccount, cbuffer )

Description:

Write a record containing only integer and character data to the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER typecode Typecode for the record.

INTEGER icount Number of integers to write to the record.

INTEGER() ibuffer Integer data to write.

INTEGER ccount Number of characters to write from the string.

CSTRING cbuffer String to write to record file.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

record_writerec_ints ( chan, typecode, count, buffer )

Description:

Write a record containing only integer data to the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER typecode Typecode for the record.

INTEGER count Number of integers to write to the record.

INTEGER() buffer Integer data to write.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

record_writerec_reals ( chan, typecode, count, buffer )

103Chapter 3: Basic FunctionsIntrinsic Functions

Description:

Write a record containing only integer data to the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER typecode Typecode for the record.

INTEGER count Number of reals to write to the record.

REAL buffer() Real data to write.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

104

record_begin_write ( chan, typecode )

Description:

Start the writing of a complex record in the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER typecode Typecode for the record.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

record_begin_read ( chan, typecode )

Description:

Start the reading of a record from the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

Output:

INTEGER typecode Typecode for the record. Will be -1 for the end of the file.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

record_end_rw ( chan )

Description:

Complete the read or complex write of a record in the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

Output:

105Chapter 3: Basic FunctionsIntrinsic Functions

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

106

record_write_rechead ( chan, format, count )

Description:

Start the next field in writing a complex record to the Record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER format Datatype that will be written. Types defined are: 1=integer, 2=real, 3=char, 4=double real (not from PCL), 5=half integer, 6=byte integer, 7=4bit integer, 8=1bit integer, 9=logical, 10=pointer.

INTEGER count Number of items of the specified format that will make up the data field.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

record_read_rechead ( chan, format, count )

Description:

Start the read of the next field from the current record of the Record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

Output:

INTEGER format Datatype that is available next. Types defined are: 1=integer, 2=real, 3=char, 4=double real (not from PCL), 5=half integer, 6=byte integer, 7=4bit integer, 8=1bit integer, 9=logical, 10=pointer.

INTEGER count Number of items of the specified format that are available in the field.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

107Chapter 3: Basic FunctionsIntrinsic Functions

record_write_ints ( chan, numitems, i_buffer )

record_write_reals ( chan, numitems, r_buffer )

record_write_chars ( chan, numitems, c_buffer )

record_write_halfints ( chan, numitems, h_buffer )

record_write_int8bits ( chan, numitems, i8_buffer )

record_write_int4bits ( chan, numitems, i4_buffer )

record_write_intbits ( chan, numitems, i1_buffer )

record_write_logicals ( chan, numitems, l_buffer )

record_write_pointers ( chan, numitems, p_buffer )

Description:

Start the read of the next field from the current record of the Record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER numitems Number of items that will be written from the buffer given.

INTEGER() i_buffer Data of integers to write.

REAL() r_buffer Data of reals to write.

STRING c_buffer String data to write.

INTEGER() h_buffer Data of half integers, one per integer, to write.

INTEGER() i8_buffer Data of 8 bit integers, one per integer, to write.

INTEGER() i4_buffer Data of 4 bit integers, one per integer, to write.

INTEGER() i1_buffer Data of 1 bit integers, one per integer, to write.

LOGICAL() l_buffer Data of logicals to write.

INTEGER() p_buffer Data of pointers, one per integer, to write.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

108

record_read_ints ( chan, numitems, i_buffer )

record_read_reals ( chan, numitems, r_buffer )

record_read_chars ( chan, numitems, c_buffer )

record_read_halfints ( chan, numitems, h_buffer )

record_read_int8bits ( chan, numitems, i8_buffer )

record_read_int4bits ( chan, numitems, i4_buffer )

record_read_intbits ( chan, numitems, i1_buffer )

record_read_logicals ( chan, numitems, l_buffer )

record_read_pointers ( chan, numitems, p_buffer )

Description:

Read all or part of the current field of the current record of the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER numitems Number of items to read into the specified buffer.

Output:

INTEGER() i_buffer Integer data read in.

REAL() r_buffer Real data read in.

STRING c_buffer String data read in.

INTEGER() h_buffer Half integer data read in, one per integer.

INTEGER() i8_buffer Eight bit integer data read in, one per integer.

INTEGER() i4_buffer Four bit integer data read in, one per integer.

INTEGER() i1_buffer One bit integer data read in, one per integer.

LOGICAL() l_buffer Logical data read in.

INTEGER() p_buffer Pointer data read in, one per integer.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

109Chapter 3: Basic FunctionsIntrinsic Functions

record_get_position ( chan, position )

Description:

Get a pointer value for the current position in the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

Output:

INTEGER position Pointer value in internal format.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

record_set_position ( chan, position )

Description:

Set the current position in the record I/O file using either a previous pointer value or the special value of zero or minus one.

Input:

INTEGER chan Channel from the record I/O open routine.

INTEGER position Start of record pointer from previous record_get_position call or zero for start of the file or minus one for end of the file.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

record_get_header ( chan, cdatetime, mdatetime )

Description:

Get creation/modification dates for the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

Output:

PCL and CustomizationIntrinsic Functions

110

Stream I/O File Utility FunctionsThe stream input/output package provides a method of reading and writing a binary file treating it as a stream of bytes and words with no record format imposed on it. Support exists for integer, real, and character data. The stream concept implies that whether 2 integer words are written 100 times, or 100 integer words 2 times, the same result is received.

Generally, a file is opened with stream_open, write to it with stream_write_int, stream_write_real, or stream_write_char, read from it with stream_read_int, stream_read_real, or stream_read_char, and close it with stream_close. Data can be skipped with stream_skip_int, stream_skip_real, or stream_skip_char. Some kinds of random access can be performed using stream_get_position and stream_set_position. The stream_update call is used to flush data to disk. File header information, which includes the filecode, description, creation and modification dates can be read and possibly modified with stream_get_header and stream_set_header.

STRING cdatetime Creation date of file in format: yyyymmddhhmmss.

STRING mdatetime Modify date of file in format: yyyymmddhhmmss.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

record_update ( chan )

Description:

Attempt to force the disk file to be up to date for the record I/O file.

Input:

INTEGER chan Channel from the record I/O open routine.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

111Chapter 3: Basic FunctionsIntrinsic Functions

stream_open ( filename, options, chan )

Description:

Create or open a new or existing stream I/O file.

Input:

STRING filename Name of file to open/create.

STRING options Open options of N, O, R, W, P, or V. See File Utility Functions, 81.

Output:

INTEGER chan Channel number to use for subsequent stream I/O operations on this file.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_close ( chan, options )

Description:

Close a file opened for stream I/O.

Input:

INTEGER chan Channel from a previous call to stream_open.

STRING options Close options. Use “D” to delete the file after closing or else use an empty string.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_get_name ( chan, fspec, lenfspec )

Description:

Get the name of a file that is open for stream I/O.

PCL and CustomizationIntrinsic Functions

112

Input:

INTEGER chan Channel from a previous call to stream_open.

Output:

STRING fspec Name of the file.

INTEGER lenfspec Length of the file specification returned.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

113Chapter 3: Basic FunctionsIntrinsic Functions

stream_get_header ( chan, filetype, description, createdate, modifydate, recordinfo )

Description:

Get header information associated with an open stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

Output:

INTEGER filetype Filetype integer set from a stream_set_header call.

STRING description Description string from a stream_set_header call.

STRING createdate Creation date in format: yyyymmddhhmmss.

STRING modifydate Modify date in format: yyyymmddhhmmss.

INTEGER(5) recordinfo Application use data words.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_set_header ( chan, filetype, description, recordinfo )

Description:

Set some header information for a stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER filetype Filetype integer, application defined.

STRING description Description string, application defined.

INTEGER(5) recordinfo Application defined data words.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_get_position ( chan, position )

PCL and CustomizationIntrinsic Functions

114

Description:

Get the current position in the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

Output:

INTEGER position Position returned in internal format.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

115Chapter 3: Basic FunctionsIntrinsic Functions

stream_set_position ( chan, position )

Description:

Set current position in the stream file to the beginning of the file or to a previously saved position.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER position Zero for beginning of file or a value returned from a previous call to stream_get_position.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_read_int ( chan, numtoread, buffer )

Description:

Read integers from the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER numtoread Number of integers to read.

Output:

INTEGER() buffer Integer data read in by the call.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_read_real ( chan, numtoread, buffer )

Description:

Read reals from the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

PCL and CustomizationIntrinsic Functions

116

INTEGER numtoread Number of reals to read.

Output:

REAL() buffer Real data read in by the call.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

117Chapter 3: Basic FunctionsIntrinsic Functions

stream_read_char ( chan, numtoread, buffer )

Description:

Read characters from the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER numtoread Number of characters to read.

Output:

STRING buffer Character data read from stream I/O file.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

stream_write_int ( chan, numtowrite, buffer )

Description:

Write integers to the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER numtowrite Number of integers to write out.

INTEGER() buffer Data to write out to the file.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_write_real ( chan, numtowrite, buffer )

Description:

Write reals to the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER numtowrite Number of reals to write out.

PCL and CustomizationIntrinsic Functions

118

REAL() buffer Data to write out to the file.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

119Chapter 3: Basic FunctionsIntrinsic Functions

stream_write_char ( chan, numtowrite, buffer )

Description:

Write character data to the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER numtowrite Number of characters to write out.

STRING buffer Character data to write.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

stream_skip_int ( chan, numtoskip )

Function;

Skip over integers in the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER numtoskip Number of integers to skip.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_skip_real ( chan, numtoskip )

Description:

Skip over reals in the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER numtoskip Number of reals to skip.

PCL and CustomizationIntrinsic Functions

120

String I/O Conversion Utility FunctionsThe string input/output routines are used when complex formatting of data to or from a character string is needed. A string of data with a format specifier can be passed to string_read to convert the character

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

stream_skip_char ( chan, numtoskip )

Description:

Skip over character data in the stream I/O file.

Input:

INTEGER chan Channel from a previous call to stream_open.

INTEGER numtoskip Number of characters to skip.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

stream_update ( chan )

Description:

Attempt to force all output to be up to date on disk.

Input:

INTEGER chan Channel from a previous call to stream_open.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

121Chapter 3: Basic FunctionsIntrinsic Functions

data to a list of integers, reals, and character strings. A set of integers, reals, and character strings can be converted to a string using string_write.

Output Format Strings

Below is a description of output format strings, that is format strings that are used to convert integer, real, and string data to a formatted output. The format string is a simple character string which contains both raw text to output, and format specifiers, enclosed by a set of percent characters, which control how data items are formatted and output. Following is a description of each type of format specifier. The percent and upper case characters in the format specifiers are treated literally. The lowercase letters, “r”, “m”, “n”, or “p” are to be replaced with an unsigned integer constant, or an asterisk, and are always optional. An asterisk denotes that the value for the operation should be taken from the next element of the integer data array. The lowercase letter “f” is replaced by single uppercase letters for options, and is also optional. Currently defined is “L” for left justified, “R” for right justified(default), and “C” for compressed (E and G format only).

%% The simplest form of format specifier is a double percent to produce a single percent in the final output.

%rIm.nf% Integer specifier. This format specifier takes the next integer value from the integer data array for formatting. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters necessary to hold the integer is used. The value of “n” is used to specify that many digits should be produced at a minimum, using leading zeros if necessary. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the integer data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion. The exact format produced is an optional minus sign followed by one or more digits.

%rXm.nf% Integer hex specifier. This format specifier takes the next integer value from the integer data array for formatting as a hexadecimal number. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters necessary to hold the conversion is used. The value of “n” is used to specify that many digits should be produced at a minimum, using leading zeros if necessary. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the integer data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion. The exact format produced is one or more hexadecimal digits.

PCL and CustomizationIntrinsic Functions

122

%rFm.nf% Fixed float specifier. This format specifier takes the next real value from the real data array for formatting in fixed point notation. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters necessary to hold the conversion is used. The value of “n” is the number of decimal digits to produce. If omitted, then all significant digits will be produced. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the real data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion. The exact format produced is an optional minus sign followed by zero or more digits, a decimal point, and zero or more digits. At least one digit will precede or follow the decimal point.

%rEm.n.pf% Exponential float specifier. This format specifier takes the next real value from the real data array for formatting in scientific exponential notation. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters necessary to hold the conversion is used. The value of “n” is the number of decimal digits to produce. If omitted, then all significant digits will be produced. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the real data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion.

%rGm.n.pf% General float specifier. This format specifier takes the next real value from the real data array for formatting in either F or E format. The format used depends on the value of the number to convert. In general, if the exponent is small, the F format will be used, otherwise the E format is used. See the descriptions of the F and E formats.

%rAmf% String specifier. This format specifier takes the next string value from the character data array for formatting. The value of “m” is the minimum number of characters to produce from the format. If “m” is omitted, then the exact number of characters in the string is used. The value of “r” is a repeat count which causes the specifier to be used that number of times with successive values from the character data array. If “r” is greater than one, and “m” is omitted, then one blank will be inserted between each conversion. Use the “L” option for “f” for left justification of the string.

%rW% White space specifier. This format specifier causes a blank character to be output. The value of “r” is a repeat count for multiple blanks.

123Chapter 3: Basic FunctionsIntrinsic Functions

Input Format Strings

Input format strings, that is format strings that are used to convert formatted input to integer, real, and string data are very similar to output format strings. The format string is a simple character string which contains format specifiers, enclosed by a set of percent characters, which control how data items are formatted and output. Text outside of the format specifiers is ignored. Following is a description of each type of format specifiers. The percent and upper case characters in the format specifiers are treated literally. The lowercase letters, “r”, “m”, or “n” are to be replaced with an unsigned integer constant, or an asterisk, and are always optional. An asterisk denotes that the value for the operation should be taken from the next element of the integer data array.

%rN% New Line specifier. This format specifier causes a new line to be started. The previous line is output as is, and formatting starts at column one of the new line. The value of “r” is a repeat count for skipping multiple lines. If output is to a string, then newline characters will be written to the string.

%r(xxx)% Repeat specifier. Enclosed within the parentheses is a secondary format string, complete with its own percent characters, which is repeated the number of times specified in the “r” repeat count. Repeat specifiers can be nested as desired.

g %rIm% Integer specifier. This format specifier converts input to an integer value and stores it in the next element of the integer data array. The value of “m” is the length of the field to process. If “m” is omitted, then the conversion will take place up to the next space, comma, or end of line. The value of “r” is a repeat count which causes the specifier to be used that number of times.

%rXm% Integer hex specifier. This format specifier converts input of a hexadecimal representation to an integer value and stores it in the next element of the integer data array. The value of “m” is the length of the field to process. If “m” is omitted, then the conversion will take place up to the next space, comma, or end of line. The value of “r” is a repeat count which causes the specifier to be used that number of times.

%rFm% Fixed float specifier. This format specifier converts input of a floating point representation to a real value and stores it in the next element of the real data array. This conversion will accept both fixed and exponential format numbers. The value of “m” is the length of the field to process. If “m” is omitted, then the conversion will take place up to the next space, comma, or end of line. The value of “r” is a repeat count which causes the specifier to be used that number of times.

%rEm% Exponential float specifier. Same as the fixed float specifier.

%rGm% General float specifier. Same as the fixed float specifier.

PCL and CustomizationIntrinsic Functions

124

The INTS, REALS, and CHARS parameters to the formatting routines are somewhat flexible. If only passing a single value, it can be passed directly instead of having to use an array. If not using the parameter at all, pass a constant for the parameter.

%rAm% String specifier. This format specifier converts input to sting value and stores it in the next element of the string data array. The value of “m” is the length of the field to process. If “m” is omitted, then the conversion will take place up to the next space, comma, or end of line. The value of “r” is a repeat count which causes the specifier to be used that number of times.

%rW% White space specifier. This format specifier causes the next character of the input to be skipped and ignored. The value of “r” is a repeat count for multiple blanks.

%rN% New Line specifier. This format specifier causes a new line to be started for input. Any remaining input on the previous line is ignored. The value of “r” is a repeat count for skipping multiple lines.

%Of% Option specifier. The value of “f” is a single character option to set. Currently defined options are “F” for fixed Fortran- style inputting or “V” for variable style inputting. The initial default is “V.” The setting remains for the remainder of the call unless overridden with another %O%. With fixed style formatting, blank fields are interpreted as zeros, and input will not continue to the next line during this call unless a %N% occurs.

%r(xxx)% Repeat specifier. Enclosed within the parentheses is a secondary format string, complete with its own percent characters, which is repeated the number of times specified in the “r” repeat count.

string_read ( string, fmt, ints, reals, chars )

Description:

Read formatted record of mixed data from a string variable.

Input:

STRING string Character string from which the conversion takes place.

STRING fmt Format string governing how conversion is done. See Input Format Strings, 123 for details.

Output:

INTEGER() ints Integer array of data filled in by the read.

REAL() reals Real array of data filled in by the read.

STRING[]() chars Character array of data filled in by the read.

INTEGER <Return Value>

Zero for success, else error message code.

125Chapter 3: Basic FunctionsIntrinsic Functions

ngs,

Example:

INTEGER stat, ints(3); REAL reals(3); STRING chars[10](3)

stat = string_read( “20 30,40 1.75 22 3E-1 Test one two three”, @

%3I%%3F%%3A%”, ints, reals, chars )

Yields:ints = 20, 30, 40

reals = 1.75, 22, .3

chars = “Test”, “one”, “two”

Example:

Error Conditions:

None.

string_write ( fmt, ints, reals, chars, string )

Description:

Write formatted records of mixed data into a string variable.

Input:

STRING fmt Format string governing how conversion is done. See Output Format Stri121 for details.

INTEGER() ints Integer array of data to convert.

REAL() reals Real array of data to convert.

STRING[]() chars String array of data to convert.

Output:

STRING string Character string which receives converted data.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

126

INTEGER stat, ints(2) = 100, 200; STRING out[80]stat = string_write( “Test ival is %I% and rval is %F% for %A% # %I%”, @ints, 3.17, “Trial”, out )Yields:out = “Test ival is 100 and rval is 3.17 for Trial # 200”

INTEGER stat, ints(9) = 2, 4, 6, 3, 3, 1, 2, 3, 2REAL reals(5) = 1., 2., 3., 4., 5. ; STRING out[80]stat = string_write( “%2(That’s %*I% and %*G%.)%”, @ints, reals, “”, out )Yields:out = “That’s 4 6 and 1.0 2.0 3.0.That’s 1 2 3 and 4.0 5.0.”

Text File I/O Utility FunctionsThe text input/output routines are used to create or read operating system readable text files. Use text_open to open/create the file by filename, and a “channel” number is returned which is used for all subsequent calls pertaining to that file. Read or write simple string records with text_read_string and text_write_string. Read or write more complex formatted records with text_read and text_write. A limited amount of random access of the file can be done by using text_get_position and text_set_position. Lastly, get the name of the open file using text_get_name.

127Chapter 3: Basic FunctionsIntrinsic Functions

text_open ( filespec, options, lrecl, maxrecs, chan )

Description:

Open a text file for the Text I/O package.

Input:

STRING filespec Filename of file to open.

STRING options Open options of N, O, A, R, W, P, or V. See File Utility Functions, 81.

INTEGER lrecl Maximum record length for the file if known. Use zero if not known.

INTEGER maxrecs Maximum number of records that the file will contain if known. Use zero if not known.

Output:

INTEGER chan Channel value to use for subsequent text I/O operations.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

text_close ( chan, options )

Description:

Close a text file that was previously opened with text_open.

Input:

INTEGER chan Channel from a previous call to text_open.

STRING options Close options. Use “D” to delete the file after closing or an empty string otherwise.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

text_flush ( chan )

PCL and CustomizationIntrinsic Functions

128

Description:

Attempt to flush any output to the disk for the specified text I/O file.

Input:

INTEGER chan Channel from a previous call to text_open.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

129Chapter 3: Basic FunctionsIntrinsic Functions

text_get_name ( chan, fspec, lenfspec )

Description:

Get the filename associated with an open text I/O file.

Input:

INTEGER chan Channel from a previous call to text_open.

Output:

STRING fspec File specification associated with text I/O file.

INTEGER lenfspec Length of string returned in fspec.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

text_read_string ( chan, line, lenline )

Description:

Read a single record into a string from a text I/O file.

Input:

INTEGER chan Channel from a previous call to text_open or zero to read from standard input (xterm window).

Output:

STRING line Line read in from the text file.

INTEGER lenline Length of the line that was read in.

INTEGER <Return Value>

Zero for success, minus one for end of file, else error message code.

Error Conditions:

None.

text_write_string ( chan, line )

Description:

Write a single record from a string to a text I/O file.

Input:

PCL and CustomizationIntrinsic Functions

130

See Input Format Strings, 123 for more information.

INTEGER chan Channel from a previous call to text_open or zero to write to standard output (xterm window).

STRING line Line to write to the text file.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

131Chapter 3: Basic FunctionsIntrinsic Functions

text_read ( chan, fmt, ints, reals, chars )

Description:

Read formatted records of mixed data from an open text I/O file.

Input:

INTEGER chan Channel from a previous call to text_open or zero to write to standard output (xterm window).

STRING fmt Format string governing how conversion is done.

Output:

INTEGER() ints Integer data converted from the read.

REAL() reals Real data converted from the read.

CSTRING[]()

chars String data converted from the read.

INTEGER <Return Value>

Zero for success, minus one if end of file, else error message code.

Error Conditions:

None.

text_write ( chan, fmt, ints, reals, chars )

Description:

Write formatted records of mixed data to a text I/O file.

Input:

INTEGER chan Channel from a previous call to text_open or zero to write to standard output (xterm window).

STRING fmt Format string governing how conversion is done.

INTEGER() ints Integer data to convert for the write.

REAL() reals Real data to convert for the write.

CSTRING[]()

chars String data to convert for the write.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

PCL and CustomizationIntrinsic Functions

132

Error Conditions:

None.

133Chapter 3: Basic FunctionsIntrinsic Functions

text_get_position ( chan, position )

Description:

Get the current position in the text file for later use with text_set_position.

Input:

INTEGER chan Channel from a previous call to text_open.

Output:

INTEGER position Internal representation of the current position in the text I/O file.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

text_set_position ( chan, position )

Description:

Set the current position in the text file to the beginning of the file, the end of the file, or to a position previously saved with text_get_position.

Input:

INTEGER chan Channel from a previous call to text_open.

INTEGER position Zero for beginning of file, minus one for end of file, or a value previously returned by a call to text_get_position.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

text_truncate ( chan )

PCL and CustomizationIntrinsic Functions

134

Description:

Truncate the text file at the current position thereby deleting any records that follow this position. The file must have been opened for write access.

Input:

INTEGER chan Channel from a previous call to text_open.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

135Chapter 3: Basic FunctionsIntrinsic Functions

text_get_file_size ( chan, bytesize )

Description:

Return the size of the file in bytes.

Input:

INTEGER chan Channel from a previous call to text_open.

Output:

INTEGER bytesize Size of the file in bytes.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

text_file_query ( filnam, options, recnum, startc, endc, lowval, hival )

Description:

Determine if a file contains character text when it is known that a portion of a record of the file contains a text representation of an integer value.

Input:

STRING filnam File to check.

STRING options Open options of P, or V. See File Utility Functions, 81.

INTEGER recnum Record of the file which contains the known integer value where record 1 is the first record of the file.

INTEGER startc Starting character position in the record for the known integer value where 1 is the first position.

INTEGER endc Ending character position in the record for the known integer value.

INTEGER lowval Lowest acceptable value for the integer.

INTEGER hival Highest acceptable value for the integer.

Output:

LOGICAL <Return Value>

TRUE if the file exists, can be read, and has a text representation of an integer in the specified record and columns that is within the specified bounds. Otherwise the result is returned FALSE.

PCL and CustomizationIntrinsic Functions

136

Virtual I/O Scratch File Utility FunctionsThe virtual I/O routines are used when large amounts of working storage is needed and performance is important. If an application always tries to allocate virtual memory for its algorithm, it is limited by the amount of memory and swap space allocated on the particular machine. The virtual file package attempts to work around this problem by automatically spilling data onto disk as necessary while still maintaining as much of the work area in memory as makes sense. To accomplish this, the virtual file package treats the work area as a stream file made up of integers, reals, and characters. The calls to the virtual file package are almost identical to those in the stream file package.

Error Conditions:

None.

virtual_open_scratch ( chan )

Description:

Create and open a virtual scratch file.

Input:

None.

Output:

INTEGER chan Channel number to be used for subsequent operations on the virtual file.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

virtual_close ( chan )

Description:

Close a virtual scratch file.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

137Chapter 3: Basic FunctionsIntrinsic Functions

Error Conditions:

None.

virtual_write_int ( chan, numtowrite, buffer )

Description:

Write integers to a virtual file.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtowrite Number of integers to write from the buffer.

INTEGER() buffer Buffer containing integers to write.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

138

virtual_write_real ( chan, numtowrite, buffer )

Description:

Write reals to a virtual file

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtowrite Number of reals to write from the buffer.

REAL() buffer Buffer containing reals to write.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

139Chapter 3: Basic FunctionsIntrinsic Functions

virtual_write_char ( chan, numtowrite, buffer )

Description:

Write characters to a virtual file.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtowrite Number of characters to write from the buffer.

STRING buffer Buffer containing characters to write.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

virtual_read_int ( chan, numtoread, buffer )

Description:

Write integers from a virtual file.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtoread Number of integers to read into the buffer.

Output:

INTEGER() buffer Area to read integers into.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

virtual_read_real ( chan, numtoread, buffer )

Description:

Read real data from a virtual file.

Input:

PCL and CustomizationIntrinsic Functions

140

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtoread Number of reals to read into the buffer.

Output:

REAL() buffer Area to read reals into.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

141Chapter 3: Basic FunctionsIntrinsic Functions

virtual_read_char ( chan, numtoread, buffer )

Description:

Read character data from a virtual file.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtoread Number of characters to read into the buffer.

Output:

STRING buffer Area to read characters into.

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

virtual_skip_int ( chan, numtoskip )

Description:

Skip over integer data in a virtual file.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtoskip Number of integers to skip over.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

virtual_skip_real ( chan, numtoskip )

Description:

Skip over real data in a virtual file.

PCL and CustomizationIntrinsic Functions

142

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtoskip Number of reals to skip over.

Output:

INTEGER <Return Value>

Zero for success, else error message code.

Error Conditions:

None.

143Chapter 3: Basic FunctionsIntrinsic Functions

virtual_skip_char ( chan, numtoskip )

Description:

Skip over character data in a virtual file.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

INTEGER numtoskip Number of characters to skip over.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

virtual_get_position ( chan, position )

Description:

Get the current position in the virtual scratch file for later use with virtual_set_position.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

Output:

INTEGER position Internal position to use in a later call to virtual_set_position.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

virtual_set_position ( chan, position )

Description:

Set the current position in the virtual scratch file to the beginning of the file or to a position previously retrieved with a call to virtual_get_position.

Input:

INTEGER chan Channel number returned by a previous call to virtual_open_scratch.

PCL and CustomizationIntrinsic Functions

144

Console I/O FunctionsThe console I/O functions are used to display messages to the terminal window, history window, and session file.

INTEGER position Zero to set position to the beginning of the file or a position previously returned by virtual_get_position.

Output:

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

145Chapter 3: Basic FunctionsIntrinsic Functions

.

xf_error_start ( mess )

Description:

Start the reporting of an error message.

Input:

STRING mess First line of error message to report.

Output:

None.

Error Conditions:

None.

xf_error_continue ( mess )

Description:

Continue reporting an error message after xf_error_start has been called.

Input:

STRING mess Additional line of error message to report.

Output:

None.

Error Conditions:

None.

xf_error_end ( )

Description:

End the reporting of an error message after xf_error_start has been called.

Input:

None.

Output:

None.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

146

xf_write_comment ( mess )

Description:

Write a comment to the history window/session file.

Input:

STRING mess Comment to write out.

Output:

None.

Error Conditions:

None.

147Chapter 3: Basic FunctionsIntrinsic Functions

xf_write_command ( mess )

Description:

Write a command to the history window/session file.

Input:

STRING mess Command to write out.

Output:

None.

Error Conditions:

None.

xf_write_query ( mess )

Description:

Write a query to the history window/session file.

Input:

STRING mess Query to write out.

Output:

None.

Error Conditions:

None.

xf_write_print ( mess )

Description:

Write a “print” message to the history window/session file.

Input:

STRING mess Message to write out.

Output:

None.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

148

xf_write_stdout ( mess )

Description:

Write a line to standard output, usually the terminal window.

Input:

STRING mess Line to write out.

Output:

None.

Error Conditions:

None.

xf_write_stderr ( mess )

Description:

Write a line to standard error, usually the terminal window.

Input:

STRING mess Line to write out.

Output:

None.

Error Conditions:

None.

xf_read_from_user ( inmess )

Description:

Read a response from the command line.

Input:

None.

Output:

STRING inmess Line entered by the user.

INTEGER <Return Value> Zero for success, else error message code.

Error Conditions:

None.

149Chapter 3: Basic FunctionsIntrinsic Functions

xf_read_stdin ( inmess )

Description:

Read a response from standard input (xterm window).

Input:

None.

Output:

STRING inmess Line read in from standard input.

INTEGER <Return Value>

Zero for success, minus one for end of file, else error message code.

Error Conditions:

None.

write ( expr, ... )

PCL and CustomizationIntrinsic Functions

150

Example:

ok = ui_read_logical( “Do you want to continue?” )

io_write ( expr, ... )

ui_write ( expr, ... )

Description:

Write out a set of expressions, one per line, to the history window (or tty if no history window).

Input:

ANY expr General PCL expression to write out.

Output:

None.

Error Conditions:

None.

ui_read_logical ( prompt[, hotread] )

Description:

Display a form to the user requesting a yes/no response.

Input:

STRING prompt Prompt to display in the form.

LOGICAL hotread Optional and ignored.

Output:

LOGICAL <Return Value> True if YES button, False otherwise.

Error Conditions:

None.

151Chapter 3: Basic FunctionsIntrinsic Functions

Example:

option = ui_read_integer( “1. Decrease, 2. Increase, 3. Quit”, 1, 3 )

Example:

scale = ui_read_real( “Enter a scale factor for the operation” )

ui_read_integer ( prompt[, minval][, maxval] )

Description:

Display a form to the user requesting an integer response.

Input:

STRING prompt Prompt to display in the form.

INTEGER minval Optional lower bound for response.

INTEGER maxval Optional upper bound for response.

Output:

INTEGER <Return Value>

Integer value that user entered or zero if aborted.

Error Conditions:

abort Value returned is zero even if outside of range specified.

ui_read_real ( prompt[, minval][, maxval] )

Description:

Display a form to the user requesting a real response.

Input:

STRING prompt Prompt to display in the form.

REAL minval Optional lower bound for response.

REAL maxval Optional upper bound for response.

Output:

REAL <Return Value> Value entered by user or zero for abort.

Error Conditions:

abort Value returned is zero even if outside of range specified.

PCL and CustomizationIntrinsic Functions

152

Example:

username = ui_read_string( “What is your name?” )

Example:

ui_read_string ( prompt[, option] )

Description:

Display a form to the user requesting a string response.

Input:

STRING prompt Prompt to display in the form.

INTEGER option Optional and ignored.

Output:

STRING return Value entered by user.

Error Conditions:

None.

ui_answer_message ( msgcode, answer )

Description:

Let PCL function supply answer to a user interface message prompt. The ui_answer_message call must occur BEFORE the user interface message appears.

Input:

INTEGER msgcode Integer code of message that response belongs to. This code is most easily found by first interactively generating the message and then looking in the resultant session file to see what code was generated. If -1 is used for the message code then the answer will apply to any message.

STRING answer Answer for the message. For normal user interface prompts, the valid strings are “YES”, “NO”, YESFOR ALL”, “NOFORALL”, and “ABORT”.

Output:

STRING return Value entered by user.

Error Conditions:

None.

153Chapter 3: Basic FunctionsIntrinsic Functions

/* Supply YES answer to next message no matter what it is */ui_answer_message( -1, “YES” )

Example:

/* Supply YES answer always to the message: * Do you wish to delete the original patches? */ui_override_message( 1000030, “YES” )

ui_override_message ( msgcode, answer )

Description:

Let PCL function supply permanent answer to a user interface message prompt. The ui_override_message call must occur BEFORE the user interface message appears. The override stays in effect until it is cancelled with an empty answer string.

Input:

INTEGER msgcode Integer code of message that response belongs to. This code is most easily found by first interactively generating the message and then looking in the resultant session file to see what code was generated.

STRING answer Answer for the message. For normal user interface prompts, the valid strings are “YES”, “NO”, YESFOR ALL”, “NOFORALL”, and “ABORT”. An empty string, ““, is used to turn off the override.

Output:

STRING return Value entered by user.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

154

write_line ( expr, ... )

io_write_line ( expr, ... )

ui_write_line ( expr, ... )

Description:

Write out a set of expressions trying to fit as much as possible into an 80 character output line, to the history window (or tty if no history window).

Input:

ANY expr General PCL expression to write out.

Output:

None.

Error Conditions:

None.

io_writec ( format, args... )

ui_writec ( format, args... )

Description:

Perform a limited C style format output to the history window. This routine is obsolete but exists for special purposes. Look at the TEXT_WRITE routine instead.

Input:

STRING format C Format string with handling of \n, \r, \t, %d, %f, %e, %g, %x, %s, %c, and %%.

unknown args Appropriate datatype for format specifiers. Incorrect specifications may cause a crash.

Output:

None.

Error Conditions:

None.

155Chapter 3: Basic FunctionsIntrinsic Functions

Message System FunctionsThe Patran messaging system allows PCL to access and display text strings. These text strings may be used for displaying messages or miscellaneous text (e.g. text strings that appear on forms - buttons, labels, etc.). Messages may either be written to the history window or displayed in a form which may require a user response (YES or NO). Additionally, messages may either be directly embedded in PCL or retrieved by a “message code”. Miscellaneous text is always retrieved by a message code.

The accessing routines fall into two categories; a simple interface that displays an embedded PCL message string in one of the message forms, and a rigorous interface that uses a numeric message code to retrieve general text strings and/or display a message in one of the message forms. This rigorous interface allows these strings to be customized by defining these strings in a user modifiable file.

For many customization activities, the simple interface (USER_MESSAGE) will be sufficient. In situations where text strings need to be externalized (defined outside of the code), the rigorous interface functions (MSG_xxx) must be used. These MSG_xxx functions (which are also used by Patran internally) allow for the retrieval and display of messages based on message codes (an integer). As these codes are also used during session file playback to validate message answers, they should be unique. MSC has reserved the values zero to 1 billion minus 1 (0 - 999,999,999) for internal use. While customers are free to use numbers beyond this range, PCL code should be written to allow these numbers to be changed in the case where multiple customizations will be combined that use the same set of numbers. For this reason, it is suggested that the C preprocessor be used extensively so that any required changes in numbering can be performed easily.

io_writef ( format, args... )

ui_writef ( format, args... )

Description:

Perform a limited FORTRAN style format output to the history window. This routine is obsolete but exists for special purposes. Look at the TEXT_WRITE routine instead.

Input:

STRING format FORTRAN format string with handling of /, 'string', X, I, F, E, G, and A formats.

unknown args Appropriate datatype for format specifiers. Incorrect specifications may cause a crash. Array arguments are allowed.

Output:

None.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

156

The MSG_xxx functions retrieve messages from either a primary or secondary file. The primary file (a read-only file that is delivered with Patran) is a specially processed file named “messages.database” that contains the text strings required by Patran. Any message code that is not in this primary file will be looked up in a secondary, user created message file. This file will be either the contents of the environment variable P3_USER_MESSAGES, or if not set, will be named user_messages.database and must exist on the PCL path. The format of the user message file requires each message code to begin in column 1 with the message text spanning as many lines as necessary. Blank lines and lines beginning with a # are ignored (to support the C preprocessor). A special symbol should be used as the base of a customization section to identify the application class.

Sample user_messages.database

This file assigns the application code (appcode) 1,000,000,000 to the application named “Some customization”. There are 2 form labels defined in this range (1,000,000,001 and 1,000,000,002), although the range of these numbers is completely unimportant as long as it is greater than one billion and unique. A single message numbered 1,000,000,100 is defined. It is a formatting string that requires a single string to be substituted in place of %A%. When this message is displayed, the first sentence will be terminated with a newline. Note the number 143 on the second message line. As long as a number does not appear in column 1, it is not considered a message number, and is therefore part of the message (number 1,000,000,100).

The routines USER_MESSAGE, MSG_TO_FORM and MSG_TO_TEXT require an argument (msgtype) that specifies the message severity. For USER_MESSAGE and MSG_TO_FORM, this value also controls the available buttons and determines the range of possible return values. Besides the ABORT button (which appears with all message forms), there are up to four (4) additional buttons that can appear with a CRITICAL or QUERY message and a selectable default value. The possible buttons are YES, NO, YES FOR ALL (YFA) and NO FOR ALL (NFA). The return message status code indicates how the user answered the question (for CRITICAL and QUERY messages).The possible return values are MSG_STAT_YES, MSG_STAT_NO, MSG_STAT_YESALL, MSG_STAT_NOALL, and MSG_STAT_ABORT. The following table lists these different combinations for both the simple and rigorous interfaces.

<start of file>

1000000000 Some customization

#define form text labels

1000000001 Custom pick 1

1000000002 Custom string

#define messages

1000000100 An error was detected while attempting to perform a 143 type operation on %A%.\nDo you wish to continue?

<end of file>

157Chapter 3: Basic FunctionsIntrinsic Functions

Sample usage:

status = MSG_TO_FORM(1000000100, MSG_CRITICAL_YN_NDEFAULT, 1000000000, 0, 0.0, “this entity”)IF ( status == MSG_STAT_YES ) THEN<do something>ENDIF

In this example, the application code (1,000,000,000) will cause the string “Critical Decision requested from application Some customization” to be displayed as the header of the Patran modal message form. The form text box will contain the string:

“An error was detected while attempting to perform a 143 type operation on this entity.Do you wish to continue?”

Additionally, the YES, NO and ABORT buttons will be available, with NO being the default button.

USER_MESSAGE

MSG_TO_FORM description or

(msgtype - string) (msgtype - integer) available buttons

INFO MSG_INFO Informative message

WARN MSG_WARNING Warning message

ERROR MSG_FATAL Error/Fatal message

ACK MSG_ACKNOWLEDGE Acknowledgment message

x_YN MSG_xxx_YN YES, NO

x_YN_Y MSG_xxx_YN_YDEFAULT YES, NO, YES default

x_YN_N MSG_xxx_YN_NDEFAULT YES, NO, NO default

x_YNY MSG_xxx_YNY YES, NO, YES FOR ALL (YFA)

x_YNY_Y MSG_xxx_YNY_YDEFAULT YES, NO, YFA, YES default

x_YNY_N MSG_xxx_YNY_NDEFAULT YES, NO, YFA, NO default

x_YNYN MSG_xxx_YNYN YES, NO, YFA, NO FOR ALL (NFA)

x_YNYN_Y MSG_xxx_YNYN_YDEFAULT YES, NO, YFA, NFA, YES default

x_YNYN_N MSG_xxx_YNYN_NDEFAULT YES, NO, YFA, NFA, NO default

where: x is either C (for CRITICAL) or Q (for QUERY).

xxx is either CRITICAL or QUERY.

See the include file pdamsg.h for constant values.

Important:It is expected that all constants actually be define symbols that will be resolved by the C preprocessor.

PCL and CustomizationIntrinsic Functions

158

The MSG_TO_xxx functions will operate on a formatting string determined by the message code. This string will be retrieved from the primary or the secondary message file. See String I/O Conversion Utility Functions, 120 for detailed information about string formatting.

user_message ( type, appcode, appname, message )

Description:

Display a user message with the MSC.Patran user interface and possibly wait for and return a reply. The “type” determines whether the message is displayed in a form or simply output to the history window. The “type” also determines what buttons are available in the form. The “appcode” is a number assigned by the programmer which can be used in conjunction with ui_answer_message and ui_override_message to supply the message response during session file playback. Use of duplicate application codes will not generally cause problems but it is better if they are unique.

Input:

STRING type[] Type of message format desired. May be:“Info” Informative message“Warn” Warning message“Error” Error/Fatal message“Ack” Acknowledgment message“Q_YN” -Yes/No Query w/o default“Q_YN_Y” -Yes/No Query Yes default“Q_YN_N” -Yes/No Query No default“Q_YNY” -Yes/No/YesAll Query w/o default“Q_YNY_N” -Yes/No/YesAll Query No default“Q_YNYN” -Yes/No/YesAll/NoAll Query w/o default“Q_YNYN_Y” -Yes/No/YesAll/NoAll Query Yes default“Q_YNYN_N” -Yes/No/YesAll/NoAll Query No default“C_YN” -Yes/No Critical w/o default“C_YN_Y” -Yes/No Critical Yes default“C_YN_N” -Yes/No Critical No default“C_YNY” -Yes/No/YesAll Critical w/o default“C_YNY_N” -Yes/No/YesAll Critical No default“C_YNYN” -Yes/No/YesAll/NoAll Critical w/o default“C_YNYN_Y” -Yes/No/YesAll/NoAll Critical Yes default“C_YNYN_N” -Yes/No/YesAll/NoAll Critical No default

INTEGER appcode Application message code, unique value.

STRING appname[] Name of the application generating the message.

INTEGER message[] Message to display.

Output:

INTEGER <Return Value> 1=Yes, 2=No, 3=Yes All, 4=Abort, 5=No All.

159Chapter 3: Basic FunctionsIntrinsic Functions

Example:

Please see user_message (p. 342) in the MSC Acumen Toolkit - Code Examples.

msg_get_string ( msgcode, string )

Description:

Retrieve a message string from the message file.

Input:

INTEGER msgtype Message code.

Output:

STRING string String retrieved from message file.

INTEGER <Return Value>

Length of retrieved message string.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

160

msg_to_form ( msgcode, msgtype, appcode, ints, reals, chars )

Description:

Display a message in either a user interface form or in the history window.

Input:

INTEGER msgcode Message code to look up in message file.

INTEGER msgtype Message type value.

INTEGER appcode Application code reporting error. Use zero for general.

INTEGER() ints Integer data for message formatting.

REAL*() reals Real data for message formatting.

STRING[]() chars String data for message formatting.

Output:

INTEGER <Return Value> Message return code (MSG_STAT_YES, ...).

Error Conditions:

None.

161Chapter 3: Basic FunctionsIntrinsic Functions

Event ManagerThe “em_” routines interact with the user through the event manager, which allows the user to abort PCL programs and interact with the graphics systems similar to the way the delivered PCL performs.

msg_to_text ( msgcode, msgtype, appcode, ints, reals, chars, maxout, chan )

Description:

Write a message to a text I/O file.

Input:

INTEGER msgcode Message code to look up in message file.

INTEGER msgtype Message type value.

INTEGER appcode Application code reporting error.

INTEGER() ints Integer data for message formatting.

REAL*() reals Real data for message formatting.

STRING[]() chars String data for message formatting.

INTEGER maxout Maximum size of each output record.

INTEGER chan Channel from a text_open call or zero to write to standard output (xterm window).

Output:

INTEGER <Return Value> Should normally be 2.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

162

em_proceed_normal ( )

Description:

This function returns FALSE if the user wants to abort and TRUE if the user does not want to abort. The user signals his abort request by clicking the Abort button and confirming the abort request on the Abort Confirmation form. This function also gives the system a chance to update the forms and the Patran viewports.

Input:

None.

Output:

LOGICAL return TRUE - Continue processing.

FALSE - Abort processing.

Error Conditions:

None.

em_proceed_quick ( )

Description:

This function returns FALSE if the user wants to abort and TRUE if the user does not want to abort. This function is identical to em_proceed_normal except it does not allow the system to update the Patran viewports.

Input:

None.

Output:

LOGICAL return TRUE - Continue processing.

FALSE - Abort processing.

Error Conditions:

None.

em_synchronize ( )

Description:

Synchronize events and graphics, making sure everything is up to date.

163Chapter 3: Basic FunctionsIntrinsic Functions

Session File FunctionsThe following set of routines support session file recording and playback.

Input:

None.

Output:

None.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

164

.

sf_record_default ( filename, rotations )

Description:

Define the default recording session file name. Typically, only the base name should be specified. The complete file name will be <basename>.ses.<version>. If an existing session file is specified, a higher version number will be automatically created. This command should only appear in the system startup file p3epilog.pcl.

Input:

STRING filename New name of recording session file.

LOGICAL rotations Write all rotation command to FILENAME.

Output:

None.

Error Conditions:

None.

sf_play_default ( filename, single_step )

Description:

Define the session file to be played after system initialization has completed. The complete filename <basename>.<extension>.<version> should always be used to eliminate any ambiguity that may arise from using the same recording and playing file basename.This command should only appear in the system startup file p3epilog.pcl.

Input:

STRING filename Name of session file to play.

LOGICAL single_step Play back the session file one line at a time.

Output:

None.

Error Conditions:

None.

sf_play ( filename )

Description:

Define a session file to be played. This command is typically used from inside a session file to play nested session files.

165Chapter 3: Basic FunctionsIntrinsic Functions

Input:

STRING filename Name of session file to play.

Output:

None.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

166

sf_commit ( commit_all )

Description:

Specify if each command played back from a session file should be committed to the database. This command is normally entered in the command line.

Input:

LOGICAL commit_all Commit every session file command.

Output:

None.

Error Conditions:

None.

sf_pause ( )

Description:

Allow the playing of a session file to be paused. This will stop/pause the current session file being played and bring up the form. This command is normally edited into a session file for future playback.

Input:

None.

Output:

None.

Error Conditions:

None.

sf_verbose ( write_sys_ms )

Description:

Define if system informational messages should be written to the recording session file.

Input:

LOGICAL write_sys_msg Write system messages to the session file

Output:

None.

167Chapter 3: Basic FunctionsIntrinsic Functions

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

168

sf_write ( string )

Description:

Write a string to the recording session file. This command is not normally used.

Input:

STRING string String to write to the recording session file.

Output:

None.

Error Conditions:

None.

sf_write_disable ( status )

Description:

This function provides control over the mechanism used to write PCL function call information to session files.

Input:

LOGICAL status This value when set to TRUE will disable, and when set to FALSE will enable, the writing of PCL function call information to the session file.

Output:

None.

Error Conditions:

None.

sf_force_write ( string )

Description:

Write a string to the recording session file, even if recording is paused. This command is mainly used for debugging purposes.

Input:

STRING string String to write to the recording session file.

Output:

None.

169Chapter 3: Basic FunctionsIntrinsic Functions

Example:

sf_rotation()> gm_rot_x(value)

Obsolete File I/O FunctionsThe following set of I/O routines are still supported but are considered obsolete. See the File Utility Functions and Text File I/O Utility Functions for the new routines.

Error Conditions:

None.

sf_rotation ( )

Description:

Define if the next command to be recorded is a rotation command. This will allow the rotation commands to be recorded only if the record rotations flag is TRUE. This command is normally used in compiled PCL.

Input:

None.

Output:

None.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

170

fio_openr ( filename, channel )

Description:

Open a text file for read only.

Input:

STRING filename File to open.

INTEGER channel Channel value to use for subsequent operations.

Output:

INTEGER <Return Value> Zero for success, otherwise error status.

Error Conditions:

None.

fio_openw ( filename, channel, overwrite )

Description:

Open a text file for write access.

Input:

STRING filename File to open.

FALSE overwrite Do not overwrite file if exists.

TRUE Overwrite file if exists.

INTEGER channel Channel value to use for subsequent operations.

Output:

INTEGER <Return Value> Zero for success, otherwise error status.

Error Conditions:

None.

fio_opena ( filename, channel )

Description:

Open a text file for write access at end of file for appending.

Input:

STRING filename File to open.

INTEGER channel Channel value to use for subsequent operations.

171Chapter 3: Basic FunctionsIntrinsic Functions

Output:

INTEGER <Return Value> Zero for success, otherwise error status.

Error Conditions:

None.

PCL and CustomizationIntrinsic Functions

172

fio_close ( channel )

Description:

Close a file opened with one of the FIO_OPENx routines.

Input:

INTEGER channel Channel value from the FIO_OPENx routine.

Output:

INTEGER <Return Value> Zero for success, otherwise error status.

Error Conditions:

None.

fio_delete ( filename )

Description:

Delete a file from the operating system.

Input:

STRING filename File to delete.

Output:

INTEGER <Return Value> Zero for success, otherwise error status.

Error Conditions:

None.

fio_rewind ( channel )

Description:

Set the file read/write position back to the start of the file.

Input:

INTEGER channel Channel value from the FIO_OPENx routine.

Output:

INTEGER <Return Value> Zero for success, otherwise error status.

Error Conditions:

None.

173Chapter 3: Basic FunctionsIntrinsic Functions

fio_read ( channel, string )

Description:

Read a string from a file.

Input:

INTEGER channel Channel value from the FIO_OPENx routine.

Output:

STRING string String read from the file. Must be at least two characters larger than the line being read.

INTEGER <Return Value> Zero for success, otherwise error status.

Error Conditions:

None.

fio_write ( channel, string )

Description:

Write a string to a file.

Input:

INTEGER channel Channel value from the FIO_OPENx routine.

STRING string String to write to the file.

Output:

INTEGER <Return Value> Zero for success, otherwise error status.

Error Conditions:

None.

fio_writec ( channel, format, args... )

Description:

Perform a limited C style format output to the file.

Input:

INTEGER channel Channel value from the FIO_OPENx routine.

STRING format C Format string with handling of \n, \r, \t, %d, %f, %e, %g, %x, %s, %c, and %%.

PCL and CustomizationIntrinsic Functions

174

unknown args Appropriate datatype for format specifiers. Incorrect specifications may cause a crash.

Output:

None.

Error Conditions:

None.

fio_writef ( channel, format, args... )

Description:

Perform a limited FORTRAN style format output to the file.

Input:

INTEGER channel Channel value from the FIO_OPENx routine.

STRING format FORTRAN format string with handling of /, 'string', X, I, F, E, G, and A formats.

unknown args Appropriate datatype for format specifiers. Incorrect specifications may cause a crash. Array arguments are allowed.

Output:

None.

Error Conditions:

None.

fio_save_vars ( channel, var, var, ... )

Description:

Write out PCL variable definitions to a file.

Input:

INTEGER channel Channel value from the FIO_OPENx routine.

ANY var Variable definition to write out to file.

Output:

INTEGER <Return Value>

Zero for success, otherwise error status.

Error Conditions:

None.

175Chapter 3: Basic FunctionsGraphics Functions

Graphics Functions

Graphics ManagerPatranPatran provides a set of PCL callable routines which can be used to draw graphical primitives into the graphics windows. These routines were developed so programmers can provide graphical feedback to the user.

The graphics routines were written at a high level to free the developer from having to worry about the current view or which viewport to draw the graphics (there is a way to direct graphics to a specific viewport). All coordinates to the graphical routines are specified in world space.

Retained GraphicsThe graphical primitives generated from the graphics routines can either be stored in the display list or drawn only to the viewports and not stored. For more information about primitives, see Graphics Primitives, 178.The advantage of stored (retained) graphics is that when the view changes, the primitives will automatically be redrawn in the current view orientation. Unretained graphics would not be redrawn when the view changes. The application would have to take care of redrawing the graphics.

The method by which the graphical primitives can be stored in the display list is through the use of segments. Any number of segments can be created in the graphics manager. Each segment can contain thousands of graphical primitives (lines, text, markers). Segment Routines, 176 contain the routines necessary for creating segments. When drawing graphics into a segment, the graphics will automatically show up in all viewports that contain the current group. As an example, if the user currently has two viewports posted, one for the top view and one for a side view of a group, any graphical feedback that is generated from within a segment will automatically be drawn to both viewports.

Example

Here is an example PCL showing how to draw a red box into a viewport. The box is placed in a segment:

REAL corner1(3), corner2(3), corner3(3), corner4(3)INTEGER segment_id, colorcolor = 1corner1(1) = 0.0corner1(2) = 0.0corner1(3) = 0.0corner2(1) = 5.0corner2(2) = 0.0corner2(3) = 0.0corner3(1) = 5.0corner3(2) = 5.0corner3(3) = 0.0corner4(1) = 0.0corner4(2) = 5.0corner4(3) = 0.0/** Create segment. Segment ID is returned from graphics manager.

PCL and CustomizationGraphics Functions

176

*/gm_segment_create( segment_id )/** Draw lines. Lines will be retained in segment.*/

gm_draw_line( segment_id, color, corner1, corner2 )gm_draw_line( segment_id, color, corner2, corner3 )gm_draw_line( segment_id, color, corner3, corner4 )gm_draw_line( segment_id, color, corner4, corner1 )/** Make sure all graphics have been flushed to the screen.*/

gm_segment_flush()

Segment Routines

These are the routines used to create, delete, and flush segments (PCL syntax shown):

177Chapter 3: Basic FunctionsGraphics Functions

gm_segment_create ( id )

Description:

To create a segment of graphics primitives (lines, text, etc. ).

Input:

None.

Output:

INTEGER id Created segment ID.

INTEGER <Return Value> Status of operation. 0 = Successful.

Error Conditions:

None.

gm_segment_delete ( id )

Description:

To delete a segment and remove all graphics primitives (lines, text, etc. ) in the segment from out of the graphics windows.

Input:

INTEGER id Segment ID to delete.

Output:

INTEGER <Return Value>

Status of operation. 0 = Successful.

Error Conditions:

None.

gm_segment_flush ( )

Description:

To flush all graphics primitives to the screen. All primitives, regardless of segment, will be flushed.

Input:

None.

Output:

INTEGER <Return Value> Status of operation. 0 = Successful.

Error Conditions:

None.

PCL and CustomizationGraphics Functions

178

Graphics Primitives

These are the routines used to draw graphics to the viewports. The graphics primitives can optionally be placed into a segment (PCL syntax shown):

179Chapter 3: Basic FunctionsGraphics Functions

gm_draw_line ( segment_id, color_id, start, end )

Description:

Draw a line in segment or current viewport.

Input:

INTEGER segment_id Segment ID created from gm_segment_create.

INTEGER color_id Color of line (0-15).

REAL[3] start Starting location of line in world coord.

REAL[3] end Ending location of line in world coord.

Output:

INTEGER <Return Value> Status of operation. 0 = Successful.

Error Conditions:

None.

gm_draw_text ( segment_id, color_id, location, text )

Description:

Draw a string in segment or current viewport.

Input:

INTEGER segment_id Segment ID created from gm_segment_create.

INTEGER color_id Color of text (0-15).

REAL[3] location Location of line in world coord.

STRING text Text string. Currently limited to 31 characters.

Output:

INTEGER <Return Value>

Status of operation. 0 = Successful.

Error Conditions:

None.

gm_draw_marker ( segment_id, color_id, location, type, size )

Description:

Draw a marker in a segment or current viewport.

PCL and CustomizationGraphics Functions

180

Input:

INTEGER segment_id Segment ID created from gm_segment_create.

INTEGER color_id Color of marker (0-15).

REAL[3] location Location of marker in world coord.

INTEGER type Type of marker (1-dot, 2-circle, 3-X, 4-+, 5-filled circle, 6-square, 7-filled square, 8-triangle, 9-filled tri, 10-diamond, 11-filled diamond).

INTEGER size Size of marker (in pixels).

Output:

INTEGER <Return Value> Status of operation. 0 = Successful.

Error Conditions:

None.

181Chapter 3: Basic FunctionsGraphics Functions

gm_draw_result_arrow (segment_id, color_id, loc, direction, size, anchor_style, string )

Description:

Draw a result arrow at the specified location in the segment or current viewport.

Input:

INTEGER segment_id Segment ID created from gm_segment_create.

INTEGER color_id Color of arrow.

REAL[3] loc Location of arrow in world coord.

REAL[3] direction Direction of arrow in world coord.

REAL size Size of arrow (percentage of model size).

INTEGER anchor_style Anchor style (1-base, 2-tip, 3-middle).

STRING string Text string.

Output:

None.

Error Conditions:

None.

Note:

The various anchor styles for the “anchor_style” argument are shown below.

Base: 0-------->

Tip: -------->0

Middle: -----0---->

where the location value is marked as "0"

gm_draw_arrow ( segment_id, color_id, base, tip, head_size )

Description:

Draw an arrow at the specified base and tip in the segment or current viewport.

Input:

INTEGER segment_id Segment ID created from gm_segment_create.

INTEGER color_id Color of arrow (0-15).

PCL and CustomizationGraphics Functions

182

Viewport Routines

REAL[3] base Base location of arrow in world coord.

REAL[3] tip Tip location of arrow in world coord.

REAL head_size Arrow head size (percentage of arrow length).

Output:

INTEGER <Return Value> Status of operation. 0 = Successful.

Error Conditions:

None.

Note: The head size is a percentage of the arrow length with a value between 0.0 and 1.0.

gm_conv_world_to_device ( vp_id, world_pt, dev_pt )

Description:

Gets the min/max x, y, z coordinate values of the bounding box that encloses the entities displayed in the current viewport. The coordinate values returned are in the global (world) coordinate system.

Input:

vp_id. integer viewport id

world_pt real (3) xyz world coordinate

Output:

dev_pt real (3) xyz device coordinate

INTEGER <Return Value> Status of operation. 0 = Successful.

Error Conditions:

15000025 Error in finding the viewport in the graphics manager display list

Note: The device coordinates are returned in floats (real). The z-value in device coordinates is to allow depth differentiation of points that map to the same x,y location on the screen. Larger z-values are in front of smaller z-values.

183Chapter 3: Basic FunctionsGraphics Functions

gm_viewports_refresh ( )

Description:

Refresh all of the viewports.

Input:

None.

Output:

None.

Error Conditions:

None.

gm_viewport_refresh ( )

Description:

Refresh current viewport.

Input:

None.

Output:

None.

Error Conditions:

None.

gm_viewport_center_get ( center )

Description:

Calculate the center of the current viewport.

Input:

None.

Output:

REAL center Center of the model.

Error Conditions:

None.

PCL and CustomizationGraphics Functions

184

gm_viewport_world_limits_get ( limits )

Description:

Get the x, y and z minimum/maximum values of the model in world space.

Input:

None.

Output:

REAL(6) limits Returns 5% less than the minimum and 5% more than the maximum x, y and z coordinates of the model in world space.

Error Conditions:

None.

gm_viewport_subject_get ( persp_off, center, zoom )

Description:

Calculate the center of the current viewport.

Input:

None.

Output:

INTEGER persp_off If TRUE, this skips perspective. If FALSE, the perspective setting in the current viewport will be used.

REAL[2] center Center of subject space for the viewport.

REAL ZOOM Zoom factor for the subject space.

Error Conditions:

None.

Chapter 4: System and Utility FunctionsPCL and Customization

4 System and Utility Functions

Spawning a Process

Database Locking

System Functions

PCL and CustomizationSpawning a Process

186

Spawning a ProcessApplication 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.” The following sections provide details for spawning a process from inside Patranwww.ebay, how a database can be locked to prevent access during the spawning process, and how to add entries to the Status Database in order track the status of a spawned process.

Spawning a remote process is one method of performing customized functionality. The PCL function utl_process_spawn is used by Patran to spawn a process. See The PATRAN Command Language (PCL) Introduction (Ch. 2) for a summary of the related PCL functions.

Example: An application developer has an executable (script or program) called mytranslator that requires the database name and a count. The developer’s executable, mytranslator, should reside somewhere along the PCL path, as defined by the PCL directive, !!PATH in either the p3prolog.pcl file or the p3epilog.pcl file. See The p3prolog.pcl and p3epilog.pcl Files (p. 54) in the Patran Reference Manual.

FUNCTION start_mytrans(dbname, count)string dbname[]integer countinteger statusstring mytrans[256], cmd[512]

/* Find where mytranslator is - we should check for errors */status = file_get_filespec(“mytranslator,” ”OP,” mytrans)

/* Format the argument string required by mytranslator */str_formatc(cmd,”%s -db %s -cnt %d,” 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 ) ) THENutl_display_error( status, 2)ENDIFEND FUNCTION /* start_mytrans */The PCL call:start_mytrans(“my.db,”542)will invoke the following from the bourne shell:mytranslator -db my.db -cnt 542

Note: For portability reasons, all scripts should be written for the bourne shell.

187Chapter 4: System and Utility FunctionsDatabase Locking

Database LockingHaving more than one process access a database simultaneously can damage the database. In order to prevent this, Patran locks the database while it is in use. Any executable that uses a database (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> . . .

Example: Modify the executable start_mytrans (shown in the Example in Spawning a Process, 186) to support database locking.

FUNCTION start_mytrans(dbname, count)< same as previous example >/* CHANGED: Format the argument string required by mytranslator */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 ) ) THENutl_display_error( status, 2)ENDIFEND FUNCTION /* start_mytrans */

Using the previous example, this will execute the following command:

lockfile my.db mytranslator -db my.db -cnt 542

PCL and CustomizationSystem Functions

188

System FunctionsSystem functions have varied functions and can be useful for getting system information or accessing special operations in the PCL environment

Example:

REAL value = 3.14159INTEGER bitssys_move_raw( value, bits )$ Bits is now the integer representation of the floating point number. $ The value contained in bits will be completely machine dependent

sys_move_raw (source, destination)

Description:

Move raw data from one PCL variable to another. This function is not generally used but can occasionally be useful if data in one format needs to be accessed in another format.

Input:

ANY source The source variable to move information from.

Output:

ANY destination The destination variable to which to copy the source variable.

Error Conditions:

None.

189Chapter 4: System and Utility FunctionsSystem Functions

sys_product ( )

Description:

Return a string representing the name of the product/application being executed.

Input:

None.

Output:

STRING <Return Value> Product name, such as “Patran”.

Error Conditions:

None.

sys_release ( )

Description:

Return a string representing the release/version of the product/application being executed.

Input:

None.

Output:

STRING <Return Value> Release/Version string.

Error Conditions:

None.

PCL and CustomizationSystem Functions

190

sys_date ( )

Description:

Return a string with the current date in dd-mm-yy format.

Input:

None.

Output:

STRING <Return Value> String representing date such as “25-Feb-92.”

Error Conditions:

None.

sys_time ( )

Description:

Return a string with the current time in hh:mm:ss format.

Input:

None.

Output:

STRING <Return Value>

String representing time such as “12:52:22.”

Error Conditions:

None.

sys_clock ( )

Description:

Return the current time in seconds since midnight.

Input:

None.

Output:

191Chapter 4: System and Utility FunctionsSystem Functions

REAL <Return Value>

Current time in seconds since midnight expressed as a REAL.

Error Conditions:

None.

PCL and CustomizationSystem Functions

192

sys_cputime ( )

Description:

Return a cpu time value in seconds on a machine dependent base. It is recommended to use this value by taking the difference between two calls to the function in the same session. This routine returns the sum of the user and system time.

Input:

None.

Output:

REAL <Return Value> CPU time in seconds from unknown base.

Error Conditions:

None.

sys_allocate_array (array, lb1, hb1 [, lb2, hb2 [, lb3, hb3 [, lb4, hb4 ]]] )

Description:

Allocate memory for a PCL virtual array variable. This function is more completely described in the virtual arrays section of the PCL manual

Input:

INTEGER lb1 Lower bound for first dimension.

INTEGER hb1 Higher bound for first dimension.

INTEGER lb2 Optional lower bound for a second dimension.

INTEGER hb2 Optional upper bound for a second dimension.

INTEGER lb3 Optional lower bound for a third dimension.

INTEGER hb3 Optional upper bound for a third dimension.

INTEGER lb4 Optional lower bound for a fourth dimension.

INTEGER hb4 Optional upper bound for a fourth dimension.

Output:

ANY(VIRTUAL) array Virtual array with storage allocated if available.

INTEGER <Return Value> Zero for success, else error code.

Error Conditions:

None.

193Chapter 4: System and Utility FunctionsSystem Functions

Remarks:

This function can only be used to increase the size of the array. An attempt to reduce the size of the array will not return an error value and will not reduce the size of the array.

This function will not reorder the data in original array. If a two-dimensional virtual array is reallocated so that the number of offsets in the second or column dimension are increased, the contents of the entries of the first or row dimension will be modified. See the example listed below.

Example:FUNCTION reallocate_demonstration() INTEGER row_count INTEGER column_count INTEGER test_array(VIRTUAL) INTEGER row_size

sys_reallocate_array (array, lb1, hb1 [, lb2, hb2 [, lb3, hb3 [, lb4, hb4 ]]] )

Description:

Re-allocate memory for a PCL virtual array variable. This function is more completely described in Virtual Arrays, 15.

Input:

ANY(VIRTUAL)

array Original virtual array.

INTEGER lb1 Lower bound for first dimension.

INTEGER hb1 Higher bound for first dimension.

INTEGER lb2 Optional lower bound for a second dimension.

INTEGER hb2 Optional upper bound for a second dimension.

INTEGER lb3 Optional lower bound for a third dimension.

INTEGER hb3 Optional upper bound for a third dimension.

INTEGER lb4 Optional lower bound for a fourth dimension.

INTEGER hb4 Optional upper bound for a fourth dimension.

Output:

ANY(VIRTUAL)

array Virtual array with storage reallocated if available.

INTEGER <Return Value>

Zero for success, else error code.

Error Conditions:

None.

PCL and CustomizationSystem Functions

194

INTEGER column_size INTEGER return_value INTEGER array_value

/* * Set up the initial array sizes */ column_size = 5 row_size = 5

/* * Do the initial array allocation */ return_value = sys_allocate_array ( test_array, 1, row_size, 1, column_size ) IF (return_value != 0 ) THEN write(" ") write("Calling sys_allocate_array() has failed.") write(" ") dump return_value END IF

write(" ") write("Initialize the array.") write(" ") array_value = 1 FOR (row_count = 1 TO row_size) FOR (column_count = 1 TO column_size) test_array (row_count, column_count) = array_value array_value = array_value + 1 END FOR END FOR dump test_array

write(" ") write("Increase the row size.") write(" ") row_size = 10 return_value = sys_reallocate_array ( test_array, 1, row_size, 1, column_size ) IF (return_value != 0 ) THEN write(" ") write("Calling sys_allocate_array() has failed.") write(" ") dump return_value END IF dump test_array

write(" ") write("Decrease the row size.") write(" ") column_size = 5 row_size = 10 return_value = sys_reallocate_array ( test_array, 1, row_size, 1, column_size ) IF (return_value != 0 ) THEN write(" ") write("Calling sys_allocate_array() has failed.") write(" ") dump return_value END IF dump test_array

write(" ") write("Deallocate, reallocate and reinitialize the original array.") write(" ") column_size = 5 row_size = 5 return_value = sys_free_array ( test_array )

195Chapter 4: System and Utility FunctionsSystem Functions

IF (return_value != 0 ) THEN write(" ") write("Calling sys_free_array() has failed.") write(" ") dump return_value END IF

return_value = sys_allocate_array ( test_array, 1, row_size, 1, column_size ) IF (return_value != 0 ) THEN write(" ") write("Calling sys_allocate_array() has failed.") write(" ") dump return_value END IF

array_value = 1 FOR (row_count = 1 TO row_size) FOR (column_count = 1 TO column_size) test_array (row_count, column_count) = array_value array_value = array_value + 1 END FOR END FOR dump test_array

write(" ") write("Increase the column size.") write(" ") column_size = 10 return_value = sys_reallocate_array ( test_array, 1, row_size, 1, column_size ) IF (return_value != 0 ) THEN write(" ") write("Calling sys_allocate_array() has failed.") write(" ") dump return_value END IF dump test_array

END FUNCTION

END FUNCTION

PCL and CustomizationSystem Functions

196

sys_free_array ( array )

Description:

Free memory for a PCL virtual array variable. This function is more completely described in Virtual Arrays, 15.

Input:

ANY(VIRTUAL) array Virtual array.

Output:

ANY(VIRTUAL) array Virtual array now deallocated

INTEGER <Return Value> Zero for success, else error code.

Error Conditions:

None.

sys_allocate_string ( string, size )

Description:

Allocate memory for a PCL virtual string variable. This function is more completely described in Virtual Arrays, 15.

Input:

INTEGER size New maximum size for the virtual string variable.

Output:

STRING string Virtual string with storage allocated if available.

INTEGER <Return Value> Zero for success, else error code.

Error Conditions:

None.

sys_reallocate_string ( string, size )

Description:

Re-allocate memory for a PCL virtual string variable. This function is more completely described in Virtual Arrays, 15.

Input:

STRING string Original virtual string.

197Chapter 4: System and Utility FunctionsSystem Functions

INTEGER size New maximum size for the virtual string variable.

Output:

STRING string Virtual string with storage allocated if available.

INTEGER <Return Value>

Zero for success, else error code.

Error Conditions:

None.

sys_free_string ( string )

Description:

Free memory for a PCL virtual array variable. This function is more completely described in Virtual Arrays, 15.

Input:

STRING string Virtual string.

Output:

STRING string Virtual string now deallocated.

INTEGER <Return Value>

Zero for success, else error code.

Error Conditions:

None.

sys_array_hbound ( array, dim )

Description:

Return the upper bound for a dimension of an array.

Input:

ANY() array Array to return upper bound for.

INTEGER dim Dimension number to return bound for, one for first dimension.

Output:

INTEGER <Return Value> Upper bound of specified dimension of specified array.

Error Conditions:

None.

PCL and CustomizationSystem Functions

198

sys_array_lbound ( array, dim )

Description:

Return the lower bound for a dimension of an array.

Input:

ANY() array Array to return lower bound for.

INTEGER dim Dimension number to return bound for, one for first dimension.

Output:

INTEGER <Return Value> Lower bound of specified dimension of specified array.

Error Conditions:

None.

sys_array_nbound ( array )

Description:

Return the number of bounds/dimensions for an array.

Input:

ANY() array Array to return number of dimensions for.

Output:

INTEGER <Return Value> Number of dimensions of specified array or zero if not an array.

Error Conditions:

None.

sys_class_get ( classname, varname )

Description:

This function will return the value of a classwide variable from a class of PCL functions.

Input:

STRING class_name[32] This value specifies the name of the PCL function class from which the variable value will be retrieved.

STRING variable_name[32]

This value specifies the name of the variable which will have its value retrieved.

Output:

199Chapter 4: System and Utility FunctionsSystem Functions

Remarks:

This function assumes that the caller already knows the data type of the variable whose contents will be returned.

Example:

None.

DYNAMIC_ILRSW

<Return Value> This function returns the value from the specified variable which is a member of the specified class.

Error Conditions:

None.

PCL and CustomizationSystem Functions

200

sys_class_set ( classname, varname, newvalue )

Description:

Set the contents of a class variable.

Input:

STRING classname Class name specified as a string.

STRING varname Variable name specified as a string.

UNKNOWN newvalue New value for the class variable. The value must be of the correct type.

Output:

None.

Error Conditions:

None.

Side Effects:

Unknown. Be cautious with this routine. Most class functions do not expect their variables to change from accesses outside of the class definition.

sys_hash_stat ( tablename )

Description:

Output internal hash table statistics for various parts of the Patran system. This routine is primarily for performance tuning and is not expected to be used by the typical user.

Input:

STRING tablename Name of a system hash table.

Output:

STRING tablename Name of a system hash table.

LOGICAL <Return Value> True if hash table found, FALSE otherwise.

Error Conditions:

None.

sys_eval (pcl_expression)

Description:

This function will execute a PCL expression contained in a string.

201Chapter 4: System and Utility FunctionsSystem Functions

Input:

STRING pcl_expression This value provides the PCL expression that will be evaluated. This expression is evaluated in a global context where it will be assumed that any variables in the PCL expression will have a global scope. This global context prevents the use of any local variables in the PCL expression.

Output:

DYNAMIC_ILRS <Return Value> This function will return the results of the evaluated PCL expression. The type of the data returned will be defined by the evaluated PCL expression.

Error Conditions:

None.

sys_func_where ( func [, options] )

Description:

Search for type and existence of a PCL function.

Input:

STRING func Name of PCL function to search for.

INTEGER options Optional argument which if set to one causes a faster search to take place which might miss changes made to library lists.

Output:

INTEGER <Return Value> Result of check. If function does not exists, the value is zero. If the function is an intrinsic function, the value is one. If the function exists and is currently loaded into memory, the value is two. If the function exists, but is currently not in memory, the value is three.

Error Conditions:

None.

PCL and CustomizationSystem Functions

202

sys_sf_callopt ( options )

Description:

Set options for session file “>” processing lines. This routine is not normally expected to be used by users.

Input:

INTEGER options One to suppress all session, two to suppress next, zero to enable.

Output:

INTEGER <Return Value> Previous value of the options.

Error Conditions:

None.

sys_sf_argopt ( argnum, options )

Description:

Set options for session file “>” processing lines. This routine is not normally expected to be used by users.

Input:

INTEGER argnum Argument number to affect.

INTEGER options Sum of 1 for use variable instead of value, 2 for output declaration, and 4 for output class declaration.

Output:

INTEGER <Return Value> Previous value of the options.

Error Conditions:

None.

sys_sf_write ( string )

Description:

Write string to session file under control of SYS_SF_CALLOPT. This routine is not normally expected to be used by users.

Input:

STRING string String to write to the session file.

Output:

203Chapter 4: System and Utility FunctionsSystem Functions

None.

Error Conditions:

None.

PCL and CustomizationSystem Functions

204

sys_sf_vwclear ( )

Description:

Clear variable written list. This routine is not normally expected to be used by users.

Input:

None.

Output:

None.

Error Conditions:

None.

sys_sf_commit ( )

Description:

Commit variable written list. This routine is not normally expected to be used by users.

Input:

None.

Output:

None.

Error Conditions:

None.

sys_sf_undo ( )

Description:

Undo variable written list up to last commit. This routine is not normally expected to be used by users.

Input:

None.

Output:

None.

Error Conditions:

None.

205Chapter 4: System and Utility FunctionsSystem Functions

sys_poll_option ( option )

Description:

Set polling options for PCL compiler/interpreter for checking aborts, events, and graphics updates. This routine is not normally expected to be used by users but can speed up operations by minimizing graphics updates if used correctly.

Input:

INTEGER option Zero for full check, one for quick check, two for no check.

Output:

INTEGER <Return Value> Previous value of the options.

Error Conditions:

None.

sys_trace ( options )

Description:

Allow setting of tracing options during runtime execution. See !!TRACE (p. 9) for details.

Input:

STRING options String with any of blank separated keywords of “CALLS”, “LINES”, “EXITS”, “STDOUT”, “NOCALLS”, “NOLINES”, “NOEXITS”, “NOSTDOUT”, “NONE”.

Output:

STRING <Return Value> Previous value of the options.

Error Conditions:

None.

sys_traceback ( )

Description:;

Output a PCL error call traceback.

Input:

None.

Output:

None.

PCL and CustomizationSystem Functions

206

Error Conditions:

None.

207Chapter 4: System and Utility FunctionsSystem Functions

sys_input ( filename [,noerror ] )

Description:

Allow setting of an input file during execution. See !!INPUT (p. 9) for details. Note: This routine will often work differently than expected as the inputted file is queued for execution and won't actually execute until PCL returns control to the user interface.

Input:

STRING FILENAME Name of operating system file to input.

LOGICAL NOERROR Optional flag which if set TRUE will suppress any error if the specified file does not exist.

Output:

LOGICAL <Return Value> True if input queued successfully.

Error Conditions:

None.

sys_stop_input ( )

Description:

Attempt to stop !!INPUT file during runtime execution.

Input:

None.

Output:

None.

Error Conditions:

None.

sys_library ( operation, args )

Description:

Allow setting of library options during runtime execution. See !!LIBRARY (p. 9) for details.

Input:

STRING operation String with operation keyword of either “”, “ADD”, “CREATE”, “DELETE”, “KEEPOPEN”, “LIST”, “MERGE”, “NONE”, “REHASH”, “REMOVE”, or “SORT”.

PCL and CustomizationSystem Functions

208

STRING args Filename(s) or function name(s) depending on operation specified.

Output:

None.

Error Conditions:

None.

209Chapter 4: System and Utility FunctionsSystem Functions

sys_path ( operation, paths )

Description:

Allow setting of path options during runtime execution. See !!PATH (p. 9) for details.

Input:

STRING operation String with operation keyword of either “ ”, “NONE”, or “REMOVE”.

STRING paths Pathname(s) for operations.

Output:

None.

Error Conditions:

None.

sys_get_env ( ename, result )

Description:

Look up a system environment variablt name.

Input:

STRING ename Name of environment variable to look up. Note that this name is case sensitive on unix systems.

Output:

STRING result String result of environment definition if environment variable is defined.

INTEGER <Return Value> Zero for success, else error code if environment variable is not defined.

Error Conditions:

None.

sys_get_errno_msg ( enoval, result )

Description:

Translate a system “errno” value to a string.

Input:

INTEGER enoval System “errno” value.

Output:

PCL and CustomizationSystem Functions

210

STRING result String with message for specified errno.

Error Conditions:

None.

211Chapter 4: System and Utility FunctionsSystem Functions

sys_get_info ( infotype, result )

Description:

Get various kind of “system” information.

Input:

INTEGER infotype Type of information desired, currently only 1=Machine Name.

Output:

STRING result Returned information as a string. For infotype=1, the possible returns are: SUNS, SGI5, RS6K, HP700, HPIPF, WINNT and LX86 with possible others in the future.

INTEGER <Return Value>

Zero for success, else error.

Error Conditions:

None.

sys_get_user ( uname )

Description:

Get operating system user name for currently logged in user.

Input:

None.

Output:

STRING uname Login name of user logged in.

Error Conditions:

None.

utl_get_cust_info ( custnumber, custname )

Description:

Get customer information.

Input:

STRING custnumber Customer number string.

STRING custname Customer name string.

Output:

PCL and CustomizationSystem Functions

212

INTEGER <Return Value> Status, 0=success.

Error Conditions:

None.

213Chapter 4: System and Utility FunctionsSystem Functions

utl_get_host_name ( host )

Description:

Retrieve name of operating system network host.

Input:

None.

Output:

STRING host Network host name.

Error Conditions:

None.

utl_get_product ( product )

Description:

Return Patran product name (same as sys_product).

Input:

None.

Output:

STRING product Product name string.

Error Conditions:

None.

utl_get_user_name ( user )

Description:

Retrieve name of operating system user.

Input:

None.

Output:

STRING user User name.

LOGICAL <Return Value> True for successful retrieval.

PCL and CustomizationSystem Functions

214

Error Conditions:

None.

215Chapter 4: System and Utility FunctionsSystem Functions

utl_get_version ( version )

Description:

Return Patran version number (same as sys_release).

Input:

None.

Output:

STRING version Version number string.

Error Conditions:

None.

utl_process_spawn ( command, wait )

Description:

The program will execute a “fork” system call (or “vfork”, depending on the specific machine implementation) followed by an “execvp” system call with the “command” specified by the caller as its argument. The spawned command becomes a “process group leader.” This allows all processes created by this spawned process to be killed via the abort button or UTL_PROCESS_KILL. Redirection cannot be used in subprocess commands entered via utl_process_spawn. If redirection is required for the subprocess it is recommended that a bourne shell script be created which accepts the redirected input and output files as arguments and then issues the actual command of interest, including the redirection. This bourne shell script is what should be input to the utl_process_spawn function in this case.

Input:

STRING command Command string to execute.

LOGICAL wait True to wait for completion before continuing. False to execute command asynchronously.

Output:

INTEGER <Return Value> If WAIT is TRUE, then a return code is returned which needs to be checked by utl_process_error. If WAIT is FALSE, then the process group ID of the subprocess is returned. On Windows NT if WAIT is FALSE, then zero is returned.

Error Conditions:

None.

PCL and CustomizationSystem Functions

216

Example:stat = utl_process_spawn( “lpr results.out”, TRUE )IF( utl_process_error( stat ) ) THEN utl_display_process_error( stat, 3 )END IF

Important: The spawned process must not return the value 253. This value is reserved for MSC internal use.

217Chapter 4: System and Utility FunctionsSystem Functions

utl_process_wait ( pid )

Description:

Wait for an asynchronous command to finish completion.

Input:

INTEGER pid Process ID returned from a previous call to utl_process_spawn with WAIT as FALSE.

Output:

INTEGER <Return Value> Status code that can be checked with utl_process_error.

Error Conditions:

None.

utl_display_process_error ( errcode, severity )

Description:

Display an error message based on a status code from one of the utl_process commands.

Input:

INTEGER errcode Status from utl_process_spawn or utl_process_wait.

INTEGER severity Type of form to use for display. 1=Info, 2=Warning, 3=Acknowlege, 4=Fatal.

Output:

None.

Error Conditions:

None.

utl_process_error ( errcode )

Description:

Check status of utl_process_spawn or utl_process_wait.

Input:

PCL and CustomizationSystem Functions

218

INTEGER errcode Status from utl_process_spawn or utl_process_wait.

Output:

LOGICAL <Return Value> TRUE if error occurred, FALSE otherwise.

Error Conditions:

None.

utl_process_kill ( pid )

Description:

To kill a spawned subprocess and all child processes created on its behalf.

Input:

INTEGER pid PID returned from UTL_PROCESS_SPAWN

Output:

None.

Error Conditions:

None.

Chapter 5: User Interface and List Processor FunctionsPCL and Customization

5 User Interface and List Processor Functions

Introduction 220

General Form Style 225

Creating Forms and Widgets Using PCL 246

widget Function Descriptions 256

List Processor 258

User Interface Functions 297

PCL and CustomizationIntroduction

220

Introduction Nearly all of the forms and widgets that are contained in Patran were created using PCL. Users can customize the Patran interface by adding a menu to the main form and by adding items to that menu. Adding a PCL function called a “callback” which is referenced by the user defined menu can then bring up forms and widgets in any way the user desires.

Customization of the interface occurs through PCL programs. The PCL Class was specifically designed to manage Forms and widgets. Each Class contains a reserved set of PCL Functions called init, display and refresh which are used to define, display and update the form and all the widgets contained in the form, respectively. The Class structure is as follows.

CLASS classname

CLASSWIDE declarations...

hheader initwidget definitionsEND FUNCTION

hheader displayui_form_display(classname)END FUNCTION

hheader refreshdb_get_item(...)ui_wid_get(...)ui_wid_set(...)END FUNCTIONfunctions (see Structure of a PCL Function, 26END CLASS

The Init Function

The init function contains PCL functions which define the form and the individual widgets. An example of a built-in to create a button widget looks like this:

/* * Create the “Apply” button */

apply_button = ui_button_create( @ /* parent */ form_id, @ /* callback */ “apply_cb”, @ /* x */ 0.136, @ /* y */ y_loc, @ /* width */ 1.0, @ /* height */ 0.0, @ /* label */ “Apply”, @ /* labelinside */ TRUE, @ /* highlight */ TRUE )

widget Hierarchy

Widgets are created in a hierarchical manner. Every widget has a parent except for a form. In the previous example which is the built-in to create an “Apply” button, the parent widget was a form and its id was “form_id”. “form_id” is a PCL variable that is declared as widget and returned as a value from a widget creation call similar to the way the PCL variable “apply_button” is assigned a value from the call to “ui_button_create” in the previous button example. When creating widgets, the parent

221Chapter 5: User Interface and List Processor FunctionsIntroduction

widget must be identified, usually as the first argument in the call to the create function. A parents widgets are referred to as its children.

Events

If the user “clicks” on a widget with the mouse button, an event is generated. Events are handled by the event manager which, in general performs the appropriate operation to respond to the user. If the user provides customized forms and widgets, it is necessary to inform the event manager that he is “listening” for events that occur regarding any of the user supplied widgets. The resulting response to a user supplied widget is a PCL function called a Callback which the user must write and identify when he creates a widget.

Callbacks

A Callback is a PCL function. If an event occurs for a user supplied widget which requires an action, a Callback must be specified at the time the widget is created to handle the event. The second argument in the widget creation call is normally a string which contains the function name as the Callback. In the “Button” example, “apply_cb” is the Callback function for the “Apply” button. The Callback function must exist in the Class in which the widget is created. In our example, the Callback looks like this:

apply_cb()/** Add all the elements with shape element_shape into the group* specified in the group_name_box list box*/

STRING group_name[32] STRING element_shape[5]

ui_wid_get(group_name_box, “VALUE”, group_name) ui_wid_get(el_shape_switch, “VALUE”, element_shape) put_element_in_group(element_shape, group_name)ui_wid_refresh()

END FUNCTION /* apply_cb end function */

The “Apply” button for our example takes all the elements of a certain shape as specified in a switch and adds them to a group which was typed into a databox. The widget id for the switch is “el_shape_switch” and the widget id for the databox is “group_name_box”. The function “ui_wid_get” gets information or parameters as specified in the second argument from the identified widget. The form might look something like this:

PCL and CustomizationIntroduction

222

Locating and Sizing Widgets

When creating a widget, the widget location is always specified relative to its parent. The position is given in inches. The only exception is a form which is positioned relative to the graphics display and can be positioned relative to the upper-left, lower-left, upper-right or lower-corner of the display.

Each widget is sized in inches, usually as a x and y dimension. In some cases, a value of zero can be input so that the size is based on the font size contained in the widget.

Tailoring Widgets

Each widget has a number of resources or parameters which can be set or changed to modify the look and response of the widget. The functions ui_wid_set and ui_wid_get allow changing the widget resources. A typical call looks like:

ui_wid_set(apply_button, “ENABLE”, FALSE)

This results in the button whose id is apply_button to be ghosted as in the following example.

223Chapter 5: User Interface and List Processor FunctionsIntroduction

The Display Function

Once the widget are defined in the init function in the Class, the display function is used to make them visible. An example of a display function is:

FUNCTION DISPLAY()

ui_form_display(“group_elements”)

END FUNCTION

The function ui_form_display has one argument which is a Class name. Any form defined in the init function for the given class is displayed along with all of its children widgets. Individual widgets on the form may be set to invisible by calling ui_wid_set(widget_id, “DISPLAY”, FALSE).

Displaying a Form, “ui_exec_function (class_name, “display”)”

To actually make the form appear it is necessary to invoke a special function called ui_exec_function. This function is specifically designed to execute a PCL function defined in the named Class so that, if the init function hasn’t been previously called, it will be prior to executing the named function in the Class, otherwise, it just executes the named function. It is important that the init function is called only once during a Patran session since this is the function which defines all of the widget attributes and saves it in memory. If the init function were to be called more than once during a session, the data would be duplicated in memory and the program would produce unexpected results.

During the development of a PCL program where forms and widgets are being created, it might be convenient to remove the definition of the widgets from memory. This can be accomplished by a call to

PCL and CustomizationIntroduction

224

ui_form_delete(class_name). Any form defined in the given Class is deleted from memory as well as all of its children widgets. After modifying the PCL Class and re-compiling use ui_exec_function to re-display the form with the revised widgets (which in turn invokes the init function).

When putting the code into “production”, ui_form_delete should be replaced with ui_form_hide(class_name) to un-display the form but not delete its resources and widget definitions.

Refreshing a form

Once a form is defined and displayed, it may display information which can change while it is being displayed. An example might be the contents of a group on the group modify form. If the user were to delete one of the entities contained in the group while the form was displayed, the form would become out-of-date if some mechanism wasn’t provided to “refresh” the form. In Patran, the function ui_wid_refresh() performs that function. When ui_wid_refresh() is called (no arguments), the User Interface Management system is invoked to determine the Class name of all forms currently displayed. For every Class whose form is displayed, the refresh function is called in that Class to update the form. An example of a refresh function is:

/*$$ callback FUNCTION refresh( ) * * Purpose: * Get the current analysis code * * Input: * <none> * * Output: * <none> * */ FUNCTION refresh( )

INTEGER db_status STRING current_analysis_code[32]

db_status = db_get_default_anal_code( current_analysis_code )

IF( db_status != 0 ) RETURN

ui_wid_set( analysis_code, “LABEL”, current_analysis_code )

END FUNCTION /* refresh */

In the above example, a label is displayed which shows the current analysis code, the call db_get_default_anal_code(current_analysis_code) returns the current analysis code in a string. the call to ui_wid_set for the label whose id is analysis_code changes the label to indicate the new analysis code.

225Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

General Form StyleDefine Strings are provided to size and position forms and widgets for a consistent “look and feel”.

Use of Include Files in Creating Patran Forms

There are two include files delivered with Patran in the $P3_HOME/customization directory which are very helpful in creating forms. They are appforms.p and uiforms.p. In order to include these files in any PCL source use the C preprocessor “#include” command, for example:

#include “appforms.p”

The contents of these files are described later in this chapter.

Whenever these include files are used in PCL source code the source file must be sent through a C preprocessor and the resulting preprocessed file used in the PCL compilation. The PCL compiler does not understand C preprocessor commands and they will cause errors if the source file is not first preprocessed.

See The C Preprocessor, 31 for more about use of the C preprocessor in PCL and other language source files.

General FormsIf these values are used it is recommended that “UL” is used for the fourth argument in the ui_form_create() call, position, to reference the upper left corner. The diagram below shows the sizes provided.

PCL and CustomizationGeneral Form Style

226

Standard Form Widths

FORM_WID_SML Use for Application Forms and forms where a SINGLE column of widgets is desired.

FORM_WID_MED Use for forms where a DOUBLE column of widgets is desired or where wide widgets are needed.

FORM_WID_LRG Use for forms where a TRIPLE column of widgets is desired or where extra wide widgets are needed.

Special Form Width

FORM_WID_SPL Use for forms that are 1.5 times a normal or small form width. This form size is good for file forms and forms that include a color bar.

Standard Form Heights

FORM_HGT_TALL FULL height is for forms that extend from the top menu to the bottom of the screen and Application Forms.

FORM_HGT_3_QTRS

3_QTRS height is for forms 3/4 of a full height form.

FORM_HGT_5_8THS 5_8THS height is for forms 5/8 of a full height form.

FORM_HGT_HALF HALF height is for forms half of a full height form.

227Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

FORM_HGT_3_8THS 3_8THS height is for forms 3/8 of a full height form.

FORM_HGT_QTR QTR height is for forms one quarter of a full height form.

Important:Other form heights may be obtained by adding heights together.

Form Margins

FORM_L_MARGIN Left margin for placing frame widgets.

FORM_R_MARGIN Right margin between frame and right side of form.

FORM_T_MARGIN Top margin for placing widgets on form.

FORM_B_MARGIN Bottom margin for placing widgets on form.

Form Placement X Locations

FORM_X_LOC Normal form x location.

FORM_X_LOC_SML Normal form x location (same as FORM_X_LOC).

FORM_X_LOC_SPL Normal special (1.5 times small) form x location.

FORM_X_LOC_MED Normal medium width form location.

FORM _X_LOC_LRG Normal large width form location.

FORM_X_LOC_SML_NX2_SML Place a small form next to a small form.

FORM_X_LOC_2ND_SML_NX2_SML Place a second small form next to a small form (result is three small forms).

FORM_X_LOC_SPL_NX2_SML Place a special (1.5 times small) form next to a small form.

FORM_X_LOC_MED_NX2_SML Place a medium form next to a small form.

FORM_X_LOC_LRG_NX2_SML Place a large form next to a small form.

FORM_X_LOC_SML_NX2_MED Place a small form next to a medium form.

FORM_X_LOC_SPL_NX2_MED Place a special (1.5 times small) form next to a medium form.

FORM_X_LOC_MED_NX2_MED Place a medium form next to a medium form.

FORM_X_LOC_SML_NX2_LRG Place a small form next to a large form.

FORM_X_LOC_SML_CEN Center a small form.

FORM_X_LOC_SPL_CEN Center a special (1.5 times small) form.

FORM_X_LOC_MED_CEN Center a medium form.

FORM_X_LOC_LRG_CEN Center a large form.

PCL and CustomizationGeneral Form Style

228

Keeping Track of Y Location for Widgets

Y locations are relative to the form. Keep in mind the form margins, label heights and the height of each widget.

Once a form is placed, the y location of the widgets inside the form are relative to the form. The total height of the items inside each form and the top and bottom form margins need to be added to the variable that keeps track of position on the form.

Form Placement Y Locations

FORM_Y_LOC Place a form under the main menu bar.

FORM_Y_LOC_HALF_CEN Center a half of full height form between the main menu bar and the command line.

FORM_Y_LOC_3_8THS_CEN Center a 3/8 of full height form between the main menu bar and the command line.

FORM_Y_LOC_QTR_CEN Center a quarter of full height form between the main menu bar and the command line.

Other Form Variables

The following variables are the widths of the colored areas outside the form.

FORM_L_BORDER The width of the dark border at the left side of the form.

FORM_R_BORDER The width of the dark border at the right side of the form.

FORM_T_BORDER The width of the dark border at the top of the form.

FORM_B_BORDER The width of the dark border at the bottom of the form.

Spacing Between Widgets

Spacing is based on the height of the font being used for widget labels. Try to use at least a HALF_SPACE between widgets. The spacing variables listed below are listed in order of size.

QTR_SPACE 1/4 of a single font height.

HALF_SPACE 1/2 of a single font height.

INTER_WIDGET_SPACE 3/4 of a font height.

FONT_HGT Font height in inches.

SINGLE_SPACE A font height in inches.

ONE_AND_HALF_SPACE 1.5 times a font height.

DOUBLE_SPACE 2.0 times a font height.

TEXT_FONT_HEIGHT Font height of Text Widget in inches.

Create spacing variables by multiplying any of the variables above by other variables or by numbers (i.e., 2 * DOUBLE_SPACE).

229Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

In PCL, it is a good idea to define a real variable as follows:

Use y_loc to keep track of location on the form. For example:

General WidgetsThere are general widgets such as

REAL y_loc

y_loc = y_loc + INTER_WIDGET_SPACE

PCL and CustomizationGeneral Form Style

230

Select Frame

Select Frames Select frames are used to group select databoxes.

Buttons Buttons may be used to bring up additional forms or to select an action such as Go, Cancel, Reset, Abort, etc. Buttons that bring up forms should have an ellipsis, (...), included with the button label.

Label Labels are not selectable; they provide information.

Functions Select frames are thicker and shadowed compared to ordinary frames. They are used to visually and functionally group select databoxes.

The command to create a select frame has an option to place a toggle over the select frame. This is an Automatic Execute toggle. When the toggle is selected, Patran will automatically traverse to the “next” select databox and will optionally execute a button callback after the last select databox is satisfied.

The select frame is used to contain select databoxes. Select databoxes are databoxes that offer the ability to filter the types of entities that may be processed.

Select databoxes may have input focus cycled by setting the logical parameter recycle to TRUE. When “recycle” is set to TRUE, the first databox in the select frame regains input focus after the last databox in the select frame loses input focus. When “recycle” is set to FALSE, the default button is activated after the last databox in the select frame loses input focus.

Restrictions • There should be margins separating the select frame from the parent form.

• Only select databoxes may be contained within a select frame.

• Select databoxes inside the select frame are positioned relative to the upper left corner of the select frame.

Placement Select frames are placed with respect to the upper left hand corner of their parent form. The following variables have been provided to help place select frames.

Select Frame Widths:

SFRAME_WID_SINGLE Use for small forms and for select frames in single columns of larger forms.

SFRAME_WID_SPECIAL Use for special forms (1.5 times small) and for select frames that span 1.5 columns of larger forms.

231Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

SFRAME_WID_DOUBLE Use for medium forms and for double width select frames that span 2 columns of a medium or a large form.

SFRAME _WID_TRIPLE Use for large forms for select frames that span 3 columns of a large form.

Select Frame Height

Select frames contain only select databoxes. The following variables have been provided to determine the height needed for a select frame depending upon the number of select databoxes it contains and whether the select databoxes have labels or not.

SFRAME_nSDB_HGT_LABOVE Height of a select frame that contains n labeled select databoxes.*

SFRAME_nSDB_HGT_NO_LABOVE

Height of a select frame that contains n select databoxes without labels.*

SFRAME_HGT_LABOVE_INCR Increment for computing the height of a select frame with more than 5 labeled select databoxes in it.

SFRAME_HGT_NO_LABOVE_INCR

Increment for computing the height of a select frame with more than 5 unlabeled select databoxes in it.

Select Frame X Locations

SFRAME_X_LOC_COL1 Location of a select frame that starts in the leftmost column of any size form.

SFRAME_X_LOC_COL2 Location of a select frame that starts in the second column from the left of a medium or large form.

SFRAME_X_LOC_COL3 Location of a select frame that starts in the third column from the left of a large form.

Select Frame Label

Select frames may have a toggle above the select frame.

SFRAME_LABEL_HGT Height of the Label and its associated toggle above a select frame.

Select Frame Margins

SFRAME_L_MARGIN Distance between select frame and left side of select databox.

PCL and CustomizationGeneral Form Style

232

Example 1: Create a Select Frame

ui_selectframe_create(parent_id, “go_button_callback”,@ SFRAME_X_LOC_COL1, y_loc,@SFRAME_WID_SIZE, SFRAME_nSDB_LABOVE,@“Auto Execute”, logical_recycle)

The y_loc for locating the next widget on the form is calculated by adding the height of the label of the select frame, the height of the select frame, the thickness of the select frame edge on top and bottom plus a spacing factor to the y_loc that was used to place the select frame.

y_loc = y_loc + SFRAME_LABEL_HGT + @SFRAME_nSDB_LABOVE +@SFRAME_2EDGE +@INTER_WIDGET_SPACE

If the select databoxes inside the select frame do not have labels, substitute SRAME_nSDB_NO_LABOVE in the above equation.

SFRAME_R_MARGIN Distance between select frame and right side of select databox.

SFRAME_T_MARGIN Distance between select frame and top of first select databox inside select frame.

SFRAME_B_MARGIN Distance between select frame and last select databox inside select frame.

Select Frame Thickness

SFRAME_1EDGE Thickness of a select frame edge.

SFRAME_2EDGE Thickness of two select frame edges (i.e., top and bottom or left and right).

*For select frames with additional select databoxes, add increments, n (from 1 to 5 only), select databoxes within a select frame.

233Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

Labell

Example 1: Create a Label Widget

Use the following command to create a label widget without a frame.

label = ui_label_create( @ /* parent */ parent_form, @ /* callback */ EMPTY_STR, @ /* x */ UNFRAMED_MARGIN, @ /* y */ y_loc, @ /* label */ “label_text” )

/* Calculate the y location for the next widget */y_loc = y_loc + LABEL_HGT + INTER_WIDGET_SPACE

Function A Label widget is used to supply information to the user.

Restrictions • The first letter should be in upper case; rules for titles should be observed, that is, important words should be capitalized.

• Label text is left justified.

• Label widgets do not have callbacks. Use a blank ““ or EMPTY_STR for this parameter.

Placement Label widgets are placed with respect to the upper left corner of their parent form. The following variables have been provided to help place labels.

The x location for an unframed label widget is:

UNFRAMED_L_MARGIN

Use the variable:

LABEL_HGT

and a spacing variable such as INTER_WIDGET_SPACE or SINGLE_SPACE to calculate the y location for the next widget.

PCL and CustomizationGeneral Form Style

234

Button

Functions The Button widget is used to:

• Bring up another form.

• Put away a form.

• Perform an action.

Restrictions • Height of the buttons should be the letter height, i.e., when the button is created, let the height = 0.0 or ZERO to default to font height.

• The width of buttons should be the same for all buttons on a line, except for default buttons, which have a border around them.

• Buttons should be arranged from the most used to the least used, or “positive” to “negative,” or sequence of use.

• Default buttons.

When there is only one button on a form, that button should be set to be the default one. For example:

When a button is used frequently (or most likely to be used), then it should be defaulted.

If there is just “Apply” and “Cancel,” then “Apply” should be the default one. For example:

Try to have a default, usually the left-most button.

235Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

The following variables have been provided to help size and place buttons:

• Combinations.

“Update” buttons should have “Reset” buttons on the same form.

Follow the sequence: “Create,” “Rename,” and “Delete” on a form that has such buttons.

• Buttons that bring up forms should have an ellipsis (...) after the label.

• Labels for buttons:

Yesindicates a positive response and closes form.

Noindicates a negative response and closes form.

Updateupdates any changes made to the form.

Resetresets any changes to the form when the form was last saved.

OKupdates and closes the form.

Cancelresets the form and closes; this should not undo the update.

Applyperforms the action specified by the label.

Keep labels for buttons to 1 word, usually a verb.

Placement • Buttons are placed with respect to their parent form.

Button Width:

BUTTON_WID_FULL This button is as wide as a single column databox. It is good for items with large labels and for buttons that bring up additional forms.

PCL and CustomizationGeneral Form Style

236

Default Buttons:Default buttons have a highlighted border around them to indicate that they are default buttons. The border to the left and right is deducted from the width of the button. The border above the default button is added above the location where the button is positioned.

BUTTON_WID_HALF Use this size for each button when two buttons are placed in a column.

BUTTON_WID_THIRD Use this size for each button when three buttons are placed in a column.

Button Height:

BUTTON_HGT Use for calculating y_loc for placement of next widget. Use 0.0 or ZERO for the button height in the PCL call so that the button height defaults to the font height of the button label.

BUTTON_DEFAULT_HGT Total height of the button including the height of the highlight border above and below.

BUTTON_DEFAULT_BORDER_WID The width of the highlight border at the left or right side of a default button.

BUTTON_DEFAULT_BORDER_HGT The height of the highlight border at the top or bottom of a default button.

Button Locations for First Column:

BUTTON_FULL_X_LOC1 Locates a full size button at left side of form.

BUTTON_HALF_X_LOC1 Locates the first half size button at left side of form.

BUTTON_HALF_X_LOC2 Locates the second half size button on the form.

BUTTON_THIRD_X_LOC1 Locates the first one third size button at left side of form.

BUTTON_THIRD_X_LOC2 Locates the second one third size button on the form.

BUTTON_THIRD_X_LOC3 Locates the third one third size button on the form.

Button Locations for Second Column:

BUTTON_FULL_X_LOC1_COL2 Locates a full size button at left side of column two on form.

BUTTON_HALF_X_LOC1_COL2 Locates a half size button at left side of column two on form.

BUTTON_HALF_X_LOC2_COL2 Locates a second half size button in column two on form.

BUTTON_THIRD_X_LOC1_COL2 Locates a one third size button at the first location of column two on form.

237Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

BUTTON_THIRD_X_LOC2_COL2 Locates a second one third size button at the second location of column two on form.on form.

BUTTON_THIRD_X_LOC3_COL2 Locates a third one third size button in position 3 of column two on form.

Button Locations for Third Column:

BUTTON_FULL_X_LOC1_COL3 Locates a full size button at left side of column three on form.

BUTTON_HALF_X_LOC1_COL3 Locates a half size button at left side of column three on form.

BUTTON_HALF_X_LOC2_COL3 Locates a second half size button in column three on form.

BUTTON_THIRD_X_LOC1_COL3 Locates a one third size button at the first location of column three on form.

BUTTON_THIRD_X_LOC2_COL3 Locates a second one third size button at the second location of column three on form.on form.

BUTTON_THIRD_X_LOC3_COL3 Locates a third one third size button in position 3 of column three on form.

Button Center Location on a Small (Single Column) Form:

BUTTON_FULL_X_LOC_CEN Center a full size button on a small single column form.

BUTTON_HALF_X_LOC_CEN Center a half size button on a small single column form.

BUTTON_THIRD_X_LOC_CEN Center a one third size button on a small single column form.

Button Center Location on a Medium (Double Column) Form:

BUTTON_FULL_X_LOC_CEN_MED Center a full size button on a medium double column form.

BUTTON_HALF_X_LOC_CEN_MED Center a half size button on a medium double column form.

BUTTON_THIRD_X_LOC_CEN_MED Center a one third size button on a medium double column form.

Button Center Location on a Large (Triple Column) Form:

BUTTON_FULL_X_LOC_CEN_LRG Center a full size button on a large triple column form.

BUTTON_HALF_X_LOC_CEN_LRG Center a half size button on a large triple column form.

BUTTON_THIRD_X_LOC_CEN_LRG Center a one third size button on a large triple column form.

PCL and CustomizationGeneral Form Style

238

Example 1: Center a Button on a Form

ui_button_create( @ /* parent */ “parent”, @ /* callback */ "callback", @ /* x */ BUTTON_SIZE_X_LOC_CEN, @ /* y */ y_loc, @ /* width */ BUTTON_WID_SIZE, @ /* height */ 0.0, @ /* label */ “button_label” @ /* labelinside */ TRUE, @ /* highlight */ FALSE )

where SIZE is FULL, HALF or THIRD. Add _COL2 or _COL3 to BUTTON_SIZE_X_LOC_CEN to center a button on a medium 2 column form or on a large 3 column form.

Example 2: Create Three Buttons in a Column

Create three buttons on a small form. The button on the left is a default button. Use one third size buttons.

When a default button is used, add a default border height to the y location before placing the set of button widgets. The highlight border of the default button goes above the y location used to position the buttons. This occurs so that default buttons and plain buttons on the same line are aligned with one another.

y_loc = y_loc + BUTTON_DEFAULT_BORDER_HGT

Create the first button and make it the default button. Note that the button height parameter in the ui_button_create() call is set to 0.0 or ZERO. This is done to let the button height default to the font height.

ui_button_create( /* parent */ form-id,@/* callback */ “callback”, @ /* x */ BUTTON_THIRD_X_LOC1, @ /* y */ y_loc, @ /* width */ BUTTON_WID_THIRD, @ /* height */ 0.0,@/* label */ “button_label1”, @ /* labelinside */ TRUE,@/* highlight */ TRUE ) Create the second button. ui_button_create( /* parent */ form-id,@/* callback */ “callback”, @ /* x */ BUTTON_THIRD_X_LOC2, @ /* y */ y_loc, @ /* width */ BUTTON_WID_THIRD @ /* height */ ZERO,@/* label */ “button_label2”, @ /* labelinside */ TRUE,@/* highlight */ FALSE ) Create the third button. ui_button_create( /* parent */ form-id,@/* callback */ “callback”, @ /* x */ BUTTON_THIRD_X_LOC3, @ /* y */ y_loc, @ /* width */ BUTTON_WID_THIRD @ /* height */ ZERO,@/* label */ “button_label3”, @ /* labelinside */ TRUE,@/* highlight */ FALSE ) @

Compute the next y location considering the border at the bottom of the default button. y_loc = y_loc + BUTTON_HGT @

239Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

+ BUTTON_DEFAULT_BORDER_HGT @ + INTER_WIDGET_SPACE

Add _COL2 or _COL3 to BUTTON_THIRD_X_LOCn to create buttons in the second column of a medium 2 column form or a large 3 column form or to create buttons in the third column of a large 3 column form.

Example 3: Unique Buttons

If fewer than the maximum number of buttons that will fit across a form is used, keep the standard positions as much as possible.

If dividing the form into columns, keep the odd button centered to the column to which it relates.

Box WidgetsThere are box type widgets such as:

PCL and CustomizationGeneral Form Style

240

DataBox

databox Databoxes are used for entering data. Labels may be placed above or to the left of the databox. A label to the left of a databox has an equal sign “=” included.

select databox The select databox provides an opportunity to enter either typed input data or graphical data. Select databoxes must be enclosed in a select data frame. A select databox is labeled but no equal signs or colons are allowed.

Function Databoxes are used for entering data.

Restrictions • Labels are only placed above or to the left of the databox.

• Labels above the databox cannot have equal signs or any symbols following the label. For example:

• Labels to the left must have an equal sign following the label and nothing else.

Placement Databoxes are placed with respect to the upper left hand corner of their parent form. The following variables have been provided to help place databoxes.

Databox Width:

DBOX_WID_SINGLE A single column width databox.

DBOX_WID_SPECIAL A 1 1/2 column width databox.

DBOX_WID_DOUBLE A two column width databox.

DBOX_WID_TRIPLE A three column width databox.

Databox Height:

DBOX_HGT_LABOVE The height of one databox with a label above.

DBOX_HGT_NO_LABOVE The height of one databox without a label.

241Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

The width of the databox next to the label is calculated as follows:

wid =DBOX_WID_SIZE - @ DBOX_LABEL_LEN_SIZE - @ DBOX_LABEL_X_OFFSET where SIZE = SINGLE, SPECIAL, DOUBLE or TRIPLE

Example 1: Place a databox on a form

ui_databox_create( /* parent */ “parent_frame”, @ /* callback */ EMPTY_STR, @ /* x */ UNFRAMED_L_MARGIN, @ /* y */ y_loc, @ /* label_length */ ZERO, @ /* box_length */ DOUBLE_WID_SINGLE, @ /* label */ "label”, @ /* value */ initial_value, @ /* label_above */ TRUE, @ /* datatype */ "STRING", @ /* num_vals */ num_values )

Calculate the y location for the next databox on the form by adding the databox height and spacing factor together.

y_loc = y_loc + DBOX_HGT_LABOVE + INTER_WIDGET_SPACE

Databox Label Width for Databoxes that are Labeled on the Left:

Use these parameters when “label_above” is FALSE.

DBOX_LABEL_LEN_SINGLE Default label length for a single width databox when label is on left.

DBOX_LABEL_LEN_SPECIAL Default label length for a special (1 1/2 column) width databox when label is on left.

DBOX_LABEL_LEN_DOUBLE Default label length for a double width databox when label is on left.

DBOX_LABEL_LEN_TRIPLE Default label length for a triple width databox when label is on left.

DBOX_LABEL_X_OFFSET Distance between end of label and start of databox.

PCL and CustomizationGeneral Form Style

242

Select Databox

Functions The select databox provides an opportunity to enter either typed input data or graphical data.

Restrictions All select databoxes require a select data frame.

• Labels should be above the select databox. No Equal signs or colons are allowed.

If it is a coordinate frame select databox and the coordinate frame is used for geometric construction purposes only, the label should be:

Refer. Coordinate Frame

If a nodal coordinate system is defined for the purpose of analysis, it should be referred to as:

Analysis Coordinate Frame

Likewise, the material coordinate frame should be referred to as:

Material Coordinate FrameThe same principle applies for other types of coordinate frames.

Placement Select databoxes are placed with respect to the upper left hand corner of their parent select frame. The following variables have been provided to help place databoxes.

Select Databox Width:

SDBOX_WID_SINGLE A single column width select databox.

SDBOX_WID_SPECIAL A 1 1/2 column width select databox.

SDBOX_WID_DOUBLE A two column width select databox.

SDBOX_WID_TRIPLE A three column width select databox.

Select Databox Height:

SDBOX_HGT_LABOVE The height of one select databox with a label above.

SDBOX_HGT_NO_LABOVE The height of one select databox without a label.

Select Databox Placement Y Location:

SDBOX_Y_LOCn _LABOVE Place a select databox with a label above inside a select frame.*

SDBOX_Y_LOCn _NO_ABOVE Place an unlabeled select databox inside a select frame.*

243Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

The width of the select databox next to the label is calculated as follows:

wid = SDBOX_WID_SIZE @ - SDBOX_LABEL_LEN_SIZE @ - SDBOX_LABEL_X_OFFSETwhere SIZE = SINGLE, SPECIAL, DOUBLE or TRIPLE

Example 1: Place Two Select Databoxes within a Select Frame

The first step is to create the select frame. The size of the select frame depends upon the number of labeled select databoxes within the select frame. The height of n databoxes inside a select frame using the standard interwidget space is:

SFRAME_nSDB_HGT_LABOVE

where n may be 1 through 5.

To put n more labeled select databoxes inside the frame, add n select frame increments to a five select databox height:

n * (SFRAME_HGT_LABOVE_INCR)

Place two labeled select databoxes inside a select frame.

sframe_height = SFRAME_2SDB_HGT_LABOVEui_selectframe_create (/* parent */ parent_form, @ /* callback */ “callback”, @

*To calculate the location of each additional select databox, add the increment, n (from 1 to 5 only), to each select databox location.

SDBOX_Y_LABOVE_INCR Increment for creating the y location for more than 5 select databoxes with labels inside a select frame.

SDBOX_Y_NO_LABOVE_INCR Increment for creating the y location for more than 5 select databoxes without labels inside a select frame.

Label Width for Select Databoxes Labeled on the Left:

Use these parameters when “label_above” is FALSE.

SDBOX_LABEL_LEN_SINGLE Default label length for a single width select databox when label is on left.

SDBOX_LABEL_LEN_SPECIAL Default label length for a special width (1 and 1/2 column) select databox when label is on left.

SDBOX_LABEL_LEN_DOUBLE Default label length for a double width select databox when label is on left.

SDBOX_LABEL_LEN_TRIPLE Default label length for a triple width select databox when label is on left.

SDBOX_LABEL_X_OFFSET Distance between end of label and start of select databox.

PCL and CustomizationGeneral Form Style

244

/* x */ FORM_L_MARGIN, @ /* y */ y_loc, @ /* width */ SFRAME_WID_SINGLE, @ /* height * sframe_height, @ /* label */ “toggle_label”, @ /* recycle */ logical_recycle ) The command to use to place the first select databox inside a select frame is:/* x */ SFRAME_L_MARGIN, @ /* y */ SDBOX_Y_LOC1_LABOVE, @/* label_length */ ZERO, @ /* box_length */ SDBOX_WID_SINGLE, @ /* label */ “label”, @/* value */ initial_value, @/* label_above */ TRUE, @ /* datatype */ “acceptable_datatype”, @/* prompt */ “prompt” ) Create the second select databox. /* x */ SFRAME_L_MARGIN, @ /* y */ SDBOX_Y_LOC2_LABOVE, @/* label_length */ ZERO, @ /* box_length */ SDBOX_WID_SINGLE, @ /* label */ “label”, @/* value */ initial_value, @/* label_above */ TRUE, @ /* datatype */ “acceptable_datatype”,/* prompt */ “prompt” )

After all the select databoxes have been placed in the select frame, to place the next new widget, calculate the y location by adding the height of the toggle of the select frame, the height of the select frame, the thickness and an interwidget spacing factor:

sframe_height + SFRAME_2EDGE + INTER_WIDGET_SPACE

Switch

The ncolumns parameter does not work intuitively for most values. The number of switch items is divided by the number of columns. One is added if a remainder was truncated. The result is used as the number of rows. The items are then added to the switch in row-major format. For example, if ncolumns is three and four switch items are supplied, the following will appear:

item1item3

Functions Switches are used for grouping items which allow only one of its items to be selected.

Restrictions • Positioned relative to the parent form.

• Switch items appear in the order in which they are created.

Placement Switches are placed with respect to the upper left hand corner of their parent form. A switch contains an arbitrary number of item widgets. Only one of the item widgets may be set to ON at any given time; setting an item ON automatically sets all other items in the switch OFF. If one item is set to FALSE, clicking on an ON item may set it to OFF depending on the value of the always_one in the ui_switch_create() call. Items in switches are organized vertically.

245Chapter 5: User Interface and List Processor FunctionsGeneral Form Style

item2item 4

The following variables have been provided to help place switches.

Switch Width:The width of a switch is determined by the number of columns and the length of the text strings that represent the items.

To calculate the height of each additional row, take the difference of a three and a four row switch and add it to the four row switch.

Switch Height:

SWITCH_1R_HGT_LABEL The height of a one row switch with a label.

SWITCH_2R_HGT_LABEL The height of a two row switch with a label.

SWITCH_3R_HGT_LABEL The height of a three row switch with a label.

SWITCH_4R_HGT_LABEL The height of a four row switch with a label.

Switch Height Unlabeled:

SWITCH_1R_HGT_NO_LABEL The height of a one row switch without a label.

SWITCH_2R_HGT_NO_LABEL The height of a two row switch without a label.

SWITCH_3R_HGT_NO_LABEL The height of a three row switch without a label.

SWITCH_4R_HGT_NO_LABEL The height of a four row switch without a label.

additional_row = SWITCH_4R_HGT_LABEL - SWITCH_3R_HGT_LABEL

PCL and CustomizationCreating Forms and Widgets Using PCL

246

Creating Forms and Widgets Using PCLAs an example of using PCL to create a form and some widgets, the PCL Class uil_list_boolean is shown. The purpose of this Class is to display the form and all the widgets which appear when the “Boolean...”pick is selected under List in the Main Menu. Actually, three forms come up, the “List A” form, the “List B” form and the “Boolean List” form. The uil_list_boolean Class controls the “List Boolean” form. The form contains an icon switch with four icons, a list box, five buttons and a separator. The form looks like this:

The Class uil_list_boolean contains nine functions which are:

1. init - Creates all the widgets displayed on the form and the form itself.

2. display - Displays the form and all its widgets.

3. bool_cb - Callback for boolean switch, calls uil_list_boolean.create.

4. create - performs boolean operation on the list.

5. save_cb - Callback from “Add to Group...” button.

6. repa_cb - Callback for “Replace A” button.

7. repb_cb - Callback for “Replace B” button.

8. hilight_cb - Callback for “Highlight” button.

9. cancel_cb - Callback for “Cancel” button.

247Chapter 5: User Interface and List Processor FunctionsCreating Forms and Widgets Using PCL

To display the form type ui_exec_function(“uil_list_boolean”,“display”) in the command line.

Style and Externalization

Add the start of the uil_list_boolean Class are three lines as follows:

#include “appforms.p”#include “appstrings.p”#include “msg_list.i”

These are references to files which are used in conjunction with the C pre-processor or cpp.

See The C Preprocessor, 31for more about use of the C preprocessor in PCL and other language source files.

The first file “appforms.p” can be found in the delivery directory along with p3. It contains define strings which look like:

#define TBOX_WID_SINGLE uil_form_sizes.tbox_wid( 1 )#define TBOX_WID_DOUBLE uil_form_sizes.tbox_wid( 2 )#define TBOX_WID_TRIPLE uil_form_sizes.tbox_wid( 3 )#define TBOX_WID_SPECIAL uil_form_sizes.tbox_wid( 4 )(Excerpt from appforms.p)

and are used to position and size widgets on the form which is described in the section General Form Style, 225. The second file, “appstrings.p”, also contains define strings but are used to externalize the displayed text for internationalization. The last file, “msg_list.i” contains the define strings for defining the unique error codes used by the message facility, i.e., msg_to_form() for displaying error messages.

uil_list_boolean.init

The init function contains all of the PCL calls to create the forms and widgets. The call to create the form itself is:

bool_form = ui_form_create( @ /* callback */ ““, @ /* x */ FORM_X_LOC_SML, @ /* y */ FORM_Y_LOC, @ /* position */ “UL”, @ /* width */ FORM_WID_SML, @ /* height */ FORM_HGT_HALF, @ /* label */ “Boolean List”, @ /* iconname */ ““)

The define strings FORM_X_LOC_SML, FORM_Y_LOC, FORM_WID_SML and FORM_HGT_HALF can all be found in “appforms.p”. The List Boolean form is a small form located in the standard position to the far right of the display directly beneath the Main Menu. The call to ui_form_create returns the widget id which was declared as classwide:

CLASSWIDE widget bool_form,boolean_switch,text_box,save_btn,sdbox,sframe

Note that there is no callback for a form and that the label on the title bar at the top of the form says “Boolean List”.

PCL and CustomizationCreating Forms and Widgets Using PCL

248

Next, we create a selectframe and selectdatabox which will be used to highlight all the resulting entities in the list after the boolean operation (‘listc‘). These widgets will never be made visible. This is necessary since the call gm_hilight_widget takes a widget id of a selectdatabox to highlight the entities contained within. To hide the widgets we make a call to ui_wid_set as and set the “DISPLAY” parameter as follows:

ui_wid_set(sdbox,“DISPLAY”,False)ui_wid_set(sframe,“DISPLAY”,False)

Now, we create the icon switch. We begin be creating the switch itself:

boolean_switch = ui_switch_create @/* parent */ (bool_form, @ /* callback */ “bool_cb”, @ /* x */ .01, @ /* y */ y_pos,@ /* cols */ 4, @ /* label */ “Operation:”, @ /* alwayson */ TRUE)

Its parent is the form and the callback is “bool_cb”. The switch has four columns, one for each of the boolean icons (only one row). The title of the switch is “Operation” and one of the items must always be selected.

Once the switch is created, we can add item icons as follows:

ui_itemicon_create @ ( boolean_switch, “and”, “and_bool.icon”, TRUE ) ui_itemicon_create @ ( boolean_switch, “or”, “or_bool.icon”, FALSE ) ui_itemicon_create @ ( boolean_switch, “a-b”, “minus_bool.icon”,FALSE ) ui_itemicon_create @ ( boolean_switch, “b-a”, “b_minus_a_bool.icon”,FALSE )

Each icon is given a name which is returned in the callback argument bool_cb(name) to indicate which switch was selected. The third argument to ui_itemicon_create is the file name which contains the bitmap for the icon. The file must exist in the PCL path, otherwise the “bart” icon will appear in its place. In our example, the “and” boolean is selected by default. To create icon files, use the UNIX or Windows NT utility bitmap.

Once all the widgets are created and placed on the form, the form is re-sized to just fit the last widget. The pcl variable, y_pos, contains the current location just beneath the last widget created (The apply button). By setting the “HEIGHT” parameter for the form with a call to ui_wid_set and passing y_pos, the form will be properly resized.

/** Set the form height*/

ui_wid_set(bool_form, “HEIGHT”, y_pos)ui_set_focus(text_box)select_focus.exit()

The display function

The display function displays both the List Boolean form and the List A and List B forms. Try to always use ui_exec_function to display forms so that the init function only gets called once. The

249Chapter 5: User Interface and List Processor FunctionsCreating Forms and Widgets Using PCL

function ui_register_help is used to provide context sensitive help to the form so that when the cursor is on the form and the F1 key is pressed, the help for the boolean form appears.

FUNCTION display

ui_exec_function( “uil_list_a”, “display” )ui_exec_function( “uil_list_b”, “display” )ui_form_display( “uil_list_boolean” )

ui_register_help(bool_form,“uil_list_boolean”)

END FUNCTION /* display */

The icon switch callback: bool_cb

If the user selects any of the boolean icons on the switch, the callback function bool_cb is called. It has two arguments (see Callbacks, 221 the first is the name of the icon item selected or unselected and the second is a string indicating if it was selected or unselected, “ON” or “OFF” respectively. bool_cb is only concerned if an icon was selected, so the test for “ON” is only checked. The function uil_list_boolean.create actually performs the boolean operation which is shown later. Note that the reason a separate routine was needed to perform the operation was because it stand alone to be valid in the session file. The “>” at the beginning of the line indicates that the PCL command appears in the session file when executed.

FUNCTION bool_cb( boolean, onoff )

GLOBAL STRING listc[VIRTUAL] STRING boolean[],onoff[]

IF (onoff == “ON”) THEN

> uil_list_boolean.create(boolean)

ui_wid_set( text_box, “VALUE”, listc )

END IF

END FUNCTION /* bool_cb */After the boolean operation is performed, the contents of the databox is updated with the global PCL variable listc. uil_list_boolean.create modifies the contents of listc based on the selected boolean operation./****************************************************************/ FUNCTION create(boolean) GLOBAL String listc[VIRTUAL],lista[VIRTUAL],listb[VIRTUAL] STRING boolean[] INTEGER status status = list_create_boolean_list(lista,listb,boolean,listc) END FUNCTION /* create *//****************************************************************/

uil_list_boolean listing

A listing of the contents of the Class follows:

/*$$ UIL List Boolean Form (uil_list_boolean) * * Purpose: * Create the List boolean form* * Side effects:

PCL and CustomizationCreating Forms and Widgets Using PCL

250

* A small form is created (List Boolean) in the third column(panel) * which contains a icon switch, a list contents textbox, an * “Add to Group...” button, a “Enumerate...” button, a “Done” button and * a “Cancel” button. * * The icon switch determines which operation applies to the * contents of two related forms, “List A’ and List B”. See * PCL Classes uil_list_a and uil_list_b for further details. * In each of the other forms is a text box with a list defined * in them. The switch determines which boolean operation is to * apply to both and applies it and places the result in the textbox * “List Contents”. * * Note: * To properly display this form call uil_list_save.load. Do * not call uil_list_save.display * */

#include “appforms.p”#include “appstrings.p”#include “msg_list.i”

CLASS uil_list_boolean

CLASSWIDE WIDGET bool_form,boolean_switch,text_box,save_btn,sdbox,sframe CLASSWIDE WIDGET hilight_btn,repa_btn,repb_btn,cancel_btn

/*$$ FUNCTION init * * Purpose: * Initialize the LIST CREATE GRID ATTRIBUTE form panel * * Input: * <none> * * Output: * <none> */

FUNCTION init

/* * Local Declarations: */

REAL x_pos, y_pos

/* * Create the “List A” form */

bool_form = ui_form_create( @ /* callback */ ““, @ /* x */ FORM_X_LOC_SML, @ /* y */ FORM_Y_LOC, @ /* position */ “UL”, @ /* width */ FORM_WID_SML, @ /* height */ FORM_HGT_HALF, @ /* label */ “Boolean List”, @ /* iconname */ ““)

/* * Create the operation option menu. */

y_pos = FORM_T_MARGIN

251Chapter 5: User Interface and List Processor FunctionsCreating Forms and Widgets Using PCL

sframe = ui_selectframe_create @ /* parent */( bool_form, @ /* callback */ ““, @ /* x */ FORM_L_MARGIN, @ /* y */ y_pos, @ /* width */ SFRAME_WID_SINGLE, @ /* height */ SFRAME_1SDB_HGT_LABOVE, @ /* label */ ““, @ /* recycle */ FALSE )

sdbox = ui_selectdatabox_create @ /* parent */ ( sframe, @ /* callback */ ““, @ /* x */ FORM_L_MARGIN, @ /* y */ y_pos, @ /* label len*/ 0.0, @ /* width */ SDBOX_WID_SINGLE, @ /* label */ ““, @ /* value */ ““, @ /*label_above*/ FALSE, @ /*datatype */ “ANY”, @ /* prompt */ ““ )

ui_wid_set(sdbox,“DISPLAY”,False) ui_wid_set(sframe,“DISPLAY”,False)

boolean_switch = ui_switch_create @ /* parent */ ( bool_form, @ /* callback */ “bool_cb”, @ /* x */ .01, @ /* y */ y_pos,@ /* cols */ 4, @ /* label */ “Operation:”, @ /* alwayson */ TRUE )

ui_itemicon_create @ ( boolean_switch, “and”, “and_bool.icon”, TRUE ) ui_itemicon_create @ ( boolean_switch, “or”, “or_bool.icon”, FALSE ) ui_itemicon_create @ ( boolean_switch, “a-b”, “minus_bool.icon”,FALSE ) ui_itemicon_create @ ( boolean_switch, “b-a”, “b_minus_a_bool.icon”,FALSE )

y_pos += 40. * PIXEL_WID + 5. * INTER_WIDGET_SPACE

/* * Create the list contents text box. */

text_box = ui_text_create( @ /* parent */ bool_form, @ /* callback */ ““, @ /* x */ UNFRAMED_L_MARGIN, @ /* y */ y_pos, @ /* width */ TBOX_WID_SINGLE, @ /* Num. Cols*/ 6, @ /* Label */ “‘listc‘ contents:”, @ /* contents */ ““, @ /* edit? */ FALSE )

y_pos += TBOX_5L_HGT_LABOVE + INTER_WIDGET_SPACE + @ TBOX_1L_HGT_NO_LABOVE

/* * Create the Add To Group... button.

PCL and CustomizationCreating Forms and Widgets Using PCL

252

*/

save_btn = ui_button_create( @ /* parent */ bool_form, @ /* callback */ “save_cb”, @ /* x */ BUTTON_HALF_X_LOC1, @ /* y */ y_pos, @ /* width */ BUTTON_WID_FULL, @ /* height */ 0., @ /* label */ “Add To Group...”, @ /* labelinside */ TRUE, @ /* highlight */ FALSE )

x_pos = 0.0 y_pos += BUTTON_HGT + INTER_WIDGET_SPACE

repa_btn = ui_button_create( @ /* parent */ bool_form, @ /* callback */ “repa_cb”, @ /* x */ BUTTON_HALF_X_LOC1, @ /* y */ y_pos, @ /* width */ BUTTON_WID_HALF, @ /* height */ 0., @/* label */ “Replace A”, @/* labelinside */ TRUE, @/* highlight */ FALSE )

/* * Create the Cancel button. */

repb_btn = ui_button_create( @ /* parent */ bool_form, @ /* callback */ “repb_cb”, @ /* x */ BUTTON_HALF_X_LOC2, @ /* y */ y_pos, @ /* width */ BUTTON_WID_HALF, @ /* height */ 0., @ /* label */ “Replace B”, @ /* labelinside */ TRUE, @ /* highlight */ FALSE )

y_pos += BUTTON_HGT + INTER_WIDGET_SPACE

/* * Add a separator */

ui_separator_create( @ /* parent */ bool_form, @ /* callback */ ““, @ /* x */ x_pos, @ /* y */ y_pos, @ /* length */ FORM_WID_SML, @ /* horizontal */ TRUE )

y_pos += LINE_THICKNESS + INTER_WIDGET_SPACE

/* * Create the Hilight button. */

hilight_btn = ui_button_create( @ /* parent */ bool_form, @ /* callback */ “hilight_cb”, @

253Chapter 5: User Interface and List Processor FunctionsCreating Forms and Widgets Using PCL

/* x */ BUTTON_HALF_X_LOC1, @ /* y */ y_pos, @ /* width */ BUTTON_WID_HALF, @ /* height */ 0., @ /* label */ “Highlight”, @ /* labelinside */ TRUE, @ /* highlight */ FALSE )

/* * Create the Cancel button. */

cancel_btn = ui_button_create( @ /* parent */ bool_form, @ /* callback */ “cancel_cb”, @ /* x */ BUTTON_HALF_X_LOC2, @ /* y */ y_pos, @ /* width */ BUTTON_WID_HALF, @ /* height */ 0., @ /* label */ “Cancel”, @ /* labelinside */ TRUE, @ /* highlight */ FALSE )

y_pos += BUTTON_HGT + FORM_B_MARGIN

/* * Set the form height */

ui_wid_set( bool_form, “HEIGHT”, y_pos) ui_set_focus(text_box) select_focus.exit()

END FUNCTION /* init */

/*$$ FUNCTION display * * Purpose: * Display the List Boolean form * * Input: * <None> * * Output: * <None> * * Log: * * Notes: * * */ FUNCTION display

ui_exec_function( “uil_list_a”, “display” ) ui_exec_function( “uil_list_b”, “display” ) ui_form_display( “uil_list_boolean” )

ui_register_help(bool_form,“uil_list_boolean”)

END FUNCTION /* display */

/*$$ callback FUNCTION bool_cb * * Purpose: * Combines the lists contained in list A and List B by the * specified boolean operation. *

PCL and CustomizationCreating Forms and Widgets Using PCL

254

* Input: * boolean string[] Item selected from icon switch * onoff string[] not used. * * Output: * <None> * * */ FUNCTION bool_cb( boolean, onoff )

GLOBAL STRING listc[VIRTUAL] STRING boolean[],onoff[]

IF (onoff == “ON”) THEN

> uil_list_boolean.create(boolean)

ui_wid_set( text_box, “VALUE”, listc )

END IF

END FUNCTION /* bool_cb */

/****************************************************************/ FUNCTION create(boolean) GLOBAL String listc[VIRTUAL],lista[VIRTUAL],listb[VIRTUAL] STRING boolean[] INTEGER status status = list_create_boolean_list(lista,listb,boolean,listc) END FUNCTION /* create *//****************************************************************//*$$ FUNCTION save_cb * * Purpose: * Displays the form to save the contents of the list. * * Input: * <None> * * Output: * <None> * * */ FUNCTION save_cb

/* * Get the list and display the save list form */

uil_list_save.load( “listc” )

END FUNCTION /* save_cb *//****************************************************************/ FUNCTION repa_cb

/* * Replace contents of lista with listc */

> uil_list_a.replace()uil_list_a.load()

255Chapter 5: User Interface and List Processor FunctionsCreating Forms and Widgets Using PCL

END FUNCTION /* repa_cb *//****************************************************************/ FUNCTION repb_cb

/* * Replace contents of listb with listc */

> uil_list_b.replace() uil_list_b.load()

END FUNCTION /* repb_cb *//****************************************************************/ FUNCTION hilight_cb

GLOBAL String listc[VIRTUAL]

gm_hilight_widget(sdbox,0)ui_wid_set(sdbox,“VALUE”,listc)gm_hilight_widget(sdbox,-1)

END FUNCTION/****************************************************************//*$$ FUNCTION cancel_cb * * Purpose: * Displays the modal form to evaluate the contents of the list * and display it. * * Input: * <None> * * Output: * <None> * * */ FUNCTION cancel_cb

/* * reset the widget parameters and exit the form */ ui_wid_restore( “uil_list_boolean” ) ui_form_hide( “uil_list_boolean” )

END FUNCTION /* cancel_cb */

END CLASS

PCL and Customizationwidget Function Descriptions

256

widget Function DescriptionsWidgets provide the user an opportunity to interact with Patran. User interaction with a widget is called an event. Widget callback functions in PCL will be called for a variety of widget events. The data passed to PCL for each widget type is described here. See User Interface Functions, 297 for a discussion of the events that lead to the widget callbacks. The arguments passed to the PCL callback function must be declared with the below datatype to avoid a runtime error.

Table 5-1

Widget Type Data Type Description of Callback Data

button No arguments are passed.

buttonicon No arguments are passed.

cascade item Does not register events.

databox string[ ] “GAIN”, “LOSE”, “CR”, or “WIDSET” (if appropriate ui_wid_set ( ) call has been made) depending on which event instigated the callback.

file string[ ]

string[ ]

Complete pathname of file.

“OPEN” or “CANCEL”

form Does not register events.

frame Does not register events.

graph Does not register events.

item Does not register events.

itemicon Does not register events.

label Does not register events.

labelicon Does not register events.

listbox integer

string[ ]()

The number of selected items.

Label of the selected items in the listbox.

menu string[ ] Name of the selected menu item.

modalform Does not register events.

option menu string[ ] Name of the currently selected item.

popup menu string[] Name of the selected item.

scroll frame Does not register events.

select databox string[ ] “GAIN”, “LOSE”, “CR”, “VALUE_CHANGED”or “WIDSET” ( if a call to ui_wid_set 'VALUE' has been made), depending on which event initiated the callback.

select frame No arguments are passed.

257Chapter 5: User Interface and List Processor Functionswidget Function Descriptions

separator Does not register events.

slide bar real

string[ ]

Current value of the slide bar.

“VALUE_CHANGED” or “DRAG”

spread sheet string[ ]

integer

integer

integer

integer

integer

“SELECTED”. To be expanded.

Starting selected column.

Starting selected row.

Ending selected column.

Ending selected row.

Selected layer.

switch string[ ]

string[ ]

Name of the switch item changed.

“ON” or “OFF”, depending on whether the named switch item, argument #1, has just been turned on or off.

text Does not register events.

toggle logical Value of toggle, TRUE or FALSE.

toggleicon logical Value of toggleicon, TRUE or FALSE.

color bar widget

integer

integer

Widget ID of the color bar.

User data specified in the widget creation call.

Selected item.

color menu widget

integer

integer

Widget ID of the color bar.

User data specified in the widget creation call.

New color value.

Table 5-1

Widget Type Data Type Description of Callback Data

PCL and CustomizationList Processor

258

List ProcessorA set of PCL utilities are provided which parse Picklists. Picklists are the character strings which appear in selectdataboxes as a result of cursor selection or the user typing in data. Examples of these strings are:

point 1:8solid 3.2element 1:7:2

The system which supports the Picklist parsing is called the list processor. The list processor evaluates the strings listed above for information that the application can use. The PCL functions described in this section call the list processor. An include file is provided called lpenums.i (referenced by lpenums.p) on the delivery media which is helpful when writing PCL routines which call the list Processor. See The C Preprocessor, 31.

The PCL functions for parsing Picklists are grouped into two categories. The low-level, more flexible PCL functions which begin with the letters lp_ and the remaining routines which are a more “user friendly” interface to the same lp_ routines. Most list processor routines call the database to obtain information about the Picklist. Routines starting with fem_u_ are different in that they just evaluate for ids which don’t require querying the database. The result is improved performance. Note that not all the types of Picklist entities are supported by the higher level routines.

When the list processor evaluates a string such as the ones above, it returns to the user a handle, which points to the beginning of a list of items. Each item (or sublist) has a type, and attributes associated with that type. Some attributes such as label and id will be associated with most sublist types, and others such as the LP_ATTRIBUTE_COORDINATE_FRAME_TYPE attribute will only be associated with one particular item type (in this case a coordinate frame).

The list processor is also capable of evaluating strings such as “1:101:5.” In this case the list processor returns a handle which points at a list of tokens. In this case a token is merely a generic term for the integers (items) that the list contains.

259Chapter 5: User Interface and List Processor FunctionsList Processor

File lpenums.iThe include file lpenums.i contains #define strings used by the list processor functions. The first section of lpenums.i contains encoded integer numbers used by lp_eval() to determine evaluation methods. The second section of lpenums.i contains sublist type filters used by the functions lp_sublist_type() and lp_sublist_count(). The third section of lpenums.i is used by lp_sublist_attribute_get_*() to parse for attributes contained within the sublist.

Evaluation Methods

There are currently eleven different evaluation methods. The different evaluation methods generate different types of lists. The LP_EVAL_PARSE_AND_EXPAND method prepares a list which can be parsed for the number, type and label of all entities in the list. Other evaluation methods can return more specific information such as the location of points or nodes.

/* Evaluation methods for LpEval */ #define LP_EVAL_BARE_PARSE 1 (internal use only) #define LP_EVAL_PARSE_AND_EXPAND 2 (label only) #define LP_EVAL_FOR_TOKENS 3 (tokens only) #define LP_EVAL_FOR_ID 4 (label and id) #define LP_EVAL_FOR_LABEL 5 (label only) #define LP_EVAL_FOR_GEOMETRY 6 (geometric information) #define LP_EVAL_FOR_FEM_DEFINITION 7 (topology, node count, etc...) #define LP_EVAL_FOR_PICKLIST_ENUMERATION 8 (entity type ex.point, curve, node) #define LP_EVAL_FOR_PICKLIST_NORMALIZATION 9 (internal use only) #define LP_EVAL_FOR_PICKLIST_ADD 10 (internal use only) #define LP_EVAL_FOR_PICKLIST_DELETE 11 (internal use only) (Excerpt from lpenums.i)

Sublist Types and Filters

Depending on the Picklist, lp_eval() will prepare different types (sublists) of items. Each type will have different attributes. The SublistType filters are used by the PCL function lp_sublist_type() to verify the type of sublist referenced by the handle. Depending on how the picklist was parsed, each type of sublist will have different attributes associated with it. The filters are also used by lp_sublist_count() to count the number of entities of the specified type in the Picklist.

If a picklist has multiple points, lines and nodes, and the current application only needs to count the number of points and lines, use a geometry filter. Using only LP_SUBLIST_CURVE will count the number of lines whereas using LP_SUBLIST_GEOMETRY will count the number of lines and points and LP_SUBLIST_ANY will count the number of entities in the entire Picklist (points, lines and nodes).

/* SublistType filters for LpSublistType */ #define LP_SUBLIST_POINT_IMMEDIATE 1 #define LP_SUBLIST_VECTOR_IMMEDIATE 2 #define LP_SUBLIST_POINT 4 #define LP_SUBLIST_CURVE 8 #define LP_SUBLIST_SURFACE 16 #define LP_SUBLIST_SOLID 32 #define LP_SUBLIST_GEOMETRY (LP_SUBLIST_POINT_IMMEDIATE + \ LP_SUBLIST_VECTOR_IMMEDIATE + \ LP_SUBLIST_POINT + \

Note: Some evaluation methods are for internal use only.

PCL and CustomizationList Processor

260

LP_SUBLIST_CURVE + \ LP_SUBLIST_SURFACE + \ LP_SUBLIST_SOLID) #define LP_SUBLIST_COORD_FRAME 64 #define LP_SUBLIST_VECTOR 128 #define LP_SUBLIST_AXIS 256 #define LP_SUBLIST_NODE 512 #define LP_SUBLIST_ELEMENT 1024 #define LP_SUBLIST_MPC 2048 #define LP_SUBLIST_FINITE_ELEMENT (LP_SUBLIST_NODE + \ LP_SUBLIST_ELEMENT + \ LP_SUBLIST_MPC) #define LP_SUBLIST_TOKEN_NULL 4096 #define LP_SUBLIST_TOKEN_INT 8192 #define LP_SUBLIST_TOKEN_FLOAT 16384 #define LP_SUBLIST_TOKEN_STRING 32768 #define LP_SUBLIST_TOKEN_FIELD 65536 #define LP_SUBLIST_TOKEN_MATERIAL 131072 #define LP_SUBLIST_TOKEN (LP_SUBLIST_TOKEN_NULL + \ LP_SUBLIST_TOKEN_INT + \ LP_SUBLIST_TOKEN_FLOAT + \ LP_SUBLIST_TOKEN_STRING + \ LP_SUBLIST_TOKEN_FIELD + \ LP_SUBLIST_TOKEN_MATERIAL) #define LP_SUBLIST_ANY

Sublist Attributes

Different Sublists have different attributes. Some sublists have no attributes while others can have many (more than 10). The number and type of attributes associated with each sublist depends on the method used for lp_eval() and the type of the sublist.

#define LP_ATTRIBUTE_ID1 (internal id of entity)#define LP_ATTRIBUTE_LABEL2 (External visible label)#define LP_ATTRIBUTE_GEOMETRY3 (Coefficients)#define LP_ATTRIBUTE_GEOMETRY_TYPE4 (type code)#define LP_ATTRIBUTE_GEOMETRY_FORMAT5 (Format)#define LP_ATTRIBUTE_GEOMETRY_COMPANY_OF_ORIGIN6 (Company of origin)#define LP_ATTRIBUTE_ORIGIN7 (origin of coord frame)#define LP_ATTRIBUTE_ROTATION_MATRIX8 (rotation matrix)#define LP_ATTRIBUTE_COORDINATE_FRAME_TYPE9 (type code)#define LP_ATTRIBUTE_LOCATION10(nodal location)#define LP_ATTRIBUTE_DISPLACEMENT11(displacement)#define LP_ATTRIBUTE_BASE12(base of axis)#define LP_ATTRIBUTE_TIP13(tip of axis)?#define LP_ATTRIBUTE_CLASS_NAME14#define LP_ATTRIBUTE_TOPOLOGY_ID15(topology code)#define LP_ATTRIBUTE_DIMENSIONALITY16(dimensionality)#define LP_ATTRIBUTE_FACE_NUMBER17(face number)#define LP_ATTRIBUTE_EDGE_NUMBER18(edge number)#define LP_ATTRIBUTE_VERTEX_NUMBER19(vertex number)#define LP_ATTRIBUTE_NODE_COUNT20(number of nodes)#define LP_ATTRIBUTE_NODE_LIST21(list of node data)#define LP_ATTRIBUTE_ORIGINAL_PARSE_CLASS22(internal use only)#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS23(internal use only)#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS_ID24(internal use only)#define LP_ATTRIBUTE_ORIGINAL_PARSE_SUBCLASS_TOPOLOGICAL_CONTEXT 25(internluseonly)#define LP_ATTRIBUTE_GEOMETRY_IN_NATIVE_FORM26(geometry data)#define LP_ATTRIBUTE_TOKEN_VALUE27(value of a token)#define LP_ATTRIBUTE_EVALUATED_POINT28#define LP_ATTRIBUTE_POINT_COUNT29#define LP_ATTRIBUTE_CURVE_COUNT30#define LP_ATTRIBUTE_SURFACE_COUNT31#define LP_ATTRIBUTE_SOLID_COUNT32

261Chapter 5: User Interface and List Processor FunctionsList Processor

#define LP_ATTRIBUTE_POINT_LIST33#define LP_ATTRIBUTE_CURVE_LIST34#define LP_ATTRIBUTE_SURFACE_LIST35#define LP_ATTRIBUTE_SOLID_LIST36#define LP_ATTRIBUTE_SIDE_NUMBER37

Example:

#include “lpenums.p”EXAMPLE INTEGER list_type = 0 INTEGER handle, status, coord_label STRING list[VIRTUAL] WIDGET sdbox . . . ui_wid_get_vstring(sdbox, “VALUE”, list) status = lp_eval(list, LP_EVAL_FOR_LABEL, handle) IF (status != 0) THEN RETURN status END IF WHILE(list_type != LP_SUBLIST_COORD_FRAME ) status = lp_sublist_type(handle, LP_SUBLIST_ANY, list_type) IF (status != 0) THEN RETURN status END IF /* now the list_type is LP_SUBLIST_COORD_FRAME */ END WHILE status = lp_sublist_attribute_get_int (handle, LP_ATTRIBUTE_LABEL, @ coord_label) IF (status != 0) THEN lp_eval_cleanup(handle) RETURN status END IF

PCL and CustomizationList Processor

262

List Processor Functions

Example:

#include “lpenums.p” . . . status = lp_eval (coord, LP_EVAL_FOR_GEOMETRY, handle1) IF (status = 0) THEN RETURN status END IF status = lp_sublist_attribute_get_int (handle1, LP_ATTRIBUTE_LABEL, @ coord_label) IF (status = 0) THEN lp_eval_cleanup(handle1) RETURN status END IF

lp_eval (list, method, handle )

Description:

Establish a new list processing anchor and handle.

Input:

STRING list Picklist from ui_wid_get_vstring on a select databox.

INTEGER method Code which indicates the evaluation method to use on the picklist. See lpenums.i

Output:

INTEGER handle Used by other lp utilities to parse the Picklist.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error

Error Conditions:

None.

263Chapter 5: User Interface and List Processor FunctionsList Processor

List Processor Functions

Remarks:

Memory is allocated for the virtual string pvc_entity_ids. Typically the deallocation would occur in the PCL program in which the virtual string was defined: string out[VIRTUAL]. Otherwise one must account for deallocation to avoid memory leaks.

lp_sub_str_by_keyword (c_lp_str, c_keyword, case_sensitive, pvc_entity_ids )

Description:

Recover entity ids as they appear in the list processor string.

Input:

STRING[] c_lp_str Input string made with list processor

STRING[] c_keyword This value specifies the keyword for extracting entity ids. Ex: "Point", "Curve", "Surface", "Solid", "Node", "Element", "MPC" keyword_with_no_trailing_blank+" " will be used for the query.

INTEGER case_sensitive 0 if FALSE

1 (or not 0) if TRUE

Output:

STRING[] pvc_entity_ids Pointer to address of virtural string containing all the entities ids as they appear in the list processor string. It will at least be allocated a minimum size of 1 char and set to ““ if a no error condition occured.

INTEGER <Return Value> This function returns a value of 0 when executed successfully.

Error Conditions:

None.

PCL and CustomizationList Processor

264

List Processor Functions

Example:

#include “lpenums.i”INTEGER handle1,ent_type, countINTEGER status.../* Now check to make sure that sublist type is a solid */status = lp_sublist_type(handle1,LP_SUBLIST_ANY, ent_type)IF ( ( status != 0 ) ||( ent_type != LP_SUBLIST_SOLID ) )THENRETURN statusEND IF...

lp_sublist_type (handle, filter, type )

Description:

Indicates which type of sublist is referenced by the handle.

Input:

INTEGER handle Returned by call to lp_eval().

INTEGER filter Filter from lpenums.i, it is most common to use LP_SUBLIST_ANY, or one of the more generic filters as this parameter.

Output:

INTEGER type Actual sublist type. See lpenums.i, sublist types.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

265Chapter 5: User Interface and List Processor FunctionsList Processor

List Processor Functions

Example:

#include “lpenums.p” . . . status = lp_eval(list_str, LP_EVAL_FOR_LABEL, handle) IF (status != 0) THEN RETURN status END IF status = lp_sublist_count(handle, LP_SUBLIST_POINT, num_items) IF (status != 0) THEN RETURN status END IF sys_allocate_array(point_labels, 1, num_items) i = 0 REPEAT loop status = lp_sublist_type(handle, LP_SUBLIST_ANY, list_type) IF ( status != 0 ) THEN RETURN status ENDIF IF ( list_type == LP_SUBLIST_POINT) THEN status = lp_sublist_attribute_get_int(handle,LP_ATTRIBUTE_LABEL, @ label) IF (status == 0 ) THEN i += 1 point_labels(i) = label END IF IF ( i == num_items ) THEN break loop ENDIF lp_sublist_next(handle) UNTIL ( i > num_items ) lp_eval_cleanup(handle)

lp_sublist_count (handle, filter, count )

Description:

Count the number of items in a sublist.

Input:

INTEGER handle Returned by call to lp_eval().

INTEGER filter Filter from lpenums.i.

Output:

INTEGER count Number of items in sublist.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

PCL and CustomizationList Processor

266

List Processor Functions

Example:

FUNCTION list_get_id(handle1,ent_type,ent_list,count,ent_id)/* Get the ids from a list of entities in a picklist */

#include “lpenums.i”

INTEGER handle1,ent_type,ent_id(),count STRING ent_list[]

INTEGER actual,icount,next_id(1),status LOGICAL end_of_list=False

icount = 1 WHILE (!end_of_list)

status = lp_sublist_type(handle1, ent_type, actual) IF(status == 0) THEN status = lp_sublist_attribute_get_int(handle1, LP_ATTRIBUTE_ID,@ next_id) IF (status == 0) THEN ent_id(icount) = next_id icount += 1 END IF END IF status = lp_sublist_next(handle1) IF (status != 0) THEN end_of_list = True IF (icount > count) THEN BREAK

END WHILE RETURN 0END FUNCTION

lp_sublist_next (handle )

Description:

Set the list position to the next sublist.

Input:

INTEGER handle Returned by call to lp_eval().

Output:

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

267Chapter 5: User Interface and List Processor FunctionsList Processor

List Processor Functions

Example:

#include “lpenums.p”...status = lp_eval(coord, LP_EVAL_FOR_GEOMETRY, handle1) IF (status != 0) THENRETURN status END IF status = lp_sublist_attribute_get_int @(handle1, LP_ATTRIBUTE_LABEL, @coord_label) IF (status != 0) THENlp_eval_cleanup(handle1) RETURN status END IF

lp_eval_cleanup (handle )

Description:

Free allocated memory for list processor operations.

Input:

INTEGER handle Returned by call to lp_eval().

Output:

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

Note: Must be called after all calls to parse a particular picklist.

PCL and CustomizationList Processor

268

List Processor Functions

Example:

#include “lpenums.p”...status = lp_eval(list_str, LP_EVAL_FOR_TOKENS, handle) IF (status != 0) THEN

lp_sublist_attribute_get_int (handle, attribute, item )

Description:

Return an array of integer values from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.

Input:

INTEGER handle Returned by call to lp_eval().

INTEGER attribute Attribute requested from sublist. See lpenums.i.

Output:

INTEGER ARRAY item Item parsed from Picklist of the specified attribute.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

lp_sublist_attribute_get_float (handle, attribute, item )

Description:

Return a real value of integer values from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.

Input:

INTEGER handle Returned by call to lp_eval().

INTEGER attribute Attribute requested from sublist. See lpenums.i.

Output:

REAL item Item parsed from Picklist of the specified attribute.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

269Chapter 5: User Interface and List Processor FunctionsList Processor

RETURN status END IF

status = lp_sublist_count(handle, LP_SUBLIST_TOKEN, ntokens) IF (status != 0) THEN RETURN status END IF

END IF IF (status!=0 || ntokens<=0) THEN lp_eval_cleanup(handle)RETURN status END IF status = SYS_ALLOCATE_ARRAY(rlist_vals, 1, ntokens)IF (status==0) THEN FOR (itoken = 1 TO ntokens) IF (itoken>1) THEN status = lp_sublist_next(handle) IF (status!=0) THEN BREAK status = lp_sublist_attribute_get_float(handle, @ LP_ATTRIBUTE_TOKEN_VALUE, rlist_vals(itoken)) IF (status!=0) THEN BREAKEND FOR END IF

List Processor Functions

Example:

#include “lpenums.p”..

lp_sublist_attribute_get_string (handle, attribute, maxsize, item, size )

Description:

Return a string from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.

Input:

INTEGER handle Returned by call to lp_eval().

INTEGER attribute Attribute requested from sublist. See lpenums.i.

INTEGER maxsize Size of output variable in bytes (use the following):

/* PCL interface help */

#define BYTES_PER_CHARACTER 1

Output:

STRING item Item parsed from Picklist of the specified attribute.

INTEGER size Actual return string size of item in bytes.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

PCL and CustomizationList Processor

270

.status = lp_eval(show_entities, LP_EVAL_FOR_GEOMETRY, handle1) WHILE (status == 0) /* * Check Data, If good data, show it on spreadsheet widget * (Dummy FOR structure allows breakout for errors) */ FOR(i = 1 TO 1) /* * Get id and label */ data_ck = lp_sublist_attribute_get_int @ (handle1, LP_ATTRIBUTE_ID, entity_id) IF(data_ck != 0) THEN BREAK

/* * Get geometry type */ data_ck = lp_sublist_attribute_get_string @ (handle1, @ LP_ATTRIBUTE_GEOMETRY_TYPE, @ BYTES_PER_CHARACTER * 64, @ type, size) IF (data_ck != 0) THEN BREAK

END FOR /* * If error found while checking data, print error message */ IF (status != 0) THEN RETURN data_ck END IF/* * Point to the next ID */ status = lp_sublist_next(handle1) END WHILE

271Chapter 5: User Interface and List Processor FunctionsList Processor

List Processor Functions

Example:

#include “lpenums.p”.../* get node count*/ IF (lp_sublist_attribute_get_int@ (handle1,LP_ATTRIBUTE_NODE_COUNT,node_count) != 0) THEN ui_writec(“Error in lp_sublist 2...”) RETURN -3 END IF

/* get nodes */ sys_allocate_array(nodes,1,20) IF (lp_sublist_attribute_get_inta@ (handle1,LP_ATTRIBUTE_NODE_LIST,node_count(1)*4,nodes,size) != 0) THEN ui_writec(“Error in lp_sublist 3...”) RETURN -3 ELSE FOR (count = 0 TO 19) node_ids(start+count)=nodes(count+1) END FOR start+=20 END IF sys_free_array(nodes)

lp_sublist_attribute_get_inta (handle, attribute, maxsize, item, size )

Description:

Return an array of integers from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.

Input:

INTEGER handle Returned by call to lp_eval().

INTEGER attribute Attribute requested from sublist. See lpenums.i.

INTEGER maxsize Size of output variable in bytes (use the following):

/* PCL interface help */

#define BYTES_PER_INTEGER 4

Output:

INTEGER ARRAY item() Item parsed from Picklist of the specified attribute.

INTEGER size Actual array size returned in item in bytes.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

PCL and CustomizationList Processor

272

List Processor Functions

Example:

#include “lpenums.p”...

status = lp_eval(coord, LP_EVAL_FOR_GEOMETRY, handle1) IF (status != 0) THEN RETURN status END IF status = lp_sublist_attribute_get_floata @ (handle1, LP_ATTRIBUTE_ROTATION_MATRIX, @ BYTES_PER_REAL * 9, @ rmatrix, size) IF (status != 0) THEN lp_eval_cleanup(handle1) RETURN status END IFEND IF

lp_sublist_attribute_get_floata (handle, attribute, maxsize, item_array, size )

Description:

Return a real array from a Picklist with a specified attribute which has been previously evaluated by a call to lp_eval.

Input:

INTEGER handle Returned by call to lp_eval().

INTEGER attribute Attribute requested from sublist. See lpenums.i.

INTEGER maxsize Size of output variable in bytes (use the following):

/* PCL interface help */

#define BYTES_PER_REAL 4

Output:

REAL ARRAY item_array() Item parsed from Picklist of the specified attribute.

INTEGER size The size of the item_array in bytes.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

273Chapter 5: User Interface and List Processor FunctionsList Processor

List Processor Functions

Example:

#include “lpenums.p”...

status = lp_eval(coord, LP_EVAL_FOR_GEOMETRY, handle1)lp_print_list(handle1) IF (status != 0) THEN RETURN status END IF status = lp_sublist_attribute_get_int @ (handle1, LP_ATTRIBUTE_LABEL, @ coord_label) IF (status != 0) THEN lp_eval_cleanup(handle1) RETURN status END IF

lp_print_list (handle )

Description:

Print the entire Picklist from the anchor block to standard out (The invoking xterm).

Input:

INTEGER handle Returned by call to lp_eval().

Output:

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

PCL and CustomizationList Processor

274

List Processor Functions

Example:

#include “lpenums.p”... status = lp_eval(ent_list,LP_EVAL_FOR_ID,handle1) IF (status != 0) THEN RETURN status IF (!em_proceed_quick()) THEN RETURN 0 db_count_curve(nbrae) IF(nbrae == 0) THENlp_eval_cleanup(handle1) RETURN 48000006 END IF SYS_ALLOCATE_ARRAY(eids,1,nbrae) FOR (iall = 1 to 4) ialloop

lp_print_sublist (handle )

Description:

Print the sublist prepared by lp_sublist_type from the anchor block to standard out (The invoking xterm).

Input:

INTEGER handle Returned by call to lp_eval().

Output:

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

lp_sublist_reset (handle )

Description:

Reset the sublist parser to resume parsing the original Picklist.

Input:

INTEGER handle Returned by call to lp_eval().

Output:

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

275Chapter 5: User Interface and List Processor FunctionsList Processor

Switch (iall) CASE (1) ent_type = LP_SUBLIST_POINT CASE (2) ent_type = LP_SUBLIST_CURVE CASE (3) ent_type = LP_SUBLIST_SURFACE CASE (4) ent_type = LP_SUBLIST_SOLID DEFAULT RETURN END SWITCH

status = lp_sublist_reset(handle1) status = lp_sublist_count(handle1,ent_type,lid) IF (status != 0) THEN lp_eval_cleanup(handle1) RETURN status END IFFOR (i = 1 To lid) Doloop...END FOREND FOR

PCL and CustomizationList Processor

276

List Processor Functions

List Processor Functions

lp_sublist_fetch (handle, maxsize, item, size )

Description:

Return the contents of a sublist.

Input:

INTEGER handle Returned by call to lp_eval().

INTEGER maxsize Size in bytes of “item”.

Output:

STRING item Contents of sublist.

INTEGER size Actual size returned.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

lp_keyword_text (keyword, family, text )

Description:

The purpose of this function is to return the keywords found in Patran that are used to describe objects, actions, etc.

NOTE: This function receives parameters in a nonintuitive fashion. The family is the first method of grouping, and the keyword is next. 1,3 yields point, and 2,3 yields grid. This should show that they keywords are organized by family, the second parameter. Below is shown all the families, and then a listing of the LpGEOMETRY family.

Input:

277Chapter 5: User Interface and List Processor FunctionsList Processor

INTEGER keyword Identifies the entity. From lpkeywords.i:

(SAMPLE for family LpGEOMETRY)

#define LpPOINT 1

#define LpGRID 2

#define LpCURVE 3

#define LpLINE 4

#define LpSURFACE 5

#define LpPATCH 6

#define LpSOLID 7

#define LpHYPERPATCH 8

#define LpPOINT_IMMEDIATE 9

#define LpSCREEN_PICK 10

#define LpCOORDINATE_FRAME 11

#define LpVECTOR 12

#define LpAXIS 13

#define LpVECTOR_IMMEDIATE 14

#define LpAXIS_IMMEDIATE 15

#define LpSIDE_NUMBER 16

PCL and CustomizationList Processor

278

Example:

#include “lpenums.p”.../*$$ FUNCTION refresh * * Purpose: * Update the Reference Coordinate Frame if the preference has been * changed. *

INTEGER family Identifies the group of entities keyword falls. From lpkeywords.i:

/* listing of possible families */

#define LpACTION 1

#define LpTECHNIQUE 2

#define LpGEOMETRY 3

#define LpFINITE_ELEMENT 4

#define LpDESIGNATOR 5

#define LpATTRIBUTE 6

#define LpGEOMETRY_TYPES 7

#define LpGEOMETRY_FORMATS 8

#define LpGEOMETRY_COOS 9

#define LpOPERATION 10

#define LpTOKEN_TYPES 11

#define LpELEMENT_TYPES 12

#define LpNUMERIC_STANDIN 13

Output:

STRING[32] item String alias for keyword.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

279Chapter 5: User Interface and List Processor FunctionsList Processor

*/ FUNCTION refresh STRING default_cid[NAME_LENGTH] STRING coord_frame_id[NAME_LENGTH]

INTEGER status

/* * Get the Preference Default Coordinate Frame */ default_cid = uil_group_transform.pref_cid()

/* * Get the List Processor’s nomenclature for Coordinate Frame */ status = lp_keyword_text(LpCOORDINATE_FRAME, LpGEOMETRY, coord_frame_id)IF (status != 0) THEN RETURN status

/* * Add the Id ... */ coord_frame_id = coord_frame_id// “ “ // default_cid

/* * ... and set the selectdatabox */ ui_wid_set(coord_dbox, “VALUE”, coord_frame_id)

END FUNCTION /* refresh */

PCL and CustomizationList Processor

280

List Processor Functions

Example:

#include “lpenums.p” CLASSWIDE WIDGET node_id STRING node_list[VIRTUAL]INTEGER status, nodes(VIRTUAL), pklist(VIRTUAL), nnodes... /* * Get the nodes from the node selectdatabox.

lp_picklist_string_creator_v (items, item_count, sort, vstring )

Description:

Create a valid Picklist in a virtual string from an array of ids.

Input:

INTEGER(item_count,6) items Each row consists of the following:

items(,1): entity Class (i.e. LpGEOMETRY)

items(,2): entity Type (i.e. LpSOLID)

items(,3): entity Identifier (i.e. 28, for label 28)

items(,4): entity SubIdentifier1 (i.e. 2, for solid 28; 0=N/A) face 2 of solid 28

items(,5): entitySubIdentifier2 (i.e. 1, for edge 1of surface 2 of solid 28; 0=N/A) edge 1 of surface 2 of solid 28

items(,6): entitySubIdentifier3 (i.e. 2, for vertex 2 of edge 1 of surface 2 of solid 28; 0=N/A) vertex 2 of edge 1 of surface 2 of solid 28

INTEGER item_count Number of items.

INTEGER sort If non zero, sort the items in ascending order, otherwise keep in original (Input) order.

Output:

STRING [VIRTUAL] vstr PCL virtual string to receive character list.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

281Chapter 5: User Interface and List Processor FunctionsList Processor

*/ ui_wid_get_vstring(node_id, “VALUE”, node_list) /* * Count the number of nodes in the node list. */ nnodes = app_count_id_list(LP_SUBLIST_NODE, node_list, @ FALSE, status)IF (status != 0) THEN RETURN status/* * Allocate a virtual array to store the node ids.

List Processor Functions*/ status = SYS_ALLOCATE_ARRAY(nodes, 1, nnodes) IF(status != 0) THEN RETURN 1/* * Allocate a virtual array to store the pick list information. */ status = SYS_ALLOCATE_ARRAY(pklist, 1, nnodes, 1, 6) IF(status != 0) THEN RETURN 1/* * Extract the node IDs from the selectdatabox string. */ status = fem_u_extract_node_ids(node_list, nnodes, nodes(1:)) IF(status != 0) THEN RETURN 1/* * Set the picklist array. */ FOR(i = 1 TO nnodes) pklist(i,1) = LpFINITE_ELEMENT pklist(i,2) = LpNODE pklist(i,3) = nodes(i) pklist(i,4) = 0 pklist(i,5) = 0 pklist(i,6) = 0 END FOR /* * Build a node list string from the node array. */ status = lp_picklist_string_creator_v(pklist(1:,1:), nnodes, @ 0, node_list) IF(status != 0) THEN RETURN 1

PCL and CustomizationList Processor

282

List Processor Functions

app_count_id_list (filter, lst, domesg, status )

Description:

Count the entities of a specified list processor type in a list using the picklist decoder routines.

Input:

INTEGER filter Filter from lpenums.i.

STRING lst Picklist from a selectdatabox.

LOGICAL domesg If TRUE, issue a message if error condition occurs.

Output:

INTEGER status Message facility code. See Message System Functions, 155. 0 indicates no error.

INTEGER <Return Value> Number of entities in the picklist of the specified type.

Error Conditions:

None.

app_count_token_list (lst, domesg, status )

Description:

Count the number of tokens that are contained in a Picklist.

Input:

STRING lst Picklist from a selectdatabox.

LOGICAL domesg If TRUE, issue a message if error condition occurs.

Output:

INTEGER status Message facility code. See Message System Functions, 155. 0 indicates no error.

INTEGER <Return Value> Number of tokens in the picklist.

Error Conditions:

None.

app_get_handle (lst, method, domesg, handle )

Description:

Open a list for processing.

283Chapter 5: User Interface and List Processor FunctionsList Processor

Input:

STRING lst Picklist from a selectdatabox.

INTEGER method Evaluation method from lpenums.i.

LOGICAL domesg If TRUE, issue a message if error condition occurs.

Output:

INTEGER handle List pointer.

INTEGER <Return Value> Number of tokens in the picklist.

Error Conditions:

None.

PCL and CustomizationList Processor

284

List Processor Functions

app_next_id (handle,filter, lst, domesg, eol, status )

Description:

Get the next id for a sublist (item) from a previously generated list.

Input:

INTEGER handle List pointer returned from app_get_handle.

INTEGER filter Filter from lpenums.i.

STRING lst Picklist from a selectdatabox.

LOGICAL domesg If TRUE, issue a message if error condition occurs.

LOGICAL eol Set to FALSE before making call. Returns TRUE when end of file encountered.

Output:

LOGICAL eol Returned as TRUE when end of file encountered.

INTEGER status Message facility error.

INTEGER <Return Value> ID of next item in Picklist.

Error Conditions:

None.

app_next_label (handle, filter, lst, domesg, eol, status )

Description:

Get the next label for a sublist item from a previously generated list.

Input:

INTEGER handle List pointer returned from app_get_handle.

INTEGER filter Filter from lpenums.i.

STRING lst Picklist from a selectdatabox.

LOGICAL domesg If TRUE, issue a message if error condition occurs.

LOGICAL eol Set to FALSE before making call. Returns TRUE when end of file encountered.

Output:

LOGICAL eol Returned as TRUE when end of file encountered.

INTEGER status Message facility error.

INTEGER <Return Value> Label of next item in Picklist.

285Chapter 5: User Interface and List Processor FunctionsList Processor

List Processor Functions

Side Effects:

• If DOMESG is true, a fatal error message will be written.If a database error, the following message will be written:

Database error during List Processing: [DB error message]

• If a list processor error, the following message will be written:

Unable to process list: “[contents of LIST]”

Error Conditions:

None.

app_lp_err_msg (domesg, lst, lp_routine, caller, status )

Description:

Handle a list processor error.

Input:

LOGICAL domesg If TRUE, issue a message if error condition occurs.

STRING lst Picklist from a selectdatabox.

STRING lp_routine Name of the list processor routine that detected the error.

STRING caller Name of the routine that called the list processor routine.

INTEGER status List processor status code.

Output:

None.

Error Conditions:

None.

PCL and CustomizationList Processor

286

List Processor Functions

fem_u_count_id_list (sublist_type, lst, domesg, status )

Description:

Count the entities of a specified list processor sublist type in a list using the picklist decoder routines.

Input:

INTEGER sublist_type Works only with following types from lpenums.p As follows:

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

STRING lst Picklist from a selectdatabox.

LOGICAL domesg If TRUE, issue a message if error condition occurs.

Output:

INTEGER status Message facility code. See Message System Functions, 155. 0 indicates no error.

INTEGER <Return Value> Number of entities in the picklist of the specified type.

Error Conditions:

None.

Note: This does not work for all sub-list types. Use lp_sublist_count if the particular type of interest is not included here. In general, this routine performs better (Take less time) than lp_sublist_count.

287Chapter 5: User Interface and List Processor FunctionsList Processor

Example:

#include “lpenums.i” STRING ent_list[] INTEGER status INTEGER lidlid = fem_u_count_id_list(LP_SUBLIST_ELEMENT,ent_list,FALSE,status) IF ( status != 0 ) THEN RETURN status END IF IF (lid == 0) THENRETURN 48000004 END IF

List Processor Functions

Example:

CLASSWIDE WIDGET node_id STRING node_list[VIRTUAL]INTEGER status, nodes(VIRTUAL), nnodes... /* * Get the nodes from the node selectdatabox. */ ui_wid_get_vstring(node_id, “VALUE”, node_list) /* * Count the number of nodes in the node list. */ nnodes = app_count_id_list(LP_SUBLIST_NODE, node_list, @ FALSE, status)IF (status != 0) THEN RETURN status/* * Allocate a virtual array to store the node ids. */ status = SYS_ALLOCATE_ARRAY(nodes, 1, nnodes)

fem_u_extract_node_ids (node_list, num_nodes, id_nodes )

Description:

Extract the array of nodes IDs from a Picklist.

Input:

STRING node_list Picklist string.

INTEGER num_nodes Number of nodes, from fem_u_count_id_list() normally.

Output:

INTEGER(num_nodes) id_nodes Array of node IDs.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

PCL and CustomizationList Processor

288

IF(status != 0) THEN RETURN 1/* * Allocate a virtual array to store the pick list information. */ status = SYS_ALLOCATE_ARRAY(pklist, 1, nnodes, 1, 6) IF(status != 0) THEN RETURN 1/* * Extract the node IDs from the selectdatabox string. */ status = fem_u_extract_node_ids(node_list, nnodes, nodes(1:)) IF(status != 0) THEN RETURN 1

List Processor Functions

Example:

*/ INTEGER elem_topo_codes(VIRTUAL) INTEGER shape_code(VIRTUAL)

fem_u_get_free_faces (el_ids, max_nodes, max_per_face, max_faces, nels, el_con, el_shape, el_nodes, face_el_ids, face_ids, free_faces)

Description:

Create a list of all free element faces in a list of solid finite elements.

Input:

INTEGER el_ids() List of solid elements.

INTEGER max_nodes Maximum number of nodes per element in EL_IDS.

INTEGER max_per_face Maximum number of nodes per face in EL_IDS.

INTEGER max_faces Maximum number of faces for any element in EL_IDS.

INTEGER nels Number of elements.

INTEGER el_con() Element node list (Connectivity).

INTEGER el_shape() Element shape array.

INTEGER el_nodes() Element node count array.

Output:

INTEGER face_el_ids() Associated element ID.

INTEGER face_ids() Free face ID.

INTEGER free_faces Number of free faces.

INTEGER <Return Value> 0, no error.1, Unsupported element type (shape/nodes).2, Memory allocation error.

Error Conditions:

None.

289Chapter 5: User Interface and List Processor FunctionsList Processor

INTEGER nodes_per_elem(VIRTUAL) INTEGER connectivity(VIRTUAL) INTEGER face_elem_ids(VIRTUAL) INTEGER keep_face_elem_ids(VIRTUAL) INTEGER free_elements(VIRTUAL) INTEGER face_ids(VIRTUAL) INTEGER elem_ids(VIRTUAL) INTEGER status INTEGER cntr1 INTEGER num_elems INTEGER num_free_faces INTEGER group_id/* *.. Now allocate element and node arrays ... */ status = db_get_current_group_id( group_id ) IF( status != 0 ) THEN RETURN status status = db_count_elems_in_group( group_id, num_elems ) IF( status != 0 ) THEN RETURN status status = sys_allocate_array( elem_ids, 1, num_elems ) IF( status != 0 ) THEN RETURN status/* * fetch all the element ids ... */ status = db_get_elem_ids_in_group( num_elems, group_id, elem_ids ) IF( status != 0 ) THEN RETURN status IF ( num_elems <= 0 ) THEN RETURN status = sys_allocate_array( elem_topo_codes, 1, num_elems ) IF( status != 0 ) THEN RETURN status status = sys_allocate_array( shape_code, 1, num_elems ) IF( status != 0 ) THEN RETURN status status = sys_allocate_array( nodes_per_elem, 1, num_elems ) IF( status != 0 ) THEN RETURN status status = sys_allocate_array( connectivity , 1,8*num_elems ) IF( status != 0 ) THEN RETURN status status = sys_allocate_array( face_elem_ids, 1,6*num_elems) IF( status != 0 ) THEN RETURN status status = sys_allocate_array( keep_face_elem_ids, 1,6*num_elems) IF( status != 0 ) THEN RETURN status status = sys_allocate_array( free_elements, 1,6*num_elems) IF( status != 0 ) THEN RETURN status status = sys_allocate_array( face_ids, 1,6*num_elems) IF( status != 0 ) THEN RETURN status/* * .. Get the associated nodes ... */ status = db_get_nodes_for_elems( num_elems, 8, elem_ids, connectivity ) IF( status != 0 ) THEN RETURN status status = db_get_elem_etop( num_elems, elem_ids, elem_topo_codes ) IF( status != 0 ) THEN RETURN status status = db_get_elem_topology_data( num_elems, elem_topo_codes, @ shape_code, nodes_per_elem) IF( status != 0 ) THEN RETURN status /* set up array for later referencing to tell if element is a wedge or a hex */ status = db_get_nodes_for_elems( num_elems, 8, elem_ids, connectivity ) IF( status != 0 ) THEN RETURN status status = fem_u_get_free_faces( elem_ids, 8, 4, 6, num_elems, connectivity ,@ shape_code, nodes_per_elem, @ face_elem_ids, face_ids, num_free_faces ) IF( status != 0 ) THEN RETURN status DUMP num_free_faces, face_elem_ids(1:num_free_faces) RETURN 0END FUNCTION

PCL and CustomizationList Processor

290

fem_u_get_id_list (sublist_type, lst, nument, domesg, ids )

Description:

Return the entities ids of a specified list processor sublist type in a list using the picklist decoder routines.

Input:

INTEGER sublist_type Works only with following types from lpenums.p As follows:

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

STRING lst Picklist from a selectdatabox.

INTEGER nument Number of entities to get.

LOGICAL domesg If TRUE, issue a message if error condition occurs.

Output:

INTEGER(nument) ids Array of entity ids.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

291Chapter 5: User Interface and List Processor FunctionsList Processor

Example:

#include “lpenums.p” STRING list1_entities[VIRTUAL] INTEGER node_ids1(VIRTUAL), num_nodes1.../* * Count the nodes in the list and return if there are no nodes or we * can’t process the list */

num_nodes1 = fem_u_count_id_list(LP_SUBLIST_NODE, list1_entities, @ true, status) IF(num_nodes1 <= 0 || status != 0) THEN RETURN

/* * Get the IDs of the nodes */

IF(sys_allocate_array(node_ids1, 1, num_nodes1) != 0) THEN RETURN status = fem_u_get_id_list(LP_SUBLIST_NODE, list1_entities, @ num_nodes1, true, node_ids1)

Note: fem_u_get_id_list does not work for all sub-list types. Use lp_sublist_type and lp_sublist_next if the particular type of interest is not included here. In general, this routine performs better (takes less time) than lp_sublist_type and lp_sublist_next.

PCL and CustomizationList Processor

292

fem_u_get_subid_list (sublist_type, lst, nument, domesg, ids, fids, edids )

Description:

Return the entities face ids and edges ids of a specified list processor sublist type in a list using the picklist decoder routines.

Input:

INTEGER sublist_type Works only with following types from lpenums.p As follows:

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

STRING lst Picklist from a selectdatabox.

INTEGER nument Number of entities to get.

LOGICAL domesg If TRUE, issue a message if error condition occurs.

Output:

INTEGER(nument) ids Array of entity ids.

INTEGER(nument) fids Face ids of the entities.

INTEGER(nument) edids Edge ids of the entities.

INTEGER <Return Value> Message facility code. See Message System Functions, 155. 0 indicates no error.

Error Conditions:

None.

293Chapter 5: User Interface and List Processor FunctionsList Processor

Example: Creating a Simple Customized Menu and FormMany times it is desired to create an additional menu that is to appear on the Main Menubar. User created menus will appear between the Applications menu and the Help menu. Customized forms may be displayed as the result of a menu selection from a customized menu item or as the result of clicking on a customized button. In either case, the PCL is exactly the same to define the form and its widgets. The following example provides the necessary PCL to create a customized menu and form. Although the example is quite simple, the basic ideas are presented. More complex examples are provided later in this book.

The p3epilog.pcl file is used to link customized PCL to Patran. Refer to The p3prolog.pcl and p3epilog.pcl Files (p. 54) in the Patran Reference Manual for more information concerning this file. Often times it is useful to refer to the PCL file or compiled PCL and, if necessary, initialize the functionality from the p3epilog.pcl file. For example, to reference the PCL in the following example which creates a customized menu and form, the required p3epilog.pcl file would be:

/** Add the PCL to the existing set of libraries accessed by Patran.*/

!! INPUT your_custom.pcl

/** Run the init function of the user_pcl class to create the menu and* the form.*/

ui_exec_function(“user_pcl”, “init”)

The first line uses the !!INPUT directive to instruct Patran to find the file named your_custom.pcl, compile it, and add it to the existing set of PCL. By calling ui_exec_function(), Patran is instructed to run the function named “init” in the class named “user_pcl”.

Here is PCL for a file named your_custom.pcl:

CLASS user_pcl

FUNCTION init()

WIDGET menubar_id, usermenu_id, form_id

/* * Get the id of the Patran menubar. */ menubar_id = uil_primary.get_menubar_id()

/* * Create the menu. */ usermenu_id = ui_menu_create(menubar_id, “menu_cbk”, “Customer Option”)

Note: fem_u_get_subid_list does not work for all sub-list types. Use lp_sublist_type and lp_sublist_next if the particular type of interest is not included here. In general, this routine performs better (takes less time) than lp_sublist_type and lp_sublist_next.

PCL and CustomizationList Processor

294

/* * Create an item for the menu. */ ui_item_create(usermenu_id, “my_item”, “Site Specific Item...”, FALSE)

/* * Create the form. Normally, each form would have it’s own class and * it’s own PCL file. But for this example, the form will be created here. */ form_id = ui_form_create(“form”, 3.4, 2.25, “UL”, 3.75, 3.25, @ “Site Specific Form”, ““)

/* * Create a label to further identify the form. Notice that once the label * is created we no longer need it’s ID, so we ignore the return value. */ ui_label_create(form_id, ““, .75, .25, “Site Specific Application”)

/* * Create some buttons which could be used to bring up other forms. The * separator at the bottom provides a visual separation between the * buttons which bring up forms and the button which closes this form. */ ui_button_create(form_id, ““, .25, .75, 3., 0., @ “Site Specific Geometry Access...”, TRUE, FALSE) ui_button_create(form_id, ““, .25, 1.25, 3., 0., @ “Acoustic Analysis...”, TRUE, FALSE) ui_button_create(form_id, ““, .25, 1.75, 3., 0., @ “Experimental Modal Import...”, TRUE, FALSE)

/* * Create the button to close the form. */ ui_button_create(form_id, “cancel”, 1.375, 2.5, 1., 0., @ “Cancel”, TRUE, TRUE)

END FUNCTION

FUNCTION display

/* * Since the form is not to be displayed unless the menu item is selected, * the display() function does not contain a ui_form_display() call. This * function exists for completeness. */

END FUNCTION/* * This function is called to handle menu events.*/FUNCTION menu_cbk(item_name)

STRING item_name[]

IF(item_name == “my_item”)THEN ui_form_display(“user_pcl”) END IF

END FUNCTION

/* * This function is called to handle Cancel button events.*/

FUNCTION cancel

ui_form_hide(“user_pcl”)

END FUNCTION

295Chapter 5: User Interface and List Processor FunctionsList Processor

END CLASS

The first executable line of the file defines the class to be user_pcl. This class will be referred to in the class and it may also be referred to from other classes. The first function in the file is the init function which creates the widgets to be used in this class. Although it is not required to create all of the widgets here, it is suggested. Notice that since the three widgets declared in the init function are referenced in only that function, they need not be declared CLASSWIDE.

If a PCL file creates a menu, become familiar with the uil_primary.get_menubar_id() function. Refer to User Interface Functions, 297 for detailed information on this function. Once the menubar ID has been returned it may be used as the parent to the menu, and in turn the menu may be used as the parent to the item. The newly created menu and menu item will now appear once this function has been called. This is a picture of part of the customized menubar:

The form is created next. The ID returned from the ui_form_create() function will be used as the parent to the label and the buttons. Notice that the locations and dimensions of the form and the widgets have been done by defining the values specifically rather than using the PCL variables. This was done to how show quickly forms and widgets can be created. Here is a picture of the resulting form:

PCL and CustomizationList Processor

296

An empty function named display() is next. Notice that since no arguments are needed for this function, the parentheses are optional. In most classes the display() function will be used to manage the display of the form created in the init() function. These function names are important as documented by ui_exec_function(). This example contains a form that is displayed from a menu pick so the callback function for the menu handles the display of the form.

The next function is named menu_cbk(). This function is the callback function for the menu created in the init() function; notice that the name, menu_cbk, is the same as the second argument in the ui_menu_create() call which is the “callback” argument. One argument is passed to the function, item_name, which is the name of the item that was selected from the menu. Since the menu has only one item there is only one IF...THEN branch (which is unnecessary for this example but is included for completeness). If the item is selected, item_name will be “my_item” which instructs Patran to display the form that was created in the class named “user_pcl.”

The last function in the class is cancel(). This function is also a callback function, this time for the button labelled Cancel (notice that the callback argument for the Cancel button, the second argument, is “cancel” which will be called when the user clicks on the Cancel button). This function simply hides the form.

297Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

User Interface Functions

BUTTON Functions

According to OSF/Motif terminology, the Patran button widget is of the XmPushButtonGadget class.

A button has only one option: it is clicked to initiate an action. No manipulation of data occurs in terms of direct input.

ui_button_create (parent, callback, x, y, width, height, label, [unused], highlight)

PCL and CustomizationUser Interface Functions

298

BUTTON Functions

A button icon falls into the same class and works exactly the same as the button widget. Instead of a text label on the button icon, an icon visually describes the widget’s function.

Description:

Create a button widget.

Input:

widget parent Parent widget of newly created widget. Must be a form.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.

NUMERIC x X location of widget in inches relative to the parent.

NUMERIC y Y location of widget in inches relative to the parent.

NUMERIC width Width of widget in inches. If zero, the button will be sized automatically to fit the text.

NUMERIC height Height of widget in inches. If zero, the button will be sized automatically to fit the text.

STRING label Text that will be displayed in button.

LOGICAL [unused] Use TRUE.

LOGICAL highlight TRUE if button is highlighted as the default button. Only one button per form may be highlighted as the default.

Output:

widget <Return Value> Button widget ID. NULL if button not created.

Error Conditions:

None.

ui_buttonicon_create (parent, callback, x, y, icon)

299Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

CASCADE Item Functions

This widget resides in the OSF/Motif defined XmCascadeButtonGadget class. Although not often used in Patran, this widget provides the ability to bring a pull-down menu from an item contained within a higher-level pull-down menu. (To operate a cascade item from the keyboard, press the space bar. The arrow keys will move focus to other items.)

Description:

Create a button icon widget.

Input:

widget parent Parent widget of newly created widget. Must be a form.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest. The first space character in the name/callback signifies that the rest of the string value is the pop-up help for the icon, and delimits the preceding string without the space as the name/callback of the widget.

NUMERIC x X location of widget in inches relative to the parent.

NUMERIC y Y location of widget in inches relative to the parent.

STRING icon Name of the file containing the icon data. Use a !!PATH in your p3midilog.pcl file if this file does not appear along the standard path.

Output:

widget <Return Value> Button widget ID. NULL if button not created.

Error Conditions:

None.

ui_cascadeitem_create (parent, name, label)

PCL and CustomizationUser Interface Functions

300

Comments:

This function may be used to create menu items that does not have an associated menu. However, it is recommended that ui_item_create() is used in such a case.

Description:

Creates an item widget to be used to bring up a cascading menu.

Input:

widget parent ID of the parent widget. Must be a menu or popup menu.

STRING name Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.

STRING label Label to be displayed indicating the widgets action. Unlike for ui_item_create(), specifying the label as ““ will not create a separator, but will create a menu item whose label is ““.

Output:

widget <Return Value> Item widget ID. NULL_WIDGET if item not created.

Error Conditions:

None.

301Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

COLOR WIDGET Functions

ui_colormenu_create (parent, callback, x, y, width, height, label, label_position, label_x, label_y, color, user_data)

Description:

Create a colormenu.

Input:

widget parent Parent widget ID. Parent widget must be a form, modal form or a frame.

STRING callback Name of the PCL function called when a color from the popup menu, posted from this widget, is selected.

NUMERIC x x location of the widget.

NUMERIC y y location of the widget.

NUMERIC width Wwidth of the widget.

NUMERIC height Height of the widget.

STRING label Widget label.

STRING label_position String specifying the position of the label. The label_position string must be from among the following.

“Top”: Place the label at the top of the menu button.

“Left”: Place the label at the left of the menu button.

“Right”: Place the label at the right of the menu button.

“None”: Place the label at the position specified by the label_x and label_y parameters.

NUMERIC label_x x location of the widget label. Used only if label_position is “None”.

NUMERIC label_y y location of the widget label. Used only if label_position is “None”.

INTEGER color Background color of the button. If 1< color < 16 the widget will be assigned the appropriate color from the Patran colors. Otherwise, the widget will show multiple colors to indicate ambiguity or nonuniqueness.

INTEGER user_data Data specific to this widget. This will be passed to the callback function (see below.)

Output:

PCL and CustomizationUser Interface Functions

302

Comments:

The PCL callback needs to be defined if the callback string passed to the creation function is not a null string. The syntax of the callback function is as follows.

FUNCTION color_cb ( wid, user_data, index )WIDGET widINTEGER user_data, index

where,

wid is the widget id of the colormenu that caused this callback.user_data is the value passed to the colormenu creation call.index is the new color value.

widget <Return Value> Colormenu widget id. NULL if the widget is not created.

Error Conditions:

None.

303Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

The PCL callback needs to be defined if the callback string passed to the creation function is not a null string. The syntax of the callback function is as follows.

FUNCTION color_cb( wid, user_data, index )WIDGET widINTEGER user_data, index

where,wid is the widget id of the colorbar that caused this callback.user_data is the value passed to the colorbar creation call.index is the number of the depressed color button when the callback is called.

ui_colorbar_create (parent, callback, x, y, width, height, label, ncolors, user_data)

Description:

Create a colormenu.

Input:

widget parent Parent widget ID. Parent widget must be a form, modal form or a frame.

STRING callback Name of the PCL function called when a color button from this widget is selected.

NUMERIC x x location of the widget.

NUMERIC y y location of the widget.

NUMERIC width Width of the widget.

NUMERIC height Height of the widget.

STRING label Widget label.

INTEGER ncolors Numbers of color buttons in the widget. Must be between 1 and 16.

INTEGER user_data Data specific to this widget. This will be passed to the callback function (see below.)

Output:

widget <Return Value>

Colorbar widget ID. NULL if the widget is not created.

PCL and CustomizationUser Interface Functions

304

The following parameters may be set using ui_wid_set call and may be obtained using ui_wid_get call.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

INTEGER(2) ITEMCOLOR Item color of the widget. The ui_wid_set or ui_wid_get call must be passed an array of size two. The first element of the carry should contain the item number. On a call to ui_wid_set the second element of the array should contain the index of the color desired. A call to the function ui_wid_get will return the color index in the second element.

INTEGER CURRENTITEM Currently depressed color button of the colorbar.

INTEGER NITEMS Number of color buttons in the colorbar.

305Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

CURSOR Functions

Example:

gu_view_center is used to pick the view center from the View menu. /*$$ gu_view_center * * Purpose: To set a flag so that the next pick rectangle will be * used for a change view center operation. * * Input: * * Output: * * Log: * * Notes: * * */ FUNCTION gu_view_center( ) GLOBAL INTEGER view_center

view_center = 1 ui_cursor_set( “graphics”, “dotbox” )

ui_cursor_set (mode, cursor)

Description:

Set the window cursor for the assigned windows.

Input:

STRING mode “ALL”, any window

“GRAPHICS”, Graphics window

”NONGRAPHICS”, Any non-graphics window

”NONMODAL”, Non-modal window

”MODAL”, Modal window

STRING cursor “dotbox” - Square with dot in it.

“cross” - Cross hair

“left_ptr” - Hand pointing

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

306

DATABOX Functions

Databoxes are defined by OSF/Motif to be text widgets which can only accept three kinds of user input: 1) integers, 2) real numbers and 3) character strings. This input may be typed or “pasted” from another databox or an X window.

Although a databox will accept only one line of information, this line can sometimes be quite long.

Depending on the application of a databox, the type of data as well as the number of data values which can be input by the user is sometimes limited, in which case a warning bell or message will be issued.

ui_databox_create (parent, callback, x, y, label_length, box_length, label, value, label_above, datatype, num_vals)

307Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

The data is checked to be consistent with datatype and num_vals each time the contents of the databox is changed.

Description:

Creates a databox widget

Input:

widget parent Parent widget ID. May be a form or a scroll frame.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.

NUMERIC x X location of the databox in inches relative to the parent.

NUMERIC y Y location of the databox in inches relative to the parent.

NUMERIC label_length Used only if label_above is FALSE. Distance between the beginning of the label and the beginning of the box, in inches. If zero, the length of the label string will be used. Specifying the label_length is useful when lining up several databoxes.

NUMERIC box_length Length of the box in inches.

STRING label Displayed text describing the value associated with the databox. To have no label initially but plan on using ui_wid_set() to change the label, assign label to be “ “. If not assigning a label, use ““ and set label_above to FALSE.

DYNAMIC value Value displayed inside the databox. This value is of the datatype specified. If the databox is to be empty upon startup, specify ““as the initial value for all datatypes.

LOGICAL label_above TRUE is the label is to be displayed above of the databox, FALSE if the label is to be displayed to the left of the databox.

STRING datatype Type of data to accept. “INTEGER,” “REAL,” or “STRING.” All values must be of the same datatype.

INTEGER num_vals Upper limit of the number of values of type datatype to accept. If “STRING” is the assigned datatype, this value is ignored.

Output:

widget <Return Value> Widget ID. NULL if the widget could not be created.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

308

EXEC Functions

Comments:

If the function name is “DISPLAY”, Patran will ensure that the class's INIT function has be executed first. As a result, it is not necessary to call ui_exec_function() twice, the first time assigning the function name as INIT, the second time assigning the function name as DISPLAY; a call to ui_exec_function(classname, “DISPLAY”) will suffice.

ui_databox_get_current ( )

Description:

Get the current databox which has focus.

Input:

None.

Output:

widget <Return Value>

Error Conditions:

None.

ui_exec_function ( classname, functionname )

Description:

Invokes a class's function. This function should be used to properly register a class containing a ui_form_create() call by calling ui_exec_function(classname, “DISPLAY”). If the INIT function is called improperly using a classname.init() call, problems will occur when attempting to display the form. By using ui_exec_function() to initialize and display forms, problems will be avoided.

Input:

STRING classname Name of the class containing the function to be executed.

STRING functionname Name of the function to be executed.

Output:

None.

Error Conditions:

None.

309Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

FILE Functions

ui_file_create (parent_id, callback_func, x_location, y_location, width, number_rows, filter_label, filter_mask, directory_label, files_label, selection_label, file_name, ok_label, filterbutton_label, cancel_label )

Description:

This function will create a file selection form.

Input:

widget parent_id This value specifies a widget identifier for the parent widget of this form.

STRING callback_func[] This value specifies the name of the PCL function that will be called for an event representing a form event. This call back function must be a member of the class in which this widget is created.

REAL x_location This value specifies the x axis location of the file widget in pixels relative to the upper left corner of the parent widget.

REAL y_location This value specifies the y axis location of the file widget in pixels relative to the upper left corner of the parent widget.

REAL width This value specifies the width of the widget in pixels, excluding the border.

INTEGER number_rows This value specifies the number of rows that will be displayed in files and directory list boxes of the form.

STRING filter_label[] This value specifies the title used on the form to describe the filter databox.

STRING filter_mask[] This value specifies the path and filter mask that determines which files will be displayed in the file list box.

STRING directory_label[] This value specifies the text used on the form to describe the directory databox.

STRING files_label[] This value specifies the text used on the form to describe the files databox.

STRING selection_label[] This value specifies the text used on the form to describe the selection databox.

STRING file_name[] This value specifies a file name to be displayed in the selection databox. If the file name specified is listed in the file list box the file list box entry will be highlighted.

PCL and CustomizationUser Interface Functions

310

Remarks:

The PCL callback function will be called when the “OK” or the “Cancel button” is selected. This PCL callback fuction should be designed to accept two strings as arguments and to return nothing. When the “OK” button is selected the callback function will have the complete path and name of the selected file passed as the first argument and the work “OPEN” passed as the second argument. When the “Cancel” button is selected an empty string or ““ will be passed as the first argument and the work “CANCEL” will be passed as the second argument.

The following input values can be manipulated through a call to the function ui_wid_set().

STRING ok_label[] This value specifies the text used to label the “OK” button.

STRING filterbutton_label[] This value specifies the text used to label the “Filter” button.

STRING cancel_label[] This value specifies the text used to label the “Cancel” button.

Output:

widget <Return Value> This function returns avalid form widget identifier when executed successfully and a value on WIDGET_NULL to indicate a change an error.

Error Conditions:

None.

311Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

:

The file widget follows the OSF/Motif standard XmFileSelectionBox. It is unique in that the file widget contains a group of closely related widgets. The filter is used to list only the desired files in the list box below and to the right. The “*” character is a wild card.

Input Value Name Corresponding

ui_wid_set() Parameter Name

callback_function NAME

x_location X

y_location Y

width WIDTH

number_rows None available.

filter_label[] FILTERLABEL

filter_mask[] DIRECTORY and FILTER

directory_label[] None available.

files_label[] FILESLABEL

selection_label[] FILENAMELABEL

file_name[] FILENAME

ok_label[] OKBUTTONLABEL

filterbutton_label[] FILTERBUTTONLABEL

cancel_label[] CANCELBUTTONLABEL

PCL and CustomizationUser Interface Functions

312

Example:

None.

FORM Functions

Forms are separate operating system windows that serve as backgrounds for widgets. They follow the OSF/Motif standard XmBulletinBoard type. They are enclosed by window manager borders. Two types of forms exist: forms and modal forms. See ui_modalform_create, 337 for information on modal forms.

ui_form_create ( callback, x, y, position, width, height, label, [unused] )

313Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Description:

Create a form widget.

Input:

STRING callback Name of PCL function called for an event in this widget. Use ““ since forms do not register events.

NUMERIC x X location of the form in inches relative to the screen.

NUMERIC y Y location of the form in inches relative to the screen.

STRING position Indicates which corners of the screen and form to use when measuring the x and y locations. Options: “UL,” “UR,” “LL” and “LR” for upper-left, upper-right, lower-left, and lower-right, respectively.

NUMERIC width Width of the form in inches.

NUMERIC height Height of the form in inches.

STRING label Label to appear in title bar.

STRING [unused]

Output:

PCL and CustomizationUser Interface Functions

314

FORM Functions

Comments:

The form will be hidden prior to deletion. This function is useful for developing new PCL forms and widgets since a call to ui_exec_function() will re-run the INIT function. However, during normal execution, all the widgets settings are lost as a result of deleting which removes them from memory. Use ui_form_hide() instead.

If class_wide variables are set upon initialization, be careful when using this function because it will cause the INIT function to be re-executed, sometimes producing un-expected results.

widget <Return Value> ID of the created form widget. NULL if the form is not created properly.

Error Conditions:

None.

ui_form_delete ( classname )

Description:

Delete a form widget.

Input:

STRING classname Name of the class containing the definition of the form to be deleted.

Output:

None.

Error Conditions:

None.

315Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

Child widgets that have been hidden by calling ui_wid_set (widget, “DISPLAY”, FALSE) will not be displayed. It is preferable to use ui_exec_function(classname, “DISPLAY”).

ui_form_display ( classname )

Description:

Displays a form defined in class classname and all of its visible children.

Input:

STRING classname Name of the class containing the definition of the form to be displayed.

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

316

FORM Functions

Example:

Typing in:

ui_form_to_file( “uil_app_asm”,1)at command line with geometry panel displayed results in file uil_app_asm.fd.01 which contains:Form title: “Geometry”Optmenu: “Construct”Label: “Action: “Optmenu: “Grid”Label: “Object: “Optmenu: “XYZ”Label: “Method: “Databox Value: “9”Label: “Grid ID List”Select: “Coord 0”Label: “Refer. Coordinate Frame”Select: “[0 0 0]”

Description:

Hides a form defined in class classname and all of its children.

Input:

STRING classname Name of the class containing the definition of the form to be hidden.

Output:

None.

Error Conditions:

None.

ui_form_to_file ( classname, level )

Description:

Given the string classname as the name of a class which has a form currently displayed, this function will create a file classname.fd.version file which contains the form and widget descriptions.

Input:

STRING classname Classname which contains form of interest.

INTEGER level Optional and defaults to 0.

Output:

<Return Value>

Error Conditions:

None.

317Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Label: “Point Coordinates List”Toggle: “Auto Execute” [On]Button: “-Apply-” [Default]

FORM Functions

Comments:

Creates FrameMaker objects when imported into a FrameMaker document through the import file menu pick.

FRAME Functions

The frame widget, OSF/Motif standard type XmFrame, is strictly a visual aid. Its “etched in,” narrow appearance groups associated widgets together in a form. Thus, no user interaction occurs with this widget type. Frames may have titles (text strings) at the top left corner.

ui_form_to_frame ( classname, scale )

Description:

Given the string classname as the name of a class which has a form currently displayed, this function will create a framemaker file classname.mif file which contains the form at a scale factor of scale.

Input:

STRING classname Name of the PCL class containing the form to be used.

INTEGER scale Scale factor for translation. Optional and defaults to 1.0.

Output:

None.

Error Conditions:

None.

ui_frame_create ( parent, callback, x, y, width, height, label, options )

PCL and CustomizationUser Interface Functions

318

Comments:

Description:

Creates a frame widget.*

Input:

widget parent ID of the parent widget. Must be a form, modalform, or window

STRING callback Name of the PCL function called for an event in this widget. Use ““ since frames are not registering events.

NUMERIC x X location of the frame in inches relative to its parent.

NUMERIC y Y location of the frame in inches relative to its parent.

NUMERIC width Width of the frame in inches.

NUMERIC height Height of the frame in inches.

STRING label Label to appear describing the contents of the frame.

INTEGER options Optional argument defaults to 0.

FRAME_CANRESIZE(1) - Allow resizable frames.

Output:

widget <Return Value> Item widget ID. NULL if frame not created.

Error Conditions:

None.

319Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Widgets placed inside of the frame are positioned relative to the upper left corner of the frame. Widgets positioned with an x or y value that is too large will only partially appear or will not be displayed at all.

ITEM Functions

Four different item types exist: menu items, listbox items, option menu items, and switch items.

ui_framemaker ( option[, scale] )

Description:

Set automatic framemaker generation. If option is 1, whenever ui_form_display() is called, the classname is echoed to the history window. This gives you the classname in order to type a ui_form_to_frame() command. If option is 2, then whenever ui_form_display() is called, the name of the class is echoed, and a call is automatically made to ui_form_to_frame() with the specified scale factor. If option is 0, then ui_form_display() reverts back to normal operation.

Input:

INTEGER option Specifies how the function works. See Description above.

REAL scale Scale factor for translation. Optional and defaults to 1.0.

Output:

None.

Error Conditions:

None.

ui_item_create ( parent, name, label, toggleable, options )

PCL and CustomizationUser Interface Functions

320

Description:

Creates an item widget to be used as a child of a menu, menubar, option menu, or switch widget. To create items in a listbox see ui_listbox_items_create, 332.

Input:

widget parent ID of the parent widget. Must be a menu, popup menu, menubar, option menu, listbox, or a switch.

STRING name Name of the widget. This name is frequently used as an argument for the callback function for the item's parent.

STRING label Label to be displayed indicating the widget’s action. If label is “ ” and the parent is a menu or option menu, the item will be defined as a separator.

LOGICAL toggleable Value used only for menu items; ignored if the item is not a menu item. If TRUE, the item will display a toggle box next to the item. If FALSE, the item will have only one value.

321Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

Menus, menubars, option menus, listboxes, and switches use item widgets. The functional attributes of the item are defined by the parent widget type. The position of the item relative to other currently existing children for the parent widget is specified by the order in which the items are created, i.e., the item created first will appear first in the parent widget, the last item created will appear last.

Use ui_cascadeitem_create() if a cascading menu is desired upon selection of this item.

INTEGER options Optional argument with default value of 0 can be the sum of a combination of the following values and are ignored if the parent is the wrong type:

MNUITEM_HAS_UNIQUE_CB(1) - Menu item has unique callback specified in the name argument above.

MNUITEM_SYMBL_1OFN(4) - The toggle item has a 1-of-many(diamond) symbol. This specification is required only for menu toggle items where by default they will have the N-of-many(square) symbol. To imitate switch-like behavior you are required to implement it the menu’s PCL callback function.

MNUITEM_ISLABL(8)- Menu item is a label.

Output:

widget <Return Value> Item widget ID. NULL if item not created.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

322

Comments:

The parent must be a listbox. Do not reference a listbox item after a ui_item_delete() call.

Comments:

The parent must be a listbox or an option menu. Do not reference items after they have been deleted.

ui_item_delete ( listbox_id, item_id )

Description:

Deletes a listbox item from it’s parent listbox.

Input:

widget listbox_id Item's parent listbox.

widget item_id Item's ID.

Output:

None.

Error Conditions:

None.

ui_item_deleteall ( parent )

Description:

Deletes all items from it’s parent. The parent must be a listbox or an option menu.

Input:

widget listbox_id Item's parent. Must be a listbox or an option menu.

Output:

None.

Error Conditions:

None.

323Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

ITEM Functions

Comments:

The parent must be a listbox. Do not reference items after they have been deleted.

Comments:

The parent may not be a listbox.

ui_item_deleteselected ( listbox_id )

Description:

Deletes selected items from a listbox.

Input:

widget listbox_id Listbox from which selected items are to be deleted.

Output:

None.

Error Conditions:

None.

ui_item_display ( item )

Description:

Displays a menu item, a switch item, or an option menu item after a call to ui_item_hide().

Input:

widget item Item widget ID to be displayed.

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

324

ITEM Functions

Comments:

If the specified parent does not have an item with the specified label, NULL will be returned.

ui_item_hide ( item )

Description:

Hides a menu item, a switch item, or an option menu item.

Input:

widget item Item widget ID to be hidden.

Output:

None.

Error Conditions:

None.

ui_item_idfromlabel ( parent, label )

Description;

Returns the item's ID given it's parent and it's label.

Input:

widget parent Item's parent.

STRING label Item's label.

Output:

widget <Return Value> Item's ID.

Error Conditions:

None.

325Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

If the specified parent does not have an item with the specified name, the string “NONE” will be returned.

ITEM Functions

Comments:

If the specified parent does not have an item with the specified label, the string “NONE” will be returned.

ui_item_labelfromname ( parent, name, label )

Description:

Outputs the item's label givens it’s parent and it’s name.

Input:

widget parent Item's parent.

STRING name Item's name.

Output:

STRING label Item's label.

Error Conditions:

None.

ui_item_namefromlabel ( parent, label, name )

Description:

Outputs the item's name givens it’s parent and it’s label.

Input:

widget parent Item's parent.

STRING label Item's label.

Output:

STRING name Item's name.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

326

Comments:

The items will be sorted if sort is set to TRUE in the ui_listbox_create() call for this listbox (Refer to the ui_listbox_create() call for more information.).

ITEM Functions

The only item icon type is the switch item icon. They may be keyboard-selected using the arrow keys to move from one item to the next, then pressing the space bar.

ui_item_relabel ( listbox_id, old_label, new_label )

Description:

Replaces an old string for a listbox item with a new string.

Input:

widget listbox_id Listbox containing the string to be replaced.

STRING old_label String to be replaced.

STRING new_label New label.

Output:

None.

Error Conditions:

None.

ui_itemicon_create ( parent, name, iconname, toggleable, options )

327Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Description:

Creates an icon item widget to be used as a child of a menu, or switch widget.

Input:

widget parent ID of the parent widget. Must be a menu, menubar, or a switch.

STRING name Name of the widget. This name is frequently used as an argument for the callback function for the item's parent. The first space character in the name/callback signifies that the rest of the string value is the pop-up help for the icon, and delimits the preceding string without the space as the name/callback of the widget.

STRING iconname Name of the file containing the hex information that is used to describe the icon.

LOGICAL toggleable Value used only for menu items; ignored if the item is not a menu item. If TRUE, the item will display a toggle box next to the item. If FALSE, the item will behave as a (push) button if it is not used as the parent for a (cascading)menu.

INTEGER options Optional argument with default value of 0 can be the sum of a combination of the following values and are ignored if the parent is the wrong type:

MNUITEM_HAS_UNIQUE_CB(1) - Menu item has unique callback specified in the name argument above.

MNUITEM_ISTOGL(2) - The item is a toggle. If specified overrides the value of the toggleable argument.)

MNUITEM_SYMBL_1OFN(4) - The toggle item has a 1-of-many(diamond) symbol. This specification is required only for menu toggle items where by default they will have the N-of-many(square) symbol. To imitate switch-like behavior you are required to implement it the menu’s PCL callback function.

MNUITEM_ISLABL(8) - Menu item is a (title)label.

Output:

PCL and CustomizationUser Interface Functions

328

Comments:

Menus, menubars, and switches use itemicon widgets. The functional attributes of the item are defined by the parent widget type. The position of the item relative to other currently existing children for the parent widget is specified by the order in which the items are created, i.e., the item created first will appear first in the parent widget, the last item created will appear last.

LABEL Functions

Labels are used only to label other widgets and cannot be selected. They provide additional information to the user.

LABELICON Functions

Label icons and labels are exactly alike except that label icons label other widgets with an icon; not text. See ui_label_create, 328 for more information.

widget <Return Value> Item widget ID. NULL if item not created.

Error Conditions:

None.

ui_label_create ( parent, callback, x, y, label )

Description:

Create a label widget

Input:

widget parent Parent widget of newly created widget. Must be a frame, a form, or a modal form.

STRING callback Not used.

NUMERIC x X location of the widget in inches relative to the parent.

NUMERIC y Y location of the widget in inches relative to the parent.

STRING label Text to be displayed.

Output:

widget <Return Value> Label widget ID. NULL if label not created.

Error Conditions:

None.

ui_labelicon_create ( parent, callback, x, y, iconname )

329Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

LISTBOX Functions

This widget is considered by OSF/Motif as an XmList contained within an XmScrolledWindow.

Description:

Create a label icon widget

Input:

widget parent Parent widget of newly created widget. Must be a frame, a form, or a modal form.

STRING callback Not used.

NUMERIC x X location of the widget in inches relative to the parent.

NUMERIC y Y location of the widget in inches relative to the parent.

STRING iconname Name of the file containing the hex information describing the icon. The file must be in the path described by the !!PATH directive assigned during session initialization.

Output:

widget <Return Value> Label widget ID. NULL if label not created.

Error Conditions:

None.

ui_listbox_create ( parent, callback, x, y, width, num_rows, label, selection_type, sort )

PCL and CustomizationUser Interface Functions

330

Comments:

In order to add items to a listbox see ui_listbox_items_create, 332. Due to a Motif bug a listbox created in a form that is already displayed will have incorrect num_rows. To work around this problem you have to call ui_wid_set( <listbox>, “ROWS”, num_rows ) after creating the listbox successfully.

selection_type Modes

Four different selection_type modes exist for the listbox, as follows:

Description:

Create a listbox widget

Input:

widget parent Parent widget of newly created widget. Must be a frame, a form, or a modal form.

STRING callback Name of the PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events in this widget are not of interest.

NUMERIC x X location of the widget in inches relative to the parent.

NUMERIC y Y location of the widget in inches relative to the parent.

NUMERIC width Width of the listbox in inches.

INTEGER num_rows Number of rows of items displayed in the listbox.

STRING label Label displayed to describe the listbox.

STRING selection_type “BROWSE”, “EXTEND”, “MULTIPLE”, or “SINGLE”. See selection_type Modes, 330.

LOGICAL sort TRUE if the items should be sorted alphabetically, FALSE if not.

Output:

widget <Return Value> Widget ID of listbox widget. NULL if not created.

Error Conditions:

None.

331Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Single Allows only one pick at a time. Here, pressing down on an item will automatically pick it. Any scrolling done afterwards or a releasing of the mouse button on another item will be inconsequential. Arrow keys highlight subsequent items which also selects one at a time.

Browse Allows only one selection to be made at a time. Pressing down on an item only initiates picking, then you may scroll up and down through the other choices without making a selection. As the cursor moves over the items, the item corresponding to the cursor location will become highlighted. Releasing the mouse button on the highlighted item makes the selection. Keyboard selection works the same for browse mode as for single mode.

Multiple Allows picking of more than one item by clicking each one separately. It will also toggle off previously highlighted items. The arrow keys highlight the items while the space bar selects and deselects them.

Extend Also permits multiple picking of items. Pressing down on the left mouse button with the cursor on the first (base) item desired will initiate picking. Next, dragging through any adjacent items will highlight them also. These highlights are temporary and can be changed by dragging elsewhere in the listbox. Releasing the mouse button on another item will pick all items between the base and last item inclusively.

PCL and CustomizationUser Interface Functions

332

LISTBOX Functions

ui_listbox_items_create ( listbox, names, labels, num_items, wid_array )

Description:

Create items in a listbox. This routine differs from ui_item_create by creating items in a listbox from an array of labels. The result is that items are created much faster with this routine than by creating them one at a time. This call ignores the DUPLICATEITEM resource setting of the listbox. The caller of this function is responsible for eliminating duplicate items when necessary.

Input:

widget listbox Listbox ID returned from the ui_listbox_create() call containing the items to be selected.

STRING[]() names Names of the widgets to be created in the listbox. These are frequently used as arguments for the callback function for the item’s parent.

STRING[]() labels Labels to be displayed indicating the widgets action.

INTEGER num_items Number of items in listbox.

Output:

WIDGET() wid_array Array that will contain the uims widgets created for each label. If uims widgets are not needed, pass the global WIDGET_NULL instead of wid_array

INTEGER <Return Value> Status. 0 if no error occurred, 1 otherwise.

Error Conditions:

None.

ui_listbox_items_delete ( listbox )

Description:

Delete all items contained in the listbox.

Input:

widget listbox Listbox ID returned from the ui_listbox_create() call containing the items to be deleted.

Output:

None.

Error Conditions:

None.

333Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

LISTBOX Functions

Comments:

This routine will work with listboxes created with a selection type of EXTENDED or MULTIPLE. It will not work with listboxes created with a selection type of BROWSE or SINGLE.

• If start is greater than the actual number of items in the listbox no items will be selected.

• If start + num_items is greater than the actual number of items in the listbox, items will be selected from position start through the last item in the listbox.

• If start is negative, then the first num_items + start items will be selected.

• If num_items is negative, no items will be selected.

ui_listbox_select_items ( listbox, start, num_items )

Description:

Select all items contained in the listbox.

Input:

widget listbox Listbox ID returned from the ui_listbox_create() call containing the items to be selected.

INTEGER start Starting position of items to select.

INTEGER num_items Number of items in listbox to select.

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

334

Comments:

This routine will work with listboxes created with a selection type of EXTENDED or MULTIPLE. It will not work with listboxes created with a selection type of BROWSE or SINGLE.

ui_list_select_nitems ( listbox, item_labels, start, num_items )

Description:

Select items specified in the listbox.

Input:

widget listbox Listbox ID returned from the ui_listbox_create() call containing the items to be deleted.

STRING ARRAY item_labels Array of item labels.

INTEGER start Starting position of item labels to select.

INTEGER num_items Number of item labels from start to select.

Output:

None.

Error Conditions:

None.

335Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

MENU Functions

The menu bar contains a horizontal grouping of menus. However, the menus listed within a menu bar are not displayed in their entirety. Instead, a menu label representing each menu is shown.

ui_listbox_unselectall ( listbox )

Description:

Unselect all items contained in the listbox.

Input:

widget listbox Listbox ID returned from the ui_listbox_create() call containing the items to be deleted.

Output:

None.

Error Conditions:

None.

ui_menu_create ( parent, callback, label, options )

PCL and CustomizationUser Interface Functions

336

Comments:

Menus are vertical groupings of item widgets. The size and number of items added to the menu widget determines the menu's size.

Description:

Create a menu widget.

Input:

widget parent Parent widget of a newly created widget. The parent must be a cascade_item or a menubar. The Patran menubar ID can be determined by calling menubar = uil_primary.get_menubar_id().

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events in this widget are not of interest.

STRING label Label that will be displayed in menubar.

INTEGER options Optional argument defaults to 0. It can have a sum of the following values: MENU_IS_SWITCH(4) - Menu behaves like a switch.

MENU_HAS_NO_CB(8) - Each menu item has its own callback.

The optional argument values are defined in ui_options.p and it is required to include the file to access the options by the default names.

Output:

widget <Return Value> Menu widget ID. NULL if menu not created.

Error Conditions:

None.

337Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

MODAL FORM Functions

Forms are separate operating system windows that serve as backgrounds for widgets. They follow the OSF/Motif standard XmBulletinBoard type. They are enclosed by window manager borders. Two types of forms exist: forms and modal forms. See ui_form_create, 312 for information on forms.

ui_modalform_create ( name, x, y, position, width, height, [unused], options )

PCL and CustomizationUser Interface Functions

338

OPTION MENU Functions

According to OSF/Motif terminology, an option menu is defined as a class XmOptionMenu widget. An

Description:

Create a modal form widget.

Input:

STRING name Name of the modal form.

NUMERIC x X location of the form in inches relative to the screen.

NUMERIC y Y location of the form in inches relative to the screen.

STRING position Indicates which corners of the screen and modal form to use when measuring the x and y locations. Options include “UL”, “UR”, “LL”, and “LR”.

NUMERIC width Width of the modal form in inches.

NUMERIC height Height of the modal form in inches.

STRING [unused] Unused. Specify ““.

INTEGER options Optional argument defaults to 0. MODAL_LOC_ISFIXED(8) - Uses the location specified to position the modal dialog form. Without this option the form is placed centered at the mouse pointer location.

Output:

widget <Return Value> Modal form widget ID. NULL if modal form not created.

Error Conditions:

None.

ui_optionmenu_create ( parent, callback, x, y, label_length, label, label_above )

339Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

option menu is a vertical grouping of items; however, only one of the items is visible until the user clicks on the item.

Comments:

The PCL callback will be called when an option menu item is selected unless the selected item is the currently displayed option menu item.

Description:

Create a option menu widget.

Input:

widget parent Parent ID. Must be a frame, a window, a form or a modal form.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events in this widget are not of interest.

NUMERIC x X location in inches relative to the parent.

NUMERIC y Y location in inches relative to the parent.

NUMERIC label_length Length of the space between the beginning of the label and the option menu button. Used only if label_above is FALSE. If 0., the actual length of the label will be used.

STRING label Label to appear describing the option menu.

LOGICAL label_above TRUE if the label is to appear above the menu. FALSE if the label is to appear to the left of the menu.

Output:

widget <Return Value> Option menu widget ID. NULL if the option menu was not created.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

340

PERCENT COMPLETE Functions

Comments:

pcntcomplete_close is PCL, Fortran and C callable. The Fortran syntax is:

PCNTCOMPLETE_CLOSE( )

The C syntax is:

PcntcompleteClose( )

Comments:

pcntcomplete_init is PCL, Fortran and C callable. The Fortran syntax is:

PCNTCOMPLETE_INIT( MESSAGE )

pcntcomplete_close ( )

Description:

Remove the percent complete form from the screen.

Input:

None.

Output:

None.

Error Conditions:

None.

pcntcomplete_init ( message )

Description:

Display the percent complete form and assign the message to be displayed.

Input:

STRING[256]

message Message to be displayed describing the operation that is being performed.

Output:

None.

Error Conditions:

None.

341Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

The C syntax is:

PcntcompleteInit( message )

PERCENT COMPLETE Functions

Comments:

pcntcomplete_update is PCL, Fortran and C callable. The Fortran syntax is:

PCNTCOMPLETE_UPDATE( NEW_PCNT )

The C syntax is:

PcntcompleteInit( new_pcnt ).

The percent complete functions are to be used to indicate to the user that progress is being made. If the operation occurs too quickly (heaven forbid), it is possible for the X queue to receive the pcntcomplete_close call and therefore the instruction to hide the pcntcomplete form before the pcntcomplete_init call has had a chance to display the form. This will result in the inability to hide the form. For these operations, it is not necessary to use the pcntcomplete functions.

pcntcomplete_update (new_pcnt )

Description:

Update the value indicated in the slidebar in the percent complete form.

Input:

REAL new_pcnt The new value to be displayed. This value should be between 0. and 100., inclusive. If new_pcnt is less than 0., the UIMS will reassign the value to 0. If new_pcnt is greater than 100., the UIMS will reassign the value to 100. Although there is nothing stopping the PCL developer from counting from 100 to 0, it would be more intuitive to count up.

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

342

RING BELL Functions

POPUP MENU Functions

A popup menu bar contains a horizontal grouping of menus activated by clicking the right mouse button. However, the menus listed within a menu bar are not displayed in their entirety. Instead, a menu label representing each menu is shown.

ui_ring_bell (new_pcnt )

Description:

Rings bell.

Input:

None.

Output:

None.

Error Conditions:

None.

ui_c_popupmenu ( parent, callback, options )

343Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

Only tree widget entities currently support right mouse button to display popup menus. Use ui_item_create() to add items to the popup menu widget in the same manner you would for ui_menu_create(). The same for cascading menu items.

POPUP MENU Functions

Posts a previously created popup menu widget.

Description:

Create a menu widget.

Input:

widget parent Should be a NULL widget if popup menu is created. Should be a widget of type created using UI_CASCADEITEM_CREATE if submenu is created.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events in this widget are not of interest.

INTEGER options Optional argument defaults to 0. It can have a sum of the following values: MENU_IS_SWITCH(4) - Menu behaves like a switch.

MENU_HAS_NO_CB(8) - Each menu item has its own callback.

The optional argument values are defined in ui_options.p and it is required to include the file to access the options by the default names.

Output:

widget <Return Value> Menu widget ID. NULL if menu not created.

Error Conditions:

None.

ui_post_popupmenu ( wid )

PCL and CustomizationUser Interface Functions

344

Comments:

Where the popup menu appears is based on setting the X and Y positions of the popuup menu using UI_WID_SET() before making this call.

SCROLLFRAME Functions

The scroll frame can contain several widgets and text. To use a scroll frame, click on either of the horizontal or vertical scroll arrows to move the contents incrementally. Otherwise, click and drag either of the scroll bars to quickly move the scroll frame contents. Any applicable widget may be selected as long as it is in the visible portion of the scroll frame.

Description:

Create a menu widget.

Input:

widget wid The variable of type WIDGET created using UI_C_POPUPMENU().

Output:

widget <Return Value> None.

Error Conditions:

None.

ui_scrollframe_create (parent, callback, x, y, width, height, label, working_width, working_height, needstaticscrolls )

345Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

Description:

Create a frame widget that scrolls.

Input:

widget parent Parent widget ID of newly created widget. Must be form, modalform, or window.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ since frames are not registering events.

NUMERIC x X location of the scrollframe in inches relative to parent

NUMERIC y Y location of the scrollframe in inches relative to parent.

NUMERIC width Width of the scrollframe in inches.

NUMERIC height Height of the scrollframe in inches.

STRING label Label to appear describing the contents of the frame.

NUMERIC working_width Width of the scrollable area inside of the scrollframe on which widgets are placed, in inches.

NUMERIC working_height Height of the scrollable area inside of the scrollframe on which widgets are placed, in inches.

LOGICAL needstaticscrolls Optional argument defaults to TRUE. Set to FALSE, whenever scrolls are to be displayed only when required.

Output:

widget <Return Value> ID of the created scrollframe widget. NULL if the scrollframe is not created properly.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

346

Slidebars used for scrolling will be drawn as needed. Widgets placed inside of the scrollframe widget are positioned relative to the upper left corner of the scrollframe. Widgets positioned with an x or y value that is too large will only partially appear or will not be displayed at all.

SELECTDATABOX Functions

Although select databoxes fall into the same OSF/Motif widget class as databoxes, several differences exist. Visibly, a select databox and a databox look exactly alike; however, only the select databox, or a group of them, is surrounded by a select frame. See ui_selectframe_create, 351 for more details.

In terms of user input, a select databox has all of the features of a databox. In addition, it also allows mouse picking. See ui_databox_create, 306 for a complete description. Select databoxes are tightly linked to graphics windows in that they allow the selection of entities in a viewport if that data is relevant. If screen selection is appropriate, a select menu may appear on the bottom of the screen when the select databox is clicked, depending on the type of data expected in the select databox. See Screen Picking (p. 33) in the Patran Reference Manual for more details.

ui_scrollitem_setvisible (parent, item, lrMargin, tbMargin )

Description:

Make an invisible or partially visible scrollframe item visible.

Input:

widget parent Parent widget ID. Must be a scroll frame.

widget item Item widget ID. Must be a descendent of scroll frame parent.

INTEGER lrMargin Margin to use between left or right edge of the item and the associated edge of the parent.

INTEGER tbMargin Margin to use between top or bottom edge of the item and the associated edge of the parent.

Output:

None.

Error Conditions:

None.

ui_selectdatabox_create (parent, name, x, y, label_width, box_width, label, cvalue, label_above, datatype, prompt, pick_callback )

347Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Description:

Creates a select databox widget.

Input:

WIDGET parent Parent WIDGET ID. Must be a select frame.

STRING name Name of the data box. See widget Function Descriptions, 256 for more information.

NUMERIC x X location of the databox in inches relative to parent

NUMERIC y Y location of the databox in inches relative to parent.

NUMERIC label_width Used only if label_above is FALSE. Distance between the beginning of the label and the beginning of the box, in inches. If zero, the length of the label string will be used. Specifying the label_width is useful when lining up several databoxes.

NUMERIC box_width Width of the box in inches.

STRING label Displayed text describing the value associated with the databox. To have no label initially but plan on using ui_wid_set() to change the label, assign label to be “ “. If not assigning a label, use ““ and set label_above to FALSE.

STRING cvalue Value displayed inside the databox. This value is of the datatype specified.

LOGICAL label_above TRUE is the label is to be displayed above of the databox, FALSE if the label is to be displayed to the left of the databox.

STRING datatype Type of data to accept. For specific types, see Comments section.

STRING prompt The prompt that will appear in the text widget in the select menu when the select databox is expecting selecting to occur.

STRING pick_callback This argument is optional. Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.

Output:

widget <Return Value> Widget ID. NULL if the widget could not be created.

PCL and CustomizationUser Interface Functions

348

Comments:

The PCL callback will be called when widget receives input focus, when the widget loses input focus, and when a carriage return (<CR>) is entered.

This function will accept any datatype, but selecting/picking will report an error if the datatype is not one of the following valid types:

Error Conditions:

None.

349Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

datatype string description

"ALL_SWEEP" Curves, surfaces, edges, faces, nodes, bar elements, 2D elements, edge elements, face elements

"ANY" Any entity; points, curves, surfaces, solids, coords, planes, vectors, nodes, elements, MPCs

"ANY_POINT" Points, geometry vertex, nodes

"ASM" ASM Menu; points, curves, surfaces, solids, coords, planes, vectors,

"BEAMELEM" Beam elements; bar elements

"CID" Coords

"CID1" Coord axis 1

"CID2" Coord axis 2

"CID3" Coord axis 3

"CONNECTOR" User entity

"CURVE" Curve Menu; curves

"CURVE_EDGE" Curves and edges; curves, geometry edges

"DECOMPSURF" Edges on surface, verticies on surface, points, points on decomposed surface

"DEF_NODE" Nodes

"DEF_POINT" Points, geometric verticies

"EDGE" Edges

"EDGEONSURFACE" Edges on surfaces

"ELEDGE" Element edges

"ELEDGE_BEAM" Bar element edges, element edges

"ELEDGE_FREE" Element edges, free element edges

"ELEM2D" 2D elements

"ELEM2_SWEEP" Nodes, bar elements, 2D elements, element edges

"ELEM3D" 3D elements

"ELEMENT" Elements

"ELEM_EDGE_2D" 2D element edges

"ELEM_EDGE_2D_FREE"

2D element edges, free element edges

"ELEM_NODE" Element node

"ELEM_SWEEP" Nodes, point elements, bar elements, 2D elements, element edges, element faces

"ELFACE" Element faces

PCL and CustomizationUser Interface Functions

350

"ELFACE_FREE" Element faces, free element faces.

"ELFACE_QUAD_TRI" Quad elements, Tria elements, element faces

"FACE" Geometry faces

"FEM" Nodes, elements, MPCs

"FEM_AND_GEO_0D" Points, point elements

"FEM_AND_GEO_1D" Curves, geometry edges, and bar elements

"FEM_AND_GEO_2D" Surfaces, geometry faces, 2D elements

"FEM_AND_GEO_3D" Solids, 3D elements

"FEM_SHELL_BNDRY" 2D element edges, element edges

"FRAME" Coordinate frames

"FREE_EDGE_ELEMS" 2D elements, 3D elements, element free edges

"FREE_FACE_ELEMS" 3D elements, element free faces

"FREE_FACE_SOLIDS" Geometric free faces, solids

"GEOMETRY" Curves, surfaces, solids, planes, vectors

"GEO_BEAM" Curves, geometric edges

"GEO_CURVE_EDGE" Curves, geometric edges

"GEO_FEATURES" Solids, surfaces, geometric faces, curve mask, geometric edges,

"GEO_SHELL" Surfaces, geometric faces

"GEO_SOLID" Geometric solid

"GEO_SOLID_BNDRY" Geometric faces

"GEO_SURFACE_FACE"

Surfaces, geometric faces

"GRID" Geometric points

"HEXELEM" Hex elements

"HPAT" Geometric solids

"LINE" Geometric curves

"MESH" Surfaces, solids, geometric edges, geometric faces, nodes, elements, MPCs

"MESH_SWEEP" Curves, surfaces, geometric edges, geometric faces

"MPC" MPCs

"NODE" Nodes

"PATCH" Surfaces

"PLANE" Planes

datatype string description

351Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

SELECTFRAME Functions

Select frames act as containers for one or more select databoxes. See ui_selectdatabox_create, 346. Select frames follow the OSF/Motif style “etched-out” frame.

Select frames can also have an attached toggle. This toggle will most often be the Auto Execute option. If a series of select databoxes is necessary for an application, then the Auto Execute function automatically advances the cursor to the next select databox as soon the previous one is filled if the select databox was filled using mouse selection. In some cases after all the select databoxes have been filled, Auto Execute may indicate to Patran to perform the function. In addition, partial data as it is input by the user will be immediately applied instead of waiting for a complete set of data before acting. Thus, if the Auto Execute option is used, the need for clicking the Apply button is eliminated.

"POINT" Points

"POINTELEM" Point elements

"POINTONNODE" Points on nodes

"POINT_VERTEX" Points, geometric verticies

"PTONCURVE" Points on curves

"PTONSURFACE" Points on decomposed surfaces

"QUADELEM" Quad elements

"SOLID" Solids

"SOLIDFACE_FREE" Geometric faces, geometric free faces

"SP" Screen points

"SURFACE" Surfaces

"SURFACE_EDGE" Surfaces edges

"SURFACE_FACE" Surfaces, geometric faces

"TETELEM" Tet elements

"TRIELEM" Tria elements

"TRIMSURFACE" Trimmed surfaces

"VECTOR" Vectors

"VERTEX" Geometric verticies

"VERTEXONSURFACE"

Verticies on surfaces

"WEDGEELEM" Wedge elements

ui_selectframe_create (parent, callback, x, y, width, height, label, recycle )

datatype string description

PCL and CustomizationUser Interface Functions

352

Description:

Create a select frame widget. This widget is used to visually and functionally group select databoxes.

Input:

widget parent Parent widget ID of newly created widget. Must be form.

STRING callback The callback function assigned will only be called when: (1) the toggle is set to ON, and (2) the last select databox in this select frame has just been filled with a list created using the select mechanism.

Typically, this callback will be the function called for the action button for a form.

NUMERIC x X location of the frame in inches relative to parent

NUMERIC y Y location of the frame in inches relative to parent.

NUMERIC width Width of the frame in inches.

NUMERIC height Height of the frame in inches.

STRING label Label of toggle describing the automatic traversal functionality. This toggle will indicate whether the select databoxes are to be automatically traversed. If the label is ““, the toggle will not be visible.

LOGICAL recycle TRUE if the first databox in the frame is to regain input focus after the last databox in the frame loses input focus otherwise focus remains in the last databox.

Output:

widget <Return Value> ID of the created frame widget. NULL if the frame is not created properly.

353Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

The toggle that indicates whether single or multiple select is to occur is currently disabled since the functionality to automatically move to the next selectdatabox is not present. Databoxes placed inside of the selectframe widget are positioned relative to the upper left corner of the frame.

Use ui_wid_set(widget_id, “TOGGLEVALUE”, FALSE) to turn the toggle to OFF if default ON is not desired.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

354

SEPARATOR Functions

Comments:

ui_separator_create (parent, name, x, y, length, horizontal )

Description:

Create a separator widget.

Input:

widget parent Parent widget ID of newly created widget. Must be a frame, a form, or a modal form.

STRING name Name of the separator.

NUMERIC x X location of the widget in inches relative to parent

NUMERIC y Y location of the widget in inches relative to parent.

NUMERIC length Length of the widget in inches.

LOGICAL horizontal TRUE if separator is horizontally oriented, FALSE if separator is vertically oriented.

Output:

widget <Return Value> Separator widget ID. NULL if widget is not created

Error Conditions:

None.

ui_set_fixedfont (wid )

Description:

Set the global fixed font for a widget.

Input:

widget wid Widget ID.

Output:

INTEGER <Return Value> 1 if successful, 0 if font is not set.

Error Conditions:

None.

355Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

This function will obtain the global fixed font specified using Patran.fixedFont resource in the Patran resource file, verify if the font exists on the X display server that Patran windows are shown, and then set the font resource for the widget.

SET FOCUS Functions

Comments:

When used in conjunction with select_focus.select_manager(), in the class display function will cause the select mechanism to immediately allow picking of graphical entities of the type specified if the widget is a select databox.

Example:

FUNCTION display /* * Enable the select menu for immediate picking */ select_focus.select_manager( /* widget */ entities_sdbox, @ /* datatype */ “ANY”, @ /* prompt */ “Input Entity IDs or “ // @ “pick a Select Menu Icon.” ) /* * Display the form */ ui_form_display( “uil_imaging_plot_erase” ) /* * Set the input focus on the selectdatabox for immediate typing */ ui_set_focus( entities_sdbox )

END FUNCTION /* display */

FUNCTION callback( treeWidget, event, callData, userData ) WIDGET treeWidget STRING event [] WIDGET callData STRING userData []

ui_set_focus (wid )

Description:

Set the input focus for a widget

Input:

widget wid Widget ID to set focus ON.

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

356

… END FUNCTION

SLIDEBAR Functions

Slide bars allow values to be increased by moving the slider to the right or decreased by moving the slider to the left.

Slide bars can be adjusted several ways. The slider may be dragged to a desired position with the mouse. Or, the slider may be repositioned to the cursor position by clicking the middle mouse button inside the slide bar. Remember that the terms “click” and “drag” mean to use the left mouse button unless otherwise noted. By clicking inside the slide bar, the slider will move toward the cursor by one default increment. Clicking and holding the left mouse button inside the slide bar will incrementally move the slide bar toward the cursor until the button is released.

Once a slide bar has focus, the arrow keys may be used to move the slider.

ui_slidebar_create (parent, callback, x, y, length, label, value, num_digits, horizontal, minlabel, maxlabel, show_value, minvalue, maxvalue )

357Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

The PCL callback will be called for either of the following events:

the user drags the slider, which instructs the UIMS to assign the string “DRAG” to be the second argument of the callback,

the user stops dragging the slider, which instructs the UIMS to assign the string “VALUE_CHANGED” to be the second argument of the callback, or

the user clicks in the slide area but not in the slider, which also instructs the UIMS to assign the string “VALUE_CHANGED” to be the second argument of the callback.

Description:

Create a slide bar widget.

Input:

widget parent Parent widget ID of newly created widget. Must be a frame, a form, or a modal form.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.

NUMERIC x X location of the widget in inches relative to parent

NUMERIC y Y location of the widget in inches relative to parent.

NUMERIC length Length of the widget in inches.

STRING label Label to appear describing the slidebar.

NUMERIC value Current value of the slidebar.

INTEGER num_digits Number of digits beyond the decimal to display.

LOGICAL horizontal TRUE if separator is horizontally oriented, FALSE if separator is vertically oriented.

STRING minlabel Label to appear at the minimum end of the slidebar.

STRING maxlabel Label to appear at the maximum end of the slidebar.

LOGICAL show_value TRUE if slidebar value is to be displayed adjacent to the slidebar value indicator.

NUMERIC minvalue Minimum value the slidebar will allow.

NUMERIC maxvalue Maximum value the slidebar will allow.

Output:

widget <Return Value> Slidebar widget ID. NULL if widget is not created.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

358

SPREADSHEET Functions

SPREADSHEET Functions

ui_spread_cell_delete (wid, col, row, lay )

Description:

Delete a spreadsheet cell

Input:

widget wid Spreadsheet widget ID.

INTEGER col Column number

INTEGER row Row number

INTEGER lay Layer number

Output:

widget <Return Value> Separator widget ID. NULL if widget is not created

Error Conditions:

None.

ui_spread_cells_delete (wid, fr_col, fr_row, to_col, to_row, lay )

Description:

Delete a block of spreadsheet cells

Input:

widget wid Spreadsheet widget ID.

INTEGER fr_col Starting column

INTEGER fr_row Starting row

INTEGER to_col Ending column

INTEGER to_row Ending row

INTEGER lay Layer

Output:

None.

Error Conditions:

None.

359Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

The spreadsheet is an MSC-developed widget.

The spreadsheet widget contains several features. It consists of rows and columns of cells with numerical values entered by the user. Each cell has an address designated by the row and column in which it resides. After entering data in a cell or multiple cells, the data may be manipulated in various ways. An entire row or column may be selected by clicking on its label. Or, an individual cell may be selected by clicking inside the cell. Also, multiple cells may be selected by dragging the mouse cursor over the desired cells.

ui_spread_create (parent, callback, x, y, width, height, label_width, num_vis_cols, num_cols, num_rows, num_layers, col_labels, row_labels, label, layer_label, layer_value_label, selection_type )

PCL and CustomizationUser Interface Functions

360

Description:

Creates a spreadsheet widget.

Input:

widget parent Parent widget ID of newly created widget. Must be a frame, a form, or a modal form.

INTEGER callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.

NUMERIC x X location of spreadsheet in inches relative to the parent.

NUMERIC y Y location of spreadsheet in inches relative to the parent.

NUMERIC width Width of the spreadsheet in inches.

NUMERIC height Height of the spreadsheet in inches.

NUMERIC label_width Width of the row labels in inches.

INTEGER num_vis_cols Number of visible columns.

INTEGER num_cols Total number of columns.

INTEGER num_rows Total number of rows.

INTEGER num_layers Total number of layers.

STRINGARRAY col_labels 2D array of column labels, (columns, layers).

STRINGARRAY row_labels 2D array of row labels, (rows, layers).

STRING label Spreadsheet label.

STRING layer_label Layer databox label (for 3D).

361Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

Four different selection_type modes exist, as follows:

The PCL callback will be called when the user clicks on the cell display portion of the spreadsheet unless the selection_type has been set to “READONLY”.

A databox must accompany this widget if data entry, editing, and expansion of cell contents is needed. The application transfers data into and out of the spreadsheet using ui_spread_set_cell and ui_spread_get_cell and the callback information.

Clicking on a row or column label selects the entire row or column.

STRING layer_value_label Layer value databox label (for 3D).

STRING selection_type “SINGLE”, “ROWSELECT”, “EXTEND”, “READONLY”. See comments below.

Output:

widget <Return Value> Widget ID of spreadsheet widget. NULL if not created.

Error Conditions:

None.

SINGLE May pick only one cell. Dragging the mouse and picking labels has no effect.

ROWSELECT Picking a cell or label selects the entire row. Dragging the mouse has no effect. Used for the coupled listbox.

EXTEND Allows picking of more than one item by clicking each one separately. It will also toggle off previously highlighted items. The arrow keys highlight the items while the space bar selects and deselects them.

READONLY Cells are not pickable. Scrollbars are still active. No callback is called.

PCL and CustomizationUser Interface Functions

362

SPREADSHEET Functions

Comments:

One cell accessed at a time.

Comments:

ui_spread_get_cell ( widget_id, col, row, layer, value )

Description:

Get a spreadsheet cell.

Input:

widget widget_id Must be a spreadsheet.

INTEGER col Column to retrieve.

INTEGER row Row to retrieve.

INTEGER layer Layer to retrieve.

Output:

STRING value Value in cell.

Error Conditions:

None.

ui_spread_get_cell_info (widget_id, col, row, layer, value )

Description:

Gets a spreadsheet cell information dot.

Input:

widget widget_id Must be a spreadsheet.

INTEGER col Column to access.

INTEGER row Row to access.

INTEGER layer Layer to access.

Output:

LOGICAL value TRUE or FALSE if dot is set or not.

Error Conditions:

None.

363Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

The dot that shows up in the cell is used to signify that there is extra information associated with this cell. It is up to the programmer to store the structure containing this information. See ui_spread_set_cell_info (p. 369).

SPREADSHEET Functions

Comments:

This value is displayed in the layer value databox.

ui_spread_get_cell_length (widget_id, col, row, layer, length )

Description:

Gets the number of visible characters in a spreadsheet cell.

Input:

widget widget_id Must be a spreadsheet.

INTEGER col Column to retrieve.

INTEGER row Row to retrieve.

INTEGER layer Layer to retrieve.

Output:

INTEGER length Number of visible characters in cell.

Error Conditions:

None.

ui_spread_get_layer_value (widget_id, layer, value )

Description:

Gets a layer value from a 3D spreadsheet.

Input:

widget widget_id Must be a spreadsheet.

INTEGER layer Layer to requested.

Output:

STRING value Value of the given layer as displayed in the layer value databox.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

364

SPREADSHEET Functions

Comments:

See ui_spread_get_top_row, 365 to determine which rows are visible.

Comments:

The callback from ui_spread_create returns the same information. If the from and to values are the same, only one cell is selected (highlighted).

ui_spread_get_num_vis_rows (wid, num_vis_rows )

Description:

Get a spreadsheet number of visible rows.

Input:

widget wid Spreadsheet widget ID.

Output:

INTEGER num_vis_rows Number of visible rows.

Error Conditions:

None.

ui_spread_get_selected (widget_id, from_col, from_row, to_col, to_row, layer )

Description:

Retrieves the starting and ending column and row positions and layer for the currently selected (highlighted) cells of a given spreadsheet.

Input:

widget widget_id Must be a spreadsheet.

Output:

INTEGER from_col Starting column.

INTEGER from_row Starting row.

INTEGER to_col Ending column.

INTEGER to_row Ending row.

INTEGER layer Layer.

Error Conditions:

None.

365Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

SPREADSHEET Functions

ui_spread_get_top_row (widget_id, top_row )

Description:

Gets the top visible row number of a spreadsheet.

Input:

widget widget_id Must be a spreadsheet.

Output:

INTEGER top_row Row to get.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

366

Comments:

Add a row after the last row of the spreadsheet.

Comments:

The row numbers are counted from the first row altogether and NOT the first currently visible one in the spreadsheet. Hence the rows following the deleted one are decremented by one. The application needs to account for this when deleting multiple rows. For example, all rows can be deleted by deleting row 1 repeatedly.

ui_spread_row_create (widget_id, label )

Description:

Add a spreadsheet row.

Input:

widget widget_id Must be a spreadsheet.

STRING label Row label.

Output:

None.

Error Conditions:

None.

ui_spread_row_delete (widget_id, row_num )

Description:

Delete a spreadsheet row.

Input:

widget widget_id Must be a spreadsheet.

INTEGER row_num Row number to be deleted.

Output:

None.

Error Conditions:

None.

367Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

One cell is set at a time. If setting cell to the empty string, use ui_spread_cell_delete instead.

ui_spread_set_cell (widget_id, col, row, layer, value )

Description:

Sets a spreadsheet cell.

Input:

widget widget_id Must be a spreadsheet.

INTEGER col Column to access.

INTEGER row Row to access.

INTEGER layer Layer to access.

STRING value Value to be set.

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

368

SPREADSHEET Functions

Comments:

Improved performance over ui_spread_set_cell.

ui_spread_set_cells (wid, fr_col, fr_row, to_col, to_row, lay, values )

Description:

Set multiple spreadsheet cell contents.

Input:

widget widget_id Spreadsheet widget ID.

INTEGER fr_col Start column.

INTEGER fr_row Start row.

INTEGER to_col End column.

STRING to_row End row.

INTEGER lay Layer.

STRINGARRAY values Data to display in cells.

Output:

None.

Error Conditions:

None.

369Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

The dot that shows up in the cell is used to signify that there is extra information associated with this cell. It is up to the programmer to store the structure containing this information. See ui_spread_get_cell_info, 362.

ui_spread_set_cell_info (widget_id, col, row, layer, value )

Description:

Sets a spreadsheet cell information dot.

Input:

widget widget_id Must be a spreadsheet.

INTEGER col Column to access.

INTEGER row Row to access.

INTEGER layer Layer to access.

STRING value TRUE or FALSE to display or hide the dot.

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

370

SPREADSHEET Functions

ui_spread_set_display (parent, state )

Description:

Modify the display state of the spreadsheet.

Input:

widget parent Spreadsheet widget ID.

STRING state Determines the display characteristics of a spreadsheet:

“COL_ROW_LINE” - Draw heavy lines after the first row and column.

”COL_LINE” - Heavy line after first column.

“ROW_LINE”- Heavy line after first row.

““- Default (No heavy lines).

Output:

None.

Error Conditions:

None.

ui_spread_set_label (widget_id, col_row, index, layer, label )

Description:

Sets a spreadsheet column or row label.

Input:

widget widget_id Must be a spreadsheet.

INTEGER col_row 1 for col, 2 for row.

INTEGER index Column or row number.

INTEGER layer Layer to set.

STRING label Label to set.

Output:

None.

Error Conditions:

None.

371Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

The new label will be truncated if it is larger than the existing space for the labels.

SPREADSHEET Functions

Comments:

This value is displayed in the layer value databox.

ui_spread_set_layer_value (widget_id, layer, value )

Description:

Sets a layer value of a 3D spreadsheet.

Input:

widget widget_id Must be a spreadsheet.

INTEGER layer Layer to set.

STRING value Value to be set.

Output:

None.

Error Conditions:

None.

ui_spread_set_selected (widget_id, from_col, from_row, to_col, to_row )

Description:

Selects (highlights) the starting and ending column and row positions for the currently visible layer of a given spreadsheet.

Input:

widget widget_id Must be a spreadsheet.

INTEGER from_col Starting column.

INTEGER from_row Starting row.

INTEGER to_col Ending column.

INTEGER to_row Ending row.

Output:

None.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

372

SPREADSHEET Functions

Comments:

The new label will be truncated if it is larger than the existing space for the layer label.

SWITCH Functions

Switches exist in either a “regular” mode or an “always one” mode. Most switches are in the “always one” mode, which means that there is always one (and only one) switch item selected at all times. The “always one” switch items do not toggle on off as the “regular” switch items do to select/deselect items.

ui_spread_set_top_row (widget_id, top_row )

Description:

Sets the top visible row number of a spreadsheet.

Input:

widget widget_id Must be a spreadsheet.

INTEGER top_row Row to set.

Output:

None.

Error Conditions:

None.

ui_spread_set_value_label (widget_id, label )

Description:

In a 3D spreadsheet, sets a spreadsheet layer label.

Input:

widget widget_id Must be a spreadsheet.

STRING label Label to set.

Output:

None.

Error Conditions:

None.

ui_switch_create (parent, callback, x, y, num_cols, label, always_one )

373Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

One way to pick a switch item is to click on it with the mouse. To select a switch item, click anywhere inside its active area. (Switch items may be keyboard-selected using the arrow keys to move from one item to the next, then pressing the space bar.)

Comments:

Description:

Creates a switch widget.

Input:

widget parent Parent widget ID. Must be a frame or a form.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.

NUMERIC x X location of switch in inches relative to parent

NUMERIC y Y location of switch in inches relative to parent.

INTEGER num_cols Number of columns of items the switch is to have (see Comments section below).

STRING label Displayed text to describe switch.

LOGICAL always_one TRUE if one item in switch must always be ON. FALSE if it is allowable to have no items selected.

Output:

widget <Return Value> Widget ID of switch widget. NULL if not created.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

374

Items in switches are organized vertically. A switch contains an arbitrary number of item widgets. Only one of the item widgets may be set to ON at any given time; setting an item ON automatically sets all other items for the switch OFF. If always_one is set to FALSE, clicking on an ON item will set it to OFF.

The num_cols parameter does not work intuitively for most values. Motif takes the number of switch items, divides it by num_cols, truncates any remainder and adds one if a remainder was truncated. The resulting value is used as the number of rows. The items are then added to the switch in row-major format. For example, if num_cols is three and four switch items are supplied, the end will be:

1. item 1item 3

2. item 2item 4

The PCL callback will be called when a switch item is selected.

TEXT Functions

The textbox is mostly for informational read-only use. However, some textboxes allow the user to input data when appropriate. If the amount of text exceeds the available visible space, use the scroll bar to vertically scroll through the material.

ui_text_create (parent, callback, x, y, width, num_rows, label, text, editable, needHScroll)

375Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

TOGGLE Functions

A toggle can only be in one of two states: “TRUE” or “FALSE.” To reverse a toggle’s state, click anywhere in its active area. (If a toggle has focus, the space bar may be used to toggle its value.)

Description:

Create a text widget.

Input:

widget parent Parent of the text widget. Must be a frame, a form, a modalform, or a window.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ since text widgets do not register events.

NUMERIC x X location of widget in inches relative to parent

NUMERIC y Y location of widget in inches relative to parent.

NUMERIC width Width of the widget, in inches.

INTEGER num_rows Number of rows that will contain the text.

STRING label Label to appear with the text widget.

STRING text Text string to initially appear in the widget. Include “\n” in the string to indicate a newline.

LOGICAL editable TRUE if the user is allowed to edit the text.

LOGICAL needHScroll TRUE if horizontal scrollbar is required. Optional and defaults to FALSE.

Output:

widget <Return Value> Text widget ID. NULL if text not created.

Error Conditions:

None.

ui_toggle_create (parent, callback, x, y, label)

PCL and CustomizationUser Interface Functions

376

Comments:

The PCL callback function will be called when the user clicks on the toggle.

TOGGLEICON Functions

Description:

Creates a toggle widget.

Input:

widget parent Parent widget ID. Must be a frame, a form, or a modalform.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest.

NUMERIC x X location of toggle in inches relative to parent

NUMERIC y Y location of toggle in inches relative to parent.

STRING label Label describing toggle.

Output:

widget <Return Value> Toggle widget ID. NULL if toggle widget not created.

Error Conditions:

None.

ui_toggleicon_create (parent, callback, x, y, icon)

377Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Description:

Creates a toggleicon widget.

Input:

widget parent Parent widget ID. Must be a frame, a form, or a modalform.

STRING callback Name of PCL function called for an event in this widget. The function must be in the class in which the widget is created. Use ““ if events for this widget are not of interest. The first space character in the name/callback signifies that the rest of the string value is the pop-up help for the icon, and delimits the preceding string without the space as the name/callback of the widget.

NUMERIC x X location of toggle in inches relative to parent

NUMERIC y Y location of toggle in inches relative to parent.

STRING icon Name of the icon to display describing the toggle.

Output:

widget <Return Value> Toggleicon widget ID. NULL if toggleicon widget not created.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

378

Tree Widget Functions

Example:

The PCL function “callback” must be defined as shown in the example below.

FUNCTION callback( treeWidget, event, callData, userData )WIDGET treeWidgetSTRING eventWIDGET callDataSTRING userData…END FUNCTION

Where:

TreeWidget is the ID of the tree widget that caused the callback event can be one of the following:

EXPANDEDCOLLAPSEDSELCHANGED

userdata is the string data set with the ui_wid_set with “CALLBACKDATA” as the parameter.

callData is the information pertaining to the event that triggered this callback. Note that this data is transient and is not valid once the callback returns. It can be queried using ui_tree_calldata_get_count and ui_tree_calldata_get_items (described below) before the call returns to get the affected items.

ui_tree_create ( parent, callback, x, y, width, height, label, selection_type, options )

Description:

creates a tree view widget

Input:

widget parent Parent form or frame containing this tree widget

STRING callback Name of the PCL function called for an event in this widget.

REAL x

REAL y

REAL width

REAL height

STRING label

STRING selection_type One of SINGLE, BROWSE, MULTIPLE, EXTEND

INTEGER options Optional and defaults to 0.

Output:

INTEGER <Return Value> ID of the widget created. NULL if creation fails.

379Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

ui_tree_calldata_get_count

(callData, event, itemCount )

Description:

Retrieves the item count related to the callback from the tree widget

Input:

widget callData This is the callData argument passed to the callback

STRING reason one of the following EXPANDED, COLLAPSED, SELECTED or UNSELECTED

Output:

INTEGER itemCount number of items that changed their state

ui_tree_calldata_get_items (callData, event, itemCount, items )

Description:

Retrieves the items related to the callback from the tree widget

Input:

widget callData This is the callData argument passed to the callback

STRING event one of the following EXPANDED, COLLAPSED, SELECTED or UNSELECTED

Output:

INTEGER itemCount size of the items array

INTEGER ()

items virtual array to hold the items that changed their state

INTEGER <Return Value> Number of items returned in items array.

>=0 number items

-1 event parameter is not valid

-2 not enough memory to return the items.

ui_tree_add_item ( treeWidget, parent, insertAfter, name, image, selectedImage )

PCL and CustomizationUser Interface Functions

380

Description:

adds an item to the tree widget

Input:

widget treeWidget

INTEGER parent

INTEGER insertafter ID of the item after which the item will be inserted into the tree

=0 item is inserted as the first item of the parent

= -1 item is appended to the parent

>0 ID of the sibling item after which the new item is inserted

if this ID is not a child of the parent then the behavior is undefined.

String label

INTEGER image

INTEGER selectedImage

Output:

INTEGER <Return Value> ID of the item created. 0 if creation fails.

381Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

ui_tree_add_items ( treeWidget, parent, insertAfter, name, image, selectedImage, nitems )

Description:

adds an item to the tree widget

Input:

widget treeWidget

INTEGER nitems

INTEGER() parent

INTEGER() insertafter

String[]() label

INTEGER() image

INTEGER() selectedImage

Output:

INTEGER <Return Value> ID of the last item created. nitems items are created with this return value being the ID of the last item. Return value of 0 indicates failure.

ui_tree_delete_item ( treeWidget, itemToDelete )

Description:

deletes an item from the tree.

Input:

widget treeWidget

INTEGER itemToDelete

Output:

logical <Return Value> TRUE if no error.

ui_tree_delete_items ( treeWidget, nitems, itemsArray)

Description:

deletes an item from the tree.

Input:

PCL and CustomizationUser Interface Functions

382

widget treeWidget

INTEGER nitems

INTEGER() itemsArray

Output:

logical <Return Value> TRUE if no error.

383Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

ui_tree_select_item ( treeWidget, itemToSelect, selectionFlag )

Description:

selects/deselects an item in the tree.

Input:

widget treeWidget

INTEGER itemToSelect

LOGICAL selectionFlag TRUE indicates selection FALSE indicates deselection

Output:

logical <Return Value> TRUE if no error.

ui_tree_select_items ( treeWidget, itemsArray, nitems, selectionFlag )

Description:

selects/deselects multiple items from the tree.

Input:

widget treeWidget

INTEGER() itemsArray

INTEGER nitems

LOGICAL selectionFlag TRUE indicates selection FALSE indicates deselection

Output:

logical <Return Value> TRUE if no error.

ui_tree_select_node ( treeWidget, nodeToSelect, selectionFlag )

Description:

selects/deselects a node and all its children in the tree.

Input:

widget treeWidget

INTEGER nodeToSelect

LOGICAL selectionFlag TRUE indicates selection FALSE indicates deselection

Output:

logical <Return Value> TRUE if no error.

PCL and CustomizationUser Interface Functions

384

ui_tree_expand_item ( treeWidget, itemId, expandOrCollapse)

Description:

expands/collapse an item (that has children) in the tree.

Input:

widget treeWidget

INTEGER nodeToSelect

LOGICAL expandOrCollapse TRUE indicates expansion FALSE indicates collapse

Output:

logical <Return Value> TRUE if no error.

ui_tree_add_image ( treeWidget, imageFile )

Description:

add an image to a tree.

Input:

widget treeWidget

STRING imageFile Name of the file containing the icon data.

Output:

INTEGER <Return Value> ID of the created image.

ui_tree_delete_image ( treeWidget, imageId )

Description:

delete an image from a tree.

Input:

widget treeWidget

INTEGER imageId ID of the image obtained from ui_tree_add_image.

Output:

LOGICAL <Return Value> TRUE if image was successfully deleted.

ui_treeitem_set_image ( treeWidget, itemId, imageId, selectedImageId )

385Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Description:

set images for a tree item.

Input:

widget treeWidget

INTEGER itemId ID of the item for which images are to be set.

INTEGER imageId ID of the image to display in unselected state.

INTEGER selectedImageId ID of the image to display in selected state.

Output:

LOGICAL <Return Value> TRUE if images were successfully modified.

PCL and CustomizationUser Interface Functions

386

ui_treeitem_set_label ( treeWidget, itemId, label )

Description:

sets the label for a tree item.

Input:

widget treeWidget

INTEGER itemId ID of the item for which images are to be set.

STRING label text to be displayed.

Output:

LOGICAL <Return Value> TRUE if the label was successfully modified.

ui_treeitem_get_image ( treeWidget, itemId, imageId, selectedImageId )

Description:

get images for a tree item.

Input:

widget treeWidget

INTEGER itemId ID of the item for which images are to be set.

Output:

INTEGER imageId ID of the image to display in unselected state.

INTEGER selectedImageId ID of the image to display in selected state.

LOGICAL <Return Value> TRUE if images were successfully obtained.

ui_treeitem_get_label ( treeWidget, itemId, label, length )

Description:

Obtains the label for a tree item.

Input:

widget treeWidget

INTEGER itemId ID of the item for which label needs to be returned.

INTEGER length size of label string

Output:

387Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

STRING label text displayed.

LOGICAL <Return Value> TRUE if the label was successfully obtained.

PCL and CustomizationUser Interface Functions

388

ui_treeitem_is_selected ( treeWidget, itemId )

Description:

returns whether a tree item is selected

Input:

widget treeWidget

INTEGER itemId ID of the item for which the information is desired.

Output:

LOGICAL <Return Value> TRUE if the item is selected FALSE if the item is not selected or does not exist.

ui_treeitem_is_ expanded ( treeWidget, itemId )

Description:

returns whether a tree item is expanded or collapsed.

Input:

widget treeWidget

INTEGER itemId ID of the item for which the information is desired.

Output:

LOGICAL <Return Value> TRUE if the item is expanded. FALSE if the item is collapsed or has no children or does not exist.

ui_tree_set_selection ( treeWidget, itemIds, itemCount )

Description:

replaces the selected items in the tree with the input list

Input:

widget treeWidget

INTEGER() itemIds

INTEGER temCount

Output:

logical <Return Value> TRUE if no error.

389Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

ui_tree_get_selection ( treeWidget, itemIds, itemCount )

Description:

obtains the list of currently selected items in the tree

Input:

widget treeWidget

Output:

INTEGER() itemIds virtual array to hold the items

INTEGER itemCount

logical <Return Value> TRUE if no error. FALSE if failed to allocate memory.

ui_tree_clear_selection ( treeWidget )

Description:

clears selection. All items in the tree are unselected after this call

Input:

widget treeWidget

Output:

None.

ui_treeitem_get_parent ( treeWidget, itemId )

Description:

gets the ID of the parent of the item

widget treeWidget

INTEGER itemId ID of the item for which parent needs to be returned.

Output:

INTEGER <Return Value> ID of the parent item. –1 if itemId is invalid.

ui_treeitem_get_child_count

( treeWidget, itemId )

PCL and CustomizationUser Interface Functions

390

VERIFY NAME Functions

Description:

gets the number of children of the item

widget treeWidget

INTEGER itemId ID of the item for which parent needs to be returned.

Output:

INTEGER <Return Value> number of immediate children of the item. –1 if itemId is invalid.

ui_treeitem_get_children ( treeWidget, itemId, childIds, childCount )

Description:

gets the ids of the child items of the given parent item

widget treeWidget

INTEGER itemId ID of the item for which parent needs to be returned.

Output:

INTEGER() childIds virtual array to hold the child items

INTEGER childCount

LOGICAL <Return Value>

TRUE if no error. FALSE if failed to allocate memory.

391Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

ui_verify_name (name)

PCL and CustomizationUser Interface Functions

392

Description:

Verify whether the given name has the syntax for a valid name.

Input:

STRING name Name to verify.

Output:

INTEGER <Return Value> = 0 if name is valid.

= 1 if name is too long.

= 2 if name contains white space.

= 3 if name contains a illegal char.

= 4 if name is NULL or ““.

Error Conditions:

None.

393Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

WIDGET Functions

Comments:

Removes the widget from memory and destroys it. To delete and destroy a form, modal form, or window use ui_form_delete instead.

ui_wid_delete (wid)

Description:

Delete and destroy the widget.

Input:

widget wid Widget to delete and destroy.

Output:

None.

Error Conditions:

None.

ui_wid_exists (widget)

Description:

Determine whether the given widget exists.

Input:

widget widget Widget whose existence is to be queried.

Output:

LOGICAL <Return Value> TRUE if widget exists, FALSE if not.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

394

WIDGET Functions

Comments:

The datatype of the return value must be that of the widget's parm. For example, for a call to:

ui_wid_get (button, “ENABLE”, logical_variable)

the third argument must be declared as a logical. For the call

ui_wid_get (button, “NAME”, string_variable)

the third argument must be declared as a string.

Possible parm names:

Button parameters:

ui_wid_get (widget, parm, value)

Description:

Get the value of a widget parameter.

Input:

widget widget Widget whose value is to be queried.

STRING parm Name of parameter. Upper or lower case is permitted.

Output:

SEE BELOW value Value of parameter.

LOGICAL <Return Value> TRUE, if no error.

Error Conditions:

None.

395Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Cascade Item parameters::

Color Bar parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

STRING LABEL String that appears in the button.

STRING NAME Name of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL y Y location of widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING ACCELERATOR Accelerator key to drop the menu.

STRING LABEL Text to be displayed.

STRING NAME Name of the widget.

STRING MNEMONIC Key mnemonic to drop the menu.

PCL and CustomizationUser Interface Functions

396

Color Menu parameters:

Databox and Selectdatabox parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

INTEGER(2) ITEMCOLOR Item color of the widget. The ui_wid_set or ui_wid_get call must be passed an array of size two. The first element of the carry should contain the item number. On a call to ui_wid_set the second element of the array should contain the index of the color desired. A call to the function ui_wid_get will return the color index in the second element.

INTEGER CURRENTITEM Currently depressed color button of the colorbar.

INTEGER NITEMS Number of color buttons in the colorbar.

STRING LABEL Label of the accompanying label widget. Returns a null string if colorbar is not created with a label.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

INTEGER COLOR Color of the widget.

STRING LABEL Label of the accompanying label widget.Returns a null string if colorbar is not created with a label.

397Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

File parameters:

Data Type Parameter Name Description

INTEGER COLUMNS Width of the widget as the number of visible characters. Valid only for databoxes.

STRING DATATYPE Name of the type of data that will be accepted by the databox.

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

FILTER_ENTITY Valid only for selectdataboxes.

REAL HEIGHT Height of the widget.

STRING LABEL Label of the accompanying label widget.

INTEGER MAXNUMCHARS Maximum number of characters that can appear in a databox. Valid only for databoxes.

STRING NAME Name of the widget.

INTEGER NUMCHARS Number of characters in the databox. Valid only for databoxes.

INTEGER NUMVALS Number of reals or integers that are in the databox. Valid only for databoxes.

STRING PROMPT Prompt to appear in the select menu when the selectdatabox has focus. Valid only for selectdataboxes.

LOGICAL READONLY TRUE if the databox can not be edited. Valid only for databoxes.

LOGICAL SINGLESELECT TRUE if the selectdatabox should not allow multiple picking. Valid only for selectdataboxes.

LOGICAL UNSELECT FALSE if all text is to be selected.

(type defined by the databox's datatype)

VALUE Current value of the databox.

LOGICAL WIDSETNOTIFY TRUE if the widget’s callback will be called for a ui_wid_set(..., “VALUE”,...) call.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL Y Y location of widget.

PCL and CustomizationUser Interface Functions

398

Form and Modalform parameters:

Frame, Scrollframe, and Selectframe parameters:

Data Type Parameter Name Description

STRING DIRECTORY Directory path.

LOGICAL DISPLAY or VISIBLE TRUE if the widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING FILENAME Name of the file to appear in the file databox.

STRING FILTER Value of the directory filter.

STRING FILTERPATH Value of the filter databox.

REAL HEIGHT Height of the widget.

STRING NAME Name of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL Y Y location of widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is currectly displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

STRING LABEL Label to appear in the banner of the form.

STRING NAME Name of the widget.

REAL WIDTH Width of the form.

REAL X X location of form.

REAL Y Y location of form.

399Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Item parameters:

Label parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if the frame’s children are displayed.

LOGICAL ENABLE TRUE if frame’s children are selectable.

REAL HEIGHT Height of the widget.

STRING LABEL Label accompanying the frame.

STRING NAME Name of the widget.

LOGICAL TOGGLEVALUE Valid only for selectframes.

REAL WIDTH Width of the widget.

WORKINGHEIGHT Valid only for scrollframes.

WORKINGWIDTH Valid only for scrollframes.

REAL X X location of widget.

REAL y Y location of widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if widget is currently displayed. Invalid for listbox items.

CHAR ACCELERATOR Character used with the <control> key to assign the item’s accelerator. Invalid for listbox items.

LOGICAL ENABLE TRUE if this widget is selectable. Not valid for listbox items.

STRING LABEL String describing the item.

CHAR MNEMONIC Character used to enable the item’s mnemonic. Invalid for listbox items.

STRING NAME Name of the widget.

LOGICAL VALUE Value of the widget. Invalid for menu bar items and menu items which are not toggles.

PCL and CustomizationUser Interface Functions

400

Listbox parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if the label is in bold print.

REAL HEIGHT Height of the widget.

STRING LABEL Text to be displayed. Valid only for widgets created with ui_label_create.

STRING NAME Name of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL y Y location of widget.

401Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Menu and Popup Menu parameters:

Data Type Parameter Name Description

STRING BOTTOMITEM Label of the item to appear at the bottom of the listbox.

INTEGER BOTTOMPOS Number of the item to appear at the bottom of the listbox.

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL DEFAULTEVENT TRUE if the recent callback was due to a Return or Enter key pressed when selection type is “SINGLE”.

LOGICAL DUPLICATEITEM TRUE if this listbox allows items having the same value to appear more than once.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

STRING ARRAY

ITEMS All items in the listbox whether selected or not selected.

STRING LABEL Label to describe the listbox.

STRING NAME Name of the widget.

INTEGER NITEMS Number of items in widget.

INTEGER NSELECTED Number of items selected in widget.

INTEGER ROWS Number of rows that can be visible in the displayed listbox.

STRING SELECTIONTYPE “SINGLE”, “MULTIPLE”, “BROWSE”, “EXTEND”, or “READONLY”.

STRING TOPITEM Label of the item to appear at the top of the listbox.

STRING ARRAY

VALUE Selected items of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL Y Y location of widget.

PCL and CustomizationUser Interface Functions

402

Menubar parameters:

Optionmenu parameters:

Popup Menu parameters:

See Menu and Popup Menu parameters:, 401.

Selectdatabox parameters:

See Databox and Selectdatabox parameters:, 396.

Separator:

Data Type Parameter Name Description

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Label of the menu.

INTEGER MNEMONIC Character that assigns the mnemonic to the menu.

REAL X X location of popup menu.

REAL y Y location of popup menu.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if the widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Label of the optionmenu.

STRING NAME Name of the optionmenu.

STRING VALUE Currently displayed name of the optionmenu.

REAL X X location of widget.

REAL y Y location of widget.

403Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Slidebar parameters:

Spreadsheet:

Switch parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is displayed.

REAL HEIGHT Height of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL y Y location of widget.

Data Type Parameter Name Description

INTEGER DECPOINTS Number of digits to appear after the decimal point. Used only when show_value (see ui_slidebar_create, 356) is TRUE.

LOGICAL DISPLAY or VISIBLE TRUE if the widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

STRING LABEL Label of the slidebar.

STRING MAXLABEL Label at the upper end of the slidebar.

STRING MINLABEL Label at the lower end of the slidebar.

STRING NAME Name of the widget.

REAL VALUE Value of the widget.

REAL WIDTH Width of the widget.

REAL X X location of the widget.

REAL Y Y location of the widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if the widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Label of the spreadsheet.

INTEGER NITEMS Number of rows in spreadsheet widget

PCL and CustomizationUser Interface Functions

404

Text:

Toggle parameters:

Data Type Parameter Name Description

INTEGER COLUMNS Number of columns of items that the switch should contain.

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Label of the widget.

STRING NAME Name of the widget.

STRING VALUE Name of the item that is currently on.

REAL X X location of the widget.

REAL Y Y location of the widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is displayed.

LOGICAL EDITABLE TRUE if the user can type in the widget.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

INTEGER MAXNUMCHARS Maximum number of characters that can be entered into the widget.

STRING NAME Name of the widget.

INTEGER NUMCHARS Number of characters in the text box.

INTEGER POSITION Location of the insertion bar in the text box.

STRING VALUE Text that appears in the widget.

REAL WIDTH Width of the widget.

REAL X X location of the widget.

REAL Y Y location of the widget.

405Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Window parameters:

WIDGET Functions

Comments:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Label that describes the toggle.

STRING NAME Name of the widget.

LOGICAL VALUE Value of the widget.

REAL WIDTH Width of the widget.

REAL X X location of the widget.

REAL Y Y location of the widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is currently displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

STRING LABEL String to appear in the window’s namestripe.

STRING NAME Name of the window.

REAL WIDTH Width of the widget.

REAL X X location of the widget.

REAL Y Y location of the widget.

ui_wid_get_vstring (widget, parm, vstr )

Description:

Get the value of a widget's string parameter and return the value in a virtual string.

Input:

widget widget Widget whose value is to be queried.

STRING parm Name of parameter. Upper or lower case is permitted

Output:

STRING [VIRTUAL] vstr Value of string parameter.

Error Conditions:

None.

PCL and CustomizationUser Interface Functions

406

All parameter names from ui_wid_get() that return a string are valid.

Comments:

Used to keep the contents of widgets up-to-date when events occur which might change the information displayed on a form. Normally ui_wid_refresh is called at the end of a callback which adds, modifies or removes an entity from the database.

The refresh function in a class should update the contents of the displayed widgets which might change from actions on unrelated forms.

WIDGET Functions

Comments:

The widget values restored are those last saved using the ui_wid_save function. If used in conjunction with a ui_form_hide(), do the hide first, then the restore, to avoid flicker.

ui_wid_refresh ( )

Description:

Calls the refresh function for all classes with forms currently visible.

Input:

None.

Output:

None.

Error Conditions:

None.

ui_wid_restore (class_name )

Description:

Restores the values of all of the widgets in the class class_name to the values assigned due to the last call to ui_wid_save (class_name).

Input:

STRING class_name Name of the form’s class.

Output:

LOGICAL <Return Value> TRUE if no error.

Error Conditions:

None.

407Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Comments:

The widget values saved using this function can be restored back into the form using ui_wid_restore. If used in conjunction with a ui_form_hide(), do the hide first, then the save, to avoid flicker.

WIDGET Functions

Remarks:

ui_wid_save (class_name )

Description:

Saves the values of all of the widgets in the class class_name.

Input:

STRING class_name Name of the form’s class.

Output:

LOGICAL <Return Value> TRUE if no error.

Error Conditions:

None.

ui_wid_set (widget_id, parameter_name, parameter_value)

Description:

This function will set a widget parameter value.

Input:

widget widget_id This value specifies the identifier of the widget that will be modified.

STRING parameter_name[]

This value specifies the name of the parameter to be modified. See below for more information.

DYNAMIC_ILRS parameter_value This value specifies the array of flags used to identify the specific entity types to be exported. See the remarks below for more information.

Output:

LOGICAL <Return Value> This function returns a value of TRUE when executed successfully and a non TRUE value to indicate a change in status or an error.

Error Conditions:

This function may return a nonzero value if an error occurs.

PCL and CustomizationUser Interface Functions

408

The data type of the input value parameter_value must match the data type specified for the input value paramter_name as listed in the tables below. The parameter names that can be used and the functions used to create the widgets with which they can be used are listed in the tables below.

Button parameters:

Cascade Item parameters:

Color Bar parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

STRING LABEL Text to be displayed.

STRING NAME Name of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL y Y location of widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING ACCELERATOR Accelerator key to drop the menu.

STRING LABEL Text to be displayed.

STRING NAME Name of the widget.

STRING MNEMONIC Key mnemonic to drop the menu.

409Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Color Menu parameters:

Databox and Selectdatabox parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

INTEGER(2) ITEMCOLOR Item color of the widget. The ui_wid_set or ui_wid_get call must be passed an array of size two. The first element of the carry should contain the item number. On a call to ui_wid_set the second element of the array should contain the index of the color desired. A call to the function ui_wid_get will return the color index in the second element.

INTEGER CURRENTITEM Currently depressed color button of the colorbar.

INTEGER NITEMS Number of color buttons in the colorbar.

STRING LABEL Label of the accompanying label widget. Invalid if colorbar is not created with a label.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

INTEGER COLOR Color of the widget.

STRING LABEL Label of the accompanying label widget. Invalid if colorbar is not created with a label.

REAL WIDTH Width of the widget.

REAL HEIGHT Height of the widget.

PCL and CustomizationUser Interface Functions

410

File Parameters:

See the ui_file_create, 309 function description for more information.

Data Type Parameter Name Description

STRING APPENDVALUE Append the string onto the current value.

INTEGER COLUMNS Width of the widget as the number of visible characters. Valid only for databoxes.

STRING DATATYPE Name of the type of data that will be accepted by the databox.

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

FILTER_ENTITY Valid only for selectdataboxes.

REAL HEIGHT Height of the widget.

STRING LABEL Label of the databox.

INTEGER MAXNUMCHARS Upper limit of characters allowed in the databox. Valid only for databoxes.

STRING NAME Name of the widget.

STRING PROMPT Prompt to be displayed when the selectdatabox has focus and if the datatype displays a selection menu. Valid only for selectdataboxes.

READONLY Valid only for databoxes.

LOGICAL SINGLESELECT Used only for selectdataboxes. TRUE for the selectdatabox if only one pick is to appear in the selectdatabox.

LOGICAL UNSELECT FALSE if all text is to be selected.

(type defined by the databox's datatype)

VALUE Current value of the databox.

LOGICAL WIDSETNOTIFY TRUE if the callback function is to be called for ui_wid_set calls.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL Y Y location of widget.

411Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Data Type Parameter Name Description

STRING CANCELBUTTONLABEL This value specifies the text used to label the “Cancel” button. See the input value cancel_label in the ui_file_create() function description for more information.

STRING DIRECTORY This value specifies the path which is used together with the filter mask specified with the input variable parameter_name value FILTER to determine which files and directories are displayed in the form. See the parameter_name value FILTERPATH for more information. See the input value filter_mask in the ui_file_create() function description for more information.

LOGICAL ENABLE This value specifies, when set to TRUE, that the file form can be selected, is active, and can be used for input. If this value is set to FALSE, the form will be grayed out and cannot be selected and used for input.

STRING FILENAME This value specifies a file name to be displayed in the selection databox. If the file name specified is listed in the file list box the file list box entry will be highlighted. See the input value file_name in the ui_file_create() function description for more information.

STRING FILENAMELABEL This value specifies the text used on the form to describe the selection databox. See the input value selection_label in the ui_file_create() function description for more information.

STRING FILESLABEL This value specifies the text used on the form to describe the files databox. See the input value files_label in the ui_file_create() function description.

STRING FILTER This value specifies the filter mask which is used together with the path specified with the input variable parameter_name value DIRECTORY to determine which files and directories are displayed in the form. See the parameter_name value FILTERPATH for more information.See the input value filter_mask in the ui_file_create() function description for more information.

STRING FILTERBUTTONLABEL This value specifies the text used to label the “Filter” button. See the input value filterbutton_label in the ui_file_create() function description.

PCL and CustomizationUser Interface Functions

412

Form and modalform parameters:

STRING FILTERLABEL This value specifies the title used on the form to describe the filter databox. See the input value filter_label in the ui_file_create() function description.

STRING FILTERPATH This value sets the path and filter mask value in the filter databox and determines what will be displayed in the directory and files databoxes. This parameter_name value combines the operations of the parameter_name values DIRECTORY and FILTER. See the input value filter_mask in the ui_file_create() function description for more information.

REAL HEIGHT This value specifies the height of the widget in inches, excluding the border.

STRING NAME This value specifies the name of the PCL function that will be called for an event representing a form event. This call back function must be a member of the class in which the ui_file_create() widget is created. See the input value callback_func in the ui_file_create() function description for more information.

STRING OKBUTTONLABEL This value specifies the text used to label the “OK” button. See the input value ok_label in the ui_file_create() function description for more information.

STRING WIDTH This value specifies the width of the widget in inches, excluding the border. See the input value width in the ui_file_create() function description for more information.

REAL X This value specifies the x axis location of the file widget in inches relative to the upper left corner of the parent widget. See the input value x_location in the ui_file_create() function description for more information.

REAL Y This value specifies the y axis location of the file widget in inches relative to the upper left corner of the parent widget. See the input value y_location in the ui_file_create() function description for more information.

413Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Frame, Scrollframe, and Selectframe parameters:

Item parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is currently displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

STRING LABEL Label to appear in the banner of the form.

STRING NAME Name of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL y Y location of widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if the frame’s children that have been specifically left ON via a ui_wid_set() are to be displayed.

LOGICAL DISPLAYALL or VISIBLEALL

TRUE if the frame’s children are to be displayed regardless of whether the children have been displayed or hidden via a ui_wid_set().

LOGICAL ENABLE TRUE if frame’s children are to be selectable.

REAL HEIGHT Height of the widget.

STRING LABEL String to appear above the frame.

STRING NAME Name of the widget.

LOGICAL TOGGLEVALUE Valid only for selectframes.

REAL WIDTH Width of the widget.

WORKINGHEIGHT Valid only for scrollframes.

WORKINGWIDTH Valid only for scrollframes.

REAL X X location of widget.

REAL y Y location of widget.

PCL and CustomizationUser Interface Functions

414

Label parameters:

Listbox parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if widget is currently displayed. Invalid for listbox items.

CHAR ACCELERATOR Specifies CRTL<char> sequence to invoke item. Item need not be visible for accelerator to work. Invalid for listbox items.

LOGICAL ENABLE TRUE if this widget is selectable. Not valid for listbox items.

STRING ICON Name of the icon used in lieu of the label. See ui_itemicon_create, 326.

STRING LABEL Text to be displayed.

CHAR MNEMONIC Specifies key to invoke item. Item must be visible for mnemonic to work. Only valid for menu items.

STRING NAME Name of the widget.

LOGICAL VALUE Value of the widget. Invalid for menu bar items.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if the label is in bold print.

REAL HEIGHT Height of the widget.

STRING ICON Name of the icon to be displayed in lieu of the label. Valid only for widgets created with ui_labelicon_create.

STRING LABEL Text to be displayed.

STRING NAME Name of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL y Y location of widget.

415Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Menu and Popup Menu parameters:

Menubar parameters:

Data Type Parameter Name Description

STRING BOTTOMITEM Label of the item that is to be the bottom visible item.

INTEGER BOTTOMPOS Number of the items to appear at the bottom of the listbox.

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL DUPLICATEITEM TRUE if this listbox allows items having the same value to appear more than once.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

STRING LABEL Label to describe the listbox.

STRING NAME Name of the listbox.

INTEGER ROWS Number of rows that can be visible in the displayed listbox.

STRING SELECTIONTYPE Selection type of the listbox. “SINGLE”, “MULTIPLE”, “BROWSE”, “EXTEND”, or “READONLY”.

STRING TOPITEM Label of the item that is to be the top visible item.

STRING ARRAY

VALUE Selected items of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL Y Y location of widget.

LOGICAL UNSELECT FALSE if all items are to be selected.

Data Type Parameter Name Description

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Label of the menu.

CHAR MNEMONIC Specifies key to invoke menu.

REAL X X location of popup menu widget.

REAL y Y location of popup menu widget.

PCL and CustomizationUser Interface Functions

416

Optionmenu parameters:

Popup Menu parameters:

See Menu and Popup Menu parameters:, 415.

Selectdatabox parameters:

See Databox and Selectdatabox parameters:, 409.

Separator:

Slidebar parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Label of the optionmenu.

STRING NAME Name of the optionmenu.

STRING VALUE Currently displayed item label of the optionmenu.

REAL X X location of widget.

REAL y Y location of widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is displayed.

REAL HEIGHT Height of the widget.

REAL WIDTH Width of the widget.

REAL X X location of widget.

REAL y Y location of widget.

417Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Spreadsheet:

Switch parameters:

Data Type Parameter Name Description

INTEGER DECPOINTS Number of digits to appear after the decimal point. Used only when show_value (see ui_slidebar_create, 356) is TRUE.

LOGICAL DISPLAY or VISIBLE TRUE if the widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Text to be displayed.

STRING MAXLABEL Label at the upper end of the slidebar.

REAL MAXVALUE Maximum allowable value.

STRING MINLABEL Label to appear at the lower end of the slidebar.

REAL MINVALUE Minimum allowable value.

STRING NAME Name of the widget.

REAL VALUE Value of the widget.

REAL X X location of the widget.

REAL Y Y location of the widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if the widget is currently displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Main label to be displayed with the widget.

LOGICAL UNSELECT TRUE to unselect all cells. FALSE does nothing.

PCL and CustomizationUser Interface Functions

418

Text:

Toggle parameters:

Data Type Parameter Name Description

INTEGER COLUMNS Number of columns of items that the switch should contain.

LOGICAL DISPLAY or VISIBLE TRUE if this widget is to be displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING LABEL Label to be displayed with the widget.

STRING NAME Name of the widget.

STRING VALUE Name of the item that is currently on. If “NONE”, all switch items will be turned OFF.

REAL X X location of the widget.

REAL Y Y location of the widget.

Data Type Parameter Name Description

STRING APPENDVALUE String to append onto the current value.

LOGICAL DISPLAY or VISIBLE TRUE if the widget is currently displayed.

LOGICAL EDITABLE TRUE if the user may alter the text value.

LOGICAL ENABLE TRUE if this widget is selectable.

REAL HEIGHT Height of the widget.

INTEGER MAXNUMCHARS Maximum number of characters that can be contained in the widget.

STRING NAME Name of the widget.

INTEGER POSITION Location of the insertion bar in the text box.

LOGICAL UNSELECT FALSE if all text is to be selected.

STRING VALUE Text that appears in the widget. To include a newline character, place “\n” in the string.

REAL WIDTH Width of the widget.

REAL X X location of the widget.

REAL Y Y location of the widget.

419Chapter 5: User Interface and List Processor FunctionsUser Interface Functions

Window parameters:

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is currently displayed.

LOGICAL ENABLE TRUE if this widget is selectable.

STRING ICON Name of icon to be used, valid only when created with ui_toggleicon_create.

STRING LABEL Text to be displayed to describe the toggle.

STRING NAME Name of the widget.

LOGICAL VALUE Value of the widget.

REAL WIDTH Width of the widget.

REAL X X location of the widget.

REAL Y Y location of the widget.

Data Type Parameter Name Description

LOGICAL DISPLAY or VISIBLE TRUE if this widget is currently displayed.

LOGICAL ENABLE TRUE if this window is selectable.

REAL HEIGHT Height of the widget.

STRING LABEL String to appear in the window’s banner.

STRING NAME Name of the window.

REAL WIDTH Width of the widget.

REAL X X location of the widget.

REAL Y Y location of the widget.

PCL and CustomizationUser Interface Functions

420

Chapter 6: Creating New Analysis Forms Using PCLPCL and Customization

6 Creating New Analysis Forms Using PCL

Introduction 2

Updating Patran Release 1.1 Analysis Forms 3

Naming Convention 4

The Analysis PCL Library 5

Contents of the Analysis Library 6

The Main Analysis Form 7

Main Analysis Form Functions 9

PCL and CustomizationIntroduction

422

IntroductionIn the previous chapter, we learned that the forms of many applications within Patran change depending upon analysis code specific definitions stored within the database. In this section we will see that the forms under Analysis are also analysis code specific. But, instead of being dependent upon analysis code specific definitions stored within the database, they are governed by PCL functions contained within a special PCL library called <analysis_code>.plb. For user defined analysis interfaces, it is the user’s responsibility to create the PCL functions needed to govern the Analysis forms for his interface and compile them into the <analysis_code>.plb library.

Then Analysis functions contained in <analysis_code>.plb have three basic responsibilities:

They control the appearance and behavior of the main Analysis form.

They control any subordinate forms or functions.

They activate the requested application once the Apply button on the main Analysis form is selected.

423Chapter 6: Creating New Analysis Forms Using PCLUpdating Patran Release 1.1 Analysis Forms

Updating Patran Release 1.1 Analysis FormsThe top level architecture of the Analysis forms has drastically changed between Patran release 1.2 and the current release. Despite this change, it should be very simple to convert Patran release 1.1 Analysis forms to this new architecture. Only two steps need be taken.

1. Delete your <analysis_code>_enabler and <analysis_code>_set_options PCL classes.

2. Create an <analysis_code>_load_aom_data class which explicitly calls out each of your subordinate Analysis forms and functions.

There might be slight differences in behavior between the main Analysis form of the 1.1 release and the current main Analysis form. If you dislike these changes, you should be able to convert back to the 1.1 style of behavior by using the functions described in this chapter.

We hope the expanded flexibility and power of our new Analysis forms counterbalances any inconveniences that this change may have created.

PCL and CustomizationNaming Convention

424

Naming ConventionThe names of the Analysis PCL library, <analysis_code>.plb, and the class which must exist in this library, <analysis_code>_load_aom_data, are derived from the analysis code name. Also, the mandatory functions within the <analysis_code>_load_aom_data PCL class (<analysis_type>_ are derived from the name of the available analysis types. The following rules should be used to convert the analysis code name or analysis code name or analysis type name to the <analysis_code> or <analysis_type> prefix.

1. Convert all alpha characters within the analysis code or analysis type name to lower case.

2. Replace any occurrence of “p3/” (as in Patran FEA) with “p.”

3. Remove any non alphanumeric characters including blanks.

For example, the prefix for “MSC.Nastran” is mscnastran,” for “Structural,” “structural,” and for “John Code,” “johncode.” This derived prefix is referenced in this chapter as either <analysis_code> or <analysis_type>.

It is recommended that the user add a unique prefix to all his PCL classes and class-less functions in order to ensure uniqueness in class and function name. For example, if the user were to create a PCL class which controlled selecting a file for an analysis code called “John Code” a good class name would be “john_select_file.” Just using “select_file” as the name might interfere with already existing Patran PCL classes or functions.

425Chapter 6: Creating New Analysis Forms Using PCLThe Analysis PCL Library

The Analysis PCL LibraryWhen an analysis code is selected as the current analysis code, Patran closes the Analysis PCL library of the previously selected analysis code and opens the Analysis library of the newly selected code. This library should contain all the PCL functions needed to control the Analysis forms for the chosen analysis code. The expected name of the library is <analysis_code>.plb. The entire Patran file path will be searched for this library. The Analysis libraries for the MSC supplied analysis interfaces (MSC Nastran, MSC.Marc, etc.) are delivered in the $P3_HOME directory.

The Analysis PCL libraries will be automatically removed and added by Patran. This is done using the sys_library ( ) PCL function. See System Functions, 188. For this reason, the Analysis PCL libraries should not be added explicitly by the user: not by the !!LIBRARY directive, not by an explicit sys_library ( ) call, not within any of the initialization files, such as “init.pcl,” and not through the command line.

If Patran is unable to locate the Analysis library, the analysis code may not be selectable on the Analysis Preference form, or the Analysis pick on the main form may be ghosted, or no forms will appear when Analysis is selected. If the Analysis library cannot be found or if the wrong Analysis library has been found, the safest course of action is to rectify the problem, exit Patran and start back up again. If the Analysis library does not exist or is deficient, create or modify this PCL library before exiting Patran. If the analysis library cannot be found, expand the Patran file path to include the location of the library or move the library to a location along the file path. If you have multiple Analysis libraries and the second library is taking precedence over the desired library, move the desired library to a higher location in the file path or change the file path to give precedence to the location of the desired library. The path changes can be added to an initialization file such as init.pcl or can be typed directly into the command line. Both the path changes and file location changes require exiting Patran and should occur before opening the Patran database in the re-started Patran session.

We maintain separate PCL libraries for the Analysis PCL functions simply because there are as many versions of the Analysis functions as there are analysis interfaces to Patran and placing every version within the p3patran.plb library would make it unnecessarily large and slow.

For more on creating PCL libraries, refer to Libraries, 28 and Directives, 9. For details about modifying the Patran file path refer to Path Directive, 29 and PCL Start-Up File, 35.

PCL and CustomizationContents of the Analysis Library

426

Contents of the Analysis LibraryAs a minimum, the Analysis library should contain one PCL class called <analysis_code>_load_aom_data. The <analysis_code>_load_aom_data class must contain as many functions as there are analysis types related to the current analysis code and the name of each of these functions is <analysis_type>. For example, if the analysis code “ANSYS” has two analysis types, “Structural” and “Thermal,” then the PCL library “anays.plb” must contain the PCL class, “ansys_load_aom_data” and this class must contain two functions called “structural” and “thermal”.

Of course, the Analysis library will most likely contain many more functions than the minimum set mentioned above. Most of the time the <analysis_code>_load_aom_data class will reference a PCL class, <apply_class>, which will contain the “apply” function activated by the Apply button on the main Analysis form and the Analysis functions. All subordinate Analysis forms will be controlled by PCL classes which exist in the Analysis library. Any PCL application code, such as the actual application, if written in PCL, or functions which will gather data for an external application, prepare Patran for an external application (such as close the database, if necessary) and spawn the external application program, should exist in the Analysis library.

427Chapter 6: Creating New Analysis Forms Using PCLThe Main Analysis Form

The Main Analysis FormThe main Analysis form is controlled by two PCL classes, “analysis_main” and <analysis_code>_load_aom_data. “analysis_main” is a generic class contained within the p3patran.plb library. The <analysis_code>_load_aom_data class is analysis code specific and resides in the <analysis_code>.plb library. “analysis_main” is not modifiable by the user. For MSC supplied analysis interfaces, such as Patran MSC Nastran or MSC.Marc, the <analysis_code>_load_aom_data class is not modifiable, whereas for user defined analysis interfaces, it is the user’s responsibility to create this class and place it into the Analysis library.

There are many levels of communication between the main Analysis form and the subordinate Analysis forms and functions. This communication will be discussed in detail in the following sections.

PCL and CustomizationThe Main Analysis Form

428

429Chapter 6: Creating New Analysis Forms Using PCLMain Analysis Form Functions

Main Analysis Form Functions

Changing the AppearanceIt is not always necessary to use “ui_wid_set” to modify the main Analysis form. The following function allows the user to automatically hide many items on the main Analysis form.

Changing the Behavior

The following calls allow the user to modify certain aspects of the way the main Analysis form works. Since the main Analysis form is refreshed every time an action-object change occurs, these calls must be repeated every time the action-object selection is changed.

Normally, the “analysis_main” class will commit all changes to the database (using “db_commit”) whenever the main Analysis form’s Apply button is selected. To prevent this from happening, the user can call the function described below.

analysis_main.set_display_flags (<job_frame_display>, <button_frame_display>, <separator_display>, <apply_button_display>)

Input:

None.

Output:

LOGICAL <job_frame_display> A flag specifying whether the job name / job description frame should be displayed (TRUE) or not (FALSE).

LOGICAL <button_frame_display> A flag specifying whether the button frame should be displayed (TRUE) or not (FALSE).

LOGICAL <separator_display> A flag specifying whether the separator widget should be displayed (TRUE) or not (FALSE).

LOGICAL <apply_button_display> A flag specifying whether the Apply button should be displayed (TRUE) or not (FALSE).

Error Conditions:

None.

Note: For the same reasons mentioned above, this call should be made every time an action-object change occurs.

PCL and CustomizationMain Analysis Form Functions

430

Also, after the Apply button is selected, the “analysis_main” class automatically updates the job name databox and list box. To prevent this from happening, the user can call “dont_update_on_apply”. This call is especially needed if the user’s application closes the Patran database without re-opening it.

If the user wishes to make the job name and job description databoxes un-editable, so that the user can only specify job names via the job name list box, then he should make the following call. This is useful whenever the action-object selection requires choosing an already existing job. An example of such an action-object combination would be “Delete” - “Job”.

To set the job name and job description databoxes to blank, use the function described below.

To load the job name databox with a new job name, use the “load_job_name_dbox” function.

analysis_main.dont_commit_on_apply ()

Input:

None.

Output:

LOGICAL <job_frame_display> A flag specifying whether the job name / job description frame should be displayed (TRUE) or not (FALSE).

LOGICAL <button_frame_display> A flag specifying whether the button frame should be displayed (TRUE) or not (FALSE).

LOGICAL <separator_display> A flag specifying whether the separator widget should be displayed (TRUE) or not (FALSE).

LOGICAL <apply_button_display> A flag specifying whether the Apply button should be displayed (TRUE) or not (FALSE).

Error Conditions:

None.

analysis_main.dont_update_on_apply ()

analysis_main.disable_jobname_and_description ()

analysis_main.set_jobname_blank ()

431Chapter 6: Creating New Analysis Forms Using PCLMain Analysis Form Functions

The function described below will place the name of the “current” job into the job name databox. The “current” job is defined as the last job created or as the name of the Patran database (with the .db suffix removed) if no jobs exist.

The user can force the job name listbox to be refreshed with the following function.

analysis_main.load_job_name_dbox ()

Input:

STRING <job_name> The name of the job to be loaded in the job name databox.

Output:

None.

Error Conditions:

None.

analysis_main.set_jobname_current ()

analysis_main.refresh_jobname_listbox ()

PCL and CustomizationMain Analysis Form Functions

432

<analysis_code>_load_aom_dataThis PCL class dictates the appearance and some of the behavior of the main Analysis form. It specifies the number of action-object-method combinations are valid, what the names for these options are, the number of buttons which exist for each action-object combination and which PCL classes will be activated by these buttons. This class must exist within the Analysis library and must contain as many functions as there are analysis types for the current analysis code. The names of these functions are derived from the names of the analysis types in the manner described in the previous Naming Convention section. For example, if an analysis code has two valid analysis types, “Structural” and “Thermal”, then the two necessary functions would be “structural” and “thermal”. The argument list for each of these functions is as follows.

<analysis_type> ( <num_actions>, <action_labels>, <num_objects>, <object_labels>, <num_methods>, <method_labels>, <num_buttons>, <button_labels>, <button_callbacks>, <apply_class>, <callback_diagnostics>)

Input:

None.

Output:

INTEGER <num_actions> The number of actions valid for this analysis code / analysis type combination. The maximum number of actions allowed is 20.

STRING ARRAY

<action_labels> An array of <num_actions> strings containing the names of all the actions.

INTEGER ARRAY

<num_objects> A <num_actions> array containing the number of objects for each action. There must be at least one object per every action, but the name of this object can be blank. The maximum number of objects allowed per any action is 20.

STRING ARRAY

<object_labels> A <num_actions>*max( <num_objects> ) array containing all the names of the objects per the chosen action.

INTEGER ARRAY

<num_methods> A <num_actions>*max( <num_objects> ) array containing the number of methods valid for every action-object combination. Methods are optional. The maximum number of methods allowed for any action-object combination is 20.

STRING ARRAY

<method_labels> A <num_actions>*max( <num_objects> ) *max(<num_methods> ) array containing the names of all the methods per action and object.

433Chapter 6: Creating New Analysis Forms Using PCLMain Analysis Form Functions

The <analysis_code>_load_aom_data classes for MSC supplied analysis interfaces are not modifiable by the user. For user defined analysis interfaces, it is the user’s responsibility to create this required class and place it into the Analysis library.

Below is an example of an <analysis_code>_load_aom_data function for analysis code “John Code”, analysis type “Structural”. This example is delivered to all users, it is called johncode_loud_aom_data.pcl and resides in the $P3_HOME/customization directory. The steps needed to create a “John Code” Analysis library are as follows:

INTEGER ARRAY

<num_buttons> A <num_actions>*max( <num_objects> ) array containing the number of buttons for every action-object combination. Buttons are optional. The maximum number of buttons allowed for a action-object combination is 10, but only 5 or 6 buttons can Be placed on the main Analysis form at a given time before the form becomes too large for the computer screen.

STRING ARRAY

<button_labels> A <num_actions>*max( <num_objects> )*max( <num_buttons> ) array containing all the button labels per action and object.

STRING ARRAY

<button_callbacks> A <num_actions>*max( <num_objects> )*max (<num_buttons> ) array containing the names of the PCL classes to be activated when the button is selected. Button callbacks are optional; they may be blank.

STRING <apply_class> The name of the PCL class which contains the “apply” function activated by the Apply button on the main Analysis form. This class is optional; it may be blank.

LOGICAL <callback_diagnostics> A flag specifying if all Analysis function calls made by the “analysis_main” class should be echoed to the command line (TRUE) or not (FALSE). Set this flag to TRUE during development in order to debug or just to get a better understanding of the interactions between the main Analysis form and the Analysis functions.

Error Conditions:

None.

Note: 1. As seen is the example below, the size of argument arrays or strings should not be explicitly stated in the <analysis_type> function so that compatibility is maintained with the “analysis_main” class regardless of the dimensions used in “analysis_main”. In other words, declare the argument <object_labels> listed above as “STRING object_labels[]()” instead of “STRING object_labels[31](20,20)”.

2. All string arguments listed in the above call have a maximum of 31 characters.

PCL and CustomizationMain Analysis Form Functions

434

1. Start Patran.

2. Type the following command into the command line: “COMPILE ($P3_HOME)/customization/johncode_load_aom_data.pcl INTO johncode.plb”.

The brackets around $P3_HOME signify that you must type in the evaluation of “$P3_HOME,” such as “/patran/patran3,” instead of typing in “$P3_HOME.” PCL does not directly support UNIX environmental variables.

/* $Header: /madrid/users9/pflib/pcl/custom/RCS/johncode_load_aom_data.pcl,v 1.1 92/12/11 20:55:13 sprack Exp Locker: sprack $ */

/*$$h */ /* * Purpose: * Define the option menu selections, button labels, and * button pcl classes for John Code. */

CLASS johncode_load_aom_data

/*---------------------------------------------------------------------*$$ FUNCTION structural * * Purpose: * Load the option menu data for "John Code-Structural". */

FUNCTION structural( num_actions, action_items, @ num_objects, object_items, @ num_methods, method_items, @ num_buttons, button_labels, @ button_callbacks, preference_class, @ callback_diagnostics ) /* * Local declarations: */ INTEGER num_actions STRING action_items[]() INTEGER num_objects() STRING object_items[]() INTEGER num_methods() STRING method_items[]() INTEGER num_buttons() STRING button_labels[]() STRING button_callbacks[]() STRING preference_class[] LOGICAL callback_diagnostics*$$ FUNCTION structural * * Purpose: * Load the option menu data for "John Code-Structural". */

FUNCTION structural( num_actions, action_items, @ num_objects, object_items, @ num_methods, method_items, @ num_buttons, button_labels, @ button_callbacks, preference_class, @ callback_diagnostics ) /* * Local declarations: */ INTEGER num_actions

435Chapter 6: Creating New Analysis Forms Using PCLMain Analysis Form Functions

STRING action_items[]() INTEGER num_objects() STRING object_items[]() INTEGER num_methods() STRING method_items[]() INTEGER num_buttons() STRING button_labels[]() STRING button_callbacks[]() STRING preference_class[] LOGICAL callback_diagnostics/* * Define the Actions, Objects and Methods. Note that at least * one actions must exist and for every action, one object * must exist. Methods are optional. */

num_actions = 3 action_items(1) = ~Analyze”

action_items(2) = "Read Results File" action_items(3) = "Read Input File"

num_objects(1) = 2 num_objects(2) = 1 num_objects(3) = 1

object_items(1,1) = "Entire Model" object_items(1,2) = "Current Group" object_items(2,1) = "Results Entities" object_items(3,1) = "Model Data"

num_methods(1,1) = 3 num_methods(1,2) = 3 num_methods(2,1) = 1 num_methods(3,1) = 1

method_items(1,1,1) = "Full Run" method_items(1,1,2) = "Check Run" method_items(1,1,3) = "Input File Only" method_items(1,2,1) = "Full Run" method_items(1,2,2) = "Check Run" method_items(1,2,3) = "Input File Only" method_items(2,1,1) = "Translate" method_items(3,1,1) = "Translate"/* * Define the number of buttons for each action-object * combinations. Then define the button labels and * callbacks. */ num_buttons(1,1) = 3 num_buttons(1,2) = 3 num_buttons(2,1) = 2 num_buttons(3,1) = 2 button_labels(1,1,1) = "Button One" button_labels(1,1,2) = "Button Two" button_labels(1,1,3) = "Button Three" button_labels(1,2,1) = "Button One" button_labels(1,2,2) = "Button Two" button_labels(1,2,3) = "Button Three" button_labels(2,1,1) = "Button One" button_labels(2,1,2) = "Button Two" button_labels(3,1,1) = "Button One" button_labels(3,1,2) = "Button Two" button_callbacks(1,1,1) = " " button_callbacks(1,1,2) = " " button_callbacks(1,1,3) = " " button_callbacks(1,2,1) = " " button_callbacks(1,2,2) = " " button_callbacks(1,2,3) = " " button_callbacks(2,1,1) = " "

PCL and CustomizationMain Analysis Form Functions

436

button_callbacks(2,1,2) = " " button_callbacks(3,1,1) = " " button_callbacks(3,1,2) = " "/* * Define the class for general button functions, such as * the "apply" function. */ preference_class = " "

callback_diagnostics = FALSE

END FUNCTION /* structural */

END CLASS /* johncode_load_aom_data */

437Chapter 6: Creating New Analysis Forms Using PCLMain Analysis Form Functions

Subordinate Analysis Forms and FunctionsBelow we see a subordinate Analysis form which is activated by selecting the “Solution Type” button on the main Analysis form and whose function is to allow the user to choose a solution type.

As described above, buttons on the main Analysis form are associated with PCL classes via the <analysis_code>_load_aom_data PCL class. Once a button on the main Analysis form is selected, the “display” function of the associated class is called. If a subordinate Analysis form is open when the action-object selection on the main Analysis form is modified or the main Analysis form is closed, the “exit” function of that form’s associated class is called.

When a subordinate Analysis form is closed by anyone other than the main Analysis form, such as by the Cancel button on the subordinate form, the following call should be made.

This call keeps the “analysis_main” class aware of which subordinate forms are open and which are closed so that when re-entering a given action-object combination “analysis_main” will know which forms were left open, and should thus be re-displayed, and which forms were closed.

There are other optional calls to the “analysis_main” class which will allow the subordinate functions and forms to gather data from the main Analysis form or in some way alter the behavior of the main Analysis form. These functions are described in the “analysis_main” section.

For more details about creating PCL forms, refer to The PATRAN Command Language (PCL) Introduction. For more details about PCL and PCL functions, refer to User Interface and List Processor Functions.

analysis_main.button_class_closed ( <associated_class>)

Input:

STRING <associated_class> The name of the class whose form is being closed.

Output:

None.

Error Conditions:

None.

PCL and CustomizationMain Analysis Form Functions

438

The <apply_class> ClassThe name of this class is defined in the PCL function <analysis_code>_load_aom_data.<analysis_type>. The purpose of this class is to capture events from the main Analysis form. None of the functions listed in this section are mandatory. In fact, the <apply_class> reference in the PCL function <analysis_code>_load_aom_data.<analysis_type> can be left blank.

The most important event to be captured is the main Analysis form’s Apply button being selected. When this happens, the “apply” function of <apply_class> is called. Typically this “apply” function will activate the PCL functions of the user application which will either directly perform the task at hand or spawn an external program to perform this task.

Another event which is trapped is the choosing of a job name from the job name list box. Once a job name has been selected from the list box, but prior to its being placed into the job name databox, the “jobname_about_to_change” function of <apply_class> is called. Once the newly selected job name is placed into the job name databox, the “jobname_was_selected” function is called.

When the main Analysis form is opened for the first time after a Patran database is opened, the “database_was_just_opened” function of <apply_class> is called.

When the current analysis code or analysis type is changed, the “preference_was_just_changed” function of <apply_class> is called. This function is not called when a Patran database with a different analysis code preference from the previous database is opened. It is only called when the analysis preference is changed after a database has been opened.

When the action-object-method selection on the main Analysis form is changed, the “option_menu_changed” function of <apply_class> is called. After the action-object-method change is completed, the “option_menu_change_is_done” function is called. If the action-object combination changed (versus only a change in the method), then two more functions are called: “hide_user_defined_widgets” and “display_user_defined_widgets.” These last two functions allow the user control over subordinate Analysis forms which are not directly affected by events on the main Analysis form will be automatically “exit”ed and re-displayed when an action-object change occurs. Other Analysis forms need to be exited and redisplayed explicitly by the user. This is most conveniently done in “hide_user_defined_widgets” and “display_user_defined_widgets.” Closing and opening of the main Analysis form and a change in analysis preference are also considered to be action-object-method changes. So, whenever any of these three events occur the four functions described in this paragraph will be called.

Similar to the specialized “display” and “exit” calls of a PCL class, all the <apply_class> functions described in this section have no arguments.

The <apply_class> of any MSC supplied analysis interface is not modifiable. For user defined analysis interfaces, it is the user’s responsibility to create the <apply_class>, if one is referenced by the <analysis_code>_load_aom_data. <analysis_type> function, and to place this class in the Analysis library.

The “analysis main” Class

439Chapter 6: Creating New Analysis Forms Using PCLMain Analysis Form Functions

The “analysis_main” is the PCL class which controls the main Analysis form. It is contained in the “p3patran.plb” library and is generic, meaning that its behavior does not change according to analysis preference. This class is not modifiable by the user.

Here is a list of main tasks performed by “analysis_main”.

1. It calls the <analysis_code>_load_aom_data.<analysis_type> function to determine the appearance of the main Analysis form.

2. When a button on the main Analysis form is selected, “analysis_main” calls the “display” function of the associated PCL class.

3. When the action-object combination on the main Analysis form is changed or the main Analysis form is closed, “analysis_main” calls the “exit” function of any class associated with an open subordinate Analysis form.

4. The “analysis_main” keeps tract of which subordinate Analysis forms were left open and which were closed for each action-object combination so that when re-entering an action-object combination, the forms which were left open can be automatically re-displayed.

5. The “analysis_main” reports any main Analysis form event to the <apply_class> as described in the previous section.

In addition to the main tasks mentioned above, there are many “analysis_main” functions which can be called from the <apply_class> or from other subordinate Analysis forms or functions which either control the appearance or behavior of the main Analysis form or extract data from the main Analysis form. Node of these function calls are mandatory, but they can greatly enhance the power of your user defined analysis interface. These optional functions are described below.

PCL and CustomizationMain Analysis Form Functions

440

Fetching Data From “analysis_main”To get the names of the currently selected action, object and method, use the following function.

To get the name and description of the currently selected job, the function described below should be used.

analysis_main.get_analysis_menu_items

(<item_orders>, <item_labels>)

Input:

None.

Output:

INTEGER ARRAY

<item_orders> A 3 element vector containing the order of the current action in the list of valid actions, the order of the current object in the list of objects valid for the chosen action, and the order of the current method in the list of methods valid for the chosen action-object selection. As an example, let us look at the case where the valid objects under “Import” are “Model,” “Results” and “Both” and there are no methods. If the object-method selection is “Import” - “Both” “ “, the <items> would be [2,3,0].

STRING ARRAY

<item_labels> A 3 element vector of strings containing the names of the currently chosen action-object-method. In the above example, <item_labels> would be [“Import,” “Both,” “ “]. The maximum length of each string is 31 characters.

Error Conditions:

None.

441Chapter 6: Creating New Analysis Forms Using PCLMain Analysis Form Functions

In order to get more detailed information about the current job, use “analysis_main.get_current_job_info”

To get the current analysis code and analysis type, use the “get_code_and_type” function.

analysis_main.get_job_name_and_desc

(<job_name>, <job_description>)

Input:

None.

Output:

STRING <job_name> The name of the currently selected job. The maximum length of this string is 31 characters.

STRING <job_description> The description of the currently selected job. The maximum length of this string is 256 characters.

Error Conditions:

None.

analysis_main.get_current_job_info

(<job_name>, <job_description>, <job_id>, <parameter_set_id>, <job_status>)

Input:

None.

Output:

STRING <job_name> The name of the currently selected job. The maximum length of this string is 31 characters.

STRING <job_description> The description of the currently selected job. The maximum length of this string is 256 characters.

INTEGER <job_id> The ID of the current job.

INTEGER <parameter_set_id> The ID of the parameter set associated with this job.

INTEGER <job_status> The status of the current job.

Error Conditions:

None.

PCL and CustomizationMain Analysis Form Functions

442

To fetch the model and results file suffixes for the current analysis code, use the function “get_file_suffixes”.

The user may want to hide, move or re-display items on the main Analysis form. In order to do this, he needs to know the widget IDs of these items. Once he has these IDs he can use “ui_wid_get” to get further information about the items and “ui_wid_set” to manipulate the items. The “get_panel_info” function can be used to get the widget IDs of many Analysis form items.

analysis_main.get_code_and_type

(<analysis_code_name>, <analysis_code_id>, <analysis_type_name>, <analysis_type_id>)

Input:

None.

Output:

STRING <analysis_code_name> The name of the current analysis code. This string has a maximum of 31 characters.

INTEGER <analysis_code_id> The ID of the current analysis code.

STRING <analysis_type_name> The name of the current analysis type. This string has a maximum of 31 characters.

INTEGER <analysis_type_id> The ID of the current analysis type.

Error Conditions:

None.

analysis_main.get_file_suffixes

(<model_suffix>, <results_suffix>)

Input:

None.

Output:

STRING <model_suffix> The user defined model file suffix of the current analysis code. The maximum length of this string is 4 characters.

STRING <results_suffix> The user defined results file suffix of the current analysis code. The maximum length of this string is 4 characters.

Error Conditions:

None.

443Chapter 6: Creating New Analysis Forms Using PCLMain Analysis Form Functions

analysis_main.get_panel_info

(<form_id>, <first_y_location>, <job_frame_id>, <button_frame_id>, <separator_id>, <apply_button_id>)

Input:

None.

Output:

widget <form_id> The ID of the main Analysis form.

REAL <first_y_location> The Y position on the main Analysis form of the first widget following the Analysis Code / Analysis Type text box.

widget <job_frame_id> The ID of the job name / job description frame.

widget <button_frame_id> The ID of the button frame.

widget <separator_id> The ID of the separator widget.

widget <apply_button_id> The ID of the apply button.

Error Conditions:

None.

Note: The values returned by “get_panel_info” are invariant with respect to action-object selection, so this calls only needs to be made once. But the main Analysis form is refreshed every time an action-object change is made (including when the analysis preference is changed or when the main Analysis for is closed and then re-opened), so any modifications to the main Analysis form must be repeated every time a action-object change is made. A good place for any main Analysis form changes would be the <apply_class>.option_menu_change_is_done function.

PCL and CustomizationMain Analysis Form Functions

444

Chapter 7: Modifying the Database Using PCLPCL and Customization

7 Modifying the Database Using PCL

Introduction 2

Querying the MSC Patran Database 3

Loading Definitions for MSC Supported Preferences 7

Loading Definitions for User Defined Preferences 8

Loading Basic Definitions 9

Adding A New Analysis Preference 10

Adding New Element Types/Properties 20

Adding the New Material Properties 63

Adding New Loads and Boundary Conditions 83

Adding Custom General Field Functions 114

Adding New Multi-Point Constraint Definitions 130

Adding Element Verification Parameters 133

Examples of Modifying the Database 136

PCL and CustomizationIntroduction

446

IntroductionThe forms of many Patran applications depend upon analysis code specific definitions contained within the Patran database. These analysis code sensitive applications are Loads and Boundary Conditions, Element Properties, Material Properties and Finite Elements (multi-point constraint equations, available element topologies and element verification). The analysis code specific definitions that they depend upon define element types, element properties, material properties, multi-point constraint equations, loads and boundary conditions and element verification parameters.

Two versions of the Patran database are delivered in the $P3_HOME directory, “template.db” and “base.db”. The “template.db” contains analysis code specific definitions for selected MSC supported interfaces (e.g., Patran MSC.Marc, Patran MSC Nastran, etc.). “base.db” is basically devoid of analysis code specific definitions but does contain some basic definitions. The definitions which are stored in “base.db” are Analysis type, Loads and Boundary Conditions and the association between Loads and Boundary Conditions and all the MSC supported interfaces.

Due to the excessive size of “template.db,” it is highly recommended that the user create his own unique template database which contains only the analysis code specific definitions pertaining to the analysis codes of immediate interest to him. He can call this new template database “<analysis_code>.db,” (e.g., “nastran.db” and can use it as the template for all new databases). See File>New (p. 67) in the Patran Reference Manual. This would produce considerably smaller and simpler databases then would the use of “template.db”.

MSC supplies PCL functions which will add analysis code specific definitions for each of the MSC supplied interfaces to any Patran database. Use of these functions is described in Loading Definitions for MSC Supported Preferences, 451.

Alternatively, the user can define his own analysis code specific definitions in order to create a new interface to Patran. The majority of this chapter is dedicated to teaching the user how to create his own interface.

447Chapter 7: Modifying the Database Using PCLQuerying the Patran Database

Querying the Patran DatabaseThe current version of Patran no longer uses Interbase to provide access to a database. The Interbase product and tools are still supplied with Patran to support conversions of older databases to be compatible with the current version of Patran. The database query tool discussed below can be used to examine the contents of databases built with older versions of Patran. A database query can be used to determine whether an application has successfully accomplished its task, to determine how other applications operate, or to determine what already exists in a database.

The database querying program is located in the $P3_HOME/bin directory. The program is called qli, which is an acronym for Query Language Interpreter and can be used to investigate the contents of a database.

To start qli, simply execute the qli command (for example, $P3_HOME/bin/qli). The qli program supports a subset of SQL, the standard query language, along with having many program specific commands of its own. The six major qli specific commands are “ready,” “show,” “list,” “print,” “help” and “quit.” A brief description of these commands are given below. For further information about qli, see the “help” command within qli. Further information about SQL can be obtained from any SQL reference book.

Ready The ready command opens the specified database and connects it to the qli process. The syntax is “ready <database_name>.” The qli program does not support any on-line arguments, i.e., “qli <database_name>” won’t work. The “ready” command must be made from within qli.

Quit The quit command will exit the qli process, closing the database if it is open.

Help The help command provides on-line help for all of the commands and command syntax supported by the qli program.

Show The show command either shows the names of all the relations in the database (“show relations”) or show the actual definition of a specified relation (“show <relation_name>”, for example: “show point”).

The following is a listing of all the relations in the database delivered with Patran V7.5.

ALLOWABLE_MAGIC_PROP MPC

ALLOWABLE_MATL_PROP MPC_IN_GROUP

ALLOWABLE_PHYS_PROP MPC_TERM

ANALYSIS_CODE MPC_TERM_DOF

ANALYSIS_ELEMENTS MPC_TERM_NODE

ANALYSIS_ELEMENT_SUMMARY MPC_TYPE

ANALYSIS_STEP NODAL_RESULT

Show (continued)

ANALYSIS_TYPE NODE_PATTERN

ANNOTATION PARAM

PCL and CustomizationQuerying the Patran Database

448

APPL_GEO_REGION PARAM_SET

ARBITRARY_CLIPPING_PLANE PERSISTENT_MEMORY

ASSIGNED_LOAD_SET PHYS_PROP_DEFN

CLIPPING_PLANE PHYS_PROP_REGION

CONDENSE_OPTION PHYS_PROP_SET_DEFN

CONFIG PHYS_PROP_SET_MBR_DEFN

CONFIG_PARAM POSTED_ANNOTATION

CONSTITUTIVE_MODEL POSTED_CLIPPING_PLANE

CONSTITUTIVE_MODELS_SPECIFIED

POSTED_GROUP

CONTROL_INFO PREFERENCE

COORDINATE_FRAME PRIMARY_RESULT

DEGREES_OF_FREEDOM RANGE

DISPLAY_PROPERTY REGION_LAYER

DOF_SET RENDER

DOF_SET_MEMBER RESULTS_COORD_SYS

DS_LBC RESULTS_DATA_BULK

DV_LBC RESULTS_DATA_REGISTER

ELEMENT_EDGE_NODE RESULTS_INFO

ELEMENT_FACE RESULTS_RDM_TARGET

ELEMENT_FACE_EDGE RESULTS_RDM_TOOL

ELEMENT_FACE_NODE RESULT_TYPE

ELEMENT_IN_REGION RESULT_VALUES

ELEMENT_POSITION SECONDARY_RESULT

ELEMENT_TOPOLOGY SECTION_POSITION

ELEMENT_TYPE SELECTED_ELEMENT_TYPE

ELEMENT_VERIFICATION_PARMS SELECTED_PROPERTY_SET

FEM_DS_LBC SHORT_FIBER

FEM_DV_LBC SOURCE_FILE

FEM_SS_LBC SPECTRUM

FEM_SV_LBC SPECTRUM_COLOR

FIELD SS_LBC

FIELD_25_LBC SUBRANGE

FIELD_FEM SUB_CASE

449Chapter 7: Modifying the Database Using PCLQuerying the Patran Database

FIELD_FUNCTION SUB_MPC

FIELD_GENERAL SUM_RES_INFO

FIELD_GENERAL_FUNCTIONS SUPPORTED_ANALYSIS_TYPE

FIELD_TABLE SV_LBC

FORMULATION_OPTION TEMP_MPC

FORMULATION_OPTION_ALIAS TEMP_RESULT

GEOMETRIC_OPTION VALID_ANAL_CODE

GEOMETRIC_REGION_LIST VALID_ANAL_LOAD_TYPE

GLOBAL_VARIABLE VALID_CONSTITUTIVE_MODELS

GROUP VALID_LBC_TARGET_ELEM

HALPIN_TSAI VALID_LBC_TYPES

INSTANCE VALID_MATERIAL_CATEGORIES

INSTANCE_IN_GROUP VALID_MPC_TYPE

JOBNAME VIEW

JOBNAME_LIST VIEWPORT

LAMINATE VIEWPORT_TITLE

LAMINATE_LAYER VPPOSTED_TITLE

LAMINATE_OPTION XXX_CLIENT_ENTITY

LAYER_POSITION XXX_CLIENT_INTEGER_DATA

LBC XXX_CLIENT_LOGICAL_DATA

LBC_APP_REGION XXX_CLIENT_REAL_DATA

LBC_GRAPHICS_VECTOR XXX_CLIENT_STRING_DATA

LBC_IN_GROUP XYAXIS

LBC_SELECT_DATATYPE XYCURVE

LBC_TYPE XYCURVE_DATA

LBC_VARIABLE_DEFN XYLEGEND

LIGHT_SOURCE XYLEGEND_ITEM

LOAD_BC XYPOSTED_CURVE

LOAD_CASE XYPOSTED_LEGEND_ITEM

LOOKUP_TABLE XYPOSTED_TITLE

LOOKUP_TABLE_VALUE XYTITLE_TABLE

MATERIAL XYWINDOW

MATERIAL_CATEGORY

MATERIAL_DIRECTIONALITY

PCL and CustomizationQuerying the Patran Database

450

MATERIAL_LINEARITY

MATL_CONST_MODEL_DEFN

MATL_DISPLAY_CATEGORY

MATL_DISPLAY_SUB_CATEGORY

MATL_MAGIC

MATL_MAGIC_ALIAS

MATL_MAGIC_DEFINITION

MATL_PROP_ALIAS

MATL_PROP_DEFN

MATL_PROP_VALUE

MEMORY_DATABASE

MESH_PARAM

MIX_COMPONENT

List The list command will list the contents of a relation (for example, list all points). The syntax is “list <relation_name>.” This command can have qualifiers associated with it. The main qualifier is “where,” for example: “list point where ID = 12.” Many conditions can be linked with “and” for example: “list point where x > 0.0 and x < 1.0.” The difference between list and show is that show merely displays the structure of the relation whereas list will display the contents of the relation.

Print The print command is identical to the list command except that the list command displays one value per line whereas the print command displays one relation per line.

list: id 5 x 1.0 y 1.5 z -0.5

id 6 x 0.5 y 0.0 z -1.0

print: id x y z 5 1.0 1.5 -0.5 6 0.5 0.0 -1.0

451Chapter 7: Modifying the Database Using PCLLoading Definitions for MSC Supported Preferences

Loading Definitions for MSC Supported PreferencesMSC supplies a number of PCL functions which will load the analysis code specific definitions required for each of the MSC supported interfaces. These functions make it easy for the user to create his own template database instead of using $P3_HOME/template.db which is excessively large and complex. The general steps for creating a new template database are:

1. Within Patran, open a new database using $P3_HOME/base.db as the template. You could call this new database “<analysis_code>.db,” (e.g., “mscnastran.db”).

2. In the Patran command line, type the command “load_<analysis_code>(),” (e.g., “load_mscnastran()”). The complete list of the available commands is given below.

3. When the command is finished (heart beat is green), close the database, saving it as a new template database.

4. When opening a new database, choose the newly created template database, instead of $P3_HOME/template.db

The complete list of MSC supplied loading functions is:

These functions can be used on any database which does not already contain definitions for the particular interface. Any number of interfaces can be added to a database at any time, even after the model has been created.

load_mscnastran() for Patran MSC Nastran

load_marck5() for MSC.Marc (K5)

load_marc() for MSC.Marc (pre K5)

load_ansys5() for Patran ANSYS (Revision 5.0)

load_ansys() for Patran ANSYS (pre Revision 5.0)

load_abaqus() for Patran ABAQUS

load_dyna3d() for Patran LS-DYNA3D

load_padvancedfea() for Patran Advanced FEA

load_pfea() for Patran FEA

load_pcfd() for Patran CFD

load_pthermal() for Patran Thermal

load_pteam() for Patran TEAM

load_samcef() for Patran SAMCEF

load_patran2nf() for PATRAN 2 Neutral File Preference

PCL and CustomizationLoading Definitions for User Defined Preferences

452

Loading Definitions for User Defined PreferencesIn addition to loading the analysis code specific definitions for a MSC supplied interface as described in the previous section, the user can add analysis code specific definitions for his own analysis code. The rest of this chapter is dedicated to describing all the PCL callable functions needed to add definitions for a user defined interface.

There are three basic ways to manage the PCL functions which add the definitions for your new analysis code. The user can create a PCL function, “load_<analysis_code>”, which would in turn make all the appropriate PCL function calls to define the new analysis code. This function would be very similar to the PCL functions delivered by MSC (e.g., “load_marck5”, “load_ansys,” etc.) In fact, the user could compile this function into p3patran.plb, giving universal access to the function. Alternatively, the user can create a session file which contains the appropriate calls to define the new analysis code. The example at the end of the chapter uses this method. Lastly, the needed commands could be directly input to the Patran command line, though this method would, in most cases, be undesirable.

It is important to understand that “base.db” contains certain code specific definitions, namely the three analysis types listed in the description of db_create_analysis_type, 454, all the load type definitions listed in the description of db_create_lbc_type_defn, 543 and the associativity between these load type definitions and all the MSC supplied analysis interfaces. In other words, all Patran databases will contain these definitions and they need never be repeated.

There are other definitions which are relatively basic and can be added to “base.db” with one simple PCL function call, “load_generics()” is completely options and is intended solely as a short cut. The user can call “load_generics()” and then reference any of the definitions loaded by this function without going through the labor defining all of them himself. All the MSC supplied interface loading functions, (e.g., “load_mscnastran()”) described in the previous section use “load_generics().” So, a database which contains definitions for any MSC supported interface will also contain all the definitions loaded by “load_generics().” If the definitions added by “load_generics()” already exist, they need not be repeated, but repeating them will also not cause any problems.

Due to the size of “template.db,” it is strongly recommended that the user develop his new template database from “base.db” instead of “templated.db.” But, if he wishes to use “template.db” he should note that all definitions detailed in the rest of this chapter exist in “template.db.” In this case, none of the documented definitions need be repeated and the repetition of certain definitions will create errors. In other words, it is impossible to modify the definitions for an analysis code once defined. In fact, even when redefinition does not create an error, the command will not be obeyed, but instead simply ignored.

Lastly, the way that the analysis interfaces recognize data is through the definitions described in this chapter. If two interfaces recognize the same set of definitions, then a model will easily transfer from one analysis code to the other. If there are differences in the sets of definitions recognized by the two analysis codes, then data is likely to be lost when transferring a model from analysis code to analysis code. So, in order to maintain consistency with the MSC supplied interfaces, it behooves the user to use the definitions documented in this chapter (which are the definitions used by the MSC supplied interfaces) as much as possible, instead of making unique definitions of his own. Most of these definitions are identified by an integer ID. When users or third-parties add new definitions, the IDs for these should be in the range 20000 to 29999 to avoid conflict with MSC-defined ID’s.

453Chapter 7: Modifying the Database Using PCLLoading Basic Definitions

Loading Basic DefinitionsThe function described below will load relatively basic analysis code definitions into the open database. It is entirely optional and is intended solely as a labor saver. The user can call “load_generics()” and then reference any of the definitions it loads without going thought the trouble of individually creating each definition himself. “load_generics()” will add the following definitions: all degrees-of-freedom listed in the description of db_create_degree_of_freedom(), all degree-of-freedom sets listed under db_create_dof_set(), all material linearities listed under options listed under db_create_laminate_opt(), all condensation options listed under db_create_formulation_opt(), all geometric options listed under db_create_geometric_opt(), all element types listed under db_create_element_type(), all element property words listed under db_create_phys_prop_defn(), and all material property words listed under db_create_matl_prop_defn().

load_generics()

Input:

None.

Output:

None.

PCL and CustomizationAdding A New Analysis Preference

454

Adding A New Analysis PreferenceA new analysis code can be added to analysis preferences by adding any new analysis types and then adding the new analysis code.

A new analysis type can be added by using the following PCL function:

This function should only be used to add new analysis types. Three analysis types are already defined in all Patran databases:

The function to add a new analysis code is

db_create_analysis_type (<analy_type_id>, <analy_type_name>)

Input:

INTEGER <analy_type_id> The ID for referencing the analysis type. This ID must be unique with respect to all previously defined analysis type IDs.

CHARACTER STRING

<analy_type_name> The name of the analysis type.

Output:

INTEGER <Return Value> Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

Analysis type <analy_type_id>

Structural Analysis 1

Thermal Analysis 2

Fluid Dynamics 3

455Chapter 7: Modifying the Database Using PCLAdding A New Analysis Preference

The following analysis code IDs should be reserved for MSC supported analysis interfaces:

db_create_analysis_code (<analy_code_id>, <analy_code_name>, <model_suffix>, <results_suffix>, <num_analy_types>, <analy_type_ids>, <def_analy_type>)

Input:

INTEGER <analy_code_id> The ID for referencing the analysis code. This ID must be unique with respect to all previously defined analysis code IDs. Users and third parties should define analysis code IDs in the range 20000 to 29999.

CHARACTER STRING

<analy_code_name> The name of the analysis code.

CHARACTER STRING

<model_suffix> Suffix to be added to the analysis code input file.

CHARACTER STRING

<results_suffix> Suffix to be added to the analysis code results file.

INTEGER <num_analy_types> The number of analysis types valid for this analysis code.

INTEGER ARRAY

<analy_type_ids> The <num_analy_types> analysis types IDs valid for this analysis code.

INTEGER <def_analy_type> The analysis type ID of the default analysis type.

Output:

INTEGER <Return Value> Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

PCL and CustomizationAdding A New Analysis Preference

456

• The following PCL function can be used to specify which analysis code will be the default analysis code, i.e., which analysis code is automatically chosen as the analysis preference upon

Analysis Code <analy_code_id>

MSC Nastran 1

ABAQUS 2

ANSYS 3

MARC 4

Patran FEA 5

Patran Thermal 6

Patran CFD 9

Patran Advanced FEA 10

MARC K5 11

ANSYS 5 12

Patran TEAM 13

SAMCEF 15

PATRAN 2NF 16

MSC.Dytran 17

Patran STRUCTURAL OPTIMIZATION

19

MARC K6 20

LMS CADA-X 21

FASTRUDL 31

SESAM 32*

*Conflict with DYNA3D will be resolved when the DYNA3D preference is eliminated.

DYNA3D 32

RCS 41

CFX-F3D 42

CFX-FLOW 43

MSC.DropTest 51

MSC.Forging 52

LS-DYNA3D 10001

PAMCRASH 13001

457Chapter 7: Modifying the Database Using PCLAdding A New Analysis Preference

opening a new database.

db_get_default_anal_code

(<analysis_code_name>)

Input:

None

Output:

STRING[31] <analysis_code_name>

Analysis code name.

Error Conditions:

None.

PCL and CustomizationAdding A New Analysis Preference

458

Since the action of the above function, namely the changing of the chosen analysis code and analysis type, might affect forms which are currently being displayed, the user might wish to include a call to the widget refresh function at the end of his analysis code definition loading session file or PCL function. The syntax of this refresh function is shown below.

ui_wid_refresh( )

db_get_anal_code_id (<analysis_code_name>, <analysis_code_id>)

Input:

STRING[31] <analysis_code_name> Analysis code name.

Output:

INTEGER <analysis_code_id> Analysis code ID.

Error Conditions:

None.

uil_pref_analysis.set_analysis_pref

(<analy_code_name>, <analy_type_name>, <input_file_suffix>, <output_file_suffix>)

Input:

CHARACTER STRING

<analy_code_name> The name of the analysis code to be set as the default. This name can be no more than 31 characters.

CHARACTER STRING

<analy_type_name> The name of the analysis type to be set as the default for the chosen analysis code. This name can be no more than 31 characters.

CHARACTER STRING

<input_file_suffix> The default file suffix for the input files of the chosen analysis code. This suffix can be no more than 4 characters.

CHARACTER STRING

<output_file_suffix> The default file suffix for the output files of the chosen analysis code. This suffix can be no more than 4 characters.

Output:

None.

Error Conditions:

None.

459Chapter 7: Modifying the Database Using PCLAdding A New Analysis Preference

Custom Data and Application Region Sub-FormsThis section is for application developers who want to create their own customized Data and Application Region sub-form classes. The class names for these custom forms will be stored and loaded in from the database with a selected analysis preference. They can then accessed by pressing the “Input Data...” and/or “Select Application Region...” buttons in the Create action of the Loads/Boundary Conditions form. If a selected analysis preference does not have a custom sub-form class(es) associated with it for the data and/or application region classes, it will use the Patran default sub-form class(es).

The Create action of the Loads/Boundary Conditions form is the parent class for the two sub-form classes. It makes a number of calls to functions within the default sub-form classes to manage them. Consequently, the custom sub-form classes must contain these same function names called from the Parent class in order to maintain the integrity of the Parent class code. The sub-form classes may or may not utilize all of the function names called from the Parent class.

Since the name of the sub-form class may vary, the parent Create class must have a generic way of accessing the sub-form class. Normally this is done by using the ui_exec_function(classname, function) call with the class name that was loaded in from the database with the selected analysis preference. This call will work for class name functions that don’t require arguments for data passing.

In order to facilitate communication between the custom sub-form classes and the parent Create class with data passing arguments, a generic interface layer has been created consisting of two new classes:

• lbc_input

• lbc_select

These new classes are independent of the classes that control the data input and application region selection sub-forms. The interface layer is basically a set of storage areas for the common data being passed between the Create class and the associated custom class managing the sub-form.

Each custom sub-form class is required to contain function names which will be called by Patran whether the custom sub-forms utilize them or not.Some of the functions pass data to/from the calling class. Within the functions requiring data passing, the programmer must include a call to the corresponding lbc_input or lbc_select class to retrieve or return data as noted in the following documented interface calls for these functions.

Following is a list of the function names that Patran uses for communication and management of its two default sub-forms.

Required Functions for Data Input Class

Important:One of the required function names for each custom class is initx. The initial Patran design of the LBC forms was made to bypass the standard init function and use an initx function. The initx functions of the custom sub-form classes must contain a call to ui_exec_function(classname, “init”) in order for the UIMS to know that the form has been initialized. Consequently the ui_form_exists(classname) call will return correctly whether or not the form has been initialized.

PCL and CustomizationAdding A New Analysis Preference

460

The required function names for this class are:

init()initx()display()input_disabled()set_cur_data()get_data()get_mem()update_cur_data()get_data_defn()

The functions that require data passing through the generic interface layer are described below:

Notes:

Since it only makes sense to have access to the custom data input form, the variable declaration is optional and the interface call can be made as:

lbc_input.set_input_disable(FALSE)

Required Function for Data Input Class

Input_disabled()

Description:

Called by loadsbcs_create class to determine if the data input form for the current (object, method, target) should be accessible.

Variable declarations (optional):

LOGICAL flag True: Enable the Input Data button.

False: Disable the Input Data button.

Preference call:

lbc_input.set_input_disable(flag)

Error Conditions:

None.

461Chapter 7: Modifying the Database Using PCLAdding A New Analysis Preference

Notes:

Requires #include “app_lbcs.p” for variable array sizes.

Required Function for Data Input Class

set_cur_data()

Description:

When an existing LBC set is selected from the listbox on the Create panel of the Loads/Boundary Conditions form, the values for the widgets which are to be displayed in this sub-form are set with the given values.

Variable declarations:

REAL lbc_sf Loads/BC Set Scale Factor.

STRING[LBC_DATA_LEN]

cid_data Coordinate Frame.

INTEGER num_data Number of databoxes on the Input Data form.

INTEGER(NUM_LBC_INP_FLDS)

data_id Internal Ids corresponding to the databoxes.

STRING[LBC_DATA_LEN](NUM_LBC_INP_FLDS)

stat_data Values from static databoxes.

STRING[LBC_DATA_LEN](NUM_LBC_INP_FLDS)

dyn_data Values from dynamic databoxes.

Preference call:

lbc_input.get_cur_data(lbc_sf, cid_data, num_data, data_id, stat_id, dyn_id)

Error Conditions:

None.

PCL and CustomizationAdding A New Analysis Preference

462

Notes:

Requires #include “app_lbcs.p” for variable array sizes.

Required Function for Data Input Class

get_data()

Description:

Used to transfer data from the data input sub-form to the loadsbcs_create class when creating a new set.

Variable declarations:

REAL lbc_sf Loads/BC Set Scale Factor.

STRING[LBC_DATA_LEN]

cid_data Coordinate Frame.

INTEGER num_data Number of databoxes on the Input Data form.

INTEGER(NUM_LBC_INP_FLDS)

data_id Internal Ids corresponding to the databoxes.

STRING[LBC_DATA_LEN](NUM_LBC_INP_FLDS)

stat_data Values from static databoxes.

STRING[LBC_DATA_LEN](NUM_LBC_INP_FLDS)

dyn_data Values from dynamic databoxes.

Preference call:

lbc_input.set_data(lbc_sf, cid_data, num_data, data_id, stat_id, dyn_id)

Error Conditions:

None.

463Chapter 7: Modifying the Database Using PCLAdding A New Analysis Preference

Required Functions for Application Region Selection Class

The required function names for this class are

The functions that require data passing through the generic interface layer are described below:

Required Function for Data Input Class

get_mem()

Description:

Allocate memory for any classwide virtual arrays.

Variable declarations:

INTEGER stat Return status of success or failure (0: success; -1: error)

Preference call:

lbc_input.set_status(stat)

Error Conditions:

None.

init()

initx()

display()

get_mem()

get_data()

set_cur_data()

get_geo_index()

clear_app_region()

update_cur_data()

PCL and CustomizationAdding A New Analysis Preference

464

Example:

geometry_str = lbc_select.get_geo_group_str()IF (geometry_str == LBC_GEOMETRY_STR) THENgeo_index = 1ELSE IF (geometry_str == LBC_FEM_STR) THENgeo_index = 2END IFlbc_select.set_geo_index(geo_index)

Notes:

Requires #include “app_lbcs.p” for LBC string definitions.

Required Function for Data Input Class

get_geo_index()

Description:

Called by the loadsbcs_create class when an existing set is selected from the listbox. Given the selected set’s geometry string, this function returns the internal index for its application region’s geometry filter.

Variable declarations:

STRING geometry_str[31} Real Geometry Group string:

LBC_GEOMETRY_STR

LBC_FEM_STR

INTEGER geo_index Geometry Group internal index

1: Geometry

2: FEM

Preference call:

geometry_str = lbc_select.get_geo_group_str( )

lbc_select.set_geo_index(geo_index)

Error Conditions:

None.

465Chapter 7: Modifying the Database Using PCLAdding A New Analysis Preference

Notes:

lbc_select.get_cur_2_app_data is only needed for 2 application region forms.

Required Function for Data Input Class

set_cur_data()

Description:

When an existing LBC set is selected from the listbox on the Create panel of the Loads/Boundary Conditions form, the values for the widgets which are to be displayed in this sub-form are set by changing the values with the given data.

Variable declarations:

INTEGER grp Geometry Group.

INTEGER num_list Number of application region lists.

STRING[VIRTUAL](VIRTUAL)

app_list Application region lists.

INTEGER couple Coupling option.

INTEGER order Ordering option.

Preference call:

lbc_select.get_cur_data(grp, num_list, app_list)

lbc_select.get_cur_2_app_data(couple, order)

Error Conditions:

None.

PCL and CustomizationAdding A New Analysis Preference

466

Notes:

lbc_select.set_2_app_data is only needed for 2 application region forms.

Required Function for Data Input Class

get_data()

Description:

Used to transfer data from the Select Application Region sub-form to the loadsbcs_create class when creating a new set.

Variable declarations:

INTEGER result Return status of success or failure. (0: success; -1: error)

INTEGER num_ar Number of application region.

INTEGER(2) ar_id Application Region ids.

STRING[VIRTUAL] app_list1 Application Region list 1 of entities.

STRING[VIRTUAL] app_list2 Application Region list 2 of entities.

STRING geo_fltr[31] Geometry filter which restricts entities which can be selected.

INTEGER couple Coupling option.

INTEGER order Ordering option.

Preference call:

lbc_select.set_status(result)

lbc_select.set_data(num_ar, ar_id, app_list1, app_list2, geo_fltr)

lbc_select.set_2_app_data(couple, order)

Error Conditions:

None.

Required Function for Data Input Class

get_mem()

Description:

Allocate memory for any classwide virtual arrays.

Variable declarations:

INTEGER stat Return status of success or failure. 0: success; -1: error)

Preference call:

467Chapter 7: Modifying the Database Using PCLAdding A New Analysis Preference

lbc_select.set_status(stat)

Error Conditions:

None.

PCL and CustomizationAdding New Element Types/Properties

468

Adding New Element Types/PropertiesFirst, all the element types of the new analysis code must be defined. In order to do this, first define the generic element attributes. These element attributes include degrees-of-freedom, degree-of-freedom sets, material linearities, material directionalities, laminate options, element condensation options, element formulation options, element geometric options and generic element types. Then use the element attributes in order to define the analysis code specific element types. Once the element types have been fully defined, the generic property words to be applied to each of these element types. Then, define the analysis code specific properties for all these property words and then group the words into property sets. Finally, associate the property sets to the appropriate element types.

If the PATRAN 2.5 neutral file is going to be used as a mode of model data communication, PATRAN 2.5 element configuration codes must be assigned to the analysis code specific element types and neutral file order must be assigned to the property words of a property set. PATRAN 2.5 configuration codes are assigned during the definition of analysis code specific element types. Neutral file order for property words is assigned during the grouping of property words into property sets.

In summary, the steps of adding element types and element properties are as follows:

• Define Generic Element Attributes:

Degrees-of-Freedom.

Degree-of-Freedom Sets.

Material Linearities.

Material Directionalities.

Laminate Options.

Element Condensation Options.

Element Formulation Options.

Element Geometric Options.

Element Types.

• Define Analysis Code Specific Element Types and, if needed, assign PATRAN 2.5 configuration codes to analysis code specific element types.

• Define Generic Property Words.

• Assign Analysis Code Specific Properties to the Property Words.

• Group Property Words into Property Sets and, if needed, assign neutral file order to property words.

• Assign Property Sets to Element Types.

Degrees-of-Freedom

To create new degrees-of-freedom use:

469Chapter 7: Modifying the Database Using PCLAdding New Element Types/Properties

The list of degrees-of-freedom defined by “load_generics()” is:

Degree-of-Freedom Sets

To create new degree-of-freedom sets use:

db_create_degree_of_freedom ( <dof_id>, <dof_name> )

Input:

INTEGER <dof_id> The ID for referencing the degree-of-freedom. This ID must be unique with respect to all previously defined degree-of-freedom IDs.

CHARACTER STRING

<dof_name> The name of the degree-of-freedom.

Output:

INTEGER <Return Value> Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

<dof_name> <dof_id>

UX 1

UY 2

UZ 3

RX 4

RY 5

RZ 6

Temperature 7

Voltage 8

Magnetic Flux 9

Pressure 10

Top Temperature 11

Middle Temperature 12

Bottom Temperature 13

PCL and CustomizationAdding New Element Types/Properties

470

The list of degree-of-freedom sets defined by “load_generics()” is:

db_create_dof_set ( <dof_set_id>, <dof_set_name>, <num_dofs>, <dof_ids> )

Input:

INTEGER <dof_set_id> The ID used to reference the degree-of-freedom set. This ID must be unique with respect to all previously defined degree-of-freedom set IDs.

CHARACTER STRING

<dof_set_name> The name of the degree-of-freedom set.

INTEGER <num_dofs> The number of degrees-of-freedom in this set.

INTEGER ARRAY

<dof_ids> The <num_dofs> IDs of the degrees-of-freedom making up this set.

Output:

INTEGER <Return Value> Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

<dof_set_name> <dof_set_id>

UX 1

UY 2

UZ 3

RX 4

RY 5

RZ 6

Temperature 7

Voltage 8

Magnetic Flux 9

Pressure 10

Top Temperature 11

Middle Temperature 12

Bottom Temperature 13

UX, UY 14

UX, UY, UZ 15

UX, UY, RX 16

471Chapter 7: Modifying the Database Using PCLAdding New Element Types/Properties

UX, UY, RZ 17

UX, UY, UZ, RX 18

UX, UY, UZ, RX, RY 19

UX, UY, UZ, RX, RY, RZ 20

RX, RY, RZ 21

UX, UY, Temp, Mag Flux 22

Volt, Mag Flux 23

UX, UY, UZ, Temp 24

UX, UY, UZ, Temp, Volt, Mag Flux

25

Temp, Volt, Mag Flux 26

Temp, Volt 27

UX, UY, UZ, Pres 28

UX, UY, Temp 29

UX, UY, Temp, Pres 30

Temp, Pres 31

Top Temp, Mid Temp, Bot Temp

32

Top Temp, Bot Temp 33

All 34

<dof_set_name> <dof_set_id>

PCL and CustomizationAdding New Element Types/Properties

472

Material Linearities

To define material linearities use:

The list of material linearities defined by “load_generics()” is:

Material Directionalities

To define material directionalities use:

db_create_matl_lin ( <lin_id>, <lin_name> )

Input:

INTEGER <lin_id> The ID used to reference the material linearity. This is must be unique with respect to all previously defined material linearities.

CHARACTER STRING

<lin_name> The name of the material linearity.

Output:

INTEGER <Return Value> Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

<lin_name> <lin_id>

N/A 0

Linear Elastic 1

Nonlinear Elastic 2

Elastoplastic 3

Hyperelastic 4

Viscoelastic 5

Creep 6

473Chapter 7: Modifying the Database Using PCLAdding New Element Types/Properties

:

The material directionalities defined by “load_generics()” is:

Laminate Options

To create the laminate options use:

db_create_matl_dir ( <dir_id>, <dir_name> )

Input:

INTEGER <dir_id> The ID used to reference the material directionality. This ID must be unique with respect to all previously defined material directionality IDs.

CHARACTER STRING

<dir_name>

The name of the material directionality.

Output:

INTEGER <Return Value>

Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

<dir_name> <dir_id>

N/A 0

Isotropic 1

Orthotropic 2

Anisotropic 3

2D Orthotropic 4

2D Anisotropic 5

PCL and CustomizationAdding New Element Types/Properties

474

The list of laminate options defined by “load_generics()” is:

db_create_laminate_opt ( <lam_id>, <lam_name> )

Input:

INTEGER <lam_id> The ID used to reference the laminate option. This ID must be unique with respect to all previously defined laminate option IDs.

CHARACTER STRING

<lam_name>

The name of the laminate option.

Output:

INTEGER <Return Value>

Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

<lam_name> <lam_id>

Homogeneous 1

N/A 2

Laminate 3

Equivalent Section 4

475Chapter 7: Modifying the Database Using PCLAdding New Element Types/Properties

Element Condensation Options

To create the element condensation options use:

The list of element condensation options defined by “load_generics()” is:

db_create_condense_opt

( <condense_id>, <condense_name> )

Input:

INTEGER <condense_id> The ID used to reference the element condensation option. Must be unique with respect to all previously defined element condensation option IDs. Users and third-parties should define IDs in the range 20000 to 29999 to avoid conflicts with MSC-defined IDs

CHARACTER STRING

<condense_name> The name of the element condensation option.

Output:

INTEGER <Return Value> Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

PCL and CustomizationAdding New Element Types/Properties

476

<condense_name> <condense_id>

Axisymmetric Link 1

Bending Only 11

Cable 12

Combination 13

Cylindrical 14

Damper 15

Deformable 16

Link 17

Mass 18

Membrane 19

N/A 20

Plane Strain 21

Plane Stress 22

Planar 23

Plate 24

Rigid 25

Rod 26

Shear Panel 27

Shell 28

Slide Line 29

Solid 30

Spherical 31

Spring 32

Spring/Damper 33

Surface Effect 34

Thin Shell 35

Thick Shell 36

Truss 37

Tube within Tube 38

Twist Panel 39

Uniaxial 40

2D Beam 41

3D Beam 42

477Chapter 7: Modifying the Database Using PCLAdding New Element Types/Properties

Element Formulation Options

To create the element formulation options use:

2D Gap 43

3D Gap 44

3D Link 45

2D Link 46

2D Rigid Surface 47

3D Rigid Surface 48

3D Thin-Wall Beam 49

General 50

General Thin Shell 51

General Thick Shell 52

Rotary Inertia 53

Linear 54

Non_linear 55

Parabolic 56

Parallel 57

Radial 58

Spatial 59

Bezier 60

Segments 61

Axisymmetric 62

<condense_name> <condense_id>

PCL and CustomizationAdding New Element Types/Properties

478

The list of element formulation options defined by “load_generics()” is:

db_create_formulation_opt

( <form_id>, <form_name> )

Input:

INTEGER <form_id> The ID used to reference the element formulation option. This ID must be unique with respect to all previously defined element formulation option IDs. Users and third-parties should define IDs in the range 20000 to 29999 to avoid conflicts with MSC-defined IDs.

CHARACTER STRING

<form_name>

The name of the element formulation option.

Output:

INTEGER <Return Value>

Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

479Chapter 7: Modifying the Database Using PCLAdding New Element Types/Properties

<form_name> <form_id>

standard formulation 1

deformable 2

Assumed Strain 10

Conduction 11

Convection 12

Convection/Radiation 13

Constant Volume 14

Constant Vol/Assumed Strain 15

Constant Volume/Twist 16

Coupled 17

Euler-Bernoulli 18

Euler-Bernoulli w/Shear 19

Fixed Direction 20

Grounded 21

Hybrid 22

Hybrid/Reduced Integration 23

Hybrid/Twist 24

Linear Axial Strain 25

Linear Temp Distr 26

Lumped 27

N/A 28

Parabolic Shear Strain 29

Plastic 30

Quadratic Temp Distr 31

Radiation 32

Reduced Integration 33

Revised Formulation 34

Rigid Contact Surface 35

Rotational DOF 36

Scalar 37

Shell Stiffener 38

Shell Stiffener w/Warp 39

True Distance 40

PCL and CustomizationAdding New Element Types/Properties

480

Element Geometric Options

To create the element geometric options use:

The list of element geometric options defined by “load_generics()” is:

Twist 41

Uniaxial 42

Viscous 43

Convectio/Diffusion 44

Conv/Diff w/Disprsion Cntrl 45

Ovalization Only 46

Ovaliz Only w/Apprx Fourier 47

Cubic Interpolation 48

Cubic Hybrid 49

Cubic Initially Straight 50

Soft Contact 51

Rigid Contact 52

db_create_geometric_opt

( <geom_id>, <geom_name> )

Input:

INTEGER <geom_id> The ID used to reference the element geometric option. This ID must be unique with respect to all previously defined element geometric option IDs.

CHARACTER STRING

<geom_name>

The name of the element geometric option. Users and third-parties should define IDs in the range 20000 to 29999 to avoid conflicts with MSC-defined IDs.

Output:

INTEGER <Return Value>

Status return value. The value will be 0 if the routine is successful.

Error Conditions:

None.

<form_name> <form_id>

481Chapter 7: Modifying the Database Using PCLAdding New Element Types/Properties

Generic Element Types

To create the generic element types use:

<geom_name> <geom_id>

Standard Geometry 1

General Section 2

Arbitrary Section 10

Auto Shell Tying 11

Box Section 12

Circular Section 13

Closed Section 14

Curved w/Arbitrary Section 15

Curved w/General Section 16

Curved w/Pipe Section 17

General Plastic Section 18

Hexagonal Section 19

I Section 20

Initial Stres