XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''"> 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.
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 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_name OS level name of file containing
* formatted records
* SIDE EFFECTS:
* GLOBAL node_disp Node 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)
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
!!LIBRARY
!!LIBRARY CREATE file [ max_entries ]
!!LIBRARY MERGE sourcefile destfile
!!LIBRARY SORT file
!!LIBRARY REHASH
!!LIBRARY KEEPOPEN file [ file ....]
!!LIBRARY DELETE file function [ function ...]
!!LIBRARY LIST file [ function ... ]
Where file is the operating system name of a library to include in future searches. LIBRARY ADD directives are cumulative. Each one adds an additional library for which to search. The libraries are searched in the reverse order from when specified. The REMOVE option removes a library from the search. The NONE option clears the library search list. A null library command displays the current library search list.
The CREATE option creates a new library which can contain up to the number of functions specified by max_entries, or if max_entries is zero, a “growable” library is created. (If max_entries is not specified it defaults to 256.)
The MERGE option allows the entries to be merged or added from one library into another library. This operation can also be used to compress a library by creating a new library, merging the old library into the new library, and then replacing the original library with the new library.
The SORT option allows the entries in the library to be sorted alphabetically to obtain a nicer listing.
The REHASH option is rarely used but, it can recognize that the contents of the libraries in the library list may have been changed by another user or process and causes Patran to rebuild its optimization tables for all libraries.
The KEEPOPEN option can be used for any library that is already in the library list and attempts to increase performance of accessing frequently used PCL libraries by keeping the operating system library file open all the time.
The DELETE option is used to delete functions from a library. The LIST option lists the contents of a library providing date and size for each function.
To access the library, my_library, issue the directive:
!!LIBRARY my_library
The functions NX and DISP_READ may now be used at any time during the session. To eliminate the need for compiling functions each time they are used, try creating and saving libraries. Use the start-up files to issue the LIBRARY directive.
The sys_library (option, data) function also allows access to the library functions and can be compiled into PCL functions or used within IF statements in PCL start-up scripts. Generally, the “option” is a string containing the operation such as “ADD” and the “data” is a string with the file or function names.
Path 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, 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).