PM_CALL_SCRIPT

Syntax

untyped_val = PM_CALL_SCRIPT ( script_file, script_name[, arg1, arg2, …] );
Input arguments
string script_file The path and the name of the script file. The file can be either already compiled (.bs) or in source format (.mac). The file can be located in the COS database, or it can be located in the file system using either an absolute or relative file path.

If the argument value is an empty string, the specified function is searched for in the project-specific script library. This binary file is loaded when a Plant Modeller session starts, and any global variables it contains retain their values throughout the session. Customer organizations cannot add scripts to it.
string script_name The name of the script function to be called.
Optional input/output arguments
variable arg1, arg2, … The argument list for the script function to be called.

Return Values

The return value from the called script function.

Description

This function can be used to call a script function located in another file or in the same file, allowing the reuse of existing code. However, be aware that calling a function in this way takes considerably longer than a normal function call, because PM_CALL_SCRIPT loads the script from the file every time it is called. In contrast, calling a function from COS only compiles the script upon the first call. Using PM_CALL_SCRIPT to call functions from files inside a loop is not recommended. A better approach is to organize the code so that PM_CALL_SCRIPT calls are kept to a minimum. When a function is called from COS, performance is much better, and such calls can be used inside loops.

This function can only verify the number of arguments passed to the script. It cannot verify the argument types.

Calls using a file path

The script file can be loaded from the file system by using an absolute or relative file path.

Call Details

PM_CALL_SCRIPT("C:\temp\script.mac", "hello_world")

This call uses an absolute path to load the script from C:\temp\script.mac.

PM_CALL_SCRIPT(".\script.mac", "hello_world")

This call uses the relative path .\ to load the script from the design area folder: <project>.pms\<workspace>.wsp\<area>.pm\script.mac

PM_CALL_SCRIPT("..\script.mac", "hello_world")

This call uses the relative path ..\ to load the script from the workspace folder: <project>.pms\<workspace>.wsp\script.mac

Calls using the COS database

The script file can be loaded from the 'pm' category of either the library or project database, using the following syntax:

PM_CALL_SCRIPT("script.mac", "hello_world")

Note: The call specifies whether the target script is a precompiled file (.bs) or a script source file (.mac). However, in the COS database, the file name is always just "script" without the extension.

Search order

When the location is not specified, PM_CALL_SCRIPT tries to find a script with a matching name from various locations, in this order:

  1. %COS Database%/Project/

  2. %COS Database%/Library/

  3. %PMS_HOME%/pm/

This search order allows, for example, a project-specific customized system script to be located in the project database while its original version is located in the library database.

Binary scripts are stored either in %PMS_RUNDIR%/pm/macro or in the Windows temporary folder if the script is run from COS.

Related topics

DM_CALL_SCRIPT