PCL and Customization > Creating New Analysis Forms Using PCL > Main Analysis Form Functions
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">   
Main Analysis Form Functions
Changing the Appearance
It is not always necessary to use “ui_wid_set” to modify the main Analysis form. The following function allows the user to automatically hide many items on the main Analysis form.
 
analysis_main.set_display_flags
(<job_frame_display>, <button_frame_display>, <separator_display>, <apply_button_display>)
 
Input:
 
 
None.
 
 
Output:
 
 
LOGICAL
<job_frame_display>
A flag specifying whether the job name / job description frame should be displayed (TRUE) or not (FALSE).
LOGICAL
<button_frame_display>
A flag specifying whether the button frame should be displayed (TRUE) or not (FALSE).
LOGICAL
<separator_display>
A flag specifying whether the separator widget should be displayed (TRUE) or not (FALSE).
LOGICAL
<apply_button_display>
A flag specifying whether the Apply button should be displayed (TRUE) or not (FALSE).
Error Conditions:
 
None.
 
 
 
Note:  
For the same reasons mentioned above, this call should be made every time an action-object change occurs.
Changing the Behavior
The following calls allow the user to modify certain aspects of the way the main Analysis form works. Since the main Analysis form is refreshed every time an action-object change occurs, these calls must be repeated every time the action-object selection is changed.
Normally, the “analysis_main” class will commit all changes to the database (using “db_commit”) whenever the main Analysis form’s Apply button is selected. To prevent this from happening, the user can call the function described below.
 
analysis_main.dont_commit_on_apply
()
 
Input:
 
 
None.
 
 
Output:
 
 
LOGICAL
<job_frame_display>
A flag specifying whether the job name / job description frame should be displayed (TRUE) or not (FALSE).
LOGICAL
<button_frame_display>
A flag specifying whether the button frame should be displayed (TRUE) or not (FALSE).
LOGICAL
<separator_display>
A flag specifying whether the separator widget should be displayed (TRUE) or not (FALSE).
LOGICAL
<apply_button_display>
A flag specifying whether the Apply button should be displayed (TRUE) or not (FALSE).
Error Conditions:
 
None.
 
 
Also, after the Apply button is selected, the “analysis_main” class automatically updates the job name databox and list box. To prevent this from happening, the user can call “dont_update_on_apply”. This call is especially needed if the user’s application closes the Patran database without re-opening it.
 
analysis_main.dont_update_on_apply
()
If the user wishes to make the job name and job description databoxes un-editable, so that the user can only specify job names via the job name list box, then he should make the following call. This is useful whenever the action-object selection requires choosing an already existing job. An example of such an action-object combination would be “Delete” - “Job”. 
 
analysis_main.disable_jobname_and_description
()
To set the job name and job description databoxes to blank, use the function described below.
 
analysis_main.set_jobname_blank
()
To load the job name databox with a new job name, use the “load_job_name_dbox” function.
    
analysis_main.load_job_name_dbox
()
Input:
 
 
STRING
<job_name>
The name of the job to be loaded in the job name databox.
Output:
 
 
None.
 
 
Error Conditions:
 
None.
 
 
The function described below will place the name of the “current” job into the job name databox. The “current” job is defined as the last job created or as the name of the Patran database (with the .db suffix removed) if no jobs exist. 
 
analysis_main.set_jobname_current
()
The user can force the job name listbox to be refreshed with the following function. 
 
analysis_main.refresh_jobname_listbox
()
<analysis_code>_load_aom_data
This PCL class dictates the appearance and some of the behavior of the main Analysis form. It specifies the number of action-object-method combinations are valid, what the names for these options are, the number of buttons which exist for each action-object combination and which PCL classes will be activated by these buttons. This class must exist within the Analysis library and must contain as many functions as there are analysis types for the current analysis code. The names of these functions are derived from the names of the analysis types in the manner described in the previous Naming Convention section. For example, if an analysis code has two valid analysis types, “Structural” and “Thermal”, then the two necessary functions would be “structural” and “thermal”. The argument list for each of these functions is as follows.
 
<analysis_type>
( <num_actions>, <action_labels>, <num_objects>, <object_labels>, <num_methods>, <method_labels>, <num_buttons>, <button_labels>, <button_callbacks>, <apply_class>, <callback_diagnostics>)
 
Input:
 
 
None.
 
 
Output:
 
 
INTEGER
<num_actions>
The number of actions valid for this analysis code / analysis type combination. The maximum number of actions allowed is 20.
STRING ARRAY
<action_labels>
An array of <num_actions> strings containing the names of all the actions.
INTEGER ARRAY
<num_objects>
A <num_actions> array containing the number of objects for each action. There must be at least one object per every action, but the name of this object can be blank. The maximum number of objects allowed per any action is 20.
STRING ARRAY
<object_labels>
A <num_actions>*max( <num_objects> ) array containing all the names of the objects per the chosen action.
INTEGER ARRAY
<num_methods>
A <num_actions>*max( <num_objects> ) array containing the number of methods valid for every action-object combination. Methods are optional. The maximum number of methods allowed for any action-object combination is 20.
STRING ARRAY
<method_labels>
A <num_actions>*max( <num_objects> ) *max(<num_methods> ) array containing the names of all the methods per action and object.
INTEGER ARRAY
<num_buttons>
A <num_actions>*max( <num_objects> ) array containing the number of buttons for every action-object combination. Buttons are optional. The maximum number of buttons allowed for a action-object combination is 10, but only 5 or 6 buttons can Be placed on the main Analysis form at a given time before the form becomes too large for the computer screen.
STRING ARRAY
<button_labels>
A <num_actions>*max( <num_objects> )*max( <num_buttons> ) array containing all the button labels per action and object.
STRING ARRAY
<button_callbacks>
A <num_actions>*max( <num_objects> )*max (<num_buttons> ) array containing the names of the PCL classes to be activated when the button is selected. Button callbacks are optional; they may be blank.
STRING
<apply_class>
The name of the PCL class which contains the “apply” function activated by the Apply button on the main Analysis form. This class is optional; it may be blank.
LOGICAL
<callback_diagnostics>
A flag specifying if all Analysis function calls made by the “analysis_main” class should be echoed to the command line (TRUE) or not (FALSE). Set this flag to TRUE during development in order to debug or just to get a better understanding of the interactions between the main Analysis form and the Analysis functions.
Error Conditions:
 
None.
 
 
 
Note:  
1. As seen is the example below, the size of argument arrays or strings should not be explicitly stated in the <analysis_type> function so that compatibility is maintained with the “analysis_main” class regardless of the dimensions used in “analysis_main”. In other words, declare the argument <object_labels> listed above as “STRING object_labels[]()” instead of “STRING object_labels[31](20,20)”.
2. All string arguments listed in the above call have a maximum of 31 characters.
The <analysis_code>_load_aom_data classes for MSC supplied analysis interfaces are not modifiable by the user. For user defined analysis interfaces, it is the user’s responsibility to create this required class and place it into the Analysis library.
Below is an example of an <analysis_code>_load_aom_data function for analysis code “John Code”, analysis type “Structural”. This example is delivered to all users, it is called johncode_loud_aom_data.pcl and resides in the $P3_HOME/customization directory. The steps needed to create a “John Code” Analysis library are as follows:
1. Start Patran.
2. Type the following command into the command line: “COMPILE ($P3_HOME)/customization/johncode_load_aom_data.pcl INTO johncode.plb”.
The brackets around $P3_HOME signify that you must type in the evaluation of “$P3_HOME,” such as “/patran/patran3,” instead of typing in “$P3_HOME.” PCL does not directly support UNIX environmental variables.
/* $Header: /madrid/users9/pflib/pcl/custom/RCS/johncode_load_aom_data.pcl,v 1.1 92/12/11 20:55:13 sprack Exp Locker: sprack $ */
 
/*$$h  */
 /* 
  *  Purpose:
  *     Define the option menu selections, button labels, and 
  *     button pcl classes for John Code.
  */
 
  CLASS johncode_load_aom_data
 
 /*---------------------------------------------------------------------
*$$ FUNCTION structural
  *
  *  Purpose:
  *     Load the option menu data for "John Code-Structural".
  */
 
     FUNCTION structural( num_actions, action_items,                         @
                          num_objects, object_items,                         @
                          num_methods, method_items,                         @
                          num_buttons, button_labels,                        @
                          button_callbacks, preference_class,                @
                          callback_diagnostics )
    /*
     *  Local declarations:
     */
        INTEGER  num_actions
        STRING   action_items[]()
        INTEGER  num_objects()
        STRING   object_items[]()
        INTEGER  num_methods()
        STRING   method_items[]()
        INTEGER  num_buttons()
        STRING   button_labels[]()
        STRING   button_callbacks[]()
        STRING   preference_class[]
        LOGICAL  callback_diagnostics
*$$ FUNCTION structural
  *
  *  Purpose:
  *     Load the option menu data for "John Code-Structural".
  */
 
     FUNCTION structural( num_actions, action_items,                         @
                          num_objects, object_items,                         @
                          num_methods, method_items,                         @
                          num_buttons, button_labels,                        @
                          button_callbacks, preference_class,                @
                          callback_diagnostics )
    /*
     *  Local declarations:
     */
        INTEGER  num_actions
        STRING   action_items[]()
        INTEGER  num_objects()
        STRING   object_items[]()
        INTEGER  num_methods()
        STRING   method_items[]()
        INTEGER  num_buttons()
        STRING   button_labels[]()
        STRING   button_callbacks[]()
        STRING   preference_class[]
        LOGICAL  callback_diagnostics
/*
     *  Define the Actions, Objects and Methods.  Note that at least
     *  one actions must exist and for every action, one object
     *  must exist.  Methods are optional.
     */
        num_actions = 3
        action_items(1) = ~Analyze”
        action_items(2) = "Read Results File"
        action_items(3) = "Read Input File"
 
        num_objects(1) = 2
        num_objects(2) = 1
        num_objects(3) = 1
 
        object_items(1,1) = "Entire Model"
        object_items(1,2) = "Current Group"
        object_items(2,1) = "Results Entities"
        object_items(3,1) = "Model Data"
 
        num_methods(1,1) = 3
        num_methods(1,2) = 3
        num_methods(2,1) = 1
        num_methods(3,1) = 1
 
method_items(1,1,1) = "Full Run"
        method_items(1,1,2) = "Check Run"
        method_items(1,1,3) = "Input File Only"
        method_items(1,2,1) = "Full Run"
        method_items(1,2,2) = "Check Run"
        method_items(1,2,3) = "Input File Only"
        method_items(2,1,1) = "Translate"
        method_items(3,1,1) = "Translate"
/*
     *  Define the number of buttons for each action-object
     *  combinations.  Then define the button labels and 
     *  callbacks.
     */
        num_buttons(1,1) = 3
        num_buttons(1,2) = 3
        num_buttons(2,1) = 2
        num_buttons(3,1) = 2
        button_labels(1,1,1) = "Button One"
        button_labels(1,1,2) = "Button Two"
        button_labels(1,1,3) = "Button Three"
        button_labels(1,2,1) = "Button One"
        button_labels(1,2,2) = "Button Two"
        button_labels(1,2,3) = "Button Three"
        button_labels(2,1,1) = "Button One"
        button_labels(2,1,2) = "Button Two"
        button_labels(3,1,1) = "Button One"
        button_labels(3,1,2) = "Button Two"
        button_callbacks(1,1,1) = " "
        button_callbacks(1,1,2) = " "
        button_callbacks(1,1,3) = " "
        button_callbacks(1,2,1) = " "
        button_callbacks(1,2,2) = " "
        button_callbacks(1,2,3) = " "
        button_callbacks(2,1,1) = " "
        button_callbacks(2,1,2) = " "
        button_callbacks(3,1,1) = " "
        button_callbacks(3,1,2) = " "
/*
     *  Define the class for general button functions, such as
     *  the "apply" function.
     */
        preference_class = " "
 
        callback_diagnostics = FALSE
 
     END FUNCTION /* structural */
 
  END CLASS /* johncode_load_aom_data */
Subordinate Analysis Forms and Functions
Below we see a subordinate Analysis form which is activated by selecting the “Solution Type” button on the main Analysis form and whose function is to allow the user to choose a solution type.
As described above, buttons on the main Analysis form are associated with PCL classes via the <analysis_code>_load_aom_data PCL class. Once a button on the main Analysis form is selected, the “display” function of the associated class is called. If a subordinate Analysis form is open when the action-object selection on the main Analysis form is modified or the main Analysis form is closed, the “exit” function of that form’s associated class is called.
When a subordinate Analysis form is closed by anyone other than the main Analysis form, such as by the Cancel button on the subordinate form, the following call should be made.
 
analysis_main.button_class_closed
( <associated_class>)
 
Input:
 
 
STRING
<associated_class>
The name of the class whose form is being closed.
Output:
 
 
None.
 
 
Error Conditions:
 
None.
 
 
This call keeps the “analysis_main” class aware of which subordinate forms are open and which are closed so that when re-entering a given action-object combination “analysis_main” will know which forms were left open, and should thus be re-displayed, and which forms were closed.
There are other optional calls to the “analysis_main” class which will allow the subordinate functions and forms to gather data from the main Analysis form or in some way alter the behavior of the main Analysis form. These functions are described in the “analysis_main” section.
For more details about creating PCL forms, refer to The PATRAN Command Language (PCL) Introduction. For more details about PCL and PCL functions, refer to User Interface and List Processor Functions.
The <apply_class> Class
The name of this class is defined in the PCL function <analysis_code>_load_aom_data.<analysis_type>. The purpose of this class is to capture events from the main Analysis form. None of the functions listed in this section are mandatory. In fact, the <apply_class> reference in the PCL function <analysis_code>_load_aom_data.<analysis_type> can be left blank.
The most important event to be captured is the main Analysis form’s Apply button being selected. When this happens, the “apply” function of <apply_class> is called. Typically this “apply” function will activate the PCL functions of the user application which will either directly perform the task at hand or spawn an external program to perform this task.
Another event which is trapped is the choosing of a job name from the job name list box. Once a job name has been selected from the list box, but prior to its being placed into the job name databox, the “jobname_about_to_change” function of <apply_class> is called. Once the newly selected job name is placed into the job name databox, the “jobname_was_selected” function is called.
When the main Analysis form is opened for the first time after a Patran database is opened, the “database_was_just_opened” function of <apply_class> is called.
When the current analysis code or analysis type is changed, the “preference_was_just_changed” function of <apply_class> is called. This function is not called when a Patran database with a different analysis code preference from the previous database is opened. It is only called when the analysis preference is changed after a database has been opened.
When the action-object-method selection on the main Analysis form is changed, the “option_menu_changed” function of <apply_class> is called. After the action-object-method change is completed, the “option_menu_change_is_done” function is called. If the action-object combination changed (versus only a change in the method), then two more functions are called: “hide_user_defined_widgets” and “display_user_defined_widgets.” These last two functions allow the user control over subordinate Analysis forms which are not directly affected by events on the main Analysis form will be automatically “exit”ed and re-displayed when an action-object change occurs. Other Analysis forms need to be exited and redisplayed explicitly by the user. This is most conveniently done in “hide_user_defined_widgets” and “display_user_defined_widgets.” Closing and opening of the main Analysis form and a change in analysis preference are also considered to be action-object-method changes. So, whenever any of these three events occur the four functions described in this paragraph will be called.
Similar to the specialized “display” and “exit” calls of a PCL class, all the <apply_class> functions described in this section have no arguments.
The <apply_class> of any MSC supplied analysis interface is not modifiable. For user defined analysis interfaces, it is the user’s responsibility to create the <apply_class>, if one is referenced by the <analysis_code>_load_aom_data. <analysis_type> function, and to place this class in the Analysis library.
The “analysis main” Class
The “analysis_main” is the PCL class which controls the main Analysis form. It is contained in the “p3patran.plb” library and is generic, meaning that its behavior does not change according to analysis preference. This class is not modifiable by the user.
Here is a list of main tasks performed by “analysis_main”.
1. It calls the <analysis_code>_load_aom_data.<analysis_type> function to determine the appearance of the main Analysis form.
2. When a button on the main Analysis form is selected, “analysis_main” calls the “display” function of the associated PCL class.
3. When the action-object combination on the main Analysis form is changed or the main Analysis form is closed, “analysis_main” calls the “exit” function of any class associated with an open subordinate Analysis form.
4. The “analysis_main” keeps tract of which subordinate Analysis forms were left open and which were closed for each action-object combination so that when re-entering an action-object combination, the forms which were left open can be automatically re-displayed.
5. The “analysis_main” reports any main Analysis form event to the <apply_class> as described in the previous section.
In addition to the main tasks mentioned above, there are many “analysis_main” functions which can be called from the <apply_class> or from other subordinate Analysis forms or functions which either control the appearance or behavior of the main Analysis form or extract data from the main Analysis form. Node of these function calls are mandatory, but they can greatly enhance the power of your user defined analysis interface. These optional functions are described below.
Fetching Data From “analysis_main”
To get the names of the currently selected action, object and method, use the following function.
 
analysis_main.get_analysis_menu_items
(<item_orders>, <item_labels>)
 
Input:
 
 
None.
 
 
Output:
 
 
INTEGER ARRAY
<item_orders>
A 3 element vector containing the order of the current action in the list of valid actions, the order of the current object in the list of objects valid for the chosen action, and the order of the current method in the list of methods valid for the chosen action-object selection. As an example, let us look at the case where the valid objects under “Import” are “Model,” “Results” and “Both” and there are no methods. If the object-method selection is “Import” - “Both” “ “, the <items> would be [2,3,0].
STRING ARRAY
<item_labels>
A 3 element vector of strings containing the names of the currently chosen action-object-method. In the above example, <item_labels> would be [“Import,” “Both,” “ “]. The maximum length of each string is 31 characters.
Error Conditions:
 
None.
 
 
To get the name and description of the currently selected job, the function described below should be used.
 
analysis_main.get_job_name_and_desc
(<job_name>, <job_description>)
 
Input:
 
 
None.
 
 
Output:
 
 
STRING
<job_name>
The name of the currently selected job. The maximum length of this string is 31 characters.
STRING
<job_description>
The description of the currently selected job. The maximum length of this string is 256 characters.
Error Conditions:
 
None.
 
 
In order to get more detailed information about the current job, use “analysis_main.get_current_job_info”
 
analysis_main.get_current_job_info
(<job_name>, <job_description>, <job_id>, <parameter_set_id>, <job_status>)
 
Input:
 
 
None.
 
 
Output:
 
 
STRING
<job_name>
The name of the currently selected job. The maximum length of this string is 31 characters.
STRING
<job_description>
The description of the currently selected job. The maximum length of this string is 256 characters.
INTEGER
<job_id>
The ID of the current job.
INTEGER
<parameter_set_id>
The ID of the parameter set associated with this job.
INTEGER
<job_status>
The status of the current job.
Error Conditions:
 
None.
 
 
To get the current analysis code and analysis type, use the “get_code_and_type” function. 
 
analysis_main.get_code_and_type
(<analysis_code_name>, <analysis_code_id>, <analysis_type_name>, <analysis_type_id>)
 
Input:
 
 
None.
 
 
Output:
 
 
STRING
<analysis_code_name>
The name of the current analysis code. This string has a maximum of 31 characters.
INTEGER
<analysis_code_id>
The ID of the current analysis code.
STRING
<analysis_type_name>
The name of the current analysis type. This string has a maximum of 31 characters.
INTEGER
<analysis_type_id>
The ID of the current analysis type.
Error Conditions:
 
None.
 
 
To fetch the model and results file suffixes for the current analysis code, use the function “get_file_suffixes”. 
 
analysis_main.get_file_suffixes
(<model_suffix>, <results_suffix>)
 
Input:
 
 
None.
 
 
Output:
 
 
STRING
<model_suffix>
The user defined model file suffix of the current analysis code. The maximum length of this string is 4 characters.
STRING
<results_suffix>
The user defined results file suffix of the current analysis code. The maximum length of this string is 4 characters.
Error Conditions:
 
None.
 
 
The user may want to hide, move or re-display items on the main Analysis form. In order to do this, he needs to know the widget IDs of these items. Once he has these IDs he can use “ui_wid_get” to get further information about the items and “ui_wid_set” to manipulate the items. The “get_panel_info” function can be used to get the widget IDs of many Analysis form items.
 
analysis_main.get_panel_info
(<form_id>, <first_y_location>, <job_frame_id>, <button_frame_id>, <separator_id>, <apply_button_id>)
 
Input:
 
 
None.
 
 
Output:
 
 
widget
<form_id>
The ID of the main Analysis form.
REAL
<first_y_location>
The Y position on the main Analysis form of the first widget following the Analysis Code / Analysis Type text box.
widget
<job_frame_id>
The ID of the job name / job description frame.
widget
<button_frame_id>
The ID of the button frame.
widget
<separator_id>
The ID of the separator widget.
widget
<apply_button_id>
The ID of the apply button.
Error Conditions:
 
None.
 
 
 
Note:  
The values returned by “get_panel_info” are invariant with respect to action-object selection, so this calls only needs to be made once. But the main Analysis form is refreshed every time an action-object change is made (including when the analysis preference is changed or when the main Analysis for is closed and then re-opened), so any modifications to the main Analysis form must be repeated every time a action-object change is made. A good place for any main Analysis form changes would be the <apply_class>.option_menu_change_is_done function.