Вы находитесь на странице: 1из 191

SmartPlant 3D/SmartMarine 3D

Programmer’s Guide

Version 2011 April 2011 DSP3D-PE-200039G


Copyright
Copyright © 2004-2011 Intergraph Corporation. All Rights Reserved.
Including software, file formats, and audiovisual displays; may be used pursuant to applicable software license
agreement; contains confidential and proprietary information of Intergraph and/or third parties which is protected by
copyright law, trade secret law, and international treaty, and may not be provided or otherwise made available
without proper authorization.
Portions of this software are owned by Spatial Corp. © 1986-2007. All Rights Reserved.

Restricted Rights Legend


Use, duplication, or disclosure by the government is subject to restrictions as set forth below. For civilian agencies:
This was developed at private expense and is “restricted computer software” submitted with restricted rights in
accordance with subparagraphs (a) through (d) of the Commercial Computer Software - Restricted Rights clause at
52.227-19 of the Federal Acquisition Regulations (“FAR”) and its successors, and is unpublished and all rights are
reserved under the copyright laws of the United States. For units of the Department of Defense (“DoD”): This is
“commercial computer software” as defined at DFARS 252.227-7014 and the rights of the Government are as
specified at DFARS 227.7202-3.
Unpublished – rights reserved under the copyright laws of the United States.
Intergraph Corporation
Huntsville, Alabama 35894-0001

Warranties and Liabilities


All warranties given by Intergraph Corporation about equipment or software are set forth in your purchase contract,
and nothing stated in, or implied by, this document or its contents shall be considered or deemed a modification or
amendment of such warranties. Intergraph believes the information in this publication is accurate as of its
publication date.
The information and the software discussed in this document are subject to change without notice and are subject to
applicable technical product descriptions. Intergraph Corporation is not responsible for any error that may appear in
this document.
The software discussed in this document is furnished under a license and may be used or copied only in accordance
with the terms of this license.
No responsibility is assumed by Intergraph for the use or reliability of software on equipment that is not supplied by
Intergraph or its affiliated companies. THE USER OF THE SOFTWARE IS EXPECTED TO MAKE THE FINAL
EVALUATION AS TO THE USEFULNESS OF THE SOFTWARE IN HIS OWN ENVIRONMENT.

Trademarks
Intergraph, the Intergraph logo, PDS, SmartPlant, FrameWorks, I-Convert, I-Export, I-Sketch, INtools, ISOGEN,
MARIAN, SmartSketch, SPOOLGEN, SupportManager, and SupportModeler are trademarks or registered
trademarks of Intergraph Corporation or its subsidiaries in the United States and other countries. Microsoft and
Windows are registered trademarks of Microsoft Corporation. ISOGEN is a registered trademark of Alias Limited.
ACIS is a registered trademark of SPATIAL TECHNOLOGY, INC. Infragistics, Presentation Layer Framework,
ActiveTreeView Ctrl, ProtoViewCtl, ActiveThreed Ctrl, ActiveListBar Ctrl, ActiveSplitter, ActiveToolbars
Ctrl, ActiveToolbars Plus Ctrl, and ProtoView are trademarks of Infragistics, Inc. Portions of 2D DCM, 3D DCM,
and HLM from D-Cubed Limited are incorporated. All rights reserved. Other brands and product names are
trademarks of their respective owners.
Table of Contents

Table of Contents
Preface.................................................................................................................................7
SmartPlant 3D/SmartMarine 3D Product Documentation ...........................................8
Administrative Guides ........................................................................................................ 8
Documentation Comments ...........................................................................................9

Introduction......................................................................................................................10
Visual Basic .NET™ ........................................................................................................ 10
What's New in Programming Resources ....................................................................11

Software Architecture .....................................................................................................12


Three-Tier Architecture ..............................................................................................13
Client Tier ......................................................................................................................... 13
Middle (Business) Tier ..................................................................................................... 14
Server Tier ........................................................................................................................ 14

Getting Started .................................................................................................................16


Resources and References ..........................................................................................17
Printed Documentation ..................................................................................................... 17

Debugging Your Code .....................................................................................................18


Adding the TaskHost Project to your Project .............................................................19

Binding and Binary Compatibility .................................................................................20


Early Binding..............................................................................................................21
Late Binding ...............................................................................................................22

Command Priorities.........................................................................................................23

Error Handling.................................................................................................................24
Error Log Component.................................................................................................25

Referencing Data Type Libraries ...................................................................................26


Using the References Tool..........................................................................................27
Errors Occurring with Visual Basic 6.........................................................................29

Creating Custom Commands..........................................................................................31


Undo Functionality .....................................................................................................32

Customizing the Software ...............................................................................................33


Using ActiveX Components .......................................................................................34

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 3


Table of Contents

Creating an Implementation.............................................................................................. 34
Customizing Naming Rules........................................................................................35
Custom Name Rule ........................................................................................................... 36
IJNameRule Interface ....................................................................................................... 36
ComputeName Method..................................................................................................... 36
GetNamingParents Method............................................................................................... 37
CNameRuleAE Object...................................................................................................... 38
IJNameRuleAE Interface .................................................................................................. 38
Frozen Property................................................................................................................. 38
NamingParentsString Property ......................................................................................... 39
NameGeneratorService Object ......................................................................................... 40
IJNameCounter Interface .................................................................................................. 40
GetCount Method ............................................................................................................. 41
GetCountEx Method ......................................................................................................... 42
GetCountRange Method ................................................................................................... 43
NamingRulesHelper Object .............................................................................................. 44
IJDNamingRulesHelper Interface..................................................................................... 44
AddNamingRelations Method .......................................................................................... 45
GetActiveNamingRule Method ........................................................................................ 45
GetEntityNamingRulesGivenName Method .................................................................... 46
GetEntityNamingRulesGivenProgID Method .................................................................. 46
IsGeneratedNameUnique Method .................................................................................... 47
Customizing Hangers and Supports............................................................................48
IJHgrAutomation Interface ............................................................................................... 48
CreateSupport Method ...................................................................................................... 48
ModifySupport Method .................................................................................................... 51
CreateSupport Method Example....................................................................................... 53
Customizing Project Management..............................................................................54
ProjectMgmtEntitiesFactory Object ................................................................................. 56
AddLocation Method ........................................................................................................ 57
AttachPDSProject Method................................................................................................ 58
CreateProjectRoot Method................................................................................................ 59
CreateModelDatabaseObject Method ............................................................................... 60
CreateCatalogDatabaseObject Method ............................................................................. 61
CreateFolder Method ........................................................................................................ 61
CreatePermissionGroup Method....................................................................................... 62
CreateAccessControlRule Method.................................................................................... 63
CreateReportsDatabaseObject Method ............................................................................. 64
IJHierarchy Interface ........................................................................................................ 65
GetDisplayChildren Method............................................................................................. 66
Parent Property ................................................................................................................. 66
IJAccessRuleHelper Interface........................................................................................... 66
AddAccessControlRule Method ....................................................................................... 67
IJBackupRestoreHelper Interface ..................................................................................... 69
BackupPlantDatabases Method ........................................................................................ 70
RestorePlantDatabases Method ........................................................................................ 71
Customizing Drawings ...............................................................................................74
Package Versioning .......................................................................................................... 75
Using the Graphic Wrapper Modules ............................................................................... 76
IJDwgExternalModule...................................................................................................... 77

4 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Table of Contents

IJDwgWrapperCompound ................................................................................................ 78
IJDwgWrapperPseudoFilter.............................................................................................. 78

When to Use a Graphic Wrapper...................................................................................80


ElbowToSingleArc .....................................................................................................80
MakeDrawable............................................................................................................80
Equipment Nozzle Separator ......................................................................................81
ElbowToSingleArc Module .............................................................................................. 81
MakeDrawable Module .................................................................................................... 85
Equipment Nozzle Separator Module ............................................................................... 86
Vertical Vessel Supports Placement...........................................................................89
Creating Vertical Vessel Supports Example...............................................................92

Creating Part Occurrence Symbols in Visual Basic: An Overview ..........................104


Add a Symbol to Reference Data .............................................................................105
Distributing Symbols Automatically ........................................................................107
Distributing Symbols Manually................................................................................109
Creating Part Occurrence Symbols with the Part Definition Wizard: An Overview110
Workflow for Creating a VB Part Occurrence Symbol .................................................. 112
Visual Basic Part Definition Wizard............................................................................... 114
Step 1 - Create VB Project Page ..................................................................................... 115
Step 2 - Create Excel Spreadsheet Page.......................................................................... 118
Step 3 - Specify Definition Properties Page.................................................................... 120
Step 4 - Specify Occurrence Properties Page.................................................................. 122
Step 5 - Identify the Outputs Page .................................................................................. 124
Programming Notes for Visual Basic: An Overview ...............................................127
Defining Electrical Parts ................................................................................................. 127
Defining HVAC Parts ..................................................................................................... 130
Defining Hanger and Support Part Ports......................................................................... 132
Defining Piping Parts...................................................................................................... 134
Defining Nozzles ............................................................................................................ 135
Defining Parametric Components................................................................................... 139
Defining Valves .............................................................................................................. 142
Using SymbolHelper....................................................................................................... 145
Using Custom Aspects with a Symbol............................................................................ 148
Using String Type as an Input Parameter ....................................................................... 149
Using a Part as the First Input......................................................................................... 150
Converting PDS EDEN to SmartPlant Visual Basic Symbols: An Overview .........151
EDEN Translator Workflow ........................................................................................... 152
EDEN Translator Command Line Structure................................................................... 153
EDEN Translator Outputs............................................................................................... 155
EDEN Translator Required VB Editing.......................................................................... 156
EDEN Translator Example ............................................................................................. 160
Symbol Definitions: An Overview ...........................................................................164

EDEN Functions Programming Reference .................................................................167


DefineActiveOrientation Method .............................................................................167
DefineNozzle Method...............................................................................................168

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 5


Table of Contents

DefinePlacePoint Method.........................................................................................169
DefinePoint Method..................................................................................................170
DrawArc Method ......................................................................................................171
DrawComplexSurface Method .................................................................................172
DrawLine Method.....................................................................................................173
InitializeGlobals Method ..........................................................................................173
MoveAlongAxis Method ..........................................................................................174
MoveToPlacePoint Method ......................................................................................174
NozzleDefineDirectionVector Method.....................................................................175
NozzleInitialize Method ...........................................................................................175
NozzlePlace Method.................................................................................................176
RotateOrientation Method ........................................................................................177

Using the Equipment Symbol Upgrade Wizard..........................................................178


Introduction...............................................................................................................179
Before You Upgrade ....................................................................................................... 179
Register and Launch the Equipment Symbol Upgrade Wizard ...................................... 179
Log Files ......................................................................................................................... 180
Upgrade to the Equipment Component........................................................................... 180
Define Locations.......................................................................................................182
Equipment Symbol Upgrade Wizard - Step 1................................................................. 182
Search Equipment ProgIDs in Spreadsheets.............................................................183
Equipment Symbol Upgrade Wizard - Step 2................................................................. 183
Search VB Project Files for ProgIDs........................................................................184
Equipment Symbol Upgrade Wizard - Step 3................................................................. 184
Upgrade VB Projects and Spreadsheets ...................................................................185
Equipment Symbol Upgrade Wizard - Step 4................................................................. 185
Finish ........................................................................................................................187

Index................................................................................................................................188

6 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Preface

Preface
This document is a user's guide for programming and customization using
SmartPlant® 3D or SmartMarine 3D and provides information about custom
commands, naming rules, project management, symbol programming, and drawings
customization.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 7


Preface

SmartPlant 3D/SmartMarine 3D Product


Documentation
Most of the software's documentation is available as Adobe Acrobat PDF files. Most
of the content is the same as online Help. To access these PDF documents, click Help
> Printable Guides in the software.

Administrative Guides
SmartPlant 3D and SmartMarine 3D Installation Guide - Provides instructions on
installing and configuring the software.

SmartPlant 3D and SmartMarine 3D Administrator's Guide - Provides information


about setting up permission groups and specifications in the software.

SmartPlant 3D and SmartMarine 3D Reference Data Guide - Provides instructions


about the Bulkload utility and the reference data common to several disciplines.

SmartPlant 3D and SmartMarine 3D Symbols Reference Data Guide - Provides


information about the three-dimensional symbols used in all tasks.

8 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Preface

Documentation Comments
Send documentation comments or suggestions to PPMdoc@intergraph.com.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 9


Introduction

Introduction
The SmartPlant 3D/SmartMarine 3D Programmer's Guide provides introductory
information to developers who want to create custom commands or custom programs
using special tools and the software. Before creating commands or programs, you
must be very familiar with the software interactively and understand its basic
concepts of projects, engineering, architecture, concurrency, and datastores.

For more specific information about creating commands using the software
application programming interface (API), please contact Intergraph Services.

This programming guide includes:

• An overview of customization with the software using Microsoft Visual


Basic™.
• Some of the tools that can be used to create commands.
• Some of the user-definable methods of implementation, such as creating
commands.
• Examples of customization and workflows.

Visual Basic .NET™


The programming interfaces in SmartPlant 3D are subject to change as the software
moves to the .NET framework. Programmers should be aware that they may be
required to modify or rewrite their code to work with future versions of SmartPlant
3D software.

10 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Introduction

What's New in Programming Resources


This section directs your attention to enhancements, changes, or special notes for this
release of the software.

Version 2011

• Changes to the Share symbol path


{Product Directory}\RefData\SharedContent\bin\{component}

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 11


Software Architecture

Software Architecture
The software has an architecture that is component-oriented and built on three tiers.
The software makes extensive use of the Microsoft® Component Object Model, or
COM. The COM paradigm is deeply rooted in the idea of separating the interface of
an object from its data. Interface names, such as IUnknown, IDispatch, and so forth,
begin with the letter I by convention. Interfaces developed in the software always
begin with IJ, such as IJAppInfo. The J distinguishes interfaces from other sources
and reduces the risk of namespace collision.

Because the software is task-oriented, it uses one datastore. The datastore is the entity
that stores the data of the persistent business object instances. The term task-oriented
means that, rather than developers producing one large executable file or several
smaller ones, all the major functional subdivisions of the software are built as
separable COM objects. These "COMponents" are known as tasks. One datastore
means that all these separate tasks operate against a single underlying database.

12 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Software Architecture

Three-Tier Architecture
The three-tier architecture of the software includes the client, middle, and server tiers.
These tiers separate the graphical user interface, or GUI, stored in the client tier, from
the business logic in the middle tier. The business logic is further separated from the
physical database in the server tier.

The architecture emphasizes programming ease in producing functionality for the


client tier. The client tier mainly consists of commands, plus some components,
ActiveX controls, and services.

Client Tier
The client tier's functionality is loaded on user demand in the form of tasks, services,
and commands.

The client tier contains the menus, toolbars, views, dialog boxes, and frames. In the
client tier, you can manipulate the GUI with services, such as the SelectSet and
GraphicViewMgr, and with software-supplied components, such as Locators,
Highlighters, and View manipulations.

A set of commands make up each task in the client tier. Eighty to ninety percent of
the code in a task is written in the form of a command or to support a command.

Each task has its own COMponent called the EnvironmentMgr and an associated
XML file. This XML file defines the look and feel for the task and specifies the
services that it uses.

Services and other components support the commands and tasks by providing a set of
commonly-used functionalities. Services should respond to task switches. When a
task starts or ends, services are notified of the event to initialize or to clean up.

A service implements one or more service-specific interfaces. Generally, a service


wraps a specific bit of re-usable functionality. A service exists as a singleton, which is
the one and only instance of its class.

A service can persist its state in a session file when the session file is saved. The
SessionMgr, a service, coordinates this activity. When a session is saved,
SessionMgr checks each service to see if it supports an interface for persistence. If
the service does support an interface for persistence, then this interface is called to
allow the service to save persistent information. When the SessionMgr loads a
session file, the reverse happens - the SessionMgr first creates the service; then, if the
service can persist, SessionMgr calls the service to restore saved information.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 13


Software Architecture

For more information about session files, see the Managing Sessions: An Overview
section of the Common User's Guide.

Middle (Business) Tier


A task and its commands manipulate business objects. Business objects correspond to
real-world things such as pipes, pumps, tanks, hulls, decks, propellers, engines, and
so forth and they populate the middle tier.

Relationships define how business objects interact with each other. The following are
examples of this interaction:

• A pipe might need to be parallel to another pipe.


• A propeller might require an engine to exceed some threshold horsepower.
• A deck must maintain some minimum distance from the decks above and
below it.
Relationships are the software business rules. Relationships react to changes as they
take place, ensuring referential integrity and data consistency. Relationships and
business objects are closely tied to each other and the tasks that define and manipulate
them. A task or set of closely-related tasks defines business objects and relationships.

The RevisionMgr is a middle tier component that manages the associative


relationships between the objects and is the center of any engineering solution. This
service continuously keeps every entity consistent with all other data in the system.
This consistency is defined by the relationships of the entities.

The RevisionMgr works in cooperation with the business objects and relationships
by detecting changes to business objects. Using the relationships that business objects
are involved in, the RevisionMgr declares changes to any business objects defined as
outputs of the relationships. The RevisionMgr continues this promulgation until all
affected business objects are up-to-date.

The RevisionMgr notifies the TransactionMgr, a client tier service, after all
affected business objects have been modified. The TransactionMgr in turn notifies
any client tier services that are listening.

Server Tier
The server tier is made up of one or more physical datastores.

The server tier also provides storage for the metadata, which is contained in the
Repository. The Repository is the name of the location in which all the UML data is
saved. Metadata is the total description of all the classes, interfaces, relationships, and
semantics in the system.

14 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Software Architecture

The RevisionMgr service in the middle tier accesses this metadata.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 15


Getting Started

Getting Started
Before you begin customizing the software, you should be familiar with the
following:

• Microsoft Visual Basic (6.0 or greater) at an advanced level. C++ is not a


requirement.
• Basic understanding of the software functionality
• Basic understanding of the software architecture
• Basic understanding of relational databases
• Engineering and project knowledge

16 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Getting Started

Resources and References


The best source for programming reference information is contained in the
documentation and Help provided with your programming tool, such as the Visual
Basic Programmer's Guide. Microsoft Visual Basic provides plenty of helpful
programming information in the Microsoft Visual Basic Help Topics in the Microsoft
Developer Network Online. You can display this information by selecting from the
Help menu in Visual Basic.

You can also use any language of your choice that is OLE compliant such as C#,
C++, J++, Smalltalk, Fortran, Cobol, and so forth. However, examples and
documentation are provided in Visual Basic 6.0 format only.

For additional sources of documentation, online training, and code samples, you can
connect to the internet and download files or read to learn more. For example, you
can access information about the following:

• Microsoft Visual Basic


• Visual Basic Resource Index
• Microsoft Visual Studio Owners Area
• Microsoft Developer Network Online
• MSDN Library
• MacMillan InformIT and links to other VB sites
• Microsoft Multimedia Central, Online Seminars

Printed Documentation
• Hardcore Visual Basic, Microsoft Press. Also available from the MSDN
Library.
• Advanced Microsoft Visual Basic 6.0, Microsoft Press. Also available
from the MSDN Library.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 17


Debugging Your Code

Debugging Your Code


No matter how carefully you create your code, errors can occur. To handle these
errors, you need to add error-handling code to your procedures.

You perform the process of locating and fixing bugs in applications by debugging the
code. Visual Basic provides several tools to help analyze how your application
operates. These debugging tools are useful in locating the source of bugs, but you can
also use the tools to experiment with changes to your application or to learn how
other applications work.

Note: You must add the TaskHost project to the integrated development environment
(IDE) before you can debug your Visual Basic project.

Before you can use the TaskHost project, you must set new paths in your computer's
environment variables. Click Start > Settings > Control Panel > System. Select the
Advanced tab and then click Environment Variables. Finally add the following path
statements according to the location in which you installed the software:

PATH=[Product Directory]\Core\Runtime; [Product


Directory]\GeometryTopology\Runtime

18 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Debugging Your Code

Adding the TaskHost Project to your Project


1. Open your Visual Basic .vbp project to debug.
2. Click File > Add Project.
3. Select the Existing tab.
4. Open SP3DTaskHost.vbp in the following path: ..\Debug\Container\Src\Host
5. In the Project window, right-click over SP3DTaskHost and then select Set as
Start Up.
6. Right-click again on SP3DTaskHost and then select SP3DTaskHost
Properties...
7. On the Project Properties dialog, change the Project Type to Standard EXE.
8. Set the breakpoint in your project to debug.
9. Click Run and wait for processing to begin. Your Visual Basic project becomes
active when the breakpoint is reached.
10. Click to view <your project>, which returns you back to the code view. Then step
through your code.
Important

Do not stop the debug process by clicking the End command. If you end processing
this way, you will throw an exception, crash all the software that is running, and lose
your changes.

To safely end processing, click File > Exit from the SmartPlant 3D TaskHost
software.

For more specific information about using the TaskHost project and creating
commands using the software's application programming interface (API), please
contact Intergraph Services.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 19


Binding and Binary Compatibility

Binding and Binary Compatibility


One of the most important steps in Visual Basic programming is to preserve the
binary compatibility of your ActiveX components. You define whether the methods
and properties of your objects are exposed in the type library.

20 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Binding and Binary Compatibility

Early Binding
A client program can access this information at design time by statically binding to
the ClassID of the classes in the type library. This process is called "early binding".

The ClassID is a unique name given to each object class at compile time, representing
the status of the exposed methods and properties on the binary level. A binary-
compatible version of the type library retains the same ClassIDs, which indicates that
the binary footprint of all the methods and properties remains unchanged and
backward compatible.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 21


Binding and Binary Compatibility

Late Binding
If binary compatibility is not guaranteed, then the client program cannot statically
bind itself to the ClassID. Instead it must query the object at runtime to verify that it
continues to support the methods and properties required by the client. This
verification is called "late binding".

22 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Command Priorities

Command Priorities
When a command is started, it is assigned a priority, and (if successfully started) a
command ID is returned. Note that commands do not possess an intrinsic priority.
They are assigned one by the task that starts them. Thus, it is possible to start the
same command with different priorities in two different tasks. However, you should
avoid this practice unless there is a valid reason for this kind of implementation.

The command ID can be stored for subsequent use by issuing


IJCommandManager2.StopCommand. Otherwise, it can be ignored.

The priority is used to determine the stacking that can be done in conjunction with the
command. If the command being started is given a higher priority than the currently
active command, and the current command is suspendable (stackable), then the
current command is (suspended) stacked. If the current command is not suspendable,
or if its priority is equal to or less than the command being started, the current
command is stopped.

There are three possible priority values: Low, Normal, and High.

Caution:

• High priority commands can not commit or abort transactions.


• Normal priority commands can commit and abort transactions. They must
stop their transaction when they are stopped or when they fail (to leave the
system in a clean state).
• Low priority commands can use transactions. They must stop their
transaction when they are stopped, suspended, or when they fail.
If these rules are not respected, a higher priority command could potentially terminate
a transaction opened by a stacked (lower priority) command. The stacked command,
upon being resumed, would be in a highly indeterminate state.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 23


Error Handling

Error Handling
Trapping and resolving errors is one of those tasks that all developers must address. It
is important to remember several guidelines when you add code to your projects for
error handling.

• Never let an exception or error "escape" from a component.


For public methods and properties, always use: On Error GoTo
ErrHandler
• Return errors at the interface level as defined by the interface
• Provide a unique name for each error handler label in a procedure that will
not conflict with any other element in the procedure.
You should code your class modules to handle every error that occurs within that
module. You should also try to handle errors in the module that arise in an object
being referenced elsewhere, when the errors are not being handled by that object.

24 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Error Handling

Error Log Component


The error log component collects and stores errors in the software. However, it does
not replace standard error checking. It makes specialized error handling much easier.

This component provides dual error tracking for the software. It can assist when
trouble-shooting problems at a customer site as well as a debugging tool during
Visual Basic project development.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 25


Referencing Data Type Libraries

Referencing Data Type Libraries


The software consists of hundreds of type libraries that provide the programmatic
interfaces to the data model and its underlying data. These libraries consist of the
data model's interfaces and their methods and properties.

The ability to integrate user-definable components into the environment is a key


capability of the software. The mechanism of creating custom commands provides
this extensibility.

To reference the available type libraries in Visual Basic:

• Click Project > References.


To perform the task of referencing your type libraries more quickly and efficiently:

• Click Project > Speedy References.


For more information on using the Speedy References tool in Visual Basic, see Using
the References Tool, page 27.

26 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Referencing Data Type Libraries

Using the References Tool


The Speedy References tool is a very useful utility that you can use to locate and
reference type libraries quickly and easily. You only need to know the name of your
class object or variable in which to perform a search.
1. Open Visual Basic.
2. Click Add-Ins > Add-In Manager....
3. Select SP3D References and make sure that the Loaded/Unloaded and Load on
Startup boxes under Load Behavior are both checked.
4. Click OK.
5. Click Project > Speedy References to invoke the dialog.
If this is the first time that you have invoked the tool, it begins reading your system to
generate a data file that contains information about all existing registered type
libraries.

Enter a class or variable name to search - Text can be the complete name or the
first few letters of the item that you want to locate.

Find the typelib

• Click the Find button.


The time your search requires depends on how many type libraries can be found
containing your information, but it usually takes only a few seconds.

I-> Result

If your search finds a match, it returns an output dialog consisting of columns that
contain the member name, the type library's complete file path and name, and the
type library description.

Check/uncheck to reference or not the typelib - Allows you to automatically


reference a type library. Being able to reference a type library here saves valuable
time otherwise spent searching using the Project > References command.

Member - The class or variable name to be located in a type library.

Typelib Filename - Complete file path and name.

Typelib Description - Matches the name that you can find in Available References,
when you click Project > References.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 27


Referencing Data Type Libraries

Display Options

• Click to display a popup menu that provides two options: Exact Search
and Update Data.
Exact Search - Off by default and cannot be toggled on permanently. When it is
toggled off, and you enter IJCopy in the text box, the tool returns all references that
are related to this name. You must click Exact Search to return only the member
name IJCopy.

Update Data - Allows you to update your data file. When you update your system
with new or changed type libraries, you need to select this command to regenerate
your data file.

28 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Referencing Data Type Libraries

Errors Occurring with Visual Basic 6


Several errors can occur when using the Speedy References tool with Visual Basic 6;
however these errors can be resolved with ease.

• Speedy References can cause an error when Visual Basic 6 is launched.


This occurs because the tool attempts to add its command name under the
Project menu at the fifteenth position. If the menu has been modified and
doesn't contain at least fourteen items, restore the Project menu as
displayed by the following:

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 29


Referencing Data Type Libraries

• If you select the Project > Speedy References command, and it does not
display the utility, then the last screen position of the tool stored in the
Registry is out of the current screen resolution. To resolve this problem,
exit from all Visual Basic programs, and remove the following Registry
key:
HKEY_CURRENT_USER\Software\VB and VBA Program Settings\Speedy
References
This Registry key will be re-created when you start Visual Basic 6 again.

30 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Custom Commands

Creating Custom Commands


The software provides developers with the ability to extend the software by creating
custom commands. Using Visual Basic, you can create custom commands that group
a series of commands and instructions into a single command in the software. As a
result, you can have customized commands that have direct correlation to the routine
in your particular operation.

The Command Wizard and Speedy References tool are each very useful in creating
custom commands.

The Command Wizard and Speedy References tool are delivered as part of the
Programming Resources. Refer to the SmartPlant 3D Installation Guide for
information on installing the Programming Resources components.

The Command Wizard allows you to select relevant tools and methods for a new
Visual Basic project and build a basic command based on those selected
requirements.

The Speedy References tool allows you to locate and reference type libraries quickly
and easily. The ability to reference a type library with this tool saves valuable time
otherwise required when searching using the Project > References command in your
Visual Basic project.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 31


Creating Custom Commands

Undo Functionality
The TransactionManager service in the software provides the ability to perform
undo functionality in addition to other kinds of transaction notifications such as
commit, abort, or compute.

When you develop a custom command that requires undo functionality, be sure to
include a string in your project that serves as the marker for undo capability.
'////////////////////////////////
'Example of undo
'////////////////////////////////
Dim strPlacePipe As String
oTransaction.Commit(strPlacePipe)

32 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

Customizing the Software


The software provides you with the ability of extending its capabilities by
programming in Microsoft Visual Basic using certain aspects of the application
programming interface (API).

• ActiveX Components - You can create custom commands by referencing


available dynamic link libraries (DLLs) and run them by using the
Custom Commands command. For more information, see Using ActiveX
Components, page 34
• Naming Rules - Each task in the software that creates new parts in the
model automatically generates a name using defined rules. You can create
a custom name rule by creating a COM object that implements the
IJNameRule interface and adds the name rule to the catalog. For more
information, see Customizing Naming Rules, page 35
• Custom Supports - You can create a variety of support objects such as
Pipe, Duct, and Cable Tray supports by using available methods on the
IJHgrAutomation interface. For more information, see Customizing
Hangers and Supports, page 48
• Project Management - You can create a variety of Project Management
objects such as plants, folders, and permission groups by using available
methods on the IJHierarchy interface and the
ProjectMgmtEntitiesFactory component. For more information, see
Customizing Project Management, page 54
• Drawings - You can customize the software by using graphic wrappers to
assist in processing by the drawings generation process. Additionally, you
can customize automatic dimensioning rules by specifying values for
special XML tags. For more information, see Customizing Drawings, page
74

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 33


Customizing the Software

Using ActiveX Components


ActiveX code components are libraries of objects that can be used by client
components and are created as ActiveX dynamic link libraries (DLLs).

An interface serves as an abstract class or template, providing methods and properties


without any underlying implementation. As the foundation of COM, an interface can
be called an abstract data type, but it cannot be created as such. An interface
represents a contract through which a specific set of object behaviors can be invoked.

You can use an interface to create a reference to an object, but not the object itself.
An interface specifies the functionalities that are guaranteed by an object. One of the
advantages in using an interface is that it allows objects to grow without breaking
earlier functionality, as long as the objects continue to implement the original
interfaces.

The purpose of using interfaces is to encapsulate details (data layout) of the class's
implementation, instead of using data members, to which dependencies can be built.

Note: More than one class can implement the same interface.

Creating an Implementation
• Create an ActiveX project as a DLL.
• Reference the abstract class.
• Include the Implements keyword followed by the name of the abstract
class inside the implementation class module, as follows:
Option Explicit
Implements <Abstract_Class_Name>
• Implement your functions and properties of the abstract class in the new
class.

34 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

Customizing Naming Rules


Each task in the software that creates new parts in the model automatically generates
a name using defined naming rules. You can use Visual Basic to write your own
custom naming rules by creating COM objects that implement the IJNameRule
interface. Then you can add the naming rule to the Catalog database.

Note: An Excel workbook contains the naming rule definitions, which is provided so
that the naming rules can be loaded into the Catalog database. For information about
the workbook implementation, see the section titled Naming Rules Reference Data:
An Overview in the SmartPlant 3D Reference Data Guide or the SmartMarine 3D
Reference Data Guide available from the Help > Printable Guides command in the
software.

You can use the following COM objects to create new naming rules:

• NameGeneratorService
• NamingRulesHelper
• CNameRuleAE
The following sections define the minimal set of references that a custom naming rule
needs to have referenced in the Visual Basic project.

The GSCADNameRuleSemantics component provides interfaces, methods, and


properties in which to generate object names automatically. Names for these objects
are composed of a base name, object type, and index. To begin using this component,
reference the Ingr Sp3d Generic NameRuleSemantics 1.0 Type Library,
NameRuleSemantics.dll, in your Visual Basic project.

The GSCADNameGenerator component provides interfaces, methods, and


properties in which to return names and indexes as appropriate. To begin using this
component, reference the Ingr Sp3d NameGenerator 1.0 Type Library,
NameGenerator.dll, in your Visual Basic project.

Important: When creating naming rules or using labels as weld identifiers for
isometric drawings, there must not be any spaces generated in the identifier.

Object Interface Methods/Properties


Custom Name Rule IJNameRule GetNamingParents
ComputeName
CNameRuleAE IJNameRuleAE Frozen
NamingParentsString
NameGeneratorService IJNameCounter GetCount

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 35


Customizing the Software

GetCountEx
NamingRulesHelper IJDNamingRulesHelper AddNamingRelations
GetActiveNamingRule
GetEntityNamingRulesGivenName
GetEntityNamingRulesGivenProgID
IsGeneratedNameUnique

Custom Name Rule


The custom name rule is the new component to be created. This component
implements the IJNameRule interface, which has the GetNamingParents and
ComputeName methods.

IJNameRule Interface
The IJNameRule interface supports the naming rule implementation for the
GSCADNameRuleSemantics component. The IJNameRule interface is
implemented as the actual naming rule.

The GetNamingParents and ComputeName methods of the IJNameRule interface


allow you to implement generation of object names automatically.

The IJNameRule interface, which implements the naming rule, contrasts with the
IJDNameRuleHolder interface, which holds the naming rule name.

ComputeName Method
Description

This method computes the name for the given entity.

Signature

Function ComputeName(pEntity, pParents, pActiveEntity)

Important: When creating naming rules or using labels as weld identifiers for
isometric drawings, there must not be any spaces generated in the identifier.

Parameters Data Type Description


pEntity Object Required. The object to be named.

36 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

pParents IJElements Required. The naming parents collection.


pActiveEntity Object Required. Semantic Active Entity

GetNamingParents Method
Description

This method returns the naming parents from which the name should be derived.

Signature

Function GetNamingParents(pEntity) As IJElements

Parameters Data Type Description


pEntity Object Required. The new object to be named.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 37


Customizing the Software

CNameRuleAE Object
The CNameRuleAE object is the active entity for the name rule. An active entity
serves as the hub or management node for relationships in the software.

The relationship mechanism maintains data model consistency when entities are
modified, copied, or deleted. This mechanism maintains referential integrity when
entities are created, connected, or disconnected.

CNameRuleAE is a persistent object that has a relationship to the named object as


well as the naming parents. This object implements the IJNameRuleAE interface.

The CNameRuleAE object is created by the system and is passed to the Custom
Name Rule component.

IJNameRuleAE Interface
The IJNameRuleAE interface supports the naming rule implementation for the
GSCADNameRuleSemantics component.

This interface has two properties, Frozen and NamingParentsString.

Frozen Property
Description

This property returns whether the name of the object is frozen or not.

Signature

Frozen As Long

38 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

NamingParentsString Property
Description

This property returns the naming parents string, which contains the Base Name.

Signature

NamingParentsString As String

Important: When creating naming rules or using labels as weld identifiers for
isometric drawings, there must not be any spaces generated in the identifier.

Remarks

This string is returned after generating the name of an object. Then it is used with the
ComputeName method of the IJNameRule interface to decide whether there should
be a new index number created.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 39


Customizing the Software

NameGeneratorService Object
The NameGeneratorService class supports the naming rule implementation for the
GSCADNameGenerator component.

This class is the middle tier service that implements the IJNameCounter interface.

IJNameCounter Interface
The IJNameCounter interface supports the naming rule implementation for the
GSCADNameGenerator component.

The GetCount, GetCountEx, and GetCountRange methods of the IJNameCounter


interface provide a counter based on the base name. The base name is translated into a
moniker and resolved in the database.

40 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

GetCount Method
Description

This method returns a new index number when the NamingParentsString property
of the IJNameRuleAE interface and the current base name are different.

Signature

Function GetCount(pResourceManager, strBaseName) As Long

Parameters Data Description


Type
pResourceManager Unknown Required. The new object to be named.
strBaseName String Required. The name translated into a moniker and
resolved in the database.

Remarks

If the base name is found in the database, the counter is incremented by one. If not, a
new object is created and the count is returned as one.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 41


Customizing the Software

GetCountEx Method
Description

This method returns the count and the location prefix.

This method returns a new index number when the NamingParentsString property
of the IJNameRuleAE interface and the current base name are different.

Signature

Function GetCountEx(pResourceManager, strBaseName, strLocation) As Long

Parameters Data Description


Type
pResourceManager Unknown Required. The new object to be named.
strBaseName String Required. The name translated into a moniker and
resolved in the database.
strLocation String Required. The specified area at the site containing
the databases.

Remarks

If the base name is found in the database, the counter is incremented by one. If not, a
new object is created and the count is returned as one.

42 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

GetCountRange Method
Description

The GetCountRange method returns a unique index to a counter based on the base
name and an option to customize the user range.

This method is similar to the GetCountEx method except that the user range received
from the COM server can be customized. To reduce gaps between numbers, a lesser
value than ten (default) can be passed in for user range. If less than ten is entered,
more DCOM calls will be made to the COM server, which impacts performance.

Signature

Function GetCountRange(pResourceManager, strBaseName, strLocation,


userRange) As Long

Parameters Data Description


Type
pResourceManager Unknown Required. The new object to be named.
strBaseName String Required. The name translated into a moniker and
resolved in the database.
strLocation String Required. The name of the location.
userRange Long Required. The user range - default = 10. Lower
values reduce the gaps. Range should be less than
range at the COM server.

Remarks

Error Codes

S_OK = operation succeeded

E_INVALIDARG = invalid argument passed in

E_UNEXPECTED = unexpected exception occurred during execution

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 43


Customizing the Software

NamingRulesHelper Object
The NamingRulesHelper object is the middle tier service that implements the
IJDNamingRulesHelper interface.

IJDNamingRulesHelper Interface
The IJDNamingRulesHelper interface is used by commands to associate a business
object to a name rule and to determine if a name is unique.

The GetEntityNamingRulesGivenName, GetEntityNamingRulesGivenProgID,


AddNamingRelations, GetActiveNamingRule, and IsGeneratedNameUnique
methods of the IJDNamingRulesHelper interface provide the ability for commands
to get naming rules, to add naming relations, and to get the active naming rule to be
used for naming the object.

The IsGeneratedNameUnique method is typically used by a custom name rule to


verify that the name is unique. It is typically only used when one of the methods on
the IJNameRuleCounter interface is not used to return a unique counter for a name.

The other methods listed are used by commands that are assigning a name rule to an
object or getting a list of name rules for a specific object type.

44 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

AddNamingRelations Method
Description

This method adds naming relations after creating the active entity and returns a
reference to the IJNameRuleAE interface of the active entity object created. The
method deletes the active entity if it is there before creating the new one so it can also
be used to delete the relations. If nothing is sent as the pNameRuleHolder argument,
the method deletes the existing relations.

Signature

Function AddNamingRelations(pDispEntity, pNameRuleHolder, pActiveEntity)

Parameters Data Type Description


pDispEntity Object Required. The new object to be named.
pNameRuleHolder IJDNameRuleHolder Required. The interface of the naming
rule.
pActiveEntity IJNameRuleAE Required. The interface of the active
entity object.

GetActiveNamingRule Method
Description

This method returns a reference to the IJDNameRuleHolder interface of the active


naming rule that is being used for naming the input object. The pNameRuleHolder
argument returns nothing if there are no active naming rules on the object.

Signature

Function GetActiveNamingRule(pDispEntity, pNameRuleHolder)

Parameters Data Type Description


pDispEntity Object Required. The new object to be named.
pNameRuleHolder IJDNameRuleHolder Required. The interface of the naming
rule.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 45


Customizing the Software

GetEntityNamingRulesGivenName Method
Description

This method returns a reference to the IJElements interface of the first object in a
collection of the naming rules. These rules are available in the Catalog database for
the given object name input.

Signature

Function GetEntityNamingRulesGivenName(strEntityName, NamingRules)

Important: When creating naming rules or using labels as weld identifiers for
isometric drawings, there must not be any spaces generated in the identifier.

Parameters Data Type Description


strEntityName String Required. The new object's name.
NamingRules IJElements Required. The interface of the first object in the
collection.

GetEntityNamingRulesGivenProgID Method
Description

This method returns a reference to the IJElements interface of the first object in a
collection of the naming rules. These rules are available in the Catalog database for
the given class ProgID input.

Signature

Function GetEntityNamingRulesGivenProgID(strEntityProgID, NamingRules)

Parameters Data Type Description


strEntityProgID String Required. The ProgID of the new object to be named.
NamingRules IJElements Required. The interface of the first object in the
collection.

46 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

IsGeneratedNameUnique Method
Description

The IsGeneratedNameUnique method returns a Boolean specifying whether the


new name is unique in the domain specified by the given oFilter parameter. The
name is unique if the method returns True.

Signature

Function IsGeneratedNameUnique(oEntity, oFilter, strGenName, [strIID],


[strAttributeName]) As Boolean

Important: When creating naming rules or using labels as weld identifiers for
isometric drawings, there must not be any spaces generated in the identifier.

Parameters Data Type Description


oEntity Object Required. The new object to be named.
oFilter IJSimpleFilter Required. The interface of the Filter to use in
determining the uniqueness.
strGenName String Required. The generated name string.
strIID String Optional. An IID as a string to help in making
the determination. If the IID is provided then
strAttributeName must be provided. The default
is a null string.
strAttributeName String Optional. An AttributeName as a string to help
in making the determination. The default is a null
string.

Remarks

This method is typically used by a custom name rule to verify that the name is
unique. It is typically only used when one of the methods on the
IJNameRuleCounter interface is not used to return a unique counter for a name.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 47


Customizing the Software

Customizing Hangers and Supports


The HgrSupProgAutoComp component provides the following methods in which to
create different types of support objects such as pipe, duct, and cable tray supports.

Object/Interface Methods
IJHgrAutomation CreateSupport
ModifySupport

Before using the HgrSupProgAutoComp component, a connection to the data store


must be established. This connection is made by starting the services of the Session
Manager, Transaction Manager, and Command Manager.

To begin using this component, reference HgrSupProgAutoComp.dll in the Visual


Basic project.

IJHgrAutomation Interface
The IJHgrAutomation interface supports the creation and modification functionality
for the HgrSupProgAutoComp component.

The CreateSupport and ModifySupport methods of the IJHgrAutomation


interface allow you to create and modify support objects such as pipes, ducts, and
cable trays.

CreateSupport Method
CreateSupport Method Example, page 53

Description

This method creates the support object.

Signature

Function CreateSupport(eHgrDisciplineType, [oParent], [dblMaxLoad],


[oSupportedObjects], [oSupportingObjects], [oLocation], [bRule],
[oSupportAssembly], [strSupportName], [strSupportRuleName]) As Object

48 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

Parameters Data Type Description


eHgrDisciplineType HgrDisciplineType Required. The discipline type of the
support that is being created:
HgrPipingDisciplineType = 1
HgrHVACDisciplineType = 2
HgrPipingHVACDisciplineType = 3
HgrCableWayDisciplineType = 4
HgrCableWayPipingDisciplineType = 5
HgrCableWayDuctDisciplineType = 6
HgrCableWayPipingDuctDisciplineType
=7
HgrConduitDisciplineType = 8
HgrConduitPipingDisciplineType = 9
HgrConduitDuctDisciplineType = 10
HgrConduitPipingDuctDisciplineType =
11
HgrConduitCableWayDisciplineType =
12
HgrEquipmentDisciplineType = 16
HgrCombinedDisciplineType = 256
HgrAllDisciplineType = 511
oParent Object Optional. The parent for the support.
dblMaxLoad Double Optional. The maximum load a support
can carry.
oSupportedObjects Object Optional. The supported object collection
for the support.
oSupportingObjects Object Optional. The supporting object
collection for the support.
oLocation Object Optional. The location of the support by
point case.
bRule Boolean Optional. The flag to indicate whether to
run the assembly selection rule.
oSupportAssembly Object Optional. The support assembly for the
support.
strSupportName String Optional. The name of the support.
strSupportRuleName String Optional. The naming rule for the
support.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 49


Customizing the Software

Remarks

If bRule and oSupportAssembly are specified, then the support assembly is considered
only when the rule fails. If strSupportName and strSupportRuleName are given, then
strSupportName is ignored.

50 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

ModifySupport Method
Description

This method modifies the support object.

Signature

Function ModifySupport(oSupport, [oParent], [dblMaxLoad], [oSupportedObjects],


[oSupportingObjects], [oLocation], [bRule], [oSupportAssembly], [strSupportName],
[strSupportRuleName]) As Object

Parameters Data Type Description


oSupport IJHgrSupport Required. The support that is being modified.
oParent Object Optional. The parent for the support.
dblMaxLoad Double Optional. The maximum load a support can
carry.
oSupportedObjects Object Optional. The supported object collection for
the support.
oSupportingObjects Object Optional. The supporting object collection for
the support.
oLocation Object Optional. The location of the support by point
case.
bRule Boolean Optional. The flag to indicate whether to run
the assembly selection rule.
oSupportAssembly Object Optional. The support assembly for the
support.
strSupportName String Optional. The name of the support.
strSupportRuleName String Optional. The naming rule for the support.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 51


Customizing the Software

Remarks

If bRule and oSupportAssembly are specified, then the support assembly is considered
only when the rule fails. If strSupportName and strSupportRuleName are given, then
strSupportName is ignored.

52 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

CreateSupport Method Example


For more specific information about using the IJHgrSupport interface and the application
programming interface (API), please contact Intergraph Services.
'/////////////////////////////////////////////////////////////////////////
Dim oHgrAutomation As IJHgrAutomation
Dim oHgrSupport As IJHgrSupport

Set oHgrAutomation = New HgrSupProgAutoComp.ProgAutoComp

'/////////////////////////////////////////////////////////////////////////
'// System, supported objects, supporting objects, and support assembly
'// to be supplied by user.
'////////////////////////////////////////////////////////////////////////
Set oHgrSupport = oHgrAutomation.CreateSupport(1, oSystem, 10#,
SupportedList, _
SupportingList, Nothing, True, oSupportAssembly, "Automation")
- - - -
- - - -
- - - -
- - - -
'/////////////////////////////////////////////////////////////////////////
'// Set the maximum load for the support with the MaxLoad method
'////////////////////////////////////////////////////////////////////////

oHgrSupport.MaxLoad = 10.0

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 53


Customizing the Software

Customizing Project Management


The following objects and methods allow you to create Project Management objects
using Automation such as plants/ships, folders, and permission groups. The
ProjectMgmtEntitiesFactory object and IJHierarchy and
IJBackupRestoreHelper interfaces are accessed by referencing the Ingr Sp3d
ProjectMgmtEntities 1.0 Type Library.

Object/Interface Methods
ProjectMgmtEntitiesFactory AddLocation
AttachPDSProject
CreateProjectRoot
CreateModelDatabaseObject
CreateCatalogDatabaseObject
CreateFolder
CreatePermissionGroup
CreateAccessControlRule
CreateReportsDatabaseObject
CreateDBObject
GetNameGeneratorServerPath
GetPDSSite
ValidateNameServer

In addition to creating objects, the following methods of the IJHierarchy interface


allow you to return the collection of plant/ship objects and, given a plant/ship object,
to traverse the project folders and permission groups.

IJHierarchy GetDisplayChildren
Parent

In addition to creating objects, the following method of the IJAccessRuleHelper


interface allows you to add access control rules by returning the
IJAccessControlRule interface. This interface is accessed by referencing the Ingr
SP3D ProjMgmt 1.0 Type Library.

IJAccessRuleHelper AddAccessControlRule

The following methods on the IJBackupRestoreHelper interface allow you to


perform validated backup and restore functionality.

54 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

IJBackupRestoreHelper BackupPlantDatabases
RestorePlantDatabases

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 55


Customizing the Software

ProjectMgmtEntitiesFactory Object
The ProjectMgmtEntitiesFactory object provides the methods in which to create
objects such as Plant/Ship, Folder, Permission Group, Access Control Rule, and
so forth.

Before using the ProjectMgmtEntitiesFactory object, a connection to the data store


must be established. This connection is made by starting the services of the Session
Manager, Transaction Manager, and Command Manager.

To begin using this object, reference Ingr Sp3d ProjectMgmtEntities 1.0 Type
Library, ProjectMgmtEntities.dll, in the Visual Basic project.
'///////////////////////////////////////////////////
'// Example using ProjectMgmtEntitiesFactory object
'///////////////////////////////////////////////////////////////////
Dim oProjectMgmtEntitiesFactory As IJProjectMgmtEntitiesFactory
Set oProjectMgmtEntitiesFactory = New ProjectMgmtEntitiesFactory

56 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

AddLocation Method
Description

The method creates a Location object.

Signature

Function AddLocation(pResourceManager As Unknown) As Object

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Project
connection for adding access control rules in the
case of project root and database. For adding rules
for permission groups, this should be defined for
Model or Catalog connections depending on the
location of the permission group under the model or
the catalog.

Remarks

You must define the project connection as the active connection on the WorkingSet.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 57


Customizing the Software

AttachPDSProject Method
Description

This method references a PDS project (Model) to the selected model (Plant/Ship).

Signature

Function AttachPDSProject(pResourceManager, pIJDProjectRoot, pIJLocation,


PDSDBName) As Object

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Model or
Catalog connection depending on whether created
under plant/ship or catalog
pIJDProjectRoot Unknown Required. Plant/Ship or Project Root object
pIJLocation Location Optional. Can be NULL.
PDSDBName String Required. PDS Project name

Remarks

You must set the permission group ID of the Project Root = active condition ID and
the project connection = active connection on the WorkingSet. There can be only one
PDS project attached (referenced) to a plant/ship.

58 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

CreateProjectRoot Method
Description

This method creates the Plant/Ship object.

Signature

Function CreateProjectRoot(pResourceManager, pIJLocation) As Object

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Project
Connection
pIJLocation Location Required. The specified area at the site containing
the databases.

Remarks

You must define the project connection = active connection and the condition ID on
the WorkingSet = "8" (PROJMGMT_PERMISSIONID).

Error Codes

E_ACCESSDENIED = -2147024891

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 59


Customizing the Software

CreateModelDatabaseObject Method
Description

This method creates the Model database object.

Signature

Function CreateModelDatabaseObject(pResourceManager, pIJDProjectRootUnk,


pIJLocation, strDatabaseProviderType, schema, server, physDbName,
[bIsDatabaseInitialised]) As Object

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Model or
Catalog connection depending on whether
created under plant or catalog
pIJDProjectRootUnk Unknown Required. Plant/Ship or Project Root object
pIJLocation Location Required. The specified area at the site
containing the databases.
strDatabaseProviderType String Required. The database provider type
schema String Required. Schema connection string
server String Required. Server name
blsDatabaseInitialised Boolean Optional. Default = True

Remarks

You must define the project connection = active connection on the WorkingSet.

Error Codes

lDISK_NO_SPACE = -2147216355

E_ACCESSDENIED = -2147024891

60 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

CreateCatalogDatabaseObject Method
Description

This method creates the Catalog database object.

Signature

Function CreateCatalogDatabaseObject(pResourceManager, pIJDProjectRoot,


pIJLocation, strDatabaseProviderType, physDbName, server,
strSchemaDatabaseName, strSchemaServerName) As Object

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Project
Connection
pIJDProjectRoot Unknown Required. Plant/Ship or Project Root object
pIJLocation Location Required. The specified area at the site
containing the databases.
strDatabaseProviderType String Required. The database provider type.
physDbName String Required. Actual database name
server String Required. Server name
strSchemaDatabaseName String Required. Schema database name
strSchemaServerName String Required. Schema server name

Remarks

You must define the project connection = active connection on the WorkingSet.

Error Codes

E_ACCESSDENIED = -2147024891

CreateFolder Method
Description

This method creates the Folder object.

Signature

Function CreateFolder(pResourceManager, pParentFolder) As Object

Parameters Data Description


Type

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 61


Customizing the Software

pResourceManager Unknown Required. Resource Manager of the Model or


Catalog connection depending on whether created
under plant or catalog
pParentFolder IJFolder Required. Folder Parent object

Remarks

You must define the active connection on the WorkingSet as follows:

• Creating Folder under Model (Plant/Ship) = Model connection


• Creating Folder under Catalog = Catalog connection
The condition ID of the plant or catalog under which the folder is created should be
set as the active condition ID on the WorkingSet.

If the folder is created under another folder, the Input folder parent object should be
set = "Nothing".

Error Codes

E_INVALIDHIERARCHY = -2147220224

E_ACCESSDENIED = -2147024891

CreatePermissionGroup Method
Description

This method creates the Permission Group object.

Signature

Function CreatePermissionGroup(pResourceManager, pFolder, pIJLocation) As


Object

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Model or
Catalog connection depending on whether created
under plant/ship or catalog
pFolder IJFolder Required. Folder object
pIJLocation Location Required. The specified area at the site containing
the databases.

Remarks

62 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

You must define the active connection on the WorkingSet as follows:

• Creating Folder under Model (Plant/Ship) = Model connection


• Creating Folder under Catalog = Catalog connection
The condition ID of the plant/ship or catalog under which the folder is created should
be set as the active condition ID on the WorkingSet.

You must define the project connection = active connection on the WorkingSet.

Error Codes

E_INVALIDHIERARCHY = -2147220224

E_ACCESSDENIED = -2147024891

CreateAccessControlRule Method
Description

This method creates the Access Control Rule object.

Signature

Function CreateAccessControlRule(pResourceManager) As Object

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Project
connection for adding access control rules on the
Plant/Ship or Catalog. For creating rules for
permission groups, this should be defined for Model
or Catalog depending on the location of the
permission group. If permission group is under
Model/Catalog database, then that type of
connection is required.

Remarks

You must define the active connection on the WorkingSet as follows:

• For Plant/Ship or Catalog objects = Project connection


• For Permission Groups under Model/Catalog = Model/Catalog connection
Note: Default permissions should be defined after the Access Control Rule objects
are created for the Plant/Ship or Catalog. There should be at least one user defined
with "Full Control".

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 63


Customizing the Software

Error Codes

E_ACCESSDENIED = -2147024891

CreateReportsDatabaseObject Method
Description

This method creates the Reports database object.

Signature

Function CreateReportsDatabaseObject(pResourceManager, pIJDProjectRoot,


pIJLocation, ReportDbName, DatabaseServer, SchemaName, SchemaServer) As
Object

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Project
Connection
pIJDProjectRoot Unknown Required. Plant/Ship or Project Root object
pIJLocation Location Required. The specified area at the site containing
the databases.
ReportDbName String Required. Reports database name
DatabaseServer String Required. Reports database server name
SchemaName String Required. Reports schema name
SchemaServer String Required. Reports schema server name

Remarks

You must define the project connection = active connection on the WorkingSet.

Error Codes

lDISK_NO_SPACE = -2147216355

E_ACCESSDENIED = -2147024891

64 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

IJHierarchy Interface
In addition to creating objects, GetDisplayChildren and GetParent methods of the
IJHierarchy interface allow you to return the collection of plant objects and, given a plant
object, to traverse the project folders and permission groups.

The classes that implement the IJHierarchy interface are ProjectCollection, ProjectRoot,
Database, Folder and PermissionGroup classes respectively.
'/////////////////////////////////////////////////////////////////////////
'// Example using methods of IJHierarchy and the ProjectCollection object.
'// Similarly, use the GetParent method to return the parent.
'///////////////////////////////////////////////////////////////////////
Dim oProjectsColl as IJProjectsCollection
Set oProjectsColl = oProjMgmtfactory. GetProjectsCollectionObject _
(oConnection.ResourceManager)
Dim oHierarchy As IJHierarchy
Set oHierarchy = oProjectsColl
Dim oChildren as IJDObjectCollection

Set oChildren = oHierarchy.GetDisplayChildren(oConnection.ResourceManager)

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 65


Customizing the Software

GetDisplayChildren Method
Description

This method returns the children of the object.

Signature

Function GetDisplayChildren(pResourceManager) As IJDObjectCollection

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the
Project/Model/Catalog connection, depending on
the object that is used

Remarks

You must input the connection resource managers as follows:

Project Collection For Project connection


Project Root For Model connection
Catalog Database For Catalog connection
Folder Under a Plant/Ship - For Model connection
Under a Catalog - For Catalog connection
Permission Group Under a Plant/Ship - For Model connection
Under a Catalog - For Catalog connection

Parent Property
Description

This property returns the parent of the object.

Signature

Parent As Object

IJAccessRuleHelper Interface
The IJAccessRuleHelper interface provides the means for access control rules to be
added.

66 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

AddAccessControlRule Method
Description

The method returns the access control rule as IJAccessControlRule.

Signature

Function AddAccessControlRule(pResourceManager As Unknown, strUserName


As String, strAccessRight As String, [IsCurrentUser As Boolean = False]) As
IJAccessControlRule

Parameters Data Description


Type
pResourceManager Unknown Required. Resource Manager of the Project
connection for adding access control rules in the
case of project root and database. For adding rules
for permission groups, this should be defined for
Model or Catalog connections depending on the
location of the permission group under the model or
the catalog.
strUserName String Required. If IsCurrentUser = True, define = NULL.
strAccessRight String Required. If IsCurrentUser = True, define = NULL.
IsCurrentUser Boolean Optional. Default value = False. If True, define
strUserName and strAccessRight = NULL.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 67


Customizing the Software

Remarks
'/////////////////////////////////////////////////////////////////////////
' Example for current user
'/////////////////////////////////////////////////////////////////////////
Dim oAccessRuleHelper As IJAccessRuleHelper
Set oAccessRuleHelper = ( ProjectRoot, database, or a permission group)
Call oAccessRuleHelper.AddAccessControlRule(oWorkingset.ActiveConnection. _
ResourceManager, vbNullString, vbNullString, True)

'/////////////////////////////////////////////////////////////////////////
' Example for other user
'/////////////////////////////////////////////////////////////////////////
Dim oAccessRuleHelper As IJAccessRuleHelper
Set oAccessRuleHelper = ( ProjectRoot, database, or a permission group)
Set oAccessRul =
oAccessRuleHelper.AddAccessControlRule(oConnection.ResourceManager,
strRole, strRight, False)

68 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

IJBackupRestoreHelper Interface
Backup and restore functionality for Project Management is exposed on the interface
IJBackupRestoreHelper, accessed by referencing the ProjectMgmtEntities.dll type
library.

Validation and Error Handling

Any errors or problems during backup and restore will be written to a log file.

All inputs will be validated. If there are invalid inputs, the error values will be either
E_INVALID_BACKUPUINPUT (-2147219456)
or E_INVALID_RESTOREUNINPUT (-2147219455), including a description.

Other problems, such as errors in deleting log files where backup configuration files
exist with the same names at the specified location, can occur with an error value of
E_FILEACCESSERROR (=75).

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 69


Customizing the Software

BackupPlantDatabases Method
Description

This method will backup specified databases.

Note: The site database and site server name entries need to be updated in the
Registry.

Signature

Function BackupPlantDatabases(ppastrPlantNames(), strServerName,


strDatabaseFileLocation, strBCFFileLocation, strLogFileLocation)

Parameters Data Description


Type
ppastrPlantNames() String Required. Array of plant names to be backed up.
The plant should be among the plants in the site
database.
strServerName String Required. Server name to which the databases
need be Backed up.
strDatabaseFileLocation String Required. Location where the .dat files are to be
stored.
strBCFFileLocation String Required. Backup configuration file name and
location.
strLogFileLocation String Required. Log file name and location. If the log
file is sent as an empty string, then it is generated
internally.

BackupRestoreErrorConstants

E_INVALID_BACKUPUINPUT
E_INVALID_RESTOREUINPUT
'//////////////////////////////////////////////////////////////////////
'// Example using BackupPlantDatabases method of IJBackupRestoreHelper.
'//////////////////////////////////////////////////////////////////////
Dim oBackupRestoreHelper As IJBackupRestoreHelperDim arrPlantNames() As
StringDim iArrayIndex As IntegerSet oBackupRestoreHelper = New
BackupRestoreHelperIArrayIndex = 0ReDim Preserve arrPlantNames(0 To
iArrayIndex) As StringarrPlantNames (iArrayIndex) = "rlakkaraPlant"
Call oBackupRestoreHelper. BackupPlantDatabases (arrPlantNames (),
"GSCAD1", "E:\Backup\TestFolder",
"E:\Backup\rlakkaraPlant1.bcf","E:\Backup\rlakkaraPlant1Backup.log")

70 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

RestorePlantDatabases Method
Description

This method can restore the databases of only plant at a time. You can restore the
catalog & model databases at the same time or individually depending upon the
ProjectManagementRestoreOptions definition.

Signature

Function RestorePlantDatabases(strCatalogServerName,
strCatalogDBDataFileLocation, strCatalogDBLogFileLocation,
strModelServerName, strModelDBDataFileLocation, strModelDBLogFileLocation,
strSymbolFileLocation, eRestoreOption)

Parameters Data Type Description


strPlantName String Required.
Name of the
plant name
whose model
and catalog
databases
need to be
restored.
strDatabaseFileLocation String Required.
Location of
the backup
.dat files
from which
the databases
are restored.
strBCFFileLocation String Required.
Backup
configuratio
n file name
and location.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 71


Customizing the Software

strLogFileLocation String Required.


Log file
name and
location. If
the log file is
sent as an
empty string,
it will be
generated
internally.
strCatalogServerName String Required.
Catalog
server name.
strCatalogDBDataFileLocatio String Required.
n Catalog
database
.mdf file
location.
strCatalogDBLogFileLocation String Required.
Catalog
database .ldf
file location.
strModelServerName String Required.
Model server
name.
strModelDBDataFileLocation String Required.
Model
database
.mdf file
location.
strModelDBLogFileLocation String Required.
Model
database ,ldf
file location.
strSymbolFileLocation String Required.
Symbol files
folder
location.
eRestoreOption ProjectManagementRestoreOption Required.
s Restore
options.

72 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

ProjectManagementRestoreOptions

RESTOREDBTYPE_MODEL
RESTOREDBTYPE_CATALOG
RESTOREDBTYPE_BOTH

BackupRestoreErrorConstants

E_INVALID_BACKUPUINPUT
E_INVALID_RESTOREUINPUT
'/////////////////////////////////////////////////////////////////////////
'// Example using RestorePlantDatabases method of IJBackupRestoreHelper.
'///////////////////////////////////////////////////////////////////////
Dim oBackupRestoreHelper As IJBackupRestoreHelperSet oBackupRestoreHelper =
New BackupRestoreHelper Call oBackupRestoreHelper. RestorePlantDatabases
("rlakkaraPlant", "E:\Backup\TestFolder", _
"E:\Backup\rlakkaraPlant1.bcf", "", "GSCAD1", "E:\datafiles", _
"E:\datafiles", "GSCAD1", "E:\datafiles", "E:\datafiles", _
"M:\CatalogData\Symbols", RESTOREDBTYPE_BOTH)

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 73


Customizing the Software

Customizing Drawings
Annotations are generated in the software by applying a set of annotation templates
against a set of 3D objects.

Drawings Package Versioning describes the new versioning attribute.

Graphic Wrapper Modules can be used to assist in processing by determining what


should be processed, and how the object should be processed by the drawings
generation process.

The Drawings Label and Dimensions XML Reference provides information to


developers who want to customize automatic dimensioning rules or labels and
generate reports.

74 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

Package Versioning
A Drawings Package is an XML file that contains data about a snap-in drawing or a
hierarchy of snap-ins. The package contains information that allows the software to
create the same type of objects and set properties from the time the package was
saved.

As Drawings Packages evolve, it is important to know the software version in which


they were created. This means that you are alerted to whether the data in the packages
needs to be modified to support a different version of software from which it was
created.

Packages are currently stored on the symbol share. You might restore a copy of
packages from another location containing data in an old format after migration has
occurred. The <package version=" "> attribute assists detection of old file formatting.

In the following example, the version attribute means that the package was created
with the v7.0 software of that it was migrated to the v7.0 schema.

<?xml version="1.0" encoding="utf-8"?>


<package version=”7.0.0.0”>
<snapin clsid="{AF2EE992-B592-11D4-8B30-0050DA23CBE0}"/>
<pkginfo foldername="Folder">
<progid progid="DataForPackages.cSnapInPackageData">
<name id="genericname"/>
<description id="genericdescription"/>
<tab id="generaltab"/>
<icon id="generic"/>
</progid>
<categories>
<type><![CDATA[folder]]></type>
<type><![CDATA[all]]></type>
</categories>
</pkginfo>
</package>

Note: All existing packages need to be modified to contain the version attribute. For
packages created in v6.1 of the software to be delivered for v7.0, this attribute will
need to be added manually.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 75


Customizing the Software

Using the Graphic Wrapper Modules


A Graphic Wrapper Module assists the processing of a particular object by the
drawings generation process. Processing is primarily concerned with two actions:

• Determines what is processed.


Instead of processing a piece of equipment as a whole, the equipment can be
separated into sub-pieces. For example, a storage tank as delivered processes all
of its components as one. That means that you cannot separate the nozzles from
the tank itself. With a graphic wrapper module, the drawing generation process
passes in the piece of equipment, and the module decides how it should be
processed. In this case, the module might return the nozzles as separate objects
along with the tank so that they can be processed separately. With this kind of
flexibility, you can decide whether to make the nozzles a separate color or
whether to label and dimension the nozzles themselves.

• Determines how the object is processed.


The generation process performs the work in the module instead of on the actual
business object. The business object is passed to the graphic wrapper. So the
module is the object that returns the graphics to be processed for that object.
Instead of processing the full pipe, the module can calculate and process the
center line representation of that pipe.

Children
When creating a graphic wrapper, you should consider whether it has any children. A
graphic wrapper without children simply encapsulates the original object, changing
some (graphic) property. A graphic wrapper with children is usually used to separate
an object into individual components. In the latter case, there can be several extra
objects, to which you can apply separate view styles.

Requirements
A Graphic Wrapper Module must implement IJDwgExternalModule interface.
Other interfaces that can be included are IJDwgWrapperCompound,
IJDwgWrapperPseudoFilter, IJGraphicEntity, or IJGraphicCompound.

All delivered modules are located in the bin directory of the following path on your
system: ..\Drawings\Symbols\DrawingsWrappers\bin. See the "Use Cases" section
for information about using these DLLs.

During software installation, all symbols are located under the top-level \CatalogData
directory. This directory serves as the symbols share for the model. Symbols must be
in a common folder so that the View Style Manager has a single location in which to
search when view styles are created, loaded, or used.

76 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

IJDwgExternalModule
The IJDwgExternalModule interface is used by the director and the action analyzer
to set the inner IUnknown of the graphic wrapper (the original business object being
"wrapped") and to pass some view information to the wrapper. The view information
is passed to the wrapper in case it needs to alter the graphic representation of the
original object. All graphic wrapper objects should implement this interface.

Properties
Name and Syntax Description Parameters
ViewDirection This passes to or retrieves from the pVec - pointer to a vector
( wrapper the view vector of the view representing the view
[put, get] being processed. direction.
IJDVector* pVec
)

UpDirection This passes to or retrieves from the wrapper pVec - pointer to a


( the up vector of the view being processed; vector representing
[put, get] that is, the 3D vector determining the the up direction.
IJDVector* positive y-axis of the view plane.
pVec
)

ScaleFactor This passes to or retrieves from the wrapper the dScale - the
( scale vector of the view being processed. view scale.
[put, get] double
dScale
)

Methods
Name and Syntax Description Parameters
SetInnerUnk This is called on the wrapper to set pInnerUnk - the
( its aggregate - the original object IUnknown of the
[in] IUNknown* being wrapped. original object.
pInnerUnk
)

GetInnerUnk This is called on the wrapper to ppInnerUnk - the


( return its aggregate - the original IUnknown of the
[out, retval] object being wrapped. original object.
IUnknown**
ppInnerUnk
)

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 77


Customizing the Software

IJDwgWrapperCompound
The IJDwgWrapperCompound interface is used by the director to return the
children of a compound wrapper object. Compound wrapper objects are used to
replace the original object with several new objects. Each one of the new objects
(children) is processed separately and independently by the drawings engine, and
therefore different graphic, label, and dimension rules can be applied to them.

Any graphic wrapper object with child elements (an object with components) should
implement this interface.

Methods
Name and Syntax Description Parameters
EnumerateEntities This is called to obtain ppEnumChildElements -
( the child elements of a pointer to the collection of
[out, retval] compound graphic child elements.
IEnumUnknown** wrapper object.
ppEnumChildElements
)

IJDwgWrapperPseudoFilter
The IJDwgWrapperPseudoFilter interface is used by the director to pass the name
of the filter to the wrapper for which it was applied. This filter name is taken from the
Graphic Preparation Rule selected for the particular view style.

This interface is also used by the Request Service. When testing an object to see if it
meets a certain filter, the Request Service first checks whether the object supports
IJDwgWrapperPseudoFilter. If so, it checks the name of the filter against the
values from IJDwgWrapperPseudoFilter::Filter and
IJDwgWrapperPseudoFilter::SubFilter.

The interface can also be used by a compound wrapper object to pass filter
information to its children.

Implement this interface when any wrapper object needs to preserve a filter name. A
most likely case - by simply delegating to the inner IUnknown of the wrapper, the
filter name cannot be matched to the correct filter. Also, all children of compound
wrappers for which separate view styles can be applied should implement this
interface. Those children are referenced in the Filter column of the View Style
Manager by Filter Name:: SubFilter Name (e.g. Equipment::Nozzles).

78 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Customizing the Software

Properties
Name and Description Parameters
Syntax
Filter This sets and returns the name of the filter bstrFilter - the name
( to which the wrapper should match. of the filter.
[put, get] BSTR
bstrFilter
)

SubFilter This sets and returns the name of the subfilter to bstrSubFilter -
( which the wrapper should match. Subfilters are the name of the
[put, get] strings used in conjunction with a filter name to subfilter.
BSTR further differentiate subcomponents of a compound
bstrSubFilter wrapper.
)
Note: To apply a special label rule for just nozzles
of a piece of equipment, apply
EquipmentNozzleSeparator.dll wrapper for objects
in the filter Catalog Filters\Equipment in the
Graphic Preparation Module section of the view
style dialog. It is assumes that a filter has been
created for all equipment named Equipment under
the Catalog Filters folder. In a row in the view style
dialog, type for filter name: "Catalog
Filters\Equipment::Nozzles", and then select the
desired label rule.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 79


When to Use a Graphic Wrapper

When to Use a Graphic Wrapper


The graphic wrapper modules allow you to customize the graphics included in your
view style. You can use a graphic wrapper to implement functionality that does not
generally support interfaces that the Drawings environment requires.

Following are the available wrapper DLLs located in


..\Drawings\Symbols\DrawingsWrappers\bin.

ElbowToSingleArc
Use this module when re-symbolizing an object in a drawing. For example, you can
use it to re-symbolize an elbow as a single arc. In this case the graphic module returns
an arc from its IJGraphicEntity interface instead of a revolution.

MakeDrawable
Use this module to force an object to be "drawable", that is, changing the
IJGraphicEntity::NotDrawable bit from IJGraphicEntity::GetProperties.

80 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

Equipment Nozzle Separator


Use this module to separate nozzles from the actual piece of equipment. Then you can
label the individual component or perform another action, such as replacing the
symbol.

ElbowToSingleArc Module
The ElbowToSingleArc module was created so that you can change the
symbolization of an elbow business object that is part of a pipe run. If you defined the
view style to process the single line representation of a pipe run, you do not want the
full elbow as part of the output.

The drawings generation process passes the elbow business object into this wrapper.
Then the process communicates to the wrapper for the geometry to process the elbow.
Finally the wrapper calculates the arc that represents the elbow. This representation of
the arc is in the center of the elbow.

Picture Without Module

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 81


When to Use a Graphic Wrapper

Picture with Module

82 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

To create the view style:


1. Create a new graphic preparation rule using the ElbowToSingleArc Wrapper.
Because the module changes only the graphics of elbows, you can use a 'wider'
filter, such as a filter for all Piping.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 83


When to Use a Graphic Wrapper

2. After creating the view style with this graphic rule, the remainder of the view
style is the same as replacing a pipe with a center line.

To view these examples, open the online programming documentation from Start >
Programs > Intergraph SmartPlant 3D > Programming and go to this section to
click any of the hot-linked file names.

Sample Code
ElbowToSingleArcConverter.cpp
ElbowToSingleArcConverter.h

The following common files should be used in all wrappers.

SimpleDelegator.cpp
SimpleDelegator.h
SimpleCoDelegator.cpp
SimpleCoDelegator.h

84 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

MakeDrawable Module
The MakeDrawable module was created in order to make an object drawable. A
property indicates whether an object is drawable or not, thus determining whether an
object should be processed for the drawing.

The business objects that display in the graphic views must implement the
IJGraphicEntity interface. This interface exposes a method called GetProperties.
To determine whether the object is drawable, testing is performed against the value
(NotDrawable = 0x0200). A business object that uses the MakeDrawable module
must already implement IJGraphicEntity or IJGraphicCompound. The wrapper
itself does not implement the interface for the object. It simply overwrites its
drawable property.

Note: This wrapper returns that the object is drawable, no matter what the real
business object returns.

To view these examples, open the online programming documentation from Start >
Programs > Intergraph SmartPlant 3D > Programming and go to this section to
click any of the hot-linked file names.

Sample Code
MakeDrawable.cpp
MakeDrawable.h
MakeDrawableGraphicHelper.cpp
MakeDrawableGraphicHelper.h

The following common files should be used in all wrappers:

SimpleDelegator.cpp
SimpleDelegator.h
SimpleCoDelegator.cpp
SimpleCoDelegator.h

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 85


When to Use a Graphic Wrapper

Equipment Nozzle Separator Module


The Equipment Nozzle Separator module was created to separate a piece of
equipment into multiple objects. This implementation provides flexibility so that you
can change the color of nozzles or label them separately from the entire piece of
equipment.

This wrapper basically reads in the whole piece of equipment and returns a collection
of objects for the drawings generation to process. This collection contains the
equipment and the nozzles as their own entity. The drawings generation process
communicates with each individual entity rather than the usual controlling piece of
equipment.

Label Nozzles Only

86 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

To create the view style:


1. Create a new graphic preparation rule using the Equipment Separator Wrapper.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 87


When to Use a Graphic Wrapper

2. Create a view style using this graphic preparation rule by selecting the entry in the
Filter Name column. Append the text "::Nozzles" to the filter name. Then select
the label rule.

To view these examples, open the online programming documentation from Start >
Programs > Intergraph SmartPlant 3D > Programming and go to this section to
click any of the hot-linked file names.

Sample Code
EquipmentNozzleSep.cpp
EquipmentNozzleSep.h
EquipNozzSepGraphicHelper.cpp
EquipNozzSepGraphicHelper.h

The following common files should be used in all wrappers:

SimpleDelegator.cpp
SimpleDelegator.h
SimpleCoDelegator.cpp
SimpleCoDelegator.h

88 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

Vertical Vessel Supports Placement


The Vertical Vessel Supports Placement command provides an example of how to
write a custom Microsoft Visual Basic command for the software. In addition to
placing structural members with appropriate frame connections and orientation, this
command follows similar standards and practices used within all structural commands
(for example, the Place Member command). This command shows how a ribbon bar
is created to include SmartSteps and other input fields that can be populated manually
or be a selection of graphics, drop-down lists, catalog browsers, or key-in fields.

The purpose of this command is to place structural members that support vertical
vessels directly (typically four lugs that rest on the members) or that support the
grating around these vessels. As it is very difficult and time consuming to complete
manual placement of these members, this command considers the vessel diameter and
clearance, or the bolt circle diameter (lug hole-to-lug hole diameter) to determine
member positions. Based on the cross section type chosen (I-section or channel), the
command also considers the gage (the distance to the bolt hole location) in
positioning the member. Because the equipment is often not centered within the main
framing of the opening, the command accommodates such conditions and displays
appropriate messages if the framing is not feasible. You also have the ability to
specify the member type, the system in which the members are placed, and section
size. See figures 1 and 2 below.

This command is currently limited to configurations where the lugs are positioned
North, South, East, and West, or at 45 degrees to these axes.

You can view or customize the sample project to meet the requirements of your own
data. The Vertical Vessel Supports Placement example is delivered as part of the
Programming Resources. Refer to the SmartPlant 3D Installation Guide for more
information on installing the Programming Resources. You should find this sample
project in the following path on your machine
..\..\ExampleCode\Commands\Examples\VerticalVesselSupport.

You can run this command by clicking Tools > Custom Commands in the software
and entering the ProgID: SPSVesselSupport.PlaceVesselSupp.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 89


When to Use a Graphic Wrapper

Figure 1 - Plan View

90 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

Figure 2A - Position of members using Bolt Circle

Figure 2B - Position of members using Vessel Diameter and


Clearance

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 91


When to Use a Graphic Wrapper

Creating Vertical Vessel Supports Example


The Command Wizard allows you to select relevant tools and methods for a new
Microsoft Visual Basic project and build a basic command based on those selected
requirements.

For more information about using the Command Wizard, in Visual Basic click Add-
Ins > Command Wizard.... Then click Help.

The following steps illustrate how to create the Vertical Vessel Support Placement
command using the Command Wizard:

• Step 1: Define name and description


• Step 2: Modality and enabling
• Step 3: Visual (ribbon bar) and help
• Step 4: References and services
• Step 5: Debugging and utilities
• Step 7: SmartStep 1 initialization
• Step 7 part 1: SmartStep 1 characteristics
• Step 7: SmartStep 2 initialization
• Step 7 part 2: SmartStep 2 characteristics
Note: When the command and ribbon bar projects were created, the wizard
automatically inserted a ProgID automatically in the code. The ProgID for the ribbon
bar was modified. The project also needed more type libraries to be referenced than
were provided by default.

The threading model for the ribbon bar project is defined as Apartment Threaded by
default. The ribbon bar threading model was modified as Single Threaded to interact
properly with the Hierarchy Combo control and the RAD2d Unit control.

For defining localized (internationalized) strings, you can use the Microsoft Visual
Basic Resource Editor to create your resource file.
1. Open Visual Basic.
2. Click Add-Ins > Add-In Manager....
3. Select VB 6 Resource Editor and make sure that the Loaded/Unloaded and
Load on Startup boxes under Load Behavior are both checked.
4. Click OK.
5. Click Tools > Resource Editor to invoke the dialog.

92 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

You can also use Microsoft Visual C++ to create the resource file and use the
software's localizer objects to access the file.

Step 1
In step 1, the new command's name, authoring, and type are defined. By designating
this type of command as normal, it means that the command implements the
IJCommand2 interface.

Note: The string entered in the New project description box appears in the Visual
Basic Project > References dialog that lists the type libraries that are available.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 93


When to Use a Graphic Wrapper

Step 2
In step 2, the command is defined as suspendable. The classification means that it is
an event-driven command that can be interrupted. Therefore, this command can be
added onto the stack while another is started. This command also needs an active
view and an active connection to the database.

94 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

Step 3
In step 3, the command is defined to have a ribbon bar. The ProgID is given so the
command can be run in the software. A localizer is added to provide
internationalization capability. Context-sensitive Help (F1) can be supplied for the
command by adding code to the IJCommandHelpInfo interface property.

Step 4
In step 4, the command is defined with the following references and services:

• AutoMath - Contains objects that allow vector math functionality.


• Geometry3D - References the type library of methods and properties for
the 3D geometry objects such as Arc3D, BSplineCurve3D, and so forth.
• StepFilter - Provides an interface with methods and properties to filter
elements by certain criteria. The StepFilter object can be used to check
whether an element or list of elements match the criteria. Criteria allowed
are: interface name, IID of an interface, a Visual Basic function, or ProgID
of a class.
• JCommand - Allows queries on a database.
• Units of measure - References units of measure type libraries.
• PreferencesMgr - References certain interfaces and CommonApp
utilities libraries.
• ValueMgr - References a special interface library.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 95


When to Use a Graphic Wrapper

Step 5
In step 5, the command is defined with a reference for debug support and the ability
to display status bar messages.

96 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

Step 6
In step 6 no selections are required for this command.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 97


When to Use a Graphic Wrapper

Step 7
In step 7, the command is defined to use the SmartStep functionality. As shown, two
SmartStep steps are set to be defined, one at a time, in the next series of steps. This
step initializes to begin defining the first step.

SmartStep 1, Page 1
In the SmartStep 1 Definition - Page 1, this command is defined with the following
options:

• Prompt to be displayed
• Maximum of four selectable elements
• QuickPick functionality
• Reference methods in the IJElemsByMonikerModified interface as
listeners to modifications in the elements collection.
• Use the step filter string ISPSMemberSystem, which allows only the
ClassIDs in that type library for the filter list.

98 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

SmartStep 1, Page 2
In this step, no selections are required for this command.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 99


When to Use a Graphic Wrapper

Step 7 Step 2
In step 7, the command is defined to use the SmartStep functionality. As shown, two
SmartStep steps are set to be defined, one at a time. This step initializes to begin
defining the second step.

SmartStep 2, Page 1
In the SmartStep 2 Definition - Page 1, this command is defined with the following
options:

• Prompt to be displayed
• Maximum of four selectable elements
• QuickPick functionality
• Reference methods in the IJElemsByMonikerModified interface as
listeners to modifications in the elements collection.
• Use the step filter string IJShape interface, which allows only the
ClassIDs in that type library for the filter list.

100 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

SmartStep 2, Page 2
In this step, no selections are required for this command.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 101


When to Use a Graphic Wrapper

Step 8
In step 8 the command's settings are saved.

102 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


When to Use a Graphic Wrapper

Adding References to the Project


Due to limitations of the Command Wizard, the following references must be
manually added to the project for the Vertical Vessel Supports Placement
command:

• Ingr Sp3d CommonApp Utilities v1.0


• Ingr Sp3d Project Management Info v1.0
• Ingr Sp3d CommonApp Application Context v1.0
• Ingr SmartPlant3D ApplicationContextSupport v1.0
• Ingr SmartPlant3D ConnectMiddle v1.0 Library
• Ingr SmartPlant3D ServerContextSupport v1.0 Library
• Ingr Sp3d Equipment Entities 1.0 Type Library
• Ingr SmartPlant3D Attributes v1.0 Library
• Ingr SmartPlant3D SPSMembers Entities v1.0 Library
• Ingr StructGenericTools Entities 1.0 Library
• Ingr SP3D GenericNamingRulesFacelets 1.0 Type Library
• Ingr SP3D GenericNamingRulesSemantics 1.0 Type Library
• Ingr Sp3d Generic NamingRules Helper 1.0
• Ingr Sp3d Generic NamingRuleAE 1.0 Type Library
• Ingr Sp3d RefDataServices 1.0 Type Library
• Ingr SmartPlant3D MetaData v1.0 Type Library
• Ingr SP3D ProjMgmt 1.0 Type Library

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 103


Creating Part Occurrence Symbols in Visual Basic: An Overview

Creating Part Occurrence Symbols in


Visual Basic: An Overview
You can create and customize three-dimensional piping part symbols that fit your
company or project using Visual Basic. The software provides the Part Definition
Wizard to help you produce symbol ports and graphics, or you can use Visual Basic
to customize delivered symbols. The Part Definition Wizard is delivered as part of the
Programming Resources. Refer to the Installation Guide for more information on
installing the Programming Resources and the Part Definition Wizard.

Related Topics
• Add a Symbol to Reference Data, page 105
• Creating Part Occurrence Symbols with the Part Definition Wizard: An Overview,
page 110
• Distributing Symbols Automatically, page 107
• Distributing Symbols Manually, page 109
• Workflow for Creating a VB Part Occurrence Symbol, page 112

104 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Add a Symbol to Reference Data


In this procedure, you add a new symbol to the reference data. Before following this
procedure, it is assumed that you have used the Visual Basic Part Definition Wizard
to create a VB project and a Microsoft Excel workbook for the symbol. Save all the
files from the wizard in a folder, such as C:\Symbols, and share this folder so that you
can access the folder from other clients. You will use this folder later when you copy
the new symbol to the other clients.

Note
• The Part Definition Wizard is delivered as part of the Programming
Resources. Refer to the Installation Guide for more information on
installing the Programming Resources.

Create the Visual Basic Project for a Symbol


1. Use the Visual Basic Part Definition Wizard to create a project and class module
files.
2. Store the VB files locally in C:\Symbols.
3. Open the Visual Basic project for the symbol.
4. Open the modules that the wizard created and add or modify code as necessary.
For example, you may need to add code in the inputs section and the outputs
section of the parent class module. This module has the same name as the project,
prefixed with a C.
5. Click File > Make <name of DLL> to compile the project and create the .DLL
file.
Tip
• In our example, save the .dll in the local folder (C:\Symbols).
6. Save the project and exit Visual Basic.

Add the Symbol to an Excel Workbook and Bulk Load


1. Open the Excel workbook that the wizard created and specify the individual parts
in the Head section on the part class sheet.
2. Add custom properties as needed on the part class sheet. You can add these
properties in the Definition section, the Head section, or both sections on the part
class sheet.
Tip
• When you ran the wizard, you defined custom properties (definition,
occurrence, or both). These properties appear on the Custom
Interfaces sheet of the workbook.
3. Type an A in the first cell of all the new rows on the part class sheet.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 105


Creating Part Occurrence Symbols in Visual Basic: An Overview

4. Save the changes to the workbook, and then exit Excel.


5. Bulk load the workbook in the Add/Modify/Delete mode. The bulkload process
is usually done on an administrator machine. For more information about bulk
loading, see the section "Bulk Load Database with Data" in the Reference Data
Guide.
6. Test the symbol in the software by opening a session and placing the part that
uses the symbol.
7. Choose whether to deploy the .dll manually or automatically.
Distributing Symbols Automatically, page 107
Distributing Symbols Manually, page 109

Related Topics
• Workflow for Creating a VB Part Occurrence Symbol, page 112

106 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Distributing Symbols Automatically


You can have the software automatically distribute new and modified symbols to
client computers by using CAB files. Use the Package & Deployment Wizard that
comes with Microsoft Visual Basic to create a CAB file for the symbol. Then, put the
CAB file on the Symbols share on the server. When a user on a client computer goes
to place the symbol, one of the following happens:

• If the symbol is a new symbol, the software automatically pulls to the


client computer the dll in the CAB file on the server, and then
automatically registers the dll on the client computer.
• If the symbol dll already exists on the client computer, the software
compares the version number of the dll on the client computer with the
version number of the CAB file on the server. If the dll in the CAB file is
newer, the software automatically pulls to the client computer the newer
dll in the CAB file, and then automatically registers the dll on the client
computer.
Note
• Because of Microsoft operating system requirements, the user on the client
computer must have Power User or Administrator access to the computer.
If you do not allow users to have Power User or Administrator access to
the client computer, then you must distribute symbols manually. For more
information, see Distributing Symbols Manually, page 109.
1. On the computer where you have created the symbols, start the Package &
Deployment Wizard that comes with Microsoft Visual Basic.
2. Select the VB project for the symbol using Browse.
3. Click Package.
4. For the Package Type, select Internet Package, and then click Next >.
5. For the Package Folder, specify the folder that you have shared (C:\Symbols),
and then click Next >.
6. On the Included Files page, clear all the checkboxes to the left of the file names
to remove them from the package except for the dll of your symbol. That is, the
only file name that should have a check next to it is the name of your symbol dll.
Then click Next >.
7. On the File Source page, verify that your symbol dll file is the only file listed,
and then click Next >.
8. On the Safety Settings page, keep the default settings, and then click Next >.
9. Click Finish.
10. Put the CAB file on the server symbols share.
11. Open the Excel workbook that contains the symbol part and go to the part sheet.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 107


Creating Part Occurrence Symbols in Visual Basic: An Overview

12. Create a new column on the sheet called Codebase.


13. In the Codebase column, type %CAB_SERVER%\name.CAB where name is the
name of the symbol CAB file.
14. Type an M in the first cell of the row and re-bulkload the workbook.

Related Topics
• Workflow for Creating a VB Part Occurrence Symbol, page 112

108 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Distributing Symbols Manually


If you choose not to use CAB files to distribute Visual Basic symbols, then you must
distribute and register the symbols manually.

Important
• If the symbol being distributed is an existing symbol that has been
modified, the major version number in the Visual Basic project properties
must be increased by 1. Increasing the major version number by 1 forces
the recomputation of existing symbol occurrences when the Synchronize
Model With Catalog command in Project Management is run. If an
existing symbol is modified and distributed, all the new symbol
occurrences will use the new symbol (unless the new occurrence uses an
existing entry of symbol's cache). If an existing symbol is modified and
distributed, and an existing occurrence is recomputed, it will use the new
symbol if the recomputation results in creation of new entry in the
symbol's cache.
1. Place the dll for the new or modified symbol on the server's symbols share.
2. On a client machine, copy the dll from the server to the local [Product Directory]\
RefData\SharedContent\bin\{component} folder.
3. Register the new .dll by clicking Start > Run and typing: regsvr32 "[Product
Directory]\\RefData\SharedContent\bin\{component} \<name of dll>".
Tip
• You can drag the file into the Run box rather than typing the entire
path.
4. Repeat steps 2 and 3 on each client machine.

Related Topics
• Workflow for Creating a VB Part Occurrence Symbol, page 112

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 109


Creating Part Occurrence Symbols in Visual Basic: An Overview

Creating Part Occurrence Symbols with the Part


Definition Wizard: An Overview
The Visual Basic Part Definition Wizard allows you to create and customize three-
dimensional piping part symbols that fit your company or project. The wizard
produces a Visual Basic project for building the symbol ports and graphics, and
generates an Excel workbook for bulk loading the symbol data into the Catalog
Database.

Before you use the wizard to create a part symbol, it is


recommended to set up the following directory structure to store the resulting files for
the part.

The bin folder stores the .dll file for the part symbol. The Excel folder stores the
reference data workbook that the wizard generates. The Modules folder stores the VB
libraries (.bas files), and the PartName folder stores the Visual Basic project (.vbp)
and class files (.cls).

A symbol created by the wizard always has the part as its first input. Information
from the part is converted into a parameter and cached using the CMCache method of
the symbol. Any other inputs are parameters. A flavor is created for each unique set
of parameters for this symbol. There is no limit on the number of inputs or outputs.
However a very high number of inputs and outputs affects the symbol's performance.

It is possible to create symbols that have other symbols as outputs (nested symbols).
An example of this is a symbol that has nozzles as outputs. These nozzles are also
symbols. These types of symbols require no special treatment by the symbol designer
other than to note that more than one level of nesting can have an impact on
performance.

Custom Component
A custom component is a specialized form of a symbol. If the symbol definition has
the property igSYMBOL_CACHE_OPTION_NOT_SHARED (meaning that the
result of its computation cannot be shared by other symbol occurrences) and the
property igSYMBOL_SUPPORT_UPDATE (the computation of the definition
supports the update of the outputs), a custom component is created instead of a
symbol by the IJDSymbolEntitiesFactory::PlaceSymbol method.

The custom component is seen as a group of entities resulting from the computation
of the definition. It does not hold a matrix. The result of the computation of the
symbol definition is directly attached to the custom component (using the output

110 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

collections) and updated at each recompilation. This eliminates the use of a flavor
object storing a unique result (gain of one object and one relation) and the creation of
the proxies for the outputs at the locate.

A custom component should be used when each symbol should be unique even if the
input parameters are the same.

Related Topics
• Creating Part Occurrence Symbols in Visual Basic: An Overview, page 104
• Visual Basic Part Definition Wizard, page 114
• Workflow for Creating a VB Part Occurrence Symbol, page 112

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 111


Creating Part Occurrence Symbols in Visual Basic: An Overview

Workflow for Creating a VB Part Occurrence Symbol


1. Start the VB Part Definition Wizard by opening Visual Basic and clicking Add-
Ins > SmartPlant 3D Part Definition Wizard.
Tip
• For instructions on how to install the Part Definition Wizard, see the
Installation Guide available from the Help > Printable Guides
command.
• The first page of the wizard contains a brief description of the wizard.
You can select an option to skip this page in the future.
2. On the Step 1 page, complete the project information.
Specify VB Project Information, page 117
3. On the Step 2 page, specify the catalog and part class information.
Specify Excel Workbook Information, page 119
4. On the Step 3 page, list the properties that are constant for all occurrences of the
part class.
Specify Definition Properties, page 121
5. On the Step 4 page, list the properties that can change for each occurrence of the
part class.
Specify Occurrence Properties, page 123
6. On the Step 5 page, list the graphical outputs of the symbol, such as the symbol
body or ports.
Identify Outputs, page 125
7. On the last page, you can select an option to save the settings as the default for the
next time that you run the wizard.
8. Click Finish.
Note
• You have just used the wizard to create a VB project, VB modules, and an
Excel workbook. Before you can test your symbol in the model, you must
add code, compile, distribute and register the .dll, edit the Excel
workbook, and bulk load into the Catalog Database. For more information,
see Distributing Symbols Automatically, page 107 or Distributing Symbols
Manually, page 109.

112 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Related Topics
• Creating Part Occurrence Symbols with the Part Definition Wizard: An Overview,
page 110
• Visual Basic Part Definition Wizard, page 114

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 113


Creating Part Occurrence Symbols in Visual Basic: An Overview

Visual Basic Part Definition Wizard


Sets options for the symbol project and Excel workbook.

Step 1 - Create VB Project Page, page 115


Step 2 - Create Excel Spreadsheet Page, page 118
Step 3 - Specify Definition Properties Page, page 120
Step 4 - Specify Occurrence Properties Page, page 122
Step 5 - Identify the Outputs Page, page 124

Related Topics
• Creating Part Occurrence Symbols with the Part Definition Wizard: An Overview,
page 110
• Workflow for Creating a VB Part Occurrence Symbol, page 112

114 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Step 1 - Create VB Project Page


Sets options for the Visual Basic project. Some of the information on this page
becomes VB comments in the main class module that the wizard generates. For
example, the text in the Author box becomes a comment in the header that tells who
ran the wizard.

You cannot advance to the next page of the wizard until you have completed the
Project name, Class name, Intergraph library location, and Save project as
boxes.

Project name - Allows you to specify the name of the Visual Basic project for the
symbol.

Class name - Specifies the name of the Visual Basic class. As you type text in the
Project name box, the Class name box fills with the same text, except it starts with
C. The maximum length of the project name and class name together is 39 characters.

Project description - Provides a brief description of the project.

Author - Gives the name of the author. The default is the current user. The default
name is your Windows login name.

Company - Gives the company of the author. The default is the company name
entered during the software installation.

Intergraph library location - Provides the path to an Intergraph-supplied library.


This location is where the CoreTraderKeys.bas file is stored. More than likely, this
location is [Product
Directory]\Programming\Programming\ExampleCode\Symbols\Modules.

Note
• The wizard checks to see if the delivered module files already exist in the
location specified. If files already exist in the location, the wizard does not
copy over them, and the existing files are included in the resulting VB
project. If the files do not exist in the location, the wizard copies the
Intergraph .bas files from the wizard's Templates folder to the specified
location, and the files are also included in the resulting VB project.
Custom library location - Provides the path to a custom library.

Save project as - Give the name of the project that you are creating.

Create bulkload spreadsheet - Specifies that the wizard creates an Excel workbook
containing the entered data for the symbol. You can use this workbook to bulk load
the symbol into the Catalog database.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 115


Creating Part Occurrence Symbols in Visual Basic: An Overview

Related Topics
• Specify VB Project Information, page 117

116 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Specify VB Project Information


1. In the Project name box, type a name for the symbol VB project. For example,
type MyPump. As you type text in the Project name box, the Class name box
fills with the same text, except it starts with C.
2. In the Project description box, type a brief explanation of the project, such as
Test Symbol.
3. Type your name and company in the Author and Company boxes, respectively.
The default name is your Windows login name, and the default company is the
text entered during installation of the software.
4. Click the ellipsis button beside the Intergraph library location box to select a
location for the VB libraries.
Tip
• The wizard checks to see if the delivered module files already exist in
the location specified. If files already exist in the location, the wizard
does not copy over them, and the existing files are included in the
resulting VB project. If the files do not exist in the location, the wizard
copies the Intergraph .bas files from the wizard's Templates folder to
the specified location, and the files are also included in the resulting
VB project.
5. Click the ellipsis button beside the Save project as box to specify the project
name and location. The default name is the value in the Project name box with a
.vbp extension.
6. If you want the wizard to create an Excel workbook with the symbol information,
make sure the Create bulkload spreadsheet box is selected.
Notes
• Some of the information on this page becomes VB comments in the main
class module that the wizard generates. For example, the text in the
Author box becomes a comment in the header that tells who ran the
wizard.
• The maximum length of the project name and class name together is 39
characters.
• You cannot advance to the next page of the wizard until you have
completed the Project name, Class name, Intergraph library location,
and Save project as boxes.
Related Topics
• Step 1 - Create VB Project Page, page 115

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 117


Creating Part Occurrence Symbols in Visual Basic: An Overview

Step 2 - Create Excel Spreadsheet Page


Creates an Excel workbook containing the part class for the symbol. After running the
wizard, you must open the workbook, add individual parts, and bulk load the
workbook into the Catalog Database for the symbol information to take effect.

Creating the Excel workbook during the wizard is optional; however, it may save you
some time because otherwise you must create the workbook or worksheets manually
after running the wizard.

Catalog server - Specifies the name of the server that stores the Catalog Database.
This box is not available.

Catalog name - Sets the name of the Catalog Database. This box is not available.

Part class name - Type the name of the part class that you want to create. The name
must not exceed 30 characters and must not include any spaces.

Copy from - Allows you to select an existing part class to use as a template for the
new part class. This button displays the standard catalog browser window. The wizard
completes all applicable boxes on the rest of the pages with the information from the
template. This is not available.

Part class description - Type a brief description of the part class. This description
will appear on the Index sheet of the resulting bulkload workbook if you specified to
create one.

Classification - Allows you to select a part class type. Your selection determines the
type of symbol, such as piping or equipment. This text will appear in the Definition
section of the part class sheet in the resulting bulkload workbook.

Save in Excel file - Specifies the name of the Excel workbook. The default name is
the project name with the .xls extension.

Related Topics
• Specify Excel Workbook Information, page 119

118 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Specify Excel Workbook Information


The Catalog server and Catalog name boxes are not available in this version.
1. In the Part class name box, type a name for the symbol part class. This name will
be the sheet name in the Excel workbook that the wizard creates. The name must
not exceed 30 characters and must not include any spaces. If you click Copy
from, you can select an existing part class as a template, and all the applicable
values from that part class appear on the following pages.
2. In the Part class description box, type a brief explanation of the part class. This
description will appear on the Index sheet of the resulting bulkload workbook if
you specified to create one.
3. In the Classification box, select a part class type. Your selection determines the
type of symbol, such as piping or equipment. This text will appear in the
Definition section of the part class sheet in the resulting bulkload workbook.
4. In the Save in Excel file box, select a location for the bulkload workbook that
contains the symbol data. The default name is the value entered in the Project
name box on the previous page of the wizard plus an .xls extension.
Notes
• You must complete both the Part class name and Classification boxes
before you can advance to the next page of the wizard.
Related Topics
• Step 2 - Create Excel Spreadsheet Page, page 118

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 119


Creating Part Occurrence Symbols in Visual Basic: An Overview

Step 3 - Specify Definition Properties Page


Specifies the properties of the part class that are constant for all occurrences of the
part. You can define new, unique interfaces and use existing interfaces for the
properties.

Completing this page is not mandatory, and you can skip it if necessary.

Definition properties - Provides a grid on which you can specify the definition
properties for the part class and correlate these properties with Visual Basic variables.

Interface Name - Specifies the name of the interface to which the property belongs.
You should begin a user-defined interface name with IJUA. This list is not populated
with the preexisting interfaces already in the catalog, so you must type the name.

Attribute Name - Type a name for the property. This name must not contain spaces.

Attribute User Name - Type a user-friendly name for the property. This name can
contain spaces.

Data Type - Provides the type of data, such as double or char.

Unit Type - Provides the category of units, such as distance or angle. For a list of
unit types, see the UOM sheet in the AllCommon.xls workbook delivered with the
catalog bulkload files.

Primary Unit - Gives the unit abbreviation, such as mm or deg, for the property.

Description - Type a brief description of the property.

Default - Type the default value for the property.

Symbol Parameter - Type the symbol parameter name. The name cannot have any
blanks or special characters. This name will appear in the Head/Start/End section of
the part class sheet. In the VB code, the symbol parameter is prefixed by par-.

Related Topics
• Specify Definition Properties, page 121

120 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Specify Definition Properties


Completing this page is not mandatory, and you can skip it if necessary.
1. In the Interface Name column, type an interface name.
Tip
• The Interface Name list is not populated with the preexisting
interfaces already in the catalog, so you must type the name.
• You should begin the interface name with IJUA (for user-defined
interfaces) or IJ (for system interfaces).
2. Type a name for the fixed property in the Attribute Name column. This name
must not contain spaces.
3. Type a user-friendly name for the property in the Attribute User Name column.
This name can contain spaces.
4. In the Data Type column, select the type of data, such as double or char.
5. In the Unit Type column, select the unit category for the data, such as distance or
angle. The list of unit types originates from the file uom.xml delivered with the
VB Part Definition Wizard.
6. In the Primary Unit column, select the unit abbreviation, such as mm or deg.
The list of primary units is filtered based on your selection in the Unit Type
column.
7. In the Description column, type a brief description of the property.
8. In the Default column, type the default value for the property.
9. In the Symbol Parameter column, type the symbol parameter name. The name
cannot have any blanks or special characters. This name will appear in the
Head/Start/End section of the part class sheet. In the VB code, the symbol
parameter is prefixed by par-.
Notes
• When defining angles in symbol code, the angle values must be in radians.
• The branch angle is the angle between the header port direction to the
branch port direction.
• Both interface names and attributes names must not exceed 30 characters.
• Fixed properties apply to every occurrence of the symbol in the model.
• The columns on this page are similar to the columns on the Custom
Interfaces sheet in the reference data workbooks.
Related Topics
• Step 3 - Specify Definition Properties Page, page 120

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 121


Creating Part Occurrence Symbols in Visual Basic: An Overview

Step 4 - Specify Occurrence Properties Page


Specifies the properties of the part class that can change for each occurrence of the
part. These properties are often called occurrence properties. Occurrence properties
are optional for symbols, so you can advance to the next page of the wizard if the grid
is blank or when at least one complete property definition is present.

As with the fixed properties, you can define new, unique interfaces and use existing
interfaces for occurrence properties.

Occurrence properties - Provides a grid on which you can specify the occurrence
properties for the part class and correlate these properties with Visual Basic variables.

Interface Name - Specifies the name of the interface to which the property belongs.
You should begin a user-defined interface name with IJUA. You will need to create
category names for the interfaces using the Catalog task.

Tip
• If you want an insulation aspect for an output of the symbol, you must
include the IJInsulationThickness interface.
Attribute Name - Type a name for the property. This name must not contain spaces.

Attribute User Name - Type a user-friendly name for the property. This name can
contain spaces.

Data Type - Provides the type of data, such as double or char.

Unit Type - Provides the category of units, such as distance or angle. For a list of
unit types, see the UOM sheet in the AllCommon.xls workbook delivered with the
catalog bulkload files.

Primary Unit - Gives the unit abbreviation, such as mm or deg, for the property.

Description - Type a brief description of the property.

Default - Provides the default value for the property. Users can change this value for
each part occurrence. The value in the Default box is not required for a complete
property definition.

Symbol Parameter - Type the symbol parameter name. The name cannot have any
blanks or special characters. This name will appear in the Head/Start/End section of
the part class sheet. In the VB code, the symbol parameter is prefixed by par-.

Related Topics
• Specify Occurrence Properties, page 123

122 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Specify Occurrence Properties


Important
• Occurrence properties are not required for symbols, so you can leave the
grid blank and advance to the next page of the wizard if you want.
• Occurrence property values can differ among symbol occurrences in the
software model. Users can change these property values on the
Occurrence tab of the Properties dialog box in the software.
1. In the Interface Name column, select one of the options in the list. You should
begin a user-defined interface name with IJUA.
Tip
• If you want an insulation aspect for an output of the symbol, you must
include the IJInsulationThickness interface.
2. Type a name for the fixed property in the Attribute Name column. This name
must not contain spaces.
3. Type a user-friendly name for the property in the Attribute User Name column.
This name can contain spaces.
4. In the Data Type column, select the type of data, such as double or char.
5. In the Unit Type column, select the unit category for the data, such as distance or
angle. The list of unit types originates from the file uom.xml delivered with the
VB Part Definition Wizard.
6. In the Primary Unit column, select the unit abbreviation, such as mm or deg.
The list of primary units is filtered based on your selection in the Unit Type
column.
7. In the Description column, type a brief description of the property.
8. In the Default column, type the value for the property. Users can change this
value for each part occurrence. The value in the Default column is not required
for a complete property definition.
9. In the Symbol Parameter column, type the symbol parameter name. The name
cannot have any blanks or special characters. This name will appear in the
Head/Start/End section of the part class sheet. In the VB code, the symbol
parameter is prefixed by par-.
Notes
• Both interface names and attributes names must not exceed 30 characters.
• For more information about units supported by the software, see
"Appendix B: Units of Measure" in the Reference Data Guide. The UOM
sheet in the AllCommon.xls workbook also contains information about
units of measure.
Related Topics
• Step 4 - Specify Occurrence Properties Page, page 122

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 123


Creating Part Occurrence Symbols in Visual Basic: An Overview

Step 5 - Identify the Outputs Page


Sets the output objects for the symbol. For each output, you must enter the name of
the output, the type of object, and an aspect.

Nozzles - Select the number of nozzles on the symbol.

Nozzle type - Select the type of nozzle, either Piping or HVAC.

Outputs - Lists the outputs in a grid format.

Name - Type a name for the output.

Description - Type a brief description. The name and description will appear in the
resulting Visual Basic program to aid you in correctly positioning additional output
object code.

Type - Allows you to select the type of object. Examples of types include body,
equipment nozzle, valve operator, primary, piping port, secondary piping port, HVAC
port, conduit port, and cable port.

Aspects - Select an aspect for the selected output.

Related Topics
• Customize the Wizard Output, page 126
• Identify Outputs, page 125

124 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Identify Outputs
1. In the Nozzles box, select the number of nozzles on the symbol.
2. In the Nozzle type box, select the type of nozzle, either Piping or HVAC.
3. In the Name column, type the name of the output in the VB program.
4. In the Description column, type a brief comment about the object. This
description is optional.
5. In the Type column, select a port type.
Tip
• Examples of types include body, equipment nozzle, valve operator,
primary, piping port, secondary piping port, HVAC port, conduit port,
and cable port.
6. Select an aspect for the output.
Notes
• The text that you type in the Name and Description columns appears in
the resulting VB program to help you find where to type additional code
for the output geometry and position.
• For each output, you must enter the name of the output, the type of object,
and an aspect.
• The wizard generates a class module for each aspect type that you specify.
For example, if you specify the simple physical aspect for one or more
outputs, the results will include CSimplePhysical.cls.
Related Topics
• Step 5 - Identify the Outputs Page, page 124

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 125


Creating Part Occurrence Symbols in Visual Basic: An Overview

Customize the Wizard Output


1. Double-click the CSimplePhysical class to open the code.
2. Find the comment line that reads Insert your code for output 1, and write your
code to define the first output. Repeat for each output.
Tips
• The wizard adds a comment line for each output you specified.
• Each primitive shape in your symbol must be represented by an output.
• If you change the number of outputs in the CSimplePhysical class, you
must also change the count of outputs within the custom class
(MyPump.cls, for example) to the correct number.
3. Verify that the Inputs section accurately describes the number of inputs for your
symbol and their positions within the arrayOfInputs.
Tip
• The first input is usually a Part Facelet object. The remaining inputs
are the inputs given to the Symbol Wizard. For example, if you were
creating a symbol of a ball valve which had three inputs, the code
could look like the following:
'Inputs
Set oPartFclt = arrayOfInputs(1)
parFacetoFace = arrayOfInputs(2)
parOperatorHeight = arrayOfInputs(3)
parOperatorLength = arrayOfInputs(4)
4. If necessary, declare any variables that your symbol requires.
Tips
• You can declare these variables as a standard data type such as double,
single, string, and so forth.
• If you are using an Intergraph standard type such as IJDPosition,
AutoMath.DPosition, and so forth, Intergraph recommends that you
declare the variable and set it equal to New in two separate steps.
Group these steps with the other declarations and inputs. For example:
Dim StemEndPos As IJDPosition
(in Dim section)
Set StemEndPos = New Dposition
(in Input section)
Related Topics
• Step 5 - Identify the Outputs Page, page 124

126 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Programming Notes for Visual Basic: An


Overview
If you are using Visual Basic to create or customize part symbols, refer to the
following programming notes for issues and examples that apply to the various
symbol types:

Defining Electrical Parts, page 127


Defining HVAC Parts, page 130
Defining Hanger and Support Part Ports, page 132
Defining Nozzles, page 134
Defining Parametric Components, page 139
Defining Valves, page 142
Using SymbolHelper, page 145
Using Custom Aspects with a Symbol, page 148
Using String Type as an Input Parameter, page 149
Using a Part as the First Input, page 150

Defining Electrical Parts


Electrical parts require some special considerations.

Electrical Conduit
Conduit is very similar to pipe, except that it is used to route electrical cables. Many
of the properties and features of conduit and piping are equivalent in the software.
The codelist for conduit measurements is available in AllCodeLists.xls on the Piping
Point Usage tab. The last option is #130 Conduit Port. The Nominal Piping Diameter
and Outside Diameter of electrical conduit are available as generic data so that they
can be standard with equipment. This information is located in AllCommon.xls.

To determine whether a nozzle is a conduit or pipe nozzle, you must trigger 130 for
Nozzle(1):PipingPointBasis as an attribute. When the command is launched, the
nozzle is automatically identified as conduit. If equipment has been created with
conduit, you must go to the catalog and trigger 130. PipingPointBasis for conduit
should be 130 and ConduitSelectionBasis should be 1 or 5.

For example, if a piece of equipment has two nozzles, one piping and one conduit, the
PipingPointBasis for the first may be 1 or 5 and the PipingPointBasis of the conduit
nozzle will be 130.

When you place conduit nozzles as equipment, they become part of the equipment
system in the hierarchy. They behave as equipment, even if they are not.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 127


Creating Part Occurrence Symbols in Visual Basic: An Overview

Cable Trays
Cable trays are open on one side and used to carry electrical cables through the
model. Similar to piping or conduit, they can be routed. However, they are
fundamentally different.

According to the National Electrical Code, a cable tray system is a unit or assembly
of units or sections and associated fittings forming a rigid structural system used to
securely fasten or support cables and raceways. A cable tray is the structural
component of the electrical system of a building or plant.

Because cable trays are open on the top, they cannot be rotated or mirrored as pipe or
conduit can. This creates a need for may different components, such as Branch left,
Branch right, Elbow down, Turn left, Reduce right, and so on. Every possible move
that can be made by a cable tray must be represented by a component symbol. The
joint where two cable trays meet is the port.

Some of the specifications that can identify a cable tray are:

• Manufacturer -- very important, because all information is fed by the part,


whose measurements are fixed by the manufacturing specification.
• Material
• Tray Type -- such as ladder or open.
• Rung Spacing -- if the tray is ladder type.
• IsTraySpec
• Determines tray versus way.
• If True, shows parts and hides feature
Spec Data + Route Topology = Generated Part

In reporting, the nominal (general categorized) width or depth is used. For example,
there may be many cable trays that have a width of about 12 inches that may all be
nominally 12 inches. However, there may be several different variances in the actual
width. Use the actual dimensions in the Visual Basic program. Although nominal
dimensions are used in reporting, the symbol returns an actual dimension.

Parts versus Features


The route followed by a series of cable trays is called the cable way. The cable way is
considered a feature of its parts, which are components of the cable tray. The cable
tray generates the part and the feature, but hides the feature. Features are not reported.

As an example, consider piping. On a valve there are many parts; mating flanges, gate
valve body, gaskets, bolts, nuts, and so on. These parts all have an Along Leg feature,
which means that the valve occurs along the pipe. In this example, there is one feature
and many parts.

128 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

There may be many features belonging to one part. A pipe run may have many
straight and bend features, however the only part is the pipe.

Because all information is standard and part driven, there are no inputs to the Visual
Basic symbol.

Reducers
An occurrence of a cable tray that is wider on one end and narrower on the other is a
reducer. Visual Basic symbols for reducers will typically have three principal
measurements:

• Face to Face -- Length between the location where the cable enters and
exits the tray.
• Width 1 -- Width where the cable enters the tray.
• Width 2 -- Width where the cable exits the tray.

Vectors
The vector directions are especially important when you construct cable tray symbols.
If a vector is facing the wrong direction, the cable tray may be built backwards,
causing the cable to go in the wrong direction, or upside down causing the cable to
fall out.

The cable tray requires two vectors emerging from the port. The port for a cable tray
begins at the center of the bottom edge of Width 1, along the Y edge. The X axis
vector, or axial orientation, begins at the port and extends outward away from the
direction in which the cable will run, along the center line of the cable tray. The Z
axis, or radial orientation, begins at the port and extends upward, toward the open end
of the tray. In dimensional terms, X represents tray length, Y represents width, and Z
represents depth. The vector settings would be (-1, 0, 0) for the axial orientation, and
(0, 0, 0) for the radial.

Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 129


Creating Part Occurrence Symbols in Visual Basic: An Overview

Defining HVAC Parts


Heating, Ventilation, and Air Conditioning (HVAC) for plants and buildings runs
through a duct system very similar to that in homes and office buildings. Similar to
piping, duct is routed through the model resulting in a duct run feature. A duct run
feature is a continuation of many individual physical components called duct parts.
When you create a run, the individual parts are generally selected by the software.
Each component is fed by one part, and is entirely catalog-driven. Because these parts
are fixed in width and depth, there are no occurrence attributes in HVAC.

Specifications
The catalog data for HVAC specs resides in the Hvac.xls workbook under the
HvacSpec sheet. On this sheet is a Specname of Spec-0, which allows for rectangular,
round, oval, and flat oval shapes. These shapes correspond to their own part numbers.

• Rectangular = PDS-100
• Round = PDS-150
• Oval = PDS-200
• Flat oval = PDS-250

HVAC Nozzles
HVAC components can contain nozzles, which are similar in form to those contained
in piping. They have measurements such as flange thickness, ports and port depths,
offset, nozzle length, and so on.

To create HVAC nozzles in a Visual Basic symbol, use the CreateNozzleFromPart


sub routine function. For example:
Set oNozzle = NozzleFactory.CreateHVACNozzleFromPart(part input,
index, False, objOutputColl.ResourceManager)
You can also use the subroutine function CreateHvacNozzle() as Object.

To create a dynamic HVAC component, do the following:


1. Pull the Symbol Parameters from the Hvac.xls sheet.
2. Use Occurrence Attributes and list in the Excel sheet.
• OA=Width in IJDuctSize
All information must be fed to the port, as the part does not exist. The component will
consist entirely of Occurrence Attributes supplied by the user.

Division
The division is an HVAC component used to split the flow from one duct run into
multiple duct runs. The most common division types split the duct run into two

130 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

divisions, either vertically or horizontally. Divisions are only used on rectangular


ducts. The Insert Component command inserts a division feature at an HVAC end
feature to route more than one individual run from the division feature.

A division feature is a cross sectional plane that is located perpendicular to the HVAC
running direction. It contains two or more cells. The divisions are created as symbols
and reside in the HVAC Reference Data catalog of parts. You can modify the cell
sizes regardless of HVAC reference data after the cells are placed. The cell sizes are
stored in reference data as occurrence properties and can be modified in route.

Division symbols are rectangular in shape. Each cell division must result in a
rectangular cross section. The total cross sectional area of all the cells must equal the
original cross sectional area before the division was inserted. (That is, A1 + A2 + A3
+ ...n = Original Area) You can modify the cell size from the settings page before or
after placing the symbol.

Each cell in the division component is treated as a port in the route.

Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 131


Creating Part Occurrence Symbols in Visual Basic: An Overview

Defining Hanger and Support Part Ports


The part symbols used to represent a hanger and support assembly are expected to generate
ports as output. The ports in question are objects implementing the IJHgrPort interface. A
factory (that is, the HgrPortFactory object) is provided for creating such objects. An example
showing the creation of ports is shown below.
Dim m_outputColl As IJDOutputCollection
. . .
Dim oStructPort As IJHgrPort
Dim oRoutePort As IJHgrPort
Dim oPortFac As IJHgrPortFactory
'Create a Port Factory
Set oPortFac = New HgrPortFactory
'Create PortA and initialize its values
Set oStructPort =
oPortFac.CreateHgrPortEntity(m_outputColl.ResourceManager)
oStructPort.Name = "Structure"
oStructPort.PutOrientation 0.0, 0.0, 0.0, _' The Port Origin
1.0, 0.0, 0.0, _' The Port X-Axis
0.0, 0.0, 1.0 ' The Port Z-Axis
'Create PortB and initialize its values
Set oRoutePort =
oPortFac.CreateHgrPortEntity(m_outputColl.ResourceManager)
oTopPort.Name = "Route"
oRoutePort.PutOrientation 2.0, 2.0, 1.0, _ ' The Port Origin
1.0, 0.0, 0.0, _ ' The Port X-Axis
0.0, 1.0, 0.0 ' The Port Z-Axis
'Add ports to output collection.
’NOTE: The output names do not need to match the port names.
m_outputColl.AddOutput "PortA", oStructPort
m_outputColl.AddOutput "PortB", oRoutePort
The creator of the port is responsible for setting its orientation and name. Orientation is set
using the following method.
Sub IJHgrPort_PutOrientation(OriginX As Double, OriginY As Double, OriginZ
As Double, XAxisX As Double, XAxisY As Double, XAxisZ As Double, ZAxisX As
Double, ZAxisY As Double, ZAxisZ As Double)
The port's name is set using the "name" property on the port object. The following conventions
should be used when naming ports.

• If a symbol is in contact with or is considered to interact with a routing object, it should


output a port named "Route". The port's location should represent the idealized point of
contact between the symbol and the route object.
• If a symbol is in contact with or is considered to interact with a structural object, it
should output a port named "Structure". The port's location should represent the
idealized point of contact between the symbol and the structural object.
This information is used in combination with the output from GetStructConnections( ) and
GetRouteConnections( ) of the Assembly Information Rule (see the Hangers and Supports

132 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Reference Data Guide for more information about Assembly Information Rules). For example,
the software uses this data to generate reports and ISOGEN drawings.

If a support is expected to generate manufacturing features, its symbols must output Support
Manufacturing Features. These objects implement the IJHgrMfgFeature interface. A factory
(that is, the HgrMfgFeatureFactory object) is provided for creating such objects.

The creator of the feature is responsible for setting its contour and type. The contour is set
using the following method.
Sub IJHgrMfgFeature_PutContour(Contour AsIJCurve)
The provided curve is used by other tasks such as Piping and Structure to generate detailed
features on the structural and routing objects associated with the support.

The feature's type is set using the Type property on the feature object. Valid values are shown
in the following table.

enum HgrMfgFeatType
WeldedType
HoleType
CutoutType
...

The feature's type determines the logic used when creating any manufacturing features.

Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 133


Creating Part Occurrence Symbols in Visual Basic: An Overview

Defining Piping Parts


When defining piping part symbols, you need to remember:

• Stock piping parts with asymmetrical ports must have which port is flow
in and which port is flow out defined in the catalog data. You cannot
define both ports as flow in or both as flow out when they are not
symmetrical.
• When defining angle values in the symbol code, the value must be in
radians..
• The branch angle is the angle between the header port direction to the
branch port direction.
• By convention, the symbol header must be defined along the X-axis.
Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

134 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Defining Nozzles
There are several ways that you can use a nozzle to connect a pipe with valves or
equipment. These differences are called end preparations. The three most commonly
used end preparations are:

• Butt Weld -- the pipe and valve butt up against each other and are welded
together. The port is at the Face to Face of the valve itself.
• Bolted Connection -- two nozzles with equally sized flanges are bolted
together through holes in the flange. The port is at the outside surface of
the flange that is attached to the valve.
• Female Socket Weld -- the valve flange has a depression, or socket, that
recedes back into it. The pipe is inserted into the socket with a small
offset. To determine the position of the port, use one of the following
formula:
PortPos = -FF/2 - Offset + Depth
PortPos = FF/2 - (Depth - Offset)
The following illustration identifies the dimensions for the formula.

1. Nozzle Length
2. Flange Thickness / Hub Thickness / Face to Face
3. Socket Offset
4. Socket Depth
5. Vector
6. Flange Diameter
7. Pipe Outside Diameter
Note
• Set Face to Face as the first input in the Part Definition Wizard.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 135


Creating Part Occurrence Symbols in Visual Basic: An Overview

Port Index
The port index (PortID) is a unique identifier that represents each port. You can write
code to communicate with this PortID because it has an interface. You can retrieve
information, such as the flange thickness, by calling the PortID. The PortID, in turn, calls
to the generic data residing in the AllCommon.xls file for the flange thickness and returns
it. This is useful when you need generic data about a part that you want to place in your
Visual Basic program. With these values, you can make calculations and perform actions
related to those calculations.

The first input to any Visual Basic program is the part. To retrieve information about this
part, add a line of code similar to the following:
RetrieveParameters 1, oPartFclt, mOutputColl, pipeDiam, flangeThick, _
flangeDiam, cptOffset, depth
If your next line of code was the following:
Set ObjBody = Placesphere(m_OutputColl, CenterPos, _
parFacetoFace / 2 - flangeThick)
You would have to inquire about the value of the flangeThick parameter from generic
data to determine the distance between the center of the valve and the beginning of the
flange.

Notes
• oPartFclt is the parent directory for all parts called in Visual Basic. It is declared
as the first DIM statement to contribute parts to symbols.
• flangeThick, as used in the previous example, is not the attribute name for flange
thickness. It is a variable used to hold the result of this value.
• When defining a piping stock part with asymmetrical ports, you must specify
which port is flow in and which port is flow out in the catalog data.

Insulation
When you add insulation to a symbol using the Part Definition Wizard, list it as an
Occurrence Attribute under the insulation aspect. There are two inputs for insulation on a
simple object, such as a ball valve.

• Input 1 -- Face to Face


• Input 2 -- Insulation Thickness
The user can modify occurrence attributes. The system property used is
InsulationThickness, and IJInsulationThickness is the interface.

Note
• The first input should always be Face To Face, Face to Center, and so on.

136 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Face to Center versus Face to Face


If the item you are creating is non-symmetrical, you might want to consider using a
Face to Center dimension instead of a Face to Face dimension.

If this was a straight pipe with nozzles, you would probably describe its length using
a simple Face to Face value, such as dimension 3. If you want to describe the length
of the center pipe, neither the Face to Face value, nor the pipe diameter, will provide
the length. A Face to Center value, or combination of Face1 to Center and Face2 to
Center values, better meet the need.

Face to Center values can also be useful when describing the length between the
center of the symbol and a port. A simple formula for center to port is:
Face1toCenter - (Depth - Offset)
or
F1C - (D - O)

Vectors and Directions


A vector determines the default direction that a plane or shape faces. Vectors should
always face the outside of the shape to insure that when you connect to a certain
nozzle or port you do not attach another component to the inside of a shape.

Vector directions are also very important for setting relationships between two
symbols. For example, if you have two pumps and want to relate them to each other
and to a horizontal plane, the vector of the plane must face upward, and the vectors of
the bottom surfaces of the pumps must face down. Otherwise you could end up with
the pumps hanging upside down from the plane.

To set vectors in the correct direction, first declare them as variables. For example:
DIM oDir AS IJDVector
Set oDir = New Dvector
Next, set the direction. The vector always begins on the same plane as the surface for
which you are setting the vector. Specify any coordinate in the correct direction
through which the vector will run. For example:

Left Facing oDir.set -1, 0, 0


Right Facing oDir.set 1, 0, 0
Upper Left Facing oDir.set -1, 1, 0

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 137


Creating Part Occurrence Symbols in Visual Basic: An Overview

Axis Orientation
The line between two ports of a symbol is its axis orientation. Certain types of
symbols should have different axis orientations based on the needs of that symbol.
For example, piping components such as valves run along pipe runs and generally
have ports along the X-axis where the component connects with the rest of the run.
There may be a second Y-axis along the valve operator of the same pipe component.

Flanges
The flange is the connection face of the nozzle. Typically, flange diameters are
significantly wider than the nominal piping diameter and are welded to the pipe.
Three common types of flanges used in the software are:

• Weld Neck Flange -- Flange and neck, welded at end of neck on both
sides with pipe.
• Plate Flange -- Plate for the flange, but no neck. Welded at the end of the
pipe inside of the flange, and at the outside of the flange to the pipe.
• Slip-on Flange -- Flange and neck, slips on to pipe and is welded to the
pipe both at the outside of the neck and the inside of the flange.
Flanges contain two ports; one to connect with other equipment, and another to
connect with the pipe. The distance between Port 1 (connection with other
equipment) and Port 2 (connection with pipe) is also the Face to Face value. If there
is no distance between the two ports, as in a plate flange, the Face to Face value is
zero.

Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

138 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Defining Parametric Components


You may need the flexibility to change the dimensions as well as nozzle data
dynamically for piping specialties or instruments. In this case, create the symbols as
fully parametric symbols so that you can change the data in the model.

A fully parametric symbol allows you to modify the following nozzle data as well as
the dimensions of a symbol. The symbol is recomputed for dimensions and nozzle
data based on the changes that you make.

• PortIndex
• Npd
• EndPreparation
• ScheduleThickness
• EndStandard
• PressureRating
• FlowDirection
A fully parametric symbol differs from a regular symbol in the following ways:

• All the input parameters are given as occurrence attributes in the PartClass
sheet (bulkload sheet).
• In addition to the regular inputs, nozzle data such as NPD and End
Preparation are defined as inputs.
• Create the fully parametric nozzle by using the CreatePipeNozzle function
in the physical class file of the symbol. The CreatePipeNozzle function is
a method on GSCADNozzleEntities.NozzleFactory. Use this instead of the
CreateNozzle function (which uses CreatePipeNozzleFromPart internally)
that you would use in regular symbols.
Notes
• Do not use the RetrieveParameters function for fully parametric symbols.
The RetrieveParameters function gets the values from the Catalog
Database. If the user changes the nozzle data (such as the EndPreparation),
the RetrieveParameters function gets the values from the Catalog Database
so the new values do not display.
• Modified nozzle data is not available for the Insulation class. You can use
static variables to account for this. When you create nozzles in the
physical class file, store the nozzle data (such as flangedia and
flangethickness) in static array variables. For example:
Dim pipeDiam(1 To 2) As Double
Dim sptOffset(1 To 2) As Double

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 139


Creating Part Occurrence Symbols in Visual Basic: An Overview

Dim flangeDiam(1 To 2) As Double


Dim depth(1 To 2) As Double
Dim flangeThick(1 To 2) As Double
Then, in the Insulation class the nozzle data is retrieved from these static variables
and used to create the geometry.

The following example shows code for creating a fully dynamic nozzle. All the
geometry output creation would be similar as in a regular symbol.
'Place Dynamic Nozzle
Dim oLogicalDistPort As GSCADNozzleEntities.IJLogicalDistPort
Dim oDistribPort As GSCADNozzleEntities.IJDistribPort
Dim oPipePort As GSCADNozzleEntities.IJDPipePort
Dim oNozzleFactory As GSCADNozzleEntities.NozzleFactory
Dim oNozzle As GSCADNozzleEntities.IJDNozzle
Set oNozzleFactory = New GSCADNozzleEntities.NozzleFactory
Private m_oCodeListMetadata As IJDCodeListMetaData
Set m_oCodeListMetadata = m_OutputColl.ResourceManager
TerminationSubClass1 =
m_oCodeListMetadata.ParentValueID("EndPreparation", EndPreparation1)
TerminationClass1 =
m_oCodeListMetadata.ParentValueID("TerminationSubClass"
TerminationSubClass1)
SchedulePractice1 =
m_oCodeListMetadata.ParentValueID("ScheduleThickness"
ScheduleThickness1)
EndPractice1 = m_oCodeListMetadata.ParentValueID("EndStandard"
EndStandard1)
RatingPractice1 =
m_oCodeListMetadata.ParentValueID("PressureRating", PressureRating1)
Set oNozzle = oNozzleFactory.CreatePipeNozzle(PortIndex1, Npd1, _
NpdUnitType1, EndPreparation1, ScheduleThickness1, EndStandard1, _
PressureRating1, FlowDirection1, PortStatus, Id1, _
TerminationClass1, TerminationSubClass1, SchedulePractice1, _
5, EndPractice1, RatingPractice1, False,
m_OutputColl.ResourceManager, oCatalogConnection.ResourceManager)
Set oLogicalDistPort = oNozzle
Set oDistribPort = oNozzle
Set oPipePort = oNozzle
pipeDiam1 = oPipePort.PipingOutsideDiameter
flangeDiam1 = oPipePort.FlangeOrHubOutsideDiameter
flangeThick1 = oPipePort.FlangeOrHubThickness
depth = oPipePort.SeatingOrGrooveOrSocketDepth
CptOffset = oPipePort.FlangeProjectionOrSocketOffset
oNozzle.Length = flangeThick1
'Direction of the Nozzle
oDir.Set -1, 0, 0
oDistribPort.SetDirectionVector oDir
'Position of the nozzle should be the connect point of the nozzle
oPlacePoint.Set -(faceToFace / 2 + CptOffset - depth), 0, 0

Using Codelist Data to Retrieve Other Nozzle Data


To create a nozzle using the CreatePipeNozzle function in a fully parametric symbol, obtain
the TerminationSubClass, TerminationClass, SchedulePractice, EndPractice, and
RatingPractice. You can obtain these values by using IJDCodeListMetaData.

140 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

For example:
Private m_oCodeListMetadata As IJDCodeListMetaData
Set m_oCodeListMetadata = m_OutputColl.ResourceManager

TerminationSubClass1 = m_oCodeListMetadata.ParentValueID("EndPreparation",
EndPreparation1)
TerminationClass1 =
m_oCodeListMetadata.ParentValueID("TerminationSubClass",
TerminationSubClass1)
SchedulePractice1 = m_oCodeListMetadata.ParentValueID("ScheduleThickness",
ScheduleThickness1)
EndPractice1 = m_oCodeListMetadata.ParentValueID("EndStandard",
EndStandard1)
RatingPractice1 = m_oCodeListMetadata.ParentValueID("PressureRating",
PressureRating1)
Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 141


Creating Part Occurrence Symbols in Visual Basic: An Overview

Defining Valves
You can create valve symbols with or without operators. If you create the valve
symbol with the operator, then the operator geometry is included in the valve
geometry. That means that you must create a separate symbol for each combination of
valve and operator.

If you create the valve symbol and operator symbol separately, you can associate the
operator symbols with the valve symbols when you bulkload the valves. The valve
symbol code contains the information for placing an operator at the required
orientation.

To attach an operator with a given symbol do the following:


1. Create one output in the physical class file for Operator. For example:
'Insert your code for output 4 (Valve Operator)
Dim oSymbolHelper As IJSymbolGeometryHelper
Set oSymbolHelper = New SP3DSymbolHelper.SymbolServices
oSymbolHelper.OutputCollection = m_OutputColl

On Error Resume Next


Dim oDirX As IJDVector
Dim oDirY As IJDVector
Dim oDirZ As IJDVector
Set oDirX = New DVector
Set oDirY = New DVector
Set oDirZ = New DVector

oDirX.Set Cos(parRotation), 0, Sin(parRotation)


oDirY.Set 0, 1, 0
oDirZ.Set -Sin(parRotation), 0, Cos(parRotation)

Dim oPipeComponent As IJDPipeComponent


Set oPipeComponent = oPartFclt
On Error GoTo ErrorLabel
Dim oOperatorPart As IJDPart
Dim oOperatorOcc As IJPartOcc
If Not oPipeComponent Is Nothing Then
Set oOperatorPart = oPipeComponent.GetValveOperatorPart
If Not oOperatorPart Is Nothing Then
Dim OpOrigin As IJDPosition
Set OpOrigin = New DPosition
OpOrigin.Set 0, 0, 0
Set oOperatorOcc =
oSymbolHelper.CreateChildPartOcc("ValveOperator", oOperatorPart,
OpOrigin, oDirX, oDirY, oDirZ)

End If
End If
Set oSymbolHelper = Nothing
Set oOperatorPart = Nothing

142 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Set oPipeComponent = Nothing


Set oOperatorOcc = Nothing
2. While bulkloading the Valve Body, specify the operator (part number -
OperatorPartNumber) that you want to combine with the valve body on the
PipingcommodityMatlControlData sheet in the ValveOperatorPartNumber
column. For example:

The value VAABAHGGAA under ContractorCommodityCode is the


IndustryCommodityCode for the valve body. The GAT-BLT-150-3 value under
ValveOperatorPartNumber is the operator IndustryCommodityCode. You must
bulkload the operator separately under the equipment hierarchy.

Create a Nozzle from a Part


You can create a nozzle using the data available in the catalog database for the
Nozzle index. You provide the data in the part class sheet of the Symbol when you
bulkload. Use this technique for symbols which are not parametric.

For example:
Set oNozzle = NozzleFactory.CreatePipeNozzleFromPart(partInput,
nozzleIndex, False, objOutputColl.ResourceManager)
PartInput – Part having the information about the Nozzle.
NozzleIndex – Nozzle Index number of the Nozzle being created and
available in Catalog data

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 143


Creating Part Occurrence Symbols in Visual Basic: An Overview

Create a Nozzle without Using a Part


You can create a nozzle using the data passed into the function by the user rather than
data from the catalog database. The following example creates nozzles in parametric
symbols:
oNozzleFactory.CreatePipeNozzle(PortIndex, Npd, NPDUnitType, _
EndPreparation, ScheduleThickness, EndStandard, PressureRating,
FlowDirection, PortStatus, Id, TerminationClass,
TerminationSubClass, SchedulePractice, 5, EndPractice,
RatingPractice, False, objOutputColl.ResourceManager,
oCatalogConnection.ResourceManager)
In the example you can specify, PortIndex, Npd, endpreparation, and so on as input
parameters to the symbol. The function creates a nozzle according to the data values
passed to it and not from the catalog database.

You can create the following types of nozzles using part information:

• Pipe Nozzle
• Cable Nozzle
• Cable Tray Nozzle
• Conduit Nozzle
• HVAC Nozzle
Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

144 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Using SymbolHelper
The SymbolHelper object (SymbolHelper.SymbolServices) implements two
interfaces; IJDUserSymbolServices and IJSymbolGeometryHelper.

SymbolHelper provides the default implementation of the methods in the


IJDUserSymbolServices interface.

The Part Definition Wizard-generated code implements the methods of


IJDUserSymbolServices in the main class file of the symbol project. Because of this,
the implementation code of these methods is copied into each symbol project. Using
the SymbolHelper object can reduce this repetition of code.

The SymbolHelper project also implements the methods of


IJSymbolGeometryHelper, which provides implementation for creation of some
primitive geometric shapes such as cylinder, sphere, and so on. You can use these
shapes to create the symbol geometry.

For more detailed information about the SymbolHelper API, refer to the
"SymbolHelper Math Reference" in the Programmer's Guide.

Note
• SymbolServices object does not support String type as a symbol input
parameter.

Example
The following example shows the main Symbol class file for a SP3DcheckValve
created using the SymbolHelper object.
'++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
'
' Copyright 1999 Copyright 1999 Intergraph
' All Rights Reserved
'
' CCheckValve.cls.cls
' ProgID: SP3DCheckValve.CCheckValve
' Author:
' Creation Date: Monday, Jan 22 2001
' Description:
' TODO - fill in header description information
'
' Change History:
' Joe Programmer : Thursday , Jan 2003
' Modified existing symbol to check for Symbol creation using
SP3DSymbolHelper.SymbolServices
' ----------- --- ------------------
'
'++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Option Explicit

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 145


Creating Part Occurrence Symbols in Visual Basic: An Overview

Private Const MODULE = "CCheckValve:" 'Used for error messages

Private m_oSymbolHelper As IJSymbolHelper


Private Const E_FAIL = &H80004005
' Declaration of the User Symbol Services interface
Implements IJDUserSymbolServices
'+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Private Sub Class_Initialize()
Const METHOD = "Class_Initialize:"
On Error GoTo ErrorHandler

Set m_oSymbolHelper = New SymbolServices


m_oSymbolHelper.ProjectName = "SP3DCheckValve"
m_oSymbolHelper.ClassName = "CCheckValve"

' Inputs
m_oSymbolHelper.NumInputs = 2
m_oSymbolHelper.AddInputDef 1, "FacetoFace", "Face to Face",
0.292
m_oSymbolHelper.AddInputDef 2, "InsulationThickness",
"Insulation Thickness", 0.025

' Outputs
m_oSymbolHelper.NumOutputs = 4
m_oSymbolHelper.AddOutputDef 1, "Body", "Check Valve Body",
SimplePhysical
m_oSymbolHelper.AddOutputDef 2, "InsulatedBody", "Insulated
Body", Insulation
m_oSymbolHelper.AddOutputDef 3, "PNoz1", "Nozzle 1",
SimplePhysical
m_oSymbolHelper.AddOutputDef 4, "PNoz2", "Nozzle 2",
SimplePhysical

' Aspects
m_oSymbolHelper.NumAspects = 2
m_oSymbolHelper.AddAspectDef 1, "Physical", "Physical",
SimplePhysical
m_oSymbolHelper.AddAspectDef 2, "Insulation", "Insulation",
Insulation

Exit Sub

ErrorHandler:
ReportUnanticipatedError MODULE, METHOD

End Sub
'+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Private Sub Class_Terminate()
Set m_oSymbolHelper = Nothing
End Sub
'+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Public Function IJDUserSymbolServices_InstanciateDefinition( _
ByVal CodeBase As String, _
ByVal defParameters As Variant, _
ByVal ActiveConnection As Object) As Object
' call symbol services default implementation of this method

146 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

IJDUserSymbolServices_InstanciateDefinition =
m_oSymbolHelper.InstanciateDefinition(CodeBase, defParameters,
ActiveConnection)
End Function
'+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Public Function IJDUserSymbolServices_GetDefinitionName(ByVal
definitionParameters As Variant) As String
IJDUserSymbolServices_GetDefinitionName =
m_oSymbolHelper.ProjectName + "." + m_oSymbolHelper.ClassName
End Function
'+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Public Sub IJDUserSymbolServices_InitializeSymbolDefinition(ByRef
pSymbolDefinition As IJDSymbolDefinition)
m_oSymbolHelper.InitializeSymbolDefinition pSymbolDefinition
End Sub
'+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Public Sub IJDUserSymbolServices_InvokeRepresentation(ByVal sblOcc
As Object, _
ByVal repName As String, _
ByVal outputcoll As Object, _
ByRef arrayOfInputs())

m_oSymbolHelper.InvokeRepresentation sblOcc, repName,


outputcoll, arrayOfInputs

End Sub
'+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Public Function IJDUserSymbolServices_EditOccurence(ByRef
pSymbolOccurence As Object, ByVal transactionMgr As Object) As
Boolean

' The definition uses the generic EditOccurrence command


IJDUserSymbolServices_EditOccurence = False

End Function
'+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 147


Creating Part Occurrence Symbols in Visual Basic: An Overview

Using Custom Aspects with a Symbol


If you want to use a custom aspect with a symbol, you must define the SymbolRepId in the
symbol's code. Custom aspects are defined in the AspectCode codelist in the
AllCodeLists.xls workbook (see the Reference Data Guide for more information about
editing codelists). Codelist numbers 19 through 30 are available for custom aspects.

The SymbolRepId represents the custom aspect codelist number as a Long in the symbol
code. For example, the custom aspect that you want to use is codelist number 19 in the
AspectCode codelist. The SymbolRepId for the symbol would be 219 or 524288. A custom
aspect with a codelist number of 30 would have 1073741824 (230) as the SymbolRepId.

Example code using a custom aspect with a codelist number of 30, SymbolRepID
1073741824:
m_oSymbolHelper.NumOutputs = 2
m_oSymbolHelper.AddOutputDef 1, "O1", "O1", 1
m_oSymbolHelper.AddOutputDef 2, "O2", "O2", 1073741824
m_oSymbolHelper.NumAspects = 2
m_oSymbolHelper.AddAspectDef 1, "SimplePhysical", "Simple", SimplePhysical
m_oSymbolHelper.AddAspectDef 2, "UseDefinedAspect", "UserDefined",
1073741824
Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

148 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Using String Type as an Input Parameter


You can set the input parameter to String type. String as an input parameter is useful
for specifying character text. A symbol can have string as an input parameter if you
want to change some input parameters dynamically, such as Nozzle Id or Unit Type.
To use String as an input type, you need to create another ParameterContent and set
its type to igString.

Add the following code to the code generated by the Part Definition Wizard in the
IJDUserSymbolServices_InitializeSymbolDefinition method:
'Create a default parameter for Text INput parameters
Dim PC1 As IMSSymbolEntities.IJDParameterContent
Set PC1 = New IMSSymbolEntities.DParameterContent
PC1.Type = igString
ReDim TextInputs(1 To iTextCount) As IMSSymbolEntities.IJDInput
For iCount = 1 To iTextCount
Set TextInputs(iCount) = New IMSSymbolEntities.DInput
TextInputs(iCount).name = m_TextInputTypes(iCount).name
TextInputs(iCount).description =
m_TextInputTypes(iCount).description
TextInputs(iCount).properties =
m_TextInputTypes(iCount).properties
PC1.String = m_TextInputTypes(iCount).Value
TextInputs(iCount).DefaultParameterValue = PC1
InputsIf.SetInput TextInputs(iCount), nInputs + iCount + 1
Set TextInputs(iCount) = Nothing
Next iCount
See Defining Parametric Components: An Overview for another example of string
type implementation.

Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 149


Creating Part Occurrence Symbols in Visual Basic: An Overview

Using a Part as the First Input


The first input in a Visual Basic symbol project is of the type PartFacelets.IJDPart.
Every aspect will have its first input parameter of type PartFacelets.IJDPart. The
following example is from the Physical.cls file:
Set oPartFclt = arrayOfInputs(1)
ParFacetoFace = arrayOfInputs(2)
...
The part (PartFacelets.IJDPart) contains information regarding the part you are
placing in the model. For example, it could contain the number of ports and end
preparations, end standard, and so on. If the symbol you are placing contains some
number of inputs and some number of nozzles, the RetrieveParameters function will
get the nozzle information such as pipe diameter, end preparation, pressure rating,
and so on using the input part PartFacelets.IJDPart.

The RetrieveParameters function uses the information in PartFacelets.IJDPart to


retrieve the pipe diameter, flange diameter, and so on of nozzles associated with the
part while placing the symbol in the model.

Related Topics
• Programming Notes for Visual Basic: An Overview, page 127

150 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Converting PDS EDEN to SmartPlant Visual


Basic Symbols: An Overview
You can convert your PDS EDEN symbols to SmartPlant Visual Basic symbols using
the EDEN2SP3D.exe translator located in the [Product Directory]
\Programming\Programming\Example
Code\PDSTranslator\EDEN2SP3D\Template_Piping folder on the server. The
translator uses the EDEN symbol's model graphics file (*.mg), which contains the
information on how to generate the symbol graphics, as the input. The translator
parses the code in the *.mg file and generates the corresponding Visual Basic project
that contains the equivalent code to generate the symbol. You must have sufficient
Visual Basic programming skills to understand and modify the generated Visual
Basic symbol code as needed.

The translator creates a log file to inform you of any errors found while parsing the
EDEN code. Typically items to look for in the log file include variables that may
need to be declared as symbol inputs and functions for which translation is not yet
available.

After you have translated and fine-tuned the Visual Basic code, you will need to
compile the symbol and test it in the software. When testing, verify the accuracy of
the graphics and the placement of the symbol ports. For information on loading the
symbol into the software, refer to Add a Symbol to Reference Data, page 105.

The created Visual Basic project should compile and generate the symbol correctly.
However, in many cases the symbol will need some manual edits. These
modifications are required in certain circumstances as described in EDEN Translator
Required VB Editing, page 156. The translator does not do a 100% translation.

A product can be purchased from CAXperts™ (http://www.caxperts.com) that is an


alternative to PDS Eden symbol translator. The product is CAXperts 3D
SymbolDesigner™. The product contains functionality to translate PDS symbols to
SmartPlant 3D symbols.

Related Topics
• Creating Part Occurrence Symbols in Visual Basic: An Overview, page 104
• EDEN Translator Command Line Structure, page 153
• EDEN Translator Example, page 160
• EDEN Translator Outputs, page 155
• EDEN Translator Required VB Editing, page 156
• EDEN Translator Workflow, page 152

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 151


Creating Part Occurrence Symbols in Visual Basic: An Overview

EDEN Translator Workflow


The PDS EDEN symbol translator (EDEN2SP3D.EXE) is located in [Product
Directory]\CatalogData\PDSTranslator\Bin. The program takes command line
arguments as inputs. The steps to translate an EDEN symbols are:
1. Create a new folder under [Product Directory]\CatalogData\Symbols (or any
other location as appropriate) to hold the new Visual Basic symbol code. We
recommend that you use the name of the symbol for the folder name.
2. Copy the EDEN Model Graphics (".mg") file to this location.
3. Run the EDEN2SP3D executable with the corresponding command line
arguments. We strongly recommend that you create a small batch file for this
purpose so that the information can be easily edited and run again in case of
errors. For more information about the outputs, see EDEN Translator Outputs,
page 155.
4. Modify the generated Visual Basic symbol, if needed, and test whether the
symbol places correctly. For more information, see EDEN Translator Required
VB Editing, page 156.

Related Topics
• Converting PDS EDEN to SmartPlant Visual Basic Symbols: An Overview, page 151

152 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

EDEN Translator Command Line Structure


The EDEN symbol translator accepts command line inputs. The explanation for the
generic command line arguments and the discipline specific arguments are:

<EDENSymbol> this is the filename of the EDEN symbol.

<SP3DProjectName> the VB project name to be generated

<SP3DSymbolName> the VB symbol name to be generated

<Author> the name of the author

Piping
[Product Directory]\Programming\Programming\Example
Code\PDSTranslator\EDEN2SP3D\Template_Piping\EDEN2SP3D.exe EDENPiping
<EDENSymbol> <SP3DProjectName> <SP3DSymbolName> <Author>
<PDSTranslatorExcelFile> <PDSModelCode> <SP3DTabName>

EDENPiping denotes that this is a Piping symbol. This should not be changed.

<PDSTranslatorExcelFile> the filename (with full path) to the PDS translator excel
file.

<PDSModelCode> the PDS model code in the "Physical Data" sheet of the PDS
translator.

<SP3DTabName> the SmartPlant3D Tab Name in the "Physical Data" sheet of the
PDS translator.

Equipment
[Product Directory] \Programming\Programming\Example
Code\PDSTranslator\EDEN2SP3D\Template_Piping\EDEN2SP3D.exe
EDENEquipment <EDENSymbol> <SP3DProjectName> <SP3DSymbolName>
<Author>

EDENEquipment denotes that this is an Equipment Symbol. This should not be


changed.

Electrical
[Product Directory] \Programming\Programming\Example
Code\PDSTranslator\EDEN2SP3D\Template_Piping\EDEN2SP3D.exe
EDENElectrical <EDENSymbol> <SP3DProjectName> <SP3DSymbolName>
<Author>

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 153


Creating Part Occurrence Symbols in Visual Basic: An Overview

EDENElectrical denotes that this is an Electrical Symbol. This should not be


changed.

Examples
The following are examples of using the tool:

[Product Directory] \Programming\Programming\Example


Code\PDSTranslator\EDEN2SP3D\Template_Piping\EDEN2SP3D.exe EDENPiping
I15AZ.mg SP3DGlobeValveF CGlobeValveF John
"M:\CatalogData\PDSTranslator\Docs\Piping Translation Rules.xls" GLO
GlobeValve

[Product Directory] \Programming\Programming\Example


Code\PDSTranslator\EDEN2SP3D\Template_Piping\EDEN2SP3D.exe.exe
EDENEquipment e405.eqp Pump PumpServices John

[Product Directory] \Programming\Programming\Example


Code\PDSTranslator\EDEN2SP3D\Template_Piping\EDEN2SP3D.exe
EDENElectrical thl SP3DElectricalSymbol HTrayElbow John

Related Topics
• Converting PDS EDEN to SmartPlant Visual Basic Symbols: An Overview, page 151

154 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

EDEN Translator Outputs


When the translator finishes running, you will find the following outputs:

• <SP3DProjectName>.vbp the Visual Basic symbol project file


• <SP3DSymbolName>.cls the Visual Basic symbol class file
• CSimplePhysical.cls the class file for the "SimplePhysical" aspect.
The translator also generates a log file, <SP3DProjectName>.log, that contains any
errors or warnings and reports on the parsing of the EDEN code.

Related Topics
• Converting PDS EDEN to SmartPlant Visual Basic Symbols: An Overview, page 151

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 155


Creating Part Occurrence Symbols in Visual Basic: An Overview

EDEN Translator Required VB Editing


Depending on the graphics and the code in the EDEN file, you may need to make
some modifications after the utility finishes translating the EDEN code to Visual
Basic code. These edits are due to some of the limitations of the translator due to the
dissimilarities in the way a symbol is defined in EDEN and the way in which a
symbol is defined in Visual Basic. Known issues are identified below.

Symbol Inputs in EDEN (Dimension_* variables)


EDEN has some general purpose variables that are used to store certain user defined
values. These variables will most probably be symbol inputs in Visual Basic.
Whenever such variables are encountered, the translator automatically treats them as
symbol Inputs. For example:
height = Dimension_34 - Dimension_37
The translator generates the code as follows:
Dim height As Variant
height = Dimension(34) - Dimension(37)
It also automatically adds the symbol inputs:
m_oSymbolHelper.AddInputDef 3, "Dimension(34)", "Dimension(34)", 3
m_oSymbolHelper.AddInputDef 4, "Dimension(37)", "Dimension(37)", 4
Note, that in Visual Basic the symbol input can be called by some other name, say,
"ImpellerDiameter", "PumpHeight", and so forth. You will have to modify the name
of the input to match the one that is defined in the excel data files. For example, you
can modify the generated code as follows:
m_oSymbolHelper.AddInputDef 3, "ImpellerDiameter",
"ImpellerDiameter", 3

Connect Points with Cylinder (Piping)


In EDEN, a cylinder is drawn separately from the Connect Point. However, in Visual
Basic there is a mechanism to draw the Cylinder along with the Nozzle (that is, use
the length property of the nozzle). It is not possible for the translator to determine
which connect point in EDEN goes with which cylinder. Therefore, the translator
simply translates the code as is. Thus, it generates two overlapping cylinders in
Visual Basic. This overlap is just a runtime overhead of drawing an extra cylinder for
each nozzle. You may want to remove the code that draws the graphic for the cylinder
if you are sure that the graphic for the nozzle will suffice to represent the symbol and
thus the extra cylinder is redundant. You will also have to remove the output
declaration in the symbol initialize, if you choose to do this.

If-Then-Else Conditions
EDEN does not require you to declare all the outputs of a symbol beforehand.
However, in Visual Basic you are required to list all the outputs of a symbol in the

156 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

initialization of the User Symbol Services object. If some graphics are drawn within
an If-Then-Else condition, then the translator has no way of knowing which object
should be drawn at runtime. The current implementation of the translator is such that
it lists all the objects in the outputs. You are required to modify the code depending
upon which outputs will be used. For example:

The EDEN code looks like this:


If ( Body_OD_1 .EQ. Body_OD_2 ) Then
Call Draw_Cylinder_With_Capped_Ends ( length, Body_OD_1 )
Else
Call Draw_Cone_With_Capped_Ends ( length, Body_OD_1, Body_OD_2 )
Endif
Depending upon the condition, either a cylinder or a cone will be drawn, but not both.
The translator generates the Visual Basic code as:
If (oNozzleData(1).dPipeDiameter = oNozzleData(2).dPipeDiameter)
Then
oT4x4Temp.LoadIdentity
oT4x4Temp.IndexValue(12) = length
Dim oCylinderCapped2 As Object
Set oCylinderCapped2 = PlaceCylinder(m_OutputColl, oOriginPos,
oT4x4Temp.TransformPosition(oOriginPos),
CDbl(oNozzleData(1).dPipeDiameter), True
oCylinderCapped2.Transform oT4x4Current
oOutputCol.Add oCylinderCapped2
oT4x4Current.MultMatrix oT4x4Temp
Else
oT4x4Temp.LoadIdentity
oT4x4Temp.IndexValue(12) = length
Dim oConeCapped1 As Object
Set oConeCapped1 = PlaceCone(m_OutputColl, oOriginPos,
oT4x4Temp.TransformPosition(oOriginPos),
CDbl(oNozzleData(1).dPipeDiameter) / 2,
CDbl(oNozzleData(2).dPipeDiameter) / 2, True)
oConeCapped1.Transform oT4x4Current
oOutputCol.Add oConeCapped1
oT4x4Current.MultMatrix oT4x4Temp
End If
The translator also adds both the outputs in the symbol initialization:
m_oSymbolHelper.AddOutputDef 1, "oCylinderCapped1",
"oCylinderCapped1", 1
m_oSymbolHelper.AddOutputDef 2, "oCylinderCapped2",
"oCylinderCapped2", 1
This causes a problem at runtime because one of the outputs will be "Nothing" at
runtime. To avoid this problem, remove the extra output as follows:
m_oSymbolHelper.AddOutputDef 1, "oCylinderorCone1",
"oCylinderorCone1", 1

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 157


Creating Part Occurrence Symbols in Visual Basic: An Overview

Note
• Remember that you will also have to edit the
m_oSymbolHelper.NumOutputs (in the same initialize method)
appropriately.
The symbol graphics code may also be modified for better readability, however the
code will function even if it is not modified.

Note
• In some cases, where the statements in the If-Then-Else are more
complex, then more modifications may be necessary. Example of this may
be when two graphics are drawn in the "if" case and only one is drawn in
the "else" case.

Approximations to Zero
Visual Basic symbols have difficulty in drawing cones with zero radii. In these cases,
the generated code will compile successfully, however, at runtime it may raise some
problems from the math calculations. This is avoided by changing the value of zero to
a value that is very close to zero. For example:
Dim diameter As Variant
diameter = DELTA_TOLERANCE ' 0#
Set oCone1 = PlaceCone(..) ' this call uses the `diameter'
variable
In the above code, a value of zero is replaced with a value of "0.00001". The
DELTA_TOLERANCE constant is defined for this purpose.

Aspects (Equipment)
Symbols in Equipment can have aspects, and each graphic that is drawn can belong to
one or many aspects. In Visual Basic we handle aspects by having separate ".cls" file
for each aspect (for those symbols not using SmartEquipment). The translator does
not generate separate code for each aspect. Thus, the code generated will not contain
any information on the aspects. All the code generated will belong only to the
SimplePhysical aspect. You will have to cut, copy and paste portions of the code into
different aspects as needed.

Nozzles (Equipment)
Equipment nozzles are now defined with a PlaceHolder in the symbol file and the
actual nozzle is placed in a "_Def.cls" file. The translator does not generate this "Def"
file automatically. You will have to generate this file either with the wizard or by
copying this file from another symbol and editing it as needed.

Draw Complex Surface


The Draw Complex Surface primitive does not add the symbol inputs to the Initialize
method in the USS symbol object. This is because several Draw Complex Surface,

158 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Draw Line, and Draw Arc calls result in a single surface being drawn and thus adding
the output automatically is not supported at this time. However, you can add the
output as follows:
m_oSymbolHelper.AddOutputDef 1, "ComplexSurface1",
"ComplexSurface1", 1
Note
• Remember that you will also have to edit the
m_oSymbolHelper.NumOutputs (in the same initialize method)
appropriately.

Removal of User Input Code (Equipment)


The Equipment EDEN modules have code that is related with getting and displaying
some information from/to the user through the forms interface. This code has no
meaning in Visual Basic and this should be removed from the Visual Basic symbol
code. This code is generally contained within a Do…Loop statement and looks
similar to this:
Do While (accepted = 0) If (LAST_INP_TYPE = USER_KEYIN) Then .. ..
Loop
Related Topics
• Converting PDS EDEN to SmartPlant Visual Basic Symbols: An Overview, page 151

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 159


Creating Part Occurrence Symbols in Visual Basic: An Overview

EDEN Translator Example


This section contains an example workflow for converting a EDEN piping symbol.

To find out what EDEN modules to extract, you must assess the source EDEN in the
PDS Graphic Commodity Library, and select the required Model Parametric Shape
files for conversion. Interference Parametric Shape EDEN, Symbol Processor EDEN,
Physical Data Definitions EDEN and User Function EDEN are not required for
conversion. This example will convert the symbol for a standard full port globe valve.
The PDS Model Code for a standard globe valve is GLO. This symbol is used in the
example to determine which EDEN Symbol Processor is required for extraction and
conversion.

Determine the EDEN Module (Option 1)


1. Start PDS.
2. Select Reference Data Manager.
3. Select Graphic Commodity Library Manager.
4. Flip the toggle to Sub-string, and then type GLO.
5. Select Revise Data.
6. Select the GLO Symbol Processor from the list.
7. Click Accept . The system displays the EDEN module.

160 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

8. In the code, find the "parametric_shape" definition. In this example, "V11" is the
module that should be extracted and converted.

Determine the EDEN Module (Option 2)


1. Choose the module to convert, in this case "GLO".
2. Find the definition of the model code "GLO" in the PDS Piping Component Data
Reference Data Guide.
3. In Appendix B of the guide, find the record for 6Q1C11, [2-way] globe valve (in-
line).
4. Find the sub-definition for a Regular Pattern, female ends, full port globe valve
(MC-GLOF).
5. Note that the definition notes SN=V11. This defines that V11 is the symbol
processor for the part.
-OR-
In Appendix C of the guide, find the corresponding symbol for a GLOF symbol.
Piping commodity symbol V11 notes a Model Code of V11.
Note
• This process assumes you have not customized the EDEN symbol. If you
have customized the EDEN symbol and user-defined Symbol Processors

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 161


Creating Part Occurrence Symbols in Visual Basic: An Overview

have been created, you must use Option 1 above and then review the
Symbol Processor EDEN to determine the actual code used to place the
physical representation of the part.

Extract the Required EDEN Module


1. Start PDS.
2. Select Reference Data Manager.
3. Select Graphic Commodity Library Manager.
4. Flip the toggle to Sub-string, and then type V11.
5. Click Extract Data.
6. Select the V11 Model Parametric Shape from the list.
7. Click Accept . The software extracts the module to the indicated folder.

Convert the Extracted PDS Piping EDEN Module


1. Create a new folder for the conversion files.
2. Copy the extracted EDEN module file to the new folder. You can rename the file
if needed, Pd_gc1 to V11 for example.
3. Optionally, copy the EDEN2SP3D.exe utility to the folder.
4. Optionally, copy the delivered conversion control file [Product
Directory]\CatalogData\PDSTranslator\Docs\Piping Translation Rules.xls to the
folder.
5. Open a command window (Start > Run then type in cmd and click OK).
6. Change folders to the new folder you created.
7. In the command window, type:
EDEN2SP3D.exe EDENPiping V11 SP3DGlobeValveNew CGlobeValveNew
User1 "Piping Translation Rules.xls" GLO GlobeValve
8. The conversion utility creates the following files:
CGlobeValveNew.cls
CSimplePhysical.cls
SP3DGlobeValveNew.log
SP3DGlobeValveNew.vbp

Review the Converted EDEN Code


The log file contains the messages regarding any errors found while parsing the
EDEN code. More importantly, the log file displays messages regarding variables that
may need to be declared as symbol inputs. The log file also contains the parsed tokens
so that any error in the parsing of the EDEN code itself can be detected easily. The
log file also lists any function for which translation is not yet available.

162 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

Compile the Visual Basic Project and Test the Symbol


Open the SP3DGlobeValveNew.vbp project file and compile a new .DLL file using
the File > Make SP3DGlobeValve.dll command. After the DLL is compiled, it will
be registered on the local machine.

After the symbol has been compiled it can be placed in the modeling environment and
then it can be verified for accuracy, especially regarding the placement of the ports in
the symbol. After the symbol has been verified to work, it can be integrated and then
used in a production environment. Open the VB project and review the converted
code. Amend as required per the limitations noted in EDEN Translator Required VB
Editing, page 156.

After you completely verify the new symbol, you need to distribute the DLL to all the
client computers. For more information, see Distributing Symbols Manually, page
109 or Distributing Symbols Automatically, page 107.

Related Topics
• Converting PDS EDEN to SmartPlant Visual Basic Symbols: An Overview, page 151

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 163


Creating Part Occurrence Symbols in Visual Basic: An Overview

Symbol Definitions: An Overview


The symbol definition is the contract that binds all the symbol objects together. The
symbol system uses the definition to check data integrity such as missing inputs,
outputs or a DLL version change. After symbols have been placed in the model or
created in the catalog, changes to the definition must only take place under controlled
conditions and be extensively tested.

It is possible to make a symbol definition flexible by declaring it as having a variable


number of inputs and/or outputs. You can do this by setting the
igCOLLECTION_VARIABLE property on the inputs and outputs collections. It is
also possible to state that certain inputs are optional with the
igDESCRIPTION_OPTIONAL property. The downside of a more flexible definition
is that the symbol system will be unable to use its internal caching mechanism and so
there will be a flavor created for each symbol placed.

Definition Options
igSYMBOL_ARGUMENTS_TYPE_MASK = The symbol arguments type
0x0000000f Bits Mask.
igSYMBOL_ARGUMENTS_TYPE_STATIC = The symbol definition has
0x00000000 no input argument.
igSYMBOL_ARGUMENTS_TYPE_PARAMETRIC = All the input arguments are
0x00000001 of type parameter. Only
numeric inputs.
igSYMBOL_ARGUMENTS_TYPE_ASSOC = Some of the input arguments
0x00000002 are not of type parameter. It
has at least one graphic
input.
igSYMBOL_CACHE_OPTION_MASK = 0x000000f0 The symbol arguments type
Bits Mask.
igSYMBOL_CACHE_OPTION_AUTOMATIC = The system checks if a result
0x00000010 is or is not sharable by
several symbols. The
symbol sub-system handles
the cache option: if it's a
static or a pure parametric
symbol, share the cache.
Otherwise, generate another
output collection.

164 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Creating Part Occurrence Symbols in Visual Basic: An Overview

igSYMBOL_CACHE_OPTION_SHARED = A result is sharable by


0x00000020 several symbols. If there's
already a placed symbol
occurrence with the same set
of arguments and same
active representations, share
the cached graphic outputs.
igSYMBOL_CACHE_OPTION_NOT_SHARED = A result is not sharable by
0x00000030 several symbols. Don't share
the cache of graphic outputs.
igSYMBOL_GEOM_OPTION_MASK = 0x00000f00 The symbol arguments drive
the symbol geometry Bits
Mask
igSYMBOL_GEOM_FREE = 0x00000100 The symbol arguments don't
drive the symbol geometry.
No external dependencies.
igSYMBOL_GEOM_DRIVEN_BY_ARG = The symbol geometry is
0x00000200 driven by input arguments.
igSYMBOL_GEOM_FIX_TO_ID = 0x00000600 The symbol geometry is
driven by input arguments.
igSYMBOL_ELLIPSIS_INPUTS = 0x00001000 The symbol has ellipsis
inputs.
igSYMBOL_METADATA_OPTION_MASK = Symbol Meta Data Option
0x00002000 Bits Mask.
igSYMBOL_STATIC_METADATA = 0x00000000 Meta data of the Symbol
definition are fully defined
by the associated USS
object (default option).
igSYMBOL_DYNAMIC_METADATA = 0x00002000 Meta data of the symbol
definition are edited and are
not similar to the one
provided by the associated
USS object.
igSYMBOL_SUPPORT_ONLY_OPTION_MASK = Symbol Support Only
0x00004000 Option Bits Mask.
igSYMBOL_SUPPORT_ONLY = 0x00000000 Definition is support only
(default value)
igSYMBOL_NOT_SUPPORT_ONLY = 0x00004000 Definition is NOT support
only.
igSYMBOL_POOL_DESC_OPTION_MASK = Symbol Pool description
0x000f0000 Option Bits Mask.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 165


Creating Part Occurrence Symbols in Visual Basic: An Overview

igSYMBOL_POOL_DESCRIPTORS = 0x00010000 Pool the descriptor objects


(inputs, outputs,
representation).
igSYMBOL_UNPOOL_DESCRIPTORS = Create a descriptor object
0x00020000 when requested instead of
getting it from a pool.
igSYMBOL_SUPPORT_UPDATE_OPTION_MASK Symbol Support Update
= 0x00400000 Option Bits Mask
igSYMBOL_SUPPORT_UPDATE = 0x00400000 Definition supports update.
igSYMBOL_NOT_SUPPORT_UPDATE = Definition is NOT support
0x00000000 Update (default value)

Flavors and the Flavor Manager


The symbol system has a caching mechanism for all symbols that share the same set
of input parameters and same set of outputs. By default the cache mechanism is
active. For more information, see cache option
(igSYMBOL_CACHE_OPTION_SHARED). A flavor object is created for each
unique set of parameters and each symbol placed using these same parameters is
connected to the flavor and uses the flavor's graphic objects for display. For this type
of 'cached' symbol, a flavor manager object is created and connected to the symbol
definition. The flavor manager keeps internal data about which flavors are currently
available. The flavor manager and flavors should be considered internal to the symbol
system. Any manipulation by external objects or programs can break the symbols
placed and compromise the model or catalog.

166 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


EDEN Functions Programming Reference

EDEN Functions Programming


Reference
The EDEN Functions Programming Reference provides documentation of the
geometry functions that can be found in the EDEN2SP3D.bas file. These functions
might be useful for manual editing following conversion of PDS EDEN symbols to
SmartPlant Visual Basic symbols.

DefineActiveOrientation Method
Description

The DefineActiveOrientation method sets the active orientation with respect to a


predefined value.

Syntax

Parameter Data Type Description


oNozzleData NozzleData Required. This argument specifies the nozzle data to be
set.
oT4x4Current IJDT4x4 Required. This argument specifies the current
transformation of the nozzle.
lPrimary Long Required. This argument specifies the primary
orientation.
lSecondary Long Required. This argument specifies the secondary
orientation.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 167


EDEN Functions Programming Reference

DefineNozzle Method
Description

The DefineNozzle method returns a nozzle according to the given part,


transformation, index, and type.

Syntax

Parameter Data Description


Type
oOutputColl Object Required. This argument specifies the pointer to the
graphic output to add into output collection so that the
resource manager and symbol definition can be accessed.
oPart IJDPart Required. This argument specifies the part to which the
nozzle belongs.
oT4x4Current IJDT4x4 Required. This argument specifies the current
transformation matrix of the point.
strNozzleString String Required. This argument specifies the name of the
nozzle.
lNozzleIndex Long Required. This argument specifies the index to which the
nozzle belongs in the collection.
INozzleType Long Required. This argument specifies the nozzle type as one
of the valid enumerated EDEN geometry types.

168 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


EDEN Functions Programming Reference

DefinePlacePoint Method
Description

The DefinePlacePoint method defines placement for a 3D point in space.

Syntax

Parameter Data Type Description


oOrientationPoint OrientationPoint Required. This argument specifies point's
orientation.
oPoint IJDPosition Required. This argument returns the position to
which the point is placed, allowing for a 3D
point in space to be modified.
oT4x4Current IJDT4x4 Required. This argument specifies the current
transformation matrix of the point.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 169


EDEN Functions Programming Reference

DefinePoint Method
Description

The DefinePoint method defines a 3D point in space according to the given


transformation, position object, and respective of the tolerance values to the reference
point.

Syntax

Parameter Data Type Description


oT4x4Current IJDT4x4 Required. This argument specifies the current
transformation matrix of the point.
oPoint IJDPosition Required. This argument specifies the object to which a
3D point in space can be modified.
oRefPoint IJDPosition Required. This argument specifies the object to which a
reference 3D point in space can be modified.
dDeltax Double Required. This argument specifies X-coordinate
tolerance value.

DeltaToleranceConstants
dDeltay Double Required. This argument specifies Y-coordinate
tolerance value.

DeltaToleranceConstants
dDeltaz Double Required. This argument specifies Z-coordinate
tolerance value.

DeltaToleranceConstants
lFlag Long Required. This argument specifies a Long value as flag.
Default = 0 (False).

170 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


EDEN Functions Programming Reference

DrawArc Method
Description

The DrawArc method creates an arc given the major and minor radius, the start angle,
and the sweep angle.

Syntax

Parameter Data Description


Type
oOutputColl Object Required. This argument specifies the pointer to the
graphic output to add into output collection so that the
resource manager and symbol definition can be accessed.
oT4x4Current IJDT4x4 Required. This argument specifies the current
transformation matrix.
dMajorRadius Double Required. This argument specifies the major radius - X-
axis direction.
dMinorRadius Double Required. This argument specifies the minor radius - Y-
axis direction.
dStartAngle Double Required. This argument specifies the beginning angle
from the major axis.
dSweepAngle Double Required. This argument specifies the angle that is
generally the difference between the ending and the
beginning parameters.
oOutputCol Collection Required. This argument specifies the output collection.

Remarks

The appearance of the sweep angle for an ellipse contrasts to that of a circle object
because the major and minor axis measurements are different.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 171


EDEN Functions Programming Reference

DrawComplexSurface Method
Description

The DrawComplexSurface method creates a complex surface geometry according to


the given arguments providing elements from two surface values.

Syntax

Parameter Data Description


Type
oOutputColl Object Required. This argument specifies the pointer to the
graphic output to add into output collection so that the
resource manager and symbol definition can be accessed.
lArg1 Long Required. This argument specifies the value for the first
surface.
lArg2 Long Required. This argument specifies the value for the second
surface.
oOutputCol Collection Required. This argument returns the output collection.

172 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


EDEN Functions Programming Reference

DrawLine Method
Description

The DrawLine method creates linear object according to the given transformation and
starting and ending positions.

Syntax

Parameter Data Type Description


oOutputColl Object Required. This argument specifies the pointer to the
graphic output to add into output collection so that the
resource manager and symbol definition can be
accessed.
oT4x4Current IJDT4x4 Required. This argument specifies the current
transformation matrix.
oFromPoint IJDPosition Required. This argument returns the first position to
which the point is placed for a line, allowing for a 3D
point in space to be modified.
oToPoint IJDPosition Required. This argument returns the second position to
which the point is placed for a line, allowing for a 3D
point in space to be modified.
oOutputCol Collection Required. This argument specifies the output collection.

InitializeGlobals Method
Description

The InitializeGlobals method initializes the place points and datum points of the
nozzle data.

Syntax

Parameter Data Type Description


oNozzleData NozzleData Required. This argument specifies the nozzle data to be
initialized.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 173


EDEN Functions Programming Reference

MoveAlongAxis Method
Description

The MoveAlongAxis method moves the current drawing position along the given axis
according to the given distance.

Syntax

Parameter Data Description


Type
oT4x4Current IJDT4x4 Required. This argument specifies the current drawing
transformation.
lAxisDirection Long Required. This argument specifies the axis direction as
one of the valid enumerated types.

lDistance Double Required. This argument specifies the distance value.

MoveToPlacePoint Method
Description

The MoveToPlacePoint method defines the move transformation for placement of a


3D point in space.

Syntax

Parameter Data Type Description


oPlacePoint OrientationPoint Required. This argument specifies the point's
placement orientation.
oT4x4Current IJDT4x4 Required. This argument specifies the current
transformation matrix of the point.

174 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


EDEN Functions Programming Reference

NozzleDefineDirectionVector Method
Description

The NozzleDefineDirectionVector method initializes the nozzle direction vector


according to the given EDEN geometry type.

Syntax

Parameter Data Type Description


oNozzleData NozzleData Required. This argument specifies the nozzle data to
be initialized.
lGeometryType Long Required. This argument specifies the EDEN
geometry type as one of the valid enumerated types.

NozzleInitialize Method
Description

The NozzleInitialize method initializes the nozzle data.

Syntax

Parameter Data Type Description


oPipeComponent IJDPipeComponent Required. This argument specifies the piping
component.
oNozzleData NozzleData Required. This argument specifies the nozzle
data to be initialized.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 175


EDEN Functions Programming Reference

NozzlePlace Method
Description

The NozzlePlace method places a nozzle and includes the origin of the nozzle ID=0.

Syntax

Parameter Data Type Description


m_OutputColl Object Required. This argument specifies the pointer to the
graphic output to add into the output collection so
that the resource manager and symbol definition can
be accessed.
oPart IJDPart Required. This argument specifies the part to which
the nozzle belongs.
oNozzleData NozzleData Required. This argument specifies the nozzle data to
be placed.
lNozzleId Long Required. This argument returns the nozzle's origin.
oPlacementPoint IJDPosition Required. This argument returns the position to
which the nozzle is placed.
oT4x4Current IJDT4x4 Required. This argument specifies the transformation
specification of the nozzle.
oNozzleCol Collection Required. This argument returns the nozzle collection
to which the placed nozzle belongs.
oOutputCol Collection Required. This argument returns the output
collection.

176 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


EDEN Functions Programming Reference

RotateOrientation Method
Description

The RotateOrientation method rotates the drawing position along the given axis by
the given angle.

Syntax

Parameter Data Description


Type
oT4x4Current IJDT4x4 Required. This argument specifies the current drawing
transformation.
lAxis Long Required. This argument specifies the axis as one of the
valid enumerated types.

dAngle Double Required. This argument specifies the angle.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 177


Using the Equipment Symbol Upgrade Wizard

Using the Equipment Symbol Upgrade


Wizard
The Equipment Symbol Upgrade Wizard allows you to upgrade SmartPlant 3D
version 5.0 Equipment symbols to Smart Occurrence-based Equipment symbols.
Smart Occurrence Equipment symbols provide better control of the Nozzles to the
design. Regular Equipment symbols require only one class for the symbol definition.
Upgraded Equipment symbols need an additional class for the custom assembly
definition. Also, the format of the spreadsheet is slightly different.

The upgraded symbols will have new ProgIDs. New part and part classes will be
generated to prevent overlap with existing Equipment symbols.

To take full advantage of the new functionality, you should upgrade the code of your
existing Equipment symbols.

Equipment in version 6.0 of SmartPlant 3D introduces a new set of functionality:

• Nozzle occurrence attributes (which allow you to edit nozzles of


equipment that come from the catalog) and properties can be controlled by
the code of the Equipment symbol.
• Standard Equipment and Designed Equipment concepts have been merged
and can be designed as any Equipment (shapes and nozzles can be added
after placement). A Designed Equipment is simply viewed as an empty
catalog Equipment.
• Equipment Component has been added as a new business object. An
Equipment Component is very similar to Equipment and can itself be
designed, but it can only be placed as a child of Equipment. An Equipment
Component is not allowed to place Equipment, old or new, as a child of a
new Equipment.

178 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Using the Equipment Symbol Upgrade Wizard

Introduction
The Equipment Symbol Upgrade Wizard upgrades regular version 5.0 Equipment
symbols to Smart Occurrence-based version 6.0 Equipment symbols. Smart
Occurrence-based Equipment gives better control of the Nozzles to the design. As
opposed to the regular Equipment symbols that require only one class for the symbol
definition, version 6.0 Equipment symbols require an additional class for custom
assembly definition. Also, the format of the spreadsheet is slightly different.

Before You Upgrade


1. Locate the directory that contains the .bas files referenced by the projects. This
directory can be the default one installed with the software or a private copied
directory. If it is private, copy basGeom3dPH.bas, FullyParametericFunPH.bas,
and Geometry3DPH.bas into this directory.
2. Open a new standard Visual Basic project.
3. Make sure that you have specified write access to your spreadsheets, the .bas files,
and all your project files and DLLs.
4. Make a backup of the input version 5.0 files.

Register and Launch the Equipment Symbol Upgrade


Wizard
Before you can use the Equipment Symbol Upgrade Wizard, you must register it as
follows:
1. Use Notepad to edit the file C:\Windows\vbaddin.ini.
2. Add SP3DeqpSymbolToSO.Wizard=1.
3. Open Visual Basic.
4. Click Add-Ins > Add-In Manager....
5. If editing vbaddin.ini fails to properly register the wizard, then you should
manually register SP3DEqpSymbolToSO.dll, located in the following default
path: C:\Program Files\SmartPlant\3D\Programming\Tools\Bin\ by running
regsvr32.
6. Select SP3D Equipment Symbol Upgrade and make sure that the
Loaded/Unloaded and Load on Startup boxes under Load Behavior are both
checked.
7. Click OK.
8. Click Add-Ins > SP3D Eqp Upgrade... to invoke the wizard.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 179


Using the Equipment Symbol Upgrade Wizard

Now you are ready to proceed with the following steps:

• Step 0 – Introduction, page 10


• Step 1 – Define Locations
• Step 2 – Search Equipment ProgIDs in Spreadsheets
• Step 3 – Search VB Project Files for ProgIDs
• Step 4 – Upgrade VB Projects and Spreadsheets
• Step 5 - Finish, page 187
Note: To override the default settings of the strings that are appended during the
upgrade process, you can edit the Registry with the following key string values:

Key: HKEY_CURRENT_USER\Software\VB and VBA Program


Settings\Microsoft Visual Basic AddIns
\SP3D EqpSymbolToSO Upgrade Wizard
String Values (equivalent to default):
AppendToPart, "_Asm"
AppendToProject, "Asm"
AppendToPartClass, "Asm"
AppendToNode, " Asm"
AppendToTopNodeUserName, " Assemblies"

Log Files
The wizard generates two log files during the upgrade process. These are:

SP3DV6UpgradeSO_<Time&Date>.log

SP3DV6UpgradeSO_<Time&Date>Checkin.log - contains the list of modified files if


a source control system is used.

The following are descriptions of results of the upgrade process:

Upgrade to the Visual Basic Code

Upgrade to the Excel Workbooks

Upgrade to the Equipment Component


1. You must perform a regular upgrade for equipment.
2. Create a new workbook (derived from the EquipmentComponent.xls file)
3. Move spreadsheets of part classes to become an Equipment Component into the
EquipmentComponent spreadsheet.

180 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Using the Equipment Symbol Upgrade Wizard

4. Change the ClassType in each spreadsheet to


"EquipmentComponentAssemblyClass".
Edit the Visual Basic project to change the CAD class (ends in
Def) entry as follows, then recompile:
m_oEquipCADHelper.OccurrenceRootClass = orcEquipment 'original
m_oEquipCADHelper.OccurrenceRootClass = orcEquipmentComponent
'after editing
Note: The ProgID for Equipment cannot be reused for an Equipment Component.
Therefore, you must upgrade some parts of Equipment Component before you
perform a bulk load.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 181


Using the Equipment Symbol Upgrade Wizard

Define Locations

Equipment Symbol Upgrade Wizard - Step 1


This step captures the various inputs for the upgrade process.

First you need to select the spreadsheets of your Equipment symbols that need to be
upgraded. Browse to the root location of the original symbols source and to the target
locations for the source and binary files of the upgraded symbols. Select the location
where your upgrade log file will be generated.

Remember that you must have write access to all of the files.

182 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Using the Equipment Symbol Upgrade Wizard

Search Equipment ProgIDs in Spreadsheets

Equipment Symbol Upgrade Wizard - Step 2


A search is performed on all the spreadsheets for bulk load that were selected in the
first step. Only the workbooks containing spreadsheets for Equipment are retained for
upgrade. The symbol definition ProgIDs are acquired for the next step.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 183


Using the Equipment Symbol Upgrade Wizard

Search VB Project Files for ProgIDs

Equipment Symbol Upgrade Wizard - Step 3


The search in this step is performed on all the files that are located at the root location
for symbol source code that you specified in the Step 1. Only Visual Basic projects
implementing ProgIDs found during Step 2 are retained for upgrade.

184 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Using the Equipment Symbol Upgrade Wizard

Upgrade VB Projects and Spreadsheets

Equipment Symbol Upgrade Wizard - Step 4


This step performs the actual symbol upgrade.

The Visual Basic projects are copied, renamed, and upgraded. Each nozzle or part
defined in the symbol is replaced by a matching place holder. For each project, a new
Public Class used as a Custom Assembly Definition is added and code is created to
place real nozzles.

The list view displays the actions, the status, and the time.

Note: This step can take a few minutes or as much as several hours to process
depending on the number of projects that need to be upgraded and compiled.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 185


Using the Equipment Symbol Upgrade Wizard

186 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Using the Equipment Symbol Upgrade Wizard

Finish
The Equipment spreadsheets have been copied and updated for the parts and part
classes using the ProgIDs that have been upgraded.

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 187


Index

Index
ActiveX components CreateModelDatabaseObject method
abstract class, 34 ProjectMgmtEntitiesFactory, 60
client, 34 CreatePermissionGroup method
DLLs, 34 ProjectMgmtEntitiesFactory, 62
implementation, 34 CreateProjectRoot method
AddAccessControlRule method ProjectMgmtEntitiesFactory, 59
IJAccessRuleHelper, 67 CreateReportsDatabaseObject method
AddNamingRelations method ProjectMgmtEntitiesFactory, 64
customizing, 45 CreateSupport method
architecture HgrDisciplineType, 48
business objects, 12 creating
client, 12 symbols, 104, 110, 112, 117
metadata, 12 custom aspects, 148
middle, 12 custom commands
server, 12 TransactionManager, 32
three-tier, 12 undo, 32
aspects custom component, 110
custom, 148 Custom Name Rule
AttachPDSProject method CNameRuleAE object, 38
ProjectMgmtEntitiesFactory, 58 customizing, 36
axis orientation, 135 custom supports
BackupPlantDatabases method CreateSupport method, 48
IJBackupRestoreHelper, 70 CreateSupport method example, 53
binary compatibility, 20 customizing, 48
binding HgrDisciplineType, 48
early, 20 HgrSupProgAutoComp, 48
late, 20 IJHgrAutomation, 48
body of symbols, 125 IJHgrSupport, 51
CAB files, 107 ModifySupport method, 51
cable trays, 127 customizing
catalog database valves, 142 naming rules, 35
classification of symbols, 118, 119 customizing Part Definition Wizard output, 126
CNameRuleAE object debugging your code
active entity, 38 TaskHost, 18
Custom Name Rule, 38 DefineActiveOrientation, 167
customizing, 38 DefineNozzle, 168
command priorities DefinePlacePoint, 169
stacking, 23 DefinePoint, 170
suspendable, 23 definition properties, 120
ComputeName method definitions
customizing, 36 symbols, 164
conduit, 127 differences between parametric and regular symbols,
converting 139
PDS symbols to SP3D, 151, 152, 153, 155, 156 directions, 135
PDS symbols to SP3D examples, 160 distributing symbols
CreateAccessControlRule method automatically, 107
ProjectMgmtEntitiesFactory, 63 manually, 109
CreateCatalogDatabaseObject method divisions, 130
ProjectMgmtEntitiesFactory, 61 DrawComplexSurface, 172
CreateFolder method DrawLine, 171, 173
ProjectMgmtEntitiesFactory, 61 EDEN symbols, 151, 152, 153, 155, 156, 160

188 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Index

command line structure, 153 IJBackupRestoreHelper


translator outputs, 155 BackupPlantDatabases method, 69
VB modifications, 156 RestorePlantDatabases method, 69
workflow, 152 IJDNamingRulesHelper
workflow examples, 160 customizing, 44
electrical determine unique name, 44
cable trays, 127 IJHgrAutomation
conduit, 127 HgrSupProgAutoComp, 48
parts versus features, 127 IJHierarchy
reducers, 127 GetDisplayChildren method, 65
vectors, 127 GetParent method, 65
end preparations, 135 IJNameCounter interface
Equipment Symbol Upgrade Wizard customizing, 40
log files, 180 IJNameRule interface
upgrading symbols, 178 customizing, 36
errors IJNameRuleAE interface
Error Log Component, 24 customizing, 38
handling, 24 InitializeGlobals, 173
example using String type, 149 inputs, 150
example using SymbolHelper, 145 insulation, 135
examples IsGeneratedNameUnique
Vertical Vessel Supports Placement Example, 89 customizing, 47
Excel workbooks, 118, 119 determine unique name, 47
Face to Center Versus Face to Face, 135 limitation of PDS translation
features, 127 discussed, 156
first input, 150 ModifySupport method
fixed properties, 112, 120, 121 IJHgrSupport, 51
flanges, 135 MoveAlongAxis, 174
flavors, 164 MoveToPlacePoint, 174
Frozen property NameGeneratorService object
customizing, 38 customizing, 40
GetActiveNamingRule method implements IJNameCounter, 40
customizing, 45 naming rules
GetCount method adding library references, 35, 36, 38
customizing, 41 adding to Catalog, 35
GetCountEx method AddNamingRelations method, 45
customizing, 42 CNameRuleAE object, 38
GetCountRange method COM, 35
customizing, 43 ComputeName method, 36
GetDisplayChildren method Custom Name Rule, 36
IJHierarchy, 66 customizing, 35
GetEntityNamingrulesGivenName method determine unique name, 44, 47
customizing, 46 Frozen property, 38
GetEntityNamingRulesGivenProgID method GetActiveNamingRule method, 45
customizing, 46 GetCount method, 41
GetNamingParents method GetCountEx method, 42
customizing, 37 GetCountRange method, 43
GetParent property GetEntityNamingrulesGivenName method, 46
IJHierarchy, 66 GetEntityNamingRulesGivenProgID method, 46
graphical output, 112 GetNamingParents method, 37
HVAC IJDNamingRulesHelper, 44
divisions, 130 IJNameCouter interface, 40
nozzles, 130 IJNameRule interface, 36
specifications, 130 IJNameRuleAE interface, 38
IJAccessRuleHelper implements IJDNamingRulesHelper, 44
AddAccessControlRule method, 66 IsGeneratedNameUnique, 47

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 189


Index

NameGeneratorService object, 40 IJBackupRestoreHelper, 69


NamingParentsString property, 39 IJHierarchy, 65
NamingRulesHelper object, 44 Ingr Sp3d ProjectMgmtEntities 1.0 Type Library,
NamingParentsString property 56
customizing, 39 Parent property, 66
NamingRulesHelper object ProjectMgmtEntitiesFactory, 56
customizing, 44 RestorePlantDatabases method, 71
implements IJDNamingRulesHelper, 44 Project Management
nested symbols, 110 access control rules, 54
NozzleDefineDirectionVector, 175 backup/restore, 54
NozzleInitialize, 175 customizing, 54
NozzlePlace, 176 traverse permision groups, 54
nozzles, 130 traverse project folders, 54
axis orientation, 135 ProjectMgmtEntitiesFactory
end preparations, 135 CreateAccessControlRule method, 56
Face to Center Versus Face to Face, 135 CreateCatalogDatabaseObject method, 56
flanges, 135 CreateFolder method, 56
insulation, 135 CreateFolderParent method, 56
port indexes, 135 CreateModelDatabaseObject method, 56
vectors and directions, 135 CreatePermissionGroup method, 56
occurrence properties, 112, 122, 123 CreateProjectRoot method, 56
output information for symbols, 124 CreateReportsDatabaseObject method, 56
parametric symbols projects for symbols, 117
differences, 139 properties
parametric valves, 142 symbols, 121, 123
part class templates, 119 reducers, 127
part classes for symbols, 118 references, 17
Part Definition Wizard, 114 setting, 27, 29
PartFacelets.IJDPart, 150 resources, 17
parts, 127 RestorePlantDatabases method
as first input, 150 IJBackupRestoreHelper, 71
PDS symbols, 151, 152, 153, 155, 156, 160 RetrieveParameters function, 150
command line structure, 153 RotateOrientation, 177
translator outputs, 155 samples
VB modifications, 156 using the Command Wizard, 92
workflow, 152 Vertical Vessel Supports Placement, 92
workflow examples, 160 specifications for HVAC, 130
port indexes, 135 String type
ports, 125 example, 149
support parts, 132 SymbolHelper
preface, 7 example, 145
programming notes for Visual Basic, 127 SymbolRepid, 148
project management symbols
AddAccessControlRule method, 67 adding to reference data, 105
AddLocation method, 57 aspects, 124
AttachPDSProject method, 58 converting PDS to SP3D, 151, 152, 153, 155, 156
BackupPlantDatabases method, 70 converting PDS to SP3D examples, 160
CreateAccessControlRule method, 63 creating, 104, 110, 112, 114
CreateCatalogDatabaseObject method, 61 creating with Visual Basic, 115, 118, 120
CreateFolder method, 61 definitions, 164
CreateModelDatabaseObject method, 60 distributing automatically, 107
CreatePermissionGroup method, 62 distributing manually, 109
CreateProjectRoot method, 59 flavors, 164
CreateReportsDatabaseObject method, 64 geometry, 125
GetDisplayChildren method, 66 inputs, 126
IJAccessRuleHelper, 66 nested, 110

190 SmartPlant 3D/SmartMarine 3D Programmer’s Guide


Index

occurrence properties in Visual Basic, 122 using the Command Wizard


outputs, 124, 125, 126 samples, 92
variables, 120 Vertical Vessel Supports Placement, 92
TaskHost valves
debugging your code, 18 creating from catalog database, 142
templates for part classes, 119 creating from parts, 142
type libraries creating parametrically, 142
referencing, 26 variable properties, 122
undo vectors, 127, 135
custom commands, 32 Vertical Vessel Supports Placement
TransactionManager, 32 using the Command Wizard, 92
upgrade to the Equipment Component Vertical Vessel Supports Placement Example
upgrading symbols, 180 overview, 89
upgrading symbols Visual Basic
Equipment Symbol Upgrade Wizard, 178 libraries, 117
getting started, 179 occurrence properties, 122
log files, 180 programming notes, 127
register and launch the wizard, 179 projects, 117
upgrade to the Equipment Component, 180 variables, 120
using Visual Basic projects, 114, 115
Speedy References tool, 27, 29 symbols, 105

SmartPlant 3D/SmartMarine 3D Programmer’s Guide 191