Adding Custom General Field Functions

PCL and Customization > Modifying the Database Using PCL > Adding Custom General Field Functions

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">

General Fields allow the user to define fields using custom PCL functions incorporated with the Patran menu system. The user/programmer can create any functionality desired for a field in PCL, and then create a custom set of forms to input data to the custom function.

Once defined in Patran, the custom function appears as a term in a General Field function expression. The custom function term may be used by itself, of in combination with other terms to constitute the field. The field can then be applied in various applications in Patran. Custom functions and forms can be created and used by a single user, or be available across an entire Patran installation.

All aspects of General Fields functions are controlled by the user/programmer. These include the function name and evaluation routine, the custom forms displayed for argument input, and the type of field for which the function is defined.

To create custom functions, the names and field type definitions must first be stored in the database. Then, the user must write a PCL evaluator function which returns the result. This evaluator will be called by the General Fields code automatically when evaluation is required. Finally, if custom forms are required for function input, the use/programmer must create a PCL class which manages the input data as specified in the rules given below. If no custom form is created, a generic argument input form will automatically display. The generic form displays only a databox for each argument, labeled with the expected data type. For this reason, the generic form should only be used with simple functions having self evident inputs.

Adding Functions to the Database

Function names are displayed to the user in the General Fields Input Data form when the “term-type” option menu is set to “P3 Functions”. The list of functions displayed is determined by the current analysis code, the current field object type, (Spatial, Material Property or Non-Spatial) and the setting of the term “sub-type” option menu. Therefore, all three of these parameters must be specified for each function name when it is entered into the database. Note that the term “sub-type” is a user specified string (31 characters maximum) which provides a convenient way to group functions for display. All sub-type strings specified for a given analysis code and field object type will appear in the sub-types option menu.

To store a function in the database, use the following PCL function:


db_add_general_field_func	(<analysis_code_id>, <object>, <sub_type>, <function_name>)


Input:
INTEGER	<analysis_code_id>	The analysis code ID.
INTEGER	<object>	The object type ID.
STRING[31]	<sub_type>	String displayed in the sub-type menu.
STRING[31]	<function_name>	Name of the Function.
Output:
INTEGER	<Return Value>	Status return value. The value will be 0 if successful.
Error Conditions:
None.

This routine specifies the four arguments which make up a unique function entry in the database. The arguments are detailed below:

• The analysis code id can be found with the function:


db_count_general_field_func	(anal_code_id, object, sub_type, count)


Description:
Counts the number of functions in the field general functions relation for given input parameters.
Input:
INTEGER	anal_code_id	Analysis Code ID.
INTEGER	object	Object type ID: 0 for Spatial, 1 for Material, 2 for Non Spatial
CHARACTER[31]	sub_type	Sub-type string.
Output:
INTEGER	count	Number of functions.
INTEGER	<Return Value>	= 0, success else error code.
Error Conditions:
Numerous.

• The object type IDs are defined as:


Spatial	= 0
Material Property	= 1
Non-Spatial	= 2

• The sub-type string is a descriptive name which is displayed in the sub-type option menu. Typically, a single sub-type will be used to group multiple function names.

• The function name is a descriptive name for the function, but is also the name of the associated PCL code required for every function.

Every function must have a PCL evaluator function of the same name as the “function_name” argument. This function must return a single value for a set of input arguments. If the function is to have a custom form as well, a PCL class of the same name must also exist. Creation of the PCL class is detailed below.


db_get_general_field_func	(anal_code_id, object, sub_type, count, names)


Description:
Retrieves the function names in the field general functions relation for given input parameters.
Input:
INTEGER	anal_code_id	Analysis code ID.
INTEGER	<object>	Object type ID: 0 for Spatial, 1 for Material, 2 for Non Spatial.
CHARACTER[31]	<sub_type>	Sub-type string.
INTEGER	count	Number of functions.
Output:
CHARACTER[31]()	names	Function names.
INTEGER	<Return Value>	= 0, success else error code.
Error Conditions:
Numerous.


Note:	The C name differs. It is DbGetGeneralFieldFunc.

Evaluator PCL

Every PCL function name added to the Patran database must have a corresponding PCL Evaluator Function. This function will take the stored argument data as an input and return a single result. The evaluator function may work with a custom PCL form, or it may use the Generic Function Data form provided by the General Fields Application.

The procedures for each case are slightly different, and instructions for the use of each method are given below.

Generic Function Form Use

The Generic form is useful for simple functions with few arguments. The General Fields code first looks for a PCL class for the function in question, and if it does not find one, it brings up the Generic form. The Generic form code interrogates the PCL function to determine its argument list, then creates a databox for each argument. Each databox is labeled as to the type of argument (integer, real, logical, string or widget) expected.

While the user is free to input data in each argument databox, all argument expressions must be valid PCL syntax. This is because the contents of each databox are used directly as inputs to the PCL evaluating function for the corresponding argument. When the user is finished filling out the generic form, all data from the form is stored as a character string in the database. The format of this string is:

<function_name>(argument_1 | argument_2 | argument_3 | ...)

The vertical bar “|” is used to denote the separation between databoxes (or arguments). When the function is evaluated, the “|” characters are replaced with commas, any independent variables are replaced with values and the line is evaluated via PCL. These details should be transparent to the user, as long as it is noted that the databoxes are created in the order of the argument list, and that the databox contents conform to PCL syntax.

Custom Function Form Use

For complex or specialized custom functions, it will be useful to create custom argument input forms. Custom forms can be very powerful, and greatly facilitate specialized work. A custom form is created similarly to other custom PCL forms (See Example: Creating a Simple Customized Menu and Form, 293, but there are some specific requirements for compatibility with General Fields.

The first requirement is that the custom form class be of the same name as the function and evaluator function. Second, the class must contain both “display” and “exit” functions, as these are called by the General Fields code. Finally, the custom argument form must communicate with the General Fields code through the following routines:

• Whenever the custom form is closed, such as for “OK” or “Cancel”, the following call must be made to notify the General Fields code:


fields_genrl_inp_data.form_up	(“<function_name>”, FALSE)


Input:
STRING[31]	<function_name>	Name of the function PCL class.
Output:
None.
Error Conditions:
None.

Comments:

The object of the custom form PCL is to present data to the user in such a way that he can compose an input argument string for the custom PCL evaluator function. Therefore, once the user input is complete and the user selects “OK”, the custom form PCL must compose the function input in the form of a character string. The format of this string must be:

<function_name>(argument_1 | argument_2 | argument_3 | ...)

The vertical bar “|” is used to denote the separation between databoxes (or arguments). When the function is evaluated, the “|” characters are replaced with commas, any independent variables are replaced with values and the line is evaluated via PCL. After the argument string is assembled by the custom form PCL, it must be written to the General Fields storage with the routine:


fields_genrl_inp_data.write_term_data	(<argument_string>)


Input:
STRING[VIRTUAL]	<argument_string>	String composed by the custom form PCL.
Output:
None.
Error Conditions:
None.

Comments:

As the argument string is used to call the evaluator function, it must obey the following rules:

The string must start with the name of the evaluator function.

This is followed by PCL expressions for each term. Note that these expressions must be in order corresponding to the argument list and that the expressions are enclosed in parentheses. The argument expressions must be valid PCL syntax.

Each argument expression is separated in the argument string with a vertical bar character(“|”).

The allowable independent variables for various fields types may change; i.e., real independent variables are not allowed for parametric fields. To get the independent variables allowed by General Fields for a specific field case, call the function:


fields_genrl_inp_data.pass_ind_var_ids	(spatial_vars, other_vars)


Input:
INTEGER(3)	<spatial_vars>	Array of spatial variable IDs.
INTEGER(6)	<other_vars>	Array of non-spatial variable IDs.
Output:
None.
Error Conditions:
None.


Independent Variable	Letter Designation	Integer ID
Spatial	“X”	1
Y Direction	“Y”	2
Z Direction	“Z”	3
R Direction	“R”	4
T Direction	“T”	5
P Direction	“P”	6
C1 Direction	“C1”	7
C2 Direction	“C2”	8
C3 Direction	“C3”	9
Temperature	“T”	10
Strain	“e”	11
Strain Rate	“er”	12
Time	“t”	13
Frequency	“f”	14
Radiosity	“RAD”	15

Comments:

Further restriction of valid independent variables available to a custom function can be implemented by the user/programmer with this information. The custom PCL form code may be programmed to error check and reject any independent variables not desired.

The General fields code will call a custom form by calling its “.display” function. When called however, a custom form must determine if it needs to be initialized, (as in the case of a new field) or filled with existing data (as in the case of modifying an existing field). In order to do this, the “.display” must call the function:


fields_genrl_inp_data.get_data	(<name>, <data>, <term_id>)


Input:
None.
Output:
STRING[31]	<name>	Function name.
STRING[VIRTUAL]	<data>	Character string data for the current term id.
INTEGER	<term_id>	Next term id available.
Error Conditions:
None.

Comments:

This function returns the currently loaded values of the arguments. If no existing General Field function is loaded, the “data” string will be blank. If that is the case, re-initialize the form. If the “data” string is not blank, parse the data string back into the individual argument strings and load the data into the databoxes.

An Example Case

Following is a short example illustrating the creation and use of custom General Field Functions. The use of both the Generic Function form and a simple custom form is explained.

Use of the Generic Function Form

In order to use the Generic form, it is necessary only to create an evaluator function and load the function name into the database. The example function, sum_func, will sum the input arguments. The evaluator function could be:

/*$$ FUNCTION sum_func

*  Purpose:

*     Sum the input arguments

*  Input:

*     Three integer arguments

*/

FUNCTION sum_func(arg1, arg2, arg3)

/*

* Local Declarations

*/

INTEGER arg1

INTEGER arg2

INTEGER arg3

INTEGER answer

answer = arg1 + arg2 + arg3

RETURN answer

END FUNCTION /* sum_func */

If the user wished to load this function only under the Spatial and Non-Spatial field types, the function required to load this function into the database might look like this:

/*$$ FUNCTION load_func

*  Purpose:

*     load function sum_func into the database.

*  Input:

*     < none >

*/

FUNCTION load_func( )

/*

* Local Declarations

*/

INTEGER stat

INTEGER acid

INTEGER FIELDS_SPATIAL_ID

INTEGER FIELDS_MATERIAL_ID

INTEGER FIELDS_NON_SPATIAL_ID

/*

* Initialize...

*/

stat = 0

acid = 1 /* Nastran code ID */

FIELDS_SPATIAL_ID      = 0

FIELDS_MATERIAL_ID     = 1

FIELDS_NON_SPATIAL_ID  = 2

/*

* Add Function "sum_func" for Spatial and Non-Spatial

* Fields Object types.

*/

stat = db_add_general_field_func(acid, 		@

FIELDS_SPATIAL_ID,		@

Simple Functions",		@

"sum_func" )

IF(stat != 0 )THEN

!$ Error adding mt_tests, stat = ‘stat‘

RETURN (-1)

END IF

stat = db_add_general_field_func(acid,		@

FIELDS_NON_SPATIAL_ID,		@

"Simple Functions",		@

"sum_func" )

IF(stat != 0 )THEN

!$ Error adding mt_tests, stat = ‘stat‘

RETURN (-1)

END IF

RETURN (0)

END FUNCTION /* load_func */

In order to incorporate this custom function into Patran, two steps must be taken. First, a new database containing this function's name and definition is created and then used as the new template.db.

To create the new template.db:

• Open a new empty database.

• Compile “load_func” with the “!! input” command in Patran.

• Execute “load_func” with the “load_func()" command.

• Close the new database, and rename it “template.db”.

Then, the evaluator function must be compiled into the Patran PCL. This is most conveniently accomplished by adding the PCL with the “p3epilog.pcl” file. In the directory in which the user is running Patran, the “p3epilog.pcl” might look like this:

!Adding General Fields Functions to PCL...

!! INPUT sum_func.pcl

As Patran is starting up, the first line of the p3epilog.pcl file will be written to the launching window as a warning that PCL is being added. Compile messages will also be written out.

Now, upon opening a database, the General Fields Input form will list the function “sum_func” in the Functions term type, under the “Simple Functions” subtype, for Spatial and Non-Spatial fields.

Use of a Custom Form

The incorporation of a custom form requires the addition of one step to the above procedure. A PCL class must be defined which displays and controls the input to the function. (For more information regarding custom PCL forms, see Example: Creating a Simple Customized Menu and Form, 293. This PCL code must follow the rules listed in Generic Function Form Use, 582 for custom forms.