Tutorial

This is a quick introduction to the CADMATIC script language. We present the essential elements of the language in real scripts, without too many details. The only way to learn a new programming language is by writing programs in it. So, we will teach the script language with a lot of examples. In other chapters you find more detailed descriptions.

We use italics to emphasize things. File and directory names are printed like this: \usr\foo.txt. Example code is printed with a different font style:

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

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

• Tutorial
• How the Script System Works?
• Executing Scripts

How the Script System Works?

The Script Compiler

The executable program dm_sc is used to compile the source format scripts into binary format scripts. To run this program, the name of the text input file and the binary file to be created are given as command-line arguments; no special directory is used. All messages are written to the standard output (usually, the terminal). Usually dm_sc is called indirectly either by the application or via special scripts.

The Script Executor

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

Intrinsic Functions

These functions are built into the script executor, and they can be called from any script.

External Functions

External functions are C-coded API functions which are loaded into the application when it is built. They are grouped into sets, so that applications do not need to load everything. The 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 of these sets. 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 which form the outermost cover of the application. User organizations usually do not make changes to the scriptlib functions. In the case of P&ID, the scriptlib is the application and we even deny to support it if scriptlib is touched by others than CADMATIC.

Executing Scripts

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

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

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

The script system

The First Script

We will follow tradition and have our first script print the magic words "Hello world" into the message pane. Start for example Plant Modeller and in another shell window change your current directory to the design area. Then start editing a file, for example with vi hello.mac. Write the following lines into the file and save it. Then select to execute the script in Plant Modeller, and choose the file hello.mac from the list. Plant Modeller will start dm_sc automatically. Have a look at the message pane. There should be the text "Hello world".

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

The include line is needed since U_MESSAGE is an external function, not a function built into the language. \usr\pms<version>\include\dmutil.h declares all the Datamatic utility functions to extern.

main() is the entry point of this function. Scripts which are "selected and run" must define at least the main() function. The parenthesis characters '( )' limit the argument list. If main() has arguments, a query dialog opens and the user can fill in the contents of the argument variables.

U_MESSAGE() function takes one argument of type character string, which it prompts in the message pane.

This script file can be run for example from Plant Modeller by selecting Tools > Script.

Let's make another script:

#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);
}

This script displays the CADMATIC Yes/No dialog and prompts the user with the eternal philosophical question.

Let's look how the script works.

default = 0;

This assignment initializes the variable 'default'. Variables must be initialized before they are used. Note that giving a value to a variable dynamically sets its type too.

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

Here, a Datamatic utility function U_YESNO is called. The default selection is set with the variable 'default'. When the user makes the selection, the return value is assigned to var 'answer'.

Depending on the truth value of the expression (does 'answer' equal to one), one of the two functions 'ToBe' or 'NotToBe' is called.

Functions in the script language (like in C, not like in Pascal) are defined outside blocks, i.e. functions conform the outermost blocking.

Here we have a function call with one argument, 's'. The reserved word string specifies that the data type of the argument is a character string. If a type specifier is used in the parameter list, then the type is checked when the function is called. Declaring the data type is optional.

CADMATIC script language implements a handy string concatenation method, s1 + s2, where either side can be a string variable or a string constant.