Tutorial

This is a quick introduction to the CADMATIC script language. It presents the essential elements of the language through real scripts, without going into too much detail. More detailed descriptions are provided in other chapters.

We use italics for emphasis.

File and directory names are presented as follows: \usr\foo.txt.

Example code is shown as follows:

main()
{
    U_MESSAGE("Hello world");
}

The appearance of the code is adapted from C (Kernighan & Ritchie: The C Programming Language).

• Tutorial
  • How the script system works
  • Script execution

How the script system works

Script compiler

The executable program dm_sc is used to compile source-format scripts into binary-format scripts. To run this program, you provide the name of the text input file and the binary output file as command-line arguments; no special directory is required. All messages are written to the standard output. Typically, dm_sc is called indirectly, either by the application or through helper scripts.

Script executor

The script executor is embedded in the application and does not exist as a separate program.

Intrinsic functions

Intrinsic functions are built into the script executor and can be called from any script.

External functions

External functions are C-coded API functions that are loaded into the application when it is built. They are grouped into sets so that applications do not need to load all functions. Common utility functions are loaded by every application.

External functions must be declared as externs in the source file. Typically, in \usr\pms<version>\include, there is an include file that declares the extern functions for each set. For example, the P&ID application loads the following function sets:

• PD functions (Diagram)
• DG functions (Graphics diagram)
• DB functions (Database)
• DW functions (2D drafting)
• 2D symbol functions

Scriptlibs

Scriptlibs are precompiled binary script libraries. When the application starts, it loads the scriptlib automatically. For example, the scriptlib of CADMATIC P&ID includes the tool functions that form the outermost layer of the application. User organizations typically do not modify scriptlib functions. In the case of P&ID, the scriptlib effectively constitutes the application, and modifications by external parties are not supported.

Script execution

Scripts can be executed from most CADMATIC applications. When the user selects to execute a script, the system prompts them to select a file with the .mac extension.

If there is no binary version of the script, or if the binary is older than the source code, the application starts another process to compile the script before execution.

All examples in this manual can be executed as described in Executing scripts.

The script system

The first script

As is customary, the first script prints the message 'Hello world' in the message pane.

Copy the following script into a text file and save it as hello.mac.

#include include/dmutil.h
main()
{
    U_MESSAGE("Hello world");
}

To run the script, start Plant Modeller, make sure the message pane is open, select Tools tab > Run group > Script, and open the .mac file. Plant Modeller starts dm_sc, runs the script, and 'Hello world' is displayed in the message pane.

Explanation:

The include directive is required because U_MESSAGE is an external function and not built into the language. The file \usr\pms<version>\include\dmutil.h declares the Datamatic utility functions as externs.

main() is the entry point of the script. Scripts that are executed must define at least the main() function. The parenthesis ( ) define the argument list. If main() has arguments, a dialog prompts the user to provide values.

The U_MESSAGE() function takes a single argument of type string and displays it in the message pane.

The second script

The second script displays the CADMATIC Yes/No dialog and prompts the user with a question.

#include include/dmutil.h
main()
{
    default = 0;
    answer = U_YESNO("To be, or not to be?",default);
    if( answer == 1 )
        ToBe("a script programmer");
    else
        NotToBe("afraid of scripts");
}
ToBe(string s)
{
    U_MESSAGE("To be "+s);
}
NotToBe(string s)
{
    U_MESSAGE("Not to be "+s);
}

Explanation:

default = 0;

This assignment initializes the variable 'default'. Variables must be initialized before use. Assigning a value to a variable also sets it type dynamically.

answer = U_YESNO("To be, or not to be?",default);

This statement calls the Datamatic utility function U_YESNO. The default selection is defined by the variable 'default'. When the user makes a selection, the return value is assigned to the variable 'answer'.

Depending on whether the expression evaluates to true (answer == 1), either the function 'ToBe' or 'NotToBe' is called.

Functions in the script language (as in C, but unlike Pascal) are defined outside blocks; that is, they are defined at the outermost level.

In this example, a function is called with one argument, 's'. The keyword string specifies that the argument is of type string. If a type specifier is used, it is checked when the function is called. Declaring the type is optional.

The CADMATIC script language supports a convenient string concatenation method, using the + operator, where either operand can be a string variable or a string literal.