XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''"> 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))
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.
> 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, 163 for the location of this toggle.
User controlled conditional recording
There is also a PCL function to allow the user to control recording of the session file. This function allows the user to prevent the next function call from being recorded, based upon the value of its logical argument. The function is:
sf_write_disable ( donext )
If the value of donext is TRUE, then the next function call to be recorded is executed normally, but is not recorded. For example:
sf_write_disable ( not_completed )
> 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 */
9 sf_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 */
21 string3 = “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”)
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’ */
3 sub1( “FIRST string”, “The 2nd string” )
4 STRING string3[256]
5 sub1( string3, “FIRST string” )
6 sub2( “The 2nd string”, string3 )
7 sub3( “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.
Line 6 is recorded at execution of SFTEST line 18. Note that the second argument is recorded as ‘string3’ rather than the value of ‘string3.’
Line 7 is recorded at execution of line 41 in function sub2. Since sub2 was executed without a > directive, > directives within sub2 are recorded.
Line 8 is recorded at execution of SFTEST line 27.
The following text is the output created by the execution of the PCL function sftest() documented above.
Output from the PCL function to the startup window:
1. SUB1: Arg1:FIRST string - Arg2:The 2nd string
2. SUB1: Arg1:This is string3 - Arg2:FIRST string
3. SUB3: Arg1:The 2nd string - Arg2:This is string 3
4. SUB3: Arg1:The 2nd string - Arg2:String 3 set by sftest
5. SUB1: Arg1:SUB2 set this string! - Arg2:FIRST string
6. /* Recorded only if record rotations is ON
Line 1 is printed from SUB1 when called from SFTEST line 12.
Line 2 is printed from SUB1 when called from SFTEST line 15.
Line 3 is printed from SUB3 when called from SUB2 line 41, which is called from SFTEST line 18.
Line 4 is printed from SUB3 when called from SUB2 line 41, which is called from SFTEST line 22.
Line 5 is printed from SUB1 when called from SFTEST line 26. Note that SUB1 is called, even though it is not recorded.
Line 6 is printed from SFTEST line 31, but the ui_write call is not recorded in the session file, because the default condition is NOT to record rotations, and the sf_rotation() call on line 30 indicates that line 31 is a rotation function.
The PCL Command Line Interpreter P3PCLCOMP
The executable p3pclcomp provides an interface to a PCL interpreter that can be executed from the command line of a UNIX shell or a Windows NT command processor.
The p3pclcomp executable functions exactly as the command line for Patran with two main differences. There is no graphics capability, and there is no access to databases. The runtime paths and libraries for p3pclcomp are also different, but this is simply because at start time, $P3_HOME/init.pcl is read by Patran and not by p3pclcomp.
Commands that are supported by p3pclcomp include:
!!input [all known options]
!!compile [all known options]
!!library [all known options]
!!path [all known options]
and most PCL functions that do not deal with graphics or the database.
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"