SP3DProgGuide

(1)

SmartPlant 3D/SmartMarine 3D

(2)

Copyright

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.

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.

(3)

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

(5)

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

(6)

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

Search VB Project Files for ProgIDs...184

Upgrade VB Projects and Spreadsheets ...185

Finish ...187

(7)

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.

(8)

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

(9)

Documentation Comments

(10)

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.

(11)

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

(12)

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.

(13)

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.

(14)

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

(15)

(16)

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

(17)

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

(18)

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

(19)

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.

(20)

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.

(21)

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

(22)

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

(23)

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.

(24)

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.

(25)

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.

(26)

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

(27)

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,

(28)

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.

(29)

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:

(30)

• 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

(31)

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.

(32)

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

(33)

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

(34)

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

(35)

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

(36)

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)

(37)

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

(38)

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

(39)

NamingParentsString Property

Description

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

Signature

NamingParentsString As String

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

(40)

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.

(41)

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 Type

Description

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.

(42)

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

Description

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.

(43)

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

Description

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

(44)

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.

(45)

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)

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)

pDispEntity Object Required. The new object to be named.

pNameRuleHolder IJDNameRuleHolder Required. The interface of the naming

(46)

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)

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)

strEntityProgID String Required. The ProgID of the new object to be named.

NamingRules IJElements Required. The interface of the first object in the

(47)

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

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

(48)

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],

(49)

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.

(50)

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

(51)

ModifySupport Method

Description

This method modifies the support object.

Signature

Function ModifySupport(oSupport, [oParent], [dblMaxLoad], [oSupportedObjects], [oSupportingObjects], [oLocation], [bRule], [oSupportAssembly], [strSupportName], [strSupportRuleName]) As Object

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.

(52)

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

(53)

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

'////////////////////////////////////////////////////////////////////////

(54)

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.

(55)

IJBackupRestoreHelper BackupPlantDatabases

(56)

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

(57)

AddLocation Method

Description

The method creates a Location object.

Signature

Function AddLocation(pResourceManager As Unknown) As Object

Description

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

(58)

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

Description

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.

(59)

CreateProjectRoot Method

Description

This method creates the Plant/Ship object.

Signature

Function CreateProjectRoot(pResourceManager, pIJLocation) As Object

Description

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

(60)

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

Type

Description

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

(61)

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

Type

Description

pResourceManager Unknown Required. Resource Manager of the Project Connection

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

Error Codes

E_ACCESSDENIED = -2147024891

CreateFolder Method

Description

This method creates the Folder object.

Signature

(62)

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

Description

pResourceManager Unknown Required. Resource Manager of the Model or Catalog connection depending on whether created under plant/ship or catalog

(63)

• 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.

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

Description

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

• For Plant/Ship or Catalog objects = Project connection

• For Permission Groups under Model/Catalog = Model/Catalog connection

(64)

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

Description

pResourceManager Unknown Required. Resource Manager of the Project Connection

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

Error Codes

lDISK_NO_SPACE = -2147216355 E_ACCESSDENIED = -2147024891

(65)

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

(66)

GetDisplayChildren Method

Description

This method returns the children of the object.

Signature

Function GetDisplayChildren(pResourceManager) As IJDObjectCollection

Description

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

SP3DProgGuide

SmartPlant 3D/SmartMarine 3D

Table of Contents

Preface

SmartPlant 3D/SmartMarine 3D Product

Documentation

Administrative Guides

Documentation Comments

Introduction

Visual Basic .NET™

What's New in Programming Resources

Software Architecture

Three-Tier Architecture

Client Tier

Middle (Business) Tier

Server Tier

Getting Started

Resources and References

Printed Documentation

Debugging Your Code

Adding the TaskHost Project to your Project

Binding and Binary Compatibility

Early Binding

Late Binding

Command Priorities

Error Handling

Error Log Component

Referencing Data Type Libraries

Using the References Tool

Errors Occurring with Visual Basic 6

Creating Custom Commands

Undo Functionality

Customizing the Software

Using ActiveX Components

Creating an Implementation

Customizing Naming Rules

Custom Name Rule

IJNameRule Interface

ComputeName Method

GetNamingParents Method

CNameRuleAE Object

IJNameRuleAE Interface

Frozen Property

NamingParentsString Property

NameGeneratorService Object

IJNameCounter Interface

GetCount Method

GetCountEx Method

GetCountRange Method

NamingRulesHelper Object

IJDNamingRulesHelper Interface

AddNamingRelations Method

GetActiveNamingRule Method

GetEntityNamingRulesGivenName Method

GetEntityNamingRulesGivenProgID Method

IsGeneratedNameUnique Method

Customizing Hangers and Supports

IJHgrAutomation Interface

CreateSupport Method

ModifySupport Method

CreateSupport Method Example

Customizing Project Management

ProjectMgmtEntitiesFactory Object

AddLocation Method

AttachPDSProject Method

CreateProjectRoot Method

CreateModelDatabaseObject Method

CreateCatalogDatabaseObject Method

CreateFolder Method

CreatePermissionGroup Method

CreateAccessControlRule Method

CreateReportsDatabaseObject Method

IJHierarchy Interface

GetDisplayChildren Method

Parent Property