Tutorial User Guide > General Utility Functions > PCL Function Descriptions
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">   
PCL Function Descriptions
acumen_drive_page_trans
(source_page, converted_page)
Description:
This function serves as a PCL environment interface to the utility function that compiles or indexes XML “drive pages” for more efficient reading by the MSC Acumen software. The first argument references a source file with the .xml file extension. The second argument names the output indexed file with a .xio file extension. It is convenient for application authors to invoke this call from full featured MSC Patran by typing it into the command line.
Input:
STRING
source_page[ ]
This is a string representing the name of the XML drive page source file, for example, “model1.xml”
STRING
converted_page[ ]
This is a string representing the name of the indexed or converted drive page, for example, “model1.xio”
Output:
An indexed and compressed .xio file is written out.
 
 
 
aa_env.ret_acumen_app
(s_acumen_app, s_acumen_master, s_acumen_ext)
 
Description:
This function will retrieve the ACUMEN_APPLICATIONS directory and home drive page file name values. This function will also verify that the named directory and file exist. It will check date stamps on the named .xml and .xio file and translate the .xml file into a .xio file if needed.
Status:
Public
Input:
None.
Output:
STRING
s_acumen_app [ 1024 ]
 
This argument will return the ACUMEN_APPLICATIONS directory value.
STRING
s_acumen_master [ 1024 ]
 
This argument will return the body of the home drive page file name defined by the ACUMEN_APPLICATIONS environment variable.
STRING
s_acumen_ext [ 1024 ]
 
This argument will return the extension of the home drive page file name defined by the ACUMEN_APPLICATIONS environment variable.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will retrieve and display to the user any error messages associated with an error value.
The error value will be returned for flow of control purposes. Any errors that occur will be reported directly to the user through the user interface.
The "ACUMEN_APPLICATIONS" value provides the path and file name for the home drive page of a user developed Tutoral application.
This value can be reset at runtime to allow application files to be located in more than one directory.The following file location and name asumptions are made:
 
1.
The master .xio and .xml files will be located directly in the home drive page directory defined by the environment variable ACUMEN_APPLICATIONS.
2.
The .def file will have the same path and base file name as the application home drive page with a .def extension.
3.
The labels file will have the same path and base file name as the application home drive page with a .labels extension.
4.
All .html help files will be in a subdirectory named "help" under the home drive page directory.
5.
The pulldown menu title definitions file will have the same path and base file name as the home drive page with a .dwn extension.
6.
Application specific .plb files will have the same path and base file name as the home drive page with a .plb extension. If a file with the specified extension cannot be found, no application specific .plb’s will be linked in.
7.
Application specific image files (.png) will be in a subdirectory named “app_images” located under the home drive page directory.
The default values returned by this function is as follows in the following order:
1. The value of the the acumen app string if set.
2. The value of the "ACUMEN_APPLICATIONS" environment variable if it is set and the acumen app string has not been set or is zero length.
3. A default value of "ACUMEN_HOME"/tutorial_apps/tutorial.xio
4. A value of "tutorial_apps/tutorial.xio"
See also: aa_env.ret_acumen_app_aa(), get_acumen_app(), set_acumen_app()
aa_env.ret_acumen_app_aa
(s_acumen_app, s_acumen_master, s_acumen_ext)
Description:
This function will retrieve the ACUMEN_APPLICATIONS directory and home drive page file name values. This function will verify that the named directory and file exist.
Input:
None
 
 
Output:
STRING
s_acumen_app [ 1024 ]
This is a string representing the name of the XML drive page source file, for example, “model1.xml”
STRING
s_acumen_master[ 1024 ]
This is a string representing the name of the indexed or converted drive page, for example, “model1.xio”
STRING
s_acumen_ext [ 1024 ]
This argument will return the extension of the home drive page file name defined by the ACUMEN_APPLICATIONS environment variable.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will retrieve and display to the user any error messages associated with an error value.
The error value will be returned for flow of control purposes. Any errors that occur will be reported directly to the user through the user interface.
The "ACUMEN_APPLICATIONS" value provides the path and file name for the home drive page of a user developed Tutoral application.
This value can be reset at runtime to allow application files to be located in more than one directory.
The following file location and name asumptions are made:
1. The master .xio and .xml files will be located directly in the home drive page directory defined by the environment variable ACUMEN_APPLICATIONS.
2. The .def file will have the same path and base file name as the application home drive page with a .def extension.
3. The labels file will have the same path and base file name as the application home drive page with a .labels extension.
4. All .html help files will be in a subdirectory named "help" under the home drive page directory.
5. The pulldown menu title definitions file will have the same path and base file name as the home drive page with a .dwn extension.
6. Application specific .plb files will have the same path and base file name as the home drive page with a .plb extension. If a file with the specified extension cannot be found, no application specific .plb’s will be linked in.
7. Application specific image files (.png) will be in a subdirectory named “app_images” located under the home drive page directory.
The default values returned by this function is as follows:
1. The value of the the acumen app string if set.
2. The value of the "ACUMEN_APPLICATIONS" environment variable if it is set and the acumen app string has not been set or is zero length.
3. A default value of "ACUMEN_HOME"/tutorial_apps/tutorial.xio
4. A value of "tutorial_apps/tutorial.xio"
See also: aa_env.ret_acumen_app(), get_acumen_app(), set_acumen_app() 
 
aa_env.ret_acumen_brw
(s_acumen_brw)
Description:
This function will retrieve the directory and file name value defined by the "ACUMEN_BROWSER" environment variable. This function will verify that the named directory and file exist.
Input:
None
 
 
Output:
STRING
s_acumen_brw [ 1024 ]
This argument will return the path and filename of the browser application used to display Tutorial application help messages.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will call code to retrieve and display to the user any error messages associated with an error value.
This function will return by the default the same value as used with P3_BRW_HELP. This relationship is established in <P3_HOME?/bin/patran.pl on WINNT and <P3_HOME>/site_setup on UNIX.
Any errors that occur will be reported directly to the user through the user interface.
The "ACUMEN_BROWSER" can be changed at run time.
This function does not have a defined default value.
See also: set_acumen_brw(), get_acumen_brw()
 
aa_env.ret_acumen_home
(s_acumen_home)
Description:
This function will retrieve the ACUMEN_HOME value and will check for the existance of the directory named. This value is used to identify the directory that contains the Tutorial core shared component.
Input:
None
 
 
Output:
STRING
s_acumen_home [ 1024 ]
This argument will return the current "ACUMEN_HOME" value.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will call code to retrieve and display to the user any error messages associated with an error value.
The error value will be returned for control of flow purposes. Any errors that occur will be reported directly to the user through the user interface.
The "ACUMEN_HOME" value can be changed at runtime.
All core .plb and status message files will be placed directly in the "ACUMEN_HOME" directory. It is assumed that the status message file will have the name "aa_message_core.dat".
The default "ACUMEN_HOME" value is defined as follows in order:
1. The internal acumen home value if it is defined.
2. The environment variable "ACUMEN_HOME".
3. The value of the P3_HOME environment variable.
4. On UNIX: "/patran/patran3", on WINNT: "c:\msc".
The directory used to contain the Tutorial core shared component is <acumen_home>/lib on UNIX platforms, or <acumen_home>/bin or <acumen_home>/bin/exe on Windows NT.
The "ACUMEN_HOME" can be changed at runtime.
See also: get_acumen_home(), set_acumen_home()
 
aa_env.ret_acumen_html
(s_html)
Description:
This function returns the value of the "HTML_IMAGE_PATH" environment variable. This value is used to provide path information to the html browser widget used to implement the Tutorial user interface.
Input:
None
 
 
Output:
STRING
s_html [ 1024 ]
This argument will return the current "HTML_IMAGE_PATH" value.
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:
This function may return a nonzero value if an error occurs.
Remarks:
The "HTML_IMAGE_PATH" can be changed at runtime. Changing this value allows the Tutorial application author to locate image file sets in multiple directories.
The "HTML_IMAGE_PATH" default value is the <s_acumen_app>/images where <s_acumen_app> is the value returned in the first argument to a call to aa_env.ret_acumen_app()
See also: aa_env.set_acumen_html()
 
aa_env.ret_acumen_int
(s_acumen_int)
Description:
This function will retrieve the "ACUMEN_INTERFACE" value.
Input:
None
 
 
Output:
STRING
s_acumen_int [ 1024 ]
This argument will the "ACUMEN_INTERFACE" value.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will call code to retrieve and display to the user any error messages associated with an error value.
The error value will be returned for control of flow purposes. Any errors that occur will be reported directly to the user through the user interface.
The "ACUMEN_INTERFACE" value can be changed at runtime. This value is used only with stand alone Tutorial applications.
This value will have no effect with Tutorial applications started through the "Help" "Tutorials" button in Patran.
This value will have no effect after the uil_init() function commonly called in <P3_HOME>/init.pcl has been called.
The Tutorial core code with accept either "ENABLE" or "DISABLE" for the "ACUMEN_INTERFACE" value.
The default "ACUMEN_INTERFACE" value returned by this funciton is "DISABLE".
When a Tutorial application is run stand alone by starting Patran with an "-ifile aa_init.pcl" the aa_init.pcl file will use a default value of "ENABLE" for the acumen interface value. The functions aa_env.ret_acumen_int() or get_acumen_int() cannot be used at that point as the plb and dll files that contain those functions have not yet been loaded into Patran.
See also: get_acumen_int(), set_acumen_int().
 
aa_env.ret_acumen_y_scale
(r_y_scale)
Description:
This function returns the "ACUMEN_Y_SCALE" value. This value is used to set a scaling factor for the form that comprises the Tutorial user interface.
Input:
None
 
 
Output:
STRING
r_y_scale
This argument will return the either a default value or the value to which "ACUMEN_Y_SCALE" has been set.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This value will have no effect after the uil_init() function commonly called in <P3_HOME>/init.pcl has been called.
The "ACUMEN_Y_SCALE" can be used to scale or adjust sizing and spacing of widgets on the Tutorial user interface.
This value was implemented to allow adjustments to be made on displays with smaller pixel counts such as may occur on laptops.
See also: get_acumen_y_scale, aa_env.set_acumen_y_scale()
 
aa_env.set_acumen_html
(s_html)
Description:
This function sets the value of the "HTML_IMAGE_PATH" environment variable. This value is used to provide path information to the html browser widget used to implement the Tutorial user interface.
Input:
STRING
s_html [ 1024 ]
This argument will return the current "HTML_IMAGE_PATH" value.
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:
This function may return a nonzero value if an error occurs.
Remarks:
The "HTML_IMAGE_PATH" can be changed at runtime. Changing this value allows the Tutorial application author to locate image file sets in multiple directories.
The "HTML_IMAGE_PATH" default value is the <s_acumen_app>/images where <s_acumen_app> is the value returned in the first argument to a call to aa_env.ret_acumen_app()
See also: aa_env.ret_acumen_html()
 
aa_env.set_acumen_y_scale
(r_y_scale)
Description:
This function sets the "ACUMEN_Y_SCALE" value. This value is used to set a scaling factor for the form that comprises the Tutorial user interface.
Input:
STRING
r_y_scale
This argument will return the either a default value or the value to which "ACUMEN_Y_SCALE" has been set.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This value will have no effect after the uil_init() function commonly called in <P3_HOME>/init.pcl has been called.
The "ACUMEN_Y_SCALE" can be used to scale or adjust sizing and spacing of widgets on the Tutorial user interface.
This value was implemented to allow adjustments to be made on displays with smaller pixel counts such
as may occur on laptops.
See also: get_acumen_y_scale, aa_env.ret_acumen_y_scale()
 
aa_env.validate_path
(s_src_path_file, s_trg_path_file)
Description:
This function will validate the existance of file with either no path, a partial path, or a full path exists.
Input:
STRING
s_src_path_file [ 1024 ]
This value defines the path and file name to be validated.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will check the input string for the following condition:
1. The first character is either a UNIX style “/” or a WINNT style”\”.
2. The second character is a colon (“:”).
If either one of these conditions is meet, it will be assumed that the input string represents a full path. If neither of these conditions are met, it will be assumed that the path is relative to the ACUMEN_APPLICATIONS directory.
The error value will be returned for flow of control purposes. Any errors that occur will be reported directly to the user through the user interface.
 
aaui_forms.html_refresh
( )
Description:
This function forces a refresh of the html browser widget in the Tutorial user interface.
Input:
None
 
 
Output:
None
 
 
 
Remarks:
Occasionally the html browser widget does not correctly display the html sent to it as a value. This function forces a refresh of the widget, correcting that problem.
If calling this funciton does not correctly refresh the browser widget, check the value returned by ui_htmlbrsr_get_image_path (). Possibly the image path value is invalid, causing images listed in the html browser widget to be displayed incorrectly.
 
acumen_drive_page_trans
(source_page, converted_page)
Description:
This function compiles or indexes XML Tutorial drive pages efficient reading by the Tutorial software.
Input:
STRING
source_page[ ]
This is a string representing the name of the XML drive page source file, for example: “model1.xml”
STRING
converted_page[ ]
This is a string representing the name of the converted drive page, for example: “model1.xio”
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:
This function will return a nonzero value if an error occurs.
When an xio file is loaded the Tutorial code will automatically convert an xml drive page into an xio file if the xml file has a time stamp identifying it as newer than the xio file or if the xio file is missing. This makes it very easy to edit an xml file then see the results while a Tutorial application is running.
Distributing xio pages without xml files will allow applications to be delivered without source files and preventing the application from being modified.
 
get_acumen_app
(s_app)
Description:
This function returns the "ACUMEN_APPLICATIONS" value.
Input:
None
 
 
Output:
STRING
s_app [1024]
This string will return:
1. The value of the the acumen app string if set.
2. The value of the "ACUMEN_APPLICATIONS" environment variable if it is set and the acumen app string has not been set or is zero length.
3. A default value of "ACUMEN_HOME"/tutorial_apps/tutorial.xio
4. A value of "tutorial_apps/tutorial.xio"
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:
This function will return a nonzero value if an error occurs.
Remarks:
The "ACUMEN_APPLICATIONS" value provides the path and file name for the home drive page of a user developed Tutoral application.
This value can be reset at runtime to allow application files to be located in more than one directory.
See also: aa_env.ret_acumen_app(), aa_env.ret_acumen_app_aa(), set_acumen_app()
 
get_acumen_brw
(s_brw)
Description:
This function returns the "ACUMEN_BROWSER" value.
Input:
None
 
 
Output:
STRING
s_brw [1024]
This string will return:
1. The value of the the acumen browser string if set.
2. The value of the "ACUMEN_BROWSER" environment variable if it is set and the acumen browser string has not been set or is zero length.
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:
This function will return a nonzero value if an error occurs.
Remarks:
The "ACUMEN_BROWSER" value provides the path and file name for the executable used to display Tutorial html help pages.
Typically this value should be set to the save value as used with the environment value "P3_BRW_HELP" with no arguments passed to the executable.
See also: aa_env.ret_acumen_brw(), set_acumen_brw()
 
get_acumen_debug
(i_debug)
Description:
This function returns the "ACUMEN_DEBUG" value.
Input:
None
 
 
Output:
INTEGER
i_debug
This value is used to control or turn on the listing of debug information. This function will return:
1. The value of the the acumen debug value if set.
2. The value of the "ACUMEN_DEBUG" environment variable if it is set and the acumen browser string has not been set or is zero length.
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:
This function will return a nonzero value if an error occurs.
Remarks:
This value is used to control the display of internal debugging information. The higher the value, the more information will be listed.
This value has a range of 0 (off) to 5.
This value can be reset at runtime.
See also: set_acumen_debug()
 
get_acumen_home
(s_acumen_home)
Description:
This function will retrieve the ACUMEN_HOME value without checking for the existance of the directory named. This value is used to identify the directory that contains the Tutorial core shared component.
Input:
None
 
 
Output:
INTEGER
s_acumen_home [ 1024 ]
This argument will return the current "ACUMEN_HOME" value.
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:
This function will return a nonzero value if an error occurs.
Remarks:
The "ACUMEN_HOME" value can be changed at runtime.
All core .plb and status message files will be placed directly in the "ACUMEN_HOME" directory. It is assumed that the status message file will have the name "aa_message_core.dat".
The default "ACUMEN_HOME" value is defined as follows in order:
1. The internal acumen home value if it is defined.
2. The environment variable "ACUMEN_HOME".
3. The value of the P3_HOME environment variable.
4. On UNIX: "/patran/patran3", on WINNT: "c:\msc".
The directory used to contain the Tutorial core shared component is <acumen_home>/lib on UNIX platforms, or <acumen_home>/bin or <acumen_home>/bin/exe on Windows NT.
The "ACUMEN_HOME" can be changed at runtime.
See also: aa_env.ret_acumen_home(), set_acumen_home()
 
get_acumen_int
(s_acumen_int)
Description:
This function will retrieve the "ACUMEN_INTERFACE" value.
Input:
None
 
 
Output:
INTEGER
s_acumen_int [ 1024 ]
This argument will the "ACUMEN_INTERFACE" value.
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:
This function will return a nonzero value if an error occurs.
Remarks:
The "ACUMEN_INTERFACE" value can be changed at runtime. This value is used only with stand alone Tutorial applications.
This value will have no effect with Tutorial applications started through the "Help" "Tutorials" button in Patran.
This value will have no effect after the uil_init() function commonly called in <P3_HOME>/init.pcl has been called.
The Tutorial core code with accept either "ENABLE" or "DISABLE" for the "ACUMEN_INTERFACE" value.
The default "ACUMEN_INTERFACE" value returned by this funciton is "DISABLE".
When a Tutorial application is run stand alone by starting Patran with an "-ifile aa_init.pcl" the aa_init.pcl file will use a default value of "ENABLE" for the acumen interface value. The functions aa_env.ret_acumen_int() or get_acumen_int() cannot be used at that point as the plb and dll files that contain those functions have not yet been loaded into Patran.
See also: aa_env.ret_acumen_int(), set_acumen_int().
 
get_acumen_y_scale
(r_y_scale)
Description:
This function returns the "ACUMEN_Y_SCALE" value. This value is used to set a scaling factor for the form that comprises the Tutorial user interface.
Input:
None
 
 
Output:
INTEGER
r_y_scale
This argument will return the either a default value or the value to which "ACUMEN_Y_SCALE" has been set.
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:
This function will return a nonzero value if an error occurs.
Remarks:
This value will have no effect after the uil_init() function commonly called in <P3_HOME>/init.pcl has been called.
The "ACUMEN_Y_SCALE" can be used to scale or adjust sizing and spacing of widgets on the Tutorial user interface.
This value was implemented to allow adjustments to be made on displays with smaller pixel counts such as may occur on laptops.
See also: aa_env.set_acumen_y_scale(), aa_env.ret_acumen_y_scale()
 
set_acumen_app
(s_app)
Description:
This function sets the "ACUMEN_APPLICATIONS" value.
Input:
STRING
s_app [1024]
The value to which "ACUMEN_APPLICATONS" is set.
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:
This function will return a nonzero value if an error occurs.
Remarks:
The "ACUMEN_APPLICATIONS" value provides the path and file name for the home drive page of a user developed Tutoral application.
This value can be reset at runtime to allow application files to be located in more than one directory.
This function only qualifies the length of the input value and does not verify the validity of the path and file name.
See also: aa_env.ret_acumen_app(), aa_env.ret_acumen_app_aa(), get_acumen_app()
 
set_acumen_brw
(s_brw)
Description:
This function sets the "ACUMEN_BROWSER" value.
Input:
STRING
s_brw [1024]
This string is used to set the "ACUMEN_BROWSER" value.
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:
This function will return a nonzero value if an error occurs.
Remarks:
The "ACUMEN_BROWSER" value provides the path and file name for the executable used to display Tutorial html help pages.
Typically this value should be set to the save value as used with the environment value "P3_BRW_HELP" with no arguments passed to the executable.
This function only qualifies the length of the input value and does not verify the validity of the path and file name.
See also: aa_env.ret_acumen_brw(), get_acumen_brw()
 
set_acumen_debug
(i_debug)
Description:
This function sets the "ACUMEN_DEBUG" value.
Input:
STRING
i_debug
This value is used to control or turn on the listing of debug information.
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:
This function will return a nonzero value if an error occurs.
Remarks:
This value is used to control the display of internal debugging information. The higher the value, the more information will be listed.
This value has a range of 0 (off) to 5.
This value can be reset at runtime.
See also: get_acumen_debug()
 
set_acumen_home
(s_acumen_home)
Description:
This function set the ACUMEN_HOME value.
Input:
STRING
s_acumen_home [ 1024 ]
This argument will set the current "ACUMEN_HOME" value.
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:
This function will return a nonzero value if an error occurs.
Remarks:
This function is used to set "ACUMEN_HOME" value at runtime.
All core .plb and status message files will be placed directly in the "ACUMEN_HOME" directory. It is assumed that the status message file will have the name "aa_message_core.dat".
The default "ACUMEN_HOME" value is defined as follows in order:
1. The internal acumen home value if it is defined.
2. The environment variable "ACUMEN_HOME".
3. The value of the P3_HOME environment variable.
4. On UNIX: "/patran/patran3", on WINNT: "c:\msc".
The directory used to contain the Tutorial core shared component is <acumen_home>/lib on UNIX platforms, or <acumen_home>/bin or <acumen_home>/bin/exe on Windows NT.
The "ACUMEN_HOME" can be changed at runtime.
See also: aa_env.ret_acumen_home(), get_acumen_home()
 
set_acumen_int
(s_acumen_int)
Description:
This function will set the "ACUMEN_INTERFACE" value.
Input:
STRING
s_acumen_int [ 1024 ]
This argument will the "ACUMEN_INTERFACE" value.
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:
This function will return a nonzero value if an error occurs.
Remarks:
The "ACUMEN_INTERFACE" value can be changed at runtime. This value is used only with stand alone Tutorial applications.
This value will have no effect with Tutorial applications started through the "Help" "Tutorials" button in Patran.
This value will have no effect after the uil_init() function commonly called in <P3_HOME>/init.pcl has been called.
The Tutorial core code with accept either "ENABLE" or "DISABLE" for the "ACUMEN_INTERFACE" value.
The default "ACUMEN_INTERFACE" value is "DISABLE". See also: aa_env.ret_acumen_int(), get_acumen_int().
 
 
aa_env.ret_acumen_brw
(s_acumen_brw)
 
Description:
This function will retrieve the acumen_browser directory and file name value. This function will verify that the named directory and file exist.
Status:
Public
Input:
None.
Output:
STRING
s_acumen_brw [ 1024 ]
 
This argument will return the path and filename of the browser application used to display MSC Acumen application help messages.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will call code to retrieve and display to the user any error messages associated with an error value.
The error value will be returned for flow of control purposes. Any errors that occur will be reported directly to the user through the user interface.
The acumen_browser value will be retrieved every time this function is called, allowing the corresponding value to be changed "on the fly". Please see the description for the PCL function set_acumen_brw ( )
This environment variable provides the path and file name for the executable used to display help pages for a user developed MSC Acumen application.
Example:
 
aa_env.ret_acumen_home
(s_acumen_home)
 
Description:
This function will retrieve the acumen_home directory value and will check for the existance of the directory used to contain the MSC Acumen core shared component.
Status:
Public
Input:
None.
Output:
STRING
s_acumen_home [ 1024 ]
 
This argument will return the current acumen_home value.
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:
This function will return a nonzero value if an error occurs.
 
Remarks:
This function will call code to retrieve and display to the user any error messages associated with an error value.
The error value will be returned for flow of control purposes. Any errors that occur will be reported directly to the user through the user interface.
The acumen_home value will be retrieved every time this function is called, allowing the corresponding value to be changed "on the fly"..Please see the description for the PCL function set_acumen_home ( ).
All core .plb and status message files will be placed directly in the acumen_home directory. It is assumed that the status message file will have the name "aa_message_core.dat".
The default acumen_home value will be retrieved from the environment variable "ACUMEN_HOME". If the "ACUMEN_HOME" environment variable is not defined, the default value of "P3_HOME" will be used. If "P3_HOME" is not defined, "/patran/patran3" will be used for UNIX, "c:\msc" for WINNT.
The directory used to contain the MSC Acumen core shared component is <acumen_home>/lib on UNIX platforms, or <acumen_home>/bin on Windows NT.
The acumen_home will be retrieved every time this function is called, allowing the corresponding environment variable to be changed "on the fly". Please see the description for the PCL function set_acumen_home ( ).
Example
:
aa_env.ret_acumen_int
( s_acumen_int )
Description:
This function will retrieve the acumen_interface value
Status:
Public
Input:
None.
Output:
STRING
s_acumen_int [1024 ]
This argument will return the path and filename of the browser application used to display MSC Acumen application help messages.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will call code to retrieve and display to the user any error messages associated with an error value.
The error value will be returned for flow of control purposes. Any errors that occur will be reported directly to the user through the user interface.
The acumen_interface value will be retrieved every time this function is called, allowing the corresponding value to be changed "on the fly"..Please see the description for the PCL function set_acumen_int ( ).
Currently MSC Acumen will accept either ENABLE or DISABLE for the acumen_interface value.
Example:
 
aa_env.validate_path
( s_src_path_file, s_trg_path_file)
 
Description:
This function will validate the existance of file with either no path, a partial path, or a full path really exists.
Status:
Public
Input:
STRING
s_src_path_file [ 1024 ]
Output:
STRING
s_trg_path_file [ 1024 ]
 
 
This value returns a string representing the path used for the test.
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:
This function may return a nonzero value if an error occurs.
Remarks:
This function will check the input string for the following condition:
1. The first character is either a UNIX style “/” or a WINNT style”\”.
2. The second character is a colon (“:”).
If either one of these conditions is meet, it will be assumed that the input string represents a full path.
If neither of these conditions are met, it will be assumed that the path is relative to the ACUMEN_APPLICATIONS directory.
The error value will be returned for flow of control purposes. Any errors that occur will be reported directly to the user through the user interface.
Example: