PCLFunction Descriptions

Tutorial User Guide > Drive Page Interpreting Functions > PCLFunction Descriptions

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">


AAI.html_calls	(pclcalls)


Description:
This function will execute the function or functions described by the string argument pclcalls. This call is typically listed on an HREF anchor of HTML dialog packets. This function will parse the argument supplied into the indicated PCL function calls with their arguments, and then make the calls.
Input:
STRING	pclcalls[ ]	This value specifies the PCL functions and all parameters for those functions. The format is given in the Remarks section below.
Output:
Error Conditions:
None.

Remarks:

The ‘;’(semicolon) character partitions the STRING argument into the sub strings which are then interpreted as function names or various types of function arguments depending upon the sub string prefixes. Since the ‘)’ character indicates the end of the call sequence to the HTML widget hypertext reference interpreter function, this character is NOT allowed in any string type substring or other arguments.

The FUNC: sub string prefix signifies the start of a function call name. Parse on the “F” and “:” characters so that F: or FN: or FUNCTION: are also valid function name prefixes

The STR: sub string prefix signifies the start of a string argument., Parse on the “S” and “:” characters so that S: or STRING: are also valid.

The REAL: sub string prefix signifies the start of a real number argument. Parse on the “R” and “:” characters so that R: is also valid.

The INT: sub string prefix signifies the start of an integer number argument. Parse on the “I” and “:” characters so that I: or INTEGER: are also valid.

The LOG: sub string prefix signifies the start of a logical variable argument (TRUE or FALSE). Parse on the “L” and “:” characters so that L: or LOGICAL: are also valid

Example:

AAI.html_calls(“FUNC:function1;STR:arg1;REAL:5.05;INT:12;FUNC:function2;LOG:TRUE;FUNC:function3;STR:string2;FUNC:function4”)

When the AAI.html_calls function processes this particular call, the following four PCL calls are made in sequential order:

function1(“arg1”, 5.05, 12)
function2(TRUE)
function3(“string2”)
function4()


Note:	Only fixed value arguments are available to PCL calls made directly by this method. When function calls require the user to input or change argument values, the “Input Box” functionality is used to display the required widgets and to automatically construct the corresponding PCL calls.

The intended use for AAI.html_calls is to allow PCL calls to be made from HTML anchors as shown below:

<A HREF="PCL:AAI.html_calls(FUNC:AANAV.lever_results;INT:1)">

Exaggerated </A> deformed shape.


AAI.get_step1id	(step1id)


Description:
This function will return the ID of the first analysis step. A separate, special XML drive page exists for the first analysis step. This function reads that page and searches for the stepid tag.
Input: Output:

STRING	step1id[4]	This value returns the ID found in the step tag.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

If this function fails to find the Step-1 XML page and the step ID from the step tag, then an error message will be issued to the UI form Dialog Box HTML widget.


Note:	The XML drive page for the first step is defined through the environment variable AdvisorPAGE1.

Example:

None


AAI.allsteps_display	()


Description:
This function will search for the <defsteps> tag on an XML page. It reads the 4 character ID and 36 character definition of steps for all analysis steps. It obtains the step completion indications from the STATE TABLE. It calls the AAUI.mainpanel_include_steps function to cause a display of the steps on the Main Panel.
Input:
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

A call to this function is typically made upon completion of the first analysis step on the separate step-1 “drive page”. Step-1 determines the particular analysis type that the user will undertake, and assigns a “nextpage” user response variable to the State Table pointing to the “home drive page” file for all subsequent steps.

Example:

None


AAI.init_step_dialog	()


Description:
This function will read the XML solution sequence page and follow the automated link rules to select the correct initial dialog for a selected step. This function is called by the user interface model in response to a user selecting an analysis step.
Input:
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This call is automatically made by the platform software when an analysis step is selected from the main panel. Application authors are not expected to call this function directly.

Example:

None


AAI.step_help_doc	()


Description:
This function will display the supplemental HTML help document associated with the current operational analysis step, if one is specified, by launching the MSC Acumen BROWSER application.
Input:
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None

Remarks:

This function is called automatically as a result of selecting the “Help” button. It will display only the document defined by an attribute to the <step> tag. Please see the AAUI.helpdoc_display, 111 call for displaying alternative HTML documents with a pop-up commercial browser.

Example:

None


AAI.next_dialog	(filename, filestep, dialog_id)


Description:
This function will read the XML page file, extract the HTML dialog called for, and feed it to the UI Dialog Box HTML widget. The dialog is selected by direct reference to the page “filename”, the step tag ID on that page file “filestep”, and the dialog tag ID within the step tag “dialog_id”. No automated link rules are followed to get to the dialog.
Input:
STRING	filename[128]	This value specifies the name of the XML file. If the first character is a ‘/’, it is a full path, otherwise it is a relative path from the AdvisorLIB environment variable path.
STRING	filestep[4]	This value specifies the step ID.
STRING	dialog_id[8]	This value specifies the dialog ID.
Output:
INTEGER	<Return Value>	his function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This call is the mechanism used to arrive at a subsequent HTML dialog upon user selection of a hypertext link. It supports all “background” PCL calls listed as attributes to a <dialog> tag. When widgets are displayed for a dialog, the “quedlg” or “errordlg” attributes to the <dialog> tag automatically point to the next HTML dialog. This function is automatically called in that case. Note the general nature of this call allows for the creation of sub-pages for common or complex processes.

Example:

None.


AAI.dynamic_next_dialog	(htmlstring, filename, filestep, dialog_id)


Description:
This function will find and display HTML dialog and handle function calls associated with the referenced <dialog> tag. In addition, this call appends the HTML contained in the “htmlstring” argument to the front of the any HTML found in the referenced “drive page” dialog. The <HTML> </HTML> tags from the two sources are consolidated into one set bounding the total constructed dialog. This call enables the dynamic construction and display of HTML dialog from automation functions. The dialog may present information that was obtained through recent computations. To use double quotes, “, within a PCL string that is being passed, two double quotes , ““, are used and will be converted to one double quote within the string. See example below.
Input:
STRING	htmlstring[ ]	This value specifies dynamically generated HTML data to append in the front of any fixed HTML contained in the referenced <dialog> tag.
STRING	filename[128]	This value specifies the name of the XML file. If the first character is a ‘/’, it is a full path, otherwise it is a relative path from the AdvisorLIB environment variable path.
STRING	filestep[4]	This value specifies the step ID.
STRING	dialog_id[8]	This value specifies the dialog ID.
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None

Remarks:

The intended use for this function is calls from an automation function as opposed to referenced calls on “drive page” hyperlinks or tag attributes.

Example:

This is an example of how to use double quotes within a PCL dynamic string definition:

htmlstring=”<HTML><BODY BGCOLOR=””#FFFFFF””><FONT COLOR=””#FF0000””>” // @

“<P>You have selected the material: “ // mat // ”	</FONT></P></HTML>”

AAI.dynamic_next_dialog(htmlstring,page,stepid,”finish”)


AAI.queued_dialog	()


Description:
This function will display the next dialog HTML packet in the UI form Dialog Box associated with the quedlg argument for the current dialog.
Input: Output:

INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This call is automatically made by the MSC Acumen platform software as a consequence of selecting the “Apply Inputs” button. The application author is not expected to use this call.

Example:

None


AAI.queued_msg	()


Description:
This function will display an error condition warning dialog HTML packet in the UI form Dialog Box. It is called when user inputs to the Inputs Box result in an error return value.
Input:
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This call is automatically made by the MSC Acumen platform software as a consequence of selecting the “Apply Inputs” button. The application author is not expected to use this call.

Example:

None


AAI.queued_ftn	()


Description:
This function will execute optional supplemental PCL function calls as requested through the queftn argument in the dialog tag.
Input:
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This call is automatically made by the MSC Acumen platform software as a consequence of selecting the “Apply Inputs” button. The application author is not expected to use this call.

Example:

None.


AAI.initiate_ftn	()


Description:
This function will execute optional supplemental PCL function calls as requested through the initftn argument in the dialog tag.
Input:
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This call is automatically made by the MSC Acumen platform software as a consequence of navigation to a “drive page” <dialog> tag. The application author is not expected to use this call.

Example:

None


AAI.exit_ftn	()


Description:
This function will execute optional supplemental PCL function calls as requested through the exitftn argument in the dialog tag.
Input:
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This call is automatically made by the MSC Acumen platform software as a consequence of selecting the “Apply Inputs” button or through navigating to the next dialog through an AAI.next_dialog call. The application author is not expected to use this call.

Example:

None