XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''"> 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:
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 concatenating the pieces together. A character string has both a maximum length and a current length. The current length of a character string can be anywhere from zero up to its maximum length.
Examples:
name = “I”
multiplier = “23*A”
option = “A CHARACTER STRING WHICH SPANS LINES SHOULD DO SO “// @
“BY SPLITTING IT INTO SMALLER PIECES AND “// @
“CONCATENATING THE PIECES TOGETHER.”
PCL strings are variable length up to the maximum size that they are declared. Therefore, the series of statements:
STRING line[40]
line = “ABC”
line = line // “ ”
line = line // “DEF”
produces the variable line defined as “ABC DEF” with no trailing blanks. This is quite different than the way FORTRAN strings work.
Widgets
A widget variable is defined by prefixing the variable name with the keyword WIDGET and is used only for working with the user interface routines. A widget can be assigned from a user interface function or other widget or can be compared against another widget.
Example:
WIDGET myform, mybutton
The only widget constant defined is WIDGET_NULL. If a user interface routine fails to operate sucessfully, the widget value returned will normally be WIDGET_NULL. To initialize widget variables, initialize them to WIDGET_NULL.
Examples:
IF ( myform == WIDGET_NULL ) THEN WRITE (“Form not initialized”)
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.
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
CLASSWIDE STRING line[80] | The string line is defined within all the functions within the class my_class. |
FUNCTION MY_FUNCTION (arg_list)
STATIC INTEGER entries | The value established for entries in MY_FUNCTION remains the same between function calls. |
LOCAL REAL x,y,z . | These variables are only defined within my_function. |
REAL arg_list () | Since arg_list is an argument to the function, its scope is inherited from the calling function. |
GLOBAL LOGICAL flag . | Even though flag is defined GLOBAL outside the function, within each function definition it needs to be declared the same way. All references to flag affect the same global value. |
END 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 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.
[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( node_list(10:30) ) | In this example, elements 10 through 30 of the node_list array are passed 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 ) | Allocate a one dimensional array. |
Or, to allocate a two dimensional array, enter:
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 non-zero if the allocation failed. Virtual strings arrays are allowed, but currently a SYS_REALLOCATE_STRING may not be performed on one.
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 TABLE(2,3) = [ 10, 20, 30, 11, 21, 31 ]
STRING PROMPT[20] = “This is a prompt”
INTEGER I = 0, J = 17
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
