Introduction

Plant Modeller can execute scripts which call functions that provide services for accessing views, drawings, and 3D model data, and for communicating with the user. Using these functions, you can write scripts that greatly improve the efficiency of design tasks. Note that script functions do not provide access to all the features that are available via the Plant Modeller user interface.

Plant Modeller script functions deal with the following special object types:

• trace structures (tracep_h)
• object handles (obj_h)
• transformation matrices (tmat_h)
• point sets (pnt_set_h)
• sets of Plant Modeller objects (set_h)
• view handles (view_h)

The handle names such as "tracep_h" and "obj_h" are used in this manual to indicate what types of handles to pass to different Plant Modeller script functions.

You cannot do any arithmetic operations with script variables that are used to store these objects. You can only pass them as arguments to script functions or test their equality with 0. If you assign these script variables to other variables, then remember that both variables refer to the same object. In scripts, the types that are mentioned above are defined as pointers or handles. A handle has a value 0 to mean that the object does not exist. The actual type of a script variable is stored in the variable itself and is checked by Plant Modeller script functions at entry time, e.g. when the function is called.

Most "create" functions return handles; "action" functions return 0 if the operation succeeds and -1 otherwise. Exceptions to these general rules are noted in the documentation.

Plant Modeller frees resources that have been allocated for various objects (tmat_h, set_h, etc.) when the execution of the script terminates and control returns back to Plant Modeller. This means that you MUST NOT attempt to store these handles in any way between different script invocations. Objects to which these handles point do not exist anymore when the next script starts.

For many resources, there is a script extern for freeing (de-allocating) the resource that was allocated on create. It is a good practice to free a resource that is no longer needed in the script, and sometimes this is even mandatory to keep memory consumption under control.

Object Types As Strings

Some script externs can take the Plant Modeller object type as an input argument whose data type is "string".

The valid object types as strings:

• "3DSPACE"

• "AIRDUCT" (obsolete, use HVACPART)

• "ATTRIBUTE"

• "BEAM"

• "CABLE"

• "CABLENETWORKPART"

• "CABLETRAY"

• "EQUIPMENT"

• "GROUP"

• "HOLEREQUEST"

• "HULLCONSTRUCTIONPART"

• "HVACPART"

• "PIPE" (obsolete, use PIPINGPART)

• "PIPINGPART"

• "STANDCMP"

• "STRUCTCMP"

• "TEMPGEOM"

• "WELD"

Several script externs can use an object type filter on their argument list. This filter is called "type mask" in the documentation, and type masks can be used in two ways: to allow selecting only certain types of objects, or to prevent selecting certain types of objects.

For example, PM_PICK_OBJECT uses a type mask.

The following call prompts the user to pick an object whose type is either equipment or structural component, other object types cannot be selected:

obj_h=PM_PICK_OBJECT("Pick objects", obsolete, "EQUIPMENT", "STRUCTCMP");

By adding "!" to the argument list, we can negate the type mask, so that the user can select any object except equipment or structural component:

obj_h=PM_PICK_OBJECT("Pick objects", obsolete, "!", "EQUIPMENT", "STRUCTCMP");