Configuration scripts for support designer

CADMATIC uses a script API to configure certain Support Designer functionality. For example, when Support Designer needs a position ID for the support to be created, it calls a script function from the COS configuration object "Configuration scripts for Support Designer". This script function can implement custom position ID generation according to the needs of the user organization. There are currently 17 script function interfaces that Support Designer calls at run-time, and the user organizations can customize each of these.

The CADMATIC example project includes an example implementation which you can view and edit by opening the Project Environment dialog and browsing to [project] > Configuration > Support Designer, as described in Configuration scripts for Support Designer.

To minimize bulk code, many of the functions call a system default function to do most of the work.

The call interfaces of these stub functions are listed below. The names and the parameters of these scripts should never be changed, and the scripts should return values back to the caller, precisely according to the documented logic.

InitConfig

Syntax

int_val = InitConfig ( )

Return Values

Success:
int 0
Failure:
int -1 Error.

Description

This script function is called before the other configuration API functions defined in this file.

It should check the existence and the compatibility of the custom attributes of location plans and piping supports.

In the example environment, it only checks one attribute: "Loc Plan Square".

GetNewLocPlanData

Syntax

int_val = GetNewLocPlanData ( gname, dname, x, y ,z, vdirx, vdiry, vdirz, umin, umax, vmin, vmax, depth, vupx, vupy, vupz )

Output arguments
string gname The support group and support drawing name.
string dname The support document name.
float x, y, z View point.
float vdirx, vdiry, vdirz View direction vector.
float umin, umax, vmin, vmax View limits.
float depth View depth.
float vupx, vupy, vupz View up direction.

Return Values

Success:
int 0
Failure:
int -1 User canceled the operation.

Description

This script function gets two names and the limits for a new location plan.

For practical reasons, we define the location plan area via view parameters—notice the difference between absolute coordinates (x,y,z) and view coordinates (u,v,w). The system function to define the limits is lpd_edit_data which uses the Plant Modeller ViewTool utility.

This script is called prior to creating the group "gname", and thus the attributes for the group are queried in another call.

EditLocPlanAttrs

Syntax

int_val = EditLocPlanAttrs ( locplan_group_h, n_perms, perms_h, gname, dname )

Input arguments
int locplan_group_h The location plan group.
int n_perms The number of permission definitions.
handle perms_h An array of permission definitions.
string gname The location plan group name.
string dname The location plan document name.

Return Values

Success:
int 0
Failure:
int -1 Error.

Description

This script function edits (assigns) attributes to the location plan. The script is called when the named location plan group is already created, to let the user assign some attribute values to the location plan.

The example implementation calls the attribute editor in %PMS_HOME%\pm\macro\EditAttrs.mac with the interface EditObjAttributesViaClassF3. This uses a permission filter (as provided via the argument list) to control which attributes can be edited in the given context.

The name of the attribute class to use is "Support Location Plan".

The call looks like this:

Copy 
st = PM_CALL_SCRIPT(EDITATTRS,"EditObjAttributesViaClassF3",  locplan_group_h, 0, "Support Location Plan", n_perms, perms, 0, 0,0,0);

In most cases, you should use the default implementation as it is and assign the attributes for the supports to this attribute class.

GetNewSupportData

Syntax

int_val = GetNewSupportData ( locplan_group_h, gname, dname, main_type, sub_type )

Input arguments
handle locplan_group_h The location plan group.
int main_type One of SP_MAIN_TYPE_PIPE, SP_MAIN_TYPE_CABLE_TRAY or SP_MAIN_TYPE_DUCT.
int sub_type Either SP_STD_SUPPORT_TYPE or SP_CUSTOM_SUPPORT_TYPE.
Output arguments
string gname The support group name.
string dname The support drawing "name".

Return Values

Success:
int 0
Failure:
int -1 User canceled the operation.

Description

This script function gets the two names for a new support.

In the example implementation the system function spd_edit_data is used to show the user a dialog for providing the name.

The call looks like this:

Copy 
st = spd_edit_data(gname, dname, main_type, sub_type, TRUE);

Note: Also the actual name of the support drawing is "gname". The value of "dname" has no other meaning in the current version but it is written automatically into the drawing header file. By default, the name of the used tag is "Dno". Thus "dname" can be used for storing the drawing number of the support drawing if the drawing sheets use "Dno" as the drawing number tag. The tag name can be overridden in the configuration script GetDrawingNameTag.

GetRenameSupportData

Syntax

int_val = GetRenameSupportData ( locplan_group_h, gname, dname, main_type, sub_type, dummy1 )

Input arguments
handle locplan_group_h The location plan group.
int main_type See GetNewSupportData.
int sub_type See GetNewSupportData.
Input/Output arguments
string gname The group name of the support.
string dname The "document name" of the support.
Additional arguments, currently not in use
dummy1

Return Values

Success:
int 0
Failure:
int -1 User canceled the operation.

Description

This script function gets a new "gname" and "dname" for an existing support. The function is called when the support is a member in the given location plan group.

EditSupportAttrs

Syntax

int_val = EditSupportAttrs ( support_group_h, main_type, sub_type, n_perms, perms_h, gname, dname, context )

Input arguments
handle support_group_h The support group.
int main_type See GetNewSupportData.
int sub_type See GetNewSupportData.
int n_perms The number of permissions in the array.
handle perms_h An array of permission definitions.
string gname The support group name.
string dname The support "document name".
string context The context in which the function was called. The value can be "SupportCreated" or "EditAttributesOfSupport".

Return Values

Success:
int 0
Failure:
int -1 Error or user canceled the operation.

Description

This function edits and/or assigns attributes of a support. The attributes are assigned to the support group.

The "context" argument indicates whether attribute editing is requested automatically by the program (when a new support is created) or by the user (to edit the attributes of an existing support).

The "context" argument makes it possible, for example, to skip the attribute editing at creation time, which is often desirable.

This function is called when the named support group is already created.

The example implementation in the delivery environment calls the function EditObjAttributesViaClassF3 in the script file %PMS_HOME%\pm\macro\EditAttrs.mac. See EditAttrs.mac for details on the permissions.

In most cases you should use the example implementation as it is, and just assign your support attributes to one of the attribute classes: “Piping Support”, “Cable Tray Support” or “Duct Support”, according to the argument "main_type".

EditPrimarySupportAttrs

Syntax

int_val = EditPrimarySupportAttrs ( obj_h, n_perms, perms_h, context )

Input arguments
int obj_h The primary support object.
int n_perms The number of permission definitions.
handle perms An array of permission definitions.
string context The context in which this function was called. The value can be "EditAttributesOfPrimary", "CopyPrimary", "ConstructPrimary" or "AssignPrimary".

Return Values

Success:
int 0
Failure:
int -1 Error or user canceled the operation.

Description

This script function edits (assigns) attributes to a primary support object.

The argument "context" makes it possible to adjust the behavior of the function according to the context in which the function is called.

In the example environment, the attributes for primaries are to be edited only if the user explicitly wants to edit the attributes of a primary support.

GetSecondarySystemId

Syntax

int_val = GetSecondarySystemId ( )

Return Values

int The System ID number.

Description

This script function returns the System ID number of the System for the secondary support objects (beams).

GetPrimaryComponentClass

Syntax

string_val = GetPrimaryComponentClass ( )

Return Values

Success:
string The component class (piping specifications) for the new primary support component.

Description

This script function returns the component class name of the new primary component. The selection from the piping specification is initialized according to this value when a new primary object (standard component) is to be inserted.

GetSecondaryPipeLine

Syntax

string_val = GetSecondaryPipeLine ( )

Return Values

Success:
string The Pipeline ID string.

Description

This function returns the Pipeline ID string for secondary components that are modeled as pipes.

GetInitialPlateSearchPattern

Syntax

string_val = GetInitialPlateSearchPattern ( cpc_field )

Input arguments
string cpc_field The Catalog Part field to search for.

Return Values

string A search pattern.

Description

When plates are inserted into the model, Support Designer initializes the Corporate Catalog selection tool to scan components which are expected to be plates.

This script function defines the search pattern which only allows plates to be shown in the selection list.

The argument "cpc_field" defines the field to use in the scanning. The return values need to define a valid CADMATIC pattern match string.

The valid abbreviations are listed in Format control for catalog parts.

In the example environment, the field is "KW" (keyword) and the pattern match value is "*PLATE*".

SetupCustomSupportDrawingGeneration

Syntax

int_val = SetupCustomSupportDrawingGeneration ( gname, dname, p_s_set, p_set_h, s_set_h, neighb_set_h, n_defs, defs_h, def_scale )

Input arguments
string gname The support group name.
string dname The support "document name".
handle p_s_set_h The set of primary and secondary objects.
handle s_set_h The set of secondary objects.
Output arguments
handle neighb_set_h The set of "neighbor" objects.
int n_defs The number of definitions in the defs_h array.
handle defs_h An array of instructions to configure the View from P1 -> P2 tool.
float def_scale The initial view scale.

Return Values

Success:
int 0
Failure:
int -1 Error.

Description

This function sets up and creates the visualization sets needed in making standard views for the custom support drawing.

The "neighbor" objects are optionally visualized to the views too, but the view limits are computed solely based on the bounding box of the objects assigned to the support.

The set of neighbor objects can be set to (int) 0, if the neighbor set is not defined.

The defs array is an n x 2 array. The first column identifies the data item to set, and the second column defines a value to it.

The array type is the old 2D array, as defined in the script %PMS_HOME%\include\array.mac.

Valid controls for View P1 -> P2 tool

  • "Front_ViewName"

  • "Top_ViewName"

  • "Left_ViewName

  • "Right_ViewName"

  • "Right_ViewName

  • "Axo_ViewName"

  • "Axo_ViewPoint"

  • "Front_Opt"

  • "Top_Opt"

  • "Left_Opt"

  • "Right_Opt"

  • "Axo_Opt"

  • "LAS_Opt"

  • "LineAttributeStyle"

  • "ClNsLimit"

  • "ViewMargin"

  • "VDirTolAngle"

  • "RmHlines"

  • "VisRule"

  • "VisRuleFront"

  • "VisRuleTop"

  • "VisRuleLeft"

  • "VisRuleRight"

  • "VisRuleAxo"

The value fields are either strings, integers or floats, depending on the context. See the user interface of the View P1 -> P2 tool. See also the source code in ViewP1P2.mac. All these settings have a reasonable default value, thus mostly only a few of them need to be defined.

AutoAnnotateSupportViews

Syntax

int_val = AutoAnnotateSupportViews ( gname, dname, set_h )

Input arguments
string gname The support group name.
string dname The support "document name".
handle set_h The set of primary and secondary objects.

Return Values

Success:
int 0
Failure:
int -1 Error.

Description

This script function generates some trivial annotations to the views in the active (custom support) drawing. When this script stub is called, the custom support drawing is the active drawing.

In the example environment, the function directly calls the corresponding system utility: AnnotSupportViews.

Note: AutoAnnotateSupportViews is called by old Support Designer versions up to 2021T2. In 2021T2 it is still possible to configure the old Support Designer to be used, and in that case this interface is still called.

AutoAnnotateSupportViews2

Syntax

int_val = AutoAnnotateSupportViews2 ( support_group_h )

Input arguments
handle support_group_h The support group.

Return Values

Success:
int 0
Failure:
int -1 Error.

Description

This script function generates labels to the views in the active (custom support) drawing.

In the example environment, the function indirectly calls the automatic labeling function described in Automatic Labeling.

Note: AutoAnnotateSupportViews2 is called by new Support Designer versions, starting from 2021T2.

GenerateAndAssignPartNumberstoObjectsInBOM

Syntax

int_val = GenerateAndAssignPartNumberstoObjectsInBOM ( support_group_h )

Input arguments
handle support_group_h The support group.

Return Values

Success:
int 0
Failure:
int -1 Error.

Description

This script function generates part numbers for parts in the support group.

The example implementation calls the system default function GenerateAndAssignPartNumbersToObjectsInBOM to generate the part numbers.

This function is called before the labels are automatically placed to the views.

AutoAnnotateLocPlanView

Syntax

AutoAnnotateLocPlanView ( gname, dname, set_h );

Input arguments
string gname The group name of the location plan.
string dname The "document name" of the location plan.
handle set_h The set of objects in the location plan group.

Return Values

Success:
int 0
Failure:
int -1 Error or user canceled the operation.

Description

This script function generates some trivial annotations to the location plan view.

When this function is called, the location plan drawing is the currently active drawing.

In the example environment, the function calls the corresponding system utility: AnnotLocPlanView.

GetCollisionTestParameters

Syntax

int_val = GetCollisionTestParameters ( accuracy_limit, min_clearance )

Input arguments
float accuracy_limit The accuracy limit value of collision testing.
float min_clearance The minimum clearance value of collision testing.

Return Values

int 0

Description

This script function gets the parameters accuracy limit and minimum clearance for executing collision checking.

GetDrawingNameTag

Syntax

string_val = GetDrawingNameTag ( )

Return Values

string The tag to be assigned to the drawing header file with "dname" as the value.

Description

This script function gets the name of the tag which will be added to the header file of the drawing with the support "dname" as the value.

Note: This function interface is optional; if the default tag name "Dno" is acceptable to you, then you do not need to have this function in this configuration script.