Patran 2008 r1 PCL and Customization
Main Index
Corporate
Europe
Asia Pacific
MSC.Software Corporation 2 MacArthur Place Santa Ana, CA 92707 USA Telephone: (800) 345-2078 Fax: (714) 784-4056
MSC.Software GmbH Am Moosfeld 13 81829 Munich, Germany Telephone: (49) (89) 43 19 87 0 Fax: (49) (89) 43 61 71 6
MSC.Software Japan Ltd. Shinjuku First West 8F 23-7 Nishi Shinjuku 1-Chome, Shinjuku-Ku Tokyo 160-0023, JAPAN Telephone: (81) (3)-6911-1200 Fax: (81) (3)-6911-1201
Worldwide Web www.mscsoftware.com
Disclaimer This 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 ©2008 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*2008R1*Z*CUS*Z* DC-USR
Main Index
Contents PCL and Customization
m`i=~åÇ=`ìëíçãáò
1
Introduction to Customization Understanding PCL
2
Steps to Adding a New Functionality to Patran
2
3
The PATRAN Command Language (PCL) Introduction Introduction
6
Basic Concepts 7 Patran and PCL 7 PCL Commands 7 PCL Comments 7 PCL Embedded in NOODL Commands and Databoxes Identifiers 8 Directives 9 PCL Variables and Constants Data Types 10 Scope 12 Arrays 13 Variable Initialization 17 Argument Declaration 18 PCL Operators and Expressions Hierarchy of Operators 19 Control Statements 21 Branching 21 Break and Continue 21 Simple If Then 21 If Then Else 21 Switch and Case 22 Looping 23 For 23 While 23 Repeat 24
Main Index
10
19
8
ii PCL and Customization ==
List
24
PCL Functions 25 Structure of a PCL Class 25 Structure of a PCL Function 26 Accessing PCL Functions 28 Libraries 28 Path Directive 29 The C Preprocessor
31
Finding Programming Errors with PCL Trace Directive 33 Debug Directive 33 Initializing the Session 35 PCL Start-Up File 35 Session Files Support in PCL
3
35
Basic Functions Intrinsic Functions 44 Math Functions 44 String Functions 59 Block I/O Functions 78 File Utility Functions 81 Record I/O Utility Functions 97 Stream I/O File Utility Functions 110 String I/O Conversion Utility Functions Text File I/O Utility Functions 126 Virtual I/O Scratch File Utility Functions Console I/O Functions 144 Message System Functions 155 Event Manager 160 Session File Functions 162 Obsolete File I/O Functions 168 Graphics Functions 174 Graphics Manager 174 Retained Graphics 174
4
System and Utility Functions Spawning a Process
Main Index
33
186
120 136
CONTENTS iii
5
Database Locking
187
System Functions
188
User Interface and List Processor Functions Introduction
220
General Form Style 225 General Forms 225 General Widgets 229 Box Widgets 239 Switch 244 Creating Forms and Widgets Using PCL widget Function Descriptions
246
256
List Processor 258 File lpenums.i 259 Example: Creating a Simple Customized Menu and Form User Interface Functions
6
297
Creating New Analysis Forms Using PCL Introduction
422
Updating Patran Release 1.1 Analysis Forms Naming Convention
424
The Analysis PCL Library
425
Contents=of the Analysis Library The Main=Analysis Form
426
427
Main Analysis Form Functions 429 Changing the Appearance 429
_load_aom_data 432 Subordinate Analysis Forms and Functions The =Class 438 Fetching Data From “analysis_main” 440
Main Index
437
423
293
iv PCL and Customization ==
7
Modifying the Database Using PCL Introduction
446
Querying the Patran Database
447
Loading Definitions for MSC Supported Preferences Loading Definitions for User Defined Preferences Loading Basic Definitions
452
453
454 Adding=A New Analysis Preference Custom Data and Application Region Sub-Forms Adding New Element Types/Properties Adding the New Material Properties
459
468 520
Adding New Loads and Boundary Conditions Adding Custom General Field Functions Adding Functions to the Database 575 Evaluator PCL 577 An Example Case 582
Adding Element Verification Parameters Examples of Modifying the Database
544
574
Adding New Multi-Point Constraint Definitions
8
451
585
591 595
Accessing the Patran Database Introduction
599
Syntax=of Documented Calls
600
Calling the Database Access Functions from C and FORTRAN External Access of the Patran Database Miscellaneous Database Functions Groups
608
Nodes 610 Exporting Node Data Importing Node Data
Main Index
610 615
604
603
601
CONTENTS v
Coordinate Frames 617 Exporting Coordinate Frame Data Importing Coordinate Frame Data Patran Element Topology Codes Elements 623 Exporting Element Data Importing Element Data
617 617 621
623 629
Element Properties 632 Exporting Element Property Data Importing Element Property Data
632 642
Association between Elements and Element Properties 647 Extracting Association between Elements and Element Properties Data Fields 650 Importation of Data Fields
647
660
Material Properties 679 Exportation of Material Data 679 Importation of Material Data 690 Exportation of Composite Material Creation Data Load Cases 699 Exportation of Load Case Definitions
694
699
Loads 708 Evaluation of Loads on Finite Element Entities Exportation of Load Data 708 Importation of Load Data 738 Multi-point Constraints 760 Exportation of Multi-point Constraint Data
708
760
Importing Results 776 Drop Results Indexing 776 Create/Find Loadcases 777 Associate Global Variables 779 Create Result Types 779 Examples of Translation 799 Results Reader 799 Extracting Temperature Dependent and/or Non-Linear Material Data Extracting Transient Load Histories 821 Forward Moldflow Translator 825
Main Index
806
vi PCL and Customization ==
9
PATRAN 2.5 Database Compatibility Introduction
830
PATRAN 2.5 Compatible Database Functions
10
831
Broken, Obsolete, Modified and New Functions Introduction
850
Basic Functions (Chapter 3)
851
System and Utility Functions (Chapter 4)
852
User Interface and List Processor Functions (Chapter 5) Possible parm names: 862 Creating New Analysis Forms Using PCL (Chapter 6) Modifying the Database Using PCL (Chapter 7) Accessing the Patran Database (Chapter 8)
874 881
PATRAN 2.5 Database Compatibility (Chapter 9)
Main Index
887
855 873
Chapter 1: Introduction to Customization PCL and Customization
1
Main Index
Introduction to Customization
Understanding PCL
Steps to Adding a New Functionality to Patran
2 PCL and Customization Understanding PCL
Understanding PCL The 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.
Main Index
Chapter 1: Introduction to Customization 3 Steps to Adding a New Functionality to Patran
Steps to Adding a New Functionality to Patran In 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.
Main Index
4 PCL and Customization Steps to Adding a New Functionality to Patran
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction PCL and Customization
2
Main Index
The PATRAN Command Language (PCL) Introduction
Introduction
Basic Concepts
PCL Variables and Constants
PCL Operators and Expressions
Control Statements
PCL Functions
The C Preprocessor
Finding Programming Errors with PCL
Initializing the Session
The PCL Command Line Interpreter P3PCLCOMP
6 PCL and Customization Introduction
Introduction The 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.
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 7 Basic Concepts
Basic Concepts Patran and PCL PCL 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. Important:Examples in the following sections are excerpts from working PCL functions. By themselves, they are incomplete and will not execute properly.
PCL Commands PCL statements come in many forms. Some examples of PCL statements include: theta = 360.0 - MTH_ASIND( value ) IF ( radius > 20.0 ) THEN radius = 20.0 make_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 = TRUE x = 5; y = 10; z = x * ( y + 5 )
PCL Comments In 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 */
Main Index
8 PCL and Customization Basic Concepts
or a one line comment with: $ This is a comment. # This is a comment too.
PCL Embedded in NOODL Commands and Databoxes A 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‘
Identifiers An 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:
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 9 Basic Concepts
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
Some examples of valid identifiers are: a, b, c, X1, x_2, InnerRadius TryAgain, 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.)
Directives Directives 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:
Main Index
!!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.
10 PCL and Customization PCL Variables and Constants
PCL Variables and Constants PCL 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 Types All 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:
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 11 PCL Variables and Constants
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.)
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
Main Index
12 PCL and Customization PCL Variables and Constants
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 = line = line =
line[40] “ABC” 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”)
Scope Scope 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.
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 13 PCL Variables and Constants
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. Examples: 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_class The string line is defined within all the functions within the class CLASSWIDE STRING line[80] 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 FUNCTION END CLASS
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
Main Index
14 PCL and Customization PCL Variables and Constants
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: 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.
An array constant can be specified by enclosing a set of constant values in square brackets. The following examples will best illustrate the syntax.
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 15 PCL Variables and Constants
[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).
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: my_function( In this example, elements 10 through 30 of the node_list array are passed node_list(10:30) ) to my_function. 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. err = SYS_ALLOCATE_ARRAY (mydata, 1, 1000 ) Or, to allocate a two dimensional array, enter:
Main Index
Allocate a one dimensional array.
16 PCL and Customization PCL Variables and Constants
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)
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.
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 nonzero if the allocation failed. Virtual strings arrays are allowed, but currently a SYS_REALLOCATE_STRING may not be performed on one.
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 17 PCL Variables and Constants
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) To find out the maximum size of any string, use the PCL function STR_MAXLENGTH(string).
Variable Initialization Variables 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. 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. Some example initializations are: REAL STRING INTEGER
Main Index
TABLE(2,3) = [ 10, 20, 30, 11, 21, 31 ] PROMPT[20] = “This is a prompt” I = 0, J = 17
18 PCL and Customization PCL Variables and Constants
Argument Declaration The 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
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 19 PCL Operators and Expressions
PCL Operators and Expressions Hierarchy of Operators PCL 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 .
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
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.
Main Index
20 PCL and Customization PCL Operators and Expressions
.
Table 2-2 Operators **
*
/
Operands +
// <
>
==
!=
<=
>=
= ||
&&
Note:
-
+=
-=
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
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.
Examples: 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”.
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”
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 21 Control Statements
Control Statements Control 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.
Branching PCL 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 Continue The 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 Then The 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 Else The 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:
Main Index
22 PCL and Customization Control Statements
IF( logical_expression ) THEN statements... ELSE IF( logical_expression ) THEN statements ... ELSE statements ... 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.0 do_my_mesh( patch_list, “QUAD”, I,el_length ) ELSE IF ( strain_energy < min_threshold) THEN el_length = 2.0 * el_length do_my_mesh( patch_list, “QUAD”, I,el_length ) ELSE BREAK adapting /* Break out of loop called adapting */ END IF
Switch and Case The 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 ... DEFAULT statements ... 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)
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 23 Control 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:”) DEFAULT WRITE_LINE(“WARNING: ELEMENT CONFIG”, el_config,“UNDEFINED”) END SWITCH
Looping A 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.
For The 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
While The 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.
Main Index
24 PCL and Customization Control Statements
count = 0 WHILE ( TEXT_READ ( fid, “%OF%%6E16.9%”, O, node_dis ( count +1, 1:6)) == 0) count += 1 IF ( count > 10000) THEN WRITE_LINE(“* DISCONTINUED READING FILE AT” // @ “10,000 RECORDS”) BREAK END IF END WHILE
Repeat The 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. REPEAT grid_id = UI_READ_INTEGER( “ INPUT GRID ID ”) UNTIL ( VALID_GID(grid_id) )
List The 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`
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 25 PCL Functions
PCL Functions A 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:
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_
Structure of a PCL Class PCL 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.
Main Index
26 PCL and Customization PCL Functions
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 classname CLASSWIDE 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 Function The 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 commands END 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. Important:Variable names and function names conflict in PCL. PCL uses a flat name space for both. 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
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 27 PCL 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, fid STRING file_name[80] REAL nodes (6) /* Open file containing node displacements*/ IF ( TEXT_OPEN( file_name, “or”, 0, 0, fid) == 0 ) THEN count = 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 ) THEN WRITE_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) = nodes END WHILE /* Close the file */ TEXT_CLOSE(fid, “ ”) ELSE WRITE_LINE(“* CANNOT FIND FILE”, file_name) END IF END 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)
Main Index
28 PCL and Customization PCL Functions
Accessing PCL Functions Once 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.
Libraries A 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
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 29 PCL Functions
!!LIBRARY !!LIBRARY !!LIBRARY !!LIBRARY !!LIBRARY !!LIBRARY !!LIBRARY !!LIBRARY
CREATE file [ max_entries ] MERGE sourcefile destfile SORT file REHASH KEEPOPEN file [ file ....] DELETE file function [ function ...] 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 Directive To 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,
Main Index
30 PCL and Customization PCL Functions
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).
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 31 The C Preprocessor
The C Preprocessor During 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 “inhouse-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
Main Index
32 PCL and Customization The C Preprocessor
-------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
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).
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 33 Finding Programming Errors with PCL
Finding Programming Errors with PCL There 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 Directive The 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 TRACE TRACE TRACE TRACE TRACE TRACE
NONE(disable tracing) CALLS(enable tracing of NOCALLS(disable tracing EXITS(enable tracing of NOEXITS(disable tracing LINES(enable tracing of NOLINES(disable tracing
function calls) of function calls) function exits) of function exits) function statements) of function statements)
!! TRACE CALLS LINES !! TRACE level mask is CALLS NOEXITS LINES . . .
Debug Directive The 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.
Main Index
34 PCL and Customization Finding Programming Errors with PCL
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
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 35 Initializing the Session
Initializing the Session PCL Start-Up File PCL 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 PCL The 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))
Main Index
36 PCL and Customization Initializing the Session
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 PCLF1AND2 REAL arg1to2 PCLF1 (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.
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 37 Initializing the Session
> PCLF1 ($arg1to2, 45.5, 60, “TRUE”) > PCLF2 ($arg1to2)
Note:
Do not start a line with a $ before a variable. Patran recognizes lines that begin with $ as comment lines.
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, 162 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 )
Main Index
38 PCL and Customization Initializing the Session
> 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 sftest 2 STRING string1[256], string2[256], string3[256] 3 4 string1 = “FIRST string” 5 string2 = “The 2nd string” 6 string3 = “This is string 3” 7 8/* Write a line to the session file */ 9sf_write(“/* Written by ‘sf_write’ */”) 10 11/* Next function call records in session file */ 12> sub1 ( string1, string2 ) 13 14/* Record Arg 1 of next func as variable NAME, not VALUE 15> sub1( $string3, string1 ) 16 17/* Record Arg 2 of next func as variable NAME, not VALUE 18> sub2( string2, $string3 ) 19 20/* Demonstrate how nested >’s act */ 21string3 = “String 3 assigned by sftest” 22 sub2 (string2, string3) 23 24 /* 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!”) 28 29/* test record rotation functionality */ 30 sf_rotation() 31> ui_writec(“!Recorded only if record rotations is ON”)
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 39 Initializing the Session
32 END FUNCTION /* sftest */ 33 34 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 */ 38 39 FUNCTION sub2 (e, f) 40 STRING e[256], f[256] 41> sub3 (e, f) 42 f = “SUB2 set this string!” 43 END FUNCTION /* sub2 */ 44 45 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.
Main Index
40 PCL and Customization Initializing the Session
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 !!compile !!library !!path
[all known options] [all known options] [all known options] [all known options]
and most PCL functions that do not deal with graphics or the database.
Main Index
Chapter 2: The PATRAN Command Language (PCL) Introduction 41 Initializing 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"
Main Index
42 PCL and Customization Initializing the Session
Main Index
Chapter 3: Basic Functions PCL and Customization
3
Main Index
Basic Functions
Intrinsic Functions
Graphics Functions
6 130
44 PCL and Customization Intrinsic Functions
Intrinsic Functions PCL 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 Functions PCL 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).
Main Index
Chapter 3: Basic Functions 45 Intrinsic 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
The sine value.
Output: REAL
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
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
The cosine value.
Error Conditions: None.
Main Index
46 PCL and Customization Intrinsic Functions
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.
The angle in degrees for the cosine.
Output: REAL
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
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
The angle in degrees for the tangent.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 47 Intrinsic 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
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
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
Main Index
The angle in radians for the sine.
48 PCL and Customization Intrinsic Functions
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 49 Intrinsic 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.
The cosine value.
Output: REAL
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
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
The tangent value.
Error Conditions: None.
Main Index
50 PCL and Customization Intrinsic Functions
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.
The angle in radians for the tangent.
Output: REAL
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.
The angle in radians for the tangent.
Output: REAL
Error Conditions: None.
mth_sqrt
( value )
Description: Return square root of the argument. Input: REAL Output:
Main Index
value
The value for which to obtain the square root.
Chapter 3: Basic Functions 51 Intrinsic Functions
REAL
Error Conditions: None.
Main Index
The square root.
52 PCL and Customization Intrinsic Functions
mth_ln
( value )
Description: Return natural logarithm of the argument. Input: REAL
value
The value for which to obtain the natural logarithm.
The natural logarithm.
Output: REAL
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.
The common logarithm.
Output: REAL
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
The result of the power of the input argument.
Output: REAL
Main Index
Chapter 3: Basic Functions 53 Intrinsic 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
The absolute value of the input argument. The datatype will match that of the input argument.
Error Conditions: None.
Main Index
54 PCL and Customization Intrinsic Functions
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
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
The nearest integer value, rounding off the input argument.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 55 Intrinsic 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.
The largest value of the input arguments. If all input arguments are INTEGER, then this result is also INTEGER. Otherwise, this result is REAL.
Output: NUMERIC
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.
The smallest value of the input arguments. If all input arguments are INTEGER, then this result is also INTEGER. Otherwise, this result is REAL.
Output: NUMERIC
Error Conditions: None.
mth_mod
( value, divisor )
Description: Return remainder of a number after dividing by a divisor. Input: NUMERIC
Main Index
value
The value to be divided by the divisor.
56 PCL and Customization Intrinsic Functions
NUMERIC
divisor
The divisor value.
Output: NUMERIC
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
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. Example: mth_round( mth_round( mth_round( mth_round(
Main Index
12.34567, 2 12.34567, 0 12.3457, -1 3.3715, 1 )
) yields 12.35 ) yields 12.0 ) yields 10.0 yields 3.4000001
Chapter 3: Basic Functions 57 Intrinsic 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.
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.
Output:
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()
Main Index
Matrix is sorted in place.
58 PCL and Customization Intrinsic Functions
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()
Matrix is sorted in place.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 59 Intrinsic Functions
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
Position in the array from 1 to n or zero if the value was not found in the array.
Error Conditions: None. Example: Some examples of using PCL math functions: max_shear = SQRT( ( eigenroot = n * pi / y = SINR( eigenroot b * SINR( k * t thru_the_thickness =
sigma_x - sigma_y ) / 2.0)**2 + shear**2 ) length * x ) * ( a * COSR( k * t ) + @ )) 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 x RETURN MTH_SIND( x ) END FUNCTION
String Functions The String functions test, convert, and manipulate PCL strings. String functions are useful for user interface applications and parsing.
Main Index
60 PCL and Customization Intrinsic Functions
.
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
The current length of the string. Remember that PCL strings are variable length.
Error Conditions: None. Example: string line[40] line = “ ” str_length( line ) is now 0 line = line // “testing” str_length( line ) is now 7
Main Index
Chapter 3: Basic Functions 61 Intrinsic 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
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
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
Main Index
The input string converted to upper case.
62 PCL and Customization Intrinsic Functions
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 63 Intrinsic 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.
The input string without any leading blanks.
Output: STRING
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
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:
Main Index
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.
64 PCL and Customization Intrinsic Functions
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
The extracted substring of the input string.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 65 Intrinsic 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.
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.
Output: STRING
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
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
Main Index
( string, chars )
66 PCL and Customization Intrinsic Functions
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
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.
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.
Output: INTEGER
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 67 Intrinsic 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
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.
INTEGER
stat
Optional status, zero for success, or the position within the input string which contains the first invalid character.
INTEGER
Integer value from conversion. Usually zero if the conversion fails.
Output:
Error Conditions: None.
str_to_real
( string [, stat] )
Description: Convert a string to a real. Input: STRING
Main Index
string
String to convert to real value.
68 PCL and Customization Intrinsic Functions
Output: INTEGER
stat
Optional status, zero for success, or the position within the input string which contains the first invalid character.
REAL
Real value from conversion. Usually zero if the conversion fails.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 69 Intrinsic Functions
str_to_logical
( string )
Description: Convert a string to a logical. Input: STRING
string
String to convert to logical value.
Output: LOGICAL
Logical value from conversion. This will be TRUE if the first nonblank 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
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
Main Index
String that represents the real value. The string may end up being in decimal or in exponential notation.
70 PCL and Customization Intrinsic Functions
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 71 Intrinsic Functions
str_from_logical ( lval ) Description: Convert a logical to a string. Input: LOGICAL
lval
Logical to convert to string representation.
Output: STRING
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.
String representing datatype. Either “INTEGER,” “REAL,” “LOGICAL,” or “STRING.”
Output: 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:
Main Index
STRING
string
Input string.
STRING
format
C Format string with handling of \n, \r, \t, %d, %f, %e, %g, %x, %s, %c, and %%.
72 PCL and Customization Intrinsic Functions
unknown
args
Appropriate datatype for format specifiers. Incorrect specifications may cause a crash.
Resultant string from processing format.
Output: STRING
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 73 Intrinsic 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
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:
Main Index
74 PCL and Customization Intrinsic Functions
STRING
Error Conditions: None.
Main Index
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.
Chapter 3: Basic Functions 75 Intrinsic 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
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
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
Main Index
ascii
Integer ASCII value to convert to a character.
76 PCL and Customization Intrinsic Functions
Output: STRING
Error Conditions: None.
Main Index
Single character represented by ASCII value.
Chapter 3: Basic Functions 77 Intrinsic 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
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.
count
The number of newline characters in the string.
Output: INTEGER
Error Conditions: None.
string_newline_position
(string, position)
Description : This function returns the newline character ( \n ) positions in a string.
Main Index
78 PCL and Customization Intrinsic Functions
Input: STRING
string[]
This value specifies the string to look for newline characters.
position[]
The newline character positions in the string.
Output: INTEGER
Error Conditions: None.
Block I/O Functions The 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.
Main Index
Chapter 3: Basic Functions 79 Intrinsic Functions
block_open
( filename, options, nwpb, chan, fsize )
Description: Open a binary block oriented proprietary format file for access. Input: STRING
cp10
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.
INTEGER
chan
Channel number to use for subsequent block I/O operations.
INTEGER
fsize
Current file size in bytes if determinable.
INTEGER
Zero for success, else error message code.
Output:
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
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.
Main Index
80 PCL and Customization Intrinsic Functions
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.
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
Zero for success, else error message code.
Output:
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 81 Intrinsic Functions
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
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.
STRING
fspec
File specification of open file.
INTEGER
lenfspec
Length of name returned in FSPEC.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
File Utility Functions The 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.
Main Index
82 PCL and Customization Intrinsic Functions
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. 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).
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)
Main Index
Chapter 3: Basic Functions 83 Intrinsic 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
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.
fspec
Modified file specification.
Output: STRING
Error Conditions: None.
file_build_fname ( dir, base, ext, options, filespec ) Description: Create a full file specification given its component parts. Input: STRING
Main Index
dir
Directory portion of file specification.
84 PCL and Customization Intrinsic Functions
STRING
base
Base filename portion.
STRING
ext
Extension for filename.
STRING
options
Options of N, O, P, or V. See File Utility Functions, 81.
filespec
Resultant file specification.
Output: STRING
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
Zero for success. If the directory already exists, the call is considered successful.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 85 Intrinsic 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.
Zero for success, else error message code.
Output: INTEGER
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
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.
True for execute permission, False if no execute permission.
Output: LOGICAL
Error Conditions:
Main Index
86 PCL and Customization Intrinsic Functions
None. Side Effects: Warning.
Main Index
If the operating system can’t determine execute permission, this function will normally return True.
Chapter 3: Basic Functions 87 Intrinsic 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
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.
TRUE if file exists. FALSE if file could not be found.
Output: LOGICAL
Error Conditions: None.
file_exists_version
( filespec, version, nzeros )
Description: Find the highest version of a file in the current directory. Input: STRING Output:
Main Index
filespec
File to look up without version specified.
88 PCL and Customization Intrinsic Functions
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
TRUE if file exists. FALSE if file could not be found.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 89 Intrinsic Functions
file_expand_home
( inspec, outspec )
Description: Expand any “~” home directory syntax in the file specification. Input: STRING
inspec
Input file specification.
outspec
File specification with expanded home syntax.
Output: STRING
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.
basename
Base filename.
Output: STRING
Error Conditions: None.
file_get_dfname
( filespec, directory )
Description: Extract the directory specification given a file specification. Input: STRING
filespec
Input file specification.
directory
Directory specification.
Output: STRING
Error Conditions: None.
Main Index
90 PCL and Customization Intrinsic Functions
file_get_efname
( filespec, extension )
Description: Extract the extension specification given a file specification (without versions). Input: STRING
filespec
Input file specification.
STRING
extension
Extension specification.
INTEGER
Zero for success, else error message code.
Output:
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.
STRING
outspec
Output file specification.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
file_get_next_path
( ipath, path )
Description: Iteratively retrieve entries from the path list. Input:
Main Index
Chapter 3: Basic Functions 91 Intrinsic Functions
INTEGER
ipath
Set to zero on first call. Pass return result back in on subsequent calls.
STRING
path
Next entry from the path list. The current directory path is returned as an empty string.
INTEGER
Minus one if no more paths left. Otherwise use this value for the next call to file_get_next_path.
Output:
Error Conditions: None.
Main Index
92 PCL and Customization Intrinsic Functions
file_get_p3_home
( path )
Description: Return directory path for Patran “home” directory. Input: None. Output: STRING
path
Path to Patran “home” directory.
INTEGER
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.
Status, zero for success, else error code.
Output: INTEGER
Main Index
Chapter 3: Basic Functions 93 Intrinsic Functions
Error Conditions: None. Example: INTEGER status, chan STRING fname [256] status = file_list_start ( “/tmp”, “patran.ses.*”, chan ) IF ( status == 0 ) THEN WHILE ( file_list_next ( chan, fname ) == 0 ) xf_write_comment ( fname ) END WHILE file_list_end ( chan ) END IF
Main Index
94 PCL and Customization Intrinsic Functions
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..
STRING
fname
The next file in the indicated directory that matches the specified filter.
INTEGER
Status, zero for success, -1 for end of list, else error code.
Output:
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.
INTEGER
chan
Return value to use on subsequent calls to file_list_next and file_list_end.
INTEGER
Status, zero for success, else error code.
Output:
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
Main Index
( filespec )
Chapter 3: Basic Functions 95 Intrinsic Functions
Description: Check if read access is possible to a file. Input: STRING
filespec
File to check for read access.
TRUE if reading is possible, otherwise FALSE.
Output: LOGICAL
Error Conditions: None.
Main Index
96 PCL and Customization Intrinsic Functions
file_writeable
( filespec )
Description: Check if write access is possible to a file. Input: STRING
filespec
File to check for write access.
Output: LOGICAL
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.
STRING
outspec
Output file specification.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
file_copy
( source, dest )
Description: Copy an operating system file. Input:
Main Index
STRING
source
Name of existing source file.
STRING
dest
Name of new destination file which must not exist.
Chapter 3: Basic Functions 97 Intrinsic Functions
Output: INTEGER
Zero for success, else error message code.
Error Conditions: None.
file_query_remote ( cp10 ) Description: Determine whether or not a file resides on a remote file system. Input: STRING
cp10
File to check.
Output: INTEGER
Zero for file is remote, otherwise message code for file local or does not exist.
Error Conditions: None.
Record I/O Utility Functions The 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
Main Index
98 PCL and Customization Intrinsic Functions
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.
Main Index
Chapter 3: Basic Functions 99 Intrinsic Functions
record_open_new
( filename, options, filecode, description, chan )
Description: Create and open a new record I/O file. Input: STRING
cp10
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.
INTEGER
chan
Value to use for subsequent operations to this file.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
record_open_old
( filename, options, chan, filecode, description )
Description: Open an existing record I/O file. Input: STRING
cp10
Name of file to open.
STRING
options
Open options of R, W, P, or V. See File Utility Functions, 81.
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
Zero for success, else error message code.
Output:
Error Conditions: None.
Main Index
100 PCL and Customization Intrinsic Functions
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
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.
STRING
fspec
Filename of open record I/O file.
INTEGER
lenfspec
Length of the file specification.
INTEGER
Zero for success, else error message code.
Output:
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:
Main Index
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.
Chapter 3: Basic Functions 101 Intrinsic Functions
Output: INTEGER
Error Conditions: None.
Main Index
Zero for success, else error message code.
102 PCL and Customization Intrinsic Functions
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.
Zero for success, else error message code.
Output: INTEGER
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
record_writerec_reals ( chan, typecode, count, buffer )
Main Index
Chapter 3: Basic Functions 103 Intrinsic 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
Zero for success, else error message code.
Error Conditions: None.
Main Index
104 PCL and Customization Intrinsic Functions
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.
Zero for success, else error message code.
Output: INTEGER
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.
INTEGER
typecode
Typecode for the record. Will be -1 for the end of the file.
INTEGER
Zero for success, else error message code.
Output:
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 Output:
Main Index
chan
Channel from the record I/O open routine.
Chapter 3: Basic Functions 105 Intrinsic Functions
INTEGER
Error Conditions: None.
Main Index
Zero for success, else error message code.
106 PCL and Customization Intrinsic Functions
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.
Zero for success, else error message code.
Output: INTEGER
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.
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
Zero for success, else error message code.
Output:
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 107 Intrinsic Functions
record_write_ints
( chan, numitems, i_buffer )
record_write_reals
( chan, numitems, r_buffer )
record_write_chars record_write_halfints record_write_int8bits record_write_int4bits record_write_intbits
( chan, numitems, c_buffer ) ( chan, numitems, h_buffer ) ( chan, numitems, i8_buffer ) ( chan, numitems, i4_buffer ) ( 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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
Main Index
108 PCL and Customization Intrinsic Functions
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.
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
Zero for success, else error message code.
Output:
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 109 Intrinsic 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.
INTEGER
position
Pointer value in internal format.
INTEGER
Zero for success, else error message code.
Output:
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
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 Output:
Main Index
chan
Channel from the record I/O open routine.
110 PCL and Customization Intrinsic Functions
STRING
cdatetime
Creation date of file in format: yyyymmddhhmmss.
STRING
mdatetime
Modify date of file in format: yyyymmddhhmmss.
INTEGER
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
Zero for success, else error message code.
Error Conditions: None.
Stream I/O File Utility Functions The 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.
Main Index
Chapter 3: Basic Functions 111 Intrinsic Functions
stream_open
( filename, options, chan )
Description : Create or open a new or existing stream I/O file. Input: STRING
cp10
Name of file to open/create.
STRING
options
Open options of N, O, R, W, P, or V. See File Utility Functions, 81.
INTEGER
chan
Channel number to use for subsequent stream I/O operations on this file.
INTEGER
Zero for success, else error message code.
Output:
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
stream_get_name ( chan, fspec, lenfspec ) Description: Get the name of a file that is open for stream I/O.
Main Index
112 PCL and Customization Intrinsic Functions
Input: INTEGER
chan
Channel from a previous call to stream_open.
STRING
fspec
Name of the file.
INTEGER
lenfspec
Length of the file specification returned.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 113 Intrinsic 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.
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.
Output:
INTEGER(5) recordinfo
Application use data words.
INTEGER
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
stream_get_position
Main Index
( chan, position )
114 PCL and Customization Intrinsic Functions
Description: Get the current position in the stream I/O file. Input: INTEGER
chan
Channel from a previous call to stream_open.
INTEGER
position
Position returned in internal format.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 115 Intrinsic 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.
Zero for success, else error message code.
Output: INTEGER
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.
INTEGER()
buffer
Integer data read in by the call.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
stream_read_real
( chan, numtoread, buffer )
Description: Read reals from the stream I/O file. Input: INTEGER
Main Index
chan
Channel from a previous call to stream_open.
116 PCL and Customization Intrinsic Functions
INTEGER
numtoread
Number of reals to read.
REAL()
buffer
Real data read in by the call.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 117 Intrinsic 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.
STRING
buffer
Character data read from stream I/O file.
INTEGER
Zero for success, else error message code.
Output:
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
stream_write_real ( chan, numtowrite, buffer ) Description: Write reals to the stream I/O file. Input:
Main Index
INTEGER
chan
Channel from a previous call to stream_open.
INTEGER
numtowrite
Number of reals to write out.
118 PCL and Customization Intrinsic Functions
REAL()
buffer
Data to write out to the file.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 119 Intrinsic 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
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
stream_skip_real ( chan, numtoskip ) Description: Skip over reals in the stream I/O file. Input:
Main Index
INTEGER
chan
Channel from a previous call to stream_open.
INTEGER
numtoskip
Number of reals to skip.
120 PCL and Customization Intrinsic Functions
Output: INTEGER
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
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
String I/O Conversion Utility Functions The 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
Main Index
Chapter 3: Basic Functions 121 Intrinsic 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).
Main Index
%%
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.
122 PCL and Customization Intrinsic Functions
Main Index
%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.
Chapter 3: Basic Functions 123 Intrinsic Functions
%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.
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.
Main Index
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.
124 PCL and Customization Intrinsic Functions
%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.
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.
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.
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
Zero for success, else error message code.
Output:
Main Index
Chapter 3: Basic Functions 125 Intrinsic Functions
Error Conditions: None. 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” 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 Strings, 121 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.
STRING
string
Character string which receives converted data.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None. Example:
Main Index
126 PCL and Customization Intrinsic Functions
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, 2 REAL 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 Functions The 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.
Main Index
Chapter 3: Basic Functions 127 Intrinsic Functions
text_open
( filespec, options, lrecl, maxrecs, chan )
Descriptio n: 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.
INTEGER
chan
Channel value to use for subsequent text I/O operations.
INTEGER
Zero for success, else error message code.
Output:
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
text_flush
Main Index
( chan )
128 PCL and Customization Intrinsic Functions
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 129 Intrinsic 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.
STRING
fspec
File specification associated with text I/O file.
INTEGER
lenfspec
Length of string returned in fspec.
INTEGER
Zero for success, else error message code.
Output:
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).
STRING
line
Line read in from the text file.
INTEGER
lenline
Length of the line that was read in.
INTEGER
Zero for success, minus one for end of file, else error message code.
Output:
Error Conditions: None.
text_write_string
( chan, line )
Description: Write a single record from a string to a text I/O file. Input:
Main Index
130 PCL and Customization Intrinsic Functions
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
Zero for success, else error message code.
Error Conditions: None. See Input Format Strings, 123 for more information.
Main Index
Chapter 3: Basic Functions 131 Intrinsic 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.
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
Zero for success, minus one if end of file, else error message code.
Output:
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
Main Index
Zero for success, else error message code.
132 PCL and Customization Intrinsic Functions
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 133 Intrinsic 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.
INTEGER
position
Internal representation of the current position in the text I/O file.
INTEGER
Zero for success, else error message code.
Output:
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
text_truncate
Main Index
( chan )
134 PCL and Customization Intrinsic Functions
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 135 Intrinsic 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.
INTEGER
bytesize
Size of the file in bytes.
INTEGER
Zero for success, else error message code.
Output:
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.
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.
Output: LOGICAL
Main Index
136 PCL and Customization Intrinsic Functions
Error Conditions: None.
Virtual I/O Scratch File Utility Functions The 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.
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
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.
Zero for success, else error message code.
Output: INTEGER
Main Index
Chapter 3: Basic Functions 137 Intrinsic 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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
Main Index
138 PCL and Customization Intrinsic Functions
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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 139 Intrinsic 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
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.
INTEGER()
buffer
Area to read integers into.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
virtual_read_real ( chan, numtoread, buffer ) Description: Read real data from a virtual file. Input:
Main Index
140 PCL and Customization Intrinsic Functions
INTEGER
chan
Channel number returned by a previous call to virtual_open_scratch.
INTEGER
numtoread
Number of reals to read into the buffer.
REAL()
buffer
Area to read reals into.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 141 Intrinsic 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.
STRING
buffer
Area to read characters into.
INTEGER
Zero for success, else error message code.
Output:
Error Conditions: None.
virtual_skip_int
( chan, numtoskip )
Descriptio n: 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.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
virtual_skip_real
( chan, numtoskip )
Description: Skip over real data in a virtual file.
Main Index
142 PCL and Customization Intrinsic Functions
Input: INTEGER
chan
Channel number returned by a previous call to virtual_open_scratch.
INTEGER
numtoskip
Number of reals to skip over.
Zero for success, else error message code.
Output: INTEGER
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 143 Intrinsic 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
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.
INTEGER
position
Internal position to use in a later call to virtual_set_position.
INTEGER
Zero for success, else error message code.
Output:
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
Main Index
chan
Channel number returned by a previous call to virtual_open_scratch.
144 PCL and Customization Intrinsic Functions
INTEGER
position
Zero to set position to the beginning of the file or a position previously returned by virtual_get_position.
Output: INTEGER
Zero for success, else error message code.
Error Conditions: None.
Console I/O Functions The console I/O functions are used to display messages to the terminal window, history window, and session file.
Main Index
Chapter 3: Basic Functions 145 Intrinsic 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.
Main Index
146 PCL and Customization Intrinsic Functions
xf_write_comment
( mess )
Description: Write a comment to the history window/session file. Input: STRING
mess
Output: None. Error Conditions: None.
Main Index
Comment to write out.
Chapter 3: Basic Functions 147 Intrinsic 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
Output: None. Error Conditions: None.
Main Index
Message to write out.
148 PCL and Customization Intrinsic Functions
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
INTEGER
Zero for success, else error message code.
Error Conditions: None.
Main Index
Line entered by the user.
Chapter 3: Basic Functions 149 Intrinsic 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
Zero for success, minus one for end of file, else error message code.
Error Conditions: None.
write
Main Index
( expr, ... )
150 PCL and Customization Intrinsic Functions
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
True if YES button, False otherwise.
Error Conditions: None. Example: ok = ui_read_logical( “Do you want to continue?” )
Main Index
Chapter 3: Basic Functions 151 Intrinsic Functions
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.
Integer value that user entered or zero if aborted.
Output: INTEGER
Error Conditions: abort
Value returned is zero even if outside of range specified.
Example: option = ui_read_integer( “1. Decrease, 2. Increase, 3. Quit”, 1, 3 )
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
Value entered by user or zero for abort.
Error Conditions: abort
Value returned is zero even if outside of range specified.
Example: scale = ui_read_real( “Enter a scale factor for the operation” )
Main Index
152 PCL and Customization Intrinsic Functions
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.
return
Value entered by user.
Output: STRING
Error Conditions: None. Example: username = ui_read_string( “What is your name?” )
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”.
return
Value entered by user.
Output: STRING
Error Conditions: None. Example:
Main Index
Chapter 3: Basic Functions 153 Intrinsic Functions
/* Supply YES answer to next message no matter what it is */ui_answer_message( -1, “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.
return
Value entered by user.
Output: STRING
Error Conditions: None. Example: /* Supply YES answer always to the message: * Do you wish to delete the original patches? */ ui_override_message( 1000030, “YES” )
Main Index
154 PCL and Customization Intrinsic Functions
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.
Main Index
Chapter 3: Basic Functions 155 Intrinsic Functions
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.
Message System Functions The 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.
Main Index
156 PCL and Customization Intrinsic Functions
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 <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> 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.
Main Index
Chapter 3: Basic Functions 157 Intrinsic Functions
USER_MESSA GE
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.
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 Important:It is expected that all constants actually be define symbols that will be resolved by the C preprocessor. 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.
Main Index
158 PCL and Customization Intrinsic Functions
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
( msgtype, appcode, appname, message )
Description: Display a message in either a user interface form or in the history window. Input: STRING
msgtype
Message severity type. See the table above for legal values.
INTEGER
appcode
Application message code. The value should be unique to insure session file compatibility.
STRING
appname
Name of the applications generating the message.
STRING
message
Message text to display.
Output: INTEGER
Size of the message in the message file.
Error Conditions: None.
msg_get_string
( msgcode, string )
Description: Retrieve a message string from the message file. Input: INTEGER
msgtype
Message code.
STRING
string
String retrieved from message file.
INTEGER
Length of retrieved message string.
Output:
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 159 Intrinsic Functions
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
Message return code (MSG_STAT_YES, ...).
Error Conditions: None.
Main Index
160 PCL and Customization Intrinsic Functions
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
Should normally be 2.
Error Conditions: None.
Event Manager The “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.
Main Index
Chapter 3: Basic Functions 161 Intrinsic Functions
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.
Main Index
162 PCL and Customization Intrinsic Functions
Input: None. Output: None. Error Conditions: None.
Session File Functions The following set of routines support session file recording and playback.
Main Index
Chapter 3: Basic Functions 163 Intrinsic Functions
.
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 .ses.. 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
cp10
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 .<extension>. 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
cp10
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.
Main Index
164 PCL and Customization Intrinsic Functions
Input: STRING
cp10
Output: None. Error Conditions: None.
Main Index
Name of session file to play.
Chapter 3: Basic Functions 165 Intrinsic Functions
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 Output: None.
Main Index
write_sys_msg
Write system messages to the session file
166 PCL and Customization Intrinsic Functions
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 167 Intrinsic Functions
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 Output: None.
Main Index
string
String to write to the recording session file.
168 PCL and Customization Intrinsic Functions
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. Example: sf_rotation() > gm_rot_x(value)
Obsolete File I/O Functions The 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.
Main Index
Chapter 3: Basic Functions 169 Intrinsic Functions
fio_openr
( filename, channel )
Description: Open a text file for read only. Input: STRING
cp10
File to open.
INTEGER
channel
Channel value to use for subsequent operations.
Output: INTEGER
Zero for success, otherwise error status.
Error Conditions: None.
fio_openw
( filename, channel, overwrite )
Description: Open a text file for write access. Input: STRING
cp10
File to open.
FALSE
overwrite
Do not overwrite file if exists.
TRUE INTEGER
Overwrite file if exists. channel
Channel value to use for subsequent operations.
Output: INTEGER
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:
Main Index
STRING
cp10
File to open.
INTEGER
channel
Channel value to use for subsequent operations.
170 PCL and Customization Intrinsic Functions
Output: INTEGER
Zero for success, otherwise error status.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 171 Intrinsic Functions
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
Zero for success, otherwise error status.
Error Conditions: None.
fio_delete
( filename )
Description: Delete a file from the operating system. Input: STRING
cp10
File to delete.
Output: INTEGER
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
Zero for success, otherwise error status.
Error Conditions: None.
Main Index
172 PCL and Customization Intrinsic Functions
fio_read
( channel, string )
Description: Read a string from a file. Input: INTEGER
channel
Channel value from the FIO_OPENx routine.
STRING
string
String read from the file. Must be at least two characters larger than the line being read.
INTEGER
Zero for success, otherwise error status.
Output:
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
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:
Main Index
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 %%.
Chapter 3: Basic Functions 173 Intrinsic Functions
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.
Zero for success, otherwise error status.
Output: INTEGER
Error Conditions: None.
Main Index
174 PCL and Customization Graphics Functions
Graphics Functions Graphics Manager PatranPatran 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 Graphics The 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, 177.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, 175 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, color color = 1 corner1(1) = 0.0 corner1(2) = 0.0 corner1(3) = 0.0 corner2(1) = 5.0 corner2(2) = 0.0 corner2(3) = 0.0 corner3(1) = 5.0 corner3(2) = 5.0 corner3(3) = 0.0 corner4(1) = 0.0 corner4(2) = 5.0 corner4(3) = 0.0 /* * Create segment. Segment ID is returned from graphics manager.
Main Index
Chapter 3: Basic Functions 175 Graphics Functions
*/ 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):
Main Index
176 PCL and Customization Graphics 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
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.
Status of operation. 0 = Successful.
Output: INTEGER
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
Status of operation. 0 = Successful.
Error Conditions: None.
Main Index
Chapter 3: Basic Functions 177 Graphics Functions
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):
Main Index
178 PCL and Customization Graphics 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
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.
Status of operation. 0 = Successful.
Output: INTEGER
Error Conditions: None.
gm_draw_marker
( segment_id, color_id, location, type, size )
Description: Draw a marker in a segment or current viewport.
Main Index
Chapter 3: Basic Functions 179 Graphics Functions
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
Status of operation. 0 = Successful.
Error Conditions: None.
Main Index
180 PCL and Customization Graphics 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: Tip: Middle:
0--------> -------->0 -----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:
Main Index
INTEGER
segment_id
Segment ID created from gm_segment_create.
INTEGER
color_id
Color of arrow (0-15).
Chapter 3: Basic Functions 181 Graphics Functions
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
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.
Viewport Routines
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
dev_pt
real (3)
xyz device coordinate
INTEGER
Status of operation. 0 = Successful.
Output:
Error Conditions: 15000025 Note:
Main Index
Error in finding the viewport in the graphics manager display list 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.
182 PCL and Customization Graphics 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
Error Conditions: None.
Main Index
Center of the model.
Chapter 3: Basic Functions 183 Graphics Functions
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.
Main Index
184 PCL and Customization Graphics Functions
Main Index
Chapter 4: System and Utility Functions PCL and Customization
4
Main Index
System and Utility Functions
Spawning a Process
Database Locking
System Functions
186 PCL and Customization Spawning a Process
Spawning a Process Application developers may have the need to execute other programs in order to perform certain operations. Programs that execute other programs are said to be “spawning a process.” 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 count integer status string 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 ) ) THEN utl_display_error( status, 2) ENDIF END 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:
Main Index
For portability reasons, all scripts should be written for the bourne shell.
Chapter 4: System and Utility Functions 187 Database Locking
Database Locking Having 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 . . .
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 ) ) THEN utl_display_error( status, 2) ENDIF END FUNCTION /* start_mytrans */
Using the previous example, this will execute the following command: lockfile my.db mytranslator -db my.db -cnt 542
Main Index
188 PCL and Customization System Functions
System Functions System functions have varied functions and can be useful for getting system information or accessing special operations in the PCL environment 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 Output:
source
The source variable to move information from.
ANY destination Error Conditions:
The destination variable to which to copy the source variable.
None. Example: REAL value = 3.14159 INTEGER bits sys_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_product
()
Description: Return a string representing the name of the product/application being executed. Input: None. Output: STRING Error Conditions: None. sys_release
Description:
Main Index
()
Product name, such as “Patran”.
Chapter 4: System and Utility Functions 189 System Functions
Return a string representing the release/version of the product/application being executed. Input: None. Output: STRING Error Conditions:
Release/Version string.
None. sys_date
()
Description: Return a string with the current date in dd-mm-yy format. Input: None. Output: STRING Error Conditions:
String representing date such as “25-Feb-92.”
None. sys_time
()
Description: Return a string with the current time in hh:mm:ss format. Input:
None. Output:
STRING
String representing time such as “12:52:22.”
Error Conditions:
None. sys_clock
Main Index
()
190 PCL and Customization System Functions
Description: Return the current time in seconds since midnight. Input: None. Output: REAL
Error Conditions: None.
Main Index
Current time in seconds since midnight expressed as a REAL.
Chapter 4: System and Utility Functions 191 System Functions
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
CPU time in seconds from unknown base.
Error Conditions: None.
sys_allocate_arr ay
(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.
ANY(VIRTUAL)
array
Virtual array with storage allocated if available.
INTEGER
Zero for success, else error code.
Output:
Error Conditions: None.
Main Index
192 PCL and Customization System Functions
sys_reall (array, lb1, hb1 [, lb2, hb2 [, lb3, hb3 [, lb4, hb4 ]]] ) ocate_arr ay 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
Zero for success, else error code.
Error Conditions: None. 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
Main Index
Chapter 4: System and Utility Functions 193 System Functions
INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER
column_count test_array(VIRTUAL) row_size column_size return_value 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(" ")
Main Index
194 PCL and Customization System Functions
column_size = 5 row_size = 5 return_value = sys_free_array ( test_array ) 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
Main Index
Chapter 4: System and Utility Functions 195 System Functions
sys_fre ( array ) e_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.
ANY(VIRTUAL)
array
Virtual array now deallocated
INTEGER
Zero for success, else error code.
Output:
Error Conditions: None.
sys_alloc ( string, size ) ate_strin g 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.
STRING
string
Virtual string with storage allocated if available.
INTEGER
Zero for success, else error code.
Output:
Error Conditions: None.
sys_rea ( string, size ) llocate_ string
Main Index
196 PCL and Customization System Functions
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.
INTEGER
size
New maximum size for the virtual string variable.
STRING
string
Virtual string with storage allocated if available.
INTEGER
Zero for success, else error code.
Output:
Error Conditions: None.
sys_fr ( string ) ee_stri ng Description: Free memory for a PCL virtual array variable. This function is more completely described in Virtual Arrays, 15.
Input: STRING
string
Virtual string.
STRING
string
Virtual string now deallocated.
INTEGER
Zero for success, else error code.
Output:
Error Conditions: None.
sys ( array, dim ) _arr ay_ hbo und
Main Index
Chapter 4: System and Utility Functions 197 System Functions
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
Upper bound of specified dimension of specified array.
Error Conditions: None.
Main Index
198 PCL and Customization System Functions
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
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
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]
STRING
variable_name[32 This value specifies the name of the variable which will ] have its value retrieved.
Output:
Main Index
This value specifies the name of the PCL function class from which the variable value will be retrieved.
Chapter 4: System and Utility Functions 199 System Functions
DYNAMIC_ILRS W
This function returns the value from the specified variable which is a member of the specified class.
Error Conditions: None. Remarks: This function assumes that the caller already knows the data type of the variable whose contents will be returned. Example: None.
Main Index
200 PCL and Customization System Functions
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.
STRING
tablename
Name of a system hash table.
LOGICAL
True if hash table found, FALSE otherwise.
Output:
Error Conditions: None.
sys_eval
(pcl_expression)
Description: This function will execute a PCL expression contained in a string.
Main Index
Chapter 4: System and Utility Functions 201 System 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.
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.
Output: DYNAMIC_ILRS
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
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.
Main Index
202 PCL and Customization System Functions
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
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
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 Output:
Main Index
string
String to write to the session file.
Chapter 4: System and Utility Functions 203 System Functions
None. Error Conditions: None.
Main Index
204 PCL and Customization System Functions
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.
Main Index
Chapter 4: System and Utility Functions 205 System 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
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
Previous value of the options.
Error Conditions: None.
sys_traceback
()
Description:; Output a PCL error call traceback. Input: None. Output: None.
Main Index
206 PCL and Customization System Functions
Error Conditions: None.
Main Index
Chapter 4: System and Utility Functions 207 System 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
True if input queued successfully.
Error Conditions: None.
sys_s ( ) top_in put 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:
Main Index
208 PCL and Customization System Functions
STRING
operation
String with operation keyword of either “”, “ADD”, “CREATE”, “DELETE”, “KEEPOPEN”, “LIST”, “MERGE”, “NONE”, “REHASH”, “REMOVE”, or “SORT”.
STRING
args
Filename(s) or function name(s) depending on operation specified.
Output: None. Error Conditions: None.
Main Index
Chapter 4: System and Utility Functions 209 System 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.
STRING
result
String result of environment definition if environment variable is defined.
INTEGER
Zero for success, else error code if environment variable is not defined.
Output:
Error Conditions: None.
sys_get ( enoval, result ) _errno_ msg Description: Translate a system “errno” value to a string. Input: INTEGER
Main Index
enoval
System “errno” value.
210 PCL and Customization System Functions
Output: STRING
result
Error Conditions: None.
Main Index
String with message for specified errno.
Chapter 4: System and Utility Functions 211 System 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.
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
Zero for success, else error.
Output:
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_inf o
( custnumber, custname )
Description: Get customer information. Input:
Main Index
STRING
custnumber
Customer number string.
STRING
custname
Customer name string.
212 PCL and Customization System Functions
Output: INTEGER
Status, 0=success.
Error Conditions: None.
Main Index
Chapter 4: System and Utility Functions 213 System Functions
utl_get_ ( host ) host_na me 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_u ( user ) ser_nam e Description: Retrieve name of operating system user. Input:
None.
Main Index
214 PCL and Customization System Functions
Output: STRING
user
LOGICAL
True for successful retrieval.
Error Conditions:
None.
Main Index
User name.
Chapter 4: System and Utility Functions 215 System 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
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.
Main Index
216 PCL and Customization System Functions
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.
Main Index
Chapter 4: System and Utility Functions 217 System Functions
utl_pro ( pid ) cess_w ait 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
Status code that can be checked with utl_process_error.
Error Conditions: None.
utl_display ( errcode, severity ) _process_ error 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_proce ss_error Description:
Main Index
( errcode )
218 PCL and Customization System Functions
Check status of utl_process_spawn or utl_process_wait. Input: INTEGER
errcode
Status from utl_process_spawn or utl_process_wait.
Output: LOGICAL Error Conditions:
TRUE if error occurred, FALSE otherwise.
None.
utl_process_kill
( pid )
Description: To kill a spawned subprocess and all child processes created on its behalf. Input: INTEGER
pid
Output: None. Error Conditions: None.
Main Index
PID returned from UTL_PROCESS_SPAWN
Chapter 5: User Interface and List Processor Functions PCL and Customization
5
Main Index
User Interface and List Processor Functions
Introduction
General Form Style
Creating Forms and Widgets Using PCL
widget Function Descriptions
List Processor
User Interface Functions
2 8
49 101
47
35
220 PCL and Customization Introduction
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 init widget definitions END FUNCTION hheader display ui_form_display(classname) END FUNCTION hheader refresh db_get_item(...) ui_wid_get(...) ui_wid_set(...) END FUNCTION functions (see Structure of a PCL Function, 26 END 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
Main Index
Chapter 5: User Interface and List Processor Functions 221 Introduction
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:
Main Index
222 PCL and Customization Introduction
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.
Main Index
Chapter 5: User Interface and List Processor Functions 223 Introduction
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
Main Index
224 PCL and Customization Introduction
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.
Main Index
Chapter 5: User Interface and List Processor Functions 225 General Form Style
General Form Style Define 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 Forms If 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.
Main Index
226 PCL and Customization General Form Style
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
Main Index
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_QTR S
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.
Chapter 5: User Interface and List Processor Functions 227 General 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
Main Index
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.
228 PCL and Customization General Form Style
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). 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.
Main Index
Chapter 5: User Interface and List Processor Functions 229 General 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: REAL
y_loc =
y_loc
y_loc + INTER_WIDGET_SPACE
General Widgets There are general widgets such as
Main Index
230 PCL and Customization General Form Style
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.
Select Frame 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:
Main Index
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.
Chapter 5: User Interface and List Processor Functions 231 General 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_LABOV E
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_INC R
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
Main Index
Distance between select frame and left side of select databox.
232 PCL and Customization General Form Style
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. 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.
Main Index
Chapter 5: User Interface and List Processor Functions 233 General Form Style
Label l
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.
Example 1: Create a Label Widget Use the following command to create a label widget without a frame. label = ui_label_create( /* parent /* callback /* x /* y /* label
*/ parent_form, */ EMPTY_STR, */ UNFRAMED_MARGIN, */ y_loc, */ “label_text”
/* Calculate the y location for the next widget */ y_loc = y_loc + LABEL_HGT + INTER_WIDGET_SPACE
Main Index
@ @ @ @ @ )
234 PCL and Customization General Form Style
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.
Main Index
Chapter 5: User Interface and List Processor Functions 235 General Form Style
• 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.
The following variables have been provided to help size and place buttons: Button Width: BUTTON_WID_FULL
Main Index
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.
236 PCL and Customization General Form Style
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.
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_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:
Main Index
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.
Chapter 5: User Interface and List Processor Functions 237 General 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:
Main Index
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.
238 PCL and Customization General Form Style
Example 1: Center a Button on a Form ui_button_create( /* parent /* callback /* x /* y /* width /* height /* label /* labelinside /* highlight
*/ “parent”, */ "callback", */ BUTTON_SIZE_X_LOC_CEN, */ y_loc, */ BUTTON_WID_SIZE, */ 0.0, */ “button_label” */ TRUE, */ 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 @
Main Index
Chapter 5: User Interface and List Processor Functions 239 General 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 Widgets There are box type widgets such as:
Main Index
240 PCL and Customization General Form Style
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.
DataBox 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:
Main Index
DBOX_HGT_LABOVE
The height of one databox with a label above.
DBOX_HGT_NO_LABOVE
The height of one databox without a label.
Chapter 5: User Interface and List Processor Functions 241 General Form Style
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.
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
Main Index
242 PCL and Customization General Form Style
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 Frame The 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:
Main Index
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.*
Chapter 5: User Interface and List Processor Functions 243 General Form Style
*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.
The width of the select databox next to the label is calculated as follows: wid = where
SDBOX_WID_SIZE @ SDBOX_LABEL_LEN_SIZE @ SDBOX_LABEL_X_OFFSET 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_LABOVE ui_selectframe_create (/* parent */ parent_form, /* callback */ “callback”,
Main Index
@ @
244 PCL and Customization General Form Style
/* 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 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.
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
Main Index
Chapter 5: User Interface and List Processor Functions 245 General 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. 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.
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. additional_row
Main Index
= SWITCH_4R_HGT_LABEL - SWITCH_3R_HGT_LABEL
246 PCL and Customization Creating Forms and Widgets Using PCL
Creating Forms and Widgets Using PCL As 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.
Main Index
Chapter 5: User Interface and List Processor Functions 247 Creating 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”.
Main Index
248 PCL and Customization Creating Forms and Widgets Using PCL
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
Main Index
Chapter 5: User Interface and List Processor Functions 249 Creating 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:
Main Index
250 PCL and Customization Creating Forms and Widgets Using PCL
* 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
Main Index
Chapter 5: User Interface and List Processor Functions 251 Creating 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.
Main Index
252 PCL and Customization Creating Forms and Widgets Using PCL
*/ 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”, @
Main Index
Chapter 5: User Interface and List Processor Functions 253 Creating 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: * * * Output: * * * 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. *
Main Index
254 PCL and Customization Creating Forms and Widgets Using PCL
* Input: * boolean string[] Item selected from icon switch * onoff string[] not used. * * Output: * * * */ 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: * * * Output: * * * */ 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()
Main Index
Chapter 5: User Interface and List Processor Functions 255 Creating 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: * * * Output: * * * */ 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
Main Index
256 PCL and Customization widget Function Descriptions
widget Function Descriptions Widgets 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
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[ ]
Complete pathname of file.
string[ ]
“OPEN” or “CANCEL”
form
Does not register events.
frame
Does not register events.
graph
Does not register events.
item
Does not register events.
itemicon
Does not register events.
label
Does not register events.
labelicon
Does not register events.
listbox
menu
integer
The number of selected items.
string[ ]()
Label of the selected items in the listbox.
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 select databox
select frame
Main Index
Description of Callback Data
Does not register events. string[ ]
“GAIN”, “LOSE”, “CR” or “WIDSET” (if appropriate ui_wid_set call has been made), depending on which event initiated the callback. No arguments are passed.
Chapter 5: User Interface and List Processor Functions 257 widget Function Descriptions
Table 5-1 Widget Type
Data Type
separator slide bar
spread sheet
switch
Description of Callback Data Does not register events.
real
Current value of the slide bar.
string[ ]
“VALUE_CHANGED” or “DRAG”
string[ ]
“SELECTED”. To be expanded.
integer
Starting selected column.
integer
Starting selected row.
integer
Ending selected column.
integer
Ending selected row.
integer
Selected layer.
string[ ]
Name of the switch item changed.
string[ ]
“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
Widget ID of the color bar.
integer
User data specified in the widget creation call. Selected item.
integer color menu
widget
Widget ID of the color bar.
integer
User data specified in the widget creation call. New color value.
integer
Main Index
258 PCL and Customization List Processor
List Processor A 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:8 solid 3.2 element 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.
Main Index
Chapter 5: User Interface and List Processor Functions 259 List Processor
File lpenums.i The 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. Note:
Some evaluation methods are for internal use only. /* 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 #define LP_SUBLIST_VECTOR_IMMEDIATE #define LP_SUBLIST_POINT #define LP_SUBLIST_CURVE #define LP_SUBLIST_SURFACE #define LP_SUBLIST_SOLID #define LP_SUBLIST_GEOMETRY (LP_SUBLIST_POINT_IMMEDIATE LP_SUBLIST_VECTOR_IMMEDIATE LP_SUBLIST_POINT
Main Index
+ + +
1 2 4 8 16 32 \ \ \
260 PCL and Customization List Processor
#define #define #define #define #define #define #define #define #define #define #define #define #define #define
#define
LP_SUBLIST_CURVE LP_SUBLIST_SURFACE LP_SUBLIST_SOLID) LP_SUBLIST_COORD_FRAME LP_SUBLIST_VECTOR LP_SUBLIST_AXIS LP_SUBLIST_NODE LP_SUBLIST_ELEMENT LP_SUBLIST_MPC LP_SUBLIST_FINITE_ELEMENT (LP_SUBLIST_NODE LP_SUBLIST_ELEMENT LP_SUBLIST_MPC) LP_SUBLIST_TOKEN_NULL LP_SUBLIST_TOKEN_INT LP_SUBLIST_TOKEN_FLOAT LP_SUBLIST_TOKEN_STRING LP_SUBLIST_TOKEN_FIELD LP_SUBLIST_TOKEN_MATERIAL 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) LP_SUBLIST_ANY
+ +
\ \
64 128 256 512 1024 2048 + \ + \ 4096 8192 16384 32768 65536 131072 + \ + \ + \ + \ + \
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
Main Index
Chapter 5: User Interface and List Processor Functions 261 List Processor
#define #define #define #define #define
LP_ATTRIBUTE_POINT_LIST33 LP_ATTRIBUTE_CURVE_LIST34 LP_ATTRIBUTE_SURFACE_LIST35 LP_ATTRIBUTE_SOLID_LIST36 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
Main Index
262 PCL and Customization List Processor
List Processor Functions
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
INTEGER
handle
Used by other lp utilities to parse the Picklist.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error
Output:
Error Conditions: None. 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
Main Index
Chapter 5: User Interface and List Processor Functions 263 List Processor
List Processor Functions
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
This function returns a value of 0 when executed successfully.
Error Conditions: None. 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.
Main Index
264 PCL and Customization List Processor
List Processor Functions
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.
INTEGER
type
Actual sublist type. See lpenums.i, sublist types.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output:
Error Conditions: None. Example: #include “lpenums.i” INTEGER handle1,ent_type, count INTEGER 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 ) )THEN RETURN status END IF . . .
Main Index
Chapter 5: User Interface and List Processor Functions 265 List Processor
List Processor Functions
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.
INTEGER
count
Number of items in sublist.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output:
Error Conditions: None. 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)
Main Index
266 PCL and Customization List Processor
List Processor Functions
lp_sublist_next
(handle )
Description: Set the list position to the next sublist. Input: INTEGER
handle
Returned by call to lp_eval().
Output: INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions: None. 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 0 END FUNCTION
Main Index
Chapter 5: User Interface and List Processor Functions 267 List Processor
List Processor Functions
lp_eval_cleanup (handle ) Description: Free allocated memory for list processor operations. Input: INTEGER
handle
Returned by call to lp_eval().
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output: INTEGER Error Conditions: None. Note:
Must be called after all calls to parse a particular picklist.
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
Main Index
268 PCL and Customization List Processor
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
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions: None. List Processor Functions
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.
REAL
item
Item parsed from Picklist of the specified attribute.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output:
Error Conditions: None. Example: #include “lpenums.p” . . . status = lp_eval(list_str, LP_EVAL_FOR_TOKENS, handle) IF (status != 0) THEN
Main Index
Chapter 5: User Interface and List Processor Functions 269 List 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 BREAK END FOR END IF
List Processor Functions
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
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions: None. Example: #include “lpenums.p” . .
Main Index
270 PCL and Customization List Processor
. 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
Main Index
Chapter 5: User Interface and List Processor Functions 271 List Processor
List Processor Functions
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
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions: None. 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)
Main Index
272 PCL and Customization List Processor
List Processor Functions
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
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions: None. 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 IF END IF
Main Index
Chapter 5: User Interface and List Processor Functions 273 List Processor
List Processor Functions
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().
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output: INTEGER Error Conditions: None. 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
Main Index
274 PCL and Customization List Processor
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().
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output: INTEGER Error Conditions: None. List Processor Functions
lp_sublist_reset
(handle )
Description: Reset the sublist parser to resume parsing the original Picklist. Input: INTEGER
handle
Returned by call to lp_eval().
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output: INTEGER Error Conditions: None. 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) THEN lp_eval_cleanup(handle1) RETURN 48000006 END IF SYS_ALLOCATE_ARRAY(eids,1,nbrae) FOR (iall = 1 to 4) ialloop
Main Index
Chapter 5: User Interface and List Processor Functions 275 List 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 IF FOR (i = 1 To lid) Doloop . . . END FOR END FOR
Main Index
276 PCL and Customization List Processor
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”.
STRING
item
Contents of sublist.
INTEGER
size
Actual size returned.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output:
Error Conditions: None. List Processor Functions
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:
Main Index
Chapter 5: User Interface and List Processor Functions 277 List 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
Main Index
278 PCL and Customization List Processor
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
Message facility code. See Message System Functions, 155. 0 indicates no error.
Error Conditions: None. Example: #include “lpenums.p” . . . /*$$ FUNCTION refresh * * Purpose: * Update the Reference Coordinate Frame if the preference has been * changed. *
Main Index
Chapter 5: User Interface and List Processor Functions 279 List 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 */
Main Index
280 PCL and Customization List Processor
List Processor Functions
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.
STRING
[VIRTUAL] vstr
PCL virtual string to receive character list.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output:
Error Conditions: None. 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.
Main Index
Chapter 5: User Interface and List Processor Functions 281 List 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
Main Index
282 PCL and Customization List Processor
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.
INTEGER
status
Message facility code. See Message System Functions, 155. 0 indicates no error.
INTEGER
Number of entities in the picklist of the specified type.
Output:
Error Conditions: None. List Processor Functions
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.
INTEGER
status
Message facility code. See Message System Functions, 155. 0 indicates no error.
INTEGER
Number of tokens in the picklist.
Output:
Error Conditions: None.
app_get_handle
(lst, method, domesg, handle )
Description: Open a list for processing.
Main Index
Chapter 5: User Interface and List Processor Functions 283 List 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.
INTEGER
handle
List pointer.
INTEGER
Number of tokens in the picklist.
Output:
Error Conditions: None.
Main Index
284 PCL and Customization List Processor
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.
LOGICAL
eol
Returned as TRUE when end of file encountered.
INTEGER
status
Message facility error.
INTEGER
ID of next item in Picklist.
Output:
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.
LOGICAL
eol
Returned as TRUE when end of file encountered.
INTEGER
status
Message facility error.
INTEGER
Label of next item in Picklist.
Output:
Main Index
Chapter 5: User Interface and List Processor Functions 285 List Processor
Error Conditions: None. List Processor Functions
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. 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]”
Main Index
286 PCL and Customization List Processor
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.
INTEGER
status
Message facility code. See Message System Functions, 155. 0 indicates no error.
INTEGER
Number of entities in the picklist of the specified type.
Output:
Error Conditions: None. Note:
Main Index
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.
Chapter 5: User Interface and List Processor Functions 287 List Processor
Example: #include “lpenums.i” STRING ent_list[] INTEGER status INTEGER lid lid = fem_u_count_id_list(LP_SUBLIST_ELEMENT,ent_list,FALSE,status) IF ( status != 0 ) THEN RETURN status END IF IF (lid == 0) THEN RETURN 48000004 END IF
List Processor Functions
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.
INTEGER(num_nodes)
id_nodes
Array of node IDs.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output:
Error Conditions: None. 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)
Main Index
288 PCL and Customization List Processor
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
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.
INTEGER
face_el_ids()
Associated element ID.
INTEGER
face_ids()
Free face ID.
INTEGER
free_faces
Number of free faces.
INTEGER
0, no error. 1, Unsupported element type (shape/nodes). 2, Memory allocation error.
Output:
Error Conditions: None. Example: */ INTEGER elem_topo_codes(VIRTUAL) INTEGER shape_code(VIRTUAL)
Main Index
Chapter 5: User Interface and List Processor Functions 289 List Processor
INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER
nodes_per_elem(VIRTUAL) connectivity(VIRTUAL) face_elem_ids(VIRTUAL) keep_face_elem_ids(VIRTUAL) free_elements(VIRTUAL) face_ids(VIRTUAL) elem_ids(VIRTUAL) status cntr1 num_elems num_free_faces 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 0 END FUNCTION
Main Index
290 PCL and Customization List Processor
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.
INTEGER(nument)
ids
Array of entity ids.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output:
Error Conditions: None.
Main Index
Chapter 5: User Interface and List Processor Functions 291 List Processor
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.
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)
Main Index
292 PCL and Customization List Processor
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.
INTEGER(nument)
ids
Array of entity ids.
INTEGER(nument)
fids
Face ids of the entities.
INTEGER(nument)
edids
Edge ids of the entities.
INTEGER
Message facility code. See Message System Functions, 155. 0 indicates no error.
Output:
Error Conditions: None.
Main Index
Chapter 5: User Interface and List Processor Functions 293 List Processor
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.
Example: Creating a Simple Customized Menu and Form Many 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 */ !! INPUT your_custom.pcl
Patran.
/* * 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”)
Main Index
294 PCL and Customization List Processor
/* * 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
Main Index
Chapter 5: User Interface and List Processor Functions 295 List 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:
Main Index
296 PCL and Customization List Processor
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.
Main Index
Chapter 5: User Interface and List Processor Functions 297 User Interface Functions
User Interface Functions BUTTON Functions
ui_button_create
(parent, callback, x, y, width, height, label, [unused], highlight)
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.
Main Index
298 PCL and Customization User Interface Functions
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.
Button widget ID. NULL if button not created.
Output: widget
Error Conditions: None. BUTTON Functions
ui_buttonicon_create
(parent, callback, x, y, icon)
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.
Main Index
Chapter 5: User Interface and List Processor Functions 299 User Interface Functions
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.
Button widget ID. NULL if button not created.
Output: widget
Error Conditions: None. CASCADE Item Functions
ui_cascadeitem_create
(parent, name, label)
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.)
Main Index
300 PCL and Customization User Interface Functions
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 ““.