Executing Scripts
Scripts can be executed by opening the script file from a menu in the application. This might not be very convenient if the script needs to be run very often. There are two possible ways to execute a script from a menu "as a command". If you are not familiar with customizing CADMATIC menus, see the CADMATIC Project Administrator's Manual.
Running Scripts as a Command
The special menu command number 902 tells the system that there is a script call in the dat field of the menu item definition record. The dat field contains two strings separated with a white space:
script_source_file function_call
Script_source_file is a pathname to the source file. The function_call includes the arguments.
About Automatic Build
The system is able to cache binary scripts and thus can start large scripts much faster.
If the script is started as a menu command or is called from another script and the pathname of the script source file is a relative pathname, then a set of directories are scanned to find the script source file using the relative pathname.
If a source file is found, the system checks if a corresponding up-to-date binary script exists in the corresponding binary directory. If not, the system compiles the script and places the binary script into the binary directory and executes it. Otherwise the existing binary is executed.
Important: The automatic build feature does not compare file modification dates of script source files included to scripts. In practice include files rarely change.
Note: If you run a script file by selecting it from the application menu, or reference the source file with an absolute pathname, the system always compiles the script before running and the temporary binary script file is removed after the execution.
How Source Files Are Scanned in Automatic Build
If the name of the source is given as macro/script_src_file, then the following root directories are scanned in this order:
%PMS_PROJROOT%/%PMS_PROJNAME%/sde/src/app/
%PMS_LIBDIR%/src/app/
%COS Database%/Library
%PMS_HOME%/app/
where app stands for the module abbreviation, e.g. "pm" for Plant Modeller.
The order of the search makes it possible to make customized system scripts into your project, since the first matching file is used. Which means that in version 5 it is possible to run scripts from old sde-directory if it exists.
Binary scripts are stored either under
%PMS_RUNDIR%/app/macro
or
Windows temporary folder if the script is run from COS.
You should also see documentation of DM_CALL_SCRIPT which tells you more about the running order of scripts and also has some examples.
Calling scriptlib Functions
Note: Scriptlibs are part of the application. Thus customers should not edit nor rebuild scriptlibs but to use the binary version delivered with the product.
The special menu command number 1001 means that there will be a scriptlib function call in the dat field.
Scriptlibs are precompiled binary script "libraries". In the %PMS_HOME%/dm/macro directory there is a compile script for scriptlibs of each module.
It is important to remember that even though scriptlibs are like script libraries the current system does not provide any tools for managing them(partial deletes, updates and additions). The compile shell scripts work like this: first a module specific subdirectory is scanned through recursive copying into a file in /tmp. Header files (xxx.h) are collected at the beginning of this file, then all the non-header script files are put one after another into the file. As the last step the file is compiled and the binary placed into directory %PMS_RUNDIR%/.<hosttype>/<app>/macro.
Note: Error messages refer to rows in the file in /tmp, not to the original source files. Each application can currently load only one scriptlib file.
The following example shows the ways to run scripts from menus. We assume that the application is P&ID.
The menu looks like this:
/* demonstrate three different ways to call scripts from a menu */
nco 1;tit Script demo;;
/* 1) Use Filetool to select the script to be
executed */
val 902;str Select and run a macro;icn macros;;
/* 2) Execute a specific script "as a command" */
val 902;str Run a func from a mac file;dat macro/howdy.mac say_howdy("People");icn hello;;
/* 3) Execute a script from the scriptlib */
val 1001;str Call func from the scriptlib;dat sclib_hello();icn sc_hello;;
and the corresponding script files:
/* sde/src/pd/macro/howdy.mac */
#include include/dmutil.h
say_howdy(string s)
{ U_MESSAGE("Howdy "+s);}
and
/* pms_home/pd/macro/scriptlib/sclibfnc.apd */
sclib_hello()
{ U_MESSAGE("This is a scriptlib function");}
The scriptlib source files are expected to have the following extensions:
|
P&ID |
.apd |
|
Plant Modeller |
.apm |
|
Piping Isometrics & Spools |
.api |
Turning script messages on and off
There is a possibility to use application defaults for turning the script "compile" and script "load" output messages on or off when the script is compiled or loaded. This is controlled by using the extern SET_INT_DEFAULT(module, name, value). Modules and names are "ScriptManager/ShowCompiles" and "ScriptManager/ShowLoads". Value can be TRUE or FALSE. The default value for these application defaults is TRUE.
The following script example shows how messages are turned off.
#include "include/dmutil.h"
#define MESSAGES FALSE
main()
{
if(MESSAGES == FALSE)
disable_messages();
else
enable_messages();
return(0);
}
disable_messages()
{
compiles = FALSE;
loads = FALSE;
write_to_appdef(compiles,loads);
}
enable_messages()
{
compiles = TRUE;
loads = TRUE;
write_to_appdef(compiles,loads);
}
write_to_appdef(compiles,loads)
{
st_compiles = SET_INT_DEFAULT("ScriptManager", "ShowCompiles", compiles);
st_loads = SET_INT_DEFAULT("ScriptManager", "ShowLoads", loads);
}
Controlling the Prompting of Run-time Error Messages
Normally, run-time errors that occur during script execution are displayed in the message pane. These messages can be difficult to notice, especially while the script is still running.
If the environment variable CONFIRM_SCRIPT_RT_ERRORS is set in the user's environment, only the first run-time error message in a series requires confirmation from the user, but all error messages are still displayed in the message pane.
All users who develop scripts should set CONFIRM_SCRIPT_RT_ERRORS, while other designers are better without. It is recommended to set this variable for the Windows user, so that it is available for any project, for the specific computer when used by the specific user.
The confirmer implements the standard logic of our error confirmers: if a run-time error happens 1000 times in a loop, pressing OK once (or twice) is enough.