AspenBasicEngV7 3 Admin

Administrator Reference Guide

Aspen Basic Engineering

Version: V7.3March 2011

Copyright © 1981 – 2011 Aspen Technology, Inc. All rights reserved.

Aspen Basic Engineering™ and the aspen leaf logo are trademarks or registered trademarks of Aspen Technology,Inc., Burlington, MA.

All other brand and product names are trademarks or registered trademarks of their respective companies.

This documentation contains AspenTech proprietary and confidential information and may not be disclosed, used,or copied without the prior consent of AspenTech.

ASPENTECH MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WIT RESPECT TOTHIS DOCUMENTATION, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE.

Aspen Technology, Inc.200 Wheeler RoadBurlington, MA 01803-5501USAPhone: (781) 221-6400Toll free: (888) 996-7001Website http://www.aspentech.com

Contents iii

Contents

1 About this Guide...................................................................................................1

About Aspen Basic Engineering ..........................................................................1Related Documentation.....................................................................................1Technical Support ............................................................................................2

Online Technical Support Center ..............................................................2Phone and E-mail ...................................................................................3

2 Knowledge Bases and the Rules Editor.................................................................5

Overview of KB API ..........................................................................................6Rules ....................................................................................................7Methods................................................................................................9Events ................................................................................................ 11Demons .............................................................................................. 12Sorts and Filters................................................................................... 15

Writing Compiled KB Code............................................................................... 19AZQDataService Interface ..................................................................... 19Registering KB Items ............................................................................ 20Defining Methods ................................................................................. 21Defining Rules ..................................................................................... 22Defining Demons.................................................................................. 22Defining Events.................................................................................... 24Defining Sorts...................................................................................... 24Defining Filters .................................................................................... 25Global Variables ................................................................................... 26Handling Arguments ............................................................................. 26Implementing Data Service Modules in .NET............................................ 26Installation and the Config File............................................................... 27

Writing Rules Editor Script............................................................................... 28Writing the KB Module .......................................................................... 28Compiling the KB Module ...................................................................... 33Loading the KB Module ......................................................................... 33Running the KB Module......................................................................... 33Events ................................................................................................ 34Dynamic Properties .............................................................................. 39Configuration File ................................................................................. 40Rules Editor Menus............................................................................... 41Rules Editor Toolbar ............................................................................. 44

AZDBQuery Library Object Reference................................................................ 44AZQKBDialog ....................................................................................... 44

3 Datasheets and the Datasheet Definer ..............................................................47

Datasheets .................................................................................................... 47Datasheet Definer .......................................................................................... 48

iv Contents

How Does the Datasheet Definer Create a Datasheet? ........................................ 49Starting the Datasheet Definer......................................................................... 49Datasheet Definer Menus ................................................................................ 50Datasheet Definer Toolbar............................................................................... 51Datasheet Definer Browser .............................................................................. 52

Browser Menu Items............................................................................. 53Datasheet Editor Template Migration Tool ......................................................... 54

Getting Started .................................................................................... 54Creating a ZTX Template for each Custom Datasheet Template.................. 55Migrating Server-Cached Templates ....................................................... 56

4 Preparing Datasheets in Microsoft Excel ...........................................................59

Fields............................................................................................................ 59Value Fields................................................................................................... 60

Inserting Value Fields ........................................................................... 60Value Field Routes................................................................................ 60Value Field Options............................................................................... 61Multi-line Fields.................................................................................... 62Field Cases .......................................................................................... 62Overspill Fields .................................................................................... 62

Quantity Type Fields....................................................................................... 63Inserting Quantity Type Fields ............................................................... 63Linking Quantity Type Fields .................................................................. 64Unlinking Quantity Type Fields ............................................................... 64

Revision Fields ............................................................................................... 64Inserting Revision Fields ....................................................................... 64Linking Revision Fields .......................................................................... 64Unlinking Revision Fields ....................................................................... 65

Sketch Fields ................................................................................................. 65Inserting Sketch Fields.......................................................................... 65

Bitmap Fields................................................................................................. 65Inserting Bitmap Fields ......................................................................... 65

Checkbox Fields ............................................................................................. 66Radio Button Fields......................................................................................... 66

Radio Groups....................................................................................... 67‘Other’ Fields ....................................................................................... 67Qualifier Fields..................................................................................... 67

Checking Fields.............................................................................................. 68Using the Browser .......................................................................................... 68

Navigating the Class View Hierarchy ....................................................... 68Specifying a Route ............................................................................... 68Assigning Wildcards.............................................................................. 68Assigning Objects................................................................................. 69

5 Generating Datasheets ......................................................................................71

Generating a Datasheet .................................................................................. 71Using Excel Features....................................................................................... 71

6 Symbols, Labels and the Graphics Definer.........................................................73

Symbols and Labels in the Aspen Basic Engineering Drawing Editor ...................... 73About Symbols .................................................................................... 74

Contents v

About Labels........................................................................................ 75Graphics Definer ............................................................................................ 75

Starting the Graphics Definer................................................................. 76

7 Defining Symbols and Labels: Worked Examples...............................................77

Example of Creating a New Label ..................................................................... 77Creating a New Label File ...................................................................... 78Specifying Label Characteristics ............................................................. 79Placing and Specifying Value Fields......................................................... 82Placing and Specifying Plain Text............................................................ 86Placing and Associating Units Fields........................................................ 86Drawing Supplementary Graphics........................................................... 88Defining a Datum for the Label .............................................................. 88Defining a Mass Balance Insert Point for the Label.................................... 89Compiling the New Label File ................................................................. 90

Example of Creating a New Symbol .................................................................. 90Creating a New Symbol File ................................................................... 90Drawing a New Symbol ......................................................................... 91Specifying Symbol Characteristics .......................................................... 91Specifying Parts and Tool Tips................................................................ 92Defining a Datum for the Symbol ........................................................... 94Adding Dimensions to the Symbol .......................................................... 94Saving the New Symbol File .................................................................. 94

8 Extracting Legacy Symbols and Labels ..............................................................95

Overview of Extracting Symbols and Labels ....................................................... 95Symbols: Extracting from AutoCAD to the Graphics Definer................................. 96

Preparation and Background Information ................................................ 96Converting Symbols from AutoCAD to the Graphics Definer ....................... 98

Labels: Extracting from AutoCAD to the Graphics Definer .................................... 99Preparation and Background Information ................................................ 99Converting Labels from AutoCAD to the Graphics Definer ........................ 100

Extracting Legacy Symbols and Labels from Other Packages.............................. 102Working with Extracted Symbols and Labels .................................................... 102

9 Graphics Definer Menus and Toolbar Buttons ..................................................103

Menus......................................................................................................... 103File Menu .......................................................................................... 103Edit Menu.......................................................................................... 104View Menu ........................................................................................ 104Definer Menu ..................................................................................... 105Insert Menu....................................................................................... 106Format Menu ..................................................................................... 106Tools Menu........................................................................................ 106

Toolbar Buttons ........................................................................................... 107Main Toolbar...................................................................................... 107View Toolbar...................................................................................... 108Graphics Definer Toolbar..................................................................... 108Ribbon Toolbar................................................................................... 109Draw Toolbar..................................................................................... 110

Parametric Symbols...................................................................................... 111

vi Contents

Parametric Symbol Toolbars .......................................................................... 111Dimensions ................................................................................................. 114

Driving Dimensions ............................................................................ 114Driven Dimensions ............................................................................. 114

Variables..................................................................................................... 115Drawing With Relationships ................................................................. 116

Relationship Commands................................................................................ 117Using Feedback from the Pointer as You Draw ....................................... 117Relationships ..................................................................................... 117Locate Zone ...................................................................................... 117Infinite Elements................................................................................ 118Adding and Deleting Dimensions .......................................................... 119

Linking Variables to Aspen Basic Engineering GUI Handles ................................ 121Example............................................................................................ 121

10 Class Library Editor .......................................................................................127

Class Library Repository................................................................................ 128Class Store........................................................................................ 128

Class Library Editor Window .......................................................................... 128Class Library Editor Menus ............................................................................ 129

File Menu .......................................................................................... 129Edit Menu.......................................................................................... 130View Menu ........................................................................................ 130Insert Menu....................................................................................... 130Tools Menu........................................................................................ 131

Class Library Editor Toolbars.......................................................................... 131Navigation Pane Context-Menu ............................................................ 132

Class Library Editor Status Bar....................................................................... 133Navigation Pane ........................................................................................... 133

Library Tab........................................................................................ 133Construct Tabs................................................................................... 134Inheritance Tab.................................................................................. 134Quantity Types Tab ............................................................................ 134Compare Library Tab .......................................................................... 135

Managing Class Libraries and Class Stores....................................................... 135Library Operations.............................................................................. 136Class Operations ................................................................................ 141Inheritance View Operations................................................................ 142Class Attribute Operations................................................................... 144Association Operations........................................................................ 148Enumeration Operations...................................................................... 149Class View Operations......................................................................... 153Composite View Operations ................................................................. 156User Preferences and Options .............................................................. 159

11 Explorer.........................................................................................................161

Explorer Menus ............................................................................................ 162File Menu .......................................................................................... 163Edit Menu.......................................................................................... 163View Menu ........................................................................................ 164Case Menu ........................................................................................ 164Folder Menu ...................................................................................... 165

Contents vii

Object Menu ...................................................................................... 165Run Menu.......................................................................................... 166Tools Menu........................................................................................ 166Framework Menu ............................................................................... 166Window Menu .................................................................................... 166Help Menu......................................................................................... 167

Explorer Toolbar........................................................................................... 167Aspen Basic Engineering Explorer Status Bar ................................................... 168Folders View................................................................................................ 168Working with Folders .................................................................................... 168

Viewing Folders.................................................................................. 168Customizing Folder Settings ................................................................ 169Creating a New Folder......................................................................... 171Renaming a Folder ............................................................................. 171Removing a Folder ............................................................................. 171Deleting a Folder................................................................................ 171Adding Existing Diagrams to a Folder.................................................... 172Adding Existing Datasheets to a Folder ................................................. 172Adding Existing Objects to a Folder ...................................................... 172Adding Files to a Folder....................................................................... 172Dragging & Dropping Folders and Objects ............................................. 173

Working with Files ........................................................................................ 173Explorer File Menu Options .................................................................. 173Launching a File from the Explorer ....................................................... 174Adding a File...................................................................................... 174Checking Out a Read-only File ............................................................. 175Checking Out an Editable File............................................................... 175Checking In a File............................................................................... 176Undo Check Out ................................................................................. 176Save As ............................................................................................ 176

Working with Objects.................................................................................... 177Creating New Objects ......................................................................... 177Copying an Object.............................................................................. 178Cloning an Object............................................................................... 178Removing an Object ........................................................................... 178Claim an Object ................................................................................. 178UnClaim an Object ............................................................................. 178Deleting an Object.............................................................................. 179Object Properties ............................................................................... 179

Viewing Object Attributes .............................................................................. 179Customizing Case Settings .................................................................. 183Default Object Classviews ................................................................... 184

Packages..................................................................................................... 185Exporting a Package ........................................................................... 185Importing a Package........................................................................... 186Packages Folder ................................................................................. 186

Query Editor ................................................................................................ 186Adding a Query.................................................................................. 188The Aspen Basic Engineering Query Language ....................................... 189Class Views ....................................................................................... 192Units of measure................................................................................ 193Cases ............................................................................................... 194The Response Object .......................................................................... 195

viii Contents

Query Editor Menus and Options .......................................................... 199Logging on to Workspaces and Projects .......................................................... 200

Logging on to a Preferred Workspace/Project......................................... 200Logging on to a User Specified Workspace/Project.................................. 201Logging on to a Workspace/Project via a URL Address ............................ 201Connecting as a Different User............................................................. 201Change Advanced Connection Settings.................................................. 202Invalid Username/Password................................................................. 202Incorrect Username/Password ............................................................. 203Invalid Business Server....................................................................... 204Invalid Authentication Protocol............................................................. 205Invalid Workspace/Project Name.......................................................... 206Closing the Workspace........................................................................ 206

Managing Workspaces .................................................................................. 206Privileges, Roles and Users .................................................................. 206Workspace Components ...................................................................... 209Configuration Management.................................................................. 210

Broker Configuration..................................................................................... 214Configuring the Broker to Support Automated Creation of Oracle RDBs ..... 214Configuring the Broker to Support Automated Creation of SQL Server RDBs216Configuring an Oracle RDB Manually for an Aspen Basic EngineeringWorkspace ........................................................................................ 217Configuring a SQL Server RDB Manually for an Aspen Basic EngineeringWorkspace ........................................................................................ 218Creating a Peer-to-Peer Network of Brokers........................................... 220

Projects within Aspen Basic Engineering.......................................................... 220Managing Projects ........................................................................................ 221

Privilege Settings for Projects .............................................................. 221Logging On To a Project ...................................................................... 222Project Management Dialog ................................................................. 223Conflict Resolution (Manage Conflict).................................................... 229Managing Users and Roles................................................................... 234Managing the Scope of a Project .......................................................... 237Adding Objects to the Project Scope ..................................................... 237

12 Smartplant ....................................................................................................241

13 Administration ..............................................................................................243

14 Bridge ...........................................................................................................245

Overview of the Interface.............................................................................. 245Bridge View and Link View Menus................................................................... 247

File Menu .......................................................................................... 247Edit Menu.......................................................................................... 248View Menu ........................................................................................ 248Link Menu ......................................................................................... 249Linkset Menu ..................................................................................... 249Application Menu................................................................................ 250Transfer Menu ................................................................................... 251Grid Menu ......................................................................................... 251Bridge View Linkset Drop-Down Menus ................................................. 252Bridge View Linksets Grid.................................................................... 252

Contents ix

Link View Drop-Down Menus and Fields ................................................ 253Links Grid in Bridge Link View Window.................................................. 253

AZ Bridge Window Toolbars ........................................................................... 254Bridge View Toolbar............................................................................ 254Link View Toolbar............................................................................... 255

Creating a Bridge ......................................................................................... 256Adding Multiple Files In One Bridge ...................................................... 256Creating Multiple Links for the Same Attribute ....................................... 257Conversion between Template Files (Linked Files) and Bridge Files(Application Files Added to Bridge) ....................................................... 258

Object/Case Bindings.................................................................................... 258Copying and Pasting Object/Case Bindings ............................................ 258Auto-Creation of Object Bindings.......................................................... 259Multi-Creation of Linksets without Object Bindings.................................. 260

Editing an Existing Bridge.............................................................................. 261Closing the Bridge Without Saving........................................................ 261

Adding a New Linkset ................................................................................... 262Editing Linksets............................................................................................ 263Iterative Linksets ......................................................................................... 263

Creating and Editing an Iterative Linkset............................................... 264Conversions between Iterative Linksets and Linksets .............................. 264

Export Package ............................................................................................ 265Exporting a Package ........................................................................... 265Packages Folder ................................................................................. 265

15 Drawing Application Automation Objects ......................................................267

Object Hierarchy .......................................................................................... 268Object Type Descriptions............................................................................... 269

Application Object .............................................................................. 269AddIns and AddIn Objects ................................................................... 269DynamicsDisplay2d ............................................................................ 270HighlightList ...................................................................................... 270Menus and Menu Objects .................................................................... 270SelectSet .......................................................................................... 271ToolBars and Toolbar Objects .............................................................. 271

Index .......................................................................................................................i

1 About this Guide 1

1 About this Guide

This guide details the Aspen Basic Engineering processes applicable to a userwith Administrative rights.

The following topics are covered:

How to generate datasheets.

Piping Systems.

Datasheets (and the Datasheet Definer) including preparing datasheets inMicrosoft Excel.

Using the Graphics Definer (including defining symbols and labels, withworked examples and extracting legacy symbols and labels.

Explorer application, including interaction with Smartplant®.

Administration application.

Class Library Editor application.

Rules Editor (and Knowledge Bases).

Bridge.

Further information about Aspen Basic Engineering applications andfunctionality is contained in the on-line help available from the WindowsStart\… menu, or from the Help menu option within each Aspen BasicEngineering application.

About Aspen Basic EngineeringAspen Basic Engineering is a client/server application that allows multipleprocess designers to be connected to a single workspace or project.

Changes made by one client are immediately reflected in the informationshown to other clients.

To generate a process design, you create database objects that represent thereal world process. You can view and modify data for these objects usingdrawings, or datasheets (Before you can work with datasheets or diagrams,you must open a Workspace or Project).

Related DocumentationIn addition to this document, the following documents are provided to helpusers learn and use the Aspen Basic Engineering applications.

2 1 About this Guide

Title Content

GettingStarted Guide

This guide provides an overview of the Aspen Basic Engineeringapplication set and takes a first-time user through basic Aspen BasicEngineering procedures

After completing the Getting Started guide, you will be able toopen/close workspaces, work with database objects, cases,documents (drawings and diagrams) and understand documentcontrol and revision processes

On-line Help A comprehensive set of help systems are also provided with AspenBasic Engineering. Help within specific applications (for exampleBridge Help) is available from the Help menu of the openapplication

A generic, self-contained Help system (detailing all Aspen BasicEngineering applications, their use and interaction) is available byclicking the Help icon within the windows Start | Programs |AspenTech | Aspen Basic Engineering path

Technical Support

Online Technical Support CenterAspenTech customers with a valid license and software maintenanceagreement can register to access the Online Technical Support Center at:

http://support.aspentech.com

You use the Online Technical Support Center to:

Access current product documentation.

Search for technical tips, solutions, and frequently asked questions(FAQs).

Search for and download application examples.

Search for and download service packs and product updates.

o Submit and track technical issues.

Search for and review known limitations.

Send suggestions.

Registered users can also subscribe to our Technical Supporte-Bulletins. These e-Bulletins proactively alert you to important technicalsupport information such as:

Technical advisories.

Product updates.

Service Pack announcements.

Product release announcements.

http://support.aspentech.com/

1 About this Guide 3

Phone and E-mailCustomer support is also available by phone, fax, and e-mail for customerswho have a current support contract for their product(s). Toll-free charges arelisted where available; otherwise local and international rates apply.

For the most up-to-date phone listings; please see the Online TechnicalSupport Center at:

http://support.aspentech.com

Support Centers Operating Hours

North America 8:00 – 20:00 Eastern time

South America 9:00 – 17:00 Local time

Europe 8:30 – 18:00 Central European time

Asia and Pacific Region 9:00 – 17:30 Local time

http://support.aspentech.com/

4 1 About this Guide

2 Knowledge Bases and the Rules Editor 5

2 Knowledge Bases andthe Rules Editor

Aspen Basic Engineering supports a set of structured routines that manageand modify engineering data within a workspace. Collectively, these are calleda Knowledge Base (KB) as they allow approved engineering design standardsand practices to be encapsulated in the form of scriptable code.

The Aspen Basic Engineering Knowledge Base (KB) Application Interfaceenables you to integrate your engineering and workflow practices andstandards with the Aspen Basic Engineering Server. For example, you canwrite a KB rule to assign equipment tags as they are created following an in-house naming convention.

You can write KB functions in two ways:

Using any Microsoft compiled language

Using the Rules Editor to create a script (which is similar to VB Script)

Compiled KB code can offer better performance because each module is onlyloaded one time during server startup and is not scanned by virus protectionsoftware. Starting in Version 7.3, out-of-the-box KB functions are delivered asVB.NET projects. Visual Basic 2008 can be used to view and change theseprojects, and can be downloaded free from Microsoft athttp://www.microsoft.com/exPress.

This chapter contains information on:

Overview of KB API

Writing Compiled KB Code

Writing Rules Editor Script

AZDBQuery Library Object Reference

6 2 Knowledge Bases and the Rules Editor

Overview of KB APIA KB can consist of a number of different items:

Rules that define general procedures having global scope sometimes,e.g., the EquipmentFolders Rule creates a folder under the Equipment ByType Folder for equipment in the workspace

Methods that define procedures tied to objects by class, e.g., theSwitchFeeds Method is defined for the Shell and Tube Heat Exchangerclass and only operates on this specific type of equipment

Events that runs when certain Aspen Basic Engineering events occur,such as the creation of an object or the issuing of a datasheet

Demons that run when attributes of a specified class change their values

Sorts that order items on datasheets and summary sheets

Filters that limit the number of items in a list, e.g., the MajorEquipmentFilter causes nozzles and other sub-objects to be excluded

You can add as many of these items as you like to a module.

The easiest way to see how to write a KB routine is to start with a simpleexample. This example is of a Method, so it operates for a specific AspenBasic Engineering object class. It can be called from a menu in an applicationsuch as the Drawing Editor or procedurally from a script or application. ThisMethod gives any PlantItem object, or object derived from the PlantItemclass, a name of the form:

<Prefix><UniqueID>, e.g., P-100 for a pump or V-101 for a vessel

[?Class= PlantItem,DisplayName = NameItem,Interactive=true?]

AZMethod NameItem()Self.ItemNumber = Self.NamePrecedent & Self.OIDEnd AZMethod

Even though this example was written as a Rules Editor Script, it illustrateskey features common to all KB definitions. Each KB definition has separateregistration and executable segments. The text in the first paragraphregisters the method by class along with other registration parameters, e.g.,whether the method can be run interactively. The second paragraph definesthe application code that is executed when the method is invoked, which inthis case is a single line of code.

All methods are passed a reference to the object on which it was invoked.This reference is called Self in the Rules Editor Language. The NamePrecedent, e.g., P- for Pump, is an attribute that is defined in the Data Modelby class. The KB can conveniently retrieve it for an object’s class or any of itssubclasses by attribute name.


The script simply reads the values of two object attributes, concatenatesthem together, and assigns this new value to the ItemNumber attribute.NamePrecedent, OID, and ItemNumber are all attributes of the classesderived from PlantItem in the Aspen Basic Engineering data model. The OID(Object Identifier) is an important system attribute, and each object in theAspen Basic Engineering database has a unique integer value for thisattribute. It is frequently used in the scripting language to look up objects.

RulesRules have global scope and are not tied to a particular object. Examplesinclude a function to refresh the project name or to condition heat curves forall shell and tube heat exchangers.

Rules can use dialog boxes for an easy way to present the user with optionsor to ask Yes-or-No questions. Reply Definitions implement the action basedon the user’s response.

Rule Definitions

Rules are the simplest KB routines. They are completely general functions andhave no special parameters available to them.

Rule Attributes

Required Attributes:

None

Optional Attributes:

Attribute Meaning Possible Values (default in bold)

DisplayName Name displayed in ruleselection dialog box

Any string (may be “” delimited inwhich case may contain punctuation)

Interactive Will this rule be presentedto user as available to run?

True, False

Secure Does this rule haveunlimited privileges?

True, False

The ScaleSymbols Rule is a good example of a rule attribute. TheScaleSymbols Rule queries the user for the types of symbols to be scaled,e.g., arrow, a scaling factor, and the drawings to be manipulated. The ReplyMethod will perform the scaling based on the user’s selection. Since the rulehas global scope, the user is able to select a drawing from a list of drawingsin the workspace using a Combo Box. The name of the Reply Method isScaleSymbolsReply.


Rule Reply Definitions

These routines are called when a user clicks OK on a KBDialog displayed froma rule. The name of the Reply Method to be called is defined when the Rulecreates the dialog.

There are two available parameters:

The inputs parameter defines the value specified by the user, e.g., thevalue of inputs("SymbolClass")would be “Arrow” if the user selected

“Arrow” as the type of symbol to be scaled.

The UserData parameter is optional to provide a mechanism for passingnamed parameters between functions as strings.

These two parameters are dictionary objects, so that the values are returnedby specifying the appropriate key value. In the example, SymbolClass is adictionary key for Inputs to retrieve the type of symbol to be scaled.

Rule Reply Attributes


Attribute Meaning Possible Values

Class Name of Aspen BasicEngineering class to whichthis Method is applied

Any valid class name



Class Name of Aspen BasicEngineering class to whichthis Method is applied,repeated as required to addclasses


Interactive Will this method bepresented to user asavailable to run?

True, False

Secure Does this method haveunlimited privileges?

True, False

DisplayName Name displayed in methodselection dialog box

Any string (can be “” delimited inwhich case may contain punctuation)

Rule Reply System Supplied Parameters

inputs A dictionary of dialog control IDs defined by the rule and

selected value for each control

userdata A dictionary optionally populated by user code in the ‘parent’

method


MethodsMethods define procedures tied to objects by class.

Methods can use dialog boxes for an easy way to present the user withoptions or to ask Yes-or-No questions. Reply Definitions implement the actionbased on the user’s response.

Method Definitions

Methods are routines which relate to a particular object; a method runs onobjects for its defined class. Methods can be run from the application menusor they can be run programmatically. For example, a method can be run fromother methods and rules by passing the method name as a RunMethodargument, such as Self.RunMethod("AutoName") runs the AutoName

method defined for the class to which Self belongs. Methods are inheritedthrough the class hierarchy so that a method defined on PowerPort would beinherited by objects of class MechanicalPowerPort. The inheriting class canhowever also declare a method with the same name. The server willautomatically call the method defined for the subclass. For example, if amethod is defined for both the Pump and CentrifugalPump class, the serverwill call the Pump Method for all pumps except centrifugal pumps.

Method Attributes










True, False


True, False

Displayname Name shown to user Any valid text


Method Reply Definitions

Method Reply Definitions are called when a user clicks OK on a KBDialogdisplayed from a Method or Event. The name of the AZMethodReply to becalled when the dialog closes is specified in the AddDialog method ofAZKBDialog.

There are three parameters available in the routine:

The self parameter provides a reference to the object.

The inputs parameter provides the values that the user selected on thedialog.

The userdata parameter provides a mechanism for passing databetween the calling routine and the reply routine.

These last two parameters are VBScript dictionary objects, so that the valuesare returned by specifying the appropriate key value.

Method Reply Attributes










True, False


True, False




Events

Event Definitions

The Aspen Basic Engineering server raises events when certain actions haveoccurred, such as the issuing of a document or the creation of an object. Theevents listed below are predefined within the system.

The Event Name is the name that should be used in the Attribute section ofthe Event declaration. A reference to the object on which the Event hasoccurred is either passed as an argument or can be referenced using thebuilt-in Self variable for Rules Editor Scripts. There may be a secondparameter called EventData that provides an additional reference for theevent as described in the table below.

When declaring an Event, you must also specify the class of the object in theAttributes section. This specifies the class of object on which the event canoccur, and provides a means of providing different actions on different classesof object for the same event:

Event Name Event Description Object Reference EventData Parameter

CreateObject The object has just beencreated

AZQObject Thecreated object

Empty

DeleteObject The object is about to bedeleted

AZQObject Thedeleted object

Empty

CloneObject The object has beencreated by cloning


AZQObject The originalobject

CopyObject The object has beencreated by copying


AZQObject The sourceobject

ChangeClass The class of the objecthas changed

AZQObject AZQClass The originalclass

ModifyAttribute The value of an attributehas changed on theobject

AZQObject Theowning object

IAZQAttributeModifyEventobject. This has two readonly propertiesAttribute:AZQAttribute,Index:long

SubmitDocument The document has beensubmitted

AZQDocument Thedocument

CheckDocument The document has beenchecked


IssueDocument The document has beenissued


WithdrawDocument The document has beenwithdrawn


As well as these events provided by the system, you can define your ownevents in external modules.


Event Attributes



Class Name of Aspen Basic Engineeringclass to which this Method isapplied




Class Name of Aspen Basic Engineeringclass to which this Method isapplied, repeated as required toadd classes


Example: Event

The following is a small CreateObject example to set the Created By andCreated Date document attributes:

[?Class = Document?]AZEvent CreateObject ()

' Update necessary information on creating a document' Should get the user and date and set these on the documentstrUser = GetUserNamedteToday = dateself.createdby = strUserself.createddate = dteToday

end AZEvent

Demons

Demon Definitions

Demons are used when you want a rule to run when an attribute changes.Since the demon only runs when specific attributes change, demons offermuch better performance than the code based on the Modify Attribute Event.

A Demon consists of two parts:

The Pattern defines the attributes that trigger the demon, e.g., theSetHotFluidAllocation demon for Shell and Tube Heat Exchangers runswhen an inlet or outlet temperature changes.

The Action is the routine that runs when the monitored attribute orattributes change.


Demon Operation

Demons are registered against specific Aspen Basic Engineering classes. LikeMethods and Events, a Demon can be specified for the class, or the class caninherit the Demon from its parent class.

When an object is first created, any demons defined for its class (or anyinherited classes) are run. During this first run, the system examines thepattern part of the demon and determines which Aspen Basic Engineeringdata model attributes are read. The system records these attributes so that itcan monitor them for when they change. The action section of the demon isnot run at this time.

When the monitored attributes subsequently change, the Demon is fired againand the Pattern section is invoked. This time, the system records any newattributes sampled by the Pattern, and the Pattern makes calls to run theAction section.

The Action section is used to update Aspen Basic Engineering attributes andperform other actions. In this way, actions are associated with attributes thathave changed in the Pattern section.

The Pattern and Action sections are coded separately.

Pattern Section

This is the part of the demon that is executed in full whenever the demon isinvoked. Any attribute referenced in this section becomes part of the demon’strigger. For this reason, the pattern should sample only those attributes thatshould be monitored for change to improve performance. The Pattern controlswhen an Action is invoked by making a call to the PerformAction method. Forexample:

[?Class=Pump?]AZDemon SampleDemonAZPattern()Cap = self.CapacityCMin= Self. MinimumCapacityCMax= Self. MaximumCapacitydemon.PerformAction Cap, Cmin, CMaxEnd AZPattern

AZAction()…End AZActionEnd AZDemon

The above Demon is run when the Pump is first created to include theCapacity, MinimumCapacity, and MaximumCapacity attributes within itstrigger. Subsequently, if any of these attributes change, the Pattern is called.An action is triggered by the call to PerformAction. It is essential for thePattern code to only access attributes that should become part of the triggerfor activating the Demon.


Action Section

This part of the demon is executed only when called by the AZPattern code.

The AZAction may contain user defined parameters. It is the user’sresponsibility to ensure that sufficient and matching parameters are suppliedin the call to PerformAction.

AZPattern Properties and Methods

This uses the following properties and methods of AZQDemonControl.

Properties:

Property Type Meaning

SuspendTrigger Boolean When TRUE (the default), it ensures that anychanges to attributes in the Pattern section donot cause the Demon to be executed

When FALSE, normal attribute monitoringtakes place, i.e., changes to an attribute causethe demon to be fired again

Matched Boolean (ReadOnly)

True if the Demon currently in the Matchedstate (see above)

Methods:

Method Parameters Return Purpose

PerformAction Any, but mustmatch those inthe AZAction

Must match thatreturned by theAZAction part ofthe demon

Calls the AZAction part ofthe demon. Only called ifthe current Matched statusis TRUE; otherwise, it hasno effect

BeginLoop None When not using the demonenumerator, useBeginLoop, RepeatLoop,and EndLoop for loopingconstructs

RepeatLoop See BeginLoop

EndLoop See BeginLoop

Enumerate Collection:Variant

An enumeratorof Collectionitems

Automatically handlesMatched state inside theloop

Example: Demon 1

[?Class=Pump?]AZDemon SampleDemon

AZPattern()Pre = self.NamePrefixC = 0For Each Nozzle in demon.Enumerate( self.Nozzles)

C = C + 1


demon.PerformAction( Nozzle, C, Pre)NextEnd AZPattern

AZAction( LocalNozzle, Num, Prefix )LocalNozzle.Name = Pre & C

End AZActionEnd AZDemon

This Demon names all the nozzles belonging to a pump by adding 1 to aprefix held by an attribute of the pump. Note that there is a Pattern and anAction section. The parameters of the Action match those of the call to thePerformAction method.

When a Pump object is created, this demon is run, and any attributes that areread in the pattern section are marked for monitoring. In this case, it is thePumps NamePrefix and Nozzles.Count attributes.

Subsequently, if either or both of these attributes change, the demon is calledagain. If just one nozzle has been added, then the AZPattern is invoked.

Demon Attributes

Mandatory Attributes:


Class Name of Aspen Basic Engineeringclass to which this Demon is applied




Class Name of Aspen Basic Engineeringclass to which this Demon is applied,repeated as required to add classes


Sorts and Filters

AZSort: Sort Definitions

Sorts are used to organize the order of objects on datasheets and summarysheets. You define a sort Key in the attribute section. This Key is thenassociated with an Aspen Basic Engineering attribute in the body of the sort,for example self.ItemNumber. The sort is performed on this attribute. You candefine whether the sort should arrange items in ascending or descendingorder by using the following terms in the attribute declaration:

“>” or “<”

If you choose “>”, then if the value of the sort attribute for an object isgreater than the corresponding attribute value of another object then thisobject appears before it in the sorted order (the items are sorted indescending order).


Sorts can be made case sensitive by adding a “c” or “C” to follow the “<” and“>”. Finally, you can force a sort to be alphanumeric by adding a “*” in theattribute definition (by default the sort is interpreted numerically wherepossible).

Sort Attributes



Key Name of key for use in body ofprocedure

Any valid VBScript identifier



Key Name of key for use in body ofprocedure. When multiple keysappear, the items are sorted sothat the first key specified is theprimary sort, the second key isthe secondary sort, etc.

< or > optionally followed by “C”or “c” optionally followed by “*”followed by a key name which isany valid VBScript identifier


Any string (may be “” delimitedin which case may containpunctuation)

Sort System Supplied Parameters

self is the object for which this method has been called.

The Key values are described in the Attributes section.

Example: Sort

[?Key= <* Key1,Key=<Key2?]AZSort Sort1()

Key1 = self.TypeKey2 = self.ItemNumber

end AZSort

This example alphanumerically sorts a list of object names in ascending orderof their Types. Where there are two entries of the same type, they are sortedto appear in descending name order.

Sorts can also be used to organize collections of objects in the script. Thefollowing example lists all piping systems to the KB’s trace window inalphanumeric order.

[?Key= >*Key1?]AZSort NameSort()

Key1 = self.ItemNumber


end AZSort

AZRule ListPipingSystemst()set cPS = ClassStore.FindClass("PipingSystem")set mPS = cPS.MembersmPS.Sort = " NameSort "mPS.refreshfor each oPS in mPS

server.trace 1, oPS.ItemNumbernext

end AZRule

AZFilter: Filter Definitions

Filters are used to select which members of a class appear on a summarysheet. They can also be used from within the scripting language to filter anobject collection.

You define which class of objects is affected by the filter using the classattribute. Then for every object of this class (or of a class that is derived fromthis class), the filter routine is called. If the routine returns true, then theobject is included otherwise it is excluded. The self parameter is available togive access to the properties of the object.

Filter Attributes



Class Name of Aspen BasicEngineering class which thisFilter accepts




Class Name of Aspen BasicEngineering class whichthis Filter accepts, repeatedas required to add classes


DisplayName Name displayed in Filterselection dialog box



Filter System Supplied Parameters

self is the object for which this filter has been called.

Functioning of a Filter

A Filter works on two levels:

1 Only classes named as attributes can be considered for the filter.

2 For instances of classes which match the above, the filter can return TRUEor FALSE.

You can provide a filter that has no VBScript code, in which case filtering isdone purely on the classes named in the attributes.

Example: Filters[?Class=SignalPort,Class= MaterialPort?]AZFilter PortFilter()End AZFilter

This filter passes any instance of classes SignalPort or MaterialPort and

any objects of classes that were derived from either of these two classes.

[?Class=MaterialPort?]AZFilter PortFilter ()

if self.Name = "Inlet" thenPortFilter = true

elsePortFilter = false

end ifEnd AZFilter

This filter passes any instance of class MaterialPort whose Name attribute isequal to “Inlet”.


Writing Compiled KB CodeKB routines can be written in any language that supports COM. In most cases,the Aspen Basic Engineering Rules Editor is the easiest way to write KBroutines. Sometimes, you need better code execution speed or the ability tointeractively debug your KB routines; in these circumstances, you need towrite your KB routines in another language. This section describes how towrite a KB module in VB.NET or VB6. Any .NET language can be used sincethey are all part of the Common Language Runtime (CLR).

Compiled KBs are implemented as Data Service Modules which are essentiallydlls that are loaded by the server on startup. Starting in version 7.3, the DataService Module can be implemented as either a Managed .NET Assembly or aCOM component coded in VB6. See the Implementing Data ServicesModules in .NET section for details on how Managed KBs are implemented.

The only requirement for implementing a KB Data Service Module is for the dllto contain a class that implements the AZQDataService interface. The servercalls the AZQDataService Register function on startup to determine the KBfunctions, e.g., Methods, Demons, the dll supports. The server dispatchescalls to the dll when a KB function supported by the dll is invoked. Unlike KBsimplemented as azkbs, the dll is loaded on startup and remains active untilthe server shuts down.

AZQDataService InterfaceThe Aspen Basic Engineering Server can load any user supplied data serviceas long as it supports the AZQDataService interface. The AZQDataServiceinterface provides methods to register different KB routines with the serverand to control execution of these KB routines.

To support the AZQDataService interface in your VB.NET Assembly:

1 Add a reference in your project to the Interop.AZDBQuery.dll that wasinstalled in the KBs folder with the Aspen Basic Engineering Server.

2 Use the Implements key word to declare that your main class willimplement the AZDBQuery.AZQDataService interface

To support the AZQDataService interface in your ActiveX (COM)module:

1 Import the Interface Definition into your project.To import the definition of AZQDataService interface into your project, useProject/References from the Visual Basic 6 menus. In the Referencesdialog box, find and select AZDBQuery Version xx.x, where xx.x is thecurrent internal version number for the Aspen Basic Engineering version.

2 Declare your Class to implement the interface.Add the following statement to your class definition:

Implements AZDBQuery.AZQDataService

3 Add the function declaration for each member of theAZQDataService interface.The Visual Basic 6 IDE makes this a simple process. In the left- hand


drop-down list above the code window, select AZQDataService.The right hand drop down list now lists the methods of AZQDataService.As you select each one, the IDE will add the method declaration to thecode. Select each method until all have been declared. When all themethods are listed in the right hand box in bold, they have all beendeclared.

More information about the declarations for IAZQDataService interface can befound in the AZDBQuery documentation, contained in the KBEditor help.

Registering KB ItemsThe Server calls the Register Function on startup for each configured KBproject to find out which KB constructs (methods, Rules, Demons) the projectsupports.

To define the KB items you are implementing, you must implement theRegister method.

To implement the Register method:

1. Call IAZQDataServiceRegistrar::SetServiceName. This uniquelyidentifies the DataService to the Aspen Basic Engineering Server.

2. Call the appropriate Add methods to define the KB item.

More information about the Add methods for defining each type of KB item islisted in the Defining Methods section.


Example

The following defines a single demon to define hot fluid allocation for a shelland tube heat exchanger. The SetServiceName function defines the namespace for the KB and is similar to Module Name in the AZKBS Scripts.

Public Sub Register(ByVal Registrar AsAZDBQuery.AZQDataServiceRegistrar) ImplementsAZDBQuery.IAZQDataService.Register

Registrar.SetServiceName("ShellAndTubeHeatExchangers")

'DemonsRegistrar.AddDemon(1, "SetHotFluidAllocation",

"ShellAndTubeHeatExchanger", False, False)End Sub

Defining MethodsTo define a Method:

1. Call IAZQDataServiceRegistrar::AddMethod from the Registermethod.

2. Implement the method handler in IAZQDataService:RunMethod.

Arguments for AddMethod

Arguments Description

iMethodID as Long Unique ID of the method used to identify it in themethod handler

MethodName as string Name of the Method

classes as string Class parameter from the meta data. Use a commato separate multiple classes

displayname as string DisplayName parameter from the meta data

description as string Description parameter from the meta data

interactive as boolean Interactive parameter from the meta data

secure as boolean Secure parameter from the meta data

casefixed as boolean CaseFixed parameter from the meta data

Arguments for RunMethod


iMethodID as long Unique ID of the method specified in the AddMethodcall

MethodName as string Name of the Method

Object as IAZQObject The object for the method

Args as Variant() An array of arguments for the method

Globals as IAZQGlobals The Globals object


For each method defined using AddMethod, you will need to branch based oniMethodID in order to handle the correct method call.

Defining RulesTo define a Rule:

1. Call IAZQDataServiceRegistrar::AddRule from the Register method

2. Implement the rule handler in IAZQDataService:RunRule.

Arguments for AddRule


iRuleID as Long Unique ID of the Rule used to identify it in the rulehandler

RuleName as string Name of the Rule



interactive as boolean Interactive parameter from the meta data



Arguments for RunRule


iRuledID as long Unique ID of the rule specified in the AddRule call

RuleName as string Name of the Rule

Args as Variant() An array of arguments for the rule


For each rule defined using AddRule, you will need to branch based on iRuleIDin order to handle the correct rule call.

Defining DemonsTo define a Demon

1. Call IAZQDataServiceRegistrar::AddDemon from the Register method.

2. Implement the Pattern matching section of the demon handler inIAZQDataService:RunDemonPattern.

3. Implement the Action section of the demon handler inIAZQDataService:RunDemonAction.


Arguments for AddDemon


iDemonID as Long Unique ID of the Demon used to identify it in theDemon handlers

DemonName as string Name of the Demon




Arguments for RunDemonPattern


iDemonID as long Unique ID of the demon specified in the AddDemoncall


Object as IAZQObject The object for which the Demon fires

pDemon asIAZQDemonControl

Demon control object


The Demon Control object pDemon is the same object as “Demon” in therules language. Call pDemon.PerformAction in order to fire the action sectionof the demon.

Arguments for RunDemonAction


iDemonID as long Unique ID of the demon specified in the AddDemoncall


Object as IAZQObject The object for which the Demon fires

pDemon asIAZQDemonControl

Demon control object

Args as Variant() An array of arguments for the rule


For each Demon defined using AddDemon, you will need to branch based oniDemonID in both the Pattern and Action handlers in order to handle thecorrect demon call.


Defining EventsTo define an Event:

1. Call IAZQDataServiceRegistrar::AddEventSink from the Registermethod.

2. Implement the method handler in IAZQDataService:NotifyEventSink.

Arguments for AddEventSink


iSinkID as Long Unique ID of the event used to identify it in theevent handler

eEventID as variant The ID of the event type, as defined by theenumeration EAZQSystemEventIDs




Arguments for NotifyEventSink


SinkID As Long Unique ID of the event specified in AddEventSink

Object As IAZQObject The object for which the event is fired

SinkData() As Variant An array of data sent to the event

Globals As IAZQGlobals The global object

For each event defined using AddEventSink, you will need to branch based oniSinkID in order to handle the correct event call.

Defining SortsTo define a Sort:

1. Call IAZQDataServiceRegistrar::AddSort from the Register method

2. Implement the method handler in IAZQDataService:GetSortValues.

Arguments for AddSort


iSortID as Long Unique ID of the sort used to identify it in the sorthandler

SortName as string Name of the Sort




keys() as variant An array of varying length, depending on thenumber of keys. For each key, the value is aninteger representing a value mask of the followingparameters:

1: inverse sort (>)

2: alphanumeric sort (*)

3: case sensitive sort (c)

(a case insensitive, alphanumeric sort ("<*Key1")would have a key value of 2)

Arguments for GetSortValues


iSortID As Long Unique ID of the sort specified in AddSort

SortName As String The name of the Sort

Object As IAZQObject The object to be sorted

Globals as IAZQGlobals The globals object

For each event defined using AddSort, you will need to branch based oniSortID in order to handle the correct sort call.

Defining FiltersTo define a Filter:

1. Call IAZQDataServiceRegistrar::AddFilter from the Register method.

2. Implement the method handler in IAZQDataService:FilterObject.

Arguments for AddFilter


iFilterID as Long Unique ID of the filter used to identify it in the filterhandler

FilterName as string Name of the Filter




Arguments for FilterObject


iFilterID As Long Unique ID of the filter specified in the AddFilter call

FilterName As String Name of the filter

Object As IAZQObject Object to be filtered

Globals As IAZQGlobals Globals object


Global VariablesWhen you write rules in the KBEditor, the rules language defines certainglobal variables that are available for the script. When you write these samerules in Visual Basic, these global variables are not defined. Each of theseglobals can be accessed from variables that are passed in through theargument list of the assorted KB handler methods. The following table liststhese globals variables and how you would access them from the arguments:

KB Global Variable Visual Basic Syntax

Server Globals

ObjectStore Globals.ObjectStore

ClassStore Globals.ClassStore

Response Globals.Response

Self Object

Handling ArgumentsThe handler methods for Methods, Rules, and Demons all have a variant array“args” as an argument. In the rules language, these arguments would belisted in the declaration of the AZMethod, AZRule, or AZDemon action section.In Visual Basic, these arguments are passed as an array.

For a Method or Rule which is handling the reply from a KBDialog (anAZMethodReply or AZRuleReply), the first argument is a Scripting.Dictionaryobject. This dictionary corresponds to the Inputs variable in the ruleslanguage.

You can pass arguments to a method when calling Object.RunMethod or to aDemon Action handler when calling pDemon.PerformAction. In each case, youmust create a Variant array, set the values of each element, and pass thearray to either RunMethod or PerformAction as the “args” optional argument.

Implementing Data Service Modules in .NETStarting in version 7.3, the Aspen Basic Engineering Server creates anApplication Domain for the Managed KBs to simplify the KB application code;KB Application code is no longer required to release COM objects and alluncaught exceptions thrown by the KBs are caught and logged in theworkspace journal file. The server will automatically load all assemblies withinthe domain that support the AZQDataService Interface on startup. Thedomain directory is defined using the ManagedKBsDirectory Config Filekeyword. Only one application domain can exist on the server.

The server will automatically run the .NET Garbage Collector, catch alluncaught exceptions thrown by the Managed KB Modules, and log exceptionmessages to the Workspace Journal File. The Managed KB Module code shouldnot release underlying COM references, i.e., calls to ReleaseComObject orFinalReleaseComObject from the


System.Runtime.InteropServices.Marshal namespace should not be

made from KB application code.

The .NET KB Code can be debugged by setting break points in the KB Codeafter attaching Visual Studio 2008 to a running Aspen Basic EngineeringServer. If using Visual Basic 2008, the attach to server function is notavailable.

Installation and the Config FileEach Data Service Module will define a class to implement IAZQDataService.This class will implement Register and other functions within IAZQDataServicethat the module supports. The server calls Register to determine themethods, demons, rules, and other KB functions the module supports.

The dlls for Data Service Modules written in .NET must be copied to anApplication Domain Folder defined using the ManagedKBsDirectory keyword,e.g., ManagedKBsDirectory = “KBS” to set the KBs folder within the server’s

folder path as the Application Domain. The assemblies should not beregistered. The ExcludedManagedKBs keyword is used to define those thatshould not be loaded, e.g., ExcludedManagedKBs = "TEF.DataSvcImpl”. A

comma delimited list of assemblies can be specified. Each assembly isidentified by specifying the Root Namespace followed by the name of theinterface class implementing IAZQDataService separated with a period.

Each class should define a unique GUID, for example:

<Guid("AE460480-A048-4c04-8D65-C731C1A146BB")> _Public Class DataSvcImpl

Implements AZDBQuery.AZQDataService

Managed assemblies should be built with the Interop dlls (for example,Interop.AZDBQuery.dll) that have been installed with the Aspen BasicEngineering Server in the KBs folder.

COM Data Service Modules, e.g., written in VB6, can also be used alongsidethe .NET KBs. These dlls are tied to the server by declaring a commadelimited list of ProgIDs using the DataServiceModules keyword, e.g.,

DataServiceModules ="ObjectCopyData162.DataServiceImpl,….,….”


Writing Rules Editor ScriptThe Aspen Basic Engineering Rules Editor is a syntax coloring editor for thecreation and modification of KB script source files. It also allows these sourcefiles to be compiled and loaded into the server and allows you to executeMethods, Rules, Sorts, and Filters. It features:

Auto Indent - The editor recognizes VBScript and Aspen BasicEngineering keywords and performs automatic indentation appropriately.

Syntax Highlighting - The editor recognizes both VBScript and AspenBasic Engineering keywords and symbols and highlights the textappropriately. If you are printing to a color printer, this coloring isretained.

Error Windows - When compilation errors are present in the Buildwindow or Run errors in the Run Error window, the menu items Tools |Next Error and Tools | Prev Error can be used to highlight the relevantsource code; double-clicking the error line in the error window will achievethe same effect.

This section assumes you have knowledge of VB scripting and a littlefamiliarity with the Aspen Basic Engineering Data Model.

Writing the KB ModuleThis section provides information on

Format of KB module source files

Dialog boxes and replies

Message boxes

Format of KB Module Source File

A KB Module source file comprises a number of sections:

CommentsThese may appear anywhere within the source file. These styles ofcomment are recognized:

o /* comment */

o ‘comment to end of line

o // comment to end of line

o REM comment to end of line

Module NameThe name of the KB module must not be the same as the module namefor any other KB file that is loaded into the workspace. The name appearsas [!Modulename=modulename !] at the beginning of the source file. Only

comments may appear before this.

Private CodeYou can define an optional private section to the file. It can contain anyvalid VBScript code, including variables, classes, functions andsubroutines, which can be used by any script within the module. Anythingin the private section is not visible outside of this module. The sectionstarts with [?Private Code?] and finishes with [?End Private Code?].


The remainder of the file consists of Event, Method, Rule, Filter, Sort, andDemon routines. A routine is described in the module by certain attributessuch as a display name. These attributes are in an attribute block thatappears at the very start of the routine between [? and ?] characters.

[?AttributeName = AttributeValue,AnotherAttribute = AnotherValue?]AZKBKeyword RoutineName( possible parameters)

VBScript codeEnd AZKBKeyword

where AZKBKeyword is one of:

AZEvent

AZMethod

AZMethodReply

AZRule

AZRuleReply

AZSort

AZFilter

AZDemon (and subsequently AZPattern and AZAction)

Example: Basic Sections of a KB File

// A Simple naming rule module[!Modulename=SimpleNaming !]

[?Private Code?]Function IncrementName(NamePrefex)Num = ObjectStore.Globals.ProcessEquipmentCounterNum = Num + 1ObjectStore.Globals.ProcessEquipmentCounter = NumIncrementName = NamePrefix & NumEnd Function[?End Private Code?]

'Set the name on the create event[?Class=PlantItem?]AZEvent CreateObject()// Self is an example of a system parameter// which here represents the objectPrefix = Self.NamePrecedentSelf.ItemNumber = IncrementName(Prefix)end AZEvent

Dialog Boxes and Replies

To interact with the user, a routine can display a dialog box that displays textand receives input by means of combo boxes, edit fields, radio buttons, etc.Dialog boxes cannot be used with Filters and Sorts.


The dialog box is created programmatically in the script where user interfaceelements are added to it. The dialog box does not appear until the method orrule that calls it has completed. When the dialog box closes, another routineis called to allow the script to continue execution.

Creating a Dialog Box

To create a dialog box for display in a routine you use theServer.NewKBDialog method:

Set dlg = Server.NewKBDialog(“dialog title”, ”reply routinename”)

“dialog title” appears in the title bar of the dialog. “reply routine

name” is a reference to another routine in the KB Module that runs when the

dialog closes. This routine can be either a AZMethodReply or AZRuleReplyroutine.

Displaying a Dialog Box

The dialog box is invoked slightly differently depending upon whether it iscalled from a rule, a method, or an event.

For a rule or method, the dialog variable is assigned to the return value of themethod or rule. The Dialog is then displayed when the method or rulecompletes, e.g.:

AZMethod NameObj()set dlg = Server.NewKBDialog( "Enter Name", "NameReply")…set NameObj = dlg //The dialog is displayed when the method endsend AZMethod

AZMethodReply NameReply ()…End AZMethodReply

After the user closes the dialog box, the specified reply method (or rule) iscalled.

Displaying a dialog box is a little different if it is invoked from an Event. AsAspen Basic Engineering supports transactions on the server, it does not allowfor user interaction whilst a transaction is in progress; this would cause thetransaction processing on the server to be held up until the dialog box wasclosed. Events typically occur as part of a transaction and so any dialog boxesthat are needed are entered into a queue until the transaction completes. Thedialog box is then displayed. For the rule writer, this means that instead ofassigning the dialog to the routine return value, they need to enter it into aqueue called the KB Dialog queue, which is done by calling the server’sQueueKBDialog method.

Example: Displaying a Dialog from an Event

[?Class=PlantItem?]AZEvent CreateObject()set dlg = Server.NewKBDialog( "Enter Name", "NameReply")// Display the dialog after the transaction completes


Server.QueueKBDialog dlgend AZEvent

Populating the Dialog Box

The Server.NewKBDialog method creates an AZQKBDialog object. Visualfeatures such as Text Boxes and combo boxes can be added to the dialog boxusing the properties and methods of the AZQKBDialog.

See AZQKBDialog for the full list of properties and methods.

The most useful properties are:

Cancel displays a cancel button on the dialog. If the user clicks thisbutton, one of two things happen. If a script has been added to the dialogbox by the AddScript method and this script contains a function calledCancel, this function is called. If this function returns true, the dialogcloses and the script is completed. If the function returns false, the user isreturned to the dialog and the script resumes. If there is no script calledCancel associated with the dialog box, then clicking Cancel closes thedialog and the script stops executing.

Title specifies the Title of the dialog box.

ReturnTo specifies the name of the routine to be called when the userclicks OK.

The OK button is always present. When it is clicked, the dialog box closes andthe Reply method or rule is called unless a script has been added to the dialogby the AddScript method containing a function called Validate. If theValidate function exists, it is called. If it returns true, the dialog closes andthe script continues; if the function returns false, the user is returned to thedialog and the script resumes. This provides a mechanism for validating theinputs on the dialog.

The most useful dialog methods are:

AddTextBox adds a text box with the specified text.

AddEditBox adds an Edit box with the specified prompt.

AddComboBox adds a combo box. An AZKBDlgComboBox object isreturned which is used to build up the combo box.

AddScript adds the script as it appears in the text.

You cannot specify the layout of these visual elements. The OK and Cancelbuttons appear at the bottom of the dialog box. The other items appearvertically underneath each other in the order in which they were created.

Combo Boxes and Radio Button Groups are the most complex visual elementto add to a dialog box. First, an object is added to the Dialog that representsthe ComboBox or Radio Button, e.g.:

Set Combo = dlg. AddComboBox ("Title", “Text”, “”)

This object can then be used to further populate the Combo Box or RadioButton Group, e.g.:

Combo.AddOption “First List Item” “Key1”Combo.AddOption “Second List Item” “Key2”

adds two items to the Combo Box. See the AZQuery class reference forfurther information.


Dialog Return Values

For each dialog box, a reply routine should be specified that is called after theuser clicks the OK button. This is the name of an AZRuleReply if the dialog iscalled from a rule; otherwise it should be an AZMethodReply.

An AZMethodReply or AZRuleReply routine has a system-supplied parameteravailable to it which provides information about the user inputs to the dialog.This is called “inputs” and it is a VBScript Dictionary object. The return valuesare accessed by using the specified Button/Option ID as the key, e.g., in amethod:

Set rBox = dlg.AddRadioGroup("Group1")rBox.AddButton "Button1","Prompt1"," ", ""rBox.AddButton "Button2","Prompt2"," ", ""

Two buttons are added with Ids of Button1 and Button2. To access the stateof the buttons after the dialog is closed, the reply method can access theinputs parameter and use the keys Button1 and Button2, e.g., in themethodreply:

Sever.Trace 1,"Button1 value = " & inputs("Button1")Server.Trace 1,"Button2 value = " & inputs("Button2")

if the you press button 1 then inputs(“Button1”) returns TRUE whilstinputs(“Button2”) returns FALSE.

Dialog User Data

The UserData property of a KBDialog is a VBScript Dictionary object; datamay be stored in this dictionary like this:

dlg.UserData.Add "Case1", “Design”dlg.UserData.Add "Case2", “Summer”

The userdata is later made available in the AZMethodReply or AZRuleReply asa system supplied parameter “UserData”, like this:

Server.TRACE 1, userdata(“Case1”)

Message Boxes

Because KB scripts run on the server, the VBScript MsgBox will not work.Therefore, the KB Dialogs must communicate any screen input from theserver back to the client.

Two other server methods of the AZGlobals object display simple messageboxes:

SendWarningMessage(<”TextString”> displays a warning box.

SendErrorMessage(<”TextString”> displays an error box.

For example:

if not Self.Temperature.HasValue then

Server. SendWarningMessage “No Temperature value specified”


Compiling the KB ModuleThe previous example can be run using the Rules Editor. This is launchedfrom the Start Menu and can be found under Configuration Tools in the AspenBasic Engineering entry in the Programs folder. With the Rules Editor running,open a Workspace from the File menu. A default module is already open. Totest the previous example you can specify the module name at the top of thefile and type or paste the text of the Rule.

Save the file using Save on the File menu. You can now compile the moduleby picking the Compile Menu item from the Tools menu. If you have anycompilation errors, they are described in the Build window at the bottom ofthe Rules Editor. You can double-click the error message to go to the problemline in the script. Otherwise, the Build window outputs the location of thecompiled file and you can see that the compiled file has a .azbx file extension.

Loading the KB ModuleAfter the script successfully compiles, select Tools | Load from the menu barto load it into the workspace. The final part of testing is to run the Method.The Run menu allows you to run a Method, Rule, Sort, or Filter. When youselect Method from the Run menu, you are given a chance to select the classof object. This is because Methods work on a particular class of object. Youcan either choose a class or click Cancel. If you click Cancel, a list of allobjects in the workspace appears; otherwise, a list of only those objects ofthe selected class appears.

Running the KB ModuleWith an object selected, you are presented with a select list of all methods inthe workspace, includes all methods loaded as part of loading the workspaceand all those loaded directly from the Rules Editor. To run your Method, selectyour Method from the list. If the previous rule had an output, for example byhaving

Server.Trace 1, “The object has been named “ & Self.ItemNumber

just before “End AZMethod”, then output such as:

The object has been named P-1

is displayed in the Trace window.

The Rule Editor also has an output window to display Run Time errors (errorsnot handled whilst the script is running). For example, if you mistype theprevious line so that it reads:

Server.Trace 1, “The object has been named “ & Self.ItemNumb

A message like:

E:\Test.azkbs(8) :error : Object doesn't support this property ormethod: 'self.ItemNumb'

is displayed in the Run Errors pane. You can double-click this message to goto the line where the error occurred.


Loading the module in this way would not ensure that the module was loadedevery time the workspace was loaded. To do this, you must place thecompiled module in the KB directory and ensure it is referenced in theworkspace configuration file, (see Configuration.)

EventsThe previous example would be more useful if it ran when an object was firstcreated, as it could then give an object a default name. This can beaccomplished with an Event. Whenever an object is created in Aspen BasicEngineering, the CreateObject event is fired. We can write a routine tocapture this event as follows:

// A Simple naming rule module[!Modulename=SimpleNaming !][?Private Code?]Function IncrementName(NamePrefix)Num = 0if Num = ObjectStore.Globals.ProcessEquipmentCounter.HasValuethen

Num = ObjectStore.Globals.ProcessEquipmentCounterend if

Num = Num + 1ObjectStore.Globals.ProcessEquipmentCounter = NumIncrementName = NamePrefix & NumEnd Function[?End Private Code?]

'Set the name on the create event[?Class=PlantItem?]AZEvent CreateObject()Prefix = Self.NamePrecedentSelf.ItemNumber = IncrementName(Prefix)end AZEvent

This event is called whenever a new PlantItem object is created. There areseveral changes from the previous Method. First, the Event calls a Function,IncrementName, which is called and declared in the normal way except thatthe IncrementName function definition itself is enclosed in a Private Codesection. Private Code gives you a convenient place to insert helper functionsthat you only need to use within the module. They are not visible to anyroutines in other modules. Only one Private Code section is allowed in amodule but it can have as many subroutines, functions, and variables as youwant.

The IncrementName function takes the name prefix as an argument, looks upa global counter which it increments and stores, and finally returns theconcatenation of the name prefix and this number. This global counter isstored in the ProcessEquipmentCounter attribute on the Globals object in theAspen Basic Engineering Data Model. This is accessed the first time in thefunction with lines like:

Num = ObjectStore.Globals.ProcessEquipmentCounter

ObjectStore is one of three Global Variables the system provides to the scriptwriter and it represents an AZObjectStore object. Aspen Basic Engineering


provides a comprehensive query language that provides full access to thedata in the workspace and the definitions found in the data model. This isaccessed in the VB Script through the AZDBQuery 2006 Type library.

When using an AZEvent of type ModifyAttribute, the code must explicitlyspecify the case when changing attribute value. If not, the governing case isused by Basic Engineering. The case which triggered the event can beretrieved using:

set attrib= eventdata.AttributeCaseID = attrib.CaseID

When attribute value is changed in the AZEvent, the caseid can be used usingsomething similar to:

self.Attribute("NormalVaporVolumetricFlowRate",CaseID)=attrib.Value *22.414*3.6

AZQObjectStore Methods

AZObjectStore is one of the objects found in the AZDBQuery library. You cansee the contents of this type library using a Class Viewer on AZDBQuery.dlland by referring to the online help for the Rules Editor, AZDBQuery LibraryObject Reference in the Knowledge Base Language topics. Some of the mostuseful methods of AZObjectStore are shown in the following table:

Method Return Type Description

CaseID(CaseName) String Returns the CaseID of this case

CaseName(CaseID) Long Returns the name of the case

CreateObject("<classname>”)

AZQObject Creates of an object of the specifiedclass

FindObject(OID) AZQObject Returns the object with thespecified object ID (OID)

GlobalCases Variant Returns an array of the CaseIDs forall cases in the workspace

Globals AZObject Returns the Aspen BasicEngineering globals object

GoverningCase Long Returns the CaseID of thegoverning case

ObjectClass(OID) Returns the class for the givenobject ID

Property Type Description

In the previous example, the Globals property shown in the table is used toget an AZObject that represents the Globals object. It is very easy at thisstage to be confused by the terms class and object, as these terms are usedby both the Aspen Basic Engineering data model and scripting.

Aspen Basic Engineering classes are defined in the Aspen Basic Engineeringdata model, such as Pump and Globals. Aspen Basic Engineering objects areinstances of the class, such as Pump P-100 and the Globals object.

Scripting uses COM classes (in particular for writing a KB, it uses the classesdefined in the AZQuery library). Examples are AZObject and AZObjectStore.


Classes are instances of these objects, e.g., the Self parameter and theObjectStore global.variable

As with the Method example, the data model attribute is used for retrievingthe value. If you examine AZObject using a class viewer, you will not findProcessEquipmentCounter because this attribute belongs to the data modeland not to the AZObject class. An examination of some of the most usefulAZObject properties and methods helps to explain what is happening.

Some AZQObject Methods

The AZQObject class provides methods that allow you to access andmanipulate an Aspen Basic Engineering object. Each AZQObject objectcorresponds to an object in the Aspen Basic Engineering workspace. Some ofthe most useful methods are shown below:

Method and Properties Return Type Description

Attribute(“<Name>”,Case [optional])

AZQAttribute Property. Returns thespecified attribute of thisobject

Attributes(Case[Optional])

AZQAttributeCollection Property. Returns allattributes for this object

Class () AZQClass Property. Returns the classfor this object

Copy() AZQObject Method. Returns a copy ofthis object

The reference to ProcessEquipmentCounter is taking advantage of AspenBasic Engineering's implementation of Dynamic Properties. TypingGlobals.ProcessEquipmentCounter is interpreted as Globals.Attribute(“ProcessEquipmentCounter”), which provides access to a scripting object (anAZQAttributes object) representing the ProcessEquipmentCounter attribute.

AZQAttribute Properties

The AZQAttribute object has methods and properties that provide access tothe attributes of an Aspen Basic Engineering object.

These include those shown below:

Properties Type Description

Value{Default]

Variant The value of the attribute

DataTypeName String The type of the attribute (as a string)

HasValue Bool True if the attribute value is set

Count Integer The number of items in a vector attribute

DataType EAZQDataTypes The type of the attribute (as an enumeratedinteger)

Value is the default value, so ObjectStore.Globals.ProcessEquipmentCounteris a short hand for the following three lines:


set objGlobal = ObjectStore.Globalsset objAttribute = objGlobal.Attribute(“ProcessEquipmentCounter”)Num = objAttribute.Value

The line:

if (ObjectStore.Globals.ProcessEquipmentCounter.HasValue) then

uses the HasValue property to determine if the ProcessEquipmentCountattribute has a value in it or not.

The DataType property will return one of the following:

azqDataTypeString = 1azqDataTypeReal = 2azqDataTypeObject = 3azqDataTypeEnum = 4azqDataTypeInteger = 5azqDataTypeDate = 6azqDataTypeBoolean = 7azqDataTypeBinary = 8

You can use either the integer or the constant name

e.g. if objAttribute.DataType = azqDataTypeObject then

to test if the attribute is an object.

Object = AZQGlobals class

As well as ObjectStore, there are two other Global objects available in thescript, Server and ClassStore. Server is an AZQGlobals object. This objectprovides the methods and properties required to navigate to many of theuseful data and methods in the Aspen Basic Engineering query language.

Method ReturnType

Description

Trace(<level>,”<Text>” Outputs the text to the KBEditor trace window

NewKBDialog(“<Title”>,”<Return>”)

AZQKBDialog Creates a Dialog for use in aRule

QueueKBDialog(<AZQKBDialog>) Queues a KB dialog

Object = AZQObjectStore class

The ClassStore object of type AZQObjectStore class gives you access to thedatamodel definitions, that is class definitions, attribute definitions, class viewdefinitions, etc.


FindClass("<classname>”) AZQClass This retrieves an objectrepresenting the named classfrom the class store

FindClassView("<classviewname>”)

AZQClassView This retrieves an objectrepresenting the namedclassview


Object = AZQClass class

The AZQClass class provides access to the Aspen Basic Engineering datamodel class definitions and provides access to existing Aspen BasicEngineering objects of that Aspen Basic Engineering class. Typically you willget a AZQClass object returned to you from the AZQClassStore.FindClassmethod. Some of the most useful methods and properties of AZQClass are:


Name String The name of the class. A readonly property

Members AZQObjectCollection Property. A collection ofAZQObject objects thatrepresents all the Aspen BasicEngineering objects of this classin the workspace

Attribute("<Name>") AZQAttributeDefn Property. Returns the definitionfor the named attribute

Attributes AZQAttributeDefnColl Property. Returns a collection ofall attributes for this class

A More Complex Example

The use of some of the methods listed above can be illustrated with a morecomplex example. When run, the following rule yields a report on aCentrifugal Pump selected by the User. The User can specify the class view forthe report or chose to report on the pump using the core data model. Thisrule displays a dialog to the user with a list of all pumps and all class viewsthat represent pumps.

[?DisplayName = PumpReport,Interactive=true, Secure=true?]AZRule PumpReport()

' Create the dialogset dlg = Server.NewKBDialog( "Select Pump and Class View",

"PumpReportReply")dlg.Cancel = trueSet PumpsCombo = dlg.AddCombobox("Pumps", "Pick a Pump","Pick a

value")' List all pumps by asking the class for all its membersset PumpClass = ClassStore.FindClass(“CentrifugalPump”)set PumpsCollection = PumpClass.Membersfor each PumpObject in PumpsCollection

PumpsCombo .AddOption PumpObject.ItemNumber , PumpObject.OID

nextSet ClassViewsCombo = dlg.AddCombobox("Class View", "Pick a

class view","Pick a class view")for each ClassView in ClassViewCollection

PumpsCombo .AddOption PumpObject.ItemNumber , PumpObject.OID

nextset PumpReport = dlg

End AZRule


Rules run on the server and therefore it is not possible to display standardmessage boxes or user interfaces. Instead, Aspen Basic Engineering has aKBDialog object that represents a dialog that the Aspen Basic Engineeringserver will post to the client for the client to display. The above rule uses theServer global AZGlobals object to call the NewKBDialog method to create thedialog box. The dialog box has several properties and methods that can becalled to add visual elements to it (see KBDialog below). In this case, twoCombo boxes are added by calling the AZKBDialog's AddComboBox method.The AddComboBox method, as many of the AZQuery methods do, returnsanother object, in this case a AZComboBox object. The AZComboBox objectcan be used to add to list entries to the Combo box.

The list of pumps is retrieved by calling the FindClass method on the third ofthe three system supplied global objects, the ClassStore. This returns anotherAZDBQuery object that represents the Pump class, in this case an AZClassobject. Calling the classes Members method returns an AZObjectCollectionobject. The AZObjectCollection object is a collection of all the objects of theCentrifugalPump class in the database. The class is enumerated for each loop,so that for every pump an item is added to the combo box using theAddComboBox's AddOption method. The AddOption method takes twoarguments; the first is the name displayed in the combo box, in this case thename of the pump. The second argument is used later and in this case, thePumps unique identifier, the OID, has been used.

The second combo box is populated in a similar way, with the list of classviews that are available for a pump being determined and the collection ofclass views enumerated for each loop.

The final line assigns the dialog object as the return value of the rule and thiswill cause the dialog box to be displayed when the rule completes. After theuser clicks OK on the dialog box another routine needs to be run to continuethe rule. The rule to run was specified when the dialog box was created. Thesecond argument of the line:

set dlg = Server.NewKBDialog( "Select Pump and Class View","PumpReportReply")

specified the name of a rule to call when the dialog box is closed, namely inthis case “PumpReportReply“.

Dynamic PropertiesAspen Basic Engineering supports a shorthand method of writing theAZObject.Attribute(“AttributeName”)

as:

Object.<AttributeName>

Therefore these two lines accomplish the same thing:

Self.Attribute(“ItemNumber”) = “P100”Self.ItemNumber = “P100”


Note: Both examples are using the default Value property of theAZQAttributes object. If the Attribute holds objects then the dynamicproperties can be chained together. Vectors can also be referenced. Bothfeatures are illustrated below.

Self. Attribute(“NormalFlow”) (1). Attribute(“BulkFllow”)(1).MoleFlowRate = 230.0

Self. NormalFlow(1).BulkFllow(1). MoleFlowRate = 230.0

Note that an error is raised in the second case if any of the intermediaryobjects do not exist.

If the intermediary objects need to be created and the value assigned, thenthe AssertRoute method should be used:

Self.AssertRoute(“NormalFlow(1).BulkFllow(1). MoleFlowRate”) =234.0

Note also that writing the previous example as:

Dim ObjSet Obj = Self.NormalFlow(1).BulkFllow(1)Obj. MoleFlowRate = 2340.0

also raises an error because the introduction of a local variable prevents thescrip from determining the correct AZQuery class.

Configuration FileAfter rules have been developed, they are normally loaded at the same timeas the workspace. To do this, the workspace configuration file must specifythe location of the rules and the names of the rule module.

The configuration file should have these parameters:

KBScriptDirectory = “<KBDirectory>”KBScripts = “<Modules>”

where:

<KBDirectory> is the folder containing the KB modules, relative to theWorkspaceLibraries folder.

<Modules> is a comma separated list of the module file names. If the fileshave the default extension of azkbx it can be omitted from this list.

e.g.:

KBScriptDirectory = "KBS"KBScripts = "Filters,component-sum"


Rules Editor MenusThe Rules Editor has the following menus:

File menu

Edit menu

View menu

Options menu

Tools menu

Run menu

Help menu (not described)

File Menu

The File menu contains the following commands:

File Menu Command Action

New Creates a new script file

Open Opens an existing script file

Save Saves the active script file

Save As Saves the active script file as a new user-selected name

Open/Close Workspace Allows you to select a Workspace

Once a Workspace is open, the Open Workspace optiontoggles to Close Workspace

Print Prints the active script file

Print Setup Open the Windows Print Setup dialog

Recent Files Displays a list of files recently opened in the Rules Editor

Exit Quits the Rules Editor application

Note: An Aspen Basic Engineering workspace is not necessary for editing andcompiling KB Script code, but must be opened before the current module canbe installed and before any procedures are run.


Edit Menu

The Edit menu contains the following commands:

Edit Menu Command Action

Undo Undoes the last action

Redo Redoes the previously undone action

Cut Copies the selection to the clipboard

Copy Copies the selection to the clipboard

Paste Places the last item(s) copied to the clipboard at thecursor position

Select All Selects the entire document

Find Find a string in the current script file

Replace Replace a string in the current script file

Find Next Finds a the next occurrence in the current script file

Find Previous Finds the previous Finds a the next occurrence in thecurrent script file

View Menu

The View menu contains the following commands used to show/hide theassociated item:

View Menu Command Action

Toolbar Shows/hides the toolbar (toggle)

Status bar Shows/hides the status bar (toggle)

Query Editor Displays the Query Editor dialog (refer to Query Editor forfurther details of the Query Editor function)

Options Menu

The Options menu contains the following commands:

Options MenuCommand

Action

Clear Build Errorson Compile

If selected, the Build window is cleared each time code iscompiled

Clear Trace/RunErrors onRun/Install

If ticked the Trace and Run Errors windows are cleared eachtime a Method, Rule, Sort or Filter is run, and each time amodule is installed

Show LineNumbers

Toggles the display of line numbers in the main edit window(NB if displayed, line numbers are also printed)

Print Header &Footer

If enabled then a suitable header and footer areprepended/appended to each page in a print out


Tools Menu

The Tools menu contains the following commands:

Tools MenuCommand

Action

Compile The current source file is saved and submitted to thecompiler; compile messages appear in the Build window

Install/ReplaceModule

The object file corresponding to the current source file isloaded into the server, displacing any current module of thesame name

Next Error

Prev Error

Compile errors appear in the Build Window, Run Time errorsin the Run Errors window. In either case, these menuoptions highlight the source code corresponding to the nextor previous error

Clear Build

Clears the corresponding windowClear Trace

Clear Run Errors

Run Menu

The Run menu contains the following commands:

Run MenuCommand

Action

Method Select option to display appropriate dialog boxes for theselection of the object if required and procedure to run

All appropriate rules, methods, etc., are listed, not justthose from the module currently being edited

Rule

Filter

Sort


Rules Editor ToolbarThe Toolbar displays commonly used menu operations as toolbar icons(buttons). Toolbar icons also display a tooltip (action) when the cursor isfloated over them.

Item Name Description

1 Open Workspace Open a Aspen Basic Engineering Workspace

2 New Create a new script file

3 Open Open an existing script file

4 Save Save the current script file

5 Cut Cut the selection onto the clipboard

6 Copy Copy the selection onto the clipboard

7 Paste Insert clipboard contents

8 Print Print the active script field

9 Compile Compiles the current file

10 Install Installs or replaces this module in the selectedserver

11 Rules Editor Help Displays Rules Editor Help

AZDBQuery Library ObjectReferencePlease also refer to the online Rules help for further details.

AZQKBDialogProperty Type Meaning

Cancel Boolean Show Cancel button or not

Title String Title of dialog

Width Integer Maximum display width (pixels)

HelpString String Text displayed when user presses F1 (use vbCrLf to getmultiple lines)

UserData Dictionary Data which persists throughout the life of the Dialog Box

ReturnTo String Name of ‘reply’ Method (or Rule)


The following dialog methods are available:

Method Description Parameters Purpose

AddTextBox Adds a text box tothe dialog

Text:String Text to display

AddEditBox Adds an Edit boxwith the specifiedprompt

ID:String

Prompt:String

Balloon:String

Width:short

ID to refer to value

Prompt shown to left ofbox

Balloon help displayswhilst hovering

Width is maximumwidth

AddCheckBox Adds a check (tick)box to the dialog

ID:String

Prompt:String

Balloon:String

Value:String


Prompt shown to left ofbox

Balloon help displayswhilst hovering

(Not used)

AddLink Adds a hyperlinkwith the specifiedURL to the dialog

URL:String

Prompt:String

Balloon:String

DisplayAs:String

The URL to link to

Prompt, text to left ofDisplayAs string,displayed text

Balloon as above

DisplayAs, string toshow

AddRadioGroup Adds a radio group.AZKBDlgRadioGroupobject is returned

Name:String Create a RadioGroup

AddComboBox Adds a combo box.AZKBDlgComboBox.Object is returned

ID:String,Prompt:String,Balloon:String

Create a ComboBox

AddScript Text: String(must be acomplete VBScript function)

If the function is calledValidate() or Cancel(),it is called when OK orCancel is clicked onthe dialog box.Validate/Cancel shouldreturn TRUE or FALSE.Returning TRUEcompletes the dialog,CANCEL returns theuser to the dialog


AZKBDlgRadioGroup Methods

The AZKBDlgRadioGroup object is returned by the AddRadioGroup method ofthe dialog box. It is used to define the contents of the group, i.e., thebuttons.


AddButton Adds a button to thegroup. A group can haveseveral buttons

ID: String

Prompt:String

BallonTip:String

Value:String


Prompt is caption

BalloonTip as above

(Not used: True orFalse are returned)

AZKBDlgComboBox Methods

The AZKBDlgComboBox object is returned by the AddComboBox method ofthe dialog box. It is used to populate the contents of the combo box:


AddOption Inserts thespecified stringinto the combobox

Display:String

Value:String

Display appearsin combo box

Value is thestring returned ifthis item isselected

Example: Combo Box

[?DisplayName = SelectOrientation,Interactive=true, Secure=true?]AZRule SelOrientation()

' Create the dialogset dlg = Server.NewKBDialog( "Select Orientation",

"OrientationReply")' Add some Text, F1 help and a cancel buttondlg.AddTextBox "Select the orientation"dlg.Cancel = true

'dlg.HelpString = "Choose an orientation" & vbCrLf & "from thedrop down"

Set combo = dlg.AddCombobox("Orientation", "Pick a value","Picka value")

combo.AddOption "0" , "1"combo.AddOption "90" , "2"combo.AddOption "180" , "3"combo.AddOption "270" , "4"' Add a combo box with four entriesset SelOrientation = dlg

End AZRule

3 Datasheets and the Datasheet Definer 47

3 Datasheets and theDatasheet Definer

Datasheets used by the Datasheet Editor must first be defined in theDatasheet Definer. A datasheet definition comprises two parts:

Dumb lines and text that represent the backing sheet

Live fields that display data directly from the database

This chapter contains information on:

Datasheets

Datasheet Definer

How the Datasheet Definer creates a datasheet

Starting the Datasheet Definer

Datasheet Definer Menus and Buttons

Datasheet Definer Browser

Datasheet Editor Template Migration Tool

DatasheetsThere are three main types of datasheet that can be generated using theDatasheet Definer:

Type ofDatasheet

Description

SummarySheets

Also commonly known as equipment lists, these show informationfrom numerous objects. They summarize the members of a class,usually displaying a limited number of attribute values for each. Thetotal number of members of a class cannot be predicted in advance.

You need only define one summary sheet for the class. Aspen BasicEngineering generates sufficient copies of the summary sheet todisplay all the existing class members.

ContinuousLists

(Excel Datasheet Editor only) Like summary sheets, continuous listsshow information from numerous objects, but instead of displayinginformation on multiple pages, all objects are displayed on a single,scrollable, continuous list.

48 3 Datasheets and the Datasheet Definer

Type ofDatasheet

Description

Datasheets These typically display information about a single object and perhapsits sub-objects.

Occasionally, a datasheet represents data relating to more than oneobject, for example, the compressor and inter-cooler datasheet. Inthis guide, the term datasheet is used loosely to refer to many typesof datasheet, including traditional datasheets, calculation sheets,design basis sheets, and so on.

You define datasheets to represent any of the following:

A set of objects, for example, a summary sheet of all the vessels in aplant

An individual object, for example, a datasheet for one vessel V101

Global project data, for example, site conditions and utility streamcharacteristics

Datasheet DefinerThe Datasheet Definer is a Microsoft Excel AddIn displayed as theDatasheets menu selection in the Microsoft Excel menu bar.

Note: You must pre-install Microsoft Excel to use the Datasheet Definer.

A floating toolbar can also be used as a shortcut for a number of menuoptions. To view the toolbar, select Datasheets | View Toolbar… from theExcel menu bar.


Use Excel to:

Define the graphical components of the datasheet, that is, the fixed textand lines

Define the size and formatting of cells that will become fields

Specify the number and order of pages in the datasheet by default

Use the Datasheet Definer to:

Specify that a cell is a field, by defining the link between fields on thedatasheet and attributes in the database

Copy and paste fields

Generate a datasheet

How Does the DatasheetDefiner Create a Datasheet?The Datasheet Definer uses the contents of the current Excel worksheet tocreate a datasheet for use in Aspen Basic Engineering.

In overview, the Datasheet Definer:

1 Examines the Excel worksheets, searching for:

o Text, lines, cell formats, and simple shapes

o Cell comments that contain XML fragments, which specify the fieldtype and link the field to the correct part of the Aspen BasicEngineering class store

2 Stores the information from the XML fragment in cell comment in a singleAspen Basic Engineering template file (.ztf).

3 Creates a run-time version of the Excel Datasheet (.ztx) which isformatted for improved performance and used by the Excel DatasheetEditor.

Starting the Datasheet DefinerTo start the Datasheet Definer:

1 From the Windows taskbar click Start | Programs | AspenTech |Aspen Basic Engineering xx.x | Configuration | Datasheet Definer.This launches Microsoft Excel.A menu option Datasheets is displayed in the Excel main menu.

2 To select the workspace that you wish to work on, click Datasheets |Open Workspace, the standard workspace dialog is displayed.

3 Select and then open a workspace.

Note: You must be logged into a workspace to define or change field routes.


Datasheet Definer MenusThe Aspen Basic Engineering Datasheet Definer has the following menuitems:

Open Workspace - Displays the Open Workspace dialog allowing youto select a workspace, connect as a different user, or change connectionsettings.

Close Workspace - Closes the currently open workspace.

Preview Mode - Disables the Definer add-in menus so that the datasheetcan be previewed only.

View ToolBar… - Displays the Datasheet Definer toolbar, which can bedocked (with the Excel menu items) or floating.

Generate Template - Generates an Aspen Basic Engineering Datasheettemplate. You must be logged onto a workspace and the Excel worksheetmust contain Aspen Basic Engineering fields before this command isactive.

Datasheet Options - Select this option to change the View and Printoptions of the datasheet fields, watermarks, and colors.

Edit - contains the following options:

o Read Only – Sets a field to read only status.

o Copy Field – Copies a selected field (or fields) onto the clipboard.

o Cut Field - Copies the selected field(s) onto the clipboard and deletesit from the current worksheet.

o Paste Field – Pastes the selected field (or fields) onto the worksheet.

o Radio Groups – Opens the Radio Button Groups dialog, allowingyou to configure (edit, delete, or add) radio button groups.

o Qualifier Groups – Opens the Qualifier Groups dialog, allowing youto configure (edit, delete, or add) qualifier groups.

o Set Repeat Area - In a continuous list datasheet, allows you to definethe direction of expansion for repeating areas as horizontal or vertical.

o Replace – Replaces field route content(s).

o Case - Sets the case using the Case dialog.

o Overspills – Checks whether overspills have been defined for thecurrent page. The Edit Overspill dialog allows you to edit and deleteoverspills.

Properties - contains the following options:

o Datasheet Properties… – Displays the Datasheet Properties dialog.

o Field Properties… – Displays the Field Properties dialog associatedwith the selected field.

Tools - contains the following options:

o Set Wildcard – Sets time-saving wildcards when specifying a largenumber of database routes. Applies to Value fields.

o Set Object – Sets the starting object for each set of fields. Applies toValue fields.


o Set Overspill - Defines an overspill association for a (pre-selected)set of Value fields.

o Attribute Browser – Opens the Attribute Browser dialog.

o Validate Fields – Validates fields on the worksheet.

o Refresh all pages – Refreshes the datasheet to update any changedfields.

o Generate Templates from Automation – Generates templates forall datasheets within a folder in a batch operation which is significantlyfaster than compiling each datasheet separately.

Link – contains the following options:

o Link – Create a link between a Value field and one or more Revision orDimension fields.

o Unlink – Breaks the link between a Value field and one or moreRevision or Dimension fields.

Help - contains the following options:

o Datasheet Definer Help – Opens help specific to the DatasheetDefiner.

o Training – Opens the AspenTech Training Center Web page.

o Product Support on the Web – Opens the Aspentech ProductSupport Web page.

o Contact Support – Opens the Technical Support Group topic in theAspen Basic Engineering Online Help.

o About Aspen Basic Engineering – Displays version information forthis release.

Datasheet Definer ToolbarThe Datasheet Definer toolbar contains icons which represent the controls fordefining field types on the datasheet. Each type of field defines a differentaspect of how the datasheet operates.

The following table describes their function:

Number Icon Description

1 Value Creates a field which displays a text value from adatabase attribute

2 Quantity Type Creates a field that displays the units for value fields

3 Revision Creates a fields that displays revision information andmust be linked to one or more value fields

4 Sketch Enables the user to add sketches to the datasheetusing OLE embedding

5 Bitmap Enables the user to display fixed bitmaps that are notchangeable by the datasheet user


6 Checkbox Opens the Checkbox Properties dialog allowing you tospecify and design a checkbox

7 Radio Button Opens the Radio Button Properties dialog allowing youto specify and design a radio button

8 Qualifier Opens the Qualifier Field Properties dialog, allowingyou to specify a group name, add/edit a group, andspecify a qualifier label

9 Copy Field Copies a selected field (or fields) onto the clipboard

Note: Copy/Paste of fields MUST be done using thetoolbar menu options. The use of Ctrl-C and Ctrl-V isNOT supported for AZ fields

10 Cut Field Copies the selected field(s) onto the clipboard anddeletes it from the current worksheet

11 Paste Field Pastes the previously copied field (or fields) onto theworksheet

Note: Copy/Paste of Fields MUST be done using thetoolbar menu options. The use of Ctrl-C and Ctrl-V isNOT supported for AZ fields

12 FieldProperties

Opens the Properties dialog associated with theselected field; e.g., if a Radio Button field is selected,the Radio Button Properties dialog is displayed

13 Refresh Refreshes the datasheet to update any changed fields

14 Delete Deletes the selected field (this button must be used todelete fields)

15 Browser Opens the Browser window

16 Link Links the currently selected field(s)

Datasheet Definer BrowserThe Datasheet Definer contains a class view attribute browser that lets youexamine the attributes of the selected class views and associate the attributewith fields.

To start the Browser:

From the Excel menu, click Datasheets | Tools | Attribute Browser.

A separate Browser window is displayed:


This window has one pane with five columns (which display descriptivecontent) and two menu options.

Browser Menu Items

Class View Menu

Item Description

Individually named ClassViews

Class views selected in the DocumentProperties dialog

Exit Quits the Browser application

Options Menu

Item Description

Always on Top Sets the Browser window to display infront of open applications.


Datasheet Editor TemplateMigration ToolStarting with 7.2 EP1, the Aspen Basic Engineering Excel Datasheet Editoruses a runtime template to improve performance. This template has a ZTXfile type and is installed with the ZTF templates on the server in theTemplates folder. The Datasheet Definer automatically generates thistemplate during the Template Generation Process.

The Datasheet Editor Template Migration Tool creates ZTX templates forcustom datasheets and migrates templates that have been cached. Cachedtemplates are used to open these datasheets so the datasheet appears as itdid when it first entered the submit, check, and issue process.

Note: If you do not have custom datasheets and have not used V7.1 CP2document revision control, you do not need to use the Datasheet EditorTemplate Migration Tool.

Migration steps depends upon your situation:

If you have custom datasheets, use the Template Migration Tool to createZTX files for custom datasheets and put them in the templates folder.

If you used V7.1 CP2 document revision control, use the TemplateMigration Tool to convert the XLS files cached on your workspaces to ZTXfiles.

If you had custom datasheets and used V7.1 CP2 document revisioncontrol, you need to follow these steps in this order:

o Use the Template Migration Tool to create the ZTX templates for eachcustom datasheet.

o Migrate the server cached templates for the workspaces containingsubmitted Excel datasheets.

o Copy the custom ZTX templates to the server WorkspaceLibraries\Templates folder.

Getting StartedBefore starting any conversions, you will need to set Excel to Trust access toVisual Basic Project.

In Microsoft Excel 2003:

1 From Tools menu, click Macro | Security…

2 On Trusted Publishers tab, select Trust access to Visual Basic Project.

3 Click OK.

4 Close Excel.


In Microsoft Excel 2007 or 2010:

1 Click the Office button. Select Excel Options.

2 Select Trust Center from the list of topics on the left.

3 Click Trust Center Settings…

4 Select Macro Settings from the list of topics on the left.

5 Select Trust access to the VBA project object model.

6 Click OK.

7 Close Excel.

To open the Datasheet Editor Template Migration Tool, double-click theDatasheetEditorTemplateMigration executable in C:\ProgramFiles\AspenTech\Basic Engineering xx.x\UserServices\bin. The DatasheetEditor Template Migration Tool dialog box appears.

Creating a ZTX Template for each CustomDatasheet TemplateYou have two options for creating ZTX Templates for custom datasheettemplates:

Batch Migration creates a ZTX template for each custom datasheettemplate in batch mode.

Single Template Option creates a single ZTX template from a single XLSand XTF file combination and is useful when resolving errors encounteredduring batch operations.

Batch Migration

To create a ZTX template for each custom datasheet template in batchmode:

1 In the Datasheet Editor Template Migration Tool dialog box, select theBatch Migration tab.

2 Select the Create ZTX templates from XLS and ZTF templates option.

3 Use the Browse buttons to identify the folders where the XLS and ZTFtemplates are located.

4 Use the Browse button to identify a folder for placing the log file forrecording any errors and warnings.

5 Click Start.

6 After the Datasheet Editor Template Migration Tool creates the ZTXtemplates, click Open log file. The log has an entry for each templatethat has been generated along with any errors or warnings. If anytemplate has errors or warnings, resolve the issues and regenerate theZTX template for that datasheet using the Single Template Options.


Single Template Options

To generate the ZTX template for a single template:

1 In the Datasheet Editor Template Migration Tool dialog box, select theSingle Template Options tab.

2 Select the Create ZTX template from selected template option.

3 Use the Browse buttons to identify both the XLS and ZTF file locations fora single template.

4 Click Start. The Datasheet Editor Template Migration Tool creates the ZTXtemplate.

Migrating Server-Cached TemplatesAfter a ZTX template has been created without error for each customtemplate, the cached templates can be migrated for each workspace.

Note: This migration is required for all workspaces containing datasheetssubmitted using release V7.1 CP2. However, the migration is not required forthe following:

All workspaces created before V7.1 CP2 V7.1 CP2 workspaces where document revision control was not used

(documents not submitted).

You have two options for migrating the server-cached templates:

Batch Migration migrates the templates in batch mode.

Single Template Option migrates a single template and is useful whenresolving errors encountered during batch operations.

Batch Migration

To migrate the templates in batch mode:

1 Perform a database backup and an AZBackup for each workspace.

2 In the Database Template Migration Tool dialog box, select the BatchMigration tab.

3 Select the Convert cached server templates to ZTX format option tomigrate the cached templates.

4 Use the Browse button to locate a work folder in which to place thecached XLS and ZTF templates.

5 Click Start.

6 The standard Open Aspen Basic Engineering Workspace dialog boxappears; choose the appropriate workspace to open.

The XLS and ZTF files for each cached template are placed in the Cachedtemplate folder as read-only files along with a log of the migration process.Archive the contents of this folder for future reference.


If a problem occurs with a particular template, resolve the problem andreplace the template using the Single Template Options.

Single Template Options

To migrate a single template:

1 In the Database Template Migration Tool dialog box, select the SingleTemplate Options tab.

2 Select the Replace cached server template with ZTX file option tomigrate the cached templates.

3 Use the Browse button to locate a ZTX file to be used to replace thecached version on the workspace.

4 Click Start.

5 The standard Open Aspen Basic Engineering Workspace dialog boxappears; choose the appropriate workspace to open.


4 Preparing Datasheets in Microsoft Excel 59

4 Preparing Datasheets inMicrosoft Excel

The Datasheet Definer automatically picks up the graphical structure ofdatasheets, but you also need to tell it what Aspen Basic Engineering datayou wish to display.

To do this, you use buttons on the Datasheet Definer to specify that cells onthe worksheet are fields. It is possible to specify a cell to represent any of thefield types available in Aspen Basic Engineering.

This chapter contains information on the following items:

Value fields.

Quantity type fields.

Revision fields.

Sketch fields.

Bitmap fields.

Checkbox fields.

Radio button fields.

Qualifier fields.

Viewing and checking fields.

Using the browser.

FieldsYou set up cells for active fields in the Excel worksheet. The DatasheetDefiner picks these up when it creates the datasheet template, and stores theinformation in a .ztf (Aspen Basic Engineering template file) file for use byAspen Basic Engineering. Later, when you open the datasheet in Aspen BasicEngineering, the active fields link to the correct part of the class store.

Use the Datasheet Definer menu options to set up these cells. The toolbarcontains buttons, which represent the types of field that can be defined on thedatasheet.

60 4 Preparing Datasheets in Microsoft Excel

Each type of field defines a different aspect of how the datasheet operateswhen it is incorporated into Aspen Basic Engineering.

Important! Merging CellsDo not merge cells after a field has been placed in a cell.Instead:Delete the field using the Delete toolbar button.Merge the cells left and or up.Add a new field to the empty cell.

Value FieldsValue fields are used to display database values on a datasheet.

A value field gives the database location, in terms of a class view attribute,from where values are retrieved. This specifies the location of the data in thedatabase.

A typical datasheet displays data for four different objects:

This Data For Example Is Accessed From

Global data Project name, customername

GlobalsClass object

Document specificdata

Document number, revisionhistory

Document object

Page specific data Page number Page object

Object data Pressures, temperatures Equipment object and relatedsub-objects (e.g., vessel,agitator and nozzles)

Inserting Value FieldsTo insert a value field:

Select a cell on the worksheet then click the Value Field button.

Value Field RoutesA route is the most important property for a value field. You set routes usingthe browser.


Value Field OptionsYou can attach options to a value field to give the user a list of possiblevalues for the field. Field options can be either:

A list of predefined values.

-or-

The name of a knowledge base method that is used at runtime todetermine the list of applicable values.

Note: If the field attribute type is an enumeration, Options cannot be set.

To add or modify field options:

1 Select the Value field(s).

2 Select the Properties toolbar button to display the Value fieldProperties dialog and select the Options tab.

3 Select one of the option modes: Forced, Free or Method:

o Forced restricts the field to accept only those values listed in theOptions property.

o Free lets the user ignore the list of options and type in any value.

o Method specifies the name of a method for generating the list.

Forced Option Mode

To specify Forced as the option mode:

1 Select the Forced radio button.

2 Type in the text you wish to appear in the options list.

3 Click the Add button.Your text is added to the Options list.

To remove an item from the list:

Select the item and click the Remove button.

Free Option Mode

To specify Free as the option mode:

1 Select the Free radio button.

2 Proceed as for Forced, earlier.

Method

This topic explains how to specify Method as the option mode, then givesbackground information on methods.

1 Select the Method radio button.

2 In the Method Name box, enter the name of the method.


Multi-line FieldsMulti-line fields enable you to place text that is longer than the field itself,over multiple lines on the datasheet.

To create a multi-line field:

1 Create a value field as described in Inserting Value Fields.

2 Select the Properties button to open the Properties dialog and specify thenumber of lines in the lines field.

Note: Lines of a multi-line value control are equally spaced, sothe taller you make the control, the wider the spacing betweenthe lines.

Field CasesBy default, datasheets display information from a single database case, butcertain types of datasheet need to be defined that can display informationfrom two or more cases on the same document.

When you define a datasheet, you do not know in advance the names of thecases in a workspace. The Datasheet Definer enables you to group fields thatdisplay data from the same case. You group them by defining a name. Thisname is not necessarily used as a workspace case name and exists only atthe datasheet definition stage.

If the datasheet is to display data from a single case, you need not assign thefields to a case. Any fields not assigned to a named case group are assumedto display information from the overall case of the datasheet.

To set the case for a field:

1 Select the Properties for the field.

2 Type or select a case name to use, in the case window.

Overspill FieldsOverspilling of datasheets allows the automatic spilling of objects onto anoverspill sheet, when there is no room left for additional objects. Theoverspilling process can be likened to the association of one datasheet toanother. Overspilling dictates where the current datasheet overspills onto.

For example, consider a vessel datasheet that has 20 nozzles, and no spaceleft for any more. Any subsequent nozzles require an overspill. The overspillsheet or association in this case is a separate nozzles sheet, which onlydisplays nozzle information. By defining an overspill association, thesubsequent sheet is automatically created, containing only those nozzles thatdo not fit on the first sheet.


Defining Overspill Associations

To define an overspill association:

1 Select the value controls from which you wish to overspill.

2 From the Datasheet Definer Edit menu, click Overspill.The objects in the selected controls are added to the overspill and an EditOverspill dialog box is displayed:

Overspill Template

The Overspill Template box is at the top of the Edit Overspill dialog box.

It gives the name of the template representing the overspill page. This can bethe same as the current template. You must define the overspill templateagainst either the same class of object or one of its superclasses.

Routes

Below the Overspill Template box, there is a list of routes that causeautomatic overspilling.

To add an entry in this list:

1 Select the control.

2 From the Datasheet Definer Tools menu, click Overspill.

Note: In the vessel example described above, you should also define anoverspill association for the nozzles sheet so that, if this second page is filled,a third identical page is created. That is, the vessel sheet overspills onto anozzles sheet, and the nozzles sheet overspills onto another nozzles sheet.

To stop a route overspilling:

In the Edit Overspill dialog box, select the route and click the Deletebutton.

Quantity Type FieldsMany value fields have associated unit fields, for example ‘mm’ for a length-dependent field. A quantity type field controls the unit of measure in whichone or more value fields are displayed. The quantity type field displays thecurrent units; values linked to the quantity type field are automaticallyconverted to the displayed unit, then redisplayed.

Inserting Quantity Type FieldsTo insert a quantity type field, select a cell on the worksheet, then click theQuantity Type Field button.

A quantity type field is inserted, but is not yet linked to any value fields.


Linking Quantity Type FieldsA single quantity type field represents the units of either a single value field,or a set of value fields.

To link a quantity type field to a single value field or a set of value fields:

1 Select the quantity type field together with the value field(s) that you wishto link to.

2 From the Datasheet Definer Link menu, click Link. (Alternatively, clickthe Link button on the Datasheet Definer toolbar.)

A link is made between the quantity type field and the value field(s). Thequantity type field is redrawn to show the name of the quantity type.

Unlinking Quantity Type FieldsYou can remove the link between a value field and the quantity type field.

To unlink a quantity type field:

1 Select the quantity type field or fields.

2 From the Datasheet Definer Link menu, click Unlink.

Revision FieldsMany datasheets have markers on the edge of the page indicating values thathave changed between successive issues of the datasheet.

Use revision fields to place these markers on the datasheet. Revision fieldsare linked to specific value fields; they display the current issue number, ifany of the fields to which they are linked, changed since the previous issue.

Inserting Revision FieldsTo insert a revision field:

Select a cell on the worksheet then click the Revision Field button.

A revision field is inserted, but is not yet linked to any other fields.

Linking Revision FieldsA single revision field can link to one or more value fields.

To link a revision field to one or more value fields:

1 Select the revision field together with the value field(s) to which you wishto link.

2 From the Datasheet Definer Link menu, click the Link button or toolbarbutton.

A link is made between the revision field and the value field(s).


Unlinking Revision FieldsYou can remove the link between a revision field and the value field.

To unlink a revision field:

1 Select the revision field or fields.

2 From the Datasheet Definer Link menu, click Unlink.

Sketch FieldsDatasheets often contain a sketch area in which the end-user can add anillustration of the equipment, or additional detail about the equipment.

A sketch field enables OLE (Object Linking & Embedding) objects to beinserted and edited at runtime via an OLE application such as Paintbrush,Microsoft Excel or Microsoft Word.

Inserting Sketch FieldsTo insert a sketch field:

Select a cell on the worksheet then click the Sketch Field button.

You can add any number of separate sketch fields to a datasheet, with eachsketch area representing a single OLE field.

Bitmap FieldsDatasheets often have a corporate logo displayed in the header of thedatasheet, and sometimes a project or client logo. If these logos are providedas bitmaps, you can easily change them in the runtime system withoutmodifying the datasheet definitions. To change logos on the datasheet, youneed only replace a single bitmap file. Bitmaps are scaled automatically to fitwithin the defined bitmap field.

Inserting Bitmap FieldsTo insert a bitmap field:

Select a cell on the worksheet then click the Bitmap Field button.

This displays the bitmap selection dialog allowing you to select from a list ofavailable bitmaps in the current workspace.

The bitmap is automatically scaled to fit, and centered within, the selectedarea when the datasheet is used in Aspen Basic Engineering.


Checkbox FieldsA Checkbox represents a Boolean attribute (True/False). Checkboxes take theform of shapes on the sheet and are marked to indicate if the option isselected, normally with a tick or cross).

To create a Checkbox field:

Select a cell.

Select the Checkbox button from the toolbar. The Checkbox dialog isdisplayed (with two tabs; Attribute and Shape).

The Attribute tab is similar to the Value Fields tab and allows thespecification of; rate, case and read-only flags.

The Shape tab allows you to specify:

o The Checkbox shape.

o The indicator used to show it is selected.

o Shape properties such as weight, color, indent and aspect ratio.

Set the properties required and click OK.

A Checkbox is inserted in the selected field.Note: A route must be specified.

Radio Button FieldsA radio button allows you to choose one item from a set of options for theattribute. Radio buttons take the form of a set of shapes and when one isselected, it is marked to indicate the choice. All other choices in the group areunmarked.

To create a radio button:

Select a cell.

Select the Radio Button toolbar icon, a Radio Button dialog is displayedallowing you to configure the button.

The Shape, Indicator and Shape Properties areas allow you to specify thebutton shape, indication type and properties (similar behaviors to theCheckbox dialog).

The Group and Value area allows you to specify the route and final valuein the database.

To create a set of linked radio buttons:

Create a number of buttons that select different values for the samegroup.

To create a new group:

Select the New Group button from the dialog.Note: ‘Other’ fields are also possible with radio buttons, see ‘Other’ Fieldsfor further details.


Radio GroupsRadio groups are used in the definition of radio buttons. A radio groupcomprises a name, route and a set of Radio Buttons that provide the visualdisplay.

The name is a tag used within the datasheet definition to refer to this group.The route is a link to the associated class view attribute. This attribute isusually an enumeration type and from the class view will supply the possiblevalues to use.

‘Other’ Fields‘Other’ fields are a special type of value field associated with a set of radiobuttons. They are used where there are a number of common options, butwhere the common options do not cover all possibilities.

To create an ‘Other’ field:

1 Select a cell and insert a Radio Button that is defined against an openenumeration.

2 Set the option of this button to be "Other value..." (this appears at thebottom of the set of options for the enumeration).

3 Add a Value field to the datasheet and link the button previously definedwith this value field.

4 Set the route for the Value field to be the same as the route for the radiobutton group.

The button and value fields are now linked and in the Datasheet Editor youare only able to edit the value field when the button is selected.

Qualifier FieldsQualifier fields are fields on a datasheet that modify the route associated withone or more other fields. They take one of two appearances:

1 A set of texts, one of which is normal, the rest are struck-out. (Forexample, Duty Clean / Duty FouledFailed 10.)

2 A set of radio buttons, one of which is selected.

If no qualifier has been selected, the associated value fields display no valuesand cannot be edited.

To create a Qualifier field:

Select a cell.

Select the Qualifier Field toolbar button.


Checking FieldsAt any time, you can check the fields on the worksheet. To do this:

From the Datasheet Definer Tools menu, click Validate Fields. AspenBasic Engineering checks the validity of the routes and links. Anyproblems are listed in a validation dialog box.

Using the BrowserThe Datasheet Definer contains an attribute browser that lets you examinethe class view and specify the routes of the fields.

To start the Browser:

From the Datasheet Definer Tools menu, click Browser.A separate Browser window is displayed. This window is divided in two:

o A tree view on the left side, which displays the nodes in the class view.

o A list view on the right, which displays the attributes in the selectedclass view node.

Navigating the Class View HierarchyYou navigate the class view hierarchy by opening the nodes displayed in thetree view, on the left:

Different data types are shown using individual icons.

Specifying a RouteTo specify the route of a value field from the Browser:

1 Select the value field.

2 In the Browser list view, double-click the attribute.

Assigning WildcardsIf you are defining a datasheet with a large number of almost identical routes,for example to show the bore of 10 nozzles on a vessel, use a wildcard in theroute to signify that the numerical position of the object is not specified. Thisspeeds up the field creation process.

Having inserted one set of fields representing the values required from asingle nozzle, you can copy them many times to produce a table of values.

To convert the wildcard into a numerical value:

1 Select the Value field(s).

2 From the Datasheet Definer Tools menu, click Set Wildcard.

3 Specify the position number to use.


Assigning ObjectsAssigning objects is common practice when defining summary sheets orequipment lists. Occasionally, a datasheet representing data for more thanone object may also use this operation. This is similar to using a wildcard aspart of the route. The route to a field always starts with the top level objectbehind the field.

For example, the route to the temperature-operating attribute for a vesseldatasheet would be Vessel (1). On a summary sheet, multiple top levelobjects appear and you must specify from which of the objects the routeshould start.

To speed up summary sheet definition, it is good practice to add all of thefields for the sub-objects that represent one object, then copy them for theother objects. After you have added all of the rows of fields, the top levelobject for each set of sub-object fields can be assigned.

To set the starting object for each set of fields:

1 Select the controls.

2 From the Datasheet Definer Tools menu, click Set Object.


5 Generating Datasheets 71

5 Generating Datasheets

Generating a DatasheetBefore generating a datasheet, ensure that you have added any necessaryfields to the Excel worksheet. See the previous chapter for information.

Note: You must pre-install Microsoft Excel to use the Datasheet Generator.

This section describes the steps you need to take to generating a datasheet,ready to load into Aspen Basic Engineering.

To create a datasheet:

From the Datasheet Definer menu, click Generate Template.

The datasheet template file (.ztf) is generated and saved in the same locationas he .xls workbook. It is not loaded into Aspen Basic Engineeringimmediately.

For information on loading datasheets, see the next section.

Note: This process creates the templates, but does not save the originalExcel spreadsheet. You must do this separately, within Excel. If you changethe contents of the Excel worksheet, you must regenerate the datasheet andload it into the worksheet to make the changes visible in Aspen BasicEngineering.

Using Excel FeaturesUse Excel’s built-in features to format cells and lines on the datasheet:

Cells – The text you enter into a cell and its font and position are used bythe datasheet. Any borders you draw around the cell are also used.

Lines – Lines drawn on the worksheet are transferred to the datasheet,but arcs are not.

Shapes – Circles, hexagons, rectangles and triangles are recognized, butother shapes are not.

72 5 Generating Datasheets

6 Symbols, Labels and the Graphics Definer 73

6 Symbols, Labels and theGraphics Definer

This chapter describes the role of symbols and labels in the Aspen BasicEngineering Drawing Editor. It also gives an overview of the (Aspen BasicEngineering) Graphics Definer tool for modifying and creating symbols andlabels.

Symbols and Labels in theAspen Basic EngineeringDrawing EditorThe Aspen Basic Engineering Drawing Editor is supplied with a selection ofsymbols and labels, used to construct drawings.

Typically, a drawing contains equipment items linked together by a network ofconnections. The equipment items and connections are labeled with text, andmay have data displaying in their vicinity:

Symbols are used to represent the equipment items and connections.

Labels are used as placeholders for text and data.

In this picture, two columns (C-100 and C-101) are linked by a connection(stream number 3):

74 6 Symbols, Labels and the Graphics Definer

About SymbolsSymbols comprise a drawing with a specified datum that controls thesymbol's behavior when it is dragged or placed on the drawing:

Some of the graphical elements of the drawing may be nominated as parts,which means they act as place-holders for connections when placed on thedrawing.

Each symbol must be associated with the class of object that it represents(for example, a pump).

6 Symbols, Labels and the Graphics Definer 75

About LabelsLabels comprise one or more fields that display database values, units andother drawing data.

You can use graphics and annotations (plain text) to enhance labels. As withsymbols, labels have a datum point that controls their behavior when draggedor placed on the drawing.

The choice of fields are:

Value fields for displaying data.

Units fields for displaying units of measure.

Labels must be associated with the class view for which the label is intended.

Graphics DefinerThe (Aspen Basic Engineering) Graphics Definer is a tool specifically designedfor creating symbol and label definitions for use in the Aspen BasicEngineering Drawing Editor.

76 6 Symbols, Labels and the Graphics Definer

You use the Graphics Definer to draw graphical symbols that representequipment, then define their behavior such as connectivity, placement andinteraction with other symbols.

With the Graphics Definer, you can design labels that can be associated withclasses in the drawing, and which display data in fields within the label. Theindividual fields display live data from the database.

Here is some guidance for using the Graphics Definer:

Launch the Graphics Definer from the desktop Start menu, in the sameway as the Aspen Basic Engineering Drawing Editor.

You must create separate symbol and label files.

Different toolbar buttons and menu commands are enabled, depending onwhether you are working with symbols or labels.

Completed label files are saved and compiled; completed symbol files areonly saved.

Starting the Graphics DefinerTo start the Graphics Definer:

From the Start menu, point to Programs | Aspen Technology | AspenBasic Engineering | Configuration then click Graphics Definer.

This launches the Graphics Definer as a separate working window:

7 Defining Symbols and Labels: Worked Examples 77

7 Defining Symbols andLabels: Worked Examples

This chapter provides two worked examples that show you how to create anew symbol and a new label.

Example of Creating a NewLabelThis example takes you through the steps for creating a new label using theGraphics Definer.

The key stages in the process are:

Create a new label file.

Specify any label characteristics, such as the class of object for which thelabel is intended.

Place and specify Value fields.

Place and specify Plain Text fields.

Place and associate Units fields.

Draw any supplementary graphics to enhance the label (for example, arectangular border).

Set the datum for the label.

Compile the new label file.

78 7 Defining Symbols and Labels: Worked Examples

Creating a New Label FileTo open a new label file:

1 Launch the Graphics Definer from your desktop Start menu:

Start | Programs | AspenTech | Aspen Basic Engineering |Configuration | Graphics Definer

This launches the Graphics Definer as a separate working window.

2 If not already connected to a workspace through the Graphics Definer,connect now by clicking the Open Workspace button.

3 Click the New Label button.

4 In the New Label dialog box that appears, specify a name and locationfor your new label file, and save it as type *.sym.

A new label sheet appears in the Graphics Definer working window. This is thecanvas where you create the new label.


Specifying Label CharacteristicsHaving opened the new label file, you now specify any label characteristics:

Label information – You must specify the class view for which the label isintended, but the other settings are optional.

Sheet Size – Contains default settings, so is optional.

Text properties for the label – Contains default settings, so is optional.

Specifying Label Information

To specify label information:

1 From the Graphics Definer Edit menu, click Properties. (Properties isalso available as a right-click menu option.)The Label Properties dialog box appears, with the Label Information tabvisible.

Most of the settings in the Label Properties tab are optional, but you mustspecify a class view suitable for use by the fields that you want to add.


2 In Global, Document or Object Class view, specify the class view for whichthe label is intended. Either:

o Navigate to the class view, by clicking one of the Browse buttons andusing the browser in the Class View dialog box (recommended)

o -or-

o Type in the class view for which the label is intended.

The other settings have default values. They govern how the label willbehave when the label is placed on a drawing.

Specifying the Sheet Size

This task is optional.

If your label is intended as a border for sheets, you may wish to change thesize of your new label sheet, to serve as a guide for the placement of objects.The size of a label sheet acts only as a guide, and serves no other purpose.

To specify the sheet size:

Open the Label Properties dialog box and go to the Sheet Size tab.

Changing Text Properties for Labels


You can change the default text properties for your new label. These changes:

Remain in force for any future labels that you create.

Do not affect existing labels.

To change the default text properties:

Click the Default Text Properties button.


The Default Text Properties dialog box appears.

Use the three radio buttons at the foot of the dialog box, to specify textproperties for Value fields, Units fields and Plain Text fields. The settingscan be different for each type of field.

Note: To change the text properties of any previously placed text fields,double-click the text to access the appropriate 'properties' dialog box.

Creating Multi-Line Value Fields


You can change the properties of the text boxes that house the Value fields,so that they appear on two or more lines. This makes long Value fields tidieron the drawing.

You do this in the Default Text Properties dialog box, using the BorderDimensions settings at the bottom right hand corner of the (expanded) dialogbox.

Y (height) and X (width) have three settings. You can choose the same ordifferent settings for Y and X:

Auto – The text box sizes in the selected dimension(s) to fit the text inthe field.

Exactly – The text box excludes text outside its limits in the selecteddimension(s).

At Least – The text box has a fixed, minimum size in the selecteddimension(s), but will expand beyond if required.


To define a multi-line Value field:

1 Set the font type and size.

2 In Border Dimensions, specify the width (X) as Exactly.

3 Set the height (Y) to either:

o Auto for a text box with fixed width, which expands in the vertical toaccommodate text.

o -or-

o Exactly for a text box with a fixed height and width.

4 Click OK to preserve the changes for all subsequent text boxes.

Note: Text justification with Y and/or X set to Auto:1 Height (Y) – If you specify the text justification as Text Top, Text Caplineor Shape Top, then the text box is fixed at the top edge and expandsdownwards. If you specify text justification as Text Baseline, Text Bottom orShape Bottom, the text is fixed at the bottom and expands upwards.2 Width (X) – This is similar to the height, with 'Left' and 'Right' replacing'Top' and 'Bottom'.

You are now ready to create the content of the label. This involves addingValue fields, Units fields and Plain Text fields, and setting the datum point.

Placing and Specifying Value FieldsValue fields are the main components of a label. They display data for theobject for which the label is intended. In our example, we are going to placetwo Value fields for the object class view PUMP, the first is capacity and thesecond is pressure difference.

Placing Value Fields

To place a Value field:

Click the Place Field button.

The Graphics Definer is now in Value field placement mode. Each time youclick on the sheet, a question mark in square brackets appears. To stop thisprocess, click any other command button (the Select button is a good choicefor this).

Once you have placed a Value field on the sheet, you need to specify itscharacteristics. In particular, you need to specify a route for the field so thatit displays the correct data. You do this through the Field Properties dialogbox.


Opening the Label Field Properties Dialog Box

To open the Label Field Properties dialog box:

Double-click the Label field.

Tip: For a selected Value field, there are two other ways of opening the LabelProperties dialog box:

Right-click on a blank part of the sheet, and from the menu that appears,click Properties.

From the Graphics Definer Edit menu, click Properties.

Setting Up Routes to Value Fields

You need to set up a route between the Value field and the class of object, sothat the field displays the correct data.

To do this:

1 Open the Label Field Properties dialog box (see earlier) and go to theRoute tab.


2 Select from the three class view options in the Browse from section. Inour example we have selected the Object class view which we set up inthe document properties earlier. Next select an attribute from thosedisplayed in the Data View list.

Tip: Right mouse click on any item to display detailed properties. Together, these twoselections define the route for the Value field. In our example, we have specified aroute for our Value field, with the attribute Capacity within the GraphicDefinerPumpclass view.

Note:

You can also type in the route, but this is not recommended. You can fill in your own tag, or have it done automatically once you have specified

the route. If you filled in the tag yourself, this will not update when you specify theroute.A suitable tag will be suggested in the Tag box, the first time you select a routefrom the Class Browser.

You may add a description, which will be used to aid identification of fields in theDrawing Application. This allows you to define short tags if you wish to clarify yourlabel definition.

Setting Up Lists of Options for Value Fields

You may want a Value field to display a list of options. For example, the fieldmay be the list of contributors to a plant design, so the Value field shouldshow these peoples' names, and nobody elses.

To set up option lists:

Open the Label Field Properties | Options/Method tab.In our example, we are not specifying the CAPACITY Label field:


Note: Options cannot be set if the route of the field produces an enumerateddata type.

The table outlines the three available choices: None, Options and Method.

Choice Description

None No options specified. This is the default

Options Create a list of (static) options, which you type in on the left, and thentransfer to the right using the various arrow buttons

You can move items up and down the list, but you cannot duplicate them

Method Run a specified method that resides on the server, to create a dynamic listof options

The method runs and returns one or more options for the user to choosefrom, or performs an action that requires no user response

If the method does not exist on the server, then an error occurs when thelabel is installed and used

If you select Selection from Options/Methods Only checkbox, this restricts thechoice of the user to the list of options, or the list returned from the method.

Making Fields Read Only

To make fields read only:

In the Label Field Properties dialog box, select the Field is Read Onlycheckbox.

This checkbox is available for all tabs.

Example Label with Two Value Fields Added

In our example label, we have placed and then specified two Value fields,CAPACITY and DIFF P.


Placing and Specifying Plain TextYou can add plain text to annotate your label.

To add plain text to a label:

1 Click the Place Plain Text button.

The Graphics Definer is now in plain text placement mode. Each time youclick on the sheet, a question mark appears. To stop this process, clickany other command button (the Select button is a good choice for this).

2 Double-click the plain text, and in the dialog box that appears, type in thetext for the annotation. You can also change the text properties.

Example Label with Plain Text Added

In our example, we have added two pieces of plain text, Capacity and DiffPress:

Placing and Associating Units FieldsIf your Value field displays data for physical quantities, such as temperatureor pressure, then it will need matching units of measure. You add units ofmeasure using Units fields.

Placing Units Fields

To place a Units field:

Click the Place Units Fields button.

The Graphics Definer is now in field placement mode. Each time you click onthe sheet, a question mark in round brackets appears. To stop this process,click any other command button (the Select button is a good choice for this).


Associating Units Fields to Value Fields

Having placed a Units field on the sheet, you need to associate it with a Valuefield. There are two ways of doing this:

Select the Units field and the Value field it serves, then click theAssociate Field button. This is the recommended approach; we haveused it in our example.

- or -

Double-click the Units field and in the Label Units Field Propertiesdialog box, manually define the associations.

Making Units Fields Read Only

To make Units fields read only:

In the Label Units Field Properties dialog box, select the Field is ReadOnly checkbox.

This checkbox is available for all tabs.

Example Label with Units Fields Added

In our example, we have selected the CAPACITY Value field and theneighboring Units field, ready to datasheet the association using theAssociate Field button.

Tracking Unit Field Associations

You can keep track of any associations that you have set up.

To do this:

Click the Associations button.

.

The picture shows our example label, with two associations flagged: one forCAPACITY and one for DIFF P.


Drawing Supplementary GraphicsYou can add graphics. For example, you may want to draw a rectangle aroundthe label. Graphics are added to labels using the standard drawing toolbuttons on the left side of the of the Graphics Definer working window.

Defining a Datum for the LabelThe datum defines how a label is dragged and placed on a drawing.

To view the datum for a label:

Click the Show/Hide Datum button.

.The datum point appears as a green target, which you cannot manipulate.

To set a datum for a label:

1 Click the Set Datum button

.A red interactive target appears.

2 Either:

o Drag-and-drop the target at your chosen datum point.

o - or -

o Click at the new datum point.

In our example, we have set a datum to the lower left of the fields:


Defining a Mass Balance Insert Point forthe LabelIf your label is a Mass Balance Header or a Mass Balance Column, youwill need to define a Mass Balance Insert Point for it. This is a point at whichthe next column will begin. The datum of the next column will be positionedto coincide with this point.

Setting a Mass Balance Insert Point is similar to Setting a Datum. Just clickon the Set Mass Balance Insert Point button or menu entry and position it onthe sheet with a mouse click.

The Show/Hide Mass Balance Insert Point button or menu item results in thecurrent Mass Balance Insert Point location being displayed.

Example of a Mass Balance Grid Header with Datum and Mass Balance InsertPoint displayed:


Compiling the New Label FileWhen you have completed your label, you need to compile it before using it inthe Aspen Basic Engineering Drawing Editor.

To compile your label:

1 Click the Compile Label button.

This creates an xml definition of the label. Any errors are reported in alist, which you can double-click for more information.

After successful compilation, you are prompted to save the label files.

2 Save the xml definition file with the extension .ztf.

3 Save the label file with the extension .sym.

Example of Creating a NewSymbolThis example takes you through the steps for creating a new symbol usingthe Graphics Definer.

The key stages in the process are:

Create a new symbol file.

Draw the symbol.

Specify any symbol characteristics, such as part definitions.

Specify any parts and tool tips.

Set the datum for the symbol.

Add any dimensions to the symbol (optional).

Save the new symbol file.

Creating a New Symbol FileYou create a new symbol file in the same way as a new label file (see earlier),but use the New Symbol button instead.


Drawing a New SymbolHaving opened a new symbol file, you can now draw the symbol using thetools on the Drawing toolbar, which is on the left of the Graphics Definerworking window.

In our example, we have used a circle with an internal triangle to represent acentrifugal pump.

Specifying Symbol CharacteristicsYou must specify some characteristics for a symbol, such as the class ofobject that it represents.

To do this:

1 From the Graphics Definer Edit menu, click Properties. (Properties isalso available as a right-click menu option.) The Symbol Propertiesdialog box appears, with the Symbol Information tab visible.

2 This illustration shows the Symbol Properties dialog box:


3 In Class, set the class of object that the symbol represents. To do this,click the Browse button and in the Class Browser that displays, navigateto the class of object.

4 In Symbol Type, select a type of symbol from the list provided. Be carefulto choose a type that does not conflict with your choice of object class (forexample, the choice Stream will conflict with the object class PUMP).

5 Modify the other settings as required.

6 If necessary, change the sheet size by going to the Sheet Size tab. SeeSpecifying Label Information, earlier.

Specifying Parts and Tool TipsParts are graphical elements of a symbol that are nominated place holders forconnectors, such as inlet and outlet points.

You can create tool tips for parts. These are meant to guide users as theymake connections to symbols in the drawing. Tool tips appear in the drawing,when you place the cursor over a nominated part.

To specify a graphical element as a part:

Click the Parts Definition button.

The Edit Part Definition dialog box appears.


To create a tool tip:

1 In the Name box, type in the name of the part.

2 In the Tool Tip box, type in the tool tip to be seen by the user.

Note: If you have previously filled in the Name text box, the text isautomatically transferred over to the Tool Tips text box.

Example Symbol with Parts and Tool Tips Defined

In our example, we nominated one of the graphical elements in the center ofthe symbol as a part. Physically, this part is an input to the equipment item,so we want to restrict connections to one angle, 180 degrees, which is atright-angles to the part. We have added the tool tip 'inlet' to guide the user.


Defining a Datum for the SymbolYou define a datum point for a symbol in the same way as for a label (seeearlier). In our example, the datum is placed in the center of the symbol.

Adding Dimensions to the SymbolThis is an optional task.

You may want to annotate the lines and angles on your symbol withdimensions, as commonly seen on engineering drawings. For example, yoursymbol may be a column on a refinery, and you want to show that the columnis 15 meters high.

To do this, you must first create the Dimensions toolbars, as follows:

1 From the View menu, click Toolbars.

2 In the Toolbars dialog box that appears, click Customize.The Customize dialog box appears.

3 In the Categories list, select Dimension.The Dimension suite of buttons appear in the dialog box.

4 Drag-and drop these buttons onto the toolbar area of the GraphicsDefiner.

You can now add dimensions to your symbol:

Click the appropriate button on the Dimensions toolbar. For example, clickSmart Dimension to add the length of a line.

To change the format of dimensions (for example, the style of the arrowheads):

From the Format menu, click Dimensions.

Saving the New Symbol FileUnlike a new label file (which needs compiling), you need only save a newsymbol file.

8 Extracting Legacy Symbols and Labels 95

8 Extracting Legacy Symbolsand Labels

This chapter explains how to use the Graphics Definer to extract legacysymbols and labels created in other products (AutoCAD in particular) for usein the Aspen Basic Engineering Drawing Application and includes thefollowing:

Overview of extracting symbols and labels.

Extracting symbols from AutoCAD to the Graphics Definer.

Extracting labels from AutoCAD to the Graphics Definer.

Extracting legacy symbols and labels from other packages.

Working with extracted symbols and labels.

Overview of Extracting Symbolsand LabelsThe Graphics Definer has a conversion facility that lets you re-use legacysymbol and label data from imported drawings:

If the legacy data is from AutoCAD – Aspen Basic Engineering's drawingapplication prior to version 10.3 – much of the information isautomatically retained. This includes geometry, part definitions and somesymbol and label attributes, but not label data for routes, options and soon.

If the legacy data is from a simple drawing, the extraction processextracts geometry, but you continue the symbol or label definition in theGraphics Definer.

96 8 Extracting Legacy Symbols and Labels

Symbols: Extracting fromAutoCAD to the GraphicsDefinerExtracting symbols from AutoCAD to the Graphics Definer is a two-stageprocess:

Stage 1 – Preparation.

Stage 2 – Conversion.

Preparation and Background InformationIf your AutoCAD symbols have been defined using the Symbol Definer utility,the chances are that very little needs to be done to prepare a file forconversion. The following points are important:

Make sure that each symbol and its attribute data can be selected easily.

Check the text attributes in the CLASS layer. If necessary, you can changethem later, once the symbol is in the Graphics Definer.

Ensure that all leader lines for named parts have a text box at one end toname the part, and a single graphical object (primitive) at the other end,which is identified by the leader line.

Set the Foreign data options (accessed from the Graphics Definer Toolsmenu, then Options) to the correct scale for your symbol drawings.

Check or uncheck the ‘Extract all geometry as parts’ menu item in theGraphics definer menu. This determines whether or not all geometry, notjust named parts, can be connected.

What is and isn't Extracted?

Many of the attributes of your original symbols will be preserved through theconversion process, but some have no meaning in the Graphics Definer, andothers cannot easily be converted. Here is a summary:

Extent – The extent of the symbol has no meaning in the Graphics Definer,and it ignores any geometry in the EXTENT layer.

Datum – The Graphics Definer determines the datum point of the symbolusing a single point in the POINTS layer. More than one point in that layercauses an error. Other geometry in the POINTS layer is ignored. If no point ispresent in the POINTS layer, the conversion process issues a warning thencontinues, assuming the datum is the center of the symbol bounds.

Parts – The extraction process converts graphical elements of the symbolinto parts. There are two categories of parts:

Named parts, which are the authentic parts from the original AutoCADsymbol.

Anonymous parts, which are the remaining graphical elements.

Both types of part are now described:


Named Parts – Named parts are extracted with their name intact. For thisprocess to be automated, each leader line in the PART-NAMES layer musthave a single text box (also in the PART-NAMES layer at one end) and asingle primitive in the OBJECTS layer at the other. The primitive may also bein another layer, as long as that layer does not have special meaning asdescribed in this document (for example, CLASS, EXTENT, PART-NAMES,POINTS layers). The text in the text box is used as the name of the new partdefinition. All other geometry in the drawing, without a special meaning to theextractor, is defined as an anonymous part, so enabling it to be used forconnection.

Anonymous Parts – As well as importing named geometry as named parts,the remaining geometry can be identified as "anonymous" parts so that it canbe connected to. This promotes consistency between the current Aspen BasicEngineering and pre-Aspen Basic Engineering 10.3 versions using AutoCAD,for which all parts of an object could be connected. You can choose to havethe remaining geometry imported as anonymous parts by checking the‘Extract all geometry as parts’ menu item in the Graphics definer menu.

CLASS Layer – Text boxes in the class layer are read and have specialmeaning. The text boxes must be ordered from top to bottom, like they wereoriginally created in the Symbol Definer. The Graphics Definer refers to thisorder when determining which text boxes are used to set which attributes.

Attributes are set in the following order:

Order Attribute What Happens to the Attribute

1 Name Sets the name, type and description of the new symbol

2 Filename Sets the default file name for the new symbol (.sym isappended as a file extension)

3 Scale Ignored

4 Rotate Ignored

5 Reflect Ignored

6 Leader Ignored

7 Connect Determines whether or not the symbol can split aconnector when placed

The following example shows the class data extracted as attributes of a newsymbol:

SHELL-AND-TUBE-HEAT-EXCHANGER

Filename: exch-ht

Scale: no

Rotate: yes

Reflect no

Leader no

Connect yes


Connect Angles

When symbols are extracted from AutoCAD into the Graphics Definer, theirparts are given default connection angles of 0, 90, 180 and 270. Once thesymbol is in the Graphics Definer, you can change the connection angles fromthe default setting.

Newly created symbols in the Graphics Definer can have any connectionangle.

Newly created symbols in the Graphics Definer have no parts nominated, andyou need to nominate them yourself.

Converting Symbols from AutoCAD to theGraphics DefinerTo extract legacy symbols from AutoCAD to the Graphics Definer:

1 Load the dwg file containing your symbol definitions, into the GraphicsDefiner.

Note: The original layers, such as POINTS and OBJECTS, are preserved.

2 Select all of the graphical data that comprises an individual symbol.

Often a box selection works well for this, but if symbols are close togetheror even overlapping, you may need to select items individually.

Ensure that all the symbol graphics, the text boxes from the class layer,the part name leader lines and the text boxes and the datum point areselected.

Select Symbol: Symbol is Selected:


3 Click the Extract button.

At this stage, you are warned of any irregularities and omissions.

4 If the conversion proceeds smoothly, you are prompted for the directoryand filename for the newly-converted symbol.The filename is already set from the CLASS layer data (if present), butyou can change it if you want.

5 Check and add symbol attributes using the Graphics Definer; then dragthe symbol onto a diagram in the Aspen Basic Engineering DrawingApplication to check that it is correctly scaled and can be connected to.

6 Repeat this process for each new symbol.

Labels: Extracting fromAutoCAD to the GraphicsDefinerAs with symbols, extracting labels from AutoCAD to the Graphics Definer is atwo-stage process:

Stage 1 – Preparation.

Stage 2 – Extraction.

Preparation and Background InformationIf your AutoCAD labels have been defined using the Symbol Definer utility,the chances are that very little needs to be done to prepare a file forconversion. The following points are important:

Make sure that each label and its attribute data can be selected easily.

Set the Foreign data options (accessed from the Graphics Definer Toolsmenu, then Options) to the correct scale for your label drawings.

What is and isn't Extracted?

Many of the attributes of your original labels will be preserved through theconversion process, but some have no meaning in the Graphics Definer andothers cannot easily be converted. Here is a summary:

Extent – The extent of the label has no meaning in the Graphics Definer, andit ignores any geometry in the EXTENT layer.

Datum – The Graphics Definer determines the datum of the label using asingle point in the POINTS layer. More than one point in that layer causes anerror. Other geometry in the POINTS layer is ignored. If no point is present in


the POINTS layer, the conversion process issues a warning then continues,assuming the datum is the center of the label bounds.

CLASS Layer – Text boxes in the class layer are read and have specialmeaning. The text boxes must be ordered from top to bottom, like they wereoriginally created in the Symbol Definer. The Graphics Definer refers to thisorder when determining which text boxes are used to set which attributes.

Attributes are set in this order, as follows:

Order Attribute What Happens to the Attribute

1 Name Sets the name, type and description of the new label

2 Type Sets the Aspen Basic Engineering class of the label

3 Filename Sets the default file name for the new label (.sym isappended as a file extension)

4 Document Sets the associate-label-to-document property

5 Rotate Ignored

The example shows the class data extracted as attributes of a new label:

Stream Diamond

Type: IN-LINE

Filename: lab-sdia

Document: No

Rotate No

Field Information

Field information does not survive the extraction.

Extracted fields appear as plain text boxes in the Graphics Definer. These textboxes retain their original style, but all field definitions are lost.

To prepare for this, note the legacy field information so that you can recreateit once the label is in the Graphics Definer.

Tip: To recreate field information for this plain text in the Graphics Definer:select the text, click either the Convert Text to Field button or the ConvertText to Units Field button, then double-click the field and complete thedialog box that appears.For more information, see the Labels example.

Converting Labels from AutoCAD to theGraphics DefinerTo convert labels from AutoCAD to the Graphics Definer:

1 Load the dwg file containing your label definitions, into the GraphicsDefiner.

Note: The original layers, such as POINTS and OBJECTS, are preserved.

2 Select all of the graphical data that comprises an individual label.


Often a box selection works well for this, but if labels are close together oreven overlapping, you may need to select items individually.

Ensure that all the label graphics, the text boxes from the class layer, andthe datum point are selected.

Select Label: Label is Selected:

3 Click the Extract button.

At this stage, you are warned of any irregularities and omissions.

4 If the conversion proceeds smoothly, you are prompted for the directoryand filename for the newly-converted label.The filename is already set from the CLASS layer data (if present), butyou can change it if you want.

5 Check and add the label attributes using the Graphics Definer; then drag itonto a diagram in the Aspen Basic Engineering Drawing Application tocheck that it is correctly scaled.

6 Repeat this process for each new label.

7 If you have extracted fields, redefine each field using the proceduresbelow:

o Select the text.

o Click either the Convert Text to Field button or the Convert Text toUnits Field button.

o Double-click the field and complete the dialog box that appears.

o For more information, see the Labels example.


Extracting Legacy Symbols andLabels from Other PackagesYou can produce symbols and labels from non-AutoCAD packages, such asMicroStation and SmartSketch, as long as the drawing loads into the GraphicsDefiner.

You extract non-AutoCAD drawings in the same way as their AutoCADcounterparts, but during the procedure, you are usually prompted to clarifywhether the drawing is to be a symbol or label once in the Graphics Definer.

The reason for this prompt is that, unlike AutoCAD drawings, non-AutoCADdrawings typically have no text items in the class layer, and it is these textitems that tell the Graphics Definer whether it is dealing with a symbol or alabel.

Note: Aspen Basic Engineering 2006 and Aspen Basic Engineering iscompatible with SmartSketch version 4. To open SmartSketch version 5symbols in the Graphics Definer you must first, within SmartSketch, savethem as Smartsketch version 4 symbols.

Working with ExtractedSymbols and LabelsOnce the extracted symbols and labels are in the Graphics Definer, you canwork with them using any of the available tools. For example:

Extracted symbols – You may want to remove parts status from someelements or add or amend port definitions for others.

Extracted labels – Because field information is not extracted, your firstpriority may be to convert the (extracted) plain text back to a Value orUnits field.

9 Graphics Definer Menus and Toolbar Buttons 103

9 Graphics Definer Menusand Toolbar Buttons

This chapter describes the menus and toolbar buttons in the Graphics Definer.

MenusThe Graphics Definer has the following menus:

File menu.

Edit menu.

View menu.

Definer menu.

Insert menu.

Format menu.

Tools menu.

Window menu (not described).

Help menu (not described).

File MenuThe File menu contains the following commands, which apply to both symbolsand labels unless stated otherwise:


New Symbol Creates a new document (.sym file) for you to create anew symbol

New Label Creates a new document (.sym file) for you to create anew label

Open Opens an existing symbol or label document (.sym file)

Close Closes the active symbol or label document

Save Saves the active symbol or label document, with itspresent name and location(For a label, you must also compile before it is ready touse.)

104 9 Graphics Definer Menus and Toolbar Buttons


Save As Saves the active symbol or label document with aspecified name and location

Open Workspace Connects you to the server and opens a workspace in theGraphics Definer

Close Workspace Disconnects you from the server and closes theworkspace

Document Properties Displays the document properties, for you to view andedit

Sheet Setup Displays specifications of the document sheet, such asthe paper size, which you can edit

Print Prints the contents of the active window

Send Dispatches a document via email

Exit Ends your session with the Graphics Definer

Edit MenuThe Edit menu contains the following commands, which apply to both symbolsand labels:


Undo Undoes your last action in the Graphics Definer.

Redo Reverses the Undo command

Cut Removes the selection to the clipboard


Paste Places the contents of the clipboard at the cursor position

Paste Special Designed for pasting images. As for Paste, but you canspecify the format for the pasted image (for example, apicture or a bitmap)

Delete Deletes selected items in the active document, but notfrom the workspace

Select All Selects all the items in the active document

Properties Displays properties for the selected item within adocument, for you to view and edit

Links Displays any links to external files, such as a graphic in aseparate document. You can update the links

View MenuThe View menu contains the following commands, which apply to bothsymbols and labels:


Grid Display Shows or hides the snap grid (a rectangular array ofpoints on the document that may be visible or hidden)

Grid Snap Toggles the point snapping to the grid, between on andoff

Zoom Area Zooms in to a specified area of the document



Zoom In Magnifies the view of the document

Zoom Out Shrinks the view of the document

Previous Returns the view to its previous setting

Fit Adjusts the view so that the document fills the drawingwindow

Pan Changes the cursor to a navigation tool, which you useto scroll around the document

Toolbars Displays the list of toolbars. You can choose to show orhide each toolbar. Also use this command to customizetoolbars and menus

Definer MenuThe Definer menu contains the following commands:

Definer Menu Command Action

Set Datum Makes the datum mobile, for you to set at yourchosen location

Show/Hide Datum Toggles between showing and hiding the datum

Place Field (labels only) Places a Values field on the document, at the cursorposition

Place Units Field (labelsonly)

Places a Units field on the document, at the cursorposition

Place Plain Text Places a Plain Text field on the document, at thecursor position

Associate Fields (labelsonly)

Graphically associates one Units field with one ormore Value fields

Show Associations (labelsonly)

Displays any associations between Value and Unitsfields

Convert Text to Fields(labels only)

Converts any plain text boxes in the selection, to aValues field

Convert Text to UnitsFields (labels only)

Converts any plain text boxes in the selection, to aUnits field

Default Text Sets a default text style, which is adopted by all newfields thereafter

Part Definition (symbolsonly)

Enables you to create and edit nominated parts for asymbol

Extract Extracts both symbols and labels created in anexternal package (typically AutoCAD), for use in theGraphics Definer

Extract all geometry asparts

When this menu option is checked, all geometry isimported as either named or anonymous parts. If leftunchecked, only named parts are imported

Compile Label (labels only) Compiles the label (symbols are not compiled)


Insert MenuUse the Insert menu to import graphics and objects.

Format MenuUse the Format menu commands to:

Modify the appearance of the lines and text used to construct the symbolsand labels.

Modify the style of any dimensions added to your symbol drawing.(Dimensions are the lines and arrow heads typically seen on engineeringdrawings, to convey the length of lines and the size of angles.)

Tools MenuThe Tools menu contains the following commands, which apply to bothsymbols and labels:

Tools Menu Command Action

PinPoint Activates a toolbar that displays geometricalinformation, such as the (x,y) position of the cursor,and the length and angle of any lines you are drawing

Character Map Displays a list of special characters, which you select,then copy and paste onto the document

Layers,Layer Groups

For legacy AutoCAD drawings extracted into theGraphics Definer. Displays the layers and layer groupsin the drawing

Measure Distance Displays the straight-line distance between twoselected points on the document

Measure Area Click on or within a selected (enclosed) region todisplay the area (in the default sheet unit). You canalso group-select areas to display the total group area

Alignment Indicator,Maintain Relationshipsand Relationship Handles

Specialist settings to help you create complex shapes.These are best left at their defaults

SmartSketch Changes the cursor from a (passive) arrow to aresponsive tool that portrays information on thefeatures over which it is passing. For example, youcan configure a SmartSketch-enabled cursor toidentify the midpoint of a line as the cursor movesalong the line

Macro Enables you to select and then run a macro on theactive document

Add-Ins Incorporates extra groups of commands andfunctionality into the Graphics Definer. Similar toMicrosoft Excel addins

Customize Enables you to modify the Graphics Definer toolbarsand menus, and create new toolbars

Options Sets options for the document, such as the spacing ofthe snap grid


Toolbar ButtonsWhen you start the Graphics Definer, a default set of toolbars appear aboveand alongside the Drawing window:

Main toolbar.

View toolbar.

Graphics Definer toolbar.

Ribbon toolbar.

Draw toolbar.

In common with many Windows applications, you can modify which toolbarsdisplay and customize each toolbar (see Customizing Menus and Toolbars inChapter 2 of Using Diagrams).

Main ToolbarThe Main toolbar contains the following buttons:

ToolbarButton

Name Description

OpenWorkspace

Connects you to the server and opens a workspacein the Graphics Definer

New Symbol Creates a new document (.sym file) for you tocreate a new symbol

New Label Creates a new document (.sym file) for you tocreate a new label

OpenDocument

Opens an existing symbol or label document (.symfile)

Save Saves the active symbol or label document, with itspresent name and location. (For a label, you mustalso compile before it is ready to use.)

Print Prints the contents of the active window

Cut Removes the selection to the clipboard


Paste Places the contents of the clipboard at the cursorposition

Undo Undoes your last action in the Graphics Definer


Grid Snap Toggles the point snapping to the grid, between onand off

Grid Display Shows or hides the snap grid (a rectangular array ofpoints on the document that may be visible orhidden)


ToolbarButton

Name Description

PinPoint Activates a toolbar that displays geometricalinformation, such as the (x,y) position of the cursor,and the length and angle of any lines you aredrawing

Help Displays Online Help for Graphics Definer

View ToolbarThe View toolbar contains the following buttons:

ToolbarButton

Name Description

Zoom Area Zooms in to a specified area of the document

Zoom In Magnifies the view of the document

Zoom Out Shrinks the view of the document

Fit Adjusts the view so that the document fills the drawingwindow

Pan Changes the cursor to a navigation tool, which you use toscroll around the document

PreviousView

Returns the view to its previous setting

Graphics Definer ToolbarThe Graphics Definer toolbar contains the following buttons:

ToolbarButton

Name Description

DocumentProperties

Displays the document properties, for you to viewand edit

Set Datum Makes the datum mobile, for you to set at yourchosen location

Show/Hide Datum Toggles between showing and hiding the datum

Set Mass BalanceInsert Point

Makes the Mass Balance Insert Point mobile, foryou to set at your chosen location

Show/Hide MassBalance InsertPoint

The Show/Hide Mass Balance Insert Point button ormenu item results in the current Mass BalanceInsert Point location being displayed

Place Field Places a Values field on the document, at thecursor position


ToolbarButton

Name Description

Place Units Field Places a Units field on the document, at the cursorposition

Place Plain TextField

Places a Plain Text field on the document, at thecursor position

Associate Fields Graphically associates one Units field with one ormore Value fields

Show Fields/UnitsFields Associations

Displays any associations between Value and Unitsfields

Convert Text toFields

Converts any plain text boxes in the selection, to aValues field

Convert Text toUnits Fields

Converts any plain text boxes in the selection, to aUnits field

Default TextProperties

Sets a default text style, which is adopted by allnew fields thereafter

Part Definition Enables you to create and edit nominated parts fora symbol

Extract Symbol Extracts both symbols and labels created in anexternal package (typically AutoCAD), for use inthe Graphics Definer

Compile Label Compiles the label (symbols are not compiled)

Ribbon ToolbarThe Ribbon toolbar contains the following buttons:

ToolbarButton

Name Description

Inside Restricts a selection to items entirely within the boundaryof that selection. This is the default setting

Overlapping

Enables the selection to include all items overlapped by theboundary of that selection

Top Down Ensures that, on selecting a constituent line or arc from anitem, the whole item is selected. This is the default setting

For example, a column comprises two lines for the sides,and two arcs for the top and bottom. With Top Downpressed, if you select either a line or an arc, the wholecolumn is selected

Bottom Up The reverse of Top Down. Use this feature if you want toselect individual lines or arcs from items


Draw ToolbarThe Draw toolbar contains the following buttons, which you use for drawinglines and arcs.

For all the buttons, the procedure is:

1 On the Draw toolbar, click the appropriate button.

2 In the Drawing window perform your chosen action, such as drawing a lineor a tangent arc.

3 When you are happy with your creation, right-click to commit the changeson the drawing.

On completing a drawing task, it is good practice to revert to the (neutral)Select/Pointer tool. See the following table for a description of the buttons:

ToolbarButton

Name Description To Use…

Select Tool(Pointer)

Selects items This is a neutral tool, for selectionpurposes only

Line Draws a straightline

Click at the start and end of the line

Tangent Arc Draws a tangentarc to an existingline

Click an existing line at the pointwhere you want the arc to start. Thisis the tangent point. Move the pointerto create the arc

Line/ArcContinuous

Draws straightlines and arcsbetweensuccessive points

Click at successive points to form aseries of connected lines or arcs. (Totoggle between lines and arcs, clickthe Line button or Arc button on thenewly displayed toolbar that appearsdirectly above the drawing)

Circle byCenter Point

Draws a circleabout a fixedcenter

Click at the center point. A red circleappears that you can expand orcontract

Ellipse byCenter Point

Draws an ellipseabout a fixedaxis. (You definethe fixed axis byits center and oneof the end points)

Click at the center point. A lineappears which you can rotate andlengthen: this is the fixed axis foryour ellipse. Click to fix this axis. Ared ellipse appears, which youmanipulate through the second, freeaxis

Rectangle Draws a rectanglewith one sidefixed. (You definethe fixed side byits end points)

Click two points that will be the fixedside of the rectangle. A red rectangleappears, and you can widen or shrinkthe free dimension

Curve For drawing free-style curvesthrough asequence of fixedpoints

Click to display a red line, which youcan manipulate to form a curve.Successive clicks create fixed pointsthrough which the curve must pass

Free Sketch For free-styledrawing

With the mouse held down, move thecursor to create a free-style drawing


ToolbarButton

Name Description To Use…

Fillet Rounds off sharpvertices

Click the two lines that form thevertex. A red curve appears betweenthe lines, which you manipulate.When you are happy with theproposed rounding, click to delete theunwanted sharp vertex

Chamfer Replaces sharpvertices with achamfer

As for Fillet, above, but the processcreates a line rather than a curve

TrimElement

Trims lines fromone intersectionto the next

For lines or arcs that containintersections.

Click the portion of the line or arc youwant trimmed. The portion is deleted

Extend toNext

Extends lines tothe nextintersection

Click the portion of the line or arc thatyou want extending

The line or arc extends until it hits anintersection

Fill Fills enclosedshapes with colorand/or hatching

Click within an enclosed shape. Selecta fill color and style from the toolbarthat appears directly above theDrawing window

Parametric SymbolsParametric functionality within Aspen Basic Engineering allows you to designand utilize symbols that can be controlled by modifiable parameters. Thissection describes parametric symbols from the perspective of the designer. AllAspen Basic Engineering symbols can be modified by uniform transformationssuch as rotation, scaling and reflection. However, if you wish to change theheight of a column without at the same time changing its width, this must beachieved using parametric symbol functionality.

Parametric Symbol ToolbarsParametric Symbols are designed within the Graphics Definer.

Two toolbars provide this functionality. These are:

Dimension toolbar.

Relationship toolbar.


These toolbars can be added to the Graphics Definer by right clicking with themouse on the existing toolbars and selecting the required toolbar in the list oftoolbars displayed, or by using the View | Toolbars menu command.

A parametric symbol is a symbol which has dimensions and also relationshipsbetween the graphical elements of that symbol.

To enable a symbol to contain relationships, check the Tools | MaintainRelationships option. Once this menu item is checked, the system sets upintelligent choices for relationships while you are drawing your symbol. Thesechoices can be removed or added. To see evidence of relationships, click the“Relationship Handles” button. Relationships are displayed in the followingways:

Connect relationship. Thesquare denotes connectionbetween the two lines

Horizontal/Verticalrelationship. The plussymbol denotes the line isconstrained to vertical orhorizontal

Parallel relationship. Thedouble bar indicates that thetwo lines are to be keptparallel. (Note: Moving themouse over one of thedouble bars results in it andits partner beinghighlighted)

Perpendicular relationship.The right-angle symbolindicates that the two linesare to remain perpendicularto each other


Tangent relationship. Thesmall circle at the junctionof the large circle and theline, indicates that the lineshould remain tangential tothe circle

Colinear relationship. Thesmall, bold circles on eachline indicate that the linesshould be kept collinear.(Note: Moving the mouseover one of the circlesresults in it and its partnerbeing highlighted)

Concentric relationship.The two outer circles shownhere are to be keptconcentric as indicated bythe small, central double-circle symbol

Symmetric relationship.The two crosses on the arcsindicate that the arcs aresymmetrical about the line

Equal relationship. The bolddouble bars on the linesindicate that they are ofequal length. (Note: Not tobe confused with parallel)

Lock relationship. The endof the line indicated by thelollipop, is fixed in space

To remove a relationship, select it and press the delete key. To add arelationship, follow the instructions later in the document.


DimensionsDimensions are the key to parameterizing symbols.

Dimensions supply information about the size, location, and orientation ofelements, such as the length of a line, the distance between points, or theangle of a line. Dimensions are associative to the elements they refer to, soyou can make design changes easily.

There are two dimension types, driving and driven.

Driving DimensionsDriving dimensions are set up so that when the numerical value changes, sodoes the geometry they are attached to. When a driving dimension isselected, the Driving/Driven button is inset (depressed). To change thedimension to be driven, toggle the Driving/Driven button.

Driven DimensionsDriven dimensions do not control geometry, they simply report itsdimensions. When a driven dimension is selected, the Driving/Driven button isnot depressed. To change the dimension to be driving, toggle theDriving/Driven button.

Note: The Driven/Driving button is only visible when a dimension is selectedon the sheet.

You can also indicate the status of dimensions using their color scheme.Select the required dimensions and click the right mouse button to setdimension properties. A color scheme is available to indicate dimensionswhich are driving, driven or in error.

Note: A useful color scheme to use might be green for driving, yellow fordriven and red for error.


VariablesVariables can be used in a symbol definition as placeholders for any value youwish to represent. In addition, if a variable is subsequently used for setting adriving parameter and if its name corresponds to the Aspen Basic Engineeringconvention, it will ultimately be used to control the symbol when it is placedon an Aspen Basic Engineering sheet.

A Variable Table is used to define and edit functional relationships betweenthe dimensions of a design in a familiar spreadsheet format. The VariableTable is accessed using the Variables command on the Tools menu.

There are two types of variables:

Dimensions displayed in the design.

Variables you create directly in the Variable Table.

Dimension variables directly control elements of a design. A user variablemust be set equal to a value or mathematical expression; for example, PI= 3.14159.

The variable table is similar to a spreadsheet. You can type into an empty rowto create a new variable, giving its name, its type and its value (or formula).If you want to control the symbol in Aspen Basic Engineering using graphicalhandles, you must create a variable that corresponds to the handle you wantto utilize.

The name of the variable should be one of:

Top, Bottom, Left or Right,


corresponding to the relative location of the GUI Handle on the placed symbol(refer to the Glossary in the on-line Help for a definition of handles). Notethat the capitalization of the first letter and the spelling must be exact.

The formula column of the variable table can contain any valid formula andyou can use variables within these formulae. This means that you can set adriving dimension using formulae containing variables.

Drawing With RelationshipsAs mentioned earlier, when the Tools | Maintain Relationships menuoption is checked, any drawing automatically contains relationships as shownin the following figure. The two shapes were drawn and the relationships wereadded automatically:

How these relationships are automatically created can be controlled by theTools | Smartsketch… menu. Check the relationships you want to haveadded.


Relationship Commands

Using Feedback from the Pointer as YouDrawAs you move the pointer, the software automatically updates values in theribbon bar, giving you constant feedback on the size and position of theelement you are drawing. As you draw, the software shows a temporary,dynamic display of the element you are drawing by the pointer – thisfeedback is called a relationship indicator. This temporary display shows thelook of the elements if you place the element at the current location.

The software gives you more information about the element that you aredrawing by displaying relationships between the temporary, dynamic elementand the following items:

Other elements in the drawing comprise:

Horizontal and vertical orientations.

Origin of the element that you are drawing.

When the software recognizes a relationship, it displays a relationshipindicator at the pointer. As you move the pointer, the software updates theindicator to show new relationships. If a relationship indicator appears by thepointer when you click to draw the element, the software applies thatrelationship to the element.

For example, if the horizontal relationship indicator appears when you click toplace the second end point of a line, then the line is exactly horizontal.

RelationshipsYou can set the types of relationships you want the software to recognize withthe Settings command on the Tools menu. The software can recognize one ortwo relationships at a time. When the software recognizes two relationships,it displays both relationship indicators at the cursor.

Locate ZoneYou do not have to move the pointer to an exact position for the software torecognize a relationship. The software recognizes relationships for anyelement within the locate zone of the pointer. The circle around the pointercrosshair or at the end of the pointer arrow indicates the locate zone. You canchange the size of the locate zone with the Settings command on the Toolsmenu.


Infinite ElementsThe software recognizes the Point On Element relationship for lines and arcsas if these elements were infinite. In the following example, the softwarerecognizes a Point On Element relationship when you position the pointerdirectly over an element and also when you move the pointer off the element.

To delete a relationship, select it and press the delete key. Often, boxselection is the best way to select.

To add a relationship, press one of the relationship buttons on the relationshiptoolbar and select the objects to be related as described:

Connect relationship. The first object selected will snapto the second object

Horizontal/Vertical relationship. The line selected willsnap to the nearest axis, horizontal or vertical. Note thatthe line must already be nearly horizontal or vertical

Parallel relationship. The first line selected will move tobe parallel with the second line selected

Perpendicular relationship. The first line selected willmove to be perpendicular to the second

Tangent relationship. The first object selected will moveto be tangential to the second

Colinear relationship. The first line selected moves tobecome collinear with the second

Concentric relationship. The first circle or arc selectedwill move to have its center point coincident with thesecond circle or arc


Symmetric relationship. First a line must be selectedwhich represents a mirror. The next object selectedmoves to be symmetrical (by reflection) with the third

Equal relationship. The first of two objects selected willmove to be equal (usually in length or radius) to thesecond

Lock relationship. Placing a lock on an object, fixes it inspace. If the lock is placed on the endpoint of an object,only that endpoint is fixed in space

Variables. Clicking this button will toggle the visibilityof the variables dialog

Adding and Deleting Dimensions

SmartDimension. Places a dimension for:

Length and angle of a line.

Radius and diameter of a circle.

Length, angle, radius, and diameter of an arc.

Radius of an ellipse or curve.

Distance Between. A linear dimension measures thelength of a line or the distance between two points orelements. You can place linear dimensions with theDistance Between and SmartDimensioncommands

Angle Between. An angular dimension measures theangle of a line, the sweep angle of an arc, or theangle between two or more lines or points. You canplace angular dimensions with the Angle Betweenand SmartDimension commands

Axis. A dimension axis allows you to placedimensions that are perpendicular to or parallel to anelement. After you set a dimension axis with the Axiscommand, you can place a dimension that runsparallel or perpendicular to the dimension axis. Touse the axis, you must set the type of dimension axisthat you want to use on the dimension ribbon bar.You do this by clicking the Distance Between orCoordinate Dimension buttons on the DimensionToolbar. Then, you click Explicit in the Dimension Axis


box on the ribbon bar

Measure Distance. You can measure the length of aline or the diameter of a circle by selecting theelement and looking at the value on the ribbon bar.For more detailed work, the software providescommands for measuring distances or areas in adrawing. The Measure Distance command measuresthe distance between points on elements and pointsin free space. The distances are shown using thecurrent units of measure for the document.

Note: This is a tool for measuring distance whenworking with the drawing. The visual feedback is notsaved with the sheet.

Measure Area. The Measure Area commandmeasures the area inside one or more closedboundaries. To set the units for measuring distancesor areas, you can use the Properties command on theFile menu.

Note: This is a tool for measuring area when workingwith the drawing. The visual feedback is not savedwith the sheet.

Coordinate Dimension. Places a dimension thatmeasures the distance from a common origin to oneor more key points or elements. The coordinatedimensions that refer to the common origin aremembers of a coordinate dimension group.

You can place coordinate dimensions in any order andon either side of the origin with respect to thedimension axis. You can also add additionalcoordinate dimensions to existing coordinatedimension groups.

Symmetric Diameter. Places a dimension thatmeasures the distance between a center line andanother element or key point, multiplies the distanceby two, and displays the value as a diameter.


Linking Variables to AspenBasic Engineering GUI HandlesWhen the parameterized symbol is used in Aspen Basic Engineering, it can bemanipulated using a graphical user interface. If any variables are definedcorresponding to “Top”, “Bottom”, “Left” or “Right”, then these will berepresented in the GUI by a diamond shaped “handle” at the top, bottom, leftor right of the symbol respectively.

Clicking on this handle and dragging the mouse results in the value of thevariable changing and therefore any geometrical dependencies within thesymbol that are based on the variable, will change too.

ExampleThe following example shows the design of a parametric symbol, in this casea column, which can change its height or width independently.

Create a new symbol:

1 Place the datum in the center of the sheet. We will also use this as a fixedpoint for the parametric operations.

2 Draw two lines horizontally to each side of the datum (switching on thegrid may help).


3 Use the lock relationship to lock one end of one of the lines at the datum(the other line is implicitly locked by the connect relationship, note thehollow square indicator).

4 Use the equal relationship to constrain the lines to be of equal length. Ifthe lines are not already constrained to be horizontal, use the HorizontalVertical relationship.

5 Now draw two vertical lines near each free end of the horizontals. Theseform the sides of the column. Constrain the lines to be vertical.

6 Connect the center point of each line to the end point of the horizontal,being careful to select the vertical line before the horizontal.

7 Use the horizontal relationship to constrain the end points of the verticallines to be horizontal to one another. (Select the button, then the endpoint of each line, a dotted line will be drawn to show the relationship).Only one set of ends need be constrained since the verticals will expandand contract about their center points.


8 You should find that you can now move one end point of one of thevertical lines and this will drive all the other endpoints keeping the objectsymmetrical about the datum.

9 Now add parameters to drive the end point that drives all the others. Usethe Distance Between parameter.

10 Create an arc by center and end points, being careful to place the centerpoint in line with the datum and the end points connecting (automatically)to the ends of the vertical lines.

11 Repeat for the arc forming the base of the column. Constrain the centerpoints of the arcs to be in line with the datum.


12 Use SmartDimension to add a dimension to the radius of the (driving) arc.

13 Open the variable table (by pressing the variables button).

Open the variable table (by pressing the variables button). Define newvariables “Top” and “Right”. In the formula field of the width-waysparameter type “Right” and in the formula field of the height controllingparameter, type “Top”. These parameters are now driven by the value ofthe variable. You may also set the radius dimension based on anothervariable or parameter. In the example it is set to 1 x V352.


14 Make the arcs equal using the equal relationship.

14 Save the symbol after setting its properties for use in Aspen BasicEngineering.

15 You may want to hide the construction lines (the original horizontals) andthe dimensions in an invisible layer. You may also shade the resultingsymbol if you wish.

To create an invisible layer:

a) Select the menu item Tools | Layers…

b) In the ribbon bar, simply type the name of the new layer to create it.When you draw an element, it is assigned to the active layer.

c) To see which layer is active, or to change the active layer, you can use theLayers button on the Main toolbar.

d) To view elements on specific layers, you can turn on one or more layerswith the Layers button.


Note: Because the icon representing the symbol is generated automaticallyfrom all of its drawing elements, large parameters placed outside thegeometry of the symbol, will cause the resulting icon to appear smaller. Toavoid this, reduce construction lines and parameters and place them withinthe bounds of the symbol geometry.

16 When the symbol is place on a drawing, it appears with a diamond shapedhandle at the top and one at the right, corresponding to the variables youdefined. These diamonds may be dragged with the mouse to change theparameters of the symbol.

10 Class Library Editor 127

10 Class Library Editor

The Class Library Editor is a client application, which allows authorized usersto create and edit Class Libraries and compile them into a Class Store(previously a Prototype Store).

A Class Library comprises a named collection of related class and associationdefinitions (organized according to an XML Schema). Typically, the set ofdefinitions contained in each class library will be related by a commonpurpose, e.g. a class library may contain classes for mechanical parts forrotating equipment, or classes of heat transfer equipment.

Aspen Basic Engineering supports multiple class libraries and a class librarymay reference other class libraries (Referenced Libraries) to allowrelationships between classes in different class libraries.

In addition to user-defined Class Libraries, a number of other Class librariesare provided with Aspen Basic Engineering, these include a System Library (aprotected, non-editable library containing classes required by the Aspen BasicEngineering system to function) and a range of engineering libraries.

128 10 Class Library Editor

Class Library RepositoryLibrary files are contained in the directory ClassLibraries. Each Library file hasan .azcl file extension (a AZCL file) and is an XML document containing allproperties of the following entities for a single class library:

Associations.

Class Views.

Classes.

Composite Views.

Enumerations.

Included Libraries.

Each entity has a namespace, i.e., no two classes can have the same name.The Name property of an entity is its identifier.

On loading a library the system performs the following consistency checksfor:

Namespace violations.

Missing dependencies.

Class StoreThe Class Store is a ‘compiled’ version of the Class Library used by the AspenBasic Engineering server. It contains a ‘flattened’ representation of theclasses in the Library and its referenced libraries, with all dependencieschecked and properly mapped.

Class Library Editor WindowThe Class Library Editor window contains the following elements:

Menu bar.

Toolbar (with tooltips).

Status Bar – Displays summary details of the Class and Library.

Navigation Pane (left pane) – Displays top level constructs in the libraryvia eight tabs.

Content Pane (right pane) – Displays the content of constructs displayedin the Navigation pane (e.g., Attributes of Classes).


Class Library Editor MenusThe Class Library Editor has the following menus:

File menu.

Edit menu.

View menu.

Insert menu.

Tools menu.

Window menu (not described).

Help menu (not described).

File MenuThe File menu contains the following commands:

File MenuCommand

Action

New Creates a new, blank class library. If an existing class library isloaded with unsaved changes, you are prompted to save thechanges

Open Open an existing class library. The default directory is the ClassLibrary Repository. If an existing class library is loaded withunsaved changes, you are prompted to save the changes

Close Close the current class library, (all open contents pane windows).If the existing class library is loaded with unsaved changes, youare prompted to save the changes

Save Save the class library to its class library (.azcl) file. If the libraryhas never been saved, the Save As dialog is displayed promptingyou to name the file

Save As Enter the name for a new file and choose a directory to save it in.The default directory is Class Library Repository

LibraryProperties

Opens the New Library Properties dialog

Recent File Displays the most recently loaded libraries(s). Choosing one ofthese files opens that library

Exit Close/Shutdown the Class Library Editor. If an existing classlibrary is loaded with unsaved changes, you are prompted to savethe changes


Edit MenuThe Edit menu contains the following commands:


Undo Reverses your last action in the Class Library Editor


Cut Removes the selection and copies it to the clipboard


Paste Places the last item copied to the clipboard at the cursorposition

Delete Deletes selected item (Class, Attribute or Association)

Find Brings up the Find dialog

Stop Sorting Returns a view back to the original order

Properties Opens the selected item’s Properties dialog

View MenuThe View menu contains the following commands used to show/hide theassociated item:


Toolbars Displays/hides the Class Library Editor toolbars

Status Bar Displays/hides the Class Library Editor status bar

Navigation View Displays/hides the Navigation View pane

Output Displays/hides the Output window

Insert MenuThe Insert menu contains the following commands:

View MenuCommand

Action

Class Opens the Class Properties dialog and allows you to insert a newclass

Association Opens the Association Properties dialog and allows you to insert anew Association

Enumeration Opens the Enumeration Properties dialog and allows you to inserta new Enumeration

CompositeView

Opens the Composite View Properties dialog and allows you toinsert a new composite class

Class View Opens the Class View Properties dialog and allows you to insert anew class view


Tools MenuThe Tools menu contains the following commands:

Tools MenuCommand

Action

Make Class Store Allows you to compile a current library to create a Class Store

Check Library Checks the Library for errors and puts the result in the Reporttab of the output bar

Check theselectedConstruct

Check the currently selected item in the navigation view forerrors and puts the results in the Report tab of the output bar

Show Usage Finds where the currently selected item in the navigation viewis used and puts the result in the Report tab of the output bar

Preferences Opens a dialog allowing you to set the Class Library Editor’spreferences

UOM Definitions Allows you to navigate to and open an XML (default format)unit of measurement (UOM) definitions file

Class Library Editor ToolbarsWhen you start the Class Library Editor, the default toolbars appear below themenu. All toolbar icons have tooltips for quick reference. In addition todisplaying standard buttons, you can customize this toolbar to display ClassLibrary Editor specific buttons (also see Customizing Menus and Toolbars inUsing Diagrams).

The Class Library Editor toolbar contains the following default buttons withintwo default toolbars. (Icons displayed may vary according to customization):

Toolbar Button Name Description

1 New Creates a new Class Library

2 Open Document Opens an existing Class Library

3 Save Saves the active Class Library

4 Cut Cuts the selection to the clipboard

5 Copy Copies the selection to the clipboard

6 Paste Pastes the contents of the clipboard at thecursor position

7 Delete Deletes the selected construct from the library

8 Undo Reverses your last action in the Class LibraryEditor

9 Redo Reverses the last Undo command


10 Properties Displays a dialog box containing the propertiesof the selected Construct or Attribute

11 Find Allows you to search for a Construct in t thelibrary and puts the result in the Find tab ofthe output bar

12 Show Usage Shows the usage of the selected construct

13 Check Constructfor Errors

Checks the selected construct for error

14 Check Libraryfor Errors

Check the whole library for errors

15 Make ClassStore

Compiles the library into a Class Store

16 Help Displays on-line help for the Class LibraryEditor

17 Open Open an alternative view depending on thecurrently selected item

18 Show SystemOrder

Stops any sorting and reorders the view in theoriginal system order

19 Insert Attribute Inserts an attribute in the selected position

20 Move Up Moves selected item up

21 Move Down Moves selected item down

22 Expand All Expands all the items one level

23 Collapse All Collapses all items

Navigation Pane Context-MenuA context-menu is displayed when you click the right mouse button while thecursor is in the left pane. Context-menu options are also available within themain menu bar (and toolbar where relevant).

The menu displayed shows the following options (black titles active; graytitles currently inactive):

Open.

Insert.

o Class.

o Association.

o Enumeration.

o Composite View.

o Class View.

o SubClass.

o Seed New Composite View.

Rename.

Delete.

Check for Errors.

Show Usage.

Find Attribute.

Properties.


Class Library Editor Status BarThe status bar displayed at the bottom of the main window provides itemsummary details in three fields:

Class.

Superclass.

Library.

Navigation PaneThis pane is displayed on the left side of the window and contains thefollowing tabs:

Library tab – Displays all library elements hierarchically.

Classes tab – A summary of classes in the current library.

Associations tab – A summary of associations in the current library.

Enumerations – A summary of enumerations in the current library.

Class Views – A summary of class views in the current library.

Composite Views – A summary of composite views in the current library.

Quantity Types – Displays all the Units Of Measure hierarchically.

Libraries – A summary of libraries in the current library.

Inheritance tab – Displays classes by inheritance.

Compare Library – Show the differences between two libraries.

Library TabThe Library tab displays all elements in the library hierarchically. The root ofthis view is the current library. All library elements are visualized, organizedby containment (i.e., Enumerations of LibraryX are displayed under LibraryX/Enumerations). Classes and Associations are further organized by category.Entities with no category are placed under the Classes/Associations node.


Construct TabsThe following tabs, Classes, Associations, Enumerations, Class Views andComposite Views display a list of all constructs of that type and display detailsof each construct. The lists can be sorted by any column and the appropriatecontent view or properties can be displayed by double clicking on an item orusing the right mouse button context menu, which has the same choices as inthe Library tab for each construct.

Inheritance TabThe Inheritance tab displays a graphical view and represents multiple baseclasses. It shows all current classes and all referenced libraries organized byinheritance. This view can only be modified via the Edit Class Propertiesdialog.

Quantity Types TabThe quantity types tab displays all the known quantity types and theirassociated units. Quantity types can be edited and modified and will be savedwhen the library is saved.


Compare Library Tab

Content Pane

The contents of Classes, Class Views, Composite Views and Enumerations canbe shown in a contents pane.

The content view for Classes is shown in the Content (right) pane. In thiswindow, attributes are displayed in columns (scroll horizontally to viewcolumns) and all columns can be sorted. Attributes can be displayed invarious colors, depending on state and context. Attributes defined in baseclasses are de-emphasized.

The content view is hierarchical, by aggregation, i.e., the view contains ahierarchical representation of aggregation, with aggregated attributesemphasized in large bold text. The ‘type’ column displays the base type(Integer, String, etc.) or Class name of the attribute, if the attribute is anaggregated class instance. If this is the case, the attribute name isemboldened and the attributes contained within it are displayed beneath itand indented.

Associations (references to other objects) are also shown in this view.

Enumerations list their options.

Managing Class Libraries andClass StoresA Class Store is a compiled Class Library used by the Aspen Basic Engineeringserver to define the objects and attributes in the Aspen Basic Engineeringdatabase.

A Class Library consists of:

A single root Library file with the extension AZCL.

Any number of included library files with the extension AZCI.

Any number of included Class Store files with the extension AZCS.

Extensions to class stores. (Normally stored in the root library)

The root library and the included libraries contain definitions of Classes,Composite Views, Class Views, Associations and Enumerations. The differenceis that only the root library can include other libraries and Class Stores, andonly the root library can be compiled into a Class Store. As such the rootlibrary with its included libraries must be “complete”; all reference from oneclass to another must be contained within the root library and it’s includedfiles.

Class Stores are compiled class libraries. Aspen Basic Engineering deliversprecompiled libraries. The System class store is always delivered. Class storescannot be modified but can be included in a new Class Library and constructsin a class store can be extended.


Though class stores cannot be edited or changed you can extend a class storein your class library by adding to a construct e.g. adding an attribute to aclass, or by modifying certain properties such as an attribute’s description butnot the name or any other property that the Aspen Basic Engineering serverdepends on. The extensions/modifications are stored in the new class library.

Library Operations

Creating a New Class Library

This procedure creates a new Class Library displayed in the Navigation paneLibrary tab and assumes the Class Library Editor is already open:

1 Select File | New.

2 If a current library is open, a Save prompt is displayed. Click Yes to saveany changes and save the current library to file.

3 A new (empty) Class Library is created and displayed in the Library tab.This becomes the current library.

Opening an Existing Class Library

This procedure opens an existing Class Library for editing.

Note: Class Libraries can only be edited using the Class Library Editor, notfrom within a Workspace.

1 Launch the Class Library Editor application.

2 Select File | Open.

3 If a current library is open, a Save prompt is displayed. Click Yes to saveany changes and save the current library to file.

4 The Open dialog is displayed allowing you to open a file (the default filedisplay format is .azcl) or navigate to the directory containing the required.azcl library file(s).

5 Select the required Library filename to open it in the Library tab.

Editing Library Properties

This procedure allows you to edit the properties of a Class Library andassumes the Class Library Editor is already open:

1 Select File | Library Properties to open the Edit Library Propertiesdialog.

2 Data in the Name, Description, Author, and Organization fields can beedited by an authorized user.

3 When complete, click OK to save changes and close the dialog, or Cancelto discard changes and close the dialog.

4 If the library name has been modified, this is displayed in the Library tab.


Refer to the following table for Library property descriptions:

Library Property Property Description

Name A short name for the library

Description A general description of the contents and purpose of this library

Author The name of the author of this library

Organization The name of the company or other organization originating thislibrary

Adding Revision Control to a Library

A revision can be set for a library. Only the current revision can be modified.The current revision can be closed at which point no further changes will beallowed to the library until either the revision is reopened or a new revision iscreated. To create, modify, reopen or close a revision:

With the Class Library Editor already open:

1 Select the current library or an included library in the Library View.

2 Select the Properties command to open the Library Properties dialog.

3 Select the Revision tab.

Adding an Include Library

This procedure adds an include library to the current library, allowing you toload the modeling constructs in the included library into the Class LibraryEditor.

Modeling constructs in the included library can be edited and references canbe created from modeling constructs in the current library to modelingconstructs in the include library.


1 Select the current library or an included library in the Library View.

2 Select the Properties command to open the Library Properties dialog.

3 Select the Add Existing Referenced library icon; a File Open dialog isdisplayed.

4 Locate a directory on the user or a networked computer (the systemdisplays the files in that directory with a .azci extension.

5 Select one of the files listed (the system displays the description propertyof the selected file).

6 Confirm the selection of the class library (the system adds the selectedclass library to the list of included libraries).

7 Confirm the changes to the library properties (the system loads thecontents of the include library if it is not already loaded).

8 The library is added as a library node in the Library View.


Removing an Include Library

This procedure allows you to remove an include library from the currentlibrary or an include library.

With the Class Library Editor and a library already open:

1 Select a library from the Library View.

2 Select the Properties command (the system displays the Edit Propertiesdialog for the selected library).

3 Select the name of an include library from the list of included libraries.

4 Select the Remove icon.A warning is displayed advising that removing the include library mayinvalidate modeling constructs in the current library that depend on theinclude library. The include library is deleted from the list of includedlibraries.

5 Click Yes on the dialog box to confirm the changes to the libraryproperties.

Note: If the library is not included by any other library currently loaded,the system unloads the contents of the library and removes the includedlibrary from the library view. Any changes made to the include librarysince it was loaded are saved.

Cutting and Pasting Library Content

This procedure allows you cut and paste a construct between include libraries.

With the Class Library Editor and a library that includes one or more otherlibraries already open:

1 Select a construct shown in the Library View. The selected construct maybe in more than one source library.

2 Select Cut. (The selected construct in the Library View is displayed in adifferent rendering to show that removal is pending.)

3 Select a target library in the Library View and select Paste. The selectedconstructs are placed in the target library and the constructs are removedfrom the source libraries.

Note: If you attempt to paste the selected constructs into a library thatalready contains one of the selected constructs, an error is reported andnone of the constructs are pasted.


Dragging and Dropping Library Content

This procedure allows you to drag and drop a construct between includelibraries.

With the Class Library Editor, and a library that includes one or more otherlibraries, already open:

1 Select a construct shown in the Library View.

2 Drag the selected construct while holding down the left mouse button.(Visual feedback that the selected objects are being dragged is indicated.)

3 Release the left mouse button over the target library. The selectedconstruct is placed in the target library and the construct is removed fromthe source libraries.

Note: If you attempt to drop the selected construct into a library thatcontains one of the selected constructs, an error is reported and none ofthe constructs are dropped.

Viewing and Selecting Library Contents

This procedure allows you to view the content of the current class library andany included libraries.


1 Select View | Navigation view from the menu. A multi-page navigationwindow is displayed with a tab for each page.

2 Select the Library tab.

The library contents are displayed as a tree view.

The root node of the tree is the current library.

Nodes below the library node represent the data model construct by type.The last node contains the included libraries.

Nodes immediately below the data model construct type nodes are thedata model construct instances.

3 Click on the + symbol to expand the nodes in the tree view and findconstructs of interest.

Saving a Class Library

This procedure allows you to save changes to the current library and assumesthe Class Library Editor is already open:

1 Select File | Save to save any changes to the library and keep thecurrent library open. If this is the first save, the Save As… dialog promptsyou to save as a filename.

2 If changes have previously been made and saved, no dialog is displayedand the file is saved with the existing name to the existing location.


Searching a Library

This procedure helps you ensure you do not duplicate modeling constructs,thus creating redundancy in the Class Libraries. You may search class librariesfor matches against a plain text string or matches against a regularexpression. The scope search can be configured to look selectively formatches in one or more kinds of modeling construct and modeling constructproperties.


1 Select Find from the toolbar or Edit menu and enter a text string.

2 Select the property to compare the string with, and modeling constructsthe search should consider.

3 Specify whether or not the search should look for the exact stringspecified or any result containing the string.

4 Selects whether or not the search uses regular expression patternmatching.

5 Confirm the search criteria.

6 The system presents a report showing all the instances where a matchwith the search string was found, in the Find tab of the output bar.

Checking a Library for Errors

This procedure causes the system to check all constructs in the library forsemantic errors (such as invalid references or missing required properties).


1 Select Tools | Check Library. This generates a report in the Report tabof the output bar listing all messages generated by the check. Messagesare classified into one of the following categories: Warning, Error, SevereError.

2 Click on the column headings to sort by any heading.

Hint: Warnings can be switched off in the Tools | Preference dialog.

Creating a Class Store

This procedure creates a Class Store file containing all the data modelconstructs from the current library and any included libraries.


1 Select Tools | Make Class Store. (The system checks whether anychanges have been made to the library contents since the library wasopened or last saved.) The Save As dialog is displayed.

2 Enter a file name and file location for the Class Store file (the systemwrites the Class Store file).

3 You can now load the Class Store into the Aspen Basic Engineering serverwithout generating errors and use the data model constructs in aWorkspace.

4 If errors are generated, an error report is displayed and the Class Storefile is not created.


Class Operations

Creating a New Class

This procedure shows you how to use a graphical interface to create newclasses and define their properties.

With the Class Library Editor already open and a class library created oropened:

1 Select Insert | Class to open the New Class Properties dialog.

2 Enter class properties in the Name, Display Name, Description, Categoryand Known Category fields.

Class Property Description

Class name The name that identifies the class within the class librariesand by the system

Display name The name by which the class is identified by an end user

Description A text description of the class (may include a URL)

Category The category of the class

Known name The name of the attribute of this class used to identify aninstance of this class

Superclasses An ordered list of the classes with which this class has ageneralization/specialization relationship and from which thisclass inherits its attributes. (Note: Only immediatesuperclasses are shown.)

3 Click OK to create a new class and close the dialog.

Editing Class Properties

This procedure shows you how to edit the properties of a class. You mayperform edit operations in any order and accept or reject edits.

With the Class Library Editor already open in Library View:

1 Select a class in the Library View.

2 Select File | Properties to open the Edit Class Properties dialog.

3 Edit the class properties (as shown in the table).

4 Click OK to create save class edits and close the dialog.

Showing Class Usage

This procedure allows you to obtain a report showing where a class is used inthe current library or the reference libraries.

With the Class Library Editor already open and a class selected in the libraryview.

Select Tools | Show Usage to display the Report dialog showing theconstructs in the current library where the classes are referenced.


Checking a Class

This procedure allows you request the system to check a class for semanticerrors such as invalid references or missing required properties.


1 Select a class in the Library View.

2 Select Tools | Check Selected Construct.

3 The system performs checks on the properties of the class and theproperties of the class attributes for errors.

4 The system shows a report on the display listing all messages generatedby the check. The user selects a class in the Library View.

Inheritance View Operations

Showing the Class Inheritance View

This procedure allows you to display the inheritance relationships between allthe classes in the current library and any included libraries graphically.

With the Class Library Editor already open and a class selected in the Libraryview.

1 Select the Inheritance tab in the Navigation View.A graphical view of the classes in the current library and any includedlibraries is displayed.

2 The view consists of a graph of nodes and arrows:

o Nodes represent classes and are shown as rectangular boxescontaining the class name.

o Arrows represent inheritance relationships. They are not labelled.

o The root GenericClass is shown on the extreme left.

o Nodes are laid out so that they do not overlap.

o Arrows are laid out left to right except where multiple arrows enter orleave a node, in which case the arrow vector may have a verticalcomponent.

o All inheritance relationships have the superclass on the left of the arcand the subclass at the right-hand end of the arc. Nodes are laid out toachieve this objective.

3 A context menu allows you to select a class node and Class Operationsthat require a class as a context.


Expand Inheritance View Depth

This procedure allows you to request the system to expand the Inheritanceview to a specified depth.

With the Class Library Editor already open and the Inheritance view as thecurrent view.

1 Right-click the mouse button (a context menu is displayed).

2 Select the Expand to n levels…” command (a dialog for entering thedepth of the expansion is displayed).

3 Enters a positive integer value (the system redisplays the Inheritance treeexpanded to the depth specified).

Refocus Start of Inheritance View

This procedure allows you to request the system to start the Inheritance viewtree at a particular class.

With the Class Library Editor already open and the Inheritance view as thecurrent view:

1 Select a Class node in the Inheritance view.


3 Select the Refocus command (the system re-displays the Inheritance treewith the selected class at the root).

Refocus Start of Inheritance View on Root Class

This procedure allows you to request the system to start the Inheritance viewtree at the root class.



2 Select the Refocus on Root Class command (the system redisplays theInheritance tree with the root class at the start of the class Inheritancetree).

Expand Node in Inheritance View

This procedure allows you to expand the Inheritance view to show thesubclasses of a selected class.


1 Select a class node in the Inheritance view.


3 Select the Expand command (the system re-displays the Inheritance treewith all the subclasses of the selected class shown).


Collapse a Node in Inheritance View

This procedure allows you to collapse the Inheritance tree view below aselected node.


1 Select a class node in the Inheritance view.


3 Select the Collapse command (the system redisplays the Inheritance treewith all the subclasses of the selected class shown).

Printing the Inheritance View

This procedure allows you to print the currently displayed Inheritance view.



2 Select the Print command (the system prints the class Inheritance tree ascurrently expanded in the Inheritance view).

Class Attribute Operations

Opening the Class Attribute View

This procedure allows you to display and edit the class attributes.

With the Class Library Editor already open and a class selected in the libraryview.

Select Open from the right mouse button context menu or double clickthe class to display the Attribute view of… window which contains a list ofall attributes in the class and all the attributes inherited from superclassesof the class.

Expanding Object Attributes

This procedure allows you to expand an attribute of type object to show theattributes of the object’s class.

With the Class Library Editor already open and the Class Attribute view as thecurrent view.

1 Click on the + next to an attribute that has a type of Object. The systemexpands the attribute in the attribute view to show attributes of theobject’s class.

2 You can expand all nodes one level or collapse all nodes using the + and –on the attribute tool bar.


Creating and Editing An Attribute

This procedure allows you to create a new attribute in a class.

With the Class Library Editor already open and the Attribute View of… windowopen:

1 Select an attribute or the end of the attribute list as an insertion point.

2 Right-click the mouse and select Insert attribute.

3 A new attribute is inserted in the attribute list at the insertion point.

4 Edit the attribute properties, clicking in each field to enter edit mode.

5 Refer to the following table for attribute details.

Note: You cannot insert into or edit an attribute belonging to another class.

ClassAttributeProperty

Description Possible values and constraints

Name The name of the attribute thesystem uses to internallyidentify the attribute withinthe class

(default = none)

DisplayName

The name of the attribute thesystem uses to identify theattribute to an end user

(default = none)

Description

A description of the attribute A text description. May include a URL

(default = none)

Type The data type of the attribute One of the following:

String

Integer

Real

Boolean

Date

Binary

Enumeration…

Object…

If Enumeration… is specified, thename of an existing enumeration typein the current or an included librarymust also be specified

If Object… is specified, the name of anexisting class in the current or anincluded library must also be specified.This specifies that the attribute willcontain instances of an object of thespecified class. An implicit containmentassociation is created between theparent object and the sub-object

Category A string that assigns acategory to the attribute forsorting, searching andfiltering purposes

(default = none)

Multiplicit The number of values that 1 (default = 1)


ClassAttributeProperty

Description Possible values and constraints

y may be stored or contained inan instance of the attribute. Avalue of 1 represents a scalarand a value of n represents avector

N

DefaultValue

A default value for theattribute to be supplied bythe system when an object iscreated. (Note: Defaultvalues may be specified forsub-objects, that is,attributes of sub-objects)

1 (default = 1)

N

DefaultFixed

Used to show if the defaultvalue can be modified onobjects of this class

True

False (default = False)

QuantityType

If the Type property is realand the attribute is intendedto hold values of a physicalquantity such as temperatureor pressure, this propertyspecifies the quantity type ofthe attribute

One of the quantity types defined in thecurrent UOM Definitions file. Examplesare:

Length

Heat Transfer Coefficient

(default = none)

CaseFixed

Specifies whether theattribute can be different fordifferent cases

True


CloneFixed

Specifies whether theattribute can have differentvalues between clones

True


Disciplines A list of discipline privilegesan end user must possess tochange the attribute value

(default = none)

Deleting an Attribute

This procedure allows you to delete an attribute from an existing class.


1 Select an attribute in the Attribute View of… window.

2 Select Edit | Delete to remove the attribute from the attribute view.

Moving an Attribute

This procedure allows you to move an attribute up or down in the systemorder of attributes in a class.


1 Select an attribute in the attribute view.


2 Click the toolbar Move Up or Move Down icon (or right-click the mouseto display the context-menu.

The selected attribute is moved up one position or down one position inthe attribute view, but remains the selected attribute. The systempreserves the new system order when the class attributes are saved to alibrary file.

Note: The Move Up command is disabled if you select an attributebelonging to a subclass or superclass of the class for which the attributeview is current.

Copying and Pasting an Attribute

This procedure allows you to copy attributes from one location in a class andmake a copy of the attributes in another location in the same class or anotherclass.


1 Select an attribute in the class attribute view (the selected attributes maynot be contiguous).

2 Select Copy Attribute from the right mouse button context menu.

3 Select another attribute in the same class attribute view or a differentclass attribute view.

4 Select Edit | Paste. A copy of the attribute is inserted immediately beforethe selected attribute and all properties of the copied attribute arereplicated in the inserted attribute.

Note: The Edit | Paste command is disabled if you select a targetattribute that belongs to a subclass or superclass of the class.

Cut Copy and Pasting an Attribute

This procedure allows you to cut, copy and paste the text from any field toanother.


1 Select one of the attributes.

2 Select Edit | Cut. This removes the selected text from the class attributeview – unsetting the property if allowed.

3 Select another attribute in the same class attribute view or a differentclass attribute view.

4 Select Edit | Paste. The previously removed text is inserted as the valuefor the selected property.

Note: If you select a target attribute that belongs to a subclass orsuperclass of the class, the Edit | Cut and Edit | Paste commands aredisabled.


Checking an Attribute

This procedure allows you to check a class attribute for semantic errors suchas invalid references or missing required properties.

1 With the Class Library Editor already open and the Attribute View of…window open, select an attribute in the Class Attribute View.

2 Select the Check Attribute command. A check on the properties of theattribute is performed and a report window listing all messages generatedby the check is generated.

Association Operations

Creating and Editing Association

This procedure allows you to create an association between classes. Onlybinary associations are supported. .

To create an association:

1 With the Class Library Editor already open and the two classes alreadyexisting in the current library or a referenced library, select Insert |Association to display the New Association Properties dialog.

2 Enter data for the new association in the available fields (refer to thefollowing table for field details).

To edit an association:

3 Select an association in the Navigation View.

4 Select Edit | Properties to display the Edit Association Properties dialog.

5 Edit the attributes (shown in the table below) in any order.

6 Click OK to save the changes (or Cancel to discard) and close the dialog.

AssociationProperty

Property Description PossibleValues/Default

AssociationName

The name of the association

Category The name of the category in which theassociation is

Disciplines A list of the disciplines that are permitted toupdate attributes through this association

Role Name A name for this role in the association

Class The name of the class that fulfils this role. Theclass must exist in the current or includedlibraries

ClassAttribute

The name of the attribute in the class fulfillingthis role that will be used to navigate theassociation. This property is not directlyenterable by the user. It is set to be the RoleName at the other end of the Association

Multiplicity The number of instances of class A that may beat this end of the association

1 (default = 1)

n

Description A text description of this role in the association


Deleting an Association

This procedure allows you to delete an association between classes.


1 Select an association in the Navigation View.

2 Select Edit | Delete. The association is deleted from the current library,and the property view of the association is closed (if open).

Renaming an Association

This procedure allows you to rename an association.


1 Select an association in the Library View.

2 Right-click and select Rename. The system allows you to change thename of the Association in-situ in the Library View.

Enumeration Operations

Creating and Editing an Enumeration Type

This procedure allows you to create an enumeration data type. Anenumeration data type is a data type that specifies a list of allowed values foran instance of that data type.


To create an enumeration data type:

1 Select Insert | Enumeration to display the New Enumerations dialog (orright-click to display the context-menu).

2 Enters properties for the enumeration type (refer to the following table forfield details).

3 Click OK to save the new enumeration type (or Cancel to discard andclose the dialog).

To edit the properties of an enumeration:

1 Select an enumeration from the Library View.

2 Select Edit | Properties to display the Edit Enumeration Propertiesdialog.

3 Edit the displayed values of the properties (refer to the following table forfield details).

4 Click OK to save the new enumeration type (or Cancel to discard) andclose the dialog.


EnumerationProperty

Property Description PossibleValues

Name The name of the enumeration

Display Name The display name of the enumeration

Description A description of the enumeration type

Category The category of the enumeration

Store As Specifies how the enumeration value is saved andaccessed by default

Integer(default)

String

Open orClosed

An open enumeration has an initial option list definedin the enumeration definition but that is not consideredto be the complete set of possible options. A closedenumeration is one where the user cannot enteroptions not specified in the enumeration definition

Open

Closed(default)

Deleting an Enumeration

This procedure allows you to delete an enumeration data type from thecurrent library.


1 Select the name of an enumeration from the Library View.

2 Select Edit | Delete. The enumeration is deleted from the current library.

Renaming an Enumeration

This procedure allows you to rename an enumeration.


1 Select an enumeration in the Library View.

2 Select Rename from the right mouse button context menu. The systemallows you to change the name of the enumeration in-situ in the LibraryView.

Showing Enumeration Usage

This procedure allows you to obtain a report showing where an enumerationis used.


1 Select the name of an enumeration from the Library View.

2 Select Tools | Show Usage to display the Report – Usage ofEnumeration ‘name’ window. The report details the places in the currentlibrary and the included libraries where the enumeration is referenced.


Check Enumeration

This procedure allows you to obtain a report showing errors in theenumeration properties or options.


1 Select the name of an enumeration from the list of enumerations in thecurrent library or enumeration options view.

2 Select Tools | Check to display the Report – Result of Check forEnumeration ‘name’ window. The report provides details of any errors inthe enumeration properties or enumeration options.

Creating and Editing an Enumeration Option

This procedure allows you to create and edit an option in an enumeration.

With the Class Library Editor already open and an enumeration option view asthe current view:

1 Select an option or the end of the option list as an insertion point.

2 Right click the mouse and select Insert Option.

3 A new option is inserted in the option list at the insertion point.

4 Edit the option properties, clicking in each field to enter edit mode.

5 Refer to the following table for option details:

Class OptionProperty

Description Possible Values andConstraints

Name The name of the attribute thesystem uses to internallyidentify the attribute within theclass

(default = none)

Display Name The name of the attribute thesystem uses to identify theattribute to an end user

(default = none)

Description A description of the attribute A text description. May include aURL (default = none)

Type The data type of the attribute One of thefollowing:StringIntegerRealBooleanDateBinaryEnumeration…Object…If Enumeration… is specified, thename of an existing enumerationtype in the current or an includedlibrary must also be specifiedIfObject… is specified, the name ofan existing class in the current oran included library must also bespecified. This specifies that theattribute will contain instances ofan object of the specified class. Animplicit containment association iscreated between the parent objectand the sub-object


Class OptionProperty

Description Possible Values andConstraints

Category A string that assigns a categoryto the attribute for sorting,searching and filtering purposes

(default = none)

Multiplicity The number of values that maybe stored or contained in aninstance of the attribute. Avalue of 1 represents a scalarand a value of n represents avector

1 (default)

n

Default Value A default value for the attributeto be supplied by the systemwhen an object is created.(Note: default values may bespecified for sub-objects, thatis, attributes of sub-objects)

1 (default)

n

Default Fixed Used to show if the defaultvalue can be modified onobjects of this class

True

False (default)

Quantity Type If the Type property is real andthe attribute is intended to holdvalues of a physical quantitysuch as temperature orpressure, this property specifiesthe quantity type of theattribute

One of the quantity types definedin the current UOM definitions file.Examples are:

Length

Heat Transfer Coefficient

(default = none)

Case Fixed Specifies whether the attributecan be different for differentcases

True

False (default)

Clone Fixed Specifies whether the attributecan have different valuesbetween clones

True

False (default)

Disciplines A list of discipline privileges anend user must possess tochange the attribute value

(default = none)

Deleting an Enumeration Option

This procedure allows you to delete an option in an enumeration.

With the Class Library Editor already open, an Enumeration option view as thecurrent view and an option selected:

1 Select the Delete command.

2 The option is removed from the list.


Class View Operations

Creating and Editing a Class View

This procedure allows you to create a new Class View in the current library.


1 Select Insert | Class View to display the New Class View dialog.

2 Enter Class View properties in the Name, Description and Category fields.

3 Click OK to save the new Class View (or Cancel to discard and close thedialog).

To edit a Class View:

4 Select a Class View in the Library View.

5 Select Edit | Properties to display the Edit Class View Properties dialog.

6 Edit Class View properties (in any order).

7 Click OK to save the new enumeration type (or Cancel to discard) andclose the dialog. The dialog is closed and changes are applied to the ClassView properties.

Renaming a Class View

This procedure allows you to change the name of a Class View in the currentlibrary.


1 Select a Class View in the Library View.

2 Select Rename from the right mouse button context-menu.

3 Edit the Class View name and click anywhere outside of the edit field tosave the change(s).

Editing Class View Content

This procedure allows you to display the content of a Class View. Class Viewcontent is organized in a structure of nodes and attributes. A node cancontain any number of other nodes and attributes.


1 Select an existing Class View in the Library View.

2 Select Open command.

3 The system displays the Class View content as a tree view.


Creating a Class View Node

This procedure allows you to create a new node anywhere in the Class Viewtree structure.

With the Class Library Editor already open and with Class View content viewas the current view:

1 Select a Class View node or attribute.

2 Select Insert Class View Node and select Before or After or Sub-nodeoption. The system creates a new Class View node at the requestedlocation and makes the new node the current node.

Expanding and Collapsing Class View Nodes

This procedure allows you to expand and/or collapse a selected node in theClass View content.

With the Class Library Editor already open and with Class View content viewas the current view:

1 Select a node in the Class View content.

2 Select the Expand All toolbar icon to display the Class View content withthe selected node expanded to show the subordinate nodes and attributes.

3 Select the Collapse All toolbar icon to display the Class View content withthe selected node collapsed.

Creating and Editing a Class View Attribute

This procedure allows you to create and edit a Class View attribute.

To create a Class View Attribute (with the Class Library Editor already openand with Class View content view as the current view):

1 Select an attribute or node in the content view.

2 Select Insert Attribute to create an attribute in the position immediatelyprior to the selected item, at the same level as the selected item.

3 Enter the properties of the new Class View attribute. Class View attributeproperties can also be edited in-line in the Class View content view.

To edit a Class View Attribute (with the Class Library Editor already open andwith Class View content view as the current view):

4 Select a Class View attribute to be edited.

5 Select Edit | Properties to display the Attribute Properties in an AttributeProperty View.

6 Edit the attribute properties (refer to the following table for fielddescriptions). Class View attribute properties can also be edited in-line inthe Class View content view.


Class ViewAttributeProperty

Description Possible Values and Constraints

Name Used by the AZ system to uniquelyidentify the attribute in the Class View.This name is used to identify thisattribute in scripting

The name must be unique in the scope ofthe Class View

DisplayName

A name used to identify the attribute inthe Class View. This does not have to beunique in the context of the Class View,but must be unique within the scope ofthe owning node

Description Description of the attribute using theterminology of the target application

Data Type The implied data type of this attribute One of the following:

String

Integer

Real

Boolean

Date

Binary

Enumeration…

Object…

If Enumeration… is specified, the name ofan existing enumeration type in the currentor included library must be specified

If Class View… is specified, the name of anexisting class view in the current or anincluded library must also be specified. Thisspecifies that the attribute will contain thespecified class view

QuantityType

If the Data Type is Real this propertycontains the quantity type of the attribute

The quantity type reference must exist inthe current UOM definitions file

Units If the attribute has a quantity type thenthis property may be set to a valid unitsreference. The units reference determinesthe units of measure that a value of thisattribute is expressed in whentransmitted to or from the application

Any units reference that is valid for thequantity type property of the attribute. Theunits reference is validated against the UOMdefinition file

Defaults

Pa

K

W

Multiplicity The number of instances of this attributethat the application allows in the contextof the owning node

1 (default = 1)

n

Help Text Text or reference to text that describesthe usage of the attribute in the contextof an application and the context of aspecific user organization

The name must be unique in the scope ofthe Class View

Link The Link to the corresponding attribute inthe Composite View


Creating a Class View to Composite View Link

This procedure allows you to create a link between an attribute in a ClassView attribute and an attribute in the Composite View.

With the Class Library Editor already open and with a Class View attributeselected:

1 Select Create link to display the content view of the correspondingComposite View.

2 Browse the content view of the composite Class View and select anattribute of the Composite View.

3 Select Create link to create a link between the Class View attribute andthe Composite View attribute.

Composite View Operations

Creating a Composite View

This procedure allows you to create a new Composite View in the currentlibrary, or select a Class View to seed a new Composite View.

With the Class Library Editor already open and with the Library View selected.

To create a new Composite View:

1 Select Insert | Composite View to display the New Composite viewProperties dialog.

o Enter the Composite View Properties in the Name, Description andCategory fields.

o Enter the Class the composite view relates to, using the browsebutton.

2 Click OK to save the new Composite View (or Cancel to discard) and closethe dialog.

To seed a new Composite View:

1 Select a Class View not already associated with a Composite View.

2 Select Insert | Seed New Composite View. A new Composite View isseeded with the content of the Class View.

Editing a Composite View

This procedure allows you to edit an existing Composite View.


1 Select an existing Composite View in the Library View.

2 Select Edit | Properties to display the Edit Composite View Propertiesdialog, or double-click on the title.

3 Enter new Composite View properties.

4 Click OK to save the new title (or Cancel to discard) and close the dialog.If you double-clicked on the title only, click anywhere away from the editfield.


Editing Composite View Properties

This procedure allows you to enter or edit Composite View properties.


1 Select a Composite View and select Edit | Properties to display the EditComposite View Properties dialog.

2 Edit the properties (in any order).

3 Click OK to save the changes (or Cancel to discard) and close the dialog.

Renaming a Composite View

This procedure allows you to change the name of a Composite View in thecurrent library.


1 Select a Composite View in the Library View.

2 Select Rename (right-click to display the context-menu) to change thename of the Composite View in situ.

Editing Composite View Content

This procedure allows you to display the content of an Composite View.Composite View content is organized as a flat list of attributes.


1 Select an existing Composite View in the Library View.

2 Select Open (right-click to display the context-menu) to display theComposite View attribute content.

3 Edit the content by clicking in the fields required to activate edit mode.

Creating and Editing a Composite View Attribute

This procedure allows you to create a Composite View attribute. Refer to thefollowing table for field details.

With the Class Library Editor already open and a Class View content viewcurrent displayed.

To create a Composite View Attribute:

1 Select an attribute or node in the content view.

2 Select Insert Attribute from the context-menu and select Before orAfter. An attribute is created in the position immediately before orimmediately after the selected item.

To edit a Composite View Attribute:

With the Class Library Editor already open; a Composite View contents viewcurrent and a Composite View attribute selected:

1 Select the Composite View attribute properties in-line in the CompositeView content view.

2 Edit the properties and click anywhere off the edit field when finished.


Edit Composite View Attribute Properties

This procedure allows you to edit the properties of a Composite View.

With the Class Library Editor already open and a Composite View contentsview as current:

1 Select a property of an attribute in the Content view. The system presentsan editor for the property (the style of the editor depends on theproperty).

2 Edit the property as required.

Composite ViewAttribute Property

Description Possible valuesand constraints

Name A name used by the AZ system touniquely identify the attribute in theClass View. This is the name that willbe used to identify this attribute inscripting

The name must beunique in the scopeof the Attribute ClassView

Description Description of the attribute using theterminology of the target application

Type The data type of this attribute Selected from the listof data typessupported by the AZObject Model

Quantity Type The quantity type of this attributeselected

Selected from the AZquantity type list

Multiplicity The number of instances of thisattribute that the application allows inthe context of the owning node

1 (default = 1)

N

Route The route to the correspondingattribute starting from the Classspecified for this Composite View

Creating and Editing a Route

This procedure allows you to set the route property for a composite viewattribute by choosing an attribute from an attribute view of the class that thecomposite view represents. The system sets the route property value basedon the selected attribute. You can then refine the route by adding attributeselection criteria.


1 Browse the Class Attribute view for the class corresponding to thecomposite view.

2 Expand attributes of type object where appropriate to locate the classattribute that the composite view attribute will be mapped to.

3 Select any valid subclass of an object attribute to expand.

4 Drag and drop the class attribute onto the composite class view routeproperty. The system writes the route of the selected class attribute intothe route property.


Locate Corresponding Class Attribute

This procedure allows you to locate the class attribute to which a compositeview attribute is routed.

With the Class Library Editor already open and a Composite View contentsview is current:

1 Select a composite view attribute and click the Open icon on the toolbar.

2 The class attribute is highlighted.

Show Composite View Attribute Usage

This procedure allows you to obtain a list of the Class View attributes in thecurrent library or an include library that are linked to a Composite ViewAttribute.


1 Select a Composite View attribute.

2 Select the Show Usage command.

The system displays a usage report showing the Class View name andClass View Attribute name for each existing reference.

3 Click an entry in the usage report and the Class View content view of thereferenced Class View is displayed.

User Preferences and OptionsThe Tools menu is used to select preferences and options.

User preferences and options are saved when the Class Library Editor isclosed and they are reused next time the application is launched.

If you do not select any preferences or options system defaults are applied forall settings.

Selecting a UOM Definitions File

A “UOM definitions file” is used by the Class Library Editor to populate theQuantity Type and Units selection dialogs and for the validation of QuantityTypes and Units.

A default UOM Definitions File is supplied by the system and this is used if theuser does not explicitly select a UOM Definitions file. The user is able to selecta different UOM Definitions File.


1 Select Tools | UOM Definitions…. The system shows the pathname ofthe currently selected UOMDefinitions file.

2 Select browse. A file Open dialog is displayed.

3 Locate the directory containing a UOM Definitions file. The system displaysthe files in the selected directory that have an xml file type.


4 Select one of the files in the file open dialog and confirm the selection. Thesystem loads the contents of the selected UOM Definition file.

5 The system subsequently uses the selected UOM Definitions file topopulate the Quantity Type selection dialog whenever you edit anattribute Quantity Type property and, uses the selected UOM Definitionsfile to validate the Quantity Type property of attributes and Unitsproperties of attributes when the Check command is given.

Set Option to Test for Warning Conditions inCheck Command

To select whether the system looks for warning conditions on a Checkcommand.

1 Select Tools | Preferences. The Preferences dialog is displayed.

2 Select the Check option Show Warnings when Checking.

Note: The existence of warning conditions does not prevent a Class Storefrom being generated. Opting to omit checks for warning conditions canreduce the time taken to execute the Check command.

Set Option to Scroll with Fixed Column

To select whether the system keeps the name column in the content panealways visible and on the left check this box.


2 Select the Check option Scroll using Fixed Column.

Select Level of Output

The system outputs status of its progress in the output tab of the output bar.To select how much output is written select the required level from the dropdown list.


2 Select the required level of output from the drop-down list.

11 Explorer 161

11 Explorer

The Aspen Basic Engineering Explorer provides an organizational view ofobjects, data, diagrams and datasheets in an open workspace. Databasecontent is collected into a tree of folders from which a variety of operationscan be performed.

Subject to permissions, authorized users (those with a valid username andpassword) can perform basic object operations, such as, copying and cloning,through to browsing or editing object attributes of Workspaces. Authorizedusers can also assign security to folders; this provides another way tomanage access to objects, documents and data.

The attribute views allow users to navigate the actual stored object structureor view the data in a flat engineering-oriented display, which is helpful toend-users rather than configuration users.

162 11 Explorer

The Explorer can also be used to launch other Aspen Basic Engineeringapplications. For example double clicking a datasheet item within a folder willlaunch the Datasheet Editor application to display the datasheet.

Within the Explorer, Workspaces can be exported for re-use, archiving orexternal delivery. External design packages can also be imported into anexisting Workspace hierarchy.

Main Window Elements

The Aspen Basic Engineering Explorer window comprises of six standardelements:

Explorer Menu – Menu options depend upon the type of view that iscurrently selected.

Toolbar (with tooltips).

Status Bar – Displays user and server information.

o Folders view – Displays the current folder tree structure.

o Filters view – Displays the currently available workspace filters

Right pane – Displays tabbed views of the currently open view windows.

These windows can be any number of the three main types:

1 Folder view – Displays the contents of a folder selected in the foldersview.

2 Filter view – Displays the objects for a filter selected in the filters view.

3 Attribute views – Displays the attributes for a selected object.

The folder tree and filter views are dockable windows so can be positionedaccording to the users preferences.

Explorer MenusThe Explorer has the following menus:

File menu

Edit menu

View menu

Case menu

Folder menu

Object menu

Run menu

Tools menu

SmartPlant menu

Window menu

Help menu (not described)

11 Explorer 163



Open Workspace Allows you to select a Workspace

Close Workspace Closes the currently open Workspace

Refresh Workspace Refreshes the current view of the Workspace

Open Folder View Opens a new folder view window

Open Filter View Opens a new filter view window

Print Prints the displayed information

Print Setup Opens the Windows Print Setup dialog

Exit Exits the Explorer application

Edit MenuThe Edit menu contains the following commands:

Edit MenuCommand

Action

Rename Renames the selected item

Copy Copies the selection to the clipboard (used to move data withinthe same Workspace)

Paste Places the last item(s) copied to the clipboard at the cursorposition (used to move data within the same Workspace)

Copy as Package Copy selected folder as an import/export package (used tomove data between different Workspaces)

Paste as Package Paste selected folder as an import/export package (used topaste data between different Workspaces)

ComponentManagement

Opens the Component Management dialog allowing you todisplay and manage mapped and unmapped components

EnumerationManagement

Opens the Enumeration Management Dialog

ProjectManagement

Opens the Project Management dialog

BEDD Management Opens the Basic Engineering Design Data (BEDD) datasheetwhich contains environmental data for the Workspace

164 11 Explorer


View MenuCommand

Action

Toolbars (drop-down menu)

Standard Toolbar: Shows/hides the toolbar (toggle)

Filter Bar: Displays the filter bar (this allows you to add yourown filters, e.g., add a filter to display all pumps, etc.)

Status Bar: Shows/hides the status bar (toggle)

Customize: Allows you to customize the menu configurations

Folder Settings Allows you to specify folder settings

Case Settings Allows you to specify how the case column information isdisplayed in the attribute views

Query Editor Displays a query window for script execution

Folder Tree View Shows/hides the folder tree view window (toggle)

Filter Tree View Shows/hides the filter tree view window (toggle)

Attributes Displays the attributes of the selected Object

Properties Displays the properties of the selected folder

Case MenuThe Case menu contains the following commands:

Case MenuCommand

Action

Create Creates a new Case (Global/Restricted)

Rename Renames an existing case

Governing Case(drop-down menu)

Set Global Default: Allows you to set the global defaultgoverning case

Set Object Governing Case: Allows you to set the governingcase for a selection of objects

Reset Object Governing Case: Allows you to reset thegoverning case back to the default for a selection of objects

Copy Object Case Copies an object case

Remove ObjectCase

Removes an object case

Delete Deletes an existing case

11 Explorer 165

Folder MenuThe Folder menu contains the following commands:

Folder MenuCommand

Action

New Folder Creates a new folder

Remove Removes items from the selected folder but keeps these items inthe database

Delete Deletes the selected folder and all contents from the Workspace.Note: As deleted objects cannot be retrieved, a warning dialog isdisplayed before deletion asking you to confirm/cancel delete

Add Diagram Adds an existing diagram to the selected folder

Add Object Adds an existing object to the folder

Add Datasheet Adds an existing datasheet to the folder

Add File Adds a file to the current folder

Export Package Exports a Workspace Package (in .zpkg file format)

Import Package Imports a Workspace Package

Object MenuThe Object menu contains the following commands:

Object MenuCommand

Action

Create Creates a new object

Copy Creates a copy of an existing object

Clone Creates a clone of an existing object

Remove Removes items from the selected folder, but keeps these items inthe database

Delete Deletes an object from the Workspace

Claim Claim a selected object

UnClaim Release a claim on a selected object

File (drop-down menu)

Check Out: Checks a file out to your local PC

Check In: Checks in a file from your local machine including anychanges made

Undo Check out: Cancels a check out undoing all changes made

Save As: Saves the selected file to a specified location

ExportPackage

Exports a Workspace Package for the objects selected

166 11 Explorer

Run MenuThe Run menu contains the following commands:

Run Menu Command Action

Local Method Runs a method on the currently selected object

Global Method Runs a method

Rule Runs a rule

Tools MenuThe Tools menu contains the following command:

Tools MenuCommand

Action

Customize Opens the Customize Tools dialog and allows you to customize(add/remove) menu commands

Framework MenuThe Framework menu contains the following commands:

Framework MenuCommand

Action

Publish Allows you to publish to SmartPlant

Find Documents toPublish

Allows you to find specific documents to publish to SmartPlant

Retrieve Allows you to retrieve from SmartPlant

Todo List Opens the Todo dialog allowing you to create a number of ‘ToDo’ operations

Browse Allows you to browse SmartPlant

Window MenuThe Window menu contains the following commands:

Window MenuCommand

Action

Cascade Arranges windows so that they overlap

Tile Horizontally Arranges windows horizontally as non-overlapping tiles

Tile Vertically Arranges windows vertically as non-overlapping tiles

Arrange Icons Arranges icons at the bottom of the window when windows areminimized

11 Explorer 167

Help MenuThe Help menu contains the following commands:

Help MenuCommand

Action

AZ Explorer Help Launches the AZ Explorer help file

Training Launches an internet connection to the AspenTech TrainingCenter for Aspen Basic Engineering

Product Support onthe Web

Launches an internet connection to the AspenTech SupportCenter for Aspen Basic Engineering

Contacting Support Provides you with information about how to contact customersupport

About Aspen BasicEngineering

Shows the help about information for Aspen Basic Engineering

Explorer ToolbarThe Toolbar displays commonly used menu operations as icons (buttons) onthe toolbar.

The icons used on the toolbar buttons display a tooltip (action) when thecursor is floated over them.

Other menu options can be added to the toolbar (as icons) through thecustomization feature:

Toolbar icons comprise:


1 Open Workspace Opens an Aspen Basic Engineering Workspace

2 Refresh Workspace Refreshes the current Workspace

3 Rename Renames the selected item

4 Copy Copies the selection to the clipboard

5 Paste Places the last item(s) copied to the clipboard atthe cursor position

6 Remove from Folder Removes the selected items from the containingfolder

7 Delete fromWorkspace

Delete the selected items permanently from theworkspace

8 Add Diagram Adds a diagram to the current folder

9 Add Datasheet Adds a datasheet to the current folder

10 Add Object Adds an object to the current folder

168 11 Explorer


11 Add File Adds a file to the current folder

12 New Folder Creates a new folder

13 Create Object Creates a new object

14 Copy Object Copies the selected objects

15 Clone Object Clones the selected objects

16 Display Help Opens the Explorer online help

Aspen Basic EngineeringExplorer Status BarThe status bar (seen at the bottom of the Explorer window) displays thefollowing information:

CAPS LOCK (keyboard status).

NUM LOCK (keyboard status).

SCROLL LOCK (keyboard status).

User (current user of the application).

Data server (currently connected).

Folders ViewThe folders tree view window allows you to organize a hierarchy of folders sothat related objects can be grouped together. A folder can be used to grouptogether datasheets, diagrams and Workspace objects. A hierarchy of folderscan be created so that the Workspace content can be organized, by processsection and within a section, by process unit to an arbitrary degree of nesting.

Working with Folders

Viewing FoldersA specific folder view is displayed when a folder is selected in the folders treeview window. Within the folder view customizable columns display the statusand attributes of the objects in the folder. The folder view can also be sortedbased on the values of any column by clicking on the column header. Anarrow indicates sort direction.

The folder view can also be filtered so that a sub-set of the objects in a foldercan be displayed by invoking the filter bar from the view menu and selectingone of the filters from the drop down list. Information on how to create thesefilters is given in the section Customizing Folder Settings below.

11 Explorer 169

An object displayed in the folder view can be used to invoke an application toedit/display that object (e.g., the Drawing Editor for a drawing object, or theDatasheet Editor for a datasheet).

Customizing Folder SettingsFolder settings can be customized within the Folder Properties dialog. Thisdialog has two tabs, View and Filter.

To specify columns displayed in the Folder view

1 In the Explorer window, click View | Folder Settings.

2 By default, you are placed on the View tab.

3 The Icon and KnownName properties can be added as a column along withany attribute name.

4 Select a field and click the Add button to add the field to the list in theDisplayed fields list.

To delete fields from the Available Fields list

1 Select a field in the Available Fields list.

2 Click the Delete button to remove the field from the list.

To update the Available Fields list

Click the Update button.

To set the order of columns displayed

1 Select a field from the Displayed Fields list and click the Up or Downbutton to move the field to the required position in the list.

2 Click OK to save settings and close the dialog, or Cancel to discard thesettings and close the dialog.

170 11 Explorer

To add a filter to the folder view

1 Click the Filter tab to display the Filter area.

2 Click the Add Filter… button to open the Add Filter dialog.

3 In the Name field, add a name for the filter (e.g., Diagrams).

4 Enter a meaningful description in the Description field.

5 In the Column field select a column title from the drop-down list, selectone of the four arguments and click the Add button to add this filter tothe right pane.

11 Explorer 171

Creating a New FolderTo create a new folder:

1 Select the folder in the hierarchy in which the new folder is to be created.The folder can be selected either from the folder tree view window or byselecting an open folder view.

2 In the Explorer window, click Folder | New Folder, (or click the NewFolder toolbar button).

3 The new folder is added to the hierarchy in the previously selectedposition.

Renaming a FolderTo rename a folder:

1 Select the folder to be renamed from the hierarchy.

2 In the Explorer window, click Edit | Rename. (An in-place edit control isdisplayed in the tree control.)

3 Enter the new name of the folder.

4 Click the Enter (keyboard) key to update the folder name. (To leave thefolder name unchanged hit the Escape key.)

Removing a FolderTo remove a folder:

1 Select the folder to be deleted from the hierarchy.

2 In the Explorer window, click Folder | Remove.

3 The folder is deleted, from the tree view, but any items contained in thefolder still exist within the workspace.

Deleting a Folder

Note: This operation deletes folder contents from the database permanently.A warning is displayed before the deletion is executed allowing you toconfirm/cancel the deletion.

To delete a folder:

1 Select the folder to be deleted from the hierarchy.

2 In the Explorer window, click Folder | Delete.

3 A warning dialog is displayed allowing you to proceed with folder (andcontaining items) deletion from the database, or cancel the deletion.

4 If you select Yes (to delete) the folder and content(s) are permanentlydeleted from the database.

172 11 Explorer

Adding Existing Diagrams to a FolderTo add an existing diagram to a folder:

1 Select the folder from the hierarchy that diagrams are to be added to.

2 In the Explorer window, click Folder | Add Diagram. This opens theSelect Objects dialog. A list of available diagrams is displayed.

3 Select the diagram(s) to be added and click the OK button. This adds theselected diagram(s) to the folder. (To cancel this action, click the Cancelbutton.)

Adding Existing Datasheets to a FolderTo add an existing datasheet to a folder:

1 Select the folder from the hierarchy that a datasheet is to be added to.

2 In the Explorer window, click Folder | Add Datasheet. This opens theSelect Objects dialog. A list of available datasheets is displayed.

3 Select the datasheet(s) to be added from the list displayed and click theOK button. This adds the selected datasheet(s) to the folder. (To cancelthis action, click the Cancel button).

Adding Existing Objects to a FolderTo add existing objects to a folder:

1 Select the folder from the hierarchy that an object is to be added to.

2 In the Explorer window, click Folder | Add Object. This opens the SelectObjects dialog. A list of existing objects is displayed.

3 Select the object(s) to be added from the list displayed and click the OKbutton. This adds the selected object(s) to the folder. (To cancel thisaction, click the Cancel button.)

Note: There is a checkbox on the dialogs for the actions adding diagrams,datasheets and objects that when checked will filter the items listed to onlydisplay editable items. This is useful when working with projects.

Adding Files to a FolderTo add files to a folder:

1 Select the folder from the hierarchy, where the file is to be added.

2 In the Explorer window, click Folder | Add File. This opens the SelectFile dialog. A list of existing files is displayed.

3 Select the file(s) to be added from the list displayed and click the OKbutton. This adds the selected file(s) to the folder. (To cancel this action,click the Cancel button.)

Note: Drag and drop. Files can be dragged and dropped from your localmachine directly into folders in the explorer application.

11 Explorer 173

Dragging & Dropping Folders and ObjectsFolders and objects can be dragged and dropped from the:

Folders tree to the folders tree.

Folders tree to the folder view.

Folder view to the folder tree.

When dragging and dropping, the following conditions apply:

The default drop action is to move the Object/Folder from the drag sourceto the drop destination folder.

Note: Cut and Paste. The cut and paste options from the Edit menu can alsobe used to achieve drag and drop behavior.

Working with FilesFiles can be added to an open workspace and viewed/edited within theExplorer, allowing individual users to modify files which may be shared bymany other users.

A file can be edited by any privileged user (a user with write access enabled)but only by one user can edit a file at any one time.

Before a file can be edited, it must be checked out from the server into acurrently open workspace (a copy of the file is sent to the local PC of theuser). The original copy of the file on the server is not changed until the local(checked out) copy is modified and checked back in, at which stage the file onthe server is updated with any changes.

If the checked out file is not modified locally, no changes are made to theoriginal file. If the checked out file is modified locally, but the Undo CheckOut option is selected, no changes are made to the original file.

A read-only copy of a file can be accessed and viewed by multiple userssimultaneously. A copy of a file can also be saved with a different name to auser specified directory (locally or across a network).

Note: Files can only be checked in or out of the Explorer individually (theycannot be group selected).

Explorer File Menu OptionsThe following Explorer File menu options are available via the Object menuand/or the context (right mouse-click) menu:

Check OutChecks a file out from the server to your local machine. This option isactivated in the main/context menu when a file has been selected in afolder view.

Check InChecks in a file from your local machine back to the server (including anychanges made to that file). This option is activated in the main/contextmenu when a file has been selected in a folder view.

174 11 Explorer

Undo Check OutCancels a check out and also cancels any changes made to that file whilechecked out. This option is activated in the main/context menu when a filehas been selected in a folder view.

Save AsAllows you to save the selected file to a specified location. This option isactivated in the main/context menu when a file has been selected in afolder view.

Launching a File from the ExplorerWhen a file is first launched from the Explorer the File Services dialog isdisplayed prompting selection of the following options:

Check out a read-only file.

Check out an editable file.

Selecting to view the read-only version of the file allows you to view a copy ofthe file and save it as another name (to a user specified directory). Multipleusers may view a read-only version of the file simultaneously.

Selecting to check out the file and edit it copies the file onto your local PC andallows you to modify the file, save it with a new name (to a different location)and update the original copy by checking the file back in.

You can also add a file to the currently open workspace. This file cansubsequently be checked out/in and edited as required.

Adding a FileTo add a new file to the currently open workspace:

1 Select a folder in the Explorer folders tree view window or by selecting afolder item in a folder view.

2 Right mouse click and select File | Add.

3 Navigate to the location of the file you want to add and click OK. A newfile is added to the workspace.

11 Explorer 175

Checking Out a Read-only FileIf you check out a read-only version of the file, it can be viewed but notedited. The current version of the file is recorded in the workspace.

To check out a read-only file:

1 Select an existing file in an open Explorer folder view.

2 Double-click on the file to display the File Services prompt.

3 Select View the current version of this file (Read-only). A read-onlycopy of the file is opened allowing you to review the content. No editorialrights are granted.

Checking Out an Editable FileIf you check out an editable file it is copied onto your computer and you havefull editorial privileges. When you have finished editing the file (and havesaved it), you can check it back in and the file on the server is updated withany changes made.

Note: If you do not save the local file before checking it back in, no changeswill be made to the original file.

To check out an editable file:

1 Select an existing file in an open Explorer folder view.

2 Double-click on the file to display the File Services prompt.

3 Select Check out this file and edit it. An editable file is opened allowingyou to review and edit the content. Full editorial rights are granted.

Check Out Status

The check out status (locked or open) is indicated in the locked and locked bycolumns in the Explorer (these columns can be shown by configuring thefolder settings).

Any changes to this information are updated when the file views arerefreshed.

If you save and close the file, then double-click to open it again withoutchecking it back out, any current changes are retained on your local copy ofthe file.

176 11 Explorer

If the File is Already Checked Out

If a second user attempts to check out a file that is already checked out, aprompt is displayed stating that the file is already checked out toDOMAIN\Username and only a read-only copy of that file can be checked out:

The second user cannot review any changes made by the first user until thelocal file has been checked back in. (This is because any changes made up tothat point only exist in the file on the local machine.)

Checking In a FileWhen you are satisfied with any changes made, the file can be checked backin enabling these changes to be available to all other users in the workspace.The file can then checked out by any other privileged user(s).

Note: Files must be checked in by the user.Check in is user-initiated, not an automatic procedure.

To check a file in:

Select the file and select Object | File | Check In (or right mouse clickto display the context menu). The locked and locked by columns in theExplorer are updated to indicate the check in was successful. (Thisinformation will be available to other users the next time they refreshtheir views on the file.)

Undo Check OutIf you do not wish to keep any changes you have made to the file on yourlocal machine (even if you have saved the file locally), you can select theUndo Check Out option.

This ensures the original file (on the server) is not updated with any locallymade changes.

To discard local changes:

Select Object | File | Undo Check Out. This option cancels any localchanges and leaves the contents of the original file intact.

Save AsThe Save As option allows you to save a copy of the file on your local PC to auser specified directory. This new file has no link back to the workspace. If

11 Explorer 177

the file saved to the local machine is then edited, changes to that file are notreflected in the file contained in the workspace.

To save a file with a different name:

Select Object | File | Save As. The Windows Save As dialog is displayedallowing you to save the file to a user specified directory.

Note: The reverse also applies when a file from your local machine has beendragged into an Explorer folder or added via the add File menu option. Oncethe file has been added to the workspace it exists as a separate entity to thefile on the local machine. Any changes to the original (or to the file in theworkspace) are not reflected in the other file.

Working with Objects

Creating New ObjectsTo create new objects in the database:

1 Select the folder from the hierarchy that an object is to be created in.

2 Click Object | Create to open the Select Class dialog.

3 Select the required class, and click the OK button. The object is placed inthe selected folder with the name New Object. (To cancel this action, clickthe Cancel button.) If the name of the class is known it can be typed inthe edit box to scroll the selection list.

4 Rename the object as required.

178 11 Explorer

Copying an ObjectTo copy an object:

1 Select the object to be copied from either an open folder or filter view.

2 Click Object | Copy to copy the currently selected object. The copy isplaced in the same folder as the original object.


Cloning an ObjectTo clone an object:

1 Select the object to be cloned from either an open folder or filter view.

2 Click Object | Clone to clone the currently selected object. The clonedobject is placed in the same folder as the original.


Removing an ObjectTo remove an object from its containing folder:

1 Select the object to be removed from an open folder view.

2 Click Object | Remove.

3 The object is removed from the containing folder. It still exists within theworkspace.

Claim an ObjectTo claim an object to your current project:

1 Select the object to be claimed from an open folder or filter view.

2 Click Object | Claim.

3 You are prompted to make a selection between taking out an exclusive ora shared claim on the object.

4 Selecting OK on the dialog claims the selected object.

For more information, see Adding Objects to the Project scope.

UnClaim an ObjectTo unclaim an object from your current project:

1 Select the object to be unclaimed from an open folder or filter view.

2 Click Object | UnClaim.

3 A warning dialog is displayed asking you to confirm the action.

4 Selecting OK to the dialog unclaims the selected object.

11 Explorer 179

Deleting an Object

Note: This operation deletes the object from the database permanently. Awarning is displayed before the deletion is executed allowing you toconfirm/cancel the deletion.

To delete an object:

1 Select the object to be deleted.

2 In the Explorer window, click Object | Delete.

3 A warning dialog promts you to proceed or cancel the deletion.

Object PropertiesTo view the properties of an object:

1 Select the object for which we want to view the properties.

2 In the Explorer window, click View | Properties.

3 The Object Properties dialog is displayed showing two tabs:

o General: Displays general property information about the item.

o Security: Displays the roles and privileges information for the objectcurrently selected.

For more information, see the section Managing Workspaces.

Viewing Object AttributesObject attributes views are launched by double clicking an object in anExplorer window. The view is added to the tabbed window collection of folderand filter views that you may already have open:

180 11 Explorer

If you repeat this action on another object then a new attribute view will beopened for that object. If you repeat this action for an object for which theyalready have a view open then the existing view will just be brought to thefront of the tabbed window collection. Attributes views that are open for anobject when it is deleted from the workspace will be automatically closed.

The attribute views are made up of a number of columns. The first twocolumns (always present) are the attribute name and the units columns. Anysubsequent columns displayed show the attribute data values for this objectfor any cases that apply. Case columns can be configured to make the vieweasier to read. Please see the section Customizing Case Settings for moreinformation.

If the governing case column for this object is visible with the current casesettings it will be identifiable to you by a red ‘g’ in a red circle before the casename.

Attribute views have the following specific menu options:

Object Select Object – Opens the Select Object dialog. If another object is

chosen then the attributes view will change to report the attributeinformation for the object selected.

Select ClassView – Opens the Select ClassView dialog. Selecting aspecific ClassView here will result in the attributes view reporting theattribute data for the currently selected object in the structure defined bythe ClassView.

Print – Opens the Windows Print dialog, allowing you to print thedisplayed information from the attributes view.

Refresh – Refreshes the contents of the open window to catch anyupdates in the attribute data displayed.

11 Explorer 181

Options

These menu options specify how the attribute information for the objectselected is displayed in the window; these options can be selected individuallyor in any combination:

Show All Attributes – Displays all available attributes.

Show Associations – Displays all available associations.

Show System Attributes – Displays all available system attributes.

Right-clicking on any cell in the attributes view displays a popup menu whichshows the following options for the attribute row and case selected:

Insert Item – Allows you to insert an object into a selected object vectorattribute.

Remove Item – Allows you to delete an object from a selected objectvector attribute.

Change Class – Allows you to change the class of a selected object in aparent object vector attribute to any of the classes that derive from theclass of the containing attribute.

Claim – Allows you to claim the object for which the attributes are beingdisplayed.

UnClaim – Allows you to unclaim the object for which the attributes arebeing displayed.

Properties – Allows you to launch the specific attribute properties for thecell selected. These are specific for the case column selected.

Units Sets that are used when displaying the attributes in the view arecontrolled by selecting from the drop down list in the top right hand corner ofthe attributes view.

182 11 Explorer

Attribute Properties

The attribute properties displayed are for the specific attribute cell selectedand represent the case data for the column from which the dialog wasinitiated:

The attribute properties dialog has three main tabs:

Data View – Allows you to view and edit the attribute specific datavalues.

Property View – Allows you to view the attribute specific properties.

History View – Allows you to view the attribute modified information.

In the data view tab you have a number of options available:

1 You can view the data value in different units of measure by selectingdifferent units of measure from the drop down list in the “UnitMeasurement Selection” section.

The data value changes automatically to represent the selection made.This is only possible when the “Edit Attribute Data” check box is notchecked.

2 If you check the “Edit Attribute Data” check box, you can edit the datavalue and set the descriptive test information for the attribute. Once thecheck box is checked the units of measure no longer alter the data valueon selection.

If you make changes on this tab they are saved to the workspace whenthe dialog is confirmed. The descriptive text options displayed in the dropdown lists indicate the currently recognized options available that areloaded on the server.

11 Explorer 183

Customizing Case SettingsThe case columns displayed in an attribute view by default show all of thecases that apply to the object in question. It may be that you want tocompare some specific cases across a number of different attribute views. Inthis scenario you can override the default case settings and configure thecases that will be visible in the attribute views by customizing the casesettings for their Explorer application.

These case configurations when made are stored on the particular clientmachine and will only affect the views for the particular workspace you areusing at the time. The changes are persisted between login sessions.

To specify the case columns displayed in the attribute views:

1 In the Explorer window, click View | Case Settings.

2 The Case Settings dialog is displayed which allows you to choose:

o A checkbox to show all cases.

o A list of all cases (global and restricted) which shows the user’spreference order whether displaying all cases or just a few.

o A check box against each case to indicate if it should always bedisplayed (i.e. when the “Show All Cases” option is unchecked).

184 11 Explorer

3 Uncheck “Show All Cases”, select the cases to display their order andconfirm the dialog. The system records the settings and applies them toany open attribute views. If the case selection does not include thegoverning case then it will not be shown. The governing case now appearsin a selected position rather than being automatically put at the start as itis when “Show All Cases” is checked.

4 You can now open up other attribute views for other objects in theworkspace. The system displays the attributes of the object for only thecases selected in the dialog.

If the case selection includes a restricted case that is not applicable for theobject being viewed then the column for the restricted case is not displayed.The system writes out to you the names of any non-applicable cases that arehidden in a text box at the top of the attributes view.

If you have previously configured the case view settings, checked the “ShowAll Cases” option and confirmed the dialog, the system retains thepreferences but refreshes all attributes views in the current client to displayall applicable cases for the object being viewed.

When you open new attribute views for other objects in the workspace thesystem displays the attributes of the object for all cases of the object in theorder selected in the Case Settings dialog.

Default Object ClassviewsThe Explorer can be configured to display a specific classview’s attributes bydefault when an object of a particular class is selected.

You will know when you are looking at a default classview because it isindicated in the status bar.

Selecting the Object | Select Classview menu option gives you the optionof either selecting a different class view or selecting the Attribute View optionwhich returns you to the default attribute collection for that object.

Default Classview definitions are configured using the Meta data propertyavailable in the datamodel via the Class Library Editor application.

To view the class properties dialog:

1 Select the Class in the navigation pane on the left hand side.

2 Right-click to display the context menu, then select Properties.

3 Select the Custom Properties button in the left hand corner.

4 Set the property to “DefaultClassView”. This is the property name theExplorer client uses to locate the class view definition.

5 Set the value to be the classview’s name you want to display by default:

11 Explorer 185

PackagesPackages, also called Modular Designs, are sections of a workspace that havebeen saved externally in an XML format. They can be used to transfer databetween workspaces and to preserve sections of a plant as modules. Tocreate a package, select an object to export from one of the Explorer windowsand select the Export Package menu option. This displays the Export Packagedialog from where you can specify the name of the file to be exported.

As well as the selected object, related objects are also exported:

Datasheets export the datasheet document and all objects that appear onit.

Drawings also export the document and all objects that appear on it. Theconnectivity between items in the package is also exported.

Folders export all objects contained in that folder.

Bridges export all the items that make up that Bridge definition. They donot however export the object that is referenced by the linksets. If youwant these objects to be exported as part of the Bridge you should put thebridge and the linked objects in a folder and export that folder.

To import a Package select a folder from one of the Explorer windows andthen select the Import Package menu option. This displays the ImportPackage dialog from where you can specify the name of the file to beimported. All items in the Package are imported into the selected folder.During import, the case names in the Package file are matched against thecase names in the current workspace. If new cases are found then they arecreated. All objects in the package are created as new objects in theWorkspace.

Note: Data from the Global class is not imported.

Exporting a PackageSelect the Folder | Export Package menu option to display the ExportPackage dialog. This allows you to specify the package file name and toenter descriptive data about the contents of the package file. The selectedobject can then be exported as a Package.

186 11 Explorer

Importing a PackageSelect the Folder | Import Package menu option to display the ImportPackage dialog. Use this dialog to specify the Package you wish to import. Itdisplays a file name and other data that will help to describe and identify thepackage file. You can enter a Title, Description, Category and a Purpose.These just enable you to describe the package and are not used by AspenBasic Engineering.

Packages FolderPackage files may be placed in the folder defined by the PACKAGESparameter in the workspaces config. file. To use this file press the Librarybutton. Alternatively you can specify the folder for your packages by pressingthe Browse button. You can see which folder is being used for the export orimport of the package files in the “Current Folder” box.

Query EditorThe Query Editor is used to send Ad-hoc queries to the workspace.

The queries are Visual Basic Scripts that can be typed in to the top half of thewindow or loaded from a file. The scripts have access to the same automationobjects and methods as a Rule in a KB script. In addition a Response object isexposed which supports a "Write" method. All the text written to theResponse object will appear in the bottom half of the window when the queryhas completed.

For example the following is a simple query to report the names anddescriptions of all pumps in the workspace:

'List all pumpsResponse.Write "Name"Response.NewlineResponse.Write "----"Response.Newline' Output name and description

For Each pump in ClassStore.FindClass("Pump").Members

Response.Write Pump.DisplayName & " " & Pump.Description

Response.NewlineNext

11 Explorer 187

When the submit button is pressed the output for the query is displayed inthe lower pane.

Alternatively the response can be modified to return html or xml as shown:

<HTML><TABLE><TR><TD> Name </TD><TD> Description </TD></TR><%'List all pumps

188 11 Explorer

For Each pump in ClassStore.FindClass("Pump").Members

Response.Write "<TR>"Response.NewlineResponse.Write "<TD>" & Pump.DisplayName & "</TD>"Response.NewlineResponse.Write "<TD>" & Pump.Description& "</TD>"Response.NewlineResponse.Write "</TR>"Response.Newline

Next%></TABLE>

Now if after you submit the query you choose the “View Response as WebPage” item from the view menu, the results are displayed as a web page.

Adding a QueryYou type your query into the top Query window using VBScript statements.When you press the submit button the query is copied to the Aspen BasicEngineering server where the script is interpreted and run on the servermachine. Each Response.Write statement in the query writes to the server’sresponse buffer. When the query completes its execution on the server, thecontents of the Response buffer are copied back to the Query Editor on yourclient machine and displayed in the bottom Response window.

11 Explorer 189

The Aspen Basic Engineering QueryLanguageThe Aspen Basic Engineering Query language uses VBScript. This help doesnot attempt to be a reference for how to use VBScript for which you shouldsee one of the many texts available or Microsoft’s web site. Instead it will justexplain those special considerations needed to use VBScript with Aspen BasicEngineering.

The Aspen Basic Engineering Query language has access to the objects in theAZDBQuery library. These are documented in the online Library ObjectReference listing, AZDBQuery.chm (see on-line help).

When you write a script you do not create the objects from the AZDBQuerydirectly. Instead four global objects are available. They are:

Name Class Name Description

Response AZQResponse Writes to the server’s text buffer which is returned atthe end of the call to the server

ClassStore AZQClassStore The VBScript object containing the definitions of thedata model classes and methods to access them andobjects of those classes

ObjectStore AZQObjectStore Provides methods for accessing all the Aspen BasicEngineering objects in the Aspen Basic Engineeringdatabase

Globals AZQGlobals Provides access to the datamodel definitions, that isclass definitions, attribute definitions class viewdefinitions etc

The full list is in the Library Object Reference.

Response is a reference to The Response Object.

You will frequently start a script by using the ClassStore global. One of itsmost useful methods is FindClass. This returns a COM object that representsthe Aspen Basic Engineering class. This is an AZQClass object. You could thenuse the Members property of the AZQClass object to loop through all theAspen Basic Engineering objects in a workspace that belong to the class youspecified in the FindClass method.

For example:

for each obj in ClassStore.FindClass("GenericClass").Members…next

Here FindClass(“GenericClass”) will find all Aspen Basic Engineering objectsthat are of GenericClass or whose class derives from GenericClass. If you lookat any class in the CLE you will see that ultimately it derives fromGenericClass, so the above example will loop through every item in theworkspace.

The obj variable holds an AZQObject object. Each of these automation objectscorresponds to an Aspen Basic Engineering object in the workspace such as apump or port. You can therefore use the methods of the AZQObject class toquery an Aspen Basic Engineering object. Typically you will want to examine

190 11 Explorer

an Aspen Basic Engineering object’s attributes which you can do with scriptlike:

for each ZyqadObject inClassStore.FindClass("GenericClass").Members

set ObjectsAttributes = ZyqadObject.Attributesnext

The attributes are again returned as an automation object. In this case, ofclass AZQAttributeCollection. This class supports an enumerator so that it canbe used in “for each” loops and an item property to allow individual attributesto be accessed.

E.g.:

set ObjectsAttributes = ZyqadObject.Attributesfor each Attr in ObjectsAttributes…next

or

set ObjectsAttributes = ZyqadObject.Attributesfor i = 1 to ObjectsAttributes.Count

set Attr = ObjectsAttributes(i) ‘ Item is the default property…next

Note that in both cases the Aspen Basic Engineering attribute is accessedthrough a class, this time called AZQAttribute (see Events).

Unless the Aspen Basic Engineering attribute contains another Aspen BasicEngineering workspace object or is a vector, the value of the attribute can beretrieved using the AZQAttribute’s Value property. So the attributes valuecould be displayed with:

response.write Attr.Value

For example, the following attempts to write all the attributes of the AspenBasic Engineering GlobalsClass.

Set ZyqadObject = ObjectStore.FindObject(1)Set ObjectsAttributes = ZyqadObject.AttributesFor i = 1 To ObjectsAttributes.Count

Set Attr = ObjectsAttributes(i) ' Item is the defaultproperty

response.write Attr.Valueresponse.Newline

Next

This example starts by using the ObjectStore global. One of its methodsallows you to retrieve an object by specifying its OID. Every object in theAspen Basic Engineering workspace has a unique Object Identifier or OID. Asthis is not engineering data it is not normally displayed to the user, although

11 Explorer 191

you can choose to display it in the Explorer. The above example takesadvantage of the fact that the GlobalsObject has an OID of 1.

However if you try to run this example it will almost certainly produce anerror such as “Invalid Index”. This is because some of the attributes arevectors and the Value method must supply the index for an array.

Therefore the script should be modified to print out each element of thearray, e.g.

For i = 1 To ObjectsAttributes.Count' Item is the default propertySet Attr = ObjectsAttributes(i)response.write Attr.DataTypeNameIf Attr.IsVector Then

For j = 1 To attr.Countset v = attr.Val(i)response.write Attr.Valueresponse.Newline

NextElse

response.write Attr.Valueresponse.Newline

End If

The IsVector property returns true if the attribute is a vector. But thisexample may still not work because the value returned for an attribute couldbe another object or not set. Neither of these can be written to the responsebuffer which is expecting a string variable. Therefore an error will beproduced. So the example must guard against these:

Set ZyqadObject = ObjectStore.FindObject(1)Set ObjectsAttributes = ZyqadObject.AttributesFor i = 1 To ObjectsAttributes.Count

Set Attr = ObjectsAttributes(i) ' Item is the defaultproperty

If attr.DataType <> azqDataTypeObject ThenIf Attr.IsVector Then

For j = 1 To attr.CountIf attr.HasValue(j) Then

response.write Attr.DataTypeName & " "response.write Attr.Name & "( "response.write i & " ) "response.write Attr.Value( i)response.Newline

End IfNext

ElseIf attr.HasValue Then

response.write Attr.DataTypeName & " "response.write Attr.Name & " "response.write Attr.Valueresponse.Newline

End IfEnd If

End If

192 11 Explorer

Next

In the above example the type of each attribute is obtained by the DataTypeproperty. This is tested to check that an attribute does not represent anobject.

The HasValue property returns true if the attribute has a value. Note how anIndex is supplied to test if the element of a vector has a value. This examplecould be further refined to get the attributes of the intermediary objectswhich are currently ignored. Getting the attributes for an intermediary objectis just like getting them for the parent object. So in the example theintermediary object can be obtained with additions like:

If attr.DataType = azqDataTypeObject ThenSet IntermediaryObject = attr.Value‘ or value(index) for a vector

End if

IntermediaryObject is an AZObject just like ZyqadObject in the earlierexample.

Class ViewsAs well as getting all the attributes of an object you can get the attributes fora Class View. To do this you should get an AZQClassView automation objectrepresenting the ClassView you want. You do this by using the FindClassViewmethod on the ClassStore global object, in a similar way to which classes arefound using the FindClass method.

E.g.:

set API610ClassView = ClassStore.FindClassView("API610")

To use this ClassView for a particular Aspen Basic Engineering object youneed to get an object that represents the implementation of that ClassViewfor a particular Aspen Basic Engineering object.

For example:

set PumpClass = ClassStore.FindClass("CentrifugalPump")

for each pump in PumpClass.Members,

set ClassViewImplementation = pump.View(API610ClassView)next

ClassViewImplementation is an object of class AZQView. This class hasAttribute and Attributes properties in a similar way to an AZQObject andthese are used to get the attributes’ values.

11 Explorer 193

Units of measureValues are stored internally in Aspen Basic Engineering in SI units. If yousimply use the Value property of the AZQAttribute or AZQViewAttributeclasses you will get the SI value. Values can also be returned in other units.The Value properties can take an optional argument which is the units for thatattribute. If this is supplied then the value returned will be in those units.

For example:

Val = Attr.Value(1, “ft3/s”)

Will return a value in ft3/s for the first element in a vector. If the particularunits are not valid for that value then an error is raised.

To find out which units are valid for an attribute you need to get its attributedefinition. Both the AZQAttribute and AZQViewAttribute classes have a UOMproperty which will return the units string for the attribute. You must specifythe unit set.

For example:

UnitString = Attr.UOM(“US”) ‘ Attr can be AZQAttribute orAZQViewAttribute class

You can get the list of unit sets in the Aspen Basic Engineering class storewith the UOMSetNames property of the AZQClassStore class.

UOMSets = ClassStore.UOMSetNames

To get the capacity of a pump in all UOMs you could use a script containing:

UOMSets = ClassStore.UOMSetNames

Set PumpObject = ObjectStore.FindObject(8) ‘ 8 is the OID of this pump

For Each UOMSet in UOMSets

Response.write "UOMSet: " & UOMSetUOM = PumpObject.Capacity.UOM(UOMSet)Response.write " Units: " & UOM & " "Response.write Pump.Capacity.Value(UOM)Response.NewLine

Next

PumpObject.Capacity in the above example is an example of a dynamicproperty. See KB Dynamic Properties for more information. Note also thatPumpObject is an automation object and is assigned with the Set operator.UOM is a variant and is simply assigned.

All possible available units for an attribute can be found by examining anattribute’s physical quantity.

194 11 Explorer

For example:

‘Get the definition of the capacity attributeset AttDefn = Pump.Capacity.Definition‘Get the physical quantity for the attributeset QuantityType = AttDefn.QuantityType‘Get the UOMS for the quantity typeUOMS = QuantityType.ValidDisplayUOMResponse.write “The Pump‘s capacity is output using all availableunits”Response.NewLineFor each UOM in UOMS

Response.write Pump.Capacity.Value(UOM)Response.write “ “ & UOMResponse.NewLine

Next

CasesAll the values returned in the previous examples have used a default Case,called the governing case. Cases, like objects, are identified internally byAspen Basic Engineering with an integer ID, called the CaseID. If you wish toget the values for a particular case you need to call the Value property withthe optional CaseID argument.

For example:

Val = Att.Value(2, “m/s”)

See AZQObjectStore, under Events, for the properties useful when usingcases.

Cases Example

‘Get the governing case ID from the ObjectStore globalActID = ObjectStore.GoverningCase‘Get its nameActName = ObjectStore.CaseName(ActID)Response.Write “The current case is “ & Globals ActName‘ Get all casesAllCases = ObjectStore.GlobalCasesResponse.NewLine‘Write out how many there areNoCases = ubound(AllCases)Response.Write "There are " & NoCases & " Cases. "‘Write out each case’s nameFor Each CaseID in AllCases

Response.NewLineResponse.Write " " & ObjectStore.CaseName(CaseID)

Next

11 Explorer 195

Script to output the values for the pump capacity in each case could be

For Each CaseID in AllCasesResponse.NewLineResponse.Write “Value: “Set cap=pump.Attribute(“Capacity”,CaseID)Response.write cap.Value(“m^3/h”)Response.Write “Case: “Response.Write " " & ObjectStore.CaseName(CaseID)

Next

The Response ObjectThe Query Editor supports the Response global object. This is actually aninstance of the AZQResponse class. It is used for building up a text string, orresponse buffer on the server which is returned to the client when the scripthas completed. It is the server’s response to the client.

Its two most frequently used methods for writing queries are the Write andNewLine methods. But it also contains some methods that allow the responseto be written more easily in an XML format.

Some of the most useful methods of AZQResponse are:

Method Description

Write (string) Writes the string into the response buffer

NewLine Writes a NewLine character into the response buffer

StartXMLDocument Starts an XML document (adds the header)

EndXMLDOcument Completes the XML document started withStartXMLDocuemt

StartElement Writes an open XML element to the response buffer

EndElement Closes the element opened by WriteElement

WriteElement Writes a complete XML element to the buffer

NewAttributeSet Returns a new AZQXMLAttributeSet object

The methods of AZQXMLAttributeSet are:

Method Description

Add (attr, value) Creates an XML attribute of the form attr=value

Clear Clears all attributes from this set

196 11 Explorer

Example of Creating XML

response.StartXMLDocument()'create the attributes for the first elementset attr = Response.NewAttributeSetattr.Add "AnAttribute", "abc"'start the first element using the above attributesResponse.StartElement "First" , attr'reuse the attributes object for the next (child) elementattr.Clearattr.Add "AValue", TrueResponse.WriteElement "child1", attrResponse.WriteElement "child2", Nothing, "some data"'End the first elementResponse.EndElementresponse.EndXMLDocument

This will produce the output<?xml version="1.0"?><First AnAttribute="abc">

<child1 AValue="1"/><child2>some data</child2>

</First>

which can be viewed directly as a web page by choosing “View response as aweb page” from the view menu.

As well as using the Response object, text can also be written directly to theresponse buffer by placing it outside of the scripts. To do this you need toenclose your scripts with <% and %> symbols. Then anything outside ofthese is written into the response buffer. If your query only consists of ascript then these symbols can be omitted as with most of the examples.

Class View Example

This example lists the attributes in the API610 class for all centrifugal pumps.It formats the response into HTML so that it can be viewed as a web page.

It illustrates writing text directly to the response buffer, using class views andalso shows how to get the attributes for an object that contains intermediaryobjects.

<HTML><% 'needed because the query contains non scripting textsub ReportOnView(view, prefix)

'writes out all the attributes in the class view. If anattribute is an object then this function is called again

For Each attr in view.attributes'this routine calls itself, a prefix is added each time inif prefix = "" then

newprefix = attr.Nameelse

newprefix = prefix & "." & attr.Nameend if

'Test if the attribute contains an object

11 Explorer 197

if attr.DataType = azqDataTypeObject then'Test if it is a vectorif attr.IsVector then

For i = 1 To attr.Count'handle the error from missing valueson error resume nextset v = nothingset v = attr.Val(i)‘Clear the error code and raise errors againErr.ClearOn Error goto 0

If Not v Is Nothing Then' v is the class view instance for the intermediary

object.ReportOnView v, newprefix & "(" & i & ")"

End IfSet v = Nothing

NextElse ' scalar

on error resume nextset v = nothingset v = attr.ValErr.Clearon error goto 0If Not v Is Nothing Then

ReportOnView v, newprefixend if

end ifElse ' not an intermediary

if attr.IsVector thenFor j = 1 To attr.Count

Response.Write "<TR>"Response.NewlineResponse.Write "<TD>" & newprefix & "</TD>"Response.Newline

On Error Resume NextIf attr.HasValue(j) Then

Response.Write "<TD>" & attr.Value(i) & "</TD>"Else

Response.Write "<TD>" & "not set" & "</TD>"End IfErr.ClearOn Error goto 0Response.NewlineResponse.Write "</TR>"

NextElse

Response.Write "<TR>"Response.NewlineResponse.Write "<TD>" & newprefix & "</TD>"Response.Newline

on error resume nextif attr.HasValue then

Response.Write "<TD>" & attr.Value & "</TD>"else

Response.Write "<TD>" & "not set" & "</TD>"end if

198 11 Explorer

Err.Clearon error goto 0Response.NewlineResponse.Write "</TR>"

end ifend if

next

end sub

'close this piece of script so that more literal text can be written

%>

<TABLE>

<TR>

<TD> Route </TD>

<TD> Value </TD>

</TR>

<% ' next script

'Get the pump class

set c = ClassStore.FindClass("CentrifugalPump")

'Get the class view we want to report on

Set cv = ClassStore.FindClassView("API610")

'loop through all pumps

For Each o in c.Members

' get the class view instance for each pump

Set v = o.View(cv )

' call the subroutine defined above

ReportOnView v, ""

Next

%>

</TABLE>

11 Explorer 199

Query Editor Menus and OptionsThe Query Editor has the following menus and options:

File Menu

The File menu contains the following commands:

Command Action

Open Query Allows you to navigate to and open an AZ Script (.azq format) queryfile

Close Query Allows you to save the current query file (in .azq format) under anew name

CloseWindow

Closes the Query Editor window

View Menu

The Edit menu contains the following commands:

Command Action

View Response as WebPage

Allows you to view the response as a Web page (HTMLformat)

Submit button

The Submit button has the following effect:

Command Action

Click Submit Submits the current query

Asynchronously checkbox

The Asynchronously checkbox has the following effect:

Command Action

Unchecked The application waits until the submitted request is returned

Checked Returns the submitted request immediately

In addition the edit window supports these accelerator keys

Ctrl-C Copy.

Ctrl-X Cut.

Ctrl-V Paste.

Ctrl-A Select All.

Ctrl-Y Redo last action (following Undo).

Ctrl-Z Undo last action.

200 11 Explorer

Logging on to Workspaces andProjectsNote: Before attempting to log on to a Workspace or Project, ensure youhave a valid username and password for the item(s) you wish to connect to,or obtain one from your Administrator.The Open Workspace menu/toolbar option is only active if noWorkspace/Project is currently open.

Logging on to a PreferredWorkspace/Project1 In the Explorer window, click File | Open Workspace to open the Open

Workspace dialog:

2 In the Workspace/Project Name field, select the name of a preferredWorkspace/Project from the list displayed.

3 Click Open to log on to the selected Workspace/Project and close theOpen Workspace dialog.

11 Explorer 201

Logging on to a User SpecifiedWorkspace/Project1 In the Explorer window, click File | Open Workspace to open the Open

Workspace dialog.

2 Click Browse to open the Select Workspace or Project dialog.

3 Navigate through the tree view of Workspaces/Projects and selectrequired Workspace/Project.

Note: If you do not have access rights to log on to a Workspace orProject, the title is grayed out.

4 Click OK to add the Workspace/Project to the list of preferred items in theOpen Workspace dialog.

5 Select the Workspace/Project from the list of preferred items in the OpenWorkspace dialog and click Open to log on to the selectedWorkspace/Project and close the Open Workspace dialog.

Logging on to a Workspace/Project via aURL Address1 In the Workspace/Project field, type the URL and name of a known

Workspace/Project.


Connecting as a Different User

Note: Please ensure you have permission from your supervisor beforeconnecting to a Workspace/Project as a different user.

To log on to a Workspace/Project as a different user:

1 In the Explorer window, click File | Open Workspace to open the OpenWorkspace dialog.

2 Select the Connect as a different user link to open the Connect Asdialog.

3 Enter a valid username in the Connect As field and the password in thePassword field.

4 Select/deselect the option to use the new username and password bydefault in the future, as required.

5 Click OK to enter the new details and close the dialog.

202 11 Explorer

Change Advanced Connection SettingsThis option allows you to specify the name of the server to connect to and theprotocol to be used for authentication.

To change advanced connection settings:

1 In the Open Workspace dialog click the Change advanced connectionsettings link to open the Advanced Connection Settings dialog.

2 Enter (type) the required server name in the Server Name field.

3 Select the required authentication protocol from the drop-down list in theAuthentication Protocol field.

4 Select/deselect the option to use these settings by default in the future,as required.

5 Click OK to enter the new details, close the dialog and retain the settings,or Cancel to close the dialog without saving the settings.

Invalid Username/PasswordIf you open the Open Workspace dialog and attempt to log on to aWorkspace/Project using an invalid username and/or password (i.e., you donot have authority to connect to the selected Workspace/Project, but yourusername and password are valid for other Workspaces/Projects), the Log-OnError dialog is displayed warning that you do not have access to the selectedWorkspace:

1 Click the OK button to close the dialog and return to the Open Workspacedialog:

11 Explorer 203

2 Select a Workspace/Project you are authorized to use and click OK, orclick the Connect as a different user link to log on using anotheridentity.Alternatively, click Cancel to abort the operation.

Incorrect Username/PasswordIf you open the Open Workspace dialog, then the Connect As dialog and enteran incorrect username and/or password, the Log-On Error dialog is displayedwarning that your user name and/or password is invalid:

1 Click OK to close the dialog and return to the Connect As dialog:

2 Enter your correct user name and password to access the selectedWorkspace.

204 11 Explorer

Invalid Business ServerIf an unknown business server is specified in the Advanced ConnectionSettings dialog, the LogOn Error dialog is displayed stating that the requestedserver cannot be found:

1 Click OK to close the dialog and return to the Advanced ConnectionSettings dialog.

2 Enter the correct server name (and Authentication Protocol option) toaccess the selected Workspace.

11 Explorer 205

Invalid Authentication ProtocolIf you attempt to log on to a Workspace/Project using an authenticationprotocol not supported on the local domain, the LogOn Error dialog isdisplayed indicating that the particular authentication protocol requested wasnot recognized:

1 Click OK to close the dialog and return to the Advanced ConnectionSettings dialog:

2 Enter the Authentication Protocol option to access the selectedWorkspace/Project.

3 Click Open to log on to the selected Workspace/Project.

206 11 Explorer

Invalid Workspace/Project NameIf you attempt to log on to a Workspace/Project using an invalid or unknownname (or the system cannot find the specified item) the LogOn Error dialog isdisplayed indicating that the system cannot connect to the specifiedWorkspace/Project.

1 Click OK to close the dialog and return to the Open Workspace dialog:

2 Reselect the Workspace/Project name.

3 Click OK to connect to the selected Workspace/Project.

Closing the WorkspaceTo close the Workspace:

1 In the Explorer window click File | Close Workspace to close thecurrently open Workspace/Project.

Managing Workspaces

Privileges, Roles and UsersAspen Basic Engineering check uses a Privilege/Role/User model to controlaccess to resources.

11 Explorer 207

Privilege: A specific right that the system tests to determine if an actioncan be performed. For example, ‘Read’ privilege is tested before readaccess to an object is granted.

Role: A collection of privilege assignments that define the rights of aparticular type of user. For example, the Owner role defines the rights anowner of the Workspace has.

User: A user is an individual that has access to the Workspace and may begranted one or more roles.

For a Role each Privilege may be granted, denied or left unspecified, using theWorkspace Explorer it is possible to change the Privileges that a Role has on aper-object basis.

A user may also be a Windows group in which case all members of that groupshare the Roles assigned to the group. The Roles a user has through groupmembership are referred to as “implicit” Roles whereas Roles assigneddirectly to a User are referred to as “explicit” Roles.

Whether a user has a privilege is determined by applying the following rulesin sequence:

1 An explicit Role for the User is granted the Privilege on the object:

The User is granted the privilege

2 An explicit Role for the User is denied the Privilege on the object:

The User is denied the privilege

3 An implicit Role for the User is granted the Privilege on the object:


4 An implicit Role for the User is denied the Privilege on the object:


5 An explicit Role for the User is granted the Privilege globally:


6 An explicit Role for the User is denied the Privilege globally:


7 An implicit Role for the User is granted the Privilege globally:


8 An implicit Role for the User is denied the Privilege globally:


9 No Role the user has specifies a state for the Privilege:


General Privileges

Administrator: This privilege is checked when a user tries to add/modify theRoles and Users for a Workspace or an Object in the Workspace.

Object Privileges

Read: This privilege is required to be able to view the data of an object. Notethat if Write privilege has been granted then the system treats Read privilegeas being implicitly granted.

208 11 Explorer

Write: This privilege is required to be able to modify data for an object.

Attribute Privileges

Lock Attribute: The privilege required to be able to Lock an attribute.

Override Attribute Lock: If the user has this privilege then they canoverride a Lock that has been placed on an attribute.

Secure Attribute: The privilege required to secure an attribute and to view asecured attribute.

Discipline Privileges

TrespassDiscipline: If this privilege is granted then the User does not haveto be granted the Discipline specific Modify privilege to change attributes.

Modify_Discipline_Data: If TrespassDiscipline is not granted and theattribute has a specific Discipline then the privilege must be granted tochange the attribute.

Document Privileges

Issue Document: A user must have this privilege to be allowed to issue adocument (i.e., a datasheet or a diagram).

Check Document: A user must have this privilege to be allowed to check adocument.

Drawing Editor Privileges

Author Drawing: The privilege required to create and edit a drawing (otherthan mark-up).

View Drawing: The privilege required to view a drawing.

Markup Drawing: The privilege required to apply mark-up to a drawing.

Export Drawing: The privilege required to be able to export a drawing.

11 Explorer 209

Bridge Privileges

Bridge User: The privilege required to open and run a Bridge.

Bridge Definer: The privilege required to create and design a Bridge.

Workspace ComponentsThe example below shows a typical installation, including the exampleWorkspace az13x.

C:\AspenZyqadServer\BasicEngineering13x\

WorkspaceLibraries/

LibrarySets.lst – A file list the default library sets available when creating aworkspace.

StandardLibrarySet.cfg and or TEFLibrarySet.cfg – The configuration settingfor workspaces using the “Standard” or “TEF” library set.

ClassLibraries/

*.azcs – Files containing compiled sets of class and view, composite view,enumerations and UOM definitions. Delivered .azcs files should not be editedand can be extended with the Class View Editor.

KBs/

*.azkbs – The script files for rules and methods.

*.azkbx – The compiled form of the above files.

Symbols/

The tree of drawing symbols accessed by the Drawing Editor.

Templates/

The collection of Datasheet and Label template files.

Workspaces

Workspaces.lst - A file listing the names and locations of the Workspaces thatcan be accessed on the computer.

PeerBrokers.lst – A file listing the other Data servers that can be accessedfrom this machine if it is used as a Business Server.

AZ13x/

The working directory for the example AZ13x workspace.

Workspace.cfg – The configuration settings for the workspace.

Privileges.xml – The user and roles for this workspace.

Workspace.mdb – the Access database that store the object data (when usingAccess)

Workspace.udl – the RDB connection configuration file. Never copy this toanother workspace directory.

210 11 Explorer

Configuration Management

Configuration Files

Configuration settings are used to control a number of aspects of Workspacebehavior, for example:

What Class Store is to be loaded and therefore what classes and classviews are available.

Which directory to look in for Templates, which governs which datasheetswill be available for the Datasheet Editor and what labels will be availablefor the Drawing Editor.

Which directory to look in for KB scripts and which KB scripts to load.

In Aspen Basic Engineering, configuration settings may be defined in one oftwo places:

In the Workspace.cfg of the Workspace. This is always located in theworking directory of the Workspace

Or, in a ‘library set’ cfg file, typically located in the WorkspaceLibrariesdirectory (e.g., StandardLibrarySet.cfg or TEFLibrarySet.cfg).

Library sets allow an Administrator to create predefined sets of configurationoptions that correspond to the requirements of different projects. The list ofavailable library sets is recorded in the LibrarySets.lst file which containslines in the following format:

LIBRARY “Standard” “StandardLibrarySet.cfg” “The standardlibrary”

Note: The ‘#’ character can be used to prefix lines which are for comments.

When the user creates a Workspace using the wizard in the AdministrationTool one of the required options is the Library Set to use. The user mustchoose a set that is listed in the LibrarySet.lst file.

When the workspace is created the choice of library set is written to thatWorkspaces Workspace.cfg file with a line of the form:

LibrarySet = “Standard”

When a LibrarySet is defined for a workspace the configuration filecorresponding to that file is loaded and its setting merged with thosecontained the Workspace.cfg file. Settings in the Workspace.cfg file takeprecedence over those in the library set.

Note: LibrarySet and all other configuration parameters can only hold asingle value. If a parameter is defined twice it is the last definition used.

Where a configuration parameter is a file location, relative paths may beused. The path will be resolved with respect to the location of theconfiguration file.

11 Explorer 211

Configuration Parameters

Configuration parameters are added with software updates. The correct andup-to-date list of parameters is available from the Administration Tool on-linehelp.

Configuring the Symbol Library Path

UNC Paths

The symbol library path must refer to the same directory for all clientmachines using the workgroup, so you need to use a U(niversal) N(aming)C(onvention) path to identify the directory if the workgroup is to be accessedfrom more than one client machine.

A UNC path describes the path to a directory that is the same for all clients onthe network. Its format is:

\\<machine>\<share name>\<directory path>

The elements of the syntax are:

<machine> – This is the network name/address of the machine holdingthe directory.

<share name> – This is the name of the share on the machine.

<directory path> – This identifies the directory.

Defining a Network Share

You define a network share from Windows Explorer, as follows:

1 Select the folder that you want to share. For the standard installation, thisis:

C:\AspenZyqadServer\Basic Engineering16.1\WorkspaceLibraries

2 From the File menu, click Properties and go to the Sharing tab.You can also do this from the right-click menu.

3 Enable the Shared As radio button.

4 Type in a share name and set the User Limit and Permissions.

Tip: All users of the client machines must have at least read access to theshare and to the symbol library. Aspen Basic Engineering PFD accesses theshare using the permissions of the users' current login account on the clientmachine, not the login account on the Aspen Basic Engineering server, so youmust account for this when defining permissions for the share.

212 11 Explorer

Troubleshooting SymbolLibrary Path

These tips help you troubleshoot problems with the symbol library path:

Path name is incorrect in the Server configuration file:

Check that the symbol path name in the server configuration file matches themachine name, share name and path on the server.

Name Translation Problems:

With an incorrectly configured WINS server, the client cannot translate 'short'server machine names in the UNC path, to IP addresses. For example,\\ServerMachine\Library would not work because there is no translation forServerMachine in the client domain.

The simplest way to test for this problem is through Windows Explorer. If theproblem is present, the Map Network Drive command responds with the"Network Path Not Found" error. Alternatively, you can test name translationusing the ping command.

It is difficult to configure WINS, here are some recommendations:

Substitute the 'long' (fully qualified domain) name of the server machinein the symbol library path. For example,\\ServerMachine.subnet.domain.com\Library\Symbolswill use the DNS lookup.

Alternatively:

Substitute the IP address of the server machine in the symbol path (forexample, \\00.00.00.00\Library\Symbols. This may be necessary if theDNS server has no translation for the long name.

-or-

Update the lmhost table on the client machine.

Domain Security:

There may be issues relating to security policy on the domains, thepermissions granted to the client login account, and the nature of thepermissions applied to the share.

The simplest way to investigate problems with security is to use WindowsExplorer from the client account that is experiencing the difficulty. Wheninvestigating, you will also want to know what domain/account the client isusing (press CTRL-ALT-DEL to display the security dialog).

From Windows Explorer, use the Map Network Drive command to map to theshare name on the UNC path. This should give error dialogs that describe thesecurity issue. Note that, when using Map Network drive, do not specify anaccount in the Connect As field; leave this blank in order to use the currentlogin account, as this is what our software will use.

A brief summary of the security requirements between the domains would be:

Server domain must 'trust' the client domain/username.

Server must allow network logins by the client domain/username.

Share must allow appropriate read/write access by everyone, or by theclient domain/username.

11 Explorer 213

Configuring Descriptive Text Options

Descriptive text is a facility that allows users to enter text into numeric fields.Three categories of Descriptive text are supported Prefixes, Postfixes andSubstitutions. The valid values for each category are defined in a text file. Thedefault file is “WorkspaceLibraries\ClassLibraries\DescriptiveText.txt”.

An example of its format is:

[PrefixText] The list of Prefix options start hereAt leastGreater thanNo more than

[PostfixText] The list of Postfix options start hereand higherand lower

[SubstitutionText] The list of Substitution options start hereTraceManufacture Recommendation

This file can be edited in a plain text editor. Note also that new entries orflexibility are added to descriptive text during software updates. Check theAdministration Tool on-line help for more information and check the deliveredDescriptiveText.txt. A software update will not update this file if you havemodified it.

Configuring the Stockpile View Tabs of theDrawing Editor

The stockpile view in the Drawing Editor provides a means for viewingexisting objects in the Workspace according to different organizations. TheViews available in the Stockpile are defined using an XML file that is specifiedby the configuration parameter “StockpileViewTabs”. The default file is“WorkspaceLibraries\ClassLibraries\StockpileViewTabs.xml”

The basic structure of the file is as follows:

<StockpileViewTabs> Start of the list of Views

<DrawingItemView Name="ByObject"> Start of a View called ByObject

<View Name="All Plant"> Start of a tab for this view

<FilterClass Name="SizeReductionEquipment"/> Name of a class of object to include in the view

</View> End of the list of classes for the current tab

<View Name="..."> Start of the View’s Second Tab...

</View>

</DrawingItemView> End of the ByObject View Definition

</StockpileViewTabs> End of list of Views

214 11 Explorer

Broker ConfigurationThe configuration of the Broker and Broker Service Account are liable tochange subsequent to changes delivered by Microsoft Operating SystemService Packs. For example significant changes have been made toaccommodate XP Service Pack 2 and Windows Server 2003 Service Pack 1due to shifts in DCOM security.

For this reason, up-to-date information is maintained in the AdministrationTool on-line help and is liable to change during software updates. Pleaseconsult the detailed help available.

Configuring the Broker to SupportAutomated Creation of Oracle RDBsTo allow the “Create Default Oracle Workspace” option in the CreateWorkspace Wizard to work, the Broker.ini file must be manually edited toinclude the following settings:

OracleServiceName: Set this to the name of the default Oracle instance touse, as registered with the Oracle Listener service.

OracleUserName: This is the username that the Aspen Basic EngineeringBroker service will use to connect to oracle when creating a newworkspace.

OraclePassword: The password for the above account, unless nativewindows authentication is being used.

OracleTablespaceSize: The default size of the Tablespace that will becreated in Oracle for the Workspace.

The Oracle User Name given must have sufficient privileges to be able tocreate Tablespaces and Users in Oracle and to query for existing Tablespacesand Users.

In addition the oracle parameter “db_create_file_dest” (based on Oracle 9i)must have also been set. (We recommend this parameter is set to a non-

default value to prevent the setting being lost when Oracle is restarted.)

11 Explorer 215

Setting the oracle “db_create_file_dest”parameter:1 Launch the Oracle Enterprise Manager Console.

2 In the tree control on the left hand side navigate down to the chosenOracle instance.

3 Right-click on this node to get the context menu and select View | EditDetails…

4 On the General tab click the All initialization parameters… button.

5 Scroll down the table to the db_create_file_dest row (this is in the “FileConfiguration” category).

6 In the Value column enter the directory location where oracle data filesshould be created by default.

7 If you are using an SPFile - make sure that you save the"db_create_file_dest" value in both the Running and the SPFile.

The default actions taken for Oracle are:

1 A new Tablespace is created in Oracle based on the Workspace name plusan integer postfix to resolve name collisions.

2 A new User is created in Oracle with the same name as the Tablespace,the new user’s default Tablespace is the new Tablespace.

3 The new User is explicitly granted Connect and Resource privileges.

Note: If you get an error message that the db_create_file_dest is not set,follow the procedure outlined below.

1 Log into OEM (Oracle Enterprise Manager) with sysdba rights.

2 Go into Storage/Tabelspaces and pick an Aspen Basic Engineering table.

3 Highlight the file directory and copy it.

4 Go into Instance | Configuration.

5 Click on the All Initialization Parameters... button.

6 While Running is selected, paste the file directory into thedb_create_file_dest value.

7 Click Apply (this changes the running instance).

8 Then change from Running to SPFile.

9 Scroll down to the db_create_file_dest value and paste in the value for thefile directory.

10 Click Apply (now it is saved for the next time you start up the Oracledatabase).

You can also make this change in SQLPlus - you have to do "create pfile fromspfile". (This places the file into the default "dba" directory.)

1 Edit the "init<sid>.ora" file that is generated, then select create spfilefrom pfile.

2 Restart the database to complete the operation.

216 11 Explorer

Setting up Aspen Basic Engineering to Auto-Create Oracle Workspaces in the AdministrationApplication

Create an Oracle User e.g. “XYZ”

1 Create a user in the Oracle enterprise Manager Console

2 Set the password e.g. “XYZ”

3 Grant the user the following roles (need ADMIN option):

4 Grant the user the following system Privileges:

Configure the Oracle database:

1 Launch the Oracle Enterprise Manager Console.

2 Select your database name under the ‘Databases’ .node. Right click andselect View/Edit details.

3 On the General tab select the All Initialization Parameters button.

4 Set the property db_create_file_dest to the directory below whichOracle stores the data files e.g. C:\oracle\oradata.

Configure the Aspen Basic Engineering Broker:

1 Open the Broker.ini file (C:\Program Files\AspenTech\Aspen BasicEngineering\DataServices\bin).

2 Add/Edit the following section:

OracleServiceName= "felim"

OracleUserName= "XYZ"

OraclePassword= "XYZ "

OracleTablespaceSize= "20M"

where the OracleServiceName is the Oarcle service name for the database.This can be viewed/set in the Oracle Net Manager application (under theService Naming node) on the Aspen Basic Engineering server machine.

Configuring the Broker to SupportAutomated Creation of SQL Server RDBsTo allow the “Create Default SQL Server Workspace” option in the CreateWorkspace Wizard to work, the Broker.ini file must be manually edited toinclude the following settings:

11 Explorer 217

SQLServerName: Set this to the name of the default SQL Server to beused.

SQLServerAdminUserName: Set this to the user name to use to connectto the SQL Server instance.

SQLServerAdminPassword: The password for the Admin account above.

SQLServerDatabaseUserName: The default user name to be used by theWorkspace server when connecting to SQL Server.

SQLServerDatabasePassword: The password for the above user name.

If the SQL Server instance has native Windows authentication enabled thenthe last four parameters can be omitted provided the user account of theBroker service has been given access to the SQL Server instance.

Configuring an Oracle RDB Manually for anAspen Basic Engineering WorkspaceThe key requirement when configuring an Oracle RDB manually is that eachWorkspace is mapped to a unique Oracle User. It is also recommended thateach Oracle User is assigned a separate permanent and temporaryTablespace.

Creating an Oracle based Workspace called “Test”1 Launch the Oracle 9i Enterprise Manager and log on the Oracle Database

to be used.

2 Create a Permanent Tablespace “ZTest”:

o Navigate to Storage | Tablespaces on the tree view.

o Right mouse click on the Tablespaces node and select Create.

o In the Create Tablespace dialog enter “ZTest” for the name and makesure that in the Type section that the Permanent option is checked.

o Click Create.

3 Create a Temporary Tablespace “ZTestTemp”:

o Navigate to Storage | Tablespaces on the tree view.

o Right mouse click on the Tablespaces node and select Create in theCreate Tablespace dialog. Enter “ZTest” for the name and in the Typesection ensure the “Temporary” option is checked (do not check “Setas Default Temporary Tablespace”).

o Click Create.

4 Create an Oracle User “ZTest”:

o Navigate to Security | Users on the tree view.

o Right mouse click on the Users node and select Create.

o In the Create User dialog enter “ZTest” for the name.

o Enter and keep a record of the password.

o In the Tables spaces section for Default select the permanentTablespace created in step 2 (i.e., ZTest) and for Temporary select thetemporary Tablespace created in step 3 (i.e., ZTestTemp).

218 11 Explorer

o On the Roles tab, ensure both the Connect and Resource options areadded to the granted roles, and (recommended) on the SystemPrivileges tab specify the Unlimited Tablespace option is added tothe granted roles.

o Click Create.

5 Create the Workspace using the Aspen Basic Engineering AdministrationTool:

o Launch the Aspen Basic Engineering Administration Tool.

o Start the Create Workspace command.

o Click Next.

o Fill in the general information and select Oracle as the database type.

o Click Next.

o Check the Create Manual Workspace option.

o Enter the name of the Oracle database to be used for the OracleServer. Enter the name of the Oracle User created at step 4 (i.e.,ZTest) for the Oracle Username and enter the password for the OracleUser in the Password field.

o Click Next.

o Click Finish.

Configuring a SQL Server RDB Manually foran Aspen Basic Engineering WorkspaceWith SQL Server it is a requirement that each Workspace is assigned aseparate database and that the Aspen Basic Engineering server is providedwith an account that has the following roles granted in the database:

db_ddladmin

db_datareader

db_datawriter

11 Explorer 219

Creating a SQL Server based Workspace called“Test”1 Set up the ZyqadAdministrators group as a recognized login in SQLServer

(this step need only be done once for each SQL Server Instance):

o Start the SQL Server Enterprise Manager.

o In the tree view open the SQL Server instance to be used and go tothe Security | Logins node.

o Right mouse click and select New Login.

o Enter the Name “ZyqadAdministrators”.

o Check the Window Authentication option and under domain selectthe local machine name.

o Click OK.

2 Create the SQL Server Database:

o Start the SQL Server Enterprise Manager.

o In the tree view open the SQL Server instance to be used and go tothe Databases node.

o Right mouse click and select New Database.

o Enter the name, e.g., “ZTest" and click OK.

o Under the new database select the Users Node theZyqadAdministrators user should be listed under. Right mouse clickand select Properties for ZyqadAdministrators.

o Make sure the roles db_ddladmin, db_datareader, and db_datawriterare checked.

o Click OK.

3 Create the Workspace:

o Launch the Aspen Basic Engineering Administration Tool.

o Start the Create Workspace wizard.

o Click Next.

o Fill in the general information and select SQL Server as the databasetype.

o Click Next.

o Check the Create Manual Workspace option.

o Enter the name of the SQL Server instance for SQL Server hostname,and the name of the Database created (e.g., ZTest) for DatabaseName. The Username and Password fields may be left blank asWindow authentication is being used.

o Click Next.

o Click Finish.

220 11 Explorer

Creating a Peer-to-Peer Network of BrokersYou can use the Administration tool to create a peer-to-peer network of DataServers allowing all Workspaces of all Data Servers in the network to beaccessed independently of the Data Server the user is connecting to.

To set up a peer-to-peer network:

1 Ensure you are logged on as a user with Aspen Basic EngineeringAdminister privilege.

2 Ensure the Broker Service Account is a domain account. A local account isnot sufficient to operate peer-to-peer brokers.

3 Start the Administration tool.

4 Right click the Aspen Basic Engineering Workspaces node to display thecontext menu.

5 Select Edit | Data Servers from the main menu.

6 A list of the current peer servers is displayed, allowing you to add andremove computers.

The list of peer servers for a computer is recorded in the file"PeerBrokers.lst", located in the same directory as the Workspaces list file(Workspaces.lst).

Projects within Aspen BasicEngineeringA project within Aspen Basic Engineering is an isolated piece of work whosechanges are only visible to users logged on to that Project. Projects typicallyare used for numerous purposes including:

Modifying an existing ‘as-built’ plant: Modifications can be made in aproject so the main design is unaffected. Once the modifications havebeen carried out to the physical plant then the project can then be‘committed’, at which point the changes will be applied to the maindesign.

Design alternatives: During a design, different topology options can becreated and analyzed, each in its own project. Once the preferred designalternative is identified then the corresponding project can be ‘committed’to the main design and the projects for the other alternatives discarded.

Segregating a design: A design can be broken up into a number ofsections, each section being a project, so that users would work on thesection(s) that they have been given access to. On completion of sectionsthe corresponding projects would be ‘committed’ to create a singlecontiguous design.

A project can be further broken-down into sub-projects, and those sub-projects can also be broken-down into sub-projects. Projects can beconsidered to exist within a workspace in a ‘Project Tree’ and there is no limitto the number of levels for the tree. Within a workspace there is 1 ‘Root’project at the top of the tree, typically the main design, and this exists by

11 Explorer 221

default. Every project, except the Root project, will have a project above it inthe tree i.e. its ‘Master’ project.

For workspaces to register to a Smartplant plant only one level of projectsbelow the root project is allowed.

Note: There may be multiple projects executing at the same time and each isindependent of the other. All projects share the same configuration settings,but may have different users, roles and privilege settings.

Managing ProjectsProjects within Aspen Basic Engineering are managed from the AZ Explorerapplication.

Before you can work on a Project, you must log on to it. You can log on todifferent Projects in different applications but an application can only belogged on to one project at one time. The project you are logged on to isdefined as the Active Project for that session.

Privilege Settings for ProjectsEach project can have independent privilege settings (its own lists of Usersand Roles). These lists can optionally be initialized from the list of its MasterProject when the Project is created.

Privileges Settings for Management of Projects comprise:

Create Project: A user must have this privilege in the Active Project tocreate a new sub-Project.

Update Project: A user must have this privilege in the Active Project to beable to update the Project from its Master.

Commit Project: A user must have this privilege in the Active Project andin the Master to be able to Commit the Active Project changes to theMaster. Having Commit Project privilege implicitly includes the UpdateProject privilege.

Delete Project: A user must have this privilege for a Project to delete theproject from its master.

Claim: A user can claim objects in a project.

Unclaim: A user can unclaim objects in a project.

222 11 Explorer

Logging On To a Project

Logging On To a Project for the First Time1 In any Aspen Basic Engineering end user application select File | Open

Workspace to open the Open Workspace dialog.

2 Click Browse to open the Select Workspace or Project dialog:

3 Navigate through the tree view of Workspaces/Projects and selectrequired Workspace/Project. Projects that the current user does not haveaccess to will be grayed out or hidden. A project will be grayed out if theuser doesn’t have access to that project but it does have access to one ofit’s sub-projects.

4 Click OK to add the Workspace/Project to the list of preferred items in theOpen Workspace dialog.

5 Select the Workspace/Project from the list of preferred items in the OpenWorkspace dialog and click Open to log on to the selectedWorkspace/Project and close the Open Workspace dialog.

11 Explorer 223

Logging on to a Previously Accessed Project

This procedure allows you to log on to a previously accessed project.

1 Launch any of the Aspen Basic Engineering end user applications andselect File | Open Workspace to open the Open Workspace dialog.

2 In the Workspace/Project Name field, select the name of a preferredWorkspace/Project from the list displayed.


Project Management DialogProjects are managed through the Project Management dialog in the AZExplorer application. This dialog allows management of activities such as:

Access to the current project.

Updating of the current project.

Creating, deleting, committing the current project’s sub-projects.

Viewing properties of the current project’s sub-projects.

To access the dialog, launch Basic Engineering Explorer and select Edit |Project Management. The options on this dialog allow you to create,update, commit, and delete sub-projects of the currently selected project.

224 11 Explorer

Creating a New Project

This procedure allows you to create a new project.

1 Select Edit | Project Management from the Explorer menu.

2 Click Create to open the New Project Details dialog:

3 Enter a sub-project name in the Name field and optionally, a descriptionof the sub-project in the Description field.

4 To copy Users (create a new project and copy all users from the parentproject as default users for the new project), check the Copy Users box.To copy Roles (create a new project and copy all roles from the parentproject as default roles for the new project), check the Copy Roles box.Alternatively, leave these boxes unchecked if you do not wish to copyUsers or Roles for the project, in which case the current user is added tothe project and to the role ‘owner’.

5 Click Create to create the new sub-project using the specifications set inthe New Project details dialog. A confirmation message is displayed if thecreation is successful:

6 Click OK to close the message.

11 Explorer 225

Creating a New Project

After logging onto a workspace in the Explorer, you can create a new project.You will have the choice of copying roles and/or users from the parent projectto the new project.

Note: You must have the ‘Create Project’ privilege in order to create aproject.

To create a project:

1 In Explorer select Edit Project Management. The ProjectManagement dialog appears showing the existing projects, if any.

2 Click Create.

The system determines from Smartplant which projects are available forcreation and presents a pull-down list of the projects.

226 11 Explorer

3 Select a project and click OK to confirm.

The system prompts you to specify whether roles and/or users should becopied from the parent to the new project.

4 Select the Create button to complete the project creation.

The system displays a confirmation dialog.

5 The new project will be listed as an available sub-project in the projectmanagement dialog:

11 Explorer 227

Updating a Project

In a Project, to be able to see changes that have occurred in its Master theProject must be updated. A link on the Project Management dialog indicateswhether or not the project’s master has changed and therefore an update ispossible.

To update a project:

1 In Explorer logon to the project that is to be updated and open theProject Management dialog Edit | Project Management.

2 A link is displayed at in the Manage Projects dialog advising if the masterproject has been changed.

If you select this link to initiate, an update report is produced which listsall the updates to be carried out as well as the conflicts that the user mustresolve. Refer to Conflict Resolution for more detail.

3 On examining the updates and resolving all the conflicts click OK toupdate the project and return to the Manage Projects dialog.

228 11 Explorer

Committing a Project

Before the changes in a Project can actually be committed to its Master anyconflicts must be resolved. This is done by performing an update, see above.If the update has not been carried out the commit will be prevented.

This procedure allows you to commit a sub-project to the database. (A usermust have this privilege in the Active Project and in the Master to be able toCommit the Active Project changes to the Master. Having Commit Projectprivilege implicitly includes the Update Project privilege.


2 Select a sub-project from the list displayed in the Sub-Projects column.

3 Click Commit. The system compares the project to its parent to confirmthe project is up to date with respect to its parent. If so, a message isdisplayed advising that the sub-project was committed successfully.

If the project is not up to date with respect to its parent, then the Commitbutton will be disabled. If the committal is accepted, the project iscommitted to its parent and the project is made read-only.

4 Click OK to close the message and return to the Manage Projects dialog.

Deleting a Project

When a project is finished or cancelled, you may want to delete it.

Note: To delete a Smartplant project, the Smartplant project status must beeither Finished or Cancelled, otherwise the ‘Delete’ button will be disabled.

This procedure allows you to select an existing sub-project and delete it fromthe database.


2 Select a sub-project from the list displayed in the Sub-Projects column.

3 Click Delete, the Delete Project Confirmation message is displayedallowing you to continue with the deletion, or cancel and return to theManage Projects dialog:

4 If you want to delete the sub-project click OK.

11 Explorer 229

Conflict Resolution (Manage Conflict)Before the changes made in a Project can be committed to its Master anychanges made in the master must be applied to the project i.e. the projectmust be ‘Updated’. Conflicts between the project and the master will exist ifthe same item has changed in both. As part of the project update process theuser is asked to resolve any conflicts that exist.

Cases

Case Deleted in the Master but still Exists in theProject

A case existing in the project but not in the Master does not necessarily meanthat the case was created in the project. The original case may have beendeleted from the Master project.

If the Project has modified values in the now deleted case there are twopossible resolutions:

Re-instate the case (in which case conflict resolution occurs).

Delete the case and lose any changes made to attributes in that case.

If the project has no modified values in that case, the case should be deleted.

Case Created in the Project but Does Not Exist inthe Master

If a case with the same name already exists in the Master project (becausethe Project and Master independently created the same named case) thereare two ways to resolve the conflict:

Rename the case in Project.

Decide both cases are the same. If either case is global the ‘merged’ casewill also be global.

By choosing to unify the two cases, all attributes in the Project that exist inthe case will have to be re-assigned to the Master’s case.

The case name in the master cannot be modified within the conflict resolutionprocedure. The user could login to the Master and rename to remove theconflict. In such a case the conflict would not appear on a subsequent projectupdate.

230 11 Explorer

Case Deleted in the Project but Still Exists in theMaster

When a case is deleted, all attributes in that case will have been deleted inthe project. If values have been modified for the deleted case in the Master,the following conflict resolutions are possible:

Re-instate the case.

Delete the case and discard all attribute values in the Master for thespecified case.

Case Renamed in both the Project and the Master

When the same case exists in both the Project and Master, the scope of thecase (Global/Local) must be the same (the scope of an existing case cannotbe modified). The name of the case may have been changed in both theProject and Master.

To resolve this conflict you can either:

Keep the new name in the Master.

Keep the new name in the Project (in which case proceed as below).

If the case has been renamed in the Project, and it now clashes with adifferent case in the Master (new or renamed), the resulting options are thesame as those in the previous section Case Created in the Project but DoesNot Exist in the Master.

Allowing merging of cases (deciding the Project and Master case are thesame) in this situation would mean checking the entire database for attributesdefined in the project case (as this case was not newly created in the Projectit may have much wider scope than the current Project).

Primary Objects

An object in the project is the same object as that in the Master if they bothhave the same ObjectID. The object may also be the same if it has the samename as an existing object.

11 Explorer 231

Object Deleted in the Master but Still Exists in theProject

An object existing in the project but not in the Master does not necessarilymean that the object was created in the project. The original object may havebeen deleted from the Master project. If the project has modified values onthe now deleted object there are two possible resolutions.

Re-instate the object (in which case conflict resolution occurs as detailedbelow).

Delete the object and lose any changes made to its attributes.

Even if the project does not have any modified values on that object, youshould still decide whether to re-instate or delete the object as other changesmade to the project may have been predicated on the object existing.

Object Created in the Project but Does not Existin the Master

For certain classes of object the name of the object is important. For examplemajor equipment items. For other types of object the name is not important(i.e. Folders, Documents). For those object types with important names, if anobject with the same name already exists in the Master project (because theProject and Master independently created the same named object) there are anumber of ways to resolve the conflict:

Rename the object in Project.

Decide that having two identically named items is acceptable.

Object Deleted in the Project and Still Exists inthe Master

Values on the deleted object (or one of it's contained sub-objects) may havebeen modified in the Master.

The following conflict resolutions are possible:

Decide to keep the object from the Master.

Delete the object and discard all attribute values in the Master for thespecified object.

232 11 Explorer

Object Exists in both the Project and the Master

If the class of the object has been changed in both the project and the Masterthe following conflict resolutions are possible:

Keep the new class from the project.

Keep the new class from the Master.

For those object types with important names. If the object has been renamedin both the Project and in the Master the user can choose to either:

Keep the new name from the Master.

Keep the new name from the Project (in which case proceed as below).

If the object has been renamed in the Project, and it now clashes with adifferent object in the Master (either new or renamed), the user can choosefrom the same options presented in the previous section Object Created inthe Project but Does not Exist in the Master.

Attribute Items

Either the value, or the status of the value (Lock/Hold/Secure) may havebeen changed in either or both the Project or the Master.

Immediate Attributes - Immediate attributes are the simple types (i.e.String/Real/Bool/Date/Enum). A conflict occurs when both the Project andMaster value (or status) have been changed since the last update.

Scalar/Vector - To resolve the conflict the user can instruct the system tooverwrite one of the values with the other, either:

Keep the value/status from the project.

Keep the value/status from the master.

Collections - A collection is a set of values which are added to/removed fromrather than simply overwritten (as in the case of a vector where the positionof the values is important). There is no conflict between the Project and theMaster attribute when ‘merging’ the differences. Starting with the currentproject collection, add what has been added in the Master and remove whathas been removed in the Master. Note that the order of values in thecollection may change.

11 Explorer 233

Object Attributes

An object attribute is an attribute that contains another object or objects. Aconflict occurs when both the Project and Master value (or status) have beenchanged since the last update.

Scalar/Vector - A conflict occurs when there are more/less or differentobject(s) in the attribute.

This can be resolved by:

Selecting which attribute routes are to be kept from the project and whichare to be kept from the master.

The selections could result in either objects in the project having some/all ofits data overwritten with data from the Master or new objects being createdfor the attribute in the project.

Collections - A collection is a set of objects which are added to/removed fromrather than simply overwritten (as in the case of a vector where the positionof the objects is important). There is no conflict between the Project and theMaster attribute when ‘merging’ the differences. There may, however, beconflicts between the contained objects. Starting with the current projectcollection, add the objects that have been added in the Master and removethe objects that have been removed in the Master. Note that the order of theobjects in the collection may change. Each object in the project collectionshould be compared with the same object (same OID) in the Master toresolve any additional conflicts.

Object Associations

An object association is one that references another object or objects. Aconflict occurs when both the Project and Master value (or status) have beenchanged since the last update. Resolution of a conflict between an associationin the Project and the Master does not require conflicts between thereferenced objects to be checked.

Scalar/Vector - A conflict occurs when there are more/less or differentobject(s) referenced by the attribute.

This can be resolved by:

Keep the value from the Project (no comparison of sub-objects required).

Keep the value from the Master (no comparison of sub-objects required).

Collections - There is no conflict between the Project and the Master attributewhen ‘merging’ the differences. Starting with the current project collection,add the objects that have been added in the Master and remove the objectsthat have been removed in the Master. Note that the order of the objects inthe collection may change.

234 11 Explorer

Conflict Interdependency

There are conflicts whose resolutions are inter-dependent. For example, if inthe Master a case is deleted that has changes in the Project you cannotchoose to both delete the case and keep the changes in the Project. Similarlythe resolution of one conflict may introduce additional conflicts that need tobe resolved. For example choosing to merge a case in the Project with a casein the Master may introduce new attribute value conflicts.

Some possible inter-dependencies are described below:

Cannot accept deletion of a case and also preserve attribute changes inthat case.

Cannot accept deletion of an object and also preserve attribute changeson the object.

Cannot accept only part of a graphical change i.e. move an object but notmove connected streams.

Cannot reject changes to a hold and keep attributes held.

Managing Users and Roles

Note: Management of Aspen Basic Engineering users and their roles isidentical whether or not you use Aspen Basic Engineering in conjunction withSmartplant.

Adding a User to a Project

You must have Aspen Basic Engineering Administrator privilege before youcan add a new user to the project.

1 Launch the AZ Explorer application and log on to a project.

2 Select Edit | Project Management and the Edit Users button, theUsers dialog is displayed:

11 Explorer 235

3 Select Add, the New User dialog is displayed which allows selection ofusers and groups:

4 Select a user name or Group name, the new user/group is added to theproject’s member list.

Editing User Properties

You must have Administrator privilege before you can edit the properties of aproject user:


2 Select Edit | Project Management and select the Edit Users button,the Users dialog is displayed.

3 Select a user name from the list displayed and click Edit. The Propertiesfor User [name] dialog is displayed:

236 11 Explorer

4 Select the Roles tab to edit the Role properties.

5 Click OK to accept the new properties and close the dialog.

Removing a User from a Project

You must have the Administrator privilege in the project before you canremove a user from the project:


2 Select Edit | Project Management and select the Edit Users button,the Users dialog is displayed.

3 Select the name of the user you want to remove from the list of usersdisplayed.

4 Click Remove. The user is removed from the project’s member list.

Assigning Privileges to Roles

Roles and privileges operate in a very similar manner within a project as theydo within a workspace in Aspen Basic Engineering. However, roles andprivileges within a project are independent of those in its master project.Roles and users can optionally be copied from the master at the time ofproject creation but from that point on they are independent.

Privileges are assigned to selected roles via Edit | Project Management andthen the Edit Roles dialog.

To assign or change the privileges for a role:


2 Select Edit | Project Management and select the Edit Roles button, theRoles dialog is displayed:

11 Explorer 237

3 Select the role name you want to modify privileges for and click Edit. TheProperties for Role [role name] dialog is displayed.

4 Select the Privileges tab to display a list of privileges and theirassignment status.

5 Select or deselect the options required in the Grant/Deny checkboxes.

6 Click OK when you have set the new privileges to return to theProperties dialog.

7 To reset privileges for other roles, follow steps 3 to 6

8 Click Close when all role privileges have been set.

Managing the Scope of a Project

Note: These procedures are not applicable when project scope is in relationto the Smartplant project.

The concept of primary items and parts is introduced in these procedures. Aprimary item is a main equipment item e.g. a vessel, whereas a part might bethe vessel’s agitator or nozzle.

Claiming an item (whether primary or part) results in all its parts beingclaimed in the same manner. Therefore if a vessel is claimed exclusively to aproject then all its nozzles are claimed exclusively to the project also.

Adding Objects to the Project Scope

Note: You must have launched an AZ client application and be logged on to aproject to perform these procedures.

Adding a Primary Item Exclusively to the ProjectScope

Select a primary item, or items (e.g. on a drawing or a field on a datasheet orin a folder) and select the Claim Exclusive command. The item and all itsparts are claimed exclusively to the project scope.If you open a peer project, and attempt to claim the same item to thatproject (either shared or exclusively), the claim is prevented.

238 11 Explorer

Adding a Primary Item as Shared to the ProjectScope

Select a primary item, or items (e.g. on a drawing or a field on a datasheet orin a folder) and select the Claim Shared command. The item and all its partsare claimed as shared to the project scope.If you open a peer project, and attempt to claim the same item to thatproject (either shared or exclusively), the claim is prevented.

Adding an Item Part to the Project Scope

This procedure is used if you wish to claim a part of an equipment item asopposed to the whole item, e.g. claim a nozzle of a vessel. The claimprocedure is the same for a part as for a primary item in the Drawing Editor(the part must have a dedicated symbol to be claimed) and AZ Explorer.

1 Select a datasheet field that relates to a part and select a claim command(either Exclusive or Shared), the system presents the primary item andthe part(s), if any, that could be claimed to edit the selected field.The part(s) presented represent ‘real-world’ entities and not the abstractsub-object classes from the data model.

2 Select the part to be claimed, the system claims (either Exclusively orShared) the part and all its constituent parts. You may still edit any dataof the part but not data of the owning item.

Removing a Primary Item or Part from the ProjectScope1 Select a claimed item, or items (e.g. on a drawing or a field on a

datasheet or in a folder) and select the Un-claim menu option. You areprompted that removing an item (identified in the prompt) from theproject scope will result in the permanent loss of any data modified forthat item in the course of the project.Note: If you select a part of a claimed primary item (e.g. agitator of aclaimed vessel), the primary item and all its constituent parts areremoved from the project scope.

2 Confirm the scope change, the selected item(s) and all constituent partsare removed from the project scope and any project data for the item(s)are deleted.

11 Explorer 239

Selecting a Part and Un-claiming (Primary Item isClaimed)

This procedure is applicable if you wish to un-claim an item that has anassociation to another claimed item where the association between the twohas been modified in the project. For example, if a stream connected to avessel is reconnected to a pump, then the vessel cannot be unclaimed withoutun-claiming the stream.

Changing a Shared Claim to an Exclusive Claim Select share claimed item(s) (e.g. on a drawing or a field on a datasheet

or in a folder) and select the Claim Exclusive menu option, the claim forthe item and all its parts is changed to an exclusive one.

Changing an Exclusive Claim to a Shared Claim Select exclusively claimed item(s) (e.g. on a drawing or a field on a

datasheet or in a folder) and select the Claim Shared menu option, theclaim for the item and all its parts is changed to a shared one.

240 11 Explorer

12 Smartplant 241

12 Smartplant

Smartplant® is a central data and document repository, data transfer conduitand a centralized project administration system.

Intergraph’s SmartPlant Foundation (SPF) is at the core of Smartplant and isrequired to allow Aspen Basic Engineering/Smartplant functionality.

Note: Before you can use Aspen Basic Engineering with Smartplant, aworkspace must be registered with a Smartplant plant database. Consult theAdministration Tool on-line help on how to do this.

The interaction with Smartplant is carried out by using the Smartplant menuthat appears on each of the main end-user application menu bars, namely theExplorer, Drawing editor and Datasheet Editor. You will find that entries inthis menu are inactive if you are not connected to a workspace that is notregistered with a SmartPlant Database.

Each of the end-user client applications where this menu appears also containa specific on-line help book dedicated to the features of the Framework menu.The menu entries and this help are identical across the applications. The on-line help covers features such as:

Publishing information to Smartplant

What is published

Retrieving information

Managing retrieved information using ToDo List tasks

Finding documents that need publishing

Browsing Smartplant

Some features interface directly to Intergraph Smartplant tools such as forbrowsing. You should refer to the on-line help of the Intergraph tool in thesecircumstances to get more information.

As significant new features are being delivered through downloadable updatesto 2006 you need to consult the on-line help provided for the most up-to-dateinformation on using Aspen Basic Engineering with Smartplant.

242 12 Smartplant

13 Administration 243

13 Administration

The Aspen Basic Engineering Administration application is used to administerWorkspaces and display Workspace information in a graphical format. TheAdministration tool is a Microsoft Management Console (MMC) snap-in, andcan be combined with other Snap-in components such as the SQL ServerEnterprise Manager to single console for the common administration tasks.Refer to the Microsoft help on MMC for more information.

The main window is divided into two resizable panes. The left pane displaysthe Workspaces that the user has access to, through the currently selectbusiness server, and under each workspace are nodes:

User Management.

Role Management.

Connection Monitoring.

Auditing.

The right-hand pane displays details for the node that is currently selected.The Action menu lists the commands that can be applied for the node that iscurrently selected.

The Adminstration tool has detailed help for the creation of workspaces,manipulating user access and workspace configuration. In addition the on-linehelp covers:

The overall architecture and role of the Aspen Basic Engineering Broker

Useful information about the Broker Services Account

How to use Oracle or SQL Server with Aspen Basic Engineering

Details on configuration parameters

Details on configuring descriptive text used in displaying attributes

How to set up symbol replication to help performance on slow networks

How to use the Aspen Basic Engineering Backup tool

The administration tool help is updated on a regular basis including softwareupdates. Please use this information as the most up-to-date guide for the useof this tool.

244 13 Administration

14 Bridge 245

14 Bridge

The Bridge application is used to create a bridge allowing two-way datatransfer between an Aspen Basic Engineering workspace and either MicrosoftWord or Microsoft Excel files.

An example of Bridge usage is:

An Excel spreadsheet created to perform a design calculation and loadedwith data from the Aspen Basic Engineering workspace by the Bridge. Thedesign calculations are performed in Excel through End-User interactionwith Excel.

The Bridge transfers the results of the calculation back to the Aspen BasicEngineering workspace.

End-users can interact with the transfer process, data can be viewed as itis transferred and bridge objects can be configured to link data objects inapplications.

New bridges can be defined in the design mode of the application. Using thismode, you can define links between Aspen Basic Engineering Class views andthe desktop tool. Bridges can also be saved and reused.

Overview of the InterfaceMost operations in the Bridge application are performed from the AZ Bridgewindow.

To access the AZ Bridge window:

1 Launch the Bridge application.

2 If you are not already connected to a workspace, select File | OpenWorkspace to display the Open Workspace dialog and log onto aworkspace.

3 Click File | New Bridge (or click the New Bridge toolbar icon) to displaythe AZ Bridge window.

246 14 Bridge

When you first open a bridge, the AZ Bridge window appears in Bridge View.From this view, you can add application files to the bridge. This is explained inCreating a Bridge.

After adding an application file to a bridge, you can add a linkset by selectingan application file and clicking Linkset | New. The AZ Bridge window thenappears in Link View, showing the links contained in a specific linkset.

The Link menu is only available in Link View.

From Link View, you can access the Link Properties dialog by clicking Link |Properties.

You can add or edit a linkset from either the AZ Bridge window’s Link View orfrom the Link Properties dialog. Refer to Adding a Linkset for instructions.

Iterative Linksets (refer to Iterative Linksets) can only be added and editedfrom the Link Properties dialog.

14 Bridge 247

Bridge View and Link ViewMenusThe menus for the Bridge and Link Views are comprised of:

File.

Edit.

View.

Link (not available in Bridge View).

Linkset.

Application (not available in Link View).

Transfer.

Grid.

Help (opens Help associated with the Bridge application).


File MenuCommand

Action

New Bridge Creates a new (untitled) bridge in the currently open workspace

Open Bridge Displays the Open Bridge dialog that displays a list of availablebridges to open in the current workspace. Bridge details arecontained in six columns

Close Bridge Closes the currently open bridge. A Save prompt is displayed ifthe bridge has been modified

Refresh Bridge Updates the data in the Bridge with the current workspace values

Save Bridge Saves the open bridge in the current workspace

Save BridgeAs…

Opens a Save As… dialog allowing you to save the bridge with anew or different name

BridgeProperties

Opens the Bridge Properties dialog

OpenWorkspace

Displays the Open Workspace dialog allowing you to select theworkspace you want to connect to

CloseWorkspace

Displays the Bridge Close dialog allowing you to save the openbridge before closing the current workspace

SynchronizeNames

Rename (or make new copies of) the location names in applicationfiles to match the attribute names (Linkset – Bridge View)

Copy Object/Case Bindings

Copies bindings from an existing (open) bridge into a new bridge(via the Paste Object/Case Bindings option)

Auto-createObjectBindings

Searches all objects in the workspace with an associated classviewand creates one linkset per object (if needed) and then boundsthe linkset (for each defined linkset in the Bridge) to therespective object

248 14 Bridge

File MenuCommand

Action

ExportPackage

Writes a package file containing the data for the objects defined inthe current bridge

Recent File Displays a list of recently opened files

Exit Exits the Bridge application and closes any connection to theworkspace. A Save prompt is displayed if the bridge has beenmodified

Edit MenuThe Edit menu contains the following commands (different options aredisplayed according to the window currently open):


Cut Cuts the selected item to the clipboard

Copy Copies the selected item to the clipboard

Paste Text Pastes the selected item from the clipboard


View MenuCommand

Action

Design ModeTurn On/Off

Turns the Design mode On/Off (toggle). Design mode has to beon for bridge definition, i.e., for adding and setting the propertiesof application files, linksets, and links

Toolbar Displays/hides the Bridge toolbar

Status Bar Displays/hides the Status bar at the bottom of the window

Bridge Opens the Linkset – Bridge View window. This is only available inthe Link View

Status Report Opens the Bridge transfer Report dialog

Error Report Opens the transfer Error dialog

Change Report Opens a Change Report dialog showing target, location and oldand new values

14 Bridge 249

Link MenuThe Link menu (displayed in Link View only) contains the following menuoptions:

Link MenuCommand

Action

Properties Displays link properties

New Adds a new link to the link grid with default workspacecase and default workspace unit group

Enable Enables selected link

Disable Disables selected link

Cut Cuts the selected link(s) from the link grid and copies itonto the clipboard

Copy Copies the selected link(s) onto the clipboard

Paste Pastes copied link(s) from the clipboard to the linksetgrid

Delete Deletes the selected link(s) from the link grid

Attribute Opens the Attribute Selector Dialog. Allows you to selectan attribute for the Class View selected

Write To Location Sets the Write To location

Read To Location Sets the Read To location

Case Sets the case for selected links

Units Sets the units for selected links. All the selected linksmust be in the same unit group.

Formats Displays dialog for setting the write format for selectedlinks.

Linkset MenuThe Linkset menu contains the following commands:

Linkset MenuCommand

Action

In Bridge View mode:

Properties Opens the Link View and displays Linkset properties

Class view Opens the Class View Selector dialog allowing you to browsefor a Class View

Object Opens the Object Select dialog allowing you to select a singleobject or multiple objects if the linkset is iterative

Create Object Used to create an object of a class that implements the classview set at the linkset

Multi-Create Allows you to create one linkset for selected objects

Case Opens the Select Case dialog. Select an unrestricted case forthe selected linksets. A drop-down list is also available in the

250 14 Bridge

Linkset MenuCommand

Action

linkset grid for setting cases

New Adds a new linkset to the linkset grid with default bridge caseand default bridge unit group

Enable Enables selected linksets. You can also use the checkboxesavailable in the linkset grid

Disable Disables selected linksets

Delete Deletes the selected linksets from the linkset grid

In Link View mode:

Next Displays next linkset

Previous Displays previous linkset

First Displays first linkset

Last Displays last linkset

Copy Copies selected linksets to the clipboard

Synchronize Names Rename (or make new copies of) the location names inapplication files to match the attribute names

Application MenuThe Application menu (not displayed when the application is in Link Viewmode) contains the following commands:

Application MenuCommand

Action

Launch Launches the application associated with the selected file inthe bridge

Properties Displays the Bridge Application File Properties dialog

Location List Displays the Application Location List dialog and allows youto display the selected location

Enable Enables the selected file for data transfer during a bridgerun

Disable Disables the selected file from being used for data transferduring a bridge run

Working Directory Specifies the working directory for checking out files

Add Displays the Open dialog allowing you to add an applicationfile(s) to the bridge. A copy of the application file is madeand added to the bridge and saved in Aspen BasicEngineering database

Add linked file Adds a linked file (also called template file). The applicationfile is not copied and added to the bridge/Aspen BasicEngineering database. The latest version of the file on theuser’s machine is used

Paste Allows a copied file to be pasted into the bridge

Save Saves the selected file back into the bridge

Save As… Displays the Save As… dialog

Delete Deletes the selected item(s)

14 Bridge 251

Transfer MenuThe Transfer menu contains the following commands:

Transfer MenuCommand

Action

Aspen BasicEngineering toApplication

Transfers data from Aspen Basic Engineering to the application

Application toAspen BasicEngineering

Transfers data from the application to Aspen Basic Engineering

Autorun A single-step export of data from Aspen Basic Engineering tothe application file

Autorun withPause

Autorun with a pause when application files are instructed torecalculate to allow end-user interaction at this step

AdvancedTransfers(with sub-menus)

The advanced options comprise data transfer from:

Aspen Basic Engineering to Bridge

Bridge to Application

Application to Bridge

Bridge to Aspen Basic Engineering

Grid MenuThe Grid menu contains the following commands:

Transfer Menu Command Action

Find Find a cell containing text

Sort Ascending Sort items in ascending order

Sort Descending Sort items in descending order

Row Selection Mode Select grid mode

252 14 Bridge

Bridge View Linkset Drop-Down MenusTwo drop-down menus are displayed in the lower pane of the AZ Bridgewindow in Bridge View mode allowing Case and Unit Standard attributes to bespecified.

Drop-down Menu Title Action

Case Design Default

<Workspace Default>

Unit Standard <Workspace Default>

Imperial

Metric

SI

US

Bridge View Linksets GridEight columns are displayed in the lower pane of the AZ Bridge window inBridge View mode allowing linkset attributes to be specified:

Column Title Action

Enabled Enabled Yes/No checkbox toggle

Name Name of the linkset (editable)

Class View Class View identity (editable), double-click to display Class ViewSelector dialog

Object Object identity (editable), double-click to display Object Selectdialog

Case Case identity can be selected, or a default is applied

Unit Standard Details the current unit standard used, selectable from a drop-down list, or a default is applied

Description Allows a description for the linkset to be entered (editable)

Errors Notifies if errors are present

14 Bridge 253

Link View Drop-Down Menus and FieldsTwo drop-down menus are displayed on the AZ Bridge window in Link Viewmode allowing Case and Unit Standard attributes to be specified.

Drop-downMenu/Field Title

Action

Name Linkset identity (editable)

Case Design Default

<Bridge Default>

<Workspace Default>

Unit Sets <Bridge Default>

<Workspace Default>

Imperial; Metric; SI; US

Class View Class view name. Click the icon to select a new Class

Object Object name. Click the icon to select a new object. If theiterative checkbox is selected, the Iterative Linkset holds a listof all objects matching the Class specified

The purpose of the Iterative Linkset is to quickly apply a setof calculations to a set of objects

Description Linkset description

Links Grid in Bridge Link View WindowNine columns are displayed in the lower pane of the AZ Bridge window in LinkView mode allowing linkset attributes to be specified:

Column Title Action

Enabled Enabled Yes/No toggle

Write To Name of the linkset (editable)

Read From Read from a linkset

Attribute Identifies the link attribute

Case Case identity can be selected, or a default is applied

Aspen BasicEngineeringValue

Displays the current value

App. Value Displays the Application value

Units Details the current unit standard used, selectable from a drop-down list, or a default is applied

Errors Notifies if errors are present

254 14 Bridge

AZ Bridge Window Toolbars

Bridge View ToolbarWhen the AZ Bridge window is in Bridge View mode, this toolbar appears:

The Bridge View toolbar contains the following icons:

ToolbarButton

Name Description

1 New Bridge Creates a new bridge file

2 Open Bridge Opens an existing bridge file

3 Save Bridge Saves the current bridge

4 Bridge Properties Displays the Bridge Properties dialog

5 Design Mode Turn Design Mode On/Off

6 Cut Cuts the selection onto the clipboard

7 Copy Copies the selection onto the clipboard

8 Paste Inserts clipboard contents

9 New Linkset Creates a new linkset

10 Delete Linksets Deletes selected linksets

11 Properties Displays Linkset Properties dialog for the selected row

12 Class View Opens the Class View Selector dialog

13 Object View Opens the Object View Selector dialog

14 Select Case Opens the Select Case dialog

15 Enable Linksets Enable selected linksets

16 Disable Linksets Disable selected linksets

17 Launch Application Launches an application file

18 Add Application File Displays the Open dialog, allowing you to search for andadd an application file

19 Application Properties Displays properties for the selected application file

20 Enable SelectedApplications

Enables the selected applications

21 Disable SelectedApplications

Disables the selected applications

22 Transfer Aspen BasicEngineering toApplication

Transfers data from Aspen Basic Engineering to anapplication

23 Transfer Applicationto Aspen BasicEngineering

Transfers data from an application to Aspen BasicEngineering

24 Autorun Start Autorun

25 Find Find a cell containing text

26 View Order (A – Z) Sets view/sort order

27 View Order (Z – A) Sets view/sort order

28 Help Displays Bridge help menu and About Bridge menu

14 Bridge 255

Link View ToolbarWhen the AZ Bridge window is in Link View mode, the following defaulttoolbar appears below the menu:

The Link View toolbar contains the following icons (all have an equivalentoption within the menus):

ToolbarButton

Name Description

1 Save Bridge Saves the current bridge

2 Bridge Properties Displays the Bridge Properties dialog

3 Design Mode Turn Design Mode On/Off

4 Cut Cuts the selection onto the clipboard

5 Copies Copies the selection onto the clipboard

6 Paste Inserts clipboard contents

7 New Linkset Creates a new linkset

8 Delete Linksets Deletes selected linksets

9 Properties Displays Linkset Properties dialog for the selectedrow

10 Write To Location Sets the write to file location

11 Read From Location Sets the read from file location

12 Attribute Select the Aspen Basic Engineering attribute

13 Set Case Select the case for selected links

14 Enable Linksets Enable selected linksets

15 Disable Linksets Disable selected linksets

16 Units Sets units for selected links

17 Write format Sets the write format for selected links

18 Bridge View Toggles the window to Bridge View mode

19 Previous Linkset Displays the previous linkset

20 Next Linkset Displays the next linkset

21 Transfer AspenBasic Engineeringto Application

Transfers data from Aspen Basic Engineering toan application

22 Transfer Applicationto Aspen BasicEngineering

Transfers data from an application to Aspen BasicEngineering

23 Autorun Start Autorun

24 Find Find a cell containing text

25 View Order (A – Z) Sets view/sort order

26 View Order (Z – A) Sets view/sort order

27 About Opens the Bridge on-line help

256 14 Bridge

Creating a BridgeThis procedure creates a new bridge and adds an application file in the Bridgeapplication:




4 Click Application | Add (or click the Paperclip toolbar icon) to display theOpen dialog and select or navigate to an application file (MS Word .doc, orMS Excel .xls format). Alternative: Drag and drop the application file infrom the File Manager/Windows Explorer.

5 Click the OK button on the Open dialog to create the new bridge file in theBridge application. (Alternatively, an application file can be dragged anddropped onto the AZ Bridge window.)

6 The Bridge uses the default Case and Unit Standard settings from theworkspace. These can be overridden via drop-down fields displayed on theAZ Bridge window.

7 Click File | Save Bridge to open the Bridge Save As… dialog and enter aname for the bridge. This creates the Bridge object in the workspace andindicates that the Bridge has been saved. The system immediatelyacquires a user lock on the Bridge so that no one else can use it until theBridge is closed.

8 Click File | Close Bridge to close the Bridge. The user lock is nowdisabled.

Adding Multiple Files In One BridgeIf a set of files have common mapping and are typically activatedsimultaneously, multiple application files can be added and deleted.

Note: The bridge can also exist and be saved with no application files. Anapplication file needs to be added before doing application data transferoperation.




4 Click Application | Add (or click the Paperclip toolbar icon) to display theOpen dialog and select or navigate to an application file (MS Word .doc, orMS Excel .xls format). Alternative: Drag and drop the application files infrom the File Manager/Windows Explorer The files can even be a mixtureof Excel and Word.

14 Bridge 257

5 Click the OK button on the Open dialog to create the new bridge file in theBridge application. (Alternatively, an application file can be dragged anddropped onto the AZ Bridge window.)

6 Repeat steps 4 and 5 for each additional application file (MS Word .doc, orMS Excel .xls format) you wish to add. You must select the file format(.xls or .doc) in the Open dialog’s Files of Type field if you wish to addboth formats.

7 Click File | Save Bridge to open the Bridge Save As… dialog and enter aname for the bridge. This creates the Bridge object in the workspace andindicates that the bridge has been saved. The system immediatelyacquires a user lock on the bridge so that no one else can use it until thebridge is closed.

8 Click File | Close Bridge to close the bridge. The user lock is nowdisabled.

Creating Multiple Links for the SameAttributeAfter you change the units at the individual link level, the bridge performs anumber of checks throughout the opened bridge.

It checks if there is another link which uses that attribute with the same classview. If a match is found, and the individual link units are different, a systemprompt asks if you wish to make the units the same, see below:

This prompt implies that objects in the respective links need not be the same.Also the links need not be in the same linkset.

From this prompt, clicking Yes or No either updates or discards the relatedlink's units. The system then continues to look for other links with the sameattribute and class view.

If you select Cancel or close the dialog, the related link's units are notchanged, and further searching is abandoned.

Selecting Yes to all updates the units on this link and any other related linksin the bridge without prompting.

258 14 Bridge

Checking Only change links in linkset.. causes only links in the samelinkset to have their units updated. So if the currently displayed related link isnot in the same linkset as the original change, no change is made to its units,even if you click Yes or Yes to all.

For example in the above dialog, if you check Only change links in linksetLinkset: 1-LS1 and click Yes or Yes to all, no change is made to the unitsof Linkset: 2 - LS2 Link: 1.

Conversion between Template Files (LinkedFiles) and Bridge Files (Application FilesAdded to Bridge)Template files are used when the requirement is to always use the latestversion of an application file. Bridge files are used when the requirement is topersist any manual entries and bridge transfers.

To change a template file to a bridge file:

Select the application icon representing the Template File and, from theApplication menu or Context menu, select the Convert to Linked Filecommand.

To change a bridge file to a template file:

Delete the bridge file and copy in the template file.

Object/Case Bindings

Copying and Pasting Object/Case BindingsWhen working on a bridge in the workspace, it is possible to copy and pasteexisting Object/Case Bindings (to prevent having to recreate themindividually).

This is achieved by importing the package containing the newly defined bridgeinto your workspace (the new bridge does not have any object bindings/casebindings), then copying object and case bindings from the source (existing)bridge to the target (newly imported) bridge.

To Copy/Paste Bindings1 Open a target bridge in the AZ Bridge application.

2 Right-click and select Copy Object/Case Bindings, or select the File |Copy Object/Case Bindings menu option. A dialog is displayed with alist of available bridges in the current workspace.

3 From the list, select the bridge you want to copy object bindings from.

4 Select the target bridge to copy the bindings into.

5 Check the newly created bindings and then either Save or Discard thechanges.

14 Bridge 259

System Conditions:

The system only attempts to copy bindings…from named linksets in thesource bridge to the target bridge (unnamed linkset are ignored).

Bindings are copied by matching names and classviews of the linksets inthe source and the target bridge…if the target bridge does not have atleast one linkset with the same name and classview as the linkset fromthe source bridge the system is attempting to copy bindings from, thatlinkset and others in the source bridge with the same name are skipped.

If there are multiple linksets in the source bridge with the same name andat least one linkset in the target bridge with a matching name andclassview…the copy operation ensures it creates additional linksets in thetarget bridge, so that the number of identically named linksets in the twobridges match and the bindings are copied.

If there are multiple linksets in the source bridge with the same name butwith differing class view settings…the system attempts to copy the firstone it finds while scanning the source bridge and the ones compatible to it(those with same name and class view), and ignores the others (thosewith a different classview from the first one found with the same name).(A message concerning any linkset in the source bridge that is missedfrom the copying process is added to the error report.)

If while attempting to copy object bindings the system finds the targetlinkset already has the object binding set…an overwrite/do notoverwrite binding prompt is displayed.

The system will not copy links contained in the linkset in the sourcebridge. If new linksets are created in the target bridge, links in the newlycreated linkset are copied from the one matching linkset found in thetarget bridge.

Auto-Creation of Object BindingsIt is possible to auto-create object bindings if:

A new bridge is imported into a workspace with some linksets withclassviews set but no object bindings (and the workspace contains severalobjects).

All objects in the workspace implementing the associated classview are foundfor each defined linkset in the bridge, and one linkset per object is created (ifneeded) and bound to the respective object.

260 14 Bridge

To Auto-create Object Bindings1 Using the AZ Explorer, import a new bridge into the workspace.

2 Open the bridge in the AZ Bridge application, then right-click and selectAuto-Create object bindings from the menu option. The workspace isscanned to find objects that implement the class view set at the linkset foreach linkset in the bridge. One linkset per object found is created andbound to the object, copying the links existing in the linkset into eachnewly created linkset patterned after the functionality that currently existsin the Bridge application for the Multi-Create Linkset menu option.

3 Check the newly created bindings and then either Save or Discard thechanges.

System Conditions:

If for a particular linkset no objects are found that implement the classview…that linkset is skipped.

If class view is not set at a linkset… the linkset is skipped. A messageabout this is added to the error report.

If more than one linkset with the same class view is found in thebridge…the first one is used in the Multi-Create process and thesubsequent ones are skipped. A message for each skipped linkset is addedto the error report.

If a linkset is found that already has an object set…it is skipped. Amessage is added to the error report.

Linksets are created for all objects that implement the classview - you arenot prompted to specify the objects.

You are prompted once to specify format information for the generation oflocation names. The same choices are applied to all linksets.

Multi-Creation of Linksets without ObjectBindingsThe dialog displayed from the Multi-create linkset menu item includes anoption (checkbox) allowing you to multi-create linksets without creatingobject bindings.

To specify this option, uncheck Create object bindings (checked bydefault). You can then specify the number of linksets to create without objectbindings.

You also need to specify the location name generator for this case (in theusual way).

14 Bridge 261

Editing an Existing Bridge1 Launch the Bridge application.


3 Click File | Open Bridge (or click the Open Bridge toolbar icon) to displaythe Open Bridge dialog.

4 Select the bridge to open from the list displayed and click OK to open theAZ Bridge window.

5 Edit the bridge as required and when completed, click File | Save Bridgeto save the changes and update the workspace.

6 Click File | Close Bridge to close the bridge. (The user lock is nowdisabled.)

Closing the Bridge Without SavingIf you attempt to close the bridge without saving, a prompt is displayedasking you to confirm whether changes are to be saved or not. Unsavedchanges are lost if No is selected.

262 14 Bridge

Adding a New LinksetThe actions described in the following steps can be made in the AZ Bridgewindow’s Link View or in the Linkset Properties mode. Both views allow datato be entered via menu options, editable columns/rows, or dialogs, checkboxes and drop-down menus.



3 Click File | Open Bridge (or click the Open Bridge toolbar icon) to displaythe Open Bridge dialog.

4 Select an application file in the bridge and click Linkset | New. A newblank row is displayed for the new Linkset.

5 Select Linkset | Class View to display the Class View Selector dialog andnavigate the class hierarchy and select the class.

6 Select the Case Name. A list of the Cases in the workspace is available forselection via a drop-down list. If a Case is not specified, the linkset usesthe bridge or workspace default (represented as <default>). The CaseName for the default is also displayed.

7 Enter the Unit Standard name. A list of the current Unit Standardsspecified in the workspace is available for selection via a drop-down list. Ifthe Unit Standard is not specified, the linkset uses the bridge orworkspace default Case (represented as <default>). The actual UnitStandard name for the default is also displayed.

8 Enter the object instance name to use with the linkset. An Object SelectDialog displays all the objects in the workspace of the Class specified. Ifthe Class has not yet been specified, the browser displays all objects.When an object is selected, if the Class has not yet been set, it is set tothe selected object’s Class.

9 Enter a name for the linkset. The default will be the object’s name.

10 Text containing information or instructions can be entered in theDescription field.

11 Using the information from the links contained in the linkset, the systemdisplays the derived export and import status.

12 Enable/disable the linkset by checking/unchecking the Enabled box in theLinkset Editor, or selecting Enable or Disable from the Linkset menuoption.

13 When completed, click File | Save Bridge to save the changes andupdate the workspace.

14 Click File | Close Bridge to close the bridge.

Note:

Linksets can also be edited using standard cut/copy/paste operations toduplicate existing linksets from this bridge and from other bridges.

Linksets can also be created for multiple objects.

14 Bridge 263

Editing LinksetsThe actions described in these steps can be made in the AZ Bridge window’sLink View or in the Linkset Properties mode. Both views allow data to beentered via menu options, editable columns/rows, or dialogs, check boxesand drop-down menus.



3 Click File | Open Bridge (or click the Open Bridge toolbar icon) to displaythe Open Bridge dialog, select a bridge and click the OK button.

4 In the AZ Bridge window, select the linkset row to be edited.

5 Highlight the field to be edited and modify the data as required.

Note: Cut/Copy/Paste Operation.Linksets can also be edited using standard cut/copy/paste operations toduplicate existing Linksets from this bridge and from other bridges.

6 Enable/disable the linkset by checking/unchecking the Enabled box in theLinkset Editor, or selecting Enable or Disable from the Linkset menuoption.

7 When completed, click File | Save Bridge to save the changes andupdate the workspace.

8 Click File | Close Bridge to close the bridge.

Iterative LinksetsAn Iterative Linkset is a variation of the standard linkset. The Iterative Linksetholds a list of all objects matching the Class specified. List items can beselectively enabled or disabled.

The purpose of the Iterative Linkset is to quickly apply a set of calculations toa set of objects. An example would be to do a pump-head calculation for allcentrifugal pumps in an Excel worksheet. There would be a single set oflocations which correspond to the pump variables.

There are three alternatives to creating an Iterative Linkset:

Make a copy of the bridge for each centrifugal pump.

Create a bridge with linksets for all of the pumps. Disable all pumplinksets except for the first. Execute the bridge. Repeat this procedure foreach pump.

Create a separate sheet for the maximum number of pumps in the singlespreadsheet, and use an indexed numbering system for the locations.(This alternative causes the spreadsheet to be very big, performance to bepoor, and consistent modifications will be difficult to manage across all ofthe sheets.)

Note: Only one Iterative Linkset per Excel and Word Bridge can be enabled.

264 14 Bridge

Creating and Editing an Iterative Linkset1 Launch the Bridge application and connect to a workspace.

2 Click File | Open Bridge (or click the Open Bridge toolbar icon) to displaythe Open Bridge dialog, select a Bridge and click the OK button.

3 Click Linkset | Properties (or click the Linkset Properties toolbar icon) todisplay the Linkset Properties dialog.

4 Check the Iterative box and select Link | New to display a blank row forthe new Iterative Linkset.

5 Enter a route for the Class. If necessary, use the Class View Selectordialog to navigate the class hierarchy and select the class.

6 Enter the Case Name from the drop-down list of the Cases in theworkspace. If the Case is not specified, the Iterative Linkset uses thebridge or workspace default (represented as <default> in the Case field).

7 Enter the Unit Standard name from the drop-down list of current UnitStandards specified in the workspace and available for selection. If theUnit Standard is not specified, the Iterative Linkset uses the bridge orworkspace default Case (represented as <default>).

8 Enter a name for the Iterative Linkset. The default is the object’s name.

9 Enter text into the Description field for documentation or instructions onhow to use.

10 Using the information from the Links contained in the Iterative Linkset,the system displays the derived export and import status. IterativeLinksets can be persistently enabled or disabled.

Note:Cut/Copy/Paste Operation.Iterative Linksets can be edited using standard cut/copy/paste operations toduplicate existing Iterative Linksets from this bridge and from other bridges.

Conversions between Iterative Linksetsand LinksetsIterative Linkset to Linkset:

Select an Iterative Linkset row and uncheck the Iterative box to convertit to a linkset. The title in the Object field **Iterative** is removed. Ifthere is a list of objects in the Iterative Linkset, the first object is used inthe linkset.

Linkset to Iterative Linkset:

Select a linkset and check the Iterative box to convert it to an IterativeLinkset. The title in the Object field changes to **Iterative**. The systemuses the class information to create the list of objects.

14 Bridge 265

Export PackagePackages exported from the Bridge contain the data of the linked objectssaved externally in an XML format. They can then be used to transfer databetween workspaces. They are imported into other workspaces by using theImport Package option from the Workspace Explorer. This provides amechanism for organizations, sites or projects to collaborate with each other.

To create a package:

Select the Export Package menu option when you are in the Bridge View.This displays the Export Package dialog from where you can specify thename of the file to be exported.

The following is exported:

o Data for those objects that are referenced by an enabled linkset. Onlydata for those attributes that appear in links are exported. This isdifferent to exporting a package from the explorer where all the datafor an object is exported.

o All enabled application files. These are exported to the same locationas that specified for the package file.This option can be switched off byclearing the “Include Application File” check box.

Exporting a Package Select the Folder | Export Package menu option to display the Export

Package dialog.

This allows you to specify the package file name and to enter descriptivedata about the contents of the package file. The selected object can thenbe exported as a Package. The “Include Application File” check box shouldbe checked if you wish to also export the enabled application files withyour package. This option is selected by default.

Packages FolderPackage files may be placed in the folder defined by the PACKAGESparameter in the workspaces config. file. To use this file click the Librarybutton. Alternatively you can specify the folder for your packages by pressingthe Browse button. You can see which folder is being used for the export orimport of the package files in the “Current Folder” box. Application files arenot exported if you have selected to export the package to the PACKAGESfolder.

266 14 Bridge

15 Drawing Application Automation Objects 267

15 Drawing ApplicationAutomation Objects

This chapter contains information on using the Intergraph RAD developmentplatform to extend the functionality of the Aspen Basic Engineering drawingapplication.

Note: Any modifications to the Aspen Basic Engineering application detailedin this chapter should only be carried out by suitably qualified developers orprogrammers. This information is not intended for end-users.

To develop AddIns for the Aspen Basic Engineering Drawing Editor, your PCmust have the following:

Microsoft Windows 2000 or XP.

Internet Explorer 3.02 (or higher).

Visual Basic 6.0.

Visual C++ 6.0 (optional).

Visual Studio 6.0, SP3.

268 15 Drawing Application Automation Objects

Object Hierarchy

Application

Documents

Menus

Toolbars

Selectset

DynamicDisplay2D

HighlightList

Addins

Document

Menu

Toolbar

Addins

Toolbar Controls

Toolbar Control


Object Type Descriptions

Object Type Object Description

Application Application object

AddIns A collection of AddIn objects

AddIn An object representing an AddIn that has been inserted into theAddIns Collection object

Documents A collection of document objects

Document Defines document specific parameters and gives access todocument related objects

DynamicsDisplay2d

The DynamicsDisplay2d object provides a service for displayingtemporary objects

HighlightList A collection of objects to be display in an indicated color

Menus A collection of menu objects

Menu Menu object

SelectSet A SelectSet object is a temporary grouping of one or moreselected objects

ToolBars A ToolBars object is a collection of ToolBar objects

ToolBar A ToolBar object is a control bar window that contains bitmapcommand buttons

ToolbarControls ToolbarControls object

ToolbarControl ToolbarControl object

Application ObjectThe instance of the (Drawing Editor) drawing application.

AddIns and AddIn ObjectsAn AddIn is an OLE server that exposes several standard methods orproperties that allow developers to insert their workflow solution into arunning instance of a RAD2D-based application. You, as a developer, or yourend-users might want to customize an application by installing a set of toolsto enhance a specific workflow. For you, this set of tools might be a fewcommands or event handlers. For the end-user, the tools might includeadding or changing the application user interface. Both types of customizationare accomplished easily with add-ins.

AddIns can extend an application without providing an entirely newapplication. AddIns can also simplify an application’s user interface. Forexample, not all commands for the entire application are available when youinstall the product; some are available through the application’s add-ins.

270 15 Drawing Application Automation Objects

DynamicsDisplay2dThe platform provides non-persistent or transient objects that can be usedwhen implementing dynamics in commands. The three types of transientobjects are:

Geometry (GeometryServices objects such as lines and arcs).

Text.

Bitmaps.

For example, you can display the current length of a line, dynamically, as texton the cursor as you are placing the line. You can also display a bitmap on thecursor.

The DynamicsDisplay2d object is in the Object Library. You can use it todisplay objects in dynamics. Use the following table to determine the correctmethod to use for each object.

To display this object Use this method

Geometry DynamicsDisplay2d.AddGeometry

Text DynamicsDisplay2d.AddText

Bitmaps DynamicsDisplay2d.AddImage

Call one method for each object you want to display.

For example:

To display three bitmaps, call the DynamicsDisplay2d.AddImage methodfor each bitmap – a total of three calls to the AddImage method.

To display two GeometryServices objects, call theDynamicsDisplay2d.AddGeometry method for each GeometryServicesobject – a total of two calls to the AddGeometry method.

HighlightListA collection of references to objects to be displayed in the highlight color.

Menus and Menu ObjectsThe Menus and Menu objects option allows you to customize the Aspen BasicEngineering application menus as required.

In addition to toolbars, menus are one of the main ways of organizing andmaking commands available to the end-user. The main advantage menushave over toolbars is that menus can be hierarchical (sub-menus withinmenus). Generally however, this hierarchy doesn't extend beyond 3 or 4menus deep.

Adding, Removing and Modifying Menus

To add, remove, or modify menus in the application, you must access theMenus collection on the Application object. From there, the Menus collectionand any Submenus collections can be traversed when you use the methodsand properties for the Menus and Menu objects.


Note: To create sub-menus you need to make sure that you add a menu itemof the type igcmdPopup. For example:Set objMenu = objMenus.Append("MyMenu", igcmdPopup.

SelectSetA collection of references to objects considered as ‘selected by’.

ToolBars and Toolbar ObjectsToolBars are dockable control bars added to the main application window.ToolBars can be used to customize the look and feel of your application. Youcan use them to give easy access to commands. Each toolbar contains one ormore buttons. Each button represents a command that can be started bypressing the button. The drawing application sets up a default set of toolbarsthat can be customized.

To add toolbars to your application, access the ToolBars collection object onthe Application object and add a ToolBar object. Next, add one or morecontrols to the ToolBar object.

Index

A

Adding a Query 194Administration 249Aspen Zyqad

opening a workspace 275overview 274

Aspen Zyqad Bridge 251Aspen Zyqad Query Language 195Assigning objects 75Attributes 102, 105AutoCAD symbols 102, 105Autolinking 70, 71available 3

B

Bitmap fieldsabout 71inserting 71, 72, 73

Broker Configuration 220Browser 63, 74

C

Casesmultiple 68

CLASS layer 103, 106Commands

dimlink 70, 71overspill 68setobject 75

Components of workspaces 215Configuration Management 216Conflict Resolution 235Controls

verifying 74Converting AutoCAD symbols

algorithm 104, 106exclusions 102, 105

ii Index

preparations 102, 105Creating a New Smartplant Project 231Creating Multiple Links 263

D

Data transferpiping systems 55

Datum attribute 102, 105Defining datasheets with Excel 57Defining summary sheets with Excel 57Development Application

launching 82Dimension fields

about 69inserting 69linking 70unlinking 70

Dimlink command 70, 71documentation 2

E

Extent attribute 102, 105

F

Field cases 68Fields

list 66

L

lass Library Editor 133Layers 103Linking

dimension fields 70multi-line fields 68revision fields 70

Log in to Aspen Zyqad 275Logging on to Workspaces and Projects 206

M

Managing Projects 227Managing the Scope of a Project 243Managing Users 240Managing Workspaces 213Manulinking 70, 71Multiline fields

about 68

Index iii

N

Named Parts attribute 103Network shares 217

O

Object/Case Bindings 264Objects

assigning 75setting starting 75

Objects, assigning 75OLE fields

about 71Opening

workspaces 275Overspill command 68Overspill fields

about 68

P

Packages 191PART NAMES layer 103Parts 103Piping systems

data transfer 55Piping Systems

about 49automated version 50

POINTS layer 102, 105Project Management Dialog 229Project Management within Aspen Zyqad 226

Q

Query Editor 192

R

Revision fieldsabout 70inserting 70linking 70unlinking 71

Routeswildcards 74

S

Schema browser 74Setobject command 75Sketch fields

about 71inserting 71

iv Index

Symbol Definer in AutoCAD 102, 105

T

Toolbar buttons 113, 137, 260, 261

U

UNC paths 217Unlinking

dimension fields 70revision fields 71

V

Validate Controls option 74Value fields

about 66dimensions 69grouping 68inserting 66linking to dimension fields 70routing from Browser 74

W

Wildcardsassigning 74

Working with Files 179Working with Folders 174Working with Objects 183Workspaces

components 215