UniSim Design

Customization Guide
Copyright
June 2005 R350 Release

The information in this help file is subject to change over time. Honeywell may make
changes to the requirements described. Future revisions will incorporate changes,
including corrections of typographical errors and technical inaccuracies.

For further information please contact

Honeywell
300-250 York Street
London, Ontario
N6A 6K2
Telephone: (519) 679-6570
Facsimile: (519) 679-3977

Copyright Honeywell 2005. All rights reserved.

Prepared in Canada.
 Table of Contents
1 Introduction ......................................................... 1-1
1.1 Customization.................................................. 1-2
1.2 Automation & Extensibility................................. 1-3
1.3 Customizing UniSim Design ............................... 1-7

2 Automation........................................................... 2-1
2.1 Introduction .................................................... 2-2
2.2 Objects........................................................... 2-2
2.3 Automation Syntax........................................... 2-9
2.4 Key UniSim Design Objects...............................2-19
2.5 Example 1: The Macro Language Editor..............2-46
2.6 Example 2: Automation in Visual Basic...............2-52

3 Extensibility ......................................................... 3-1

3.1 Introduction .................................................... 3-3
3.2 Implementing Interfaces ................................... 3-5
3.3 Data Types...................................................... 3-6
3.4 Extension Development Kit ................................ 3-7
3.5 Creating an Extension ....................................... 3-8
3.6 Registering Extensions .....................................3-17
3.7 Extension Interface Details ...............................3-21
3.8 Extension Reaction Kinetics ..............................3-22
3.9 Extension Property Packages ............................3-41
3.10 Extension Unit Operations ................................3-47
3.11 References .....................................................3-76

4 Extension View Editor........................................... 4-1

4.1 Introduction .................................................... 4-3
4.2 Using the View Editor........................................ 4-8
4.3 Widget Properties............................................4-28

iii
5 User Variables ...................................................... 5-1
5.1 Introduction .................................................... 5-2
5.2 Adding a User Variable...................................... 5-2
5.3 Importing/Exporting User Variables .................... 5-6
5.4 User Variable View ........................................... 5-8
5.5 Data Types.....................................................5-10
5.6 User Variables Tabs .........................................5-13
5.7 Code Editor ....................................................5-21
5.8 User Variable Examples....................................5-22

6 User Unit Operation .............................................. 6-1

6.1 Introduction .................................................... 6-2
6.2 Adding a User Unit Operation............................. 6-2
6.3 User Unit Op Property View ............................... 6-5
6.4 Dehumidifier Example......................................6-12

A Customization FAQ ...............................................A-1

A.1 Automation FAQ............................................... A-2
A.2 Extensibility FAQ ............................................ A-10

Index.................................................................... I-1

iv
 Introduction 1-1

1 Introduction

1.1 Customization ................................................................................ 2

1.2 Automation & Extensibility............................................................. 3

1.2.1 Automation ............................................................................. 3
1.2.2 Extensions .............................................................................. 4

1.3 Customizing UniSim Design ........................................................... 7

1.3.1 UniSim Design & the Macro Language Editor ................................ 8
1.3.2 Programming UniSim Design from External Programs.................. 10

1-1
1-2 Customization

1.1 Customization
Unlike its accompanying volumes, the Customization Guide does
not discuss exact procedures for accomplishing tasks within
UniSim Design. The purpose of this volume is to demonstrate
the possible simulation technologies that can be created both
within UniSim Design and also in addition to the application.
UniSim Design incorporates an advanced software architecture
and OLE Technology to provide a component-based framework
that can be easily customized, updated and maintained to meet
changing user requirements.

The term customization encompasses several different

approaches for tailoring UniSim Design including:

Method Description
Automation The use of third party tools such as Visual Basic or the
UniSim Design Macro Language Editor to programmatically
run UniSim Design.
Extensibility The creation of custom unit operations, property packages
and kinetic reactions which become part of the simulation
and function as built in UniSim Design objects.

The difference between automation and extensibility may not be

explicitly apparent. The difference lies in the environment in
which your personal algorithms are executed. Automation
requires the use of third party software to link to UniSim Design
in a client-server relationship. Using this functionality, you can
hide the complexity of a simulation by building a front-end in
another program that allows access to only the important
parameters of the simulation. You can also use UniSim Design
as a server in your own applications. UniSim Design is an
Automation Server, which means that it can act as an
Automation client that can be used to access UniSim Design.
Some examples of tools that can access UniSim Design are
Microsoft Visual Basic and the VBA component of applications
such as Excel, Word, PowerPoint and Visio. You can also access
UniSim Design through programs written in C++.

Extensibility incorporates your custom algorithms in the form of

Extension Property Packages, Extension Unit Operations, and
Extension Reaction Kinetics. The calculations take place within

1-2
 Introduction 1-3

the calculation sequence of a UniSim Design simulation.

Extensions can be easily distributed to other machines, and they
appear as any other UniSim Design object in the program. You
could easily develop an extension, test it, market it and sell it to
other UniSim Design users as a third party add-in.

The Customization Guide’s purpose is threefold:

• To introduce the user to the functionality of UniSim
Design automation and extensibility.
• To demonstrate different methods of accessing and using
UniSim Design objects.
• To provide straightforward examples that teach you the
basics and allow you to begin customizing UniSim
Design.

Within the UniSim Design environment, several tools are

provided so you can begin writing code for automation and
extensions:

Tool Description
The Macro Language An interactive design environment for developing,
Editor testing and executing WinWrap basic scripts.
For more information on User Variables and the Allow you to increase the functionality of UniSim
User Variables and User User Unit Operation Design by creating your own variables or unit
Unit Ops see Chapter 5 operations.
- User Variables and
Chapter 6 - User Unit
Operation.
1.2 Automation &
Extensibility
1.2.1 Automation
Automation allows programmers to expose objects within a
program for use by other applications. The exposed objects
provide the means by which different applications can interact
with each other and the operating system. Automation is a
standard based on Microsoft's Component Object Model (COM).
It is not necessary to understand all the intricacies of
Automation or COM in order to utilize the functionality they
provide.

1-3
1-4 Automation & Extensibility

Automation evolved from what was once called OLE, which

stands for Object Linking and Embedding. This allowed you to
take a particular object such as a spreadsheet and embed it into
another object such as a text document. Changes to values in
the spreadsheet would automatically be updated in the text
document. This was a very powerful feature and was available to
users without the added complexity of writing code. It was
simply a matter of cutting and pasting the objects.

Automation is the ability to programmatically interact with an

application through objects exposed by developers of that
application. While UniSim Design was being developed, code
was added to expose various objects in the program. By using
an Automation client like Visual Basic, the end user can write
the code to access these objects and interact with UniSim
Design. The end user does not need to see the UniSim Design
source code or even understand what was required to expose
the objects. All that is required is the knowledge of those
objects that are available.

Automation works in a client/server fashion. A server is

something that provides a service that can be used by clients if
they know the proper protocols. UniSim Design is an Automation
server application. By writing a little Visual Basic code, it is
possible to send and receive information to and from UniSim
Design. The exposed objects make it possible to perform nearly
any action that is accomplished through the UniSim Design
graphical user interface.

You can use Automation to access UniSim Thermo in UniSim

Design to calculate UniSim Thermo properties such as fugacity
coefficients, K-values, entropy, and enthalpy

1.2.2 Extensions
The UniSim Design architecture allows direct extensibility for
unit operations, kinetic reactions, and property packages.
Extensibility can be described as the ability to augment existing
functionality in a direct and seamless manner. Unit operation
extensions look and feel like the existing operations in UniSim
Design but the algorithms used by the extension reside in a

1-4
 Introduction 1-5

separate Windows DLL. Similarly, kinetic reaction extensions

and property package extensions appear seamlessly in the basis
environment.

A UniSim Design extension is typically composed of two distinct

and interdependent components; an ActiveX Server DLL and an
Extension Definition File (EDF). The ActiveX Server DLL contains
the actual code for the extensions and can be created in any
OLE controller language such as Visual Basic, C++, or Delphi.
Nearly any other type of compiled code base can be accessed
via a short wrapper utilizing Visual Basic or C++. The Server is a
program that exposes a class with a set of properties and
methods. For UniSim Design extensions, the exposed class
contains methods recognized by UniSim Design (for example,
when dealing with a Unit Operation Extension, UniSim Design
looks for a method named Initialize that takes one argument
and returns a long variable).

The EDF file acts as the interface view within UniSim Design as
well as the point for variable declaration and storage. It is
created through the Extension View Editor which is included with
your copy of UniSim Design. The View Editor is similar to the
tool used by Honeywell Developers when creating the views for
UniSim Design.

How Does a UniSim Design

Extension Work?
When UniSim Design first starts up, it looks in the system
registry, at a specific location, to see if any extensions exist for
the machine. If an extension does exist it is added to the
appropriate menu within UniSim Design. Unit operation
extensions show up in the UnitOps view when the Extensions
radio button is selected. Kinetic reaction extensions show up in
the Reactions view which is brought up when the Add Rxn
button is clicked on the Reactions tab of the Simulation Basis
Manager property view. Property package extensions show up in
the Property Package Selection group found on the Set Up tab of
the Fluid Package property view.

1-5
1-6 Automation & Extensibility

Once you find the appropriate extension, you can select it and
begin using it as though it were a built-in UniSim Design object.

1-6
 Introduction 1-7

1.3 Customizing UniSim

Design
UniSim Design can be programmatically run from any tool that
supports Automation. You can set up scripts that do repetitive
tasks, or you can set up programs of your own that uses UniSim
Design as the calculation engine.

For example, the simulation of a plant can be easily hidden by a

front-end created in Microsoft Excel. This front-end could be a
yield prediction program of some sort that uses a rigorous
simulation underneath. Another example would be a proprietary
equipment sizing program that uses UniSim Design to generate
fluid properties for the calculations.

When creating these programs, UniSim Design can be run

invisibly. You do not need to know the source of the calculations,
nor do you need to deal with another program on the desktop.

Third party tools are not required to access the automation

capabilities of UniSim Design. UniSim Design provides an
Internal Macro Engine that supports the same syntax as
Microsoft Visual Basic. With this engine, you can automate tasks
in UniSim Design without the need for another program.

1-7
1-8 Customizing UniSim Design

1.3.1 UniSim Design & the

Macro Language Editor
For more information on The Macro Language Editor is accessed by selecting the Macro
the Macro Language
Language Editor command from the Tools menu in the
Editor, consult the online
help that accompanies Simulation environment.
the editor. You can find
the online help in the
Figure 1.1
Help menu in the Editor’s
menu bar.

The editor is an interactive design environment for developing,

testing and executing WinWrap Basic automation scripts. The
editor, which uses a syntax that is very similar to Microsoft®’s
Visual Basic, allows you to write code that interacts with UniSim
Design.

Two objects can be accessed directly from any point in a macro:

• Application
• ActiveCase

These special commands allow you to generalize your macros so

that they can be run under many different situations. If you
reference the ActiveCase object, your macro works for any
Simulation Case that is currently open in the UniSim Design
environment.

1-8
 Introduction 1-9

The Macro Language Editor now has two new features:

• Autocompletion feature, which helps you complete the
user variable codes and helps you debug the program
with flyby evaluation.
For example, if you want to specify “SimulationCase”,
you just need to type up the first few letters of the
variable, and the autocompletion feature will display all
variables with similar names in a drop-down list.

Figure 1.2

• List command feature, which shows you a list of valid

methods or properties depending on the context (type of
expression) you enter.
For example, if you type ActiveObject and type the
period, a drop-down list appears displaying a list of
methods that are applicable to the current object.

Figure 1.3

1-9
1-10 Customizing UniSim Design

1.3.2 Programming UniSim

Design from External
Programs
UniSim Design can be accessed from external programs using
Automation. Programs such as Microsoft Visual Basic and
Microsoft Excel can use UniSim Design as a calculation engine,
allowing you to create new applications that invisibly use UniSim
Design in the background.

Two UniSim Design objects can be created by an external

program:
• The UniSim Design Application object
• The UniSim Design SimulationCase object

The Application object can be created using the UniSim

Design.Application ProgID. Simulation Cases can be created
using the UniSim Design.SimulationCase ProgID, or by calling
GetObject and passing the name of a Simulation Case. For
example, this is how you would create an Application object and
a SimulationCase object from Visual Basic:

Dim App as Object

Set App = CreateObject(“UniSimDesign.Application”)
Dim HYCASE as Object
Set HYCASE = GetObject(“c:\UniSim
Design\cases\azeocol.usc”)

Once the Application and Case objects have been created, other
UniSim Design objects can be accessed through them. For
example, from the Case's flowsheet object (accessed through
the flowsheet property of the Case), you can create new Process
Streams and Unit Operations.

1-10
 Introduction 1-11

VBA
Microsoft Excel and related products make use of Visual Basic
for Applications (VBA). VBA is a high level programming
language that is oriented around an object framework and event
driven execution. Visual Basic is termed “visual” because most
applications are created around a graphical interface and Visual
Basic is designed to allow code associated with the interface to
be added easily and intuitively.

Event driven programming is quite different from typical

structured programming. In a structured program, execution
begins at the top of the program and executes for the most part
in a sequential manner. When the bottom of the program is
reached the application exits and is finished. In event driven
programming, the path of execution from the beginning of the
program to the end depends almost entirely on how the end
user interacts with the application.

Visual Basic for Applications is a large sub-set of the Visual Basic

language. It is a macro language that is integrated tightly in to
supporting applications. The syntax and functionality is identical
to straight Visual Basic.

1-11
1-12 Customizing UniSim Design

1-12
 Automation 2-1

2 Automation

2.1 Introduction................................................................................... 2

2.2 Objects .......................................................................................... 2

2.2.1 Object Hierarchy ...................................................................... 3
2.2.2 UniSim Design Type Library ....................................................... 4
2.2.3 Object Browser ........................................................................ 5

2.3 Automation Syntax ........................................................................ 9

2.4 Key UniSim Design Objects .......................................................... 19

2.4.1 UniSim Design Object Overview ............................................... 19
2.4.2 Container Objects................................................................... 19
2.4.3 Basis Objects......................................................................... 22
2.4.4 Oils Objects........................................................................... 27
2.4.5 Stream Objects...................................................................... 30
2.4.6 Operation Objects .................................................................. 35
2.4.7 Support Objects ..................................................................... 39
2.4.8 PFD Objects........................................................................... 45

2.5 Example 1: The Macro Language Editor........................................ 46

2.6 Example 2: Automation in Visual Basic ........................................ 52

2-1
2-2 Introduction

2.1 Introduction
Automation, defined in its simplest terms, is the ability to drive
one application from another. For example, the developers of
Product A have decided in the design phase that it would make
their product more usable if they exposed Product A’s objects,
thereby making it accessible to Automation. Since Products B, C
and D all have the ability to connect to applications that have
exposed objects, each can programmatically interact with
Product A.

In the early product planning stages, the UniSim Design

development team had the vision to begin exposing objects.
That, makes UniSim Design a very powerful and useful tool in
the design of hybrid solutions. Since access to an application
through Automation is language-independent, anyone who can
write code in Visual Basic, C++ or Java, to name three
languages, can write applications that interact with UniSim
Design. There are a number of applications that can be used to
access UniSim Design through Automation, including Microsoft
Visual Basic, Microsoft Excel and Visio. With so many
combinations of applications that can transfer information, the
possibilities are numerous and the potential for innovative
solutions is endless.

2.2 Objects
The key to understanding Automation lies in the concept of
objects. An object is a container that holds a set of related
functions and variables. In Automation terminology, the
functions of an object are called methods and the variables are
called properties.

Consider the example of a simple car. If it were an object, a car

would have a set of properties such as: make, colour, number of
doors, etc. The car object may also have methods such as: turn
on, drive or open hood. By utilizing the properties and methods
of a car object it is possible to define, manipulate and interact
with the object.

2-2
 Automation 2-3

Figure 2.1

Object: Car

Properties: Colour, Make, Engine Methods: Drive, Refuel

Each property of the car is a variable that has a value associated

with it. The colour would be a string or hexadecimal number
associated with a specific colour. The gas mileage would be
single floating point value. Methods are nothing more than
functions and sub-routines associated with the object.

An object is a container that holds all the attributes associated

with it. An object could contain other objects that are logical
sub-set of the main object. The car object may contain other
objects such as engine or tire. These objects would have their
own set of independent properties and methods. An engine
would have properties related to the number of valves and the
size of the pistons. The tires would have properties such as
tread type or model number.

2.2.1 Object Hierarchy

The path that is followed to get to a specific property may
involve several objects. The path and structure of objects is
referred to as the object hierarchy. In Visual Basic the properties
and methods of an object are accessed by hooking together the
appropriate objects through a dot operator (.) function. Each dot
operator in the object hierarchy is a function call. In many cases
it is beneficial to reduce the number of calls by setting
intermediate object variables.

2-3
2-4 Objects

For instance, expanding on our previous example involving the

car, suppose there existed an object called Car and you wanted
to set the value of its engine size. You could approach the
problem in one of two ways.

Direct specification of object property

Car.Engine.Size = 4
Indirect specification of object property
Dim Eng1 as Object

Set Eng1 = Car.Engine.Size

Eng1 = 4

If the Engine size is a property you wanted to access quite often

in your code, using the indirect method of specification may be
easier as it reduces the amount of code thereby reducing the
possibility of error.

2.2.2 UniSim Design Type

Library
In order to do anything with objects it is first necessary to know
what objects are available. When an application is exposed for
Automation, a separate file is usually created that lists all the
objects and their respective properties and methods. This file is
called the type library and nearly all programs that support
Automation have one of these files available. With the help of an
Object Browser, such as the one built in to MS Excel, you now
have a way to view all the objects, properties, and methods in
the application by examining the type library.

The UniSim Design type library reveals over 340 objects that
contain over 5000 combined properties and methods. For every
object, the type library shows its associated properties and
methods. For every property, the type library shows its return
type. For every method, the type library shows what type of
arguments are required and what type of value might be
returned.

Accessing a specific property or method is accomplished in a

2-4
 Automation 2-5

hierarchical fashion by following a chain of exposed objects. The

first object in the chain should be an object from which all other
objects can be accessed. This object is typically the main
application or one of the open documents. In UniSim Design, the
starting objects are the SimulationCase and Application objects.
All other objects are accessible through these two starting
objects.

2.2.3 Object Browser

The type library itself does not exist in a form which is
immediately viewable to you. In order to view the type library,
you require the use of an application commonly referred to as
an Object Browser. The Object Browser interprets the type
library and displays the relevant information. Microsoft Excel
and Visual Basic both include a built in Object Browser.

Accessing the Object Browser in

Excel 97/2000/XP
1. Open the Tools menu.
2. Press ALT F11 (or select the Visual Basic Editor option
from Macro group).
3. Within the Visual Basic Editor, open the Tools menu.
4. Select the References command.
5. Check the checkbox next to the UniSim Design 3.X Type
Library.
6. Click the OK button.
7. Open the View menu and select the Object Browser
command (or press F2).
8. Open the Libraries/Workbooks drop-down list and select
UniSimDesign.

2-5
2-6 Objects

Navigating Through the type Library

This section shows how to navigate through the type library in
order to determine the object hierarchy necessary to access a
particular property. Consider the desired property is the
temperature of a stream called “Feed_Stream”.

The first step is to begin with one of the starting objects. The
Application and SimulationCase objects are the starting points in
UniSim Design. You can visualize what is available from the
Application object by picturing the UniSim Design application
view when the program is first started. You can do the same
with the SimulationCase object by thinking of all the information
contained within a case. Nearly all the objects of interest are
accessed from the SimulationCase object.

Figure 2.2

Selecting the SimulationCase object in the browser reveals all of

its related properties and methods. Examining the list of
properties does not reveal any type of stream like object so
there must be a connection through another object. The
properties that are links to other objects can be determined by
looking at the type shown when a property is selected. If the
type shown is not a string, Boolean, variant, double, integer, or
long then it is most likely an object. The object type shown is
found somewhere in the object list and is the next step to
determining the object hierarchy.

2-6
 Automation 2-7

With prior experience in UniSim Design the flowsheet object is a

logical choice. Selecting the flowsheet object in the object list
shows the associated properties and methods. There is an
EnergyStreams property, a MaterialStreams property, and a
Streams property. All three of these properties are of type
Streams and are therefore objects. In this case some previous
experience in using UniSim Design would suggest that
MaterialStreams is the object of interest.

Figure 2.3

The MaterialStreams object is of type Streams. Examining the

Streams object does not reveal any temperature properties. The
Streams object is a collection object, which is simply an object
that is a collection of other objects with some properties and
methods for navigating through the collection.

2-7
2-8 Objects

In this case the Streams object is a collection of ProcessStream

objects.

Figure 2.4

The individual members of a collection object can be accessed

by index number (like an array) or directly by name. Either
approach can be used through the Item property. Examining the
ProcessStream object shows a property called
TemperatureValue, which is of type Double. This is the desired
property.

Figure 2.5

2-8
 Automation 2-9

The resulting syntax for the desired property is:

SimulationCase.Flowsheet.Streams.
Item(“Feed_Stream”).TemperatureValue

2.3 Automation Syntax

Declaring Objects
An object in Visual Basic is another type of variable and should
be declared. Objects can be declared using the generic type
identifier object. The preferred method however uses the type
library reference to declare the object variables by an explicit
object name.

Early Binding:
Dim|Public|Private objectvar As ObjectName as
specified in the type library
Late Binding:
Dim|Public|Private objectvar As Object

Once a reference to the type library has been established, the

actual name of the object as it appears in the type library can be
used. This is called early binding. It offers some advantages
over late binding, including speed and access to Microsoft’s
Intellisense® functionality when using Visual Basic or VBA.

Example: Late Binding

Public hyCase As Object
Public hyStream As Object
Example: Early Binding
Public hyCase As SimulationCase
Public hyStream As ProcessStream

2-9
2-10 Automation Syntax

Set Keyword
Connections or references to object variables are made by using
the Set keyword.

Syntax:
Set objectvar = object.[object…].object | Nothing

The example below assumes hycase is set to the SimulationCase

object.

Example: Set
Dim hyStream As ProcessStream
Set hyStream =
hyCase.Flowsheet.MaterialStreams.Item(0)

GetObject, CreateObject
In order to begin communication between the client and server
applications, an initial link to the server application must be
established. In UniSim Design this is accomplished through the
starting objects: Application or SimulationCase. The typical
ActiveX object structure supplies a starting object to access the
application interface and another to access the documents
within the application.

Syntax for creating an instance of an application:

CreateObject(class)

GetObject([pathname] [, class])

where:

class = the starting object as specified in the type library.

In UniSim Design there are two objects that can be
used for the class statement:
UniSimDesign.Application or
UniSimDesign.SimulationCase.

2-10
 Automation 2-11

The CreateObject function starts a new instance of the main

application. CreateObject is used in UniSim Design with the
UniSim Design.Application class as specified in the type library.
This connects to the main application interface of UniSim
Design.

The GetObject function opens a specific document in the

currently running instance of the server application. If the
application is not running then a new instance of the application
starts. If a specific document is not specified with the GetObject
function the current instance of the application is connected or a
new instance of the application is started.

For application objects or document objects the codes are shown

below:

Example: CreateObject and GetObject

Set applicationobj =
CreateObject(“UniSimDesign.Application”)
or
Set applicationobj = GetObject(,
“PROGRAM.Application”)

Set documentobj = GetObject(“c:\filepath”,

“PROGRAM.Document”)

In the example below, hyCase is declared as type object so it is

using late binding. The hyCase variable is connected to a UniSim
Design case by using the GetObject function and the Set
keyword. The second argument in the GetObject function is the
starting object.

Example 1: Starting a UniSim Design case through

Automation
Dim hyCase As Object
Set hyCase = GetObject(“c:\samples\c-2.usc”, “UniSim
Design.SimulationCase”)

2-11
2-12 Automation Syntax

The second example is identical to the first except that the

object variable hyCase is declared using the actual object name
as it appears in the type library. This assumes that a reference
to the type library has already been set.

Example 2: Starting a UniSim Design case through

Automation
Dim hyCase As SimulationCase
Set hyCase = GetObject(“c:\samples\c-2.usc”,
“UniSimDesign.SimulationCase”)

The third example uses early binding in the object declaration.

The CreateObject command is used to bring up an instance of
UniSim Design. The starting object here is the UniSim
Design.Application object since a case is not initially being
opened. The SimulationCases object is accessed through the
Application object and the Open method of SimulationCases is
used to bring up a specific UniSim Design case. The hyCase
object is set to the active case through the ActiveDocument
property of hyApp.

Example 3: Starting a UniSim Design case through

Automation
Dim hyCase As SimulationCase
Dim hyApp As UniSimDesign.Application
Set hyApp = CreateObject(“UniSimDesign.Application”)
hyApp.SimulationCases.Open(“c:\UniSim
Design\samples\c-2.usc”)
Set hyCase = hyApp.ActiveDocument

2-12
 Automation 2-13

Object Properties, Methods, &

Hierarchy
The sequence of objects is set through a special dot function.
Properties and methods for an object are also accessed through
the dot function. It is preferable to keep the sequence of objects
to a minimum since each dot function is a call to link between
the client and the server application.

Syntax for setting objects and accessing properties:

Set objectvar = object.[object.object...].object
Variable = object.[object.object...].property
Syntax for accessing methods:
Function Method
returnvalue = object.method([argument1,
argument2,...])

Sub-routine Method
object.method argument1, argument2

The object hierarchy is an important and fundamental concept

for utilizing Automation. A particular property can only be
accessed by following a specific chain of objects. The chain
always begins with either the Application or SimulationCase
object and ends with the object containing the desired property.

The methods of an object are accessed in the same fashion as

properties by utilizing the dot function. A method for a particular
object is nothing more then a function or sub-routine whose
behaviour is related to the object in some fashion.

Sub-routines in Visual Typically the methods of an object require arguments to be

Basic do not require passed when the method is called. The type library provides
parentheses around the
argument list. information about which arguments are necessary to call a
particular method. A function returns a value.

2-13
2-14 Automation Syntax

The example below, starts up UniSim Design and opens a

specific case. The temperature value of a specific stream is then
obtained. The temperature value is obtained through a
connection of three objects: SimulationCase, Flowsheet, and
MaterialStreams.

Example 1: Accessing UniSim Design object properties

Dim hyCase As SimulationCase
Dim TempVal As Double
Set hyCase = GetObject(“c:\c-
2.usc”,”UniSimDesign.SimulationCase”)
TempVal =
hyCase.Flowsheet.MaterialStreams.Item(0).TemperatureV
alue
MsgBox TempVal

The example below, also accesses the temperature value of a

specific stream but creates some intermediate objects so that
when the temperature value is actually requested the chain of
objects only contains one object.

Example 2: Accessing UniSim Design object properties

Dim hyCase As SimulationCase
Dim hyFlowsheet As Flowsheet
Dim hyStream As ProcessStream
Dim TempVal As Double
Set hyCase = GetObject(“c:\samples\c-2.usc”,
“UniSimDesign.SimulationCase”)
Set hyFlowsheet = hyCase.Flowsheet
Set hyStream =
hyCase.Flowsheet.MaterialStreams.Item(0)
TempVal = hyStream.TemperatureValue
MsgBox TempVal

2-14
 Automation 2-15

Collection Objects
A collection object is an object that contains a set of other
objects. This is similar to an array of objects. The difference
between an array of objects and a collection object is that a
collection object contains a set of properties and methods for
navigating and manipulating the objects in the collection.

Syntax: Typical Properties of a Collections Object

Item(index) Accesses a particular member of the collection by

number.

Index(name) Determines the index number for a member in

the collection by its name.

Count Returns the number of objects in the collection.

Syntax: Enumeration of Objects

For Each element In group
[statements]
[Exit For]
[statements]
Next [element]

The most commonly used properties are:

• Index. The Index property takes in a name and returns
a number value associated with the object’s name.
• Item. The Item property takes an index value or name
or integer number as the argument and returns a
reference to the object within the collection.
• Count. The Count property returns the number of items
in the collection.

A special type of For loop, called For Each, is available for

enumerating through the objects within the collection. The For
Each loop provides a means for enumerating through the
collection without explicitly specifying how many items are in
the collection. This helps avoid having to make additional
function calls to the Count and Item properties of the collection
object in order to perform the same type of loop.

2-15
2-16 Automation Syntax

The example below, connects to a collection of streams by

setting the hyStreams object. A For loop is created that uses the
Count and Item properties of a collection in order to display a
view that contains the stream name. The items in the collection
are indexed beginning with 0. The Count property returns the
actual number of objects in the collection so it is necessary to
subtract one in order to access all the objects in the collection.

Example 1: Accessing Collection Objects

Dim hyStreams As Streams
Dim hyStream As ProcessStream
Set hyStreams = hyCase.Flowsheet.MaterialStreams
For j = 0 To hyStreams.Count - 1
MsgBox hyStreams.Item(j).name
Next j

The example below, is identical to the first example except that

a For Each loop is used instead of the standard For loop in order
to enumerate through the Streams collection.

Example 2: Accessing Collection Objects

Dim hyStreams As Streams
Dim hyStream As ProcessStream
Set hyStreams = hyCase.Flowsheet.MaterialStreams
For Each hyStream In hyStreams
MsgBox hyStream.name
Next hyStream

2-16
 Automation 2-17

Variants
A property can return a variety of variable types. Values such as
temperature and pressure are returned as doubles or 32-bit
floating-point values. The stream name property returns a string
value. Visual Basic provides an additional variable called a
variant. A variant is a variable that can take on the form of any
type of variable including, Integers, Double, String, Array, and
Objects.

Syntax for using variant values

Dim myvariant as Variant
myvariant = {object.property}
To determine the upper and lower bound of the variant:
UBound(arrayname[,dimension])
LBound(arrayname[,dimension])

If the property of an object returns an array whose size can vary

depending upon the case, then a variant is used to access that
value. For example, the ComponentMassFractionValue property
of a ProcessStream returns an array of doubles sized to the
number of components associated with that stream.

In Visual Basic, if a variable is not explicitly declared then it is

implicitly a variant. Variants have considerably more storage
associated with their use, so for a large application it is good
practice to limit the number of variants being used. It is also just
good programming practice to explicitly declare variables
whenever possible.

The dimensions of the array depend upon what property is being

called. The following table lists the most common properties
that return arrays and what is the dimension of the array.

Common Variant of UniSim Design Returning Property

Component Mass Fractions One Dimensional array
Column Component Fraction Values Two Dimensional array
Interaction Parameters Two Dimensional array

2-17
2-18 Automation Syntax

The example below, shows how to get an array of stage

pressures in a column. The hyOp object is declared as a
ColumnOp as specified in the type library. The operations
collection is filtered to only include columns by using the word
“ColumnOp”. HyOp is set to the first column in the operations
collection. HyStagePressure is set equal to an array of doubles
returned by the ColumnOp object. Since the number of stages in
this column may not be known the Ubound function is used to
determine the upper bound of the one dimensional array. A view
prints out the pressure value for each stage in the column.

Example 1: Using Variants in UniSim Design

Dim hyOp As ColumnOp
Dim hyStagePressure As Variant
Set hyOp =
hyCase.Flowsheet.Operations(“ColumnOp”).Item(0)
hyStagePressure = hyOp.PressureValues
For j = 0 To UBound(hyStagePressure)
MsgBox “Stage “ & j +1 & “ Pressure = “ &
hyStagePressure(j)
Next j

The example below, accesses the VapourComponentFraction

property of a column. The array is set to hyStageCompFrac. This
array is two-dimensional. The first dimension represents the
components in the systems as specified in the fluid package.
The second dimension represents the stages in the column. A
view displays the vapour fraction of component 1 for each stage
of the column.

Example 2: Using Variants in UniSim Design

Dim hyOp As ColumnOp
Dim hyStageCompFrac As Variant
Set hyOp =
hyCase.Flowsheet.Operations(“ColumnOp”).Item(0)
hyStageCompFrac = hyOp.VapourComponentFraction
For j = 0 To UBound(hyStageCompFrac,2)
MsgBox “Stage “ & j +1 & “ Component 1 Vapour
Fraction = “ & hyStageCompFrac(0,j)
Next j

2-18
 Automation 2-19

2.4 Key UniSim Design

Objects
2.4.1 UniSim Design Object
Overview
There are over 340 automation objects exposed in UniSim
Design. These objects collectively contain of over 5000
properties and methods. One of the more time consuming and
difficult tasks in learning to use Automation objects is
determining what objects are available and how to get at a
property of interest.

The following sub-sections are designed to explore key UniSim

Design objects in more detail and hopefully provide the
necessary information required to access nearly any object,
property, or method in UniSim Design. Because of the large
number of key objects and their attributes, the objects within
UniSim Design have been divided in seven distinct categories.
These object categories are: Container Objects, Support
Objects, Oil Objects, Basis Objects, Stream Objects, Operation
Objects, Extension Objects, and PFD Objects.

2.4.2 Container Objects

This category refers to objects that house other objects or form
the basis from which a large number of objects are derived. For
instance, the Application object can contain several
SimulationCase objects. The SimulationCase object contains all
the remaining objects associated with that case. The flowsheet
object is a repository for all the streams and unit operations of
the case. The flowsheet can also contain another flowsheet,
Application or SimulationCase.

2-19
2-20 Key UniSim Design Objects

Application and SimulationCase

The Application object is the top most object in UniSim Design
and represents the UniSim Design program itself. From the
Application object, nearly all the objects listed in the UniSim
Design type library can be accessed. The SimulationCase object
is the starting object for accessing or opening specific simulation
cases.

Syntax: Connecting to the Application

Set hyApp = CreateObject(“UniSimDesign.Application”)
Syntax: Connecting to the Simulation Case
Through GetObject
Set hyCase = GetObject(“filepath”,
“UniSimDesign.SimulationCase”)

Through the Application Object

Set hyCase = hyApp.ActiveDocument

Through SimulationCases Collection Object

Set hyCase = hyApp.SimulationCases.Item(“CaseName”)

The SimulationCase object and the Application object can be

created directly through the GetObject function in Visual Basic.
The CreateObject function can also be used to access the
Application object. In general the starting object for most
Automation procedures is the SimulationCase object.

The example below, uses the GetObject function to start-up

UniSim Design with the specified case.

Example 1: Accessing the UniSim Design Container Objects

Dim hyCase As SimulationCase
Set hyCase = GetObject(“c:\UniSim Design\cases\c-
2.usc”, “UniSimDesign.SimulationCase”)

2-20
 Automation 2-21

The example below, connects to the UniSim Design Application

object and enumerates through all the currently open cases. If a
case name matches the specified string then a SimulationCase
object is set to that case. The FOR loop cycles through the list of
cases based on the count value. In Visual Basic arrays and
collections are base 0 unless otherwise specified.

Example 2: Accessing the UniSim Design Container Objects

Dim hyApp As UniSimDesign.Application
Dim hyCases As SimulationCases
Dim hyCase As SimulationCase
Set hyApp = CreateObject(“UniSimDesign.Application”)
Set hyCases = hyApp.SimulationCases
For j = 0 To hycases.Count - 1
If hycases.Item(j).name = “ethanol.usc” Then
Set hyCase = hyCases.Item(j)
End If
Next j

Flowsheet(s)
The main flowsheet object is accessed through the
SimulationCase object. The flowsheet object is a container of all
the ProcessStream and Operations objects as well as a link to
the FluidPackage object associated with that flowsheet. Each
flowsheet and sub-flowsheet can have its own fluid package and
likewise its own property package and set of components. Sub-
flowsheets can be accessed from the main flowsheet object
through the flowsheet collection object.

Syntax: Flowsheet Object

Dim hyFlowsheet As Flowsheet

Set hyFlowsheet = hyCase.Flowsheet

The above syntax, shows how to connect to the flowsheet object

of the UniSim Design case. This assumes the hyCase variable is
already set to the SimulationCase object in UniSim Design. The
remaining examples in this module assume a SimulationCase
object 'hyCase' is already set.

2-21
2-22 Key UniSim Design Objects

The example below, shows how to connect to a sub-flowsheet of

a flowsheet. Sub-flowsheets are accessed from the main
flowsheet. The main flowsheet is accessed through the
SimulationCase.

Example: Connecting Flowsheets

Dim hyFlowsheet As Flowsheet
Dim hySubFlowsheets As Flowsheets
Dim hySubFlowsheet As Flowsheet
Set hyFlowsheet = hyCase.Flowsheet
Set hySubFlowsheets = hyFlowsheet.Flowsheets
Set hySubFlowsheet = hySubFlowsheets.Item(0)

2.4.3 Basis Objects

The Basis objects refer predominantly to objects handled by the
UniSim Design BasisManager. The BasisManager object in
UniSim Design is responsible for handling the global aspects of a
UniSim Design simulation case. These objects include reactions,
components, and property packages.

The BasisManager object is accessed through the

SimulationCase object. From the BasisManager object the
FluidPackages and HypoGroups collection objects are accessed.
Changing the objects accessed directly or indirectly through the
BasisManager such as FluidPackages, PropertyPackage,
Components, and Hypotheticals requires notification to the
UniSim Design simulation environment. The BasisManager
object contains methods that allow changes to the basis to take
place smoothly. The following methods must be used on the
outer limits of any code that makes changes to Basis objects.

Syntax: Changing Basis Values

SimulationCase.BasisManager.StartBasisChange
... changes to components, interaction parameters,
reactions, etc.
SimulationCase.BasisManager.EndBasisChange

2-22
 Automation 2-23

FluidPackage(s)
Although both examples of syntax shown below lead you to a
FluidPackage object, there are differences that exist which are
only apparent when attempting to use the fluid package.

Syntax: Accessing FluidPackages

From the BasisManager
SimulationCase.BasisManager.FluidPackages.Item(0)

From the Flowsheet

SimulationCase.Flowsheet.FluidPackage

The FluidPackages object returned by the BasisManager object

is a collection object containing all FluidPackage objects in a
case. Each FluidPackage object can have its own
PropertyPackage object and Components object. When you
access the fluid package in this way, changes can be made to
the property package and the list of components.

When obtaining a reference to the FluidPackage object from the

flowsheet object, you are accessing the one fluid package
associated with the flowsheet. You can view the property
package or component list of the FluidPackage object, however
you are not able to make any changes.

The example below, displays the number of FluidPackage

objects in a case and sets a FluidPackage object to the first
member of the FluidPackages collection.

Example: FluidPackage
Dim hyFluidPackages As FluidPackages
Dim hyFluidPackage As FluidPackage
Set hyFluidPackages =
hyCase.BasisManager.FluidPackages
MsgBox “Number of Fluid Packages = “ &
hyFluidPackages.Count
Set hyFluidPackage = hyFluidPackages.Item(0)

2-23
2-24 Key UniSim Design Objects

PropPackage (PropertyPackage)
The PropPackage object is accessed through the FluidPackage
object. Each FluidPackage object can have a single PropPackage
object. The type of property package can be determined through
the PropPackage TypeName property or through the
PropertyPackageName property of the FluidPackage object. Each
property package has a set of unique properties and methods
along with the common ones shared among all property
packages.

Syntax to determine the type of property package

SimulationCase.BasisManager.Fluidpackages.Item(0).Pro
pPackage.TypeName
or
SimulationCase.BasisManager.Fluidpackages.Item(0).Pro
pertyPackageName

The example above, connects to the FluidPackages collection

object and checks each member FluidPackage to see if it
contains the PengRobinson property package.

Example: Property Package

Dim hyFluidPackages As FluidPackages
Dim hyFluidPackage As FluidPackage
Dim hyBasis As BasisManager
Dim hyPropPackage As PropPackage
Set hyBasis = hyCase.BasisManager
Set hyFluidPackages = hyBasis.FluidPackages
For Each hyFluidPackage In hyFluidPackages
If hyFluidPackage.PropertyPackageName =
“PengRobinson” Then
MsgBox “PengRobinson Property Package is Present”
Set hyPropPackage = hyFluidPackage.PropPackage
End If
Next hyFluidPackage

2-24
 Automation 2-25

Component(s)
The Components object is accessed through the FluidPackage
object. Each FluidPackage can have its own unique set of
Components.

Syntax for accessing components

From the BasisManager
SimulationCase.BasisManager.FluidPackages.Item(0).Com
ponents

From the Flowsheet

SimulationCase.Flowsheet.Components

The example below, shows how to access the Components

object associated with a particular FluidPackage object. In this
example each component's normal boiling point is checked and
a tally of all the components whose boiling point is below 0°C is
counted.

Example: Components
Dim numComp As Integer
Dim hyFluidPackage As FluidPackage
Dim hyBasis As BasisManager
Dim hyComponents As Components
Dim hyComponent As Component
Set hyBasis = hyCase.BasisManager
Set hyFluidPackage = hyBasis.FluidPackages.Item(0)
Set hyComponents = hyFluidPackage.Components
numComp = 0
For Each hyComponent In hyComponents
If hyComponent.NormalBoilingPointValue < 0 Then
numComp = numComp + 1
End If
Next hyComponent
MsgBox numComp & “ components have NBP below 0"

2-25
2-26 Key UniSim Design Objects

Hypotheticals
The HypoGroups collection object is accessed from the
BasisManager. This object contains a collection of HypoGroup
objects, each of which provides access to a HypoComponents
object. A HypoComponent can be entirely specified through
Automation and added to a UniSim Design simulation case.
Methods for the HypoComponent object are used to estimate
properties based on the minimum data requirement.

Syntax: Hypotheticals
SimulationCase.BasisManager.HypoGroups.Item(0).HypoCo
mponents.Item(0)

Hypotheticals have a '*' The example below, adds a hypothetical component and sets its
appended to the name
once they are created.
boiling point value in order to estimate the remaining properties.
The StartBasisChange and EndBasisChange methods are
invoked prior to adding this hypothetical to the case.

Example: HypoComponent
Dim hypGroups As HypoGroups
Dim hypoComp As Object
hyCase.BasisManager.StartBasisChange
Set hypGroups = hyCase.BasisManager.HypoGroups
hypGroups.Add “myhypo”
hypGroups.Item(“myhypo”).HypoComponents.Add
“mycomponent”, “userhypo”
Set hypoComp =
hypGroups.Item(“myhypo”).HypoComponents.Item(“mycompo
nent*”)
hypoComp.NormalBoilingPointValue = 300
hypoComp.Estimate
MsgBox hypoComp.NormalBoilingPointValue
hyCase.BasisManager.EndBasisChange

2-26
 Automation 2-27

2.4.4 Oils Objects

Oils objects refer to the objects accessed through the Oil
Manager. The OilManager object is set through the
BasisManager and contains Assay and Blend objects.

OilManager
Assays and Blends are not Set through the BasisManager, the OilManager object provides
estimated until the
EndOilChange method is
access to the oils environment. Like changes made to the
invoked. objects accessed through the BasisManager, notification to the
simulation environment is required when modifying assays or
blends. This is accomplished by calling the StartOilChange and
EndOilChange methods. Calling the StartOilChange method
before calling the StartBasisChange method by default causes
the StartBasisChange method to be invoked.

Example: Accessing the Oil Manager Environment

Public hyOil As OilManager
hyCase.BasisManager.StartBasisChange
hyCase.BasisManager.StartOilChange
Set hyOil = hyCase.BasisManager.OilManager
'//code to manipulate oil manager objects
hyCase.BasisManager.EndOilChange
hyCase.BasisManager.EndBasisChange

2-27
2-28 Key UniSim Design Objects

AssaysCollection & Assays

AssayTypes: The AssaysCollection object is accessed through the OilManager
• at_ASTMD2887 = 4 object and contains the assay objects available within a
• at_BulkPropertiesOnly
= 7 at_Chromatograph particular UniSim Design case. There are eight types of assays
=5 available and each of them has a specific set of properties and
• at_D1160 = 2
• at_D86 = 1
methods. The properties associated with the hypocomponents
• at_D86D1160 = 3 generated by the OilManager can be accessed through the Assay
• at_EFV = 6 object.
• at_TBP = 0

Syntax: Assays
Referencing a Collection
Set hyAssays = hyCase.BasisManager.OilManager.Assays

Referencing a Member
Set hyAssay =
hyCase.BasisManager.OilManager.Assays.Item(“name”)

Adding an Assay
hyCase.BasisManager.OilManager.Assays.Add “name”,
AssayType

2-28
 Automation 2-29

Below is an example on creating an assay.

Example: Creating Assays

Dim hyAssay As AssayTBP
Dim hyBasis As BasisManager
Set hyAssay =
hyBasis.OilManager.Assays.Add(“AssayName”, “TBP”)
With hyAssay
.Basis = ab_LiquidVolumeFraction
.BulkMolecularWeight = 300
.BulkMassDensity.SetValue 783, “API”
Dim hyValue As Variant
Dim hyPercent As Variant
hyPercent = Array(0,10,20,30,40,50,60,70,80,90,98)
hyValue =
Array(26.67,123.89,176.11,221.11,275,335,399,
490.56,590.56,691.67,795.56)
.AssayPercentForBoilingTemperature = hyPercent
.BoilingTemperatureValue = hyValue
.Calculate
End With

Blend(s)
Blends are created through the BasisManager and can be
completed by specifying at least one assay. Multiple assays can
be used in a blend as long as flow rates for each of the assays is
specified. A large number of blend properties for the

2-29
2-30 Key UniSim Design Objects

hypocomponents created can be viewed.

Syntax for Blends

Referencing a Collection
Set hyBlends = hyCase.BasisManager.OilManager.Blends

Referencing a Member
Set hyBlend =
hyCase.BasisManager.OilManager.Blend.Item(“blendname”
)

Adding Assay to Blend

HyBlend.AddAssay “AssayName”

Installing to a ProcessStream
hyBlend.InstallIntoStream “StreamName”

The example below, creates a blend, assigns one assay to the

blend, and then prints out the TBP values for the blend. The
blend is also assigned to a stream in the UniSim Design case.

Example: Blends
Dim hyBlend As Blend
'//create blend and assign assay
Set hyBlend =
hyBasis.OilManager.Blends.Add(“BlendName”)
hyBlend.AddAssay “AssayName”
'//print out some properties
Dim hyVar As Variant
hyvar = hyBlend.TrueBPTemperatureValue
For i = 0 To UBound(hyVar)
Debug.Print hyVar(i)
Next i
hyBlend.InstallIntoStream “Blend_Stream”

2.4.5 Stream Objects

The main objects of the stream category are the ProcessStream
and Fluid objects. The Fluid object is a type of Stream object
that is not connected to operations but can be derived from a
ProcessStream. The Fluid object can be manipulated without

2-30
 Automation 2-31

effecting the operations and streams within the case. The

ProcessStream object can be accessed from either the flowsheet
or the operation to which it is connected.

ProcessStream
The Streams object is a collection object returned by the
flowsheet. The Streams collection contains one or more
ProcessStream objects. There are approximately 124 properties
associated with the ProcessStream, including attributes such as
temperature, pressure, density, and viscosity. These properties
return values of type Double. The ProcessStream object also
returns arrays as variants for properties such as
ComponentMassFraction. The Fluid object contains a similar set
of properties and methods.

Syntax for accessing the ProcessStream object

By Name
SimulationCase.Flowsheet.MaterialStreams(“streamname”
)
SimulationCase.Flowsheet.MaterialStreams.Item(“stream
name”)

By Index
SimulationCase.Flowsheet.MaterialStreams.Item(j)

In most instances the collection object and member object of

the collection have nearly similar names. The name of the
collection object is normally the member name with an “s” at
the end. The Streams collection is an exception to this
statement, since it contains a collection of ProcessStream
objects. The flowsheet returns three stream collections;
MaterialStreams, EnergyStreams, and Streams. All three stream
collections accessed through the flowsheet are Streams objects.
The difference between the Streams collection objects relates to
how the member ProcessStream objects are filtered.

The example below, shows how to access a particular stream in

the system by index and how to retrieve the temperature value.

2-31
2-32 Key UniSim Design Objects

The remaining properties are accessed in a similar fashion.

Example 1: ProcessStream
Dim hyFlowsheet As Object
Dim hyStream As Object
Set hyFlowsheet = hyCase.Flowsheet
Set hyStream = hyFlowsheet.MaterialStreams.Item(0)
MsgBox “Stream Temperature = “ &
hyStream.TemperatureValue

The example below, shows how to access the MassFractionValue

for each component in the stream. An array of doubles is
returned to the variant hyCompFrac. The Ubound function is
used to determine the upper bound of the array and thus the
number of components. A separate object is set for the
component collection. The indexing between the array of mass
fractions and the list of components in the FluidPackage is
identical so it is easy enough to match the values with the
appropriate components.

Example 2: ProcessStream
Dim hyFlowsheet As Flowsheet
Dim hyStream As ProcessStream
Dim hyComponents As Components
Dim hyCompFrac As Variant
Set hyFlowsheet = hyCase.Flowsheet
Set hyComponents =
hyCase.BasisManager.FluidPackages.Item(0).Components
Set hyStream = hyFlowsheet.MaterialStreams.Item(2)
hyCompFrac = hyStream.ComponentMassFractionValue
For j = 0 To UBound(hyCompFrac)
MsgBox “Component “ & hyComponents.Item(j) & “ Mass
Fraction = “ & hyCompFrac(j)
Next j

2-32
 Automation 2-33

Fluid
A Fluid object is derived from a single ProcessStream through
the DuplicateFluid method. A Fluid object is essentially an
internal copy of the ProcessStream that can be manipulated for
property calculation purposes. The ProcessStream and Fluid
share many of the same properties. A Fluid however can be
flashed without interfering with the simulation case.

Syntax for creating a fluid

SimulationCase.Flowsheet.MaterialStreams(“streamname”
).DuplicateFluid

The example below, shows how to create a Fluid off of a stream

and use the Fluid to perform a flash calculation. The
DuplicateFluid method returns a Fluid object. A variety of flashes
could have been performed, but in this case a pressure-vapour
fraction flash is run with the desired pressure and vapour
fraction used as arguments to the method.

Example: Fluid
Public Sub FluidExample(pressureval As Double)
Dim hyFluid As Fluid
Dim hyStream As ProcessStream
Set hyStream =
hyCase.Flowsheet.MaterialStreams.Item(0)
Set hyFluid = hyStream.DuplicateFluid
hyFluid.PVFlash pressureval, 0
MsgBox “Bubble Point Temperature = “ &
hyFluid.TemperatureValue
End Sub

2-33
2-34 Key UniSim Design Objects

FluidPhase(s)
PhaseTypes (constants): The FluidPhases collection object is derived from the Fluid
• ptUnknownPhase object. Each FluidPhase in the collection contains a set of
• ptCombinedLiquidPhase
properties and methods that are similar to the Fluid itself except
• ptCombinedPhase
• ptLiquid2Phase that the properties correspond to a specific phase of the Fluid.
• ptLiquidPhase The PhaseType property of the FluidPhase objects can be
• ptPolymerPhase
accessed to determine the type of phase.
• ptSolidPhase
• ptVapourPhase
Syntax: FluidPhase(s)
Through Collection
Set hyFluidPhase = hyFluid.FluidPhases.Item(0)
HeavyLiquidPhase
Set hyFluidPhase = hyFluid.HeavyLiquidPhase
LightLiquidPhase
Set hyFluidPhase = hyFluid.LightLiquidPhase
VapourPhase
Set hyFluidPhase = hyFluid.VapourPhase

The example below, enumerates through the FluidPhases of a

Fluid and displays the phase type for each fluid in a view.

Example: FluidPhase
Dim i As Integer
Dim hyCase As SimulationCase
Dim hyfluid As Fluid
Dim hystream As ProcessStream
Dim hyPhase As FluidPhase
Dim hyPhases As FluidPhases
Set hystream =
hyCase.Flowsheet.MaterialStreams.Item(0)
Set hyfluid = hystream.DuplicateFluid
Set hyPhases = hyfluid.FluidPhases
i = 1
For Each hyPhase In hyPhases
If hyPhase.PhaseType = ptVapourPhase Then
MsgBox “Phase “ & i & “ is the vapour phase”
i = i + 1
End If
Next

2-34
 Automation 2-35

2.4.6 Operation Objects

A majority of the unit operations in UniSim Design are accessible
as Automation objects. Operations can be accessed through the
flowsheet object. Each operation typically has a characteristic
set of properties and methods.

Operations
All operations have a few properties and methods in common.
Operation objects contain properties for determining the feeds,
products, and additional objects connected to the operation. The
operation objects also contain methods for adding and removing
the operations from the flowsheet and the UniSim Design case.

Syntax for accessing operations

Getting all the operations on the flowsheet
SimulationCase.Flowsheet.Operations

Getting a specific collection of operations

SimulationCase.Flowsheet.Operations(“PumpOp”)

Getting to a specific operation by name

SimulationCase.Flowsheet.Operations.Item(“UnitName”)

Determining the type of operation

SimulationCase.Flowsheet.Operations.Item(0).TaggedNam
e

The Operations collection object obtained from the flowsheet

returns a collection of all the operations on that flowsheet. It is
possible to filter the collection of operations returned by
specifying the operation type. It is important to note however
that the operations object always returns a collection and not an
individual operation. The objects in the collection need to be
checked in order to find a specific type of operation.

2-35
2-36 Key UniSim Design Objects

The example below, enumerates through all the operations on

the flowsheet and displays the unit type in a view.

Example: Operation
Dim i As Integer
Dim hyOperations As Operations
Set hyOperations = hyCase.Flowsheet.Operations
For i = 0 To hyOperations.Count - 1
MsgBox “Operation “ & hyOperations.Item(i).name & “
is unit type - & hyOperations.Item(i).TypeName
Next i

ColumnOp & ColumnFlowsheet

The column operation is a special kind of operation in UniSim
Design and actually contains its own flowsheet. The
ColumnFlowsheet is accessed either from the Columnop object
or as a member of the flowsheets object accessed through the
main flowsheet. In order to access the various temperatures,
pressures, and specifications for a column the ColumnFlowsheet
must be accessed.

Syntax: Accessing Columns

Set objColumn =
SimulationCase.Flowsheet.Operations(“ColumnOp”).Item(
0)

Set objColumnSubFlow = objColumn.ColumnFlowsheet

2-36
 Automation 2-37

The ColumnFlowsheet object contains a considerable amount of

information regarding the column. A variant is used to receive
an array of column pressure information and displays a stage by
stage breakdown of the pressure values.

Example: Column Operation

Dim hyColumn As ColumnOp
Dim hyColumnSubFlowsheet As ColumnFlowsheet
Dim Pressure_Profile As Variant
Set hyColumn =
hyCase.Flowsheet.Operations(“ColumnOp”).Item(0)
Set hyColumnSubFlowsheet = hyColumn.ColumnFlowsheet
Pressure_Profile = hyColumnSubFlowsheet.Pressures
For i = 0 To UBound(Pressure_Profile)
MsgBox “Stage “ & i + 1 & “ pressure = “ &
Pressure_Profile(i)
Next i

ColumnSpecification(s)
A column is solved based on matching specifications related to
the available degrees of freedom. The ColumnSpecifications
collection object is accessed through the ColumnFlowsheet. The
ColumnSpecification contains information such as the goal
value, current value, and status.

Syntax: ColumnSpecification
Set hyColumn =
hyCase.Flowsheet.Operations(“ColumnOp”).Item(0)
Set hyColumnFlowsheet = hyColumn.ColumnFlowsheet

By Index:
Set hyColumnSpec = hyColumnFlowsheet.
Specifications.Item(0)
By name:
Set hyColumnSpec =
hyColumnFlowsheet.Specifications.Item(“specname”)

2-37
2-38 Key UniSim Design Objects

The example below, enumerates through all the column

specifications and displays in a view whether the specification is
active or an estimate.

Example: ColumnSpecification
Dim hyColumnSpec As ColumnSpecification
Dim hyColumnSpecs As ColumnSpecifications
Dim hyColumn As ColumnOp
Dim hyColumnFlowsheet As ColumnFlowsheet
Set hyColumn =
hyCase.Flowsheet.Operations(“ColumnOp”).Item(1)
Set hyColumnFlowsheet = hyColumn.ColumnFlowsheet
Set hyColumnSpecs = hyColumnFlowsheet.Specifications
For Each hyColumnSpec In hyColumnSpecs
If hyColumnSpec.IsActive Then
MsgBox “Column spec '" & hyColumnSpec & “' is
active.”
Else
MsgBox “Column spec '" & hyColumnSpec & “' is an
estimate.”
End If
Next hyColumnSpec

ColumnStage(s) & SeparationStage

The ColumnStages object is a collection of ColumnStage objects
accessed through ColumnFlowsheet. SeparationStage is an
object of ColumnStage and provides a variety of properties
related to the fluids residing on a particular column stage.

Syntax: ColumnStage(s)
By Index:
Set hyColumnStage =
hyColumnFlowsheet.ColumnStages.Item(0)

By Name:
Set hyColumnStage =
hyColumnFlowsheet.ColumnStages.Item(“1_Main TS”)

Syntax: SeparationStage
Set hySepStage = hyColumnStage.SeparationStage

2-38
 Automation 2-39

The example below, loops through each feed stage and displays
in the Debug view its molar liquid flows.

Example: ColumnStage
Dim hyColumn As ColumnOp
Dim hyColumnFlowsheet As ColumnFlowsheet
Dim hyFeedStage As Object
Dim hySepStage As SeparationStage
Set hyColumn =
hyCase.Flowsheet.Operations(“ColumnOp”).Item(0)
With hyColumn.ColumnFlowsheet
For Each hyFeedStage In .FeedStages
Debug.Print “Stage “
&.ColumnStages(hyFeedStage.name)
StageNumberValue & “ Molar Liquid Flow (kgmole/hr)
is “ &.ColumnStages(hyFeedStage.name).
SeparationStage.MolarLiquidFlowValue
Next hyFeedStage
End With

2.4.7 Support Objects

Support objects are used primarily to perform a function or
service to an object in UniSim Design. Support objects may not
have a visible equivalent in a UniSim Design case when viewed
within the simulation environment. The support objects can be
accessed by several of the objects in UniSim Design. The two
most commonly accessed objects in this category are
FixedAttachments and RealVariable.

2-39
2-40 Key UniSim Design Objects

RealVariable/RealFlexVariable
The RealVariable object provides additional information about a
particular variable such as its units and whether it is calculated
or set. UniSim Design performs all calculations in SI units
regardless of how the user preference settings are set. By
default, the values returned through Automation are also in SI
units. It becomes your responsibility to handle how units are
handled when writing applications. A RealVariable contains a
property called GetValue and SetValue which allows one to
specify the units that are to be used when returning or setting
the value.

Syntax for using RealVariable

SimulationCase.Flowsheet.MaterialStreams.Item(0).prop
erty
RealVariable Properties/Methods

GetValue Gets the value in a specified unit.

SetValue Sets the value in a specified unit.

Status Returns calculated or specified

Value Value in SI units.

The presence of “Flex” in The RealVariable object also contains a property called Value.
the object name
The Value property returns the actual value in SI units within
indicates the possibility
of a dynamic array (i.e., the UniSim Design case. Many of the objects that return a
has a “variable” size, RealVariable for a given property also have a similarly named
depending on what is
being returned.) property with the word value concatenated to it. The alternative
property allows direct access to the actual variable in SI units
with one less function call. An example for the ProcessStream
object would be the Temperature property that returns a
RealVariable and the TemperatureValue property, that returns a
value in °C.

The RealFlexVariable contains roughly the same properties and

methods as the RealVariable but is used for array values
returned to variants.

2-40
 Automation 2-41

The example below, shows how to get a stream property value

in a specific unit using the RealVariable method GetValue.

Example 1: RealVariable
Dim hyStream As ProcessStream
Dim TemperatureVal As Double
Set hyStream =
hyCase.Flowsheet.MaterialStreams.Item(0)
TemperatureVal = hyStream.Temperature.GetValue(“F”)
MsgBox hyStream.name & “ temperature(F) = “ &
TemperatureVal

The example below, shows how to set a stream property value

in a specific unit using the RealVariable method SetValue.

Example 2: RealVariable
Dim hyStream As ProcessStream
Dim TemperatureVal As Double
Set hyStream =
hyCase.Flowsheet.MaterialStreams.Item(0)
TemperatureVal = 150
hyStream.Temperature.SetValue 150, “F”

The example below, checks how the temperature value of a

stream is determined by examining the state property. The
constants vsCalculated, vsSpecified, and vsDefaultedValue are
integer variables specified in the type library.

Example 3: RealVariable
Dim hystream As ProcessStream
Set hystream =
hyCase.Flowsheet.MaterialStreams.Item(0)
Select Case hystream.Temperature.State
Case vsCalculated
MsgBox “Temperature value is calculated.”
Case vsSpecified
MsgBox “Temperature value is specified.”
Case vsDefaultedValue
MsgBox “Temperature value is default.”
End Select

2-41
2-42 Key UniSim Design Objects

Fixed Attachments
The FixedAttachments object is a collection object accessed
from Operations or Stream objects. The FixedAttachments
collection object contains a set of objects related to the feeds,
products, or connected operations.

Syntax: Using FixedAttachments

Set FixAtch =
SimulationCase.Flowsheet.Operations.Item(0).AttachedF
eeds

Set hyStream = FixAttachObj.Item(0)

Types of objects a FixedAttachments Collection

AttachedFeeds - ProcessStream

AttachedProducts - ProcessStream

AttachedLogicalOps - UnitOperation

AttachedOpers - UnitOperation

The example below, shows how to determine the streams

attached to a specific unit operation. This example selects the
first column in the operations collection object and then sets an
object to the attached feeds of the column. The names of the
feed streams to the column appear in a view.

Examples: FixedAttachments
Dim hyFeeds As FixedAttachments
Dim hyOp As ColumnOp
Set hyOp =
hyCase.Flowsheet.Operations(“ColumnOp”).Item(0)
Set hyFeeds = hyOp.AttachedFeeds
For j = 0 To hyFeeds.Count - 1
MsgBox “FeedStream “ & j & “ Name = “ &
hyFeeds.Item(j).name
Next j

2-42
 Automation 2-43

Solver & Integrator

The Solver is accessed from the SimulationCase object. The
Solver object can be used to turn the calculations on and off.

Syntax for the Solver and Integrator

Solver
SimulationCase.Solver.CanSolve = False
SimulationCase.Solver.CanSolve = True

Integrator
SimulationCase.Solver.Integrator.Active = True
SimulationCase.Solver.Integrator.Active = False

When accessing UniSim Design through Automation it is

important to note that UniSim Design does not allow
communication while it is solving. If information is sent to
UniSim Design from a client application, UniSim Design does not
return control to the calling program until calculations are
complete. If it is necessary to pass a large amount of
information to UniSim Design it is best to turn the solver off first
and then turn it on once the information is sent. Otherwise,
UniSim Design calculates after each piece of information is sent
and it takes much longer to transfer the data.

Example: Starting/Stopping the Solver

Dim hystream As ProcessStream
Set hystream =
hyCase.Flowsheet.MaterialStreams.Item(0)
hyCase.Solver.CanSolve = False
hystream.Temperature.SetValue 100, “F”
hystream.Pressure.SetValue 1, “atm”
hystream.MassFlow.SetValue 1000, “lb/hr”
hyCase.Solver.CanSolve = True

2-43
2-44 Key UniSim Design Objects

SpreadsheetOp &
SpreadsheetCell(s)
The SpreadsheetCells object is a collection of SpreadsheetCell
objects. The cell properties allow access to information related
to the UniSim Design variable being imported or exported, the
formulas associated with the cell, and the value within the cell.

Syntax: SpreadsheetOp and SpreadsheetCell(s)

Set hySS =
hyCase.Flowsheet.Operations.Item(“spreadsheetname”)
Set hyCell = hySS.Cell(columnindex, rowindex)

By utilizing the spreadsheet operation, it is possible to access

nearly every property or value in UniSim Design even if the
object associated with that property is not exposed as an
Automation interface.

Example: Accessing Spreadsheet Cells

Dim hySS As SpreadsheetOp
Dim hyCell As SpreadsheetCell
Set hySS =
hyCase.Flowsheet.Operations(“spreadsheetop”).Item(0)
Dim x As Variant, y As Variant
For i = 0 To 5
x = 1 ' col #
y = i ' row #
Set hycell = hySS.Cell(x,y)
Debug.Print “CELL VALUE = “ & hyCell.CellValue
Debug.Print “CELL FORMULA = “ & hyCell.CellText
Debug.Print “CELL PROPERTY = “ & hyCell.VariableName
& “ (“ & hyCell.Units & “)”
Next i

2-44
 Automation 2-45

2.4.8 PFD Objects

PFD objects are used for the manipulation and automation of
PFDItems. A PFDItem is any item that is found on the UniSim
Design PFD, such as a unit op or a stream. You can use PFD
objects to Move, Size, Mirror, Rotate, Hide, etc. any PFDItem.
PFD objects also allow you to import and display a selection of
PFDItems in to Visio, a CAD application or Excel (what items you
get depends on what parameters you specify). In addition to
manipulating the PFD you can use the PFDConnection object for
such things as finding the “stream line” route between two
PFDItems.

Example: Nozzle Type

If nozzle.NozzleType = pfdInletFromMaterialStream Or
nozzle.NozzleType = pfdOutletToMaterialStream Or
nozzle.NozzleType = pfdInletFromStream Or
nozzle.NozzleType = pfdOutletToStream Then
newLine.Line.ForeColor.RGB = RGB(0, 0, 128)
newShape.Fill.ForeColor.RGB = RGB(128, 128, 128)
ElseIf nozzle.NozzleType = pfdInletFromEnergyStream Or
nozzle.NozzleType = pfdOutletToEnergyStream Then
newLine.Line.ForeColor.RGB = RGB(128, 0, 0)
newShape.Fill.ForeColor.RGB = RGB(128, 128, 128)
ElseIf nozzle.NozzleType = pfdMaterialStreamInlet Or
nozzle.NozzleType = pfdMaterialStreamOutlet Then
newLine.Line.ForeColor.RGB = RGB(0, 0, 128)
newShape.Fill.ForeColor.RGB = RGB(0, 0, 128)
newShape.Line.ForeColor.RGB = RGB(0, 0, 128)
ElseIf nozzle.NozzleType = pfdEnergyStreamInlet Or
nozzle.NozzleType = pfdEnergyStreamOutlet Then
newLine.Line.ForeColor.RGB = RGB(128, 0, 0)
newShape.Fill.ForeColor.RGB = RGB(128, 0, 0)
newShape.Line.ForeColor.RGB = RGB(128, 0, 0)
Else
newLine.Line.ForeColor.RGB = RGB(0, 255, 0)
End If

2-45
2-46 Example 1: The Macro Language

2.5 Example 1: The Macro

Language Editor
This complete example In this example, you use the UniSim Design Macro Language
has also been pre-built
Editor to build a macro tool that displays the Mach number for a
and is located in the
UniSim selected stream over a number of different pipe sizes. The speed
Design\Samples\OLE\ma of sound in the stream fluid also appears. The fluid velocity
cros\mach directory.
calculated for each pipe size is the average fluid velocity; no
attempt is made to estimate the maximum velocity.
1. Begin by opening UniSim Design and the Macro Language
Editor which is found under the Tools menu.

Figure 2.6

2. Add a function that returns the Stream object that you

choose from a list. Creating separate functions allows for
easy re-use in other programs.

Code Explanation
Function SelectStream(simcase As Object) As Object Signifies the beginning of the
SelectStream function. This
function takes a SimulationCase
object and prompts the user to
select a Stream from a list of
streams in the case, returning
an interface to the Stream.
Set FS = simcase.Flowsheet Acquire the case flowsheet.

2-46
 Automation 2-47

Code Explanation
Set Strms = FS.MaterialStreams Acquire the collection of Streams
from the flowsheet.
Dim strmnames() Build a string array of the
strmnames = Strms.Names Stream names.

Begin Dialog UserDialog 390,210,”Streams in “ + Generate a user view containing

Right$(simcase.FullName, Len(simcase.FullName)- a list of Streams Please notice
that the first button created
Len(simcase.Path)) automatically becomes the
ListBox 20,35,350,119,strmnames(),.listsrc default.
Text 20,14,360,14,”Select a Stream for Mach Use the Language Help option
number estimation:” provided in the Help menu to
OKButton 140,175,90,21 explore the use of UserDialogs.
CancelButton 270,175,90,21
End Dialog
Dim dlg As UserDialog Finally, run the Dialog and
If Dialog(dlg) = 0 Then End terminate the macro if the user
cancels (i.e., Dialog function
returns 0).
Set SelectStream = Strms(dlg.listsrc) Set the function's return value to
the user selected stream
interface.
End Function Signifies the end of the function.
This line does not need to be
added.

3. At this time it is probably a good idea to globally declare

some constants that are used in the Main sub-routine as
shown below.

Figure 2.7

2-47
2-48 Example 1: The Macro Language

4. You can now begin defining the Main sub-routine. Enter the
following code:

Code Explanation
Sub Main Signifies the beginning main
sub-routine.
pipeSizes(1) = 2 Defines an array of pipe sizes (in
pipeSizes(2) = 3 inches).
pipeSizes(3) = 4
pipeSizes(4) = 6
pipeSizes(5) = 8
pipeSizes(6) = 10
pipeSizes(7) = 12
pipeSizes(8) = 16
Dim simcase As Object Looks for an open active case. If
Set simcase = ActiveCase there is no active case, it alerts
the user and terminates.
If simcase Is Nothing Then
MsgBox “No UniSim Design case is open.”
End
End If
Dim strm As Object Calls the SelectStream function
Set strm = SelectStream(simcase) to select a stream in the
simcase.
Set flow = strm.MassFlow Check to see if the selected
If flow.IsKnown Then stream has a defined mass flow
rate. If the flow rate is known,
flowValue = flow.GetValue(“lb/hr”) convert the flow rate in to “lb/s”.
flowValue = flowValue / 3600
Else
GoTo NoFlow
End If
Set rho = strm.MassDensity Checks to see if the stream’s
If rho.IsKnown Then mass density has been
calculated.
rhoValue = rho.GetValue(“lb/ft3”)
Else
GoTo NoRho
End If
flowValue = flowValue / rhoValue Calculates volumetric flow rate.
On Error GoTo NoCv Proceeds to an error trap if the
Cv = strm.MolarHeatCapacityValue / Cv value of the stream has not
been calculated.
strm.CpCvValue
On Error GoTo NoZ Proceeds to an error trap if the
Z = strm.CompressibilityValue compressibility of the stream
has not been calculated.
On Error GoTo NoTemp Proceeds to an error trap if the
T = strm.TemperatureValue + 273.15 absolute temperature of the
stream cannot be calculated.

2-48
 Automation 2-49

Code Explanation
On Error GoTo NoMolWt Proceeds to an error trap if the
MolWt = strm.MolecularWeightValue / 1000.0 molecular weight of the stream
cannot be calculated.
soundVel = Sqr(Z*R*T/MolWt*(1.0+Z*R/Cv)) Calculates the Speed of Sound
soundVel = soundVel / 0.3048 of the stream and converts it
from m/s to ft/s.
soundVelTxt = Format(soundVel,
“###,###,###.###”)
Dim DispText() As String Declares an array of String
ReDim DispText(nPipes + 2) types. The “+2” leaves room for
a two line header. The two
DispText(0) = “Pipe Size (in) Mach header lines are assigned.
Number “
Please note there are eighteen
DispText(1) = “--------------------------------- spaces between “(in)” and
------------------------------” “Mach” and four spaces after
“Number”. There are
approximately seventy dashes in
the line DispText(1) = “---...”
For num = 1 To nPipes For each pipe size, the Mach
rSquared = pipeSizes(num) * pipeSizes(num)/ number is calculated, formatted
and stored in the previously
144.0/4.0 created array of strings.
Mach = flowValue / pi / rSquared / soundVel
Please notice that there are
sizetxt = Format(pipeSizes(num), eighteen spaces between the
"###,###,###.###") quotation marks in the sixth line
Machtxt = Format(Mach, "###,###,###.#####") of code (ninth line displayed).
DispText(num + 1) = Format$(sizetxt,
"@@@@@@@@@@@@@@@") + " " +
Format$(Machtxt, "@@@@@@@@@@@@@@@")
Next num
Begin Dialog UserDialog 360,217 Create a user view that displays
ListBox 10,49,340,133,DispText(),.Field5 the Speed of Sound value as
well as the Mach number for
OKButton 250,189,90,21 each of the pipe sizes.
Text 30,14,150,14,"Speed of Sound (ft/s):",
Use the Language Help option
.Field2 provided in the Help menu to
TextBox 190,14,90,21,.Field1 explore the use of UserDialogs.
End Dialog
Dim dlg2 As UserDialog
dlg2.Field1 = soundVelTxt
Dialog dlg2
End

2-49
2-50 Example 1: The Macro Language

Code Explanation
NoFlow: This is where you define the
MsgBox "Unknown mass flow in stream " + error trap instances.
strm.name
End
NoRho:
MsgBox "Unknown density in stream " +
strm.name
End
NoCv:
MsgBox "Unknown heat capacity in stream " +
strm.name
End
NoZ:
MsgBox "Unknown compressibility in stream " +
strm.name
End
NoTemp:
MsgBox "Unknown temperature in stream " +
strm.name
End
NoMolWt:
MsgBox "Unknown molecular weight in stream " +
strm.name
End
End Sub Signifies the end of the method.

5. Once you have finished adding this code, you should be

ready to run the program. First ensure that UniSim Design
has a case loaded with at least one fully defined stream. You
can start the program using one of the following ways:
• Right-click on any area of the Macro Language Editor
view, select Macro | Run command from the Object
Inspect menu.
• Clicking the Start/Resume icon on the tool bar.

Start/Resume icon

2-50
 Automation 2-51

You should see a view similar to the one shown below:

Figure 2.8

6. Select a stream from the list and click the OK button. This
should result in a view similar to the one shown below.

Figure 2.9

7. Be sure to save the program by doing one of the following:

• Right-click on any area of the Macro Language Editor
view, select File | Save from the Object Inspect menu.
• Press the CTRL S hot key combination.
• Clicking the Save icon in the tool bar.

Save icon

2-51
2-52 Example 2: Automation in Visual

2.6 Example 2:
Automation in Visual
Basic
This complete example In this example UniSim Design is used as the Automation server
has also been pre-built
and is located in the
for a unit conversion program. More specifically, you are
UniSim accessing an object called the UnitConversionManager which
Design\Samples\OLE\vb\ manages unit conversion within UniSim Design.
ucsm directory.

Although Visual Basic 6.0 is recommended for this example,

you can create this Automation application in Visual Basic
Editor provided in MS Excel 97® and MS Word 97®.

1. Open a new project in Visual Basic 6.0® and from the New
tab of the New Project view select the Standard EXE icon
and click the Open button.

2-52
 Automation 2-53

Your screen should appear similar to the figure below.

Figure 2.10

Toolbox Form Properties Tiled View

2. By default you should have a form associated with the

project. Begin, by giving the form a name. In the Name field
of the Properties tiled view give the form the name:
frmUCSM.
3. In the Caption field type: UNIT CONVERSION MANAGER.
This caption should now appear in the Title Bar of the form.
4. Before adding objects to the form, resize the view to
accommodate the different objects that are required. In the
Width field found in the Properties tiled view change the
width of the form to 12600 or so that the form is sufficiently
wide enough to contain all the objects you are adding (see
Figure 2.14).

2-53
2-54 Example 2: Automation in Visual

5. From the toolbox select the Combo Box icon and create a
combo box on the form as shown below.

Figure 2.11
Combo Box icon

6. Ensure that the combo box is the active control. This can be
done in one of two ways:
• Select the combo box on the form so that the object
guides appear around the object.
• From the drop-down list found at the top of the
Properties tiled view select the name of the combo box
you have just created.
7. In Properties tiled view, set the name of the Combo Box as
ddUnitSet in the Name field. If you want, you can also
change the default text that appears inside the combo box
by entering a new name in the Text field.
8. You can add a Label to the form (i.e., to identify the object
from others), by clicking the Label icon and drawing a label
on the form just above the combo box you have just created.
Label icon
Figure 2.12

9. Ensuring that the Label control is active using one of the

methods suggested in #6, go to Properties tiled view and
change the text in the Caption field to Unit Conversion
Set.

2-54
 Automation 2-55

10. Now add an Text Box next to the Combo Box you created.
Use the method described in Steps #6 - #7 to name this
Text Box ebFromValue. Repeat Steps #8 - #9 to add a
Label above the ebFromValue Text Box that reads From
Value.

Figure 2.13

11. Add the following objects to the view using the previously
described methods.

Figure 2.14

Object Type - Label Object Type - Label Object Type - Label

Caption - From Unit Conversion Caption - To Value Caption - To Unit Conversion

Object Type - Combo Box Object Type - Label Object Type - Combo Box
Name - ddFromUnit Name - lbToValue Name - ddToUnit
Text - ddFromUnit Caption - lbToValue Text - ddToUnit

2-55
2-56 Example 2: Automation in Visual

12. Only two more objects are required on the form. Select the
Command icon control from the toolbox and add two
buttons to the view as shown below.
Command icon
Figure 2.15

Object Type - Command icon Object Type - Command icon

Name - btConvert Name - btExit
Caption - Convert Caption - Exit

13. You are now ready to begin defining the events behind the
form and objects. You can enter the code environment using
a number of methods:
• Click the View Code icon in the Project tiled view.
• Select the Code command from the View menu.
View Code icon • Double-click the frmUCSM form.

2-56
 Automation 2-57

The following view should appear:

Figure 2.16

The Private Sub

Form_Load() method
definition is only visible if
you enter the code
environment by double-
clicking the form.

If you attempt to use an 14. Begin by declaring the following variables under the Option
undeclared variable, an Explicit declaration.
error occurs at compile
time.
Figure 2.17

2-57
2-58 Example 2: Automation in Visual

15. The first sub-routine should already be declared. The

Form_Load sub-routine is the first sub-routine called once
the program is run. It is usually used to initialize the
variables and objects used by the program. Enter the
following code in to the Form_Load sub-routine.

Code Explanation
Private Sub Form_Load() Signifies the Start of the form load sub-routine. You do
not have to add it as it should already be there.
ddUnitSet.Clear Clear the default text found inside the ddUnitSet,
ddFromUnit.Clear ddFromUnit and ddToUnit combo boxes.
ddToUnit.Clear
Set hyApp = Connects to UniSim Design and the UniSim Design Unit
CreateObject("UniSimDesign.Application") Conversion Set Manager.
Set UCSM = hyApp.UnitConversionSetManager
For Each UCS In UCSM For each Unit Conversion Set found in the Unit
ddUnitSet.AddItem UCS.Name Conversion Set Manager add the Unit Set to
Next UCS ddUnitSet combo box list.
Indicates no item is currently selected in the ddUnitSet
ddUnitSet.ListIndex = -1
combo box.
ebFromValue.Text = "" Clears the text that appears in the ebFromValue text
lbToValue.Caption = "" box and the lbToValue label.
End Sub Signifies the end of the initialization sub-routine. This
line does not need to be added.

16. The next section of code to be added tells the program what
is to occur when an option is selected in the ddUnitSet
combo box.

Code Explanation
Private Sub ddUnitSet_Click() Signifies the Start of the sub-routine.
ddFromUnit.Clear Clears any list entries in the ddFromUnit and
ddToUnit.Clear ddToUnit combo boxes.
Set hyApp = Connects to UniSim Design and the UniSim Design Unit
CreateObject("UniSimDesign.Application") Conversion Set Manager.
Set UCSM = hyApp.UnitConversionSetManager
Once the selection is made in the ddUnitSet combo
UCSNumber = ddUnitSet.ListIndex box, the UCSNumber variable holds the internal
UniSim Design index number of the selected Unit Set.
Find the selected Unit Conversion Set in Unit
Set UCS = UCSM.Item(UCSNumber)
Conversion Manager.
For Each UC In UCS For each Unit Conversion type (UC) in the Unit
ddFromUnit.AddItem UC.Name
Conversion Set, add the Unit type to both the
ddFromUnit combo box (the unit type the program is
ddToUnit.AddItem UC.Name
converting from) and the ddToUnit (the unit type the
Next UC program is converting to).
ddFromUnit.ListIndex = -1 Indicates no items are currently selected in the
ddToUnit.ListIndex = -1 ddFromUnit and ddToUnit combo box.

2-58
 Automation 2-59

Code Explanation
lbToValue.Caption = "" Clears any text that appears in the lbToValue label.
End Sub Signifies the end of the sub-routine. This line does not
need to be added.

17. The next 2 sub-routines reset the lbToValue label whenever

an option is selected in either the ddFromUnit or ddToUnit
combo box.

Code Explanation
Private Sub Signifies the Start of the sub-routine.
ddFromUnit_Click()
lbToValue.Caption = "" Clears any text that appears in the lbToValue label.
End Sub Signifies the end of the sub-routine. This line does not need to
be added.

Code Explanation
Private Sub ddToUnit_Click() Signifies the Start of the sub-routine.
lbToValue.Caption = "" Clears any text that appears in the lbToValue label.
End Sub Signifies the end of the sub-routine. This line does not need to
be added.

18. The final two sub-routines define the actions of the two
buttons: btConvert and btExit.

Code Explanation
Private Sub btConvert_Click() Signifies the Start of the sub-routine.
Set hyApp = Connects to UniSim Design and the UniSim Design
CreateObject("UniSimDesign.Application") Unit Conversion Set Manager.
Set UCSM = hyApp.UnitConversionSetManager
Takes the value entered in the ebFromValue text
FromValue = CDbl(Val(ebFromValue.Text))
box and converts in to a numerical variable type.
Set ebFromValue text box text equal to
ebFromValue.Text = CStr(FromValue)
FromValue double.
UCSNumber = ddUnitSet.ListIndex Gets current selection in the three drop-down lists
FromNumber = ddFromUnit.ListIndex (combo boxes).
ToNumber = ddToUnit.ListIndex
If FromNumber < 0 Or ToNumber < 0 Then If no selection is made in either the ddFromUnit
lbToValue.Caption = "" or ddToUnit combo boxes, exit the sub-routine.
Exit Sub
End If

Set UCS = UCSM.Item(UCSNumber) Chooses a specific UCS from UCSM. It takes the
Unit conversion type you want to change from,
Set FromUC = UCS.Item(FromNumber)
and the Unit Conversion type you want to change
Set ToUC = UCS.Item(ToNumber)
to.

2-59
2-60 Example 2: Automation in Visual

Code Explanation
Converts the contents of the ddFromValue
Intermediate = FromUC.ToCalculationUnit(FromValue) combo box from the FromUC units to UniSim
Design internal units (Intermediate). It then
ToValue = ToUC.FromCalculationUnit(Intermediate)
converts the Intermediate value from internal
lbToValue.Caption = CStr(ToValue)
units to the ToUC units. It then displays the
converted value in the lbToValue label.
End Sub Signifies the end of the sub-routine. This line does
not need to be added.

Code Explanation
Private Sub btExit_Click() Signifies the Start of the sub-routine.
Unload Me Unloads the form and ends the program.
End
End Sub Signifies the end of the sub-routine. This line does
not need to be added.

19. You are now ready to compile and run the program. Before
you begin, please ensure that you have a copy of UniSim
Design on the computer.
20. To compile the program do one of the following:
• Click the Start icon in the toolbar.
• Select Start command from the Run menu.
Start icon • Press F5 from the keyboard.
VB informs you of any errors that occur during compile time.

2-60
 Extensibility 3-1

3 Extensibility

3.1 Introduction................................................................................... 3

3.2 Implementing Interfaces ............................................................... 5

3.2.1 Implementing an Interface Through a Dispatch Interface............... 5
3.2.2 Implementing an Interface Through a Custom Interface ................ 6

3.3 Data Types ..................................................................................... 6

3.4 Extension Development Kit ............................................................ 7

3.5 Creating an Extension .................................................................... 8

3.5.1 In Visual Basic ......................................................................... 8
3.5.2 In C++ ................................................................................. 12

3.6 Registering Extensions ................................................................ 17

3.6.1 Registering Extensions Written in C++ ...................................... 18
3.6.2 Registering Extensions Written in Visual Basic ............................ 20

3.7 Extension Interface Details.......................................................... 21

3.7.1 ExtnContainer Interface .......................................................... 21
3.7.2 ExtensionObject Interface ....................................................... 22

3.8 Extension Reaction Kinetics ......................................................... 22

3.8.1 ExtnKineticReaction Interface................................................... 24
3.8.2 ExtnKineticReactionContainer Interface ..................................... 25
3.8.3 Kinetic Reaction Example ........................................................ 26

3.9 Extension Property Packages ....................................................... 41

3.9.1 ExtnPPkgContainer Interface.................................................... 44
3.9.2 ExtnPropertyPackage Interface................................................. 45

3-1
3-2 Extensibility

3.10 Extension Unit Operations ..........................................................47

3.10.1 ExtnUnitOperationContainer Interface....................................48
3.10.2 ExtnUnitOperation Interface .................................................49
3.10.3 Passes...............................................................................49
3.10.4 Extension Unit Operation Example.........................................51

3.11 References..................................................................................76

3-2
 Extensibility 3-3

3.1 Introduction
UniSim Design provides the unique capability of enhancing its
functionality through the addition of custom objects to a
simulation. With its open concept, the functionality of UniSim
Design can be extended to include your unique or proprietary
calculations. Currently, you can add:
• Extension Unit Operations
• Extension Reaction Kinetics
• Extension Property Packages

Extensions are packaged in to two distinct files making them

easy to transfer to different machines. The extension code
becomes part of a DLL (dynamic linked library), that hides its
proprietary information, making it an excellent vehicle for
commercial distribution. Extensions become part of the
simulation and participate in simulation calculations like any
other UniSim Design object. For example, each extension unit
operation has a corresponding PFD icon and property view. Also,
the Extension has its Execute method called by the Steady-State
Solver. Unlike applications which interact with UniSim Design
through Automation, extensions exist in process with the
UniSim Design applications. New extensions can be written in
any language that supports Automation (formerly OLE
Automation). This provides much flexibility to the end user, who
can develop the extension in languages such as C++ or Visual
Basic. By its very nature, Visual Basic provides the easiest
development environment in which to create unit operation and
kinetic reaction extensions. The Extension Property Package
interface must be implemented as a custom interface, therefore
C++ must be used.

Each type of extension is represented in UniSim Design by an

Extension Container. This object is the gateway through which
UniSim Design communicates with the extension. The Container
can also provide a number of services to the extension, such as
performing Mass Balances or allowing access to the Status Bar.

3-3
3-4 Introduction

Figure 3.1

UniSim Extension
Design Container Code

UniSim Design finds extensions by looking for specific keys in

the System Registry. When an extension is registered on a
computer, information about it is added to the Registry. Upon
start-up, UniSim Design scans the Registry for this information,
and adds user-specified descriptions to the appropriate lists
within the program. For instance, when a unit operation
extension is created with the description provided as “MY Unit
Op”. This text appears in the UniSim Design UnitOp view in the
Available Unit Operations pane so that the user can create
instances of them.

When the user asks for an extension to be created, UniSim

Design instantiates the object and calls its Initialize method. At
this point, the extension code gains access to its Container. After
the extension has been initialized, it behaves like any other
UniSim Design object of the same class.

All extensions must support at least two interfaces:

• The ExtensionObject interface
• At least one other interface particular to the type of
extension

Containers support one interface, which is particular to the type

of container.

3-4
 Extensibility 3-5

3.2 Implementing
Interfaces
An extension implements an interface if it supports the methods
in that interface. There are two different ways of implementing
an interface.

3.2.1 Implementing an
Interface Through a
Dispatch Interface
An extension can implement interfaces through Dispatch
interfaces. This can be done in Visual Basic if the extension is
implemented as a Visual Basic Class.

When an extension is implemented in this manner, only the

methods of the interface that are required for minimal operation
of the extension need be used. All other methods may be
ignored, or they can be provided if the extension implements
that functionality.

For example, an extension Unit Operation can be implemented

by supporting only the Initialize and Execute methods. The
BasisChanged method need only be implemented if the
extension needs to be notified when the Basis of the simulation
has changed.

3-5
3-6 Data Types

3.2.2 Implementing an
Interface Through a
Custom Interface
An extension can also be implemented by overloading the
Custom interfaces defined for the extension. For example, an
extension Unit Operation can be created by overloading the
ExtensionObject interface and the ExtnUnitOperation interface.

When an extension is created in this manner, all methods of the

interface must be overloaded (this is a requirement of the C++
language definition). If a method does not contain any
functionality, however, the error condition E_NOTIMPL should be
returned to indicate to UniSim Design that the method is not
being used. Using the Extension Unit Operation as an example
once again; each of the methods in its two supported interfaces
must be overloaded, but only the Initialize and Execute methods
need return anything other than E_NOTIMPL.

3.3 Data Types

When sending an array This documentation for the most part uses Visual Basic syntax in
of numbers to UniSim
Design they should
its sample code and examples. The following table provides a
always be of type REAL map of Visual Basic types to C++ types, for those that choose
or LONG. create extensions in C++.

Visual Basic Type C++ Type

Variant VARIANT
String BSTR
Boolean VARIANT_BOOL
Long long
Integer short
Double double
Single float
arrays SAFEARRAY

3-6
 Extensibility 3-7

3.4 Extension
Development Kit
A number of tools are provided in the UniSim Design Extension
Development Kit. These tools are not required to build
extensions for UniSim Design, but they make the job much
easier. Included in the kit are the following:

File Description
UniSim The UniSim Design Type Library, that contains definitions
Design.tlb for all objects exposed by UniSim Design, as well as
definitions for interfaces required by UniSim Design
Extensions. Programming languages such as Visual Basic
use this file to determine what a particular object contains.
Many programs provide browsers to look at the contents of
this file. For example, Excel provides an Object Browser
that can be used to view the properties of methods of each
object and to help navigate the object model. Unlike the
other files in the table, the UniSim Design Type Library is
always installed, even when you do not install the
Extension Development Kit.
extsdk.bas Contains constants defined by UniSim Design in a format
that can easily be included in a Visual Basic project. This
allows the extension developer to refer to UniSim Design
constants through Const definitions, rather than through
numbers. This information can also be read from the
UniSim Design Type Library, if your programming language
supports this.
extsdk.cpp Contain support code that can be included in a C++
and project. They implement a ClassFactory for any extensions
extsdk.hpp in the project and also implement the DllRegisterServer and
DllUnregisterServer methods. These files compile in both
Microsoft Visual C++ and Borland C++.
UniSimDesig Contains definitions of all the interfaces and enumerations
n.hh found in the UniSim Design Type Library. Including this file
in your C++ source allows you to call methods on UniSim
Design interfaces.
UniSimDesig Instantiates all of the GUIDs defined by UniSim Design. It
niid.cc can be included as part of a C++ project to allow reference
to UniSim Design GUIDs.
The UniSim Allows you to:
Design View • Define extension information for the registration
Editor program.
• Define Variables for UniSim Design to create and
manage on behalf of an extension.
• Create Views for an extension.

3-7
3-8 Creating an Extension

3.5 Creating an Extension

3.5.1 In Visual Basic
Creating an extension in Visual Basic is a very straightforward
procedure. The following six steps can be used as a general
framework:
1. Create the Extension Definition.
2. Create the Object views.
3. Implement the Required Methods.
4. Register the Extension.
5. Debug the Extension.
6. Distribute the Extension.

These steps are explained in more detail in the following

sections.

Create the Extension Definition

The extension definition The EDF contains important information about an extension that
file, which contains the
definition of the is required by the extension's container in UniSim Design.
extension is created Specifically, it contains information about the variables that the
using the View Editor. extension own (that are managed by the container), and it can
also contain one or more Views for the object.

It is possible to create For each extension, you must provide either a CLSID or a
an EDF with 0 views.
ProgID. Other information that can be provided at this point
includes: the extension description, from which you identify the
extension within UniSim Design, the extension type and the
number of views. For extensions written in Visual Basic, you
must specify a ProgID. The selection of the ProgID is explained
in the following sub-section entitled: Register the Extension.

3-8
 Extensibility 3-9

For more information on Once the preliminary definition information is provided, you
the View Editor see specify the variables that the object owns and that are visible to
Chapter 4 - Extension
View Editor. the user. These variables are of the following types:

Variable Type Description

Numeric • Represent numerical quantities and have a
Variable Type that allows UniSim Design to
manage Unit Conversions for the user.
• May have zero, one, or two dimensions.
• Can also trigger the steady state solver when
they are changed. If this is the case, the variable
operates like other UniSim Design variables in
that the solver performs consistency checking
when values are changed.
Text • Represents a string.
• May be zero- or one-dimensional.
Message Usually associated with buttons in a view. Messages
are sent through the VariableChanged method of an
extension.

Numeric Variables and Text Variables may or may not be

persistent. If they are, their values are stored when the
Simulation Case containing the extension is saved.

Create the Object View(s)

A view for your extension is not necessary, but quite often you
want the user to be able to interact with your object. The View
Editor can be used to create views for your object.

A widget is an equivalent Views are created by adding widgets to the DefaultView form.
term for a Visual Basic
Select a widget with the secondary mouse button, drag it on to
control.
the DefaultView form, and drop it. You can then position the
widget to your liking. Double-click the widget to access its
Properties view, from which you can specify detailed information
for the widget. If necessary, you can associate a variable with
the widget.

Each DefaultView form must have a unique name. The object’s

default view must be called DefaultView as it is the view UniSim
Design attempts to open when the object is instantiated,
provided the functionality of the OnView method is not
overridden.

3-9
3-10 Creating an Extension

Implement the Required Methods

To implement an extension from Visual Basic, you must create a
project containing a Class Module. This Class Module must
implement whatever methods are required by the container. For
example, to implement an Extension Unit Operation, you must
implement an Initialize method and an Execute method, and
these methods must have the same parameters as defined by
the interface.

Register the Extension

Before you register your extension, you must ensure that the
ProgID defined by your Visual Basic project is the same as that
which you entered in the EDF for this object. ProgIDs are
defined by Visual Basic in the following form:

ProjectName.ClassName

where:

ProjectName = the name of the project (which is set on the

Project tab of the Options view in VB 5.0)

ClassName = the name of the class (which is set through the

Name parameter of the class' property view).

For Example, a class called Extension1 in a project called

HoneywellExtensionProject would have a ProgID of
HoneywellExtensionProject.Extension1.

For more information on You can register extensions on the Extensions tab of the Session
extension registration Preferences property view.
see Section 3.6 -
Registering
Extensions.

3-10
 Extensibility 3-11

Debug the Extension

For more information on To debug the extension, you can set breakpoints on just about
debugging, please
any line in your Visual Basic class. Initially, you should probably
consult your Visual Basic
manual and help files. set a breakpoint on the Initialize method. Then, start the
extension (via the Start button or the Start command in the Run
menu).

Next, start UniSim Design and create an instance of your

extension. This is done in the same manner as you would create
other objects of the same class. For example, extension Unit
Operations can be created through the UnitOps view (accessed
though the F12 key).

When you create an instance of your extension, UniSim Design

creates a container for it. This container first creates an instance
of your Visual Basic class, and then calls its Initialize method. At
this point, your breakpoint in Visual Basic should be reached.
Now you can inspect variables and step through your code.

You can also use the Debug object in Visual Basic to print
information to the Debug view while the extension runs.

Distribute the Extension

Once you are confident that your extension is behaving properly,
you can create an ActiveX DLL file. Create the DLL file by
selecting the appropriate option from Visual Basic’s File menu.
The end result of this step is an extension that you can
distribute without exposing any proprietary information or
methods.

To distribute your extension, you must provide the DLL file, the
EDF file, and any other files required by your extension (i.e., a
separate FORTRAN DLL called from your extension). You must
register your extension on each individual machine that uses the
extension calculations. You can use the registration tool found
on the Extensions tab of the Session Preferences property view
for this, or you can include this step in your own setup program.

3-11
3-12 Creating an Extension

3.5.2 In C++
The following six steps provide a framework for creating an
extension in C++:
1. Create the Extension Definition.
2. Implement the Required Interfaces.
3. Implement the ClassFactory.
4. Create and Register the DLL.
5. Debug the Extension.
6. Distribute the Extension.

These steps are explained in more detail in the following

sections.

Create the Extension Definition

The extension definition The EDF contains important information about an extension that
file, which contains the
definition of the
is required by the extension's container in UniSim Design.
extension is created Specifically, it contains information about the variables that the
using the View Editor. extension own (that are managed by the container), and it may
also contain one or more Views for the object.

It is possible to create For each extension, you must provide either a CLSID or a
an EDF with 0 views.
ProgID. Other information that can be provided at this point
includes: the extension description, from which you identify the
extension within UniSim Design, the extension type and the
number of views. The selection of the ProgID is explained in the
following sub-section entitled: Register the Extension.

3-12
 Extensibility 3-13

For more information on Once the preliminary definition information is provided, you
the View Editor see specify the variables that the object owns and that is visible to
Chapter 4 - Extension
View Editor. the user. These variables are of the following types:

Variable Type Description

Numeric • Represent numerical quantities and have a
Variable Type that allows UniSim Design to
manage Unit Conversions for the user.
• May have zero, one, or two dimensions.
• Can also trigger the steady state solver when
they are changed. If this is the case, the variable
operates like other UniSim Design variables in
that the solver performs consistency checking
when values are changed.
Text • Represents a string.
• May be zero- or one-dimensional.
Message Usually associated with buttons in a view. Messages
are sent through the VariableChanged method of an
extension.

Numeric Variables and Text Variables may or may not be

persistent. If they are, their values are stored when the
Simulation Case containing the extension is saved.

Implement the Required Interfaces

To create an extension in C++, you must create a class that
implements the required interfaces. For example, an Extension
Unit Operation must implement the ExtensionObject interface
and the ExtensionUnitOperation interface. This calculation can
be done through inheritance or aggregation. UniSim Design
functions if either approach is taken, as long as the interfaces
are supported through the COM QueryInterface mechanism.

To implement an extension, you must provide code for the

standard COM IUnknown methods (AddRef, Release,
QueryInterface), as well as any methods required by the
interfaces you are supporting. Other methods may return
E_NOTIMPL if you choose not to implement them.

3-13
3-14 Creating an Extension

Definitions of the interfaces that you must implement (as well as

any interfaces provided by UniSim Design objects) are provided
in the UniSimDesign.hh file, that is included in the Extension
Development Kit. You must include this file in any source files
that access the defined interfaces.

Implement the Class Factory

When UniSim Design creates an instance of your extension
object, it accesses the COM Library which calls the function
DllGetClassObject which is contained in the DLL. DllGetObject
creates the requested class factory. You can implement a
ClassFactory yourself, or you can use the one provided in
extsdk.cpp (which is included in the Extension Development
Kit).

If you choose to use the ClassFactory provided by extsdk.cpp,

you must implement the REGISTER_EXTENSION macro
somewhere in your code. This macro provides information to the
ClassFactory on how to create an instance of your extension.
The syntax of this macro is:
REGISTER_EXTENSION(ClassName, clsid, VisibleDescription)

where:

ClassName = the C++ name of the class

clsid = the CLSID of the class

VisibleDescription = a string containing a description of the

class that a user can understand

You must implement this macro once for every extension in your
DLL.

3-14
 Extensibility 3-15

Create & Register the DLL

When you build your project, you must implement it as a 32-bit
Dynamic Link Library (DLL). This DLL must contain code for your
extension, a ClassFactory to create your extensions, and a
DllRegisterServer entry point.

The Extension Development Kit provides extsdk.cpp, which

contains a ClassFactory and an implementation of
DllRegisterServer. If you use this ClassFactory, you must include
this file in your project.

For more information on You can register your DLL on the Extensions tab of the Session
extension registration
see Section 3.6 - Preferences property view.
Registering
Extensions.
Debug the Extension
You can debug your extension by putting a call to the Win32
function DebugBreak in your code. When UniSim Design
executes this part of your code, you are allowed to start your
debugger and debug the code from there. You are then able to
inspect variables, and trace the execution of your extension's
code. You can also debug your extension in MS DevStudio by
setting breakpoints in the code. Specifying the path of the
UniSim Design executable file in the Executable for debug
session field on the Debug tab of the Project Settings view and
launch VC++ auto debug.

You can load your extension by starting UniSim Design and

creating an instance of the extension. UniSim Design creates a
container, and this container then calls the extension's Initialize
method.

3-15
3-16 Creating an Extension

Distribute the Extension

Once you are confident that your extension is behaving properly,
you can create an ActiveX DLL file. The end result of this step is
an extension that you can distribute without exposing any
proprietary information or methods.

To distribute your extension, you must provide the DLL file, the
EDF file, and any other files required by your extension (i.e., a
separate FORTRAN DLL called from you extension). You must
register your extension on each individual machine that uses the
extension calculations. You can use the registration tool found
on the Extensions tab of the Session Preferences property view
for this, or you can include this step in your own setup program.

3-16
 Extensibility 3-17

3.6 Registering Extensions

In order for UniSim Design to find extensions, they must be
registered in the Extensions tab of the Session Preference view.
UniSim Design looks for extensions in the:
HKEY_CLASSES_ROOT\Software\Honeywell\UniSimDesign\1.1\Ex
tensions key.

Each extension should have the following information under this

key:

KeyName = Descriptive Name of Extension

ExtensionDefinitionFile = name of Extension Definition File
ExtensionType = type, class
CLSID = CLSID of Extension or
ProgID = ProgID of Extension

See Chapter 4 - All this information is provided when the EDF is created in the
Extension View Editor
for more information on
View Editor.
creating an EDF.
Extensions can be registered with either a CLSID (Class
Only one of the ProgID
or CLSID values can be Identifier) or a ProgID (Program Identifier). It is recommended
used. that ProgID be used for extensions created in Visual Basic, and
CLSID be used for all other extensions.

The Extension Definition File entry gives the name of the

Extension Definition File for the object.

The type of the extension is given by the ExtensionType entry.

The type can be UnitOperation, PropertyPackage or
KineticReaction. The class descriptor is optional, and currently is
ignored if present.

3-17
3-18 Registering Extensions

3.6.1 Registering Extensions

Written in C++
When you create an extension in C++, you must implement a
DllRegisterServer function in the DLL containing the extension.
This function is called from UniSim Design when registering the
extension. The file extsdk.cpp that is included with the
Extension Development Kit provides code that implements this
function.

Ensure that the EDF and To register an extension written in C++, simply use the
extension DLL are in the
following procedure:
same directory.
1. Start UniSim Design. From the Tools menu, select
Preferences command. The Session Preferences view
opens.
2. Go to the Extensions tab and click the Register an
Extension button. This opens the Select an Extension to
be Registered view.
3. Use the File Path group to find the directory in which the
DLL file is saved. Once you find the DLL file, select it and
click the OK button.

Figure 3.2

3-18
 Extensibility 3-19

The Extensions tab should now appear similar to the figure

below.

Figure 3.3

You are now ready to use the extension in UniSim Design.

3-19
3-20 Registering Extensions

3.6.2 Registering Extensions

Written in Visual Basic
Extensions written in Visual Basic may be run from within Visual
Refer to Section 3.6.1 - Basic, or may be compiled to an ActiveX DLL file. Either way,
Registering
Extensions Written in Visual Basic takes care of registering half of the information
C++, for the step by required for UniSim Design to find the extension. The UniSim
step procedure for Design registration tool provided in the Session Preferences
registering UniSim
Design extensions. property view may be used to register the other half.

Running Within Visual Basic

To view EDF files in If you are running your extension within the Visual Basic
Select an Extension to
be Registered view, you environment, Visual Basic temporarily adds information to the
must change the registry every time the project is run. This information changes
settings in the File Filter
drop-down list from
every time you run the project. The extra information needed
Application Extensions can be added by going to the Extensions tab of the Session
(*.dll) to Extension Preferences property view and registering the EDF file. When
Definition Files (*.edf).
run this way, information about where to find an extension is
added to the registry, but information on how to create it is not.

Compiled DLL Files

When you compile your extension to an ActiveX DLL file, you
must do both parts of the registration. You can use the
procedure described in the Section 3.6.1 - Registering
Extensions Written in C++ to register the DLL files in the
UniSim Design Session Preferences.

UniSim Design loads the DLL file and registers it, and then it
takes the name of the DLL file and looks for an Extension
Definition File with the same name in the same directory to
complete the registration.

3-20
 Extensibility 3-21

3.7 Extension Interface

Details
Three types of extensions can currently be created for use
within UniSim Design:
• Unit Operations
• Kinetic Reactions
• Property Packages

Each extension type is associated with a unique container

interface derived from the ExtnContainer object. For instance
Unit Operation Extensions have an ExtnUnitOperation interface.

3.7.1 ExtnContainer Interface

Each type of extension has a unique container associated with it.
Each container implements an interface that provides methods
and properties for the extension.

Derived from Properties Methods

IDispatch ExtensionInterface ClearStatusBar
FPStatus FindVariable
OnOleEnabledThread OpenContainerStorage
SimulationCase OpenView
StatusBar Trace
WaitForTurn

3-21
3-22 Extension Reaction Kinetics

3.7.2 ExtensionObject
Interface
Every extension must implement the ExtensionObject interface.
This interface defines methods that are common to all UniSim
Design extensions. No methods in this interface are mandatory;
that is, all methods may be ignored if the extension does not
implement them.
Derived from Properties Methods
IDispatch none OnHelp
Save
StatusQuery
Terminate
VariableChanged
VariableChanging

3.8 Extension Reaction

Kinetics
You can add your own Reaction Kinetics expressions to UniSim
Design though the Reaction Kinetics Extension. These
extensions appear to the user like any other UniSim Design
reaction type. Additionally, you can specify which components
partake in the expression, as well as define new properties for
the reactants.

To implement an extension Kinetic Reaction, you must

implement two interfaces

Interface Description
ExtensionObject Called when reaction extension is added to the
simulation.
ExtnKineticReaction Called when the reaction extension is used.

The container for the extension supports the

ExtnKineticReactionContainer interface. This acts as the
interface to all the widgets and variables in the UniSim Design

3-22
 Extensibility 3-23

standard kinetic reaction view.

These previously described interfaces allow a reaction to be

implemented and associated with a UniSim Design case through
a fluid package. The Reaction Extension also requires the
definition of two methods in order for the extension to be viable:

Method Description Details

Initialize The Initialize method is ByVal Container as
called whenever the ExtnUnitOperationContainer
extension is first added The kinetic reaction container object.
or whenever a case
containing the ByVal IsRecalling as Boolean
extension is reopened. Value related to the state of the extension. False if
This is also the created for the first time. True if there is an
procedure where you existing extension.
would usually set the
Initialize as Long (Return Value)
state of the properties
and define the Return value must be the current UniSim Design
reactants used. build. A constant extnCurrentVersion is provided in
the type library for this purpose.
ReactionRa Called when the ByVal hyFluid as Fluid
te reaction extension is Fluid based on the input stream to the operation.
used. The method is a
function that returns ByVal RxnTemperatureInC as Double
true when successful Reaction Temperature in UniSim Design internal
and false if an error units of Celsius.
occurs. The calculation
ByVal RxnVolumeInKmolPerM3 as Double
involves returning a
rate value through the Reaction volume in UniSim Design internal units of
‘Rate’ argument while cubic meters.
the UniSim Design Rate as Double
solver iteratively calls
the ReactionRate Rate value, passed by reference, so its value can
method. manipulated and permanently altered within the
method.
ReactionRate as Boolean
True if rate could be calculated, False if there is an
error.

3-23
3-24 Extension Reaction Kinetics

Extension Definition Files

An extension definition file is required for the kinetic reaction
extension. Since UniSim Design uses a specific interface for
reaction extensions, the view within the EDF is not the primary
view when the extension is accessed in UniSim Design. If you do
create a customized view in the View Editor, you can access it
through the View Extension Parameters button found on the
Parameters tab.

Figure 3.4

3.8.1 ExtnKineticReaction
Interface
The ExtnKineticReaction interface must be implemented by all
extension kinetic reactions. In addition to the Initialize and
Reaction Rate methods which are mandatory, the interface also
has the following associated properties and methods:

Derived from Properties Methods

IUnknown IsReady BasisChanged
ReactionRate2

3-24
 Extensibility 3-25

3.8.2 ExtnKineticReactionCont
ainer Interface
The ExtnKineticReactionContainer interface is passed to an
extension Kinetic Reaction in its Initialize method.

Derived from Properties Methods

ExtnContainer • BaseReactant • AddReactantProperty
• BasisConversion • RemoveReactantProperty
• MaxTemperature • SetReactionPropertyState
• MinTemperature
• Phase
• RateConversion
• Reactants
• ReactionBasis

3-25
3-26 Extension Reaction Kinetics

3.8.3 Kinetic Reaction Example

In this example, you use Visual Basic 5.0 to build a reaction
kinetics extension for a reaction involving vinyl acetate.
1. Create a new project in Visual Basic 5.0 from the New tab of
the New Project view. Select the ActiveX.DLL icon as the
project type and click the Open button.
ActiveXDLL icon 2. Make sure that the UniSim Design 3.* Type Library is
checked in the References view, which is accessed by
selecting the References command from the Project
menu.

Figure 3.5

3. In the Properties tiled view, ensure that the Instancing

drop-down list is set to 5-MultiUse.
4. In the Properties tiled view, rename the class module
VinylAc.
5. Save the class and project by selecting Save Project
command from the File menu. Save the class and project as
VinylAc.cls and VinylAc.vbp

Properties view

3-26
 Extensibility 3-27

6. You are now ready to define the class. Begin by defining the
global variables in the Project VinylAc Code view:

Code Explanation
Option Explicit Used to force explicit declaration of
all variables in that module.
Dim hyContainer As Object Declare the global UniSim Design
Dim hyBulkDens As Object objects. The hy prefix is a
convention to identify variables
which come from UniSim Design.

7. The first function declared is the Initialize function. It is

called when the extension is first added to UniSim Design or
when a case containing the extension is loaded.

Code Explanation
Public Function Initialize(ByVal Container As Initialize is called when the extension is
Object, ByVal IsRecalling As Boolean) As Long first added to the simulation or when a
simulation case containing the extension
is loaded.
On Error GoTo ErrorTrap Enable Error trapping.
Dim hyReactant As Reactant Declare KineticReactionContainer
variable.
Initialize = extnCurrentVersion Reference the current UniSim Design
version
Set hyContainer = Container This reference lets the extension interact
with UniSim Design through the
extension container, the
ExtnKineticReactionContainer object.
Methods from the ExtensionObject object
are also available.
Set hyBulkDens = Set an object reference to the BulkDens
hyContainer.FindVariable("BulkDens").Variabl variable, which is created in the EDF file.
e
If IsRecalling = False Then The variable IsRecalling is only False
hyBulkDens.Value = 2700 when the extension is first added to the
simulation. This sets a default for
BulkDens (2700 kg catalyst/m3 reactor
volume).
hyContainer.Phase = ptVapourPhase Setting the remaining reaction properties
hyContainer.ReactionBasis = (usually found on the Basis tab of the
Reaction view). The Phase of the
rbPartialPressBasis reaction is to be Vapour and the reaction
Basis is to be Partial Pressure.
hyContainer.Reactants.RemoveAll This initializes the reactants list by
removing any reactants that may be
specified.

3-27
3-28 Extension Reaction Kinetics

Code Explanation
Set hyReactant = Adds the component Ethylene as a
hyContainer.Reactants.Add("Ethylene") Reactant. It sets the stoichiometric
coefficient of ethylene as -1 (i.e., 1 mole
hyReactant.StoichiometricCoefficientValue of ethylene being consumed). You are
= -1 also specifying ethylene to be the base
hyContainer.BaseReactant = hyReactant reactant.
Set hyReactant = Adds the remaining components and
hyContainer.Reactants.Add("AceticAcid") specifies their stoichiometric coefficients.
hyReactant.StoichiometricCoefficientValue
= -1
Set hyReactant =
hyContainer.Reactants.Add("Oxygen")
hyReactant.StoichiometricCoefficientValue
= -0.5
Set hyReactant =
hyContainer.Reactants.Add("VinylAcetate")
hyReactant.StoichiometricCoefficientValue
= 1
Set hyReactant =
hyContainer.Reactants.Add("H2O")
hyReactant.StoichiometricCoefficientValue
= 1
hyContainer.BasisConversion = "psia" Sets the Basis Conversion units to psia.
The Rate Conversion units is left in
UniSim Design internal units of kg mole/
m3-s.
With hyContainer Sets the property states as Calculated so
.SetReactionPropertyState rpReactants, that they cannot be modified.
vsCalculated The With statement is used for efficiency
.SetReactionPropertyState since each line uses the
SetReactionPropertyState method of
rpStoichiometricCoefficients, vsCalculated the hyContainer object.
.SetReactionPropertyState
rpMinTemperature, vsCalculated
.SetReactionPropertyState
rpMaxTemperature, vsCalculated
.SetReactionPropertyState
rpReactionBasis, vsCalculated
.SetReactionPropertyState
rpReactionPhase, vsCalculated
.SetReactionPropertyState
rpBaseReactant, vsCalculated
.SetReactionPropertyState
rpBasisConversion, vsCalculated
.SetReactionPropertyState
rpRateConversion, vsCalculated
End With
End If

3-28
 Extensibility 3-29

Code Explanation
ErrorTrap: Line to which the On Error statement
branches if an error occurs
End Function Signifies the end of the function. This line
does not need to be added.

8. The other function that is required to implement a kinetic

reaction extension is the ReactionRate function.

Code Explanation
Public Function ReactionRate(ByVal Fluid As This function is called whenever the
Object, ByVal RxnTemperatureInC As Double, extension is executed.
ByVal RxnVolumeInKmolPerM3 As Double, rate As
Double) As Boolean
On Error GoTo ErrorTrap Enable Error trapping.
Dim TotalPressure As Double Declare local variables.
Dim RxnTemperatureinK As Double
Dim EthyleneIndex As Integer
Dim AceticAcidIndex As Integer
Dim OxygenIndex As Integer
Dim WaterIndex As Integer
Dim ComponentFracs As Variant
Dim EthylenePP As Double
Dim AceticAcidPP As Double
Dim OxygenPP As Double
Dim WaterPP As Double
If hyBulkDens.Value <= 0 Then Check to see if the value of hyBulkDens >
hyBulkDens.Value = 2700 0. If not, then sets it to the default value
of 2700 kg catalyst/m3 reactor volume.
TotalPressure = Gets the overall pressure of the reaction
Fluid.Pressure.GetValue("psia") in psia.

RxnTemperatureinK = RxnTemperatureInC + Get the temperature of the reaction K.

273.15
EthyleneIndex = Get component index numbers. These
Fluid.Components.Index("Ethylene") index numbers are later used to
reference the components and their
AceticAcidIndex = properties.
Fluid.Components.Index("AceticAcid")
OxygenIndex =
Fluid.Components.Index("Oxygen")
WaterIndex = Fluid.Components.Index("H2O")
ComponentFracs = Fluid.MolarFractionsValue Set ComponentFracs equal to the
component molar fractions of the fluid.

3-29
3-30 Extension Reaction Kinetics

Code Explanation
EthylenePP = ComponentFracs(EthyleneIndex) * Get partial pressure of components in
TotalPressure psia by multiplying component mole
fraction by total pressure (Smith and Van
AceticAcidPP = Ness, p. 300).
ComponentFracs(AceticAcidIndex) *
TotalPressure
OxygenPP = ComponentFracs(OxygenIndex) *
TotalPressure
WaterPP = ComponentFracs(WaterIndex) *
TotalPressure
rate = 0.1036 * Exp(-3674 / Calculate the reaction rate1. The rate is in
RxnTemperatureinK) * OxygenPP * EthylenePP * g mol AceticAcid consumed/min-g
catalyst. hyBulkDens.Value is
AceticAcidPP * (1 + 1.7 * WaterPP) / ((1 + multiplied by 1000 to convert it to g
0.583 * OxygenPP * (1 + 1.7 * WaterPP)) * (1 + catalyst/m3 reactor volume.
6.8 * AceticAcidPP)) * hyBulkDens.Value *
1000
rate = rate / 1000 / 60 Since the units required by UniSim
Design are kg mole/m3-s, divide by 1000
g mol/kg mol and divide by 60 s/min.
ReactionRate = True Tell UniSim Design that the calculation
worked as expected.
ErrorTrap: Line to which the On Error statement
branches if an error occurs.
End Function Signifies the end of the function. This line
does not need to be added.

9. Select Make VinylAc.dll command from the File menu. The

Make Project view appears.

Figure 3.6

3-30
 Extensibility 3-31

10. Select the folder you want to save the VinylAc.dll file in, and
click the OK button.

Creating the Extension Definition File (EDF)

In order to complete the Kinetic Reaction Extension, you must
create an EDF. This is done through the Extension View Editor.

If it has been installed, the Extension View Editor is found in

the same launch point in the Start menu as UniSim Design.
For more information on installing and accessing the View
Editor, see Section 4.1.1 - Accessing the View Editor.

1. Open the Extension View Editor and open a new EDF by

doing one of the following:
• Select New command under the File menu in the menu
bar
• Use the hot key combination CTRL N
• Click the New File icon
The default View Manager view appears as shown below:
New File icon
Figure 3.7

The file path in

the View File
group may be
different,
depending on
where you
installed UniSim
Design.

2. Click the Objects Manager icon to open the Objects

Manager view.
Objects Manager icon

3-31
3-32 Extension Reaction Kinetics

3. In the ProgID/CLSID field enter RxnExtn.VinylAc as the

extension ID.
4. Enter an appropriate description for the extension in the
Description field, such as Vinyl Acetate Reaction
Extension as shown in Figure 3.8.
5. Select Kinetic Reaction as extension type in the Type drop-
down list.
6. Specify the information in the Variables of Selected Object
group as shown below, and check the Persistent checkbox.

Figure 3.8

3-32
 Extensibility 3-33

7. Click the Close button. This returns you to the Views

Manager view.

Figure 3.9

8. From the Existing Views list, select the DefaultView and click
the Edit button. The DefaultView form appears. It consists of
several default objects that are not used in this example.
These objects have to be deleted.

3-33
3-34 Extension Reaction Kinetics

9. Begin by deleting the Page Tabs widget. Select the tabs

found at the bottom of the DefaultView form as shown below
and press the DELETE key.

Figure 3.10

Static
Text

Text
Entry

Page
Tabs

10. Delete the Name Static Text widget and the Object Name
Text Entry widget using the method described in the step
above.
11. Resize the DefaultView form into a smaller view, as shown
below.

Figure 3.11

3-34
 Extensibility 3-35

Adding Widgets to the DefaultView form

1. From the Widgets Palette select a Numerical Input widget.
Right-click, hold, and drag the widget into the DefaultView
form. When you find an appropriate part of the view to place
the widget, release the mouse button and the widget should
drop into place.
2. Using the drag and drop method described in the above step
to add the two Static Text widgets and a Button widget as
shown below.

Figure 3.12

3. Now the widgets must be defined. To open a widget’s

properties do one of the following:
• Double-click on the widget
• Right-click the widget and select <Widget Type>
Properties command from the Object Inspect menu,
where Widget Type would be Button for a Button widget.
4. For the upper Static Text widget specify properties as shown
below. When you are finished click the OK button.

Figure 3.13

3-35
3-36 Extension Reaction Kinetics

5. For the lower Static Text widget specify properties as shown

below. When you are finished click the OK button.

Figure 3.14

The Target Moniker field 6. For the Numerical Input widget specify properties as shown
is specified by clicking
the Ellipsis icon
below. When you are finished click the OK button.
associated with the field
and selecting Bulk Figure 3.15
Density from the Select
Number Variable view.

Ellipsis icon

7. Open the properties view for the Button widget.

8. In the Label field specify the button label as &Close where
the & indicates the hot key underscore designation (i.e.,
pressing ALT + hot key brings focus to this object).
9. Click the Ellipsis icon associated with the Message field to
open the Edit Messages view.

3-36
 Extensibility 3-37

10. Click the Insert button on the Edit Messages view. The
Select Message view appears. Select the Close the View
message from the list.

Figure 3.16

11. Click the OK button to add this message to this button. The
Edit Messages view appears as shown below.

Figure 3.17

12. Click the OK button on the Edit Messages view to close this
view and return to the Button Properties view.

3-37
3-38 Extension Reaction Kinetics

13. Specify the Name field as shown below. When you are
finished click the OK button.

Figure 3.18

The view now appears as shown below.

Figure 3.19

14. Select Save command from the File menu and save the EDF
file as “VinylAc.edf” in the same directory as the DLL file.

3-38
 Extensibility 3-39

Attaching the Extension to UniSim Design

You are now ready to attach the extension to UniSim Design.
The following steps demonstrate how to attach an extension
within UniSim Design.
1. Start UniSim Design. From the Tools menu, select
Preferences command. The Session Preferences view
appears.
2. Go to the Extensions tab and click the Register an
Extension button. The Select an Extension to be Registered
view appears.
3. Use the File Path group to find the directory in which the
VinylAc.dll file is saved in. Once you find the DLL file, select
it and click the OK button.

Figure 3.20

4. The UniSim Design Extension Registration view appears and

displays whether the registration was successful or not. Click
the OK button to close the view.

3-39
3-40 Extension Reaction Kinetics

The Extensions tab should now appear similar to the figure

below.

Figure 3.21

5. You can now go to the Reactions tab of the Simulation Basis

Manager view and add a VinylAcetate Reaction Extension
from the Reactions view.

Figure 3.22

3-40
 Extensibility 3-41

3.9 Extension Property

Packages
You can put your own physical property calculations into UniSim
Design as an Extension Property Package, which appears to the
user as any other property package in the program.

UniSim Design makes calls to property packages under a

number of different situations. Calls are made in both Steady
State and Dynamics mode.

To implement an Extension Property Package, you must

implement two interfaces:

Interface Description
ExtensionObject Called when the property package extension
is added to the simulation.
ExtnPropertyPackage Called when the property package extension
is used.

Many different methods must be supported by Extension

Property Packages; however, depending on what functionality is
supported, certain methods may be left unimplemented. The
extension must let its container know which features it supports
through the ExtensionPPkgInit structure passed to the extension
in its Initialize method.

The ExtnPropertyPackage interface is not a dual interface; for

efficiency, non-ActiveX Automation compatible data types are
passed as parameters. This means that Extension Property
Packages cannot be easily written in Visual Basic, and cannot be
implemented as Local Servers.

3-41
3-42 Extension Property Packages

Initialization
When an Extension Property Package is initialized, it must fill in
the ExtensionPPkgInit structure passed to it by its container.
This structure lets the container know which features the
extension supports, such as requirements for a component slate
and whether or not the property package can handle changes to
the component slate order.

An Extension Property Packages can be as simple as a steam

table, or as complex as an activity model or equation of state
package. UniSim Design behaves differently for property
packages of differing functionality. For example, if a given
property package cannot handle hypothetical components, you
are not allowed access to the Oil Environment for that property
package.

Component Slates
If the Extension Property Packages has a fixed component slate,
UniSim Design pre-selects those components, and does not
allow the user to remove them or add other components. The
extension lets its container know of this restriction by setting
the NumberOfPreselectedComponents member of the
ExtensionPPkgInit structure to a non-zero value. UniSim Design
then calls the extension's GetPreselectedCompIDs method at a
later point. If zero is passed for the
NumberOfPreselectedComponents member, UniSim Design
allows you to select whatever components are available.

Filtering of the component list is done through the

implementation of the IsComponentAllowed method. This
method returns True if the component with the passed
ComponentID is supported by the property package, or False if
it is not. If the extension has a fixed component slate (that is, it
has returned a non-zero for NumberOfPreselectedComponents),
the container handles the implementation of the
IsComponentAllowed method, allowing the extension developer
to return E_NOTIMPL for the method.

3-42
 Extensibility 3-43

If the property package cannot handle changes to the

component slate, the CanExchangeComponents flag can be set
in the ExtensionPPkgInit structure. If this flag has been set,
UniSim Design only allows you to add or remove components
from the end of the list.

ExtensionPPkgInit structure
This structure is passed to an Extension Property Packages in its
Initialize method. The extension must fill in the structure
according to its capabilities.

typedef struct
{
long StructSize;
long Version;
long NumberOfPreselectedComponents;
enum DynamicPropertyMethod DynPropMethod;
VARIANT_BOOL IsActivityModelType;
VARIANT_BOOL CanExchangeComponents;
VARIANT_BOOL CanCalculateFugacity;
VARIANT_BOOL CanCalculateLLE;
VARIANT_BOOL CanHandleOilHypos;
VARIANT_BOOL UseGFlashInDynamics;
VARIANT_BOOL CanHandleInsideOutPHFlash;
} ExtensionPPkgInit;

Data Member Details

StructSize This data member contains the size of the
ExtensionPPkgInit structure.
Version This data member must be filled in with
extnCurrentVersion.
NumberOfPreselectedComponents If the property package has a fixed component
slate, this number should be a non-zero value.
DynPropMethod This must be set to the type of Dynamic Property
Method to be used with the property package. See
DynamicPropertyMethod_enum in the type
library.
IsActivityModelType This should be set to True if the property package
can be considered an activity model property
package. A number of flash algorithms in UniSim
Design optimize their algorithms based on the
value of this data member.

3-43
3-44 Extension Property Packages

Data Member Details

CanExchangeComponents This member should be set to True if the property
package can handle changes to the location of
components in the component slate.
CanCalculateFugacity This should be set to True if the property package
has implemented the ComputePhaseFugacities
method. If it is set to False, this method is never
called.
CanCalculateLLE This should be set to True if the property package
can calculate liquid-liquid equilibrium calculations
using the inside-out algorithm. If this is set to
True, the property package must implement the
ComputeHInnerParamsLL and ComputeKFactorsLL
methods.
CanHandleOilHypos If the property package can handle Oil
hypotheticals, this should be set to True. If it is set
to False, the user is not allowed in to the Oil
Environment.
UseGFlashInDynamics This flag is used to optimize thermodynamic
calculations in dynamics. If is recommended that
this be set to True unless the property package is
an equation of state.
CanHandleInsideOutPHFlash This flag disables the inside-out enthalpy flash if it
is set to False. It is recommended that this flag be
set to True unless the property package operates
on a narrow temperature range.

3.9.1 ExtnPPkgContainer
Interface
The ExtnPPkgContainer interface is passed to an Extension

3-44
 Extensibility 3-45

Property Package in its Initialize method.

Derived from Properties Methods

ExtnContainer NumberOfComponents BuildPlot
BreakRequested BuildPlot2
ExtensionInterface BuildPlotWithCallback
FPStatus ClearStatusBar
name DeletePlot
OnOleEnabledThread FindVariable
SimulationCase GetComponent
StatusBar GetPlot
GetPlot2
OpenContainerStorage
OpenView
Trace
WaitForTurn

3.9.2 ExtnPropertyPackage
Interface
The ExtnPropertyPackage interface must be implemented by all
Extension Property Packages. Only the Initialize method must
be supported, all others could return E_NOTIMPL.

Derived from Properties Methods

IUnknown none AddComponent CopyPropertyPackage
ComponentChanged DynTreatComponentAsInert
ComputeHInnerParamsLL EndBasisChange
ComputeHInnerParamsVL ExchangeComponents
ComputeKFactors ExchangeTwoPhases
ComputeKFactorsLL GetPreSelectedCompIDs
ComputeKFactorsVL GuessBubblePointTemperature
ComputeLiquidMolarDensity Initialize
ComputeLiquidSurfaceTension InitializeKFactors
ComputePhaseActivity IsComponentAllowed
ComputePhaseFugacities OrderPhases
ComputePhaseProperties QueryEndBasisChange
ComputePhaseThermalConductivity RemoveComponent
ComputePhaseViscosity StartBasisChange

3-45
3-46 Extension Property Packages

The ExtnPropertyPackage interface is not a dual interface,

and methods of the interface will not be called through the
Dispatch Invoke mechanism.

3-46
 Extensibility 3-47

3.10 Extension Unit

Operations
You can implement Unit Operation calculations in UniSim Design
by creating an Extension Unit Operation.

To implement an Extension Unit Operation, you must implement

two interfaces:

Interface Description
ExtensionObject Called when unit operation extension is added to
the simulation.
ExtnUnitOperation Called when the unit operation extension is used.

These objects allow the unit operation to function in the UniSim

Design environment. The minimum requirements for the Unit
Operation Extensions is the definition of two methods:

Method Description
Initialize The Initialize method is called whenever the extension is first
added or whenever a case containing the extension is reopened.
The Initialize method is a function that expects the current build
value of UniSim Design to be returned. By referencing the
UniSim Design Type Library it is possible to use the constant
extnCurrentVersion to return the proper build value.
The Initialize method passes two arguments when it is called.
The first argument is the extension container object. With the
extension container object, all the variables declared in the EDF
can be accessed. The second argument “IsRecalling” is used to
determine if the extension is being added for the first time or if
the case already contained the extension. This flag can be used
to set default values or to assure that the values specified by
the user are not overwritten by the default values.

3-47
3-48 Extension Unit Operations

Method Description
Execute Extension Unit Operations perform their calculations within their
Execute method. This method is called by the Steady State
Solver during the Execute Passes; it must not be called directly
by the extension.
The Execute method is called whenever a stream connected to
the extension is changed or when any of the variables marked
as trigger solve in the EDF are changed. UniSim Design
automatically calls the Execute method and pass the Forgetting
argument. The Forgetting argument relates to how UniSim
Design solves based on the degrees of freedom approach.
Whenever a variable is changed within UniSim Design, all the
values associated or utilizing that value as a basis for
calculation must be forgotten. This Forget process propagates
throughout the simulation model. It is a good idea to check the
Forgetting argument prior to executing code. Especially if values
that are forgotten are used in the calculation. A forgotten value
is set to the empty state, which, for UniSim Design is the
number -32767.

Extension Definition Files

An extension definition file is required for the custom unit
operation’s visual interface within the UniSim Design
environment and also for the object interface to the ActiveX
Server DLL. Variables that are used through the interface need
to be declared in the EDF.

3.10.1 ExtnUnitOperationCont
ainer Interface
The ExtnUnitOperationContainer interface is passed to an
extension Unit Operation in its Initialize method.

Derived from Properties Methods

ExtnContainer BreakRequested AddSolverNotification FindVariable
ExtensionInterface Balance GetPlot
Flowsheet BuildPlot GetPlot2
FPStatus BuildPlot2 OpenContainerStorage
name BuildPlotWithCallback OpenView
OnOleEnabledThread ClearStatusBar RemoveSolverNotification
SimulationCase CreateFluid SolveComplete
StatusBar DeletePlot Trace
FindFluid TriggerSolve

3-48
 Extensibility 3-49

3.10.2 ExtnUnitOperation
Interface
The ExtnUnitOperation interface must be implemented by all
Extension Unit Operations. Only two methods (the Initialize
method and the Execute method) are mandatory.

Derived from Properties Methods

IDispatch none BasisChanged
Execute
Initialize

3.10.3 Passes
Execute Passes
The Solver performs steady state calculations in two passes: the
Forget Pass and the Calculate Pass. Normally, extension Unit
Operations need not know which pass is underway, but an
IsForgetting parameter is passed to the extension's Execute
method so the extension can optimize calculations if necessary.

The Solver propagates information through the flowsheet via the

Solver Notification links that are set up when connections are
made between objects. Whenever a Unit Operation changes the
value of a variable within a linked object, that object's Execute
method is called. If that object then changes the value of a
variable in another object, the Solver then moves on to that
object.

The propagation of information is completed when no object can

calculate any new information, or if calculated values are within
a tolerance of the value previously calculated. When new values
are within the tolerance, the linked object does not have its
Execute method called.

If two objects calculate the same value in to an object, and

these values are not within the tolerance, an Inconsistency

3-49
3-50 Extension Unit Operations

condition occurs. When this happens, the Solver stops and

switches in to Hold Mode. To allow different objects to calculate
different values because of changes in the flowsheet, it is
necessary that values that depend on another changing value be
forgotten. This forgetting occurs during the Forget Pass.

Forget Pass
When the value of a variable changes, the Solver first does one
Solve Pass on the flowsheet with the value marked as unknown.
Each object that is linked to the object with the changed variable
has its Execute method called, and the object must perform as
many calculations as it can with the remaining known
information.

Any calculations that were performed based on the value of the

newly forgotten variable in the last pass are not able to be
calculated during this pass. After the object has finished its
Execute call, the Solver then determines which variables the
object calculated last time that have not been touched this time.
These variables are then marked as unknown, and the Solver
propagates this information to other linked objects in the
flowsheet.

Normally, an object need not behave any differently during the

Forget Pass than during the Calculate Pass. In order to prevent
unnecessary propagation of forgotten information (and
therefore the unnecessary recalculation of this information in
the Calculate Pass), the object must still calculate all that it can
to ensure that the variables it calculated last time are touched.

Calculate Pass
After all information based on the previous value of a variable
has been forgotten, the new value is set in to the variable and
the second Solver pass (the Calculate Pass) is started. In this
pass, each object affected by the change in the variable has its
Execute method called. Any changes these objects make are
propagated through the flowsheet as the variables in other
objects are touched.

3-50
 Extensibility 3-51

The Execute method of an object can be called more than once

in either of the Solve Passes, as variables in the object are
touched by other objects in the flowsheet.

3.10.4 Extension Unit

Operation Example
In this example, you use Visual Basic 5.0 to build a unit
operation extension that saturates a feed stream with Water.
1. Open a new project in Visual Basic 5.0 and from the New
tab of the New Project property view select the ActiveX.DLL
icon and click the Open button.
ActiveXDLL icon 2. Make sure that the UniSim Design Type Library is
checked in the References view, which is accessed by
selecting References command from the Project menu.

Figure 3.23

3. In the Properties tiled view, rename the class module

Saturate, and ensure that the Instancing field is set to 5-
MultiUse.

Properties tiled view

3-51
3-52 Extension Unit Operations

4. Rename the project name to UnitOpExtn as shown.

Figure 3.24

5. Save the class and project by selecting Save Project

command from the File menu. Save the class and project as
Saturate.cls and Saturate.vbp.

3-52
 Extensibility 3-53

6. Begin by defining the global variables in the Project Code

Editor:

Code Explanation
Option Explicit Used to force explicit declaration of all variables in
that module.
Declare the global UniSim Design objects. The hy
prefix is a convention to identify variables which
come from UniSim Design.
Dim hyContainer As • The extension unit operation container
ExtnUnitOperationContainer object.

Dim hyFeedStrm As Object • The extension feed stream object.

Dim hyProdStrm As Object • The extension product stream object.
Dim hyWatStrm As Object • The extension water stream object.
Declare objects used internally:
Dim Components As Object • The UniSim Design Components collection
object.
Dim Component As Object • A single UniSim Design Component object.
Dim WorkFluid As Object • A fluid object used for calculations.
Dim WatFluid As Object • A water fluid object.
Dim Streams(0 To 2) As Object • An array of ProcessStream objects.
Dim myOp As Object • Object reference to the Extension Interface.
Declare variables used internally:
Dim WaterPresent As Boolean • Indicates if water is present.
Dim H2O As Integer • The index for water.
Dim Temp As Variant • Temporary variable.
Dim MoleFl As Variant • Array of molar flows.
Dim Count As Integer • Count variable.
Dim i As Integer • Count variable.
Dim IsKnownFeedArray As Variant • Are the feed streams in the array valid.
Dim CalcError(0 to 1) As Boolean • Error level used to display status messages.
Dim IsIgnoredBool As Boolean • Indicates if the unit op is ignored.
Const conEmpty As Integer = -32767 • -32767 is used internally by UniSim Design to
represent an empty value.

3-53
3-54 Extension Unit Operations

7. The first function declared is the Initialize function. It is

called when the extension is first added to UniSim Design or
when a case containing the extension is loaded.

Code Explanation
Public Function Initialize(ByVal Container As Initialize is called when the extension is
Object, ByVal IsRecalling As Boolean) As Long first added to the simulation or when a
simulation case containing the extension
is loaded.
On Error GoTo ErrorTrap Enable Error trapping.
CalcError(0) = False Initialize variables.
CalcError(1) = False
Initialize = extnCurrentVersion Reference the current UniSim Design
version.
Set hyContainer = Container This reference lets the extension interact
Set myOp = hyContainer.ExtensionInterface with UniSim Design through the
extension container, the
ExtnUnitOperationContainer object.
Methods from the ExtensionObject
object are also available.
Set Components = Get the list of components that are
hyContainer.Flowsheet.FluidPackage.Component currently attached to the fluid package.
For each component in the list, determine
s if water is one of the components.
WaterPresent = False
If water is present, determine the
For Each Component In Components internal index number of water.
If Component.Name = "H2O" Then
WaterPresent = True
Next
If WaterPresent Then H2O =
Components.Index("H2O")
Set hyFeedStrm = Set an object reference to the Feed,
hyContainer.FindVariable("FeedStream").Varia Product and Water stream attachment
objects in the EDF.
ble.object
Set hyProdStrm =
hyContainer.FindVariable("ProductStream").Va
riable.object
Set hyWatStrm =
hyContainer.FindVariable("WaterStream").Vari
able.object
If IsRecalling = False Then IsRecalling is False when the extension
End If is first added to the simulation,
IsRecalling is True when a saved
simulation case containing the extension
is loaded. The If statement uses
IsRecalling to set defaults. Saturate has
no default values, so none are set here.

3-54
 Extensibility 3-55

Code Explanation
ErrorTrap: Line to which the On Error statement
branches if an error occurs.
End Function Signifies the end of the function. This line
does not need to be added.

8. The other function that is required to implement a Unit

Operation Extension is the Execute function.

Code Explanation
Public Sub Execute(ByVal Forgetting As Boolean) This sub-routine is called whenever the
extension is executed.
On Error GoTo ErrorTrap Enable Error trapping.
If Not Forgetting Then When a change is made to a variable
which affects the extension, UniSim
Design performs a Forgetting pass and
two Calculation Passes. The Forgetting
pass is used to identify the streams, unit
operations, etc. affected by the change.
The first Calculation pass is used to allow
the extension to complete its internal
calculations. The second Calculation pass
is made so that external references made
by the extension use correct values. If
the extension makes no external
references, then the second pass can be
bypassed using the SolveComplete
method of the Container object. This
command is included later in the code.
For efficiency, no calculations are made
during the Forgetting pass.
Set Components = Determine if water is present (ensure it
hyContainer.Flowsheet.FluidPackage.Component hasn't been removed).
s
WaterPresent = False
For Each Component In Components
If Component.Name = "H2O" Then
WaterPresent = True
Next Component
If Not WaterPresent Then GoTo ErrorTrap
H2O = Components.Index("H2O") Get the index for water.

3-55
3-56 Extension Unit Operations

Code Explanation
Set hyFeedStrm = Set an object reference to the Feed,
hyContainer.FindVariable("FeedStream").Varia Product and Water stream attachment
objects in the EDF.
ble.object
Set hyProdStrm =
hyContainer.FindVariable("ProductStream").Va
riable.object
Set hyWatStrm =
hyContainer.FindVariable("WaterStream").Vari
able.object
If hyFeedStrm Is Nothing Then GoTo If the streams are not attached, then
ErrorTrap exit.
If hyWatStrm Is Nothing Then GoTo ErrorTrap
If hyProdStrm Is Nothing Then GoTo
ErrorTrap
If hyFeedStrm.TemperatureValue = conEmpty Determine if the feed stream has the
Then GoTo ErrorTrap information required.
If hyFeedStrm.PressureValue = conEmpty
Then GoTo ErrorTrap
If hyFeedStrm.MolarFlowValue = conEmpty
Then GoTo ErrorTrap
Temp = hyFeedStrm.ComponentMolarFraction
If (Temp(0) = conEmpty) Then GoTo ErrorTrap
Set WorkFluid = hyFeedStrm.DuplicateFluid Create a duplicate fluid object of
MoleFl = WorkFluid.MolarFractionsValue hyFeedStrm and creates an array
containing the mole fraction of each
component in the fluid.
For i = 0 To Components.Count - 1 For every component in the fluid, divide
MoleFl(i) = MoleFl(i) / 10 the mole fraction by a factor of 10. This
means that the current composition of
Next the stream now only make up 10% of the
MoleFl(H2O) = 0.9 + MoleFl(H2O) fluid composition. Make the remaining
WorkFluid.MolarFractionsValue = MoleFl 90% water.
WorkFluid.TPFlash Do a TP Flash on the fluid at the
hyFeedStrm.TemperatureValue, temperature and pressure of the stream
hyFeedStrm. If there is a second phase
hyFeedStrm.PressureValue then an error has occurred.
If WorkFluid.FluidPhases.Count = 1 Then
CalcError(0) = True
GoTo ErrorTrap
End If
Temp = hyWatStrm.ComponentMolarFraction Creates a temporary array containing the
If Temp(0) = conEmpty Then component molar fraction values of the
stream object hyWatStrm (the water
MoleFl = stream).
hyWatStrm.ComponentMolarFraction
If the mole fraction of the first component
in the stream is not specified, then do the
following:

3-56
 Extensibility 3-57

Code Explanation
For i = 0 To Components.Count - 1 Set the mole fraction of every component
MoleFl(i) = 0 in the temporary array to be zero. Then
set the mole fraction of water to be 1.
Next i
MoleFl(H2O) = 1
hyWatStrm.ComponentMolarFraction.Erase Deletes the current component molar
hyWatStrm.ComponentMolarFraction.Calculate fraction values of the stream
hyWatStrm. It then sets the component
MoleFl fraction of the stream to the contents of
the temporary array MoleFl.
ElseIf Temp(H2O) = 0 Then Else if the mole fraction of water in the
CalcError(1) = True stream hyWatStrm is zero then an error
has occurred.
GoTo ErrorTrap
End If
With hyWatStrm Resets the water stream temperature and
.Pressure.Erase pressure at the new molar composition.
.Pressure.Calculate
hyFeedStrm.PressureValue
.Temperature.Erase
.Temperature.Calculate
hyFeedStrm.TemperatureValue
End With
If hyFeedStrm.MolarFlowValue = 0 Then If the feed stream molar flow is 0 then
hyWatStrm.MolarFlow.Calculate 0 exit.
GoTo EndCalcs
End If
Set WorkFluid = hyFeedStrm.DuplicateFluid Creates a duplicate fluid of the feed and
Set WatFluid = hyWatStrm.DuplicateFluid water streams and sets the counter
variable Count to zero.
Count = 0
If WorkFluid.FluidPhases.Count > 1 Then If the number of phases in the feed
hyWatStrm.MolarFlow.Calculate 0 stream fluid is greater than 1, then set
the molar flow of the water stream to
GoTo EndCalcs zero.
End If
Do While WorkFluid.FluidPhases.Count = 1 Determine water stream flow required to
Count = Count + 1 saturate feed stream.
Set WorkFluid = While the number of phases in the feed
hyFeedStrm.DuplicateFluid stream is still one, increase the molar
flow of the water stream. Add the feed
WatFluid.MolarFlowValue = and water streams and reflash the
WorkFluid.MolarFlowValue * (Count / 20) stream at the feed stream’s temperature
WorkFluid.AddFluid WatFluid and pressure.
WorkFluid.TPFlash
hyFeedStrm.TemperatureValue,
hyFeedStrm.PressureValue
Loop
MoleFl = Set MoleFl to the values of the
WorkFluid.HeavyLiquidPhase.MolarFlowsValue component molar flows of the heavy
liquid phase of the fluid object WorkFluid.

3-57
3-58 Extension Unit Operations

Code Explanation
Temp = WatFluid.MolarFlowValue - Set the variable Temp to be the difference
MoleFl(H2O) between the flow rate of the water
stream and component molar flow rate of
If Temp < 0 Then Temp = 0 water in the heavy liquid phase of the
hyWatStrm.MolarFlow.Calculate Temp saturated stream. If the difference is
negative (i.e., no water is required), set
the molar flow rate of the water fluid to
zero.
EndCalcs: Begin the end calculations procedure.
WorkFluid.Erase Erase contents of the fluid.
WatFluid.Erase
With hyProdStrm Set product stream temperature and
.Pressure.Erase pressure values.
.Pressure.Calculate
hyFeedStrm.PressureValue
.Temperature.Erase
.Temperature.Calculate
hyFeedStrm.TemperatureValue
End With
If hyFeedStrm.MolarFlowValue = 0 Then If feed stream molar flow is 0 then
calculate product stream as feed stream.
hyProdStrm.ComponentMolarFraction.Calculate
hyFeedStrm.ComponentMolarFractionValue
hyProdStrm.MolarFlow.Calculate
hyFeedStrm.MolarFlowValue
Else If feed stream molar flow is not 0, then
Set Streams(0) = hyFeedStrm perform a mole balance.
Set Streams(1) = hyWatStrm
Set Streams(2) = hyProdStrm
hyContainer.Balance btMoleBalance, 2,
Streams
End If
hyContainer.SolveComplete This line prevents a second Calculation
pass, because it is not required. See the
comment associated with the If Not
Forgetting Then line of code at the
beginning of the code. Read the section
on the SolveComplete method in
Extending UniSim Design Help file for
more information.
CalcError(0) = False Reset error flags.
CalcError(1) = False
End If
ErrorTrap: Line to which the On Error statement
branches if an error occurs.
End Sub Signifies the end of the sub-routine. This
line does not need to be added.

3-58
 Extensibility 3-59

9. While the Initialize and Execute methods are required for the
implementation of the unit operation extension, it is strongly
recommended you also include a Status Query method that
accurately assesses how the extension is performing.

Code Explanation
Public Sub StatusQuery(hyStatus As ObjectStatus) The StatusQuery sub-routine of the
extension is used to display appropriate
messages on the extension view (EDF
file) in UniSim Design. This sub-routine is
called whenever some change is made to
the extension, whether it is a result of a
solver pass or user interaction.
Dim OK As Boolean Declare and initialize the OK flag.
OK = True
If WaterPresent = False Then If there is no water present in the fluid
Call package, an error message appears
telling you water is required.
hyStatus.AddStatusCondition(slMissingRequire
dInformation, 1, "Water is Required as a
Component")
OK = False
End If
If hyFeedStrm Is Nothing Then If there is no feed stream attached to the
Call unit op, an error message appears telling
you that a feed stream is required.
hyStatus.AddStatusCondition(slMissingRequire
dInformation, 2, "Feed Stream Required")
OK = False
End If
If hyWatStrm Is Nothing Then If there is no water stream attached to
Call the unit op, an error message appears
telling you that a water stream is
hyStatus.AddStatusCondition(slMissingRequire required.
dInformation, 4, "Water Stream Required")
OK = False
End If
If hyProdStrm Is Nothing Then If there is no product stream attached to
Call the unit op, an error message appears
telling you that a product stream is
hyStatus.AddStatusCondition(slMissingRequire required.
dInformation, 3, "Product Stream Required")
OK = False
End If
If myOp.IsIgnored = True Then If the Ignored checkbox is checked then
Call send an Ignored message to the status
bar.
hyStatus.AddStatusCondition(slWarning, 11,
"Ignored")
OK = False
End If

3-59
3-60 Extension Unit Operations

Code Explanation
If OK = False Then Exit Sub These next message can wait until the
connections are made so skip them.
If Not hyFeedStrm.Temperature.IsKnown Then If the feed stream temperature is not
Call known, then send an Unknown Feed
Temperature message to the status bar.
hyStatus.AddStatusCondition(slMissingOptiona
lInformation, 5, "Unknown Feed Temperature")
OK = False
End If
If Not hyFeedStrm.Pressure.IsKnown Then If the feed stream pressure is not known,
Call then send an Unknown Feed Pressure
message to the status bar.
hyStatus.AddStatusCondition(slMissingOptiona
lInformation, 6, "Unknown Feed Pressure")
OK = False
End If
If Not hyFeedStrm.MolarFlow.IsKnown Then If the feed stream molar flow rate is not
Call known, then send an Unknown Feed Flow
message to the status bar.
hyStatus.AddStatusCondition(slMissingOptiona
lInformation, 7, "Unknown Feed Flow")
OK = False
End If
IsKnownFeedArray = Check to see if the feed stream’s
hyFeedStrm.ComponentMolarFraction.IsKnown composition has been set. If it has not,
an error message is sent to the status bar
If Not IsKnownFeedArray(0) Then indicating an Unknown Feed Composition.
Call
hyStatus.AddStatusCondition(slMissingOptiona
lInformation, 8, "Unknown Feed Composition")
OK = False
End If
If CalcError(0) Then If the first error flag has been tripped, it
Call hyStatus.AddStatusCondition(slError, sends a message to the status bar
indicating that the Feed Cannot be
9, "Feed Cannot be Saturated with Water") Saturated with Water.
OK = False
End If
If CalcError(1) Then If the second error flag has been tripped,
Call hyStatus.AddStatusCondition(slError, it sends a message to the status bar
indicating that Water is Required in the
10, "Water is required in Water Stream") Water Stream.
OK = False
End If
End Sub Signifies the end of the sub-routine. This
line does not need to be added.

10. Select Make Saturate.dll command from the File menu.

3-60
 Extensibility 3-61

Creating the Extension Definition File (EDF)

In order to complete the Unit Operation Extension, you must
create an EDF. This is done through the UniSim Design
Extension View Editor.

If it has been installed, the Extension View Editor is found in

the same launch point in the Start menu as UniSim Design.
For more information on installing and accessing the View
Editor, see Section 4.1.1 - Accessing the View Editor.

1. Open the Extension View Editor. Open a new EDF by doing

one of the following:
• Select New command under File menu in the menu bar
• Use the hot key combination CTRL N
• Click the New File icon

The default View Editor should appear as shown below:

New File icon
Figure 3.25

The file path in

the View File
group may be
different,
depending on
where you
installed UniSim
Design.

2. Click the Objects Manager icon to view the Objects

Manager view.
Objects Manager icon 3. In the ProgID/CLSID cell enter UnitOpExtn.Saturate as the
extension ID.
4. Enter an appropriate description for the extension in the
Description cell, such as Saturate Extension.

3-61
3-62 Extension Unit Operations

5. Select Unit Operation as the extension type in the Type

drop-down list.
6. In the Variables of Selected Object group declare the
following variables:

Attachment Flow N
Tag Description Type Persistent
Type Direction Dimensions
FeedStream FeedStrm Attachment Active Material Feed None
Stream
ProductStream ProductStrm Attachment Active Material Product None
Stream
WaterStream WaterStrm Attachment Active Material Feed None
Stream

The Object Manager view now appears similar to the figure

below.

Figure 3.26

3-62
 Extensibility 3-63

7. Click the Close button. This returns you to the Views

Manager view.

Figure 3.27

8. From the Existing Views list, select DefaultView and click

the Edit button. The DefaultView form appears.

Figure 3.28

3-63
3-64 Extension Unit Operations

Defining the Tabs

1. To open the properties view for the Page Tabs widget (or
for any widget), do one of the following:
• Double-click on the widget
• Right-click the widget and select <Widget Type>
Properties command from the Object Inspect menu,
where Widget Type would be Button for a Button widget.
2. The Page Tabs properties view appears. Click the Ellipsis
icon associated with the Target Moniker field.
Ellipsis icon 3. The Select Number Variable view appears. From the list
select Current Page and click the OK button.

Figure 3.29

3-64
 Extensibility 3-65

4. In the Label field of the Static Tabs group change the two
entries Page1 and Page2 to Connections and
Worksheet, respectively.

Figure 3.30

5. Close the Page Tabs properties view by clicking the OK

button.
6. Now controls must be added to the tabs. Open the Visibility
Manager view by right-clicking the DefaultView form
background and selecting Open Visibility Manager
command from the Object Inspect menu.
7. A default controller has already been set up for the page
tabs called PageController. Click the Edit button to view
the Visibility Controller Properties view.

3-65
3-66 Extension Unit Operations

8. In the States matrix, you should notice two entries: Page1

and Page2. Rename these two states Connections and
Worksheet, respectively, to coordinate the states to
respective tab names.

Figure 3.31

The names of the two 9. Click the OK button to return to the Visibility Manager view.
radio buttons that
appear in the
PageController group
have changed to the Adding Widgets to Connections Tab
names of the two page
tabs.
You are now ready to add widgets to the Connections tab on the
DefaultView form.
1. From the Widgets Palette select the Attachment Name
widget. Right-click, hold, and drag the widget on to the
DefaultView form. Move the widget to the left side of the
view.
2. Add two more Attachment Name widgets to the view using
the drag and drop method described in the step above.
Stagger the two widgets in the upper and lower corners of
the right side as shown in Figure 3.32.

3-66
 Extensibility 3-67

3. Place a Static Text widget above each Attachment Name

widget.

Figure 3.32

4. First the Feed widgets (i.e., the Attachment Name and Static
Text widget on the left) is defined. For the Feed Static Text
widget specify properties as shown below. When you are
finished click the OK button.

Figure 3.33

3-67
3-68 Extension Unit Operations

5. For the Feed Attachment Name widget specify properties

as shown below. When you are finished click the OK button.

Figure 3.34

The Target Moniker field

is specified by clicking
the Ellipsis icon
associated with the field
and selecting FeedStrm
from the Select
Attachment view.

Ellipsis icon

6. For the Water Stream (i.e., upper right) Static Text widget
specify properties as shown below. When you are finished
click the OK button.

Figure 3.35

3-68
 Extensibility 3-69

7. For the Water Attachment Name widget specify properties

as shown below. When you are finished click the OK button.

Figure 3.36

The Target Moniker field

is specified by clicking
the Ellipsis icon
associated with the field
and selecting
WaterStrm from the
Select Attachment view.

Ellipsis icon

8. For the Product Stream (i.e., lower right) Static Text widget
specify properties as shown below. When you are finished
click the OK button.

Figure 3.37

3-69
3-70 Extension Unit Operations

9. For the Product Attachment Name widget specify

properties as shown below. When you are finished click the
OK button.

Figure 3.38
The Target Moniker field
is specified by clicking
the Ellipsis icon
associated with the field
and selecting
ProductStrm from the
Select Attachment view.

Ellipsis icon

The DefaultView form now appears as shown in the figure

below.

Figure 3.39

3-70
 Extensibility 3-71

Adding Widgets to Worksheet Tab

The next step is to add widgets to the Worksheet tab on the
DefaultView form.
Open the Visibility 1. In the Visibility Manager view, select the Worksheet radio
Manager view by right-
clicking the DefaultView
button.
form background and 2. Insert a Matrix widget on the Worksheet tab. Resize the
selecting Open
widget so that about 1 cm space appears between the
Visibility Manager
command from the matrix and tab borders.
Object Inspect menu.
Figure 3.40

3. Open the Matrix Properties view. In the Fly By field enter

Properties of connected streams.
4. In the Cells group change the value in the Width field to 46
and the value in the Wrap field to 2.
5. In the Labels group set the Labels drop-down list to Row,
the Show Units drop-down list to Row, and the Left Width
field to 74.

3-71
3-72 Extension Unit Operations

6. Check the Vertical Direction checkbox. The Matrix

Properties view should appear similar to the figure below.

Figure 3.41

7. The Data Set list should contain a default data set. Click the
Insert button to open the Select a Data Type view and add a
new data set to the list.
8. On the Select a Data Type view, select Text as the data type
and click the OK button.

Figure 3.42

9. A Text Data Set Properties view appears. Change the name

of the data set to WRKName.
10. Click the Ellipsis icon associated with the Moniker field to
open the Select Text Variable view.
Ellipsis icon 11. On the Select Text Variable view, select WaterStrm from
the Base Object drop-down list.

3-72
 Extensibility 3-73

12. From the list select Object Name as shown in the figure
below and click the OK button.

Figure 3.43

13. The Select Text Variable view closes, and you are returned to
the Text Data Set Properties view.
14. In the Label group enter Name as the label associated with
field and click the OK button to close the Data Set Properties
view.

Figure 3.44

15. Insert a Numeric data set as described in the above steps

#7 and #8.
16. A Numeric Data Set Properties view appears. Change the
name of the data set to WRKFlow.
17. Click the Ellipsis icon associated with the Moniker field to
open the Select Number Variable view.
Ellipsis icon 18. On the Select Number Variable view, select WaterStrm
from the Base Object drop-down list.

3-73
3-74 Extension Unit Operations

19. From the list select Molar Flow and click the OK button.
The Select Number Variable view closes, and you are
returned to the Numeric Data Set Properties view.
20. In the Label group enter Molar Flow as the label associated
with field and click the OK button to close the Numeric Data
Set Properties view.

Figure 3.45

Other data sets can be 21. Click the OK button on the Matrix Properties view to close
added for other streams
and other stream
the view. The DefaultView form appears similar to the figure
properties, however for shown below.
the sake of brevity,
these are the only two
Figure 3.46
cells defined.

22. Select Save command from the File menu and save the EDF
as Saturate.edf in the same directory as the DLL file.

3-74
 Extensibility 3-75

Attaching the Extension to UniSim Design

You are now ready to attach the extension to UniSim Design.
The following steps demonstrates how to attach an extension
within UniSim Design.
1. Start UniSim Design. From the Tools menu, select
Preferences command. The Session Preferences view
appears.
2. Go to the Extensions tab and click the Register an
Extension button. The Select an Extension to be Registered
view appears.
3. Use the File Path group to find the directory in which the
Saturate.dll file is saved in. Once you find the DLL, select it
and click the OK button.
The Extensions tab now appears similar to the figure below.

Figure 3.47

3-75
3-76 References

4. You can now go in to the main Simulation environment and

from the UnitOps view find the Saturate Extension in the
Available Unit Operations list.

Figure 3.48

3.11 References
1 "An Industrial Design/Control Study for the Vinyl Acetate Monomer
Process", Luyben & Tyreus, p.4.

3-76
 Extension View Editor 4-1

4 Extension View Editor

4.1 Introduction................................................................................... 3
4.1.1 Accessing the View Editor.......................................................... 4
4.1.2 Creating a New EDF File ............................................................ 5
4.1.3 Editing an Existing EDF File........................................................ 8

4.2 Using the View Editor..................................................................... 8

4.2.1 Manipulating Widgets................................................................ 8
4.2.2 DefaultView Form Toolbar........................................................ 11
4.2.3 Visibility Manager ................................................................... 16
4.2.4 The Objects Manager View....................................................... 23
4.2.5 Views Manager ...................................................................... 27

4.3 Widget Properties ........................................................................ 28

4.3.1 Common Widget Properties ..................................................... 32
4.3.2 DefaultView Form Object ......................................................... 34
4.3.3 Button Widget ....................................................................... 39
4.3.4 Static Text Widget .................................................................. 40
4.3.5 Text Entry Widget................................................................... 42
4.3.6 Rich Text Entry Widget............................................................ 44
4.3.7 Format Entry Widget............................................................... 45
4.3.8 Numerical Input Widget .......................................................... 46
4.3.9 Matrix Widget ........................................................................ 48
4.3.10 Check Box Widget ................................................................ 57
4.3.11 Radio Buttons Widget............................................................ 58
4.3.12 Graphic Button Widget .......................................................... 60
4.3.13 Group Widget....................................................................... 63
4.3.14 Page Tabs Widget ................................................................. 64
4.3.15 Ply Picker Widget.................................................................. 66
4.3.16 Attachment Name Widget ...................................................... 68
4.3.17 Enumeration Widget ............................................................. 70

4-1
4-2 Extension View Editor

4.3.18 Unit Enumeration Widget........................................................71

4.3.19 Text List Widget ....................................................................73
4.3.20 Enumeration List Widget ........................................................75
4.3.21 Attachment List Widget ..........................................................78
4.3.22 Level Widget.........................................................................81
4.3.23 Plot Widget...........................................................................84
4.3.24 Worksheet Matrix Widget........................................................85
4.3.25 ACTIVEX Container Widget .....................................................88

4-2
 Extension View Editor 4-3

4.1 Introduction
The View Editor can be used to create or modify Extension
Definition Files (*.edf). Users that are accessing the automation
and extension capabilities of UniSim Design generally make use
of EDF files. The extension definition file acts as the interface
view within UniSim Design as well as the point for variable
declaration and storage.

Figure 4.1

4-3
4-4 Introduction

4.1.1 Accessing the View

Editor
The Extension Access to the View Editor is provided with each commercial
Development SDK files
release of UniSim Design. However, it is not available unless you
option is not activated
by default as it requires have selected the Extension SDK option during the UniSim
additional hard drive Design installation.
space.

Figure 4.2

During the installation procedure, UniSim Design adds the

viewed.exe application to the directory that currently holds
your UniSim Design files. You can access the View Editor by
either:
• Selecting the View Editor option in the Start menu
where it should reside in the same launch group as
UniSim Design.
• Finding the directory name used to store your UniSim
Design files and double-clicking on viewed.exe in File
Manager or Windows Explorer.

4-4
 Extension View Editor 4-5

The View Editor appears as shown below:

Figure 4.3

You can now either open an existing EDF or create a new EDF.

4.1.2 Creating a New EDF File

Once the View Editor has been accessed, you can create a EDF
by following this simple procedure:
1. Do one of the following:
• Select New command under File menu in the menu bar
• Use the hot key combination CTRL N
• Click the New File icon

New File icon

4-5
4-6 Introduction

The Views Manager view and the Widgets Palette appears as

shown in the figure below.

Figure 4.4

4-6
 Extension View Editor 4-7

2. Assuming, at this time, that only one view exists for this EDF
file, click the Edit button to open the DefaultView form.

Figure 4.5

The DefaultView form contains three widgets: Text Entry

widget, Static Text widget, and Page Tabs widget.
3. Delete these widgets if you do not require them. To delete a
widget, simply click on the widget and do either of the
following:
• Right-click the widget and select the Delete command
from the Object Inspect menu.
• Press the DELETE key.
4. Place the widgets you want on the DefaultView form and, if
needed, modify the widget properties.
5. Move and resize the widgets if required.
6. Save your work by clicking the Save View File icon and
providing an appropriate name for the EDF file.

Save View File icon

4-7
4-8 Using the View Editor

4.1.3 Editing an Existing EDF

File
To edit an existing file, its ‘write’ attribute must be enabled
(it cannot be read-only).

1. To open an existing EDF file, do one of the following:

• Select Open under File in the menu bar.
• Use the hot key combination CTRL O.
• Click the Open View File icon.
2. Select the EDF file from the Open View File view and click
the Open button.
Open File icon
3. Edit the EDF file and save the file before exiting the program.

4.2 Using the View Editor

4.2.1 Manipulating Widgets
Adding Widgets
You can add a widget to your view by using the following
procedure:
1. Select the widget you want to add in the Widgets Palette.
2. Right-click, hold, and drag the widget to the location on the
view where you want to place it.
Drag Cursor 3. When the widget can be properly placed on the view, the
cursor changes to a Bull’s Eye. Release the mouse button
and the widget appears on the view.

The default sized widget appears on the DefaultView form where

Bull’s Eye Cursor you released the mouse button. Re-sizing handles are shown
around the border of the widget, when the widget is selected.

4-8
 Extension View Editor 4-9

Alternate Approach
An alternate approach to the above steps #2 through #3 is to
check the Lock checkbox found at the bottom of the Widgets
Palette. Once checked, the mouse cursor changes in to a cross-
hair cursor whenever the mouse cursor is placed over the
DefaultView form. You can then use the cross-hair cursor to
draw the currently selected widget in the Widget Palette by
clicking and dragging the cursor in the DefaultView form.

With the Lock checkbox checked, you can add multiple widgets
of the same type simply by clicking on the DefaultView form
multiple times.

Figure 4.6

4-9
4-10 Using the View Editor

Deleting a Widget
To delete a widget simply select the widget and do one of the
following:
• Press the DELETE key.
• Right-click the widget and from the resulting Object
Inspect menu, select the Delete <Widget Type>
command.

Re-sizing a Widget
To re-size the widget using the mouse:
1. Select the widget.
Notice the cursor
2. Place the cursor over one of the re-sizing handles.
changes to a double-
headed arrow. 3. Hold down the primary mouse button and drag in one of the
directions indicated by the double-headed arrow.

Figure 4.7

You can also select multiple widgets by dragging a frame around

the widgets of choice or by selecting individual widgets while
holding down the CTRL key. You can then simultaneously resize
all selected widgets by resizing the anchor widget, which is the
widget displayed with the resizing handles.

4-10
 Extension View Editor 4-11

To re-size the widget using the Properties view:

1. Open the widget’s Properties view.
2. On the widget’s Properties view, enter the new width and
height of the widget in the XY table shown in the figure
below.

Figure 4.8

You can also move the widget by

entering new coordinate values in the
Position row.

Moving a Widget
You can also select To move a widget:
multiple widgets by
dragging a frame 1. Select a widget.
around the widgets of
2. Hold down the primary mouse button and drag the widget to
choice or by selecting
individual widgets while a new location.
holding down the CTRL

4.2.2 DefaultView Form

key.

Toolbar
When you are creating a new view or editing an existing view,
there is a toolbar containing buttons on the DefaultView form.
These buttons can be used to access some of the widget
properties without opening the particular widget property view.

Active Location Settings

Tab Order Icon
When this icon is clicked, an integer value appears over each
widget on the DefaultView form that can capture the focus. The
Tab Order icon sequence of the integer values determines the order in which
the widgets attain the focus when the TAB key is pressed.

4-11
4-12 Using the View Editor

As widgets are placed on the DefaultView form, the View Editor

assigns the next available integer value to the new widget. It is
possible for you to change the tab order that is assigned to the
widgets.

A UniSim Design valve property view is shown in the figure

below and it is used to demonstrate the re-arranging of the tab
order.

Figure 4.9

The tab order is indicated by the integer values in the black dots
covering the widgets. From the Name field (#6), pressing TAB
moves the focus to the Ignored checkbox (#7), then to the
Delete button (#8) and so on.

Notice that static text widgets such as Name, Inlet and Outlet
also receive tab order values. These values should always be
one below the value on the widget with which the static text is
associated. This enables the associated widget to get the focus
when the static text hot key is pressed. For example, when the
user presses ALT N, the focus should be in the text entry cell
where the name can be input. Since the static text Name widget
(#5) cannot accept the focus, the next integer value is used
(#6).

There are two approaches to changing the tab order. You can
click either the Select #1 or the Select Sequentially button. The

4-12
 Extension View Editor 4-13

following sections describe each buttons in detail.

Select #1 Button
When you click this button, the View Editor allows you to select
a different widget to carry the value #1 in the tab order. When a
new #1 is selected, the tab order remains the same, but the
integer values are rotated to accommodate the new #1
selection.

For example, if you clicked the Select #1 button for the valve
view shown previously, and then selected the Text Entry Outlet
widget (current #3), this widget would become #1. All other
widgets would have their integer values increase by 1 with the
old #1, the Static Text Inlet widget, becoming #8 (as shown in
the figure below).

Figure 4.10

If this new order was not what you wanted, you could continue
with a user selected order. Notice the Select Sequentially button
has changed to a selected Select #2 button. So you can select
the widget that you would like to be #2 in the tab order. After
you select a widget to by #2, the Select #2 button changes to
Select #3 button. So you can choose the #3 widget in the tab
order. The sequence number button increase with each selection
until the highest number has been designated to a widget.

4-13
4-14 Using the View Editor

When the highest number (like number 9 from the figure above)
has been designated, the sequence number goes back to #1
and you can resequence the view again. You can keep
resequencing the tab order until the Tab Order icon is clicked
again or the view is closed.

Select Sequentially Button

When you click the Select Sequentially button, the View Editor
allows you to select a current widget tab order value which
begins the sequence of values for changes. For instance, if you
clicked this button and then clicked the #4 widget, the Select
Sequentially button would change in to a Select #5 button. Once
you selected the widget that you would like to be #5 in the tab
order, the button would change to a Select #6 button. This
continues until the Tab Order icon is clicked again or the view is
closed.

Sizing Icons
Stretch Width
Clicking the Stretch Width icon toggles the X-direction Stretch
checkbox (found in the widget’s Properties view) for the selected
Stretch Width icon widget. When the Stretch checkbox is checked, the width of the
widget increases as the DefaultView form is expanded
horizontally. Stretching is related to the Tie To Corner and the
Tie Reference properties.

Stretch Height
Clicking the Stretch Height icon toggles the Y-direction Stretch
checkbox (found in the widget’s Properties view) for the selected
Stretch Height icon widget. This icon is disabled for those widgets that are not
designed to stretch vertically (vertically-challenged widgets).

4-14
 Extension View Editor 4-15

When the Stretch checkbox is checked, the height of the widget

increases as the DefaultView form is expanded vertically.
Stretching is related to the Tie To Corner and the Tie Reference
properties.

Alignment Icons
These icons are disabled unless you select multiple widgets on a
DefaultView form. The icons that become available depends on
the orientation of the widgets that you have selected.

For instance, if you select two static text widgets, one being
below the other, the icons that become available allow you to
choose a left, centre or right alignment according to the widget
that is chosen as the anchor widget.

Figure 4.11

In the view shown on the left, Object B is the anchor widget.

When the Align to Top icon is clicked, Object A is aligned to the
top of Object B resulting in the view on the right. If you wanted
to align Object B to A you would select Object A again and
Object A would become the anchor widget.

The anchor widget is the widget that serves as the basis for
alignment and is identified by the resizing handles around its
outline. The other widgets in the group selection become the
widgets that are moved. To change the anchor widget, simply
select another of the selected widgets. This changes the
selected widget’s outline from the solid black line to a thinner
outline with resizing handles.

4-15
4-16 Using the View Editor

The Alignment icons that are available:

Name Description Icon

Align to Left Lines up the selected widgets according to the
leftmost point of the anchor widget.

Align to Lines up the selected widgets according to the

Right rightmost point of the anchor widget.

Align to Top Lines up the selected widgets according to the

topmost point of the anchor widget.

Align to Lines up the selected widgets according to the

Bottom bottommost point of the anchor widget.

Align at There are two of these icons, although only one is

Centre shown at any given time. The one that appears
depend on the orientation of the selected widgets.
Clicking the icon lines up the selected widgets
according to the centre point of the anchor widget,
either in a vertical (X-axis centre point) or
horizontal (Y-axis centre point) fashion, depending
on the icon being shown.
Equally There are two of these icons, although only one is
Space shown at any given time. The one that appears
depend on the orientation of the selected widgets.
For this icon to become available, at least three
widgets must be selected. Clicking the icon
vertically or horizontally spaces the widgets,
depending on the icon being shown.

4.2.3 Visibility Manager

The Visibility Manager is used when you want to show or hide
certain parts of your view at specific times. In other words, it
allows you to discretely select what is to be shown based on the
conditions of the view (i.e., static - done by the view designer)
or the state of the application (i.e., dynamic - manipulated
through code).

4-16
 Extension View Editor 4-17

For instance, many UniSim Design views have tabs along the
lower part of the view which enable different information to be
grouped and shown at different times. When the second tab on
a view is selected, the information from the first tab is typically
hidden and the information specific to the second tab is shown.

Figure 4.12

Although the Visibility Manager is used mainly with tabs, it can

be used with other widgets. Other selection devices, such as
radio buttons and checkboxes can prompt the use of this tool to
selectively show and hide information.

The Visibility Manager can be accessed by right-clicking

anywhere on the DefaultView form and selecting the Open
Visibility Manager command from the Object Inspect menu.

The Visibility Manager largely consists of the Create Controller

button and the controls you have created. A control is denoted
by the presence of a group containing an Edit and Delete button.
Each control allows you to create States, or instances when
widgets or events occur. The default view of the Visibility
Manager, shown in the figure below, consists of a default
PageController control which controls the visibility of the two
tabs.

Figure 4.13

4-17
4-18 Using the View Editor

An example, if you were to select the Page2 radio button, you

would see the Page 2 tab. Only the widgets placed on this tab
would automatically set to be visible on the tab in the
DefaultView form.

Clicking the Create Controller button adds a new controller

group to the Visibility Manager view. The name of the control is
the name shared by the group. You can delete a controller by
clicking the Delete button associated with the controller group.
You can also edit the controller by clicking the Edit button.

Visibility Manager view Clicking the Edit button opens the Visibility Controller Properties
view.

Figure 4.14

The Visibility Controller Properties view is where individual

object states are set. The view consists of 10 objects:

Object Description
Name The controller name. The name entered in to this field is
the name of that appears in the Visibility Manager.
Moniker Clicking the Ellipsis icon associated with this field, opens
the Select Number Variable view. You can select the
moniker type you want to associate to the controller using
Ellipsis icon the Select Number Variable view. See Moniker
Specification sub-section from Section 4.3 - Widget
Properties for more information.

4-18
 Extension View Editor 4-19

Object Description
States This group has three different fields that require
specification:
• Name. The name of the state. This appears as a radio
button in the controller group on the Visibility Manager
view.
• Low. The low value for the state.
• High. The high value for the state.
Insert State Click this button to add a new state to the list.
Delete State Select a state and click this button to delete the currently
selected state.
Apply Click this button to apply any changes made on the
Properties view to the Visibility Manager view.
Select Click this button to open the Visibility Controller Widget
Widgets Selections view which allows you to associate widgets with
the state.
Activation Click this button to open the Visibility Controller Activation
view which allows you to create a hierarchy of visibility
states.

Using Tabs
A view created through the View Editor can contain multiple
tabbed sections within the same view. Double-clicking on the
tabs of a view opens the tab Properties view. Labels are added
for each new tab to be displayed.
1. To add a tab to a view, right-click, hold, and drag the Page
Tab widget from the Widget Palette into the DefaultView
form.
2. Resize the tab size to your specifications.

Figure 4.15

4-19
4-20 Using the View Editor

3. Right-click the DefaultView form background and select

Open Visibility Manager command from the Object
Inspect menu.
4. The Visibility Manager view appears. Click the Create
Controller button.
5. A VisController group appears above the Page Controller
group as shown in the figure below.
Page Tabs Object Inspect
menu
Figure 4.16

6. Click the Edit button in the VisController group, to open the

Visibility Controller Properties view.

Figure 4.17

7. Click the Ellipsis icon associated with Moniker field to open

the Select Number Variable view.
Ellipsis icon

4-20
 Extension View Editor 4-21

8. Select Current Page from the list in the Select Number

Variable view, and click the OK button.

Figure 4.18

9. Enter a name for the first tab in the Name column of the
States group.
10. Enter an integer value in the Low and High cells beside the
Name cell from the above step. The integer value for both
Low and High cells have to be the same.
If the values entered for the Low and High cells is not for the
first tab, increment the values by one for each tabbed sheet
(i.e., High and Low for first tab is 0, High and Low for second
tab is 1).

Figure 4.19

4-21
4-22 Using the View Editor

It is required that the High/Low values provided (in #10) for

each tab match the Value for each tab in the Static Tabs
group of the tab Properties view. It is highly recommended
that you match the tab Name (#9) in the Visibility Controller
Properties view with the Label in the tab Properties view.

11. Repeat #9 and #10 for each tab.

12. Click the Select Widgets button. Check the checkbox under
the appropriate tab name for each widget that appears only
on that tab. For widgets that appears on all tabs, do not
check any checkboxes.

Figure 4.20

High and Low Integer Values

The values for High and Low in the Visibility Controller
Properties view do not always have to be the same. You can use
the Visibility Manager to selectively show widgets according to
values in the application. For example, if you want to show a
static text widget when the pressure of a specific stream was
between 150 and 200 kPa, you could specify the moniker
representing the stream pressure in the Moniker field of the
Visibility Controller Properties view and then use the Low and
High cells to specify the pressure range.

4-22
 Extension View Editor 4-23

4.2.4 The Objects Manager

View
The Objects Manager provides a view in which you can enter
crucial information related to extensions. This information is
used to register an extension properly and to declare the
variables and objects used by the extension.

You can access the Objects Manager view by either:

• Clicking the Objects Manager icon on the Views
Manager view.
Objects Manager icon • Selecting Objects Manager under View in the menu
bar.

Figure 4.21

The Object Manager

view consists of:
• the Object
Definition matrix
• the Attributes of
Selected Object
group
• the Variables of
Selected Object
group

4-23
4-24 Using the View Editor

Object Definition Matrix

The Object Definition matrix consists of four columns:

Column Description
ProgID/ The entry in this cell identifies the name of the object that
CLSID owns the views shown in the Existing Views group of the
Views Manager view. This information must match what is
in the registry and is used by UniSim Design to access the
proper DLL file.
Description This is the text that appears in the appropriate location
within UniSim Design in order to select the extension.
Type This specifies the type of extension. The choices include:
• Unit Operation
• Property Package
• Kinetic Reaction
• Exchanger Design, Base
• Exchanger Design, End Point
• Exchanger Design, Simple
• Exchanger Design, Weighted
• DeltaP (Pressure Drop) Correlation
• Sim Case Translator
• ExternalAddIn
• Pipe Deposition Correlation
• Property Balance
• Mixing Rule
This selection impacts the list of internal Honeywell
variables that are visible when the Ellipsis icon is clicked on
a widget Properties view.
Ellipsis icon Views The number of views associated with this extension.

Attributes of Selected Object Group

The Attributes of Selected Object group allows you to transfer
the attributes of operation types to your unit operation
extension. This allows you to find your extension unit operation
not only under the Extension categories but also under the
category of the operation whose attributes you have selected.
For instance if you add the attributes of the Reactor to your
extension, when you want to find your extension in the UnitOp
view, you are able to find it by selecting either the Reactors or
Extensions radio buttons.

4-24
 Extension View Editor 4-25

Variables of Selected Object Group

In the Variables of Selected Object group, you can specify all
variable-related information for the selected object in the
ProgID/CLSID cell. Once these variables are created, you can
use them as monikers to associate a particular variable with a
widget on your view. Variables are defined in the table that
contains three columns:

Column Description
Tag Represents the internal name of the variable that is stored to
disk (usually input as the same as Name). You cannot have 2
identical tags for the same object.
Name Represents the variable name which is visible on views in the
program (usually the same as Tag). This name should be
unique such that you can identify it in the program. Unlike the
Tag, spaces are allowed in this text string.
Type Variable types include:
• Real Number. Numeric variable for which you can
specify the dimensions and unit type.
• Enumeration. A related set of identifiers, each of which
is associated with an integer value; you can specify the
dimensions and create the enumeration through the
Enumeration Values button.
• Text. A string variable for which you can specify the
dimensions.
• Attachment. Represents a variable associated with an
object that is attached to another object (i.e., a feed
stream is attached to the inlet of a pump, so the feed
stream name is of type Attachment); allows you to
specify the dimensions, attachment type and flow
direction.
• Message. A variable holding information passed when a
button is clicked.

The group also consists of several additional objects that,

depending on the type of the currently selected variable in the
matrix:

Object Description
Persistent Check this checkbox if you want this variable value to be
saved with the simulation case. Pertains to all variables
except Message variables.
Triggers Check this checkbox if you want changes in the variable to
Solve set off a smart solve (solve whatever needs to be solved).
The checkbox is enabled for all variables ONLY when the
object in question is a Unit Operation. For Real Number and
Enumeration types, this checkbox is checked by default.

4-25
4-26 Using the View Editor

Object Description
Attachment For Attachment variables, you can specify the attachment
Type type as one of the following:
• Stream. Generic specification, implying that the
stream can be either material or energy.
• Material Stream. The attachment is a material
stream and cannot be an energy stream.
• Energy Stream. The attachment is an energy stream
and cannot be a material stream.
Flow The choice for Flow Direction impacts the PFD in its
Direction presentation of nozzles for unit operations in Attach Mode.
For Attachment variables, you can specify the flow direction
as one of the following:
• Unknown. The PFD does not know until run-time if
the attachment is a feed or product; depends if the
attachment is already attached to something.
• Feed. Only feed nozzles are presented by the PFD.
• Product. Only product nozzles are presented by the
PFD.
Numeric For variables of type Real Number, a unit type can be
Type specified. This guarantees that the appropriate value
appears by the view according to the user specified unit
set.
N For all variable types except Message, the variable
Dimensions dimensions can be specified as one of the following:
• None. Single value.
• Vector. One dimensional array.
• Matrix. Two dimensional array.
• Cube. Three dimensional array.
Only the Real Number variable type has access to all
dimension types. The other variable types have access to
only None and Vector.
Enumeration When you click the Enumeration Values button, the
Values Enumeration Values view appears (as shown in Figure
Button 4.22), on which you can create your enumeration. Simply
enter the labels and the integer values with which the
labels are associated.

Figure 4.22

4-26
 Extension View Editor 4-27

4.2.5 Views Manager

The View Manager view consists of two groups: View File and
Selected Object.

Figure 4.23

The View File group

contains the path and
name of the current
*.edf file.

When the Views Manager

view is opened for a new
view file, UniSim Design
automatically creates a
view named DefaultView
in Existing Views list.

Each *.edf file can have an unlimited number of objects

associated with it, each of which can have an unlimited
number of views.

Selected Objects Group

The Selected Object group consists of a drop-down list with an
associated Objects Manager icon and the Existing Views list. The
Objects Manager icon drop-down list allows you to select one of the objects defined in
the Objects Manager view. The Objects Manager icon opens the
Objects Manager view.

The Existing Views list displays all of the existing views

associated with the selected object.

4-27
4-28 Widget Properties

From the Views Manager view, you can click any of the buttons
that pertain to the Existing Views list:

Button Description
Edit Opens the selected view and the Widget Palette.
Test Allows you to test the view.
Add Adds a new view to the object.
Copy Creates a copy of the selected view.
Remove Removes the selected view from the object.

4.3 Widget Properties

As mentioned earlier in this guide, a view is the interface seen
within the UniSim Design environment. Views can contain
several tabs and pages of information. The controls placed on
the view are referred to within the View Editor as widgets. These
include many of the typical control features associated with
windows programs such as text fields/cells, checkboxes, drop-
down lists, buttons, etc.

The Properties view of a specific widget can be accessed by

either:
• Double-clicking on the widget
• Right-clicking the widget and selecting <Widget Type>
Properties command from the Object Inspect menu,
where Widget Type would be the Button for a button
widget.

The properties of the DefaultView form itself can also be

accessed in either of the aforementioned ways.

When dealing with the properties of a widget and where

applicable, you can access options for the cell/field by clicking
Ellipsis icon the Ellipsis icon. A view is presented from which you can make a
selection that is appropriate for the widget property.

For extensions, the most important feature involves associating

the widget item to a particular variable declared in the Objects
Manager view. This is accomplished through the Moniker, which
is another name for a variable. For most widgets the Target
Moniker option is used to assign a specific variable to the
widget.

4-28
 Extension View Editor 4-29

Common widget properties are discussed in the next section,

followed by widget specific properties. In the section describing
the specific widget properties, an example of each widget (as
well as its respective Properties view) is shown.

Moniker Specification
Moniker (or variable) specification is usually done via the Ellipsis
icon that is usually associated with the moniker field. There are
Ellipsis icon usually three types of monikers specified:

Variable Type Description

Number Numerical variables are selected via the Select Number
Variables Variable view which appears when the Ellipsis icon is
clicked. These variables:
• Represent numerical quantities and have a
Variable Type that allows UniSim Design to
manage Unit Conversions for the user.
• Can have zero, one, or two dimensions.
• Can trigger the steady state solver when they are
changed. If this is the case, the variable operates
like other UniSim Design variables in that the
solver performs consistency checking when
values are changed.
Text Variables Text variables are selected via the Select Text Variable
view which appears when the Ellipsis icon is clicked.
These variables:
• Represent string quantities.
• Can be zero- or one-dimensional.
Message Text variables are selected via the Edit Messages view
Variables which appears when the Ellipsis icon is clicked. These
variables do not represent any particular
quantification, but can be associated with buttons in a
view. Messages are sent through the VariableChanged
method of an extension.

4-29
4-30 Widget Properties

The Select Number Variable and Select Text Variable view are
very similar in their appearance and operation. Both consist of a
list that displays the available variables in the variables set (or
sub-set) selected in the Base Object drop-down list.

Figure 4.24

The Base Object drop-down list contains variable sets and sub-
sets. The drop-down list acts as a path to object and object sub-
sets. The default option is the <Form’s Base Object>.

Notice the angle brackets around the Form’s Base Object. This
indicates that the options appearing below it in the drop-down
list are all variable sub-sets. For example, the options that
appear below the Form’s Base Object option are all variable sub-
sets of the DefaultView form. If such a tributary option is
selected, the drop-down list hierarchy immediately changes.
While the selected option appears in the field, when the drop-
down list appear, the selected variable sub-set appears just
below the Form’s Base Object option surrounded by square
brackets. Drop-down list options that appear above the current
selection allow you to return to a higher level of the variable
hierarchy. The options that appear below are in turn sub-sets of
that selection. The display field that appears above the list
displays the variable set path.

4-30
 Extension View Editor 4-31

An example, suppose a stream variable was selected in the Base

Object drop-down list. As shown in the figure below, FeedStrm,
the material stream selected, appears in the display field.

Figure 4.25

The list above the Base Object drop-down list displays all
variables that belong to this sub-set. Selecting the drop-down
list shows that the list has changed. The <Form’s Base Object>
option is placed at the top of the list. If you wanted to return to
a higher level of the object hierarchy you would select this
option. Below it is the current selection in the field, FeedStrm, in
square brackets. The options that appear below the Feedstrm
option are all variable sub-sets of the material stream variable
set.

4-31
4-32 Widget Properties

4.3.1 Common Widget

Properties
Each of the widgets listed in the Widgets Palette has a set of
common properties listed on its respective Properties view. Even
though all widgets have access to these properties, not all of the
listed properties apply to all widgets. The common properties
are shown in the figure below and described in the table:

Figure 4.26

Object Description
Name Each widget is named automatically when it is placed on
the DefaultView form. You can replace the default name
with one that is more descriptive or meaningful.
Fly By Place text in this field to have a message appear in the
UniSim Design status bar and/or as a tool tip when the
cursor is placed over the widget. The ‘\n’ (newline
sequence) is used to differentiate status bar output and
tool tips. Multiple newlines allow for multi-line tool tips.
For example, with the Fly By input of “Performs an
action.\nThe sky is blue”, the message to the left of the
newline sequence, “Performs an action”, would appear in
the status bar and the message to the right of the newline
sequence, “The sky is blue” would appear as a tool tip. If
the newline sequence is not used, the whole message
appears in the status bar.
Position The X and Y values represent the co-ordinate values of the
top left corner of the widget with the reference point being
the top left corner of the DefaultView form. Co-ordinate
units are 1/8 of a character for the Y direction or height and
1/4 of a character for the X direction or width, where the
character in question is of the size seen on a button widget.
Size The X and Y values represent, respectively, the horizontal
and vertical size of the widget. Co-ordinate units are 1/8 of
a character for the Y direction or height and 1/4 of a
character for the X direction or width, where the character
in question is of the size seen on a button widget.

4-32
 Extension View Editor 4-33

Object Description
Stretch When the X-direction Stretch checkbox is checked, the
width of the widget increases as the DefaultView form is
expanded horizontally. When the Y-direction Stretch
checkbox is checked, the height of the widget increases as
the DefaultView form is expanded vertically.
Stretching is related to the Tie To Corner and the Tie
Reference properties.
Background Double-click the field to opens the Select A Colour view.
Colour The Select A Colour view allows you to select the
background colour of the widget from all listed internal
widget colours.
Enable Allows you to provide or select a variable that allows you to
Moniker control whether or not the widget is disabled/enabled
(greyed out or normal) at certain times. When the variable
is true, the widget is enabled.
On False Check this checkbox to force a reverse effect for the Enable
Moniker variable. The widget is enabled when the selected
variable is false.
Tie To Corner Select one of the radio buttons, which represents the
corner to which the widget is bound. If the DefaultView
form is stretched, you may want the widget to remain
stationary relative to a certain corner of the DefaultView
form. For example, a button that is placed near the lower
right corner of the DefaultView form can have the lower
right radio button selected. So the button is always the
same distance from the lower right corner of the
DefaultView form if the DefaultView form is stretched
vertically or horizontally.
This property is dependent on the selection for the Tie
Reference property as well as the Stretch properties.
Tie From this drop-down list, you can choose another widget to
Reference which the currently selected widget is bound. This can be
useful when you do not want to have stretching widgets
overlap on a DefaultView form. Otherwise, use the default
selection, which is the DefaultView form.
OK Click this button to close the widget’s Properties view and
accept the properties setting in the Properties view for the
widget.
Cancel Click this button to close the widget’s Properties view
without accepting any current changes made to the
properties setting on the Properties view.
Apply Click this button to apply changes to the widget without
closing the widget’s Properties view. This button is only
available after you made at least one change to the
properties setting.
Visibility The Visibility button opens the Widget Visibility Control
view, which is similar to the Visibility Controller Properties
view. Refer to the Section 4.2.3 - Visibility Manager.

4-33
4-34 Widget Properties

4.3.2 DefaultView Form Object

The DefaultView form object has its own set of properties that
control the appearance and functions performed by of the
DefaultView form. To view and change the attributes associated
with the DefaultView form you must access the Object Inspect
menu of the DefaultView form.

Figure 4.27

Right-click
anywhere on
the
DefaultView
form to access
the Object
Inspect menu.

The DefaultView Form Object

Inspect Menu
The DefaultView form Object Inspect menu has five commands:

Menu Option Description

Form Opens the Form Properties view of the DefaultView form.
Properties For more information of this view see the following Form
Properties View sub-section.
Open Opens the Visibility Manager view, from which you can
Visibility create controllers. Refer to the Section 4.2.3 - Visibility
Manager Manager for more information.
Snap Grid This option offers a sub-menu from which you can enable
and disable snapping to the DefaultView form background
(Snap All, Snap Selected, Disable), hide the snap grid or
resize the grid (2x2, 4x2, 4x4). The default is a 2x2 grid
with snapping enabled.
Test Select this to view a test of your DefaultView form.
Normally, this option is used to test the visibility options for
widgets on the tabs and the resizing of the DefaultView
form (i.e., stretching and tying of widgets).
Revert Selecting this option allows you to undo all changes since
your last saved version for the active view only.

4-34
 Extension View Editor 4-35

Form Properties View

The DefaultView form is the only object that has a unique
properties layout. It does not have the common properties listed
previously.

Figure 4.28

The following table contains a description of the objects in the

Form Properties view.

Object Description
Form Title The text entered in this field, appears in the title bar of the
DefaultView form. The default is a format string (%s) that
simply uses the object name.
Name Source Allows you to choose from a list of sources for the
DefaultView form name. By default, the object name is the
source.
Help Panel This entry provides a link between the view and the help
system, such that a certain help topic appears when F1 is
pressed and the particular view has focus. For extensions,
this is normally left blank.
Form Icon The choice of icon appears in the upper left corner of the
DefaultView form. Double-clicking on the icon brings up a
view from which you can choose an icon from a list of
internal UniSim Design icons.
Background Double-clicking on the associated cell brings up a view from
Colour which you can choose a DefaultView form background
colour from a list of UniSim Design colours.

4-35
4-36 Widget Properties

Object Description
Form Style In this group, you can choose one of the radio buttons that
assigns characteristics to the DefaultView form:
• Normal. A DefaultView form similar to most property
view in UniSim Design.
• Modal. A DefaultView form that always stays on top
of others and does not allow access to other views
until it is closed or de-pegged; can be pegged or not,
depending on the Peggable checkbox selection.
• Floating. A DefaultView form similar to the object
palette, that remains on top but does not restrict
access to other views.
The following checkboxes are also within the Form Style
group:
• Small Caption. Activating this checkbox reduces the
height of the caption area to that of a UniSim Design
face plate or the object palette. The checkbox is
available as a choice only to Normal style views. The
checkbox is checked by default for Floating style
views.
• Peggable. Activating this checkbox allows a modal
DefaultView form to become non-modal by placing a
peg in the upper right corner of the view. The
checkbox is available to Modal style views only.
• Cached Data. Activating this checkbox allows
changes to be made on the DefaultView form without
the object below knowing it until the time when:
FlushCache is called; this allows a user to make
changes to the DefaultView form and then click Cancel
without having the changes accepted; an example of
using this is on the New Object Type form, which can
be accessed from the Setup view of the Workbook.
The OK button sends both the FlushCache and
CloseView messages. The checkbox is available to
Modal style views only.
Action Allows you to specify a message to be sent, much like when
Messages a button is clicked, but in this case, when the user double-
clicks the background of the DefaultView form (Double
Ellipsis icon Click), opens the DefaultView form (Form Open) or closes
the DefaultView form (Form Close). Clicking the Ellipsis icon
brings up a view on which you can add, edit or delete the
messages.
Form Default Select a button name from either the Enter or Escape drop-
Buttons down list to have the button display its message when
either the ENTER key or ESC key is pressed, respectively.
Normal use is having the ENTER key associated with a Close
button and having the ESC key associated with a Cancel
button.
The Enter drop-down list is available with Normal and Modal
DefaultView forms, while the Escape drop-down list is only
available for Modal DefaultView forms.
File/Print The Widget to Print drop-down list allows the selection of a
Override particular widget on the DefaultView form to be printed
instead of the whole DefaultView form. The drop-down list
changes the way Print command under the File menu
works. An example of its use is on the PFD. When the PFD
is printed, all you get is the PFD, not its toolbar, tabs or the
DefaultView form surrounding the PFD.

4-36
 Extension View Editor 4-37

Object Description
Borders Allows you to specify the distance that the top, bottom, left,
and right edges of the DefaultView form are from the
outermost widgets. The minimum size of the DefaultView
form is dictated by the placement of the widgets on the
DefaultView form.
Units of measure are 1/8 of a character for the height and
1/4 of a character for the width, where the character in
question is of the size seen on a Button widget.

4-37
4-38 Widget Properties

Object Description
Advanced When you click the Advanced button, the Advanced Form
Properties view appears.

The following are options available in the view:

• Can Open Multiple. If not checked, the existing
DefaultView form is always opened; if checked, the
action of opening the DefaultView form opens a new
instance each time.
• Preserve Placement. If checked, the DefaultView
form re-opens in the same location where it was
before it was closed.
• Can Crop Width. If checked, allows you to resize the
view to a width smaller than minimum required width.
The minimum required width value is set to show all
the widgets on the view.
• Can Crop Height. If checked, allows you to resize the
view to a height smaller than minimum required
height. The minimum required height value is set to
show all the widgets on the view.
• Use Crop Scroll Bars. This option only makes sense
with one or both of the above crop settings checked.
The cropped scroll bars appear to allow you access at
the cropped area of the view.
• Disable Close. If checked, UniSim Design greys out
the Close icon and the close option from the Object
icon menu. UniSim Design still allows CloseView
messages.
• Page Limits. This group contains options that allow
you to specify a widget which serves as the page
bottom or top reference point. These values control
where the page’s bevelled edges are drawn. Usually,
the top is left blank and the bottom is specified as a
tabs widget.
• Suggested Size. This group contains fields that allow
you to enter width and height values for a useful size,
which can be larger than the minimum DefaultView
form size; minimum DefaultView form size is, as
described previously, a function of the widget
placement on the DefaultView form.

4-38
 Extension View Editor 4-39

4.3.3 Button Widget

The button widget is used to send specific instructions to its
base object when it is clicked by the user.

To access the Button The Button Properties view appears as shown in the figure
Properties view do one
of the following: below.
• Double-click the
button widget. Figure 4.29
• Right-click the
button widget, and
select the Button
Properties
command from the
Object Inspect
menu.

Button Properties
The properties available for a Button widget are described in the
table below:

Object Description
Label Whatever is entered in this field, is shown on the face of the
button. Place an ampersand (&) before the character that
gets the hot key (underscore) designation.
Message This is the command(s) that will be executed/fired when the
button is clicked. Common examples include: Delete and
CloseView. You can click the Ellipsis icon to access the Edit
Ellipsis icon Messages view, which provides a list of the current
messages that are being used for the particular button.
From this view, you can add new messages, delete existing
ones, edit the list or re-arrange the order in which the
messages are fired. If you have created variables of type
Message in the Objects Manager, these are available for
addition to the Edit Messages view.

4-39
4-40 Widget Properties

Object Description
Source Allows you to choose a widget that provides required
Widget information when the button is clicked. It is used to
‘populate’ the arguments for the Message.
For example, the Simulation Basis Manager view shows a list
of fluid packages in the Current Fluid Packages group. The
View button opens a fluid package according to the selection
made in the Current Fluid Packages group. Thus the text list
widget (list of fluid packages) acts as a source widget for the
View button.
Target Allows you to choose a widget which holds a collection of
Widget objects. The selected object or multiple selected objects will
be affected by the clicking of the button.
This is illustrated by the Delete button. This button has the
attachments list widget, which displays all of the column
specifications, as its target widget. By clicking the Delete
button, you are indirectly affecting the attachments list
widget by passing the: Delete message to a particular
Specification object. The target widget is not deleted, but is
updated after the selected Specification object is deleted.
Requires Activating this checkbox limits selection in the source widget
Single to a single item. Continuing the example cited in the Source
Source Widget discussion, activating this checkbox allows you to
select only a single fluid package in the list.
Requires Activating this checkbox limits selection in the target widget
Single to a single item. If the button deletes items from a list, you
Target may want to limit the user to only a single deletion per
button click.

4.3.4 Static Text Widget

Use this widget to show read-only text on the application’s view.

Figure 4.30

4-40
 Extension View Editor 4-41

Static Text Properties

The properties available for a Static Text widget are described in
the table below:

Object Description
Type of Select one of the radio buttons to specify the type of static
Text text widget:
• Fixed. Makes the Fixed Text field available. An example
of the use of this radio button is the descriptive text seen
beside a numerical input field.
• Source. Makes the Source Moniker field and Source
Widget drop-down list available. An example of the use
of this radio button is the status text seen at the bottom
of each unit operation property view.
There is also a Framed checkbox that you can checked if you
want the static text widget to have a frame. Unframed static
text widgets can usually be seen next to numerical or text
input widgets. An example of a framed version is the status
text for each unit operation.
Fixed Text This is available only when the Fixed radio button is selected.
Allows you to enter a string in the Fixed Text input field that
does not change at run-time.
Source This is available only when the Source radio button is
Moniker selected. Allows you to select a text variable that provides the
string for the static text widget. Any variables of type Text
Ellipsis icon that you have set up in the Objects Manager are available
when you click the Ellipsis icon. For a UniSim Design property
view status bar, the usual selection is Description of Highest
Status Condition.
Source Available only when the Source radio button is selected. This
Widget is rarely used in UniSim Design, but it allows you to choose a
widget that supplies the static text with information. For
example, you could select the tabs widget and have the tab
label appear in the static text widget.
Alignment Select a radio button to determine the justification of the text
in the static text widget. Choose Left, Centre, or Right.

4-41
4-42 Widget Properties

Object Description
Colour Allows you to select a variable that determines the
Variable background colour of the static text widget at run time. Click
the Ellipsis icon for current options. For a UniSim Design
Ellipsis icon property view status bar, the usual selection is Colour for
Current Status.
Ellipsis The selection in this drop-down list instructs the static text
Style widget how to show its information when the text is too long
to be fully shown. This should only apply to Source text, not
Fixed text, since you know the length of fixed text and can
adjust the size of the widget to accommodate it. You can
choose from three available options:
• None. The text is cropped according to the widget size.
• Path. Applies to file names; as much of the path name
as possible is shown; for instance, the path c:\program
files\UniSim Design\cases\ed.usc may be shown as
c:\,...\cases\ed.usc.
• End. As much as possible is shown with an ending … if
the text cannot fit.

4.3.5 Text Entry Widget

Use this widget to allow the user to input text on the view.

Figure 4.31

4-42
 Extension View Editor 4-43

Text Entry Properties

The properties available for a Text Entry widget are described in
the table below:

Object Description
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Text that you have created in the Object Manager.
Message This is the command(s) that will be executed/fired when
the ENTER key is pressed or the space bar is pressed,
depending on the radio button selection in the Send
Message After group.
Send Select the Enter Key radio button to send the command
Message specified in the Message input after the ENTER key has been
After pressed, or select the Token radio button to send the
Message command after the space bar has been pressed.
Multi-Line Check this checkbox if you would like the text entry widget
to hold more than a single line of text. Scroll bars are
added automatically. For more than a single line to be
shown at a time, you must resize the widget accordingly.
Word Wrap Available only when the Multi-Line checkbox is checked.
Check this checkbox if you would like the widget to start a
new line of text when the width of the widget has been
reached. If this checkbox is unchecked, you must use the
ENTER key to proceed to the next line.

Update Each When this checkbox is checked, an update (Viewable

Character methods SpecifyText and TextValue called) is performed
after each character is entered. This is used in the Match
cell for component selection, Components tab of the Fluid
Package view.
Allow When this checkbox is checked, the text entry widget is
Viewing Only read-only.
Push Default When this checkbox is checked, pressing the ENTER key
Button sends the message for the DefaultView form’s default
button. This is a convenience feature that allows the user to
enter a text string, press ENTER and have the DefaultView
form react as though the default button had also been
pressed. It is rarely used, but can be used to have the
DefaultView form accept the text input and close the
DefaultView form at the same time. The default button is
specified in the DefaultView form properties.

4-43
4-44 Widget Properties

Object Description
Mono Space Check this checkbox to have characters line up perfectly in
Font the vertical direction when using the Multi-Line
functionality.
This is equivalent to selecting Mono Space as a font in the
Session Preferences (Tools-Preferences).
Target By making a selection from this drop-down list, you are
Widget instructing the text entry widget to receive its information
from the Target Widget. When a target widget is selected,
the target moniker must correspond to a variable
associated with the target widget.
For example, you could select an attachment list (i.e., a list
of product streams) as the target widget and have the
selected item in the list, an object, appear in the text entry
widget. You would then have to link the Target Moniker to
the object variable type associated with the attachment list.

4.3.6 Rich Text Entry Widget

Use this widget to allow the user to enter text and change the
text’s attributes (i.e., font, colour).

Figure 4.32

4-44
 Extension View Editor 4-45

Rich Text Entry Properties

The properties available for a Rich Text Entry widget are
described in the table below:

Object Description
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Text that you have created in the Object Manager.
Get/Set As Check this checkbox if you would like all input to the widget
Text to be treated as text. This is useful if you will be passing the
moniker to a method that requires a text parameter. The
entered text loses any formatting that might bet attached to
it (i.e., strips RTF).
Hide Toolbar Checking this checkbox hides the toolbar that accompanies
the rich text entry widget.

4.3.7 Format Entry Widget

Use this widget to allow the user to choose the format for
certain values on the application’s view.

Figure 4.33

4-45
4-46 Widget Properties

Format Entry Properties

The properties available for a Format Entry widget are described
in the table below:

Object Description
Target This is the variable to which you put your widget data and/or
Moniker from which you get your widget data. It is the variable that is
associated with the widget. Clicking the Ellipsis icon gives a list
Ellipsis icon of available options, including any applicable variables that you
have created in the Object Manager.
Format This is the variable that represents the default format for the
Moniker widget. It is called when the user presses either the DELETE key
in the widget or the Use Default button on the Real Format
Editor view.

4.3.8 Numerical Input Widget

Use this widget to allow the user to input numerical values on
the application’s view.

Figure 4.34

4-46
 Extension View Editor 4-47

Numerical Input Properties

The properties available for a Numerical Input widget are
described in the table below:

Object Description
Target This is the variable to which you put your widget data and/or
Moniker from which you get your widget data. It is the variable that is
associated with the widget. Clicking the Ellipsis icon gives a list
Ellipsis icon of available options, including any variables of type Real
Number or Enumeration that you have created in the Object
Manager.
Format Specify the format for the value in the numerical input widget.
Clicking the Ellipsis icon brings up the Real Format Editor view.
Empty If the value held in the widget becomes -32767, whatever is
Text input in the Empty Text field is shown.
View Only Check this checkbox to make the widget read-only.
Hidden If the value held in the widget becomes -32768, whatever is
Text input in the Hidden Text field is shown.
Time If using a target moniker with time units, specify the format to
Format be shown.
Units There are three particulars in the Units group:
• Var Type Moniker. This is for historical purposes only
and is no longer relevant (the method GetEDVarType is
used internally).
• Show Unit. Check this checkbox if you want to show the
unit associated with the moniker with the value in the
widget.
For information • Fixed Unit Type. Enter a unit here if you want to force
concerning the format of the value in the widget to remain as this unit type
entries in this field, refer regardless of the unit set selection in the Session
to Section 12.3.1 - Preferences. For a temperature moniker, you could enter
Units Page from the ‘C’ and have the value always in Celsius.
UniSim Design User Target By making a selection from this drop-down list, you are
Guide. Widget instructing the Numerical Input widget to receive its
information from the Target Widget. When a target widget is
selected, the target moniker must correspond to a variable
associated with the target widget.
For an example, see the Target Widget property for the text
entry widget.
Use Popup Check this checkbox if you want the edit bar to pop up beside
Edit Bar the numerical input widget as opposed to below the view’s title
bar.
Disable Check this checkbox if you want to disable the fly by
Fly By description that appears when the cursor is over the Numerical
Input widget.

4-47
4-48 Widget Properties

4.3.9 Matrix Widget

Use this widget to display related information in an organized
fashion.

Figure 4.35

4-48
 Extension View Editor 4-49

Matrix Properties
The properties available for a Matrix widget are described in the
table below:

Object Properties
Data Sets In this list, you can Edit or Delete a selected data set or
Insert a new data set by clicking the appropriate button.
The View Editor requires a minimum of one data set at all
times for the matrix widget.
When the Insert button is clicked, you must choose the
type of data set from the Select a Data Type view. Each
type has its own set of properties. Only the most frequently
used data set types are described:
• Attachment. For objects such as streams, pump
curves, etc.
• Boolean. Shows a checkbox (or other designated
symbol) for true/false type situations.
• Enumeration. Shows the enumeration label for the
given enumeration value.
• Numeric. For any numeric value, real or integer.
• Text. For text values or labels.
• Unit. Used to show and specify the unit being used
(i.e. for time units, choose between seconds, minutes,
hours, etc.) for other data in the matrix; provides a
link for overriding the Session Preferences unit set for
other matrix data.
Vertical If this checkbox is checked, data sets are added one below
Direction the next (vertical direction).
Multi- If this checkbox is checked, you are able to select multiple
Selectable cells in the matrix, horizontally, vertically, and diagonally.
Sticky Last If this checkbox is checked, placing the focus on the last
Entry entry will keep the focus on the last entry in the matrix
even when additions are being made to the matrix. For
instance, while the solver is performing iterations, run time
data can enter a matrix. If you always wanted to see the
last entry in the list, you would check the Sticky Last Entry
checkbox and place the focus on the last entry in the
matrix. Placing the focus anywhere but on the last entry
will keep the focus on that particular entry, which is also
the behaviour which is exhibited if the checkbox is
unchecked.
Position Allows you to assign different monikers to the x and y
Track locations in the matrix so you can keep track of the exact
Monikers location of the focus. An example of this functionality is in
the Workbook. The Show Name Only button compresses all
the stream information to show only the names of the
streams. The current focus can be on any of the stream
properties (i.e., name, temperature, molar flow) when
uncompressed information is shown. When the Show Name
Only button is clicked the focus moves to the name of the
stream that held the focus, which would be a different row
number.

4-49
4-50 Widget Properties

Object Properties
Labels The Labels group has two drop-down lists, a numerical
entry cell and a cell for a label moniker:
• Unnamed. The first drop-down list is unnamed, but
allows you to choose where you would like labels
shown in the matrix. Your options are None, Row
(place the labels in the left column on each row),
Column (place the labels along the top row on each
column) and Both.
• Show Units. A drop-down list from which you can
choose to display units along with the label on the
Row, in the Column, or on Both, or choose None. This
will likely coincide with your choice of whether or not
to display units.
• Left Width. Enter a value for the leftmost column
when labels are present.
• Moniker. Assign a variable for the labels. An example
of its use is the assignment of labels to a matrix at run
time, when you could have a variety of names in a
matrix. If you are adding column specifications to the
column property view, you will have no idea what
specs will be added until run time, so by retrieving the
spec names through a running label moniker at run
time, you can perform this action.
Cells In this group, you can set global Width, Height and Wrap
values for the matrix widget. The cell width can be
overridden in the individual data set properties. The cell
height of 9 is the standard that is used in all UniSim Design
views. The value for Wrap allows you to force a particular
number of columns of data to be displayed in the matrix.
After this value is reached the next column of data starts at
the far left. An example of this behaviour is on the
Worksheet tab of the Column unit operation (its value is set
to 5).

4-50
 Extension View Editor 4-51

Object Properties
Enter Motion Select a direction for the focus movement when the ENTER
key has been pressed in the matrix. The options include:
• None. Stay in the same cell.
• Right. Move to the cell to the right.
• Down. Move to the cell directly below.
• Complement. Move to the complementary matrix cell
(i.e., if focus is in row 2, column 4 move to row 4,
column 2). An example of this behaviour is in the
binary coefficients matrix for the Chien Null activity
model.
• Right Wrap. Use this option in conjunction with the
Wrap cell. When data in the last cell of the rightmost
column has been input, the focus moves to the next
line in the leftmost column. This is used in the view for
molecular weight/density/viscosity assay data input.
• Right if Empty. If the value in the cell was <Empty>
before input, then move to the right; if it held a value
and the user is simply editing, then stay in that cell.
• Down if Empty. If the value in the cell was <Empty>
before input, then move down one cell; if it held a
value and the user is simply editing, then stay in that
cell.
• Complement if Empty. If the value in the cell was
<Empty> before input, then move to the
complementary matrix cell; if it held a value and the
user is simply editing, then stay in that cell.
Grids Specify whether you want the matrix grid shown for each
Column, each Row, Both rows and columns or None at all.
Target By making a selection from this drop-down list, you are
Widget instructing the matrix widget to receive its information from
the Target Widget. When a target widget is selected, the
target moniker must correspond to a variable associated
with the target widget.
For an example, see the Target Widget property for the Text
Entry widget.

DataSet Properties
All data set types have the following common properties:

Figure 4.36

4-51
4-52 Widget Properties

Object Description
Name Retain the default name or input a more descriptive name
for the data set, which appears in the Data Sets list on the
Matrix Properties view.
Fly By Place text in this cell to have a message appear in the
UniSim Design status bar and/or as a tool tip when the
mouse is placed over the data set. This overrides any Fly By
that has been input for the matrix widget. The ‘\n’ (newline
sequence) is used to differentiate status bar output and
tool tips.
For example, with the Fly By input of “Performs an
action.\nThe sky is blue”, the message to the left of the
newline sequence, “Performs an action”, would appear in
the status bar and the message to the right of the newline
sequence, “The sky is blue” would appear as a tool tip. If
the newline sequence is not used, the whole message
appears in the status bar.
Moniker This is the variable to which you put your data and/or from
which you get your data. It is the variable that is associated
with the data set. Clicking the Ellipsis icon gives a list of
Ellipsis icon available options, including any appropriate variables that
you have created in the Object Manager.
Message This is the command(s) that will be executed/fired when
the ENTER key is pressed.
Label Select either the Fixed or Moniker radio button and then
either specify a static label or associate a moniker with the
data set label.
Cell Width Enter a width for the data set cell that overrides the value
Override in the Width cell of the Cells group on the Matrix Properties
view.
View Only Check this checkbox to make the data set read-only.

Specific data set type properties include:

Attachment
Figure 4.37

Object Description
Drop List Assign a type of sorting for the list of attachments that
Sorting appears in the drop-down list: Ascending (alphabetical),
Descending (reverse alphabetical) or None.

4-52
 Extension View Editor 4-53

Object Description
Expand Style This is the recommended way, by controlling through the
widget instead of through code, to control how the matrix
expands.
There are three selections in this drop-down list:
• Always. Adds another field to the matrix when the
current boundary is exceeded. The default setting for
Empty Text is <Empty>.
An example of this behaviour is found for unit
operations that can handle multiple feeds or products.
You are first presented with something like <New
Feed>. As you add feeds, the matrix is expanded and
<New Feed> is added to the bottom of the list. When
the physical size of the matrix is exceeded, scroll bars
appear and another field is added to the bottom of the
list. In this case, the.edf file has been modified
through a text editor to change the Empty Text from
<Empty> to <New Feed>.
• Never. The matrix is limited to the physical size of the
widget.
• Limit. Supply a limit for the maximum size that is
allowed for the data set.
Allow Check this checkbox if you want the user to be able to type
Creation in a name and have a new object (of the particular type) be
created and added to the list if the name does not already
exist.
Show Tag If this checkbox is checked, you will see the flowsheet
Names name attached to the object name if you are currently not
in the flowsheet where the object resides (i.e., from the
column environment, you might see Feed@Main if the
stream Feed was created in the main environment).

Boolean
Figure 4.38

Object Description
True Icon Double-click on this cell to select an icon that represents
the true value of the Boolean, which is the value 1.
False Icon Double-click on this cell to select an icon that represents
the false value of the Boolean, which is the value 0.
Third State Double-click on this cell to select an icon that represents
Icon the (often misunderstood) other state of the Boolean,
which is any value other that 0 or 1.

4-53
4-54 Widget Properties

Enumeration
Figure 4.39

Object Description
Specify EMPTY Check this checkbox if you want -32767 to be set in
on Delete the variable when the user presses DELETE.

Numeric
Figure 4.40

Object Description
Format Specify the format for the value in the data set. Clicking the
Ellipsis icon brings up the Real Format Editor view.
Empty Text If the value held in the matrix cell becomes -32767,
Ellipsis icon whatever is input in the Empty Text field is shown.
Hidden Text If the value held in the matrix cell becomes -32768,
whatever is input in the Hidden Text field is shown.
Variable type This is for historical purposes only and is no longer relevant
override (the method GetEDVarType is now used internally).
moniker
Auto Assigns the appropriate unit according to the specified
Moniker and the chosen Unit Set in the Session
Preferences.
Moniker This choice allows you to override the selection in the
Session Preferences, but also gives the opportunity for the
user to make the unit selection at run time. You must
specify a moniker to be used when this radio button is
selected. This is usually used in conjunction with a Unit
data set, which specifies the unit moniker. The same
moniker is then used in this unit moniker cell, forming a
link between the two cells.
A good example is on the Integrator view, where the user
can select a time unit for the integrator step size. The step
size, minimum and maximum are then shown in that
selected time unit regardless of the choice in the Session
Preferences.

4-54
 Extension View Editor 4-55

Object Description
Fixed Allows you to hard code a particular unit type which
overrides the selection in the Session Preferences; for a
temperature moniker, you could enter ‘C’ and have the
value always in Celsius; for the format of entries in this
field, refer to the unit representations as shown in the
Display Units group on the Units page of the Session
Preferences view.
Show Unit in Check this checkbox if you want to show the unit associated
Cell with the data set Moniker along with the value in the cell.
Hide Units in Check this checkbox if you want to hide the unit in the data
Label set label.

Spreadsheet
Figure 4.41

Object Description
Unit System Optional setting. When set it allows the unit set used for
Moniker the held data to differ from the default “Unit Set”
configured in preferences.
Variable This is for historical purposes only and is no longer
Type relevant.
Moniker
Is Formula? Opens the Select Number Variable view. This allows you
Moniker to set whether the moniker will be used to get or set either:
text (a formula) or numbers (non-formula).
Formula Must return an error code form that indicates what type of
Error mathematical error has occurred or when all is well.
Moniker

4-55
4-56 Widget Properties

Unit
Figure 4.42

Object Description
Variable Type This is for historical purposes only and is no longer
Moniker relevant.

Worksheet Attach
Figure 4.43

Object Description
Expand There are three options for this drop-down list:
Style • Always. The default setting. It allows you to
automatically expand the worksheet data set to include
new entries.
• Never. This option does not allow you to expand the
number of variable entries.
• Limit. This option allows you to explicitly set the
number of entries you can expand to.

Numerical Format
Figure 4.44

Object Description
Default This is the variable that represents the default format for
Format the widget. It is called when the user presses either the
DELETE key in the widget or the Use Default button on the
Real Format Editor view.

4-56
 Extension View Editor 4-57

4.3.10 Check Box Widget

Use this widget for boolean (true/false or yes/no) situations.

Figure 4.45

Checkbox Properties
The properties available for a Checkbox widget are described in
the table below:

Object Description
Label Whatever is entered here is shown as the text next to the
checkbox. Place an ampersand (&) before the character
that gets the hot key (underscore) designation.
Label Select a radio button to place the label text to the left or to
Placement the right of the checkbox.
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Real or Enum that you have created in the Object
Manager.
Target By making a selection from this drop-down list, you are
Widget instructing the checkbox widget to receive its information
from the Target Widget. When a target widget is selected,
the target moniker must correspond to a variable
associated with the target widget.
For an example, see the Target Widget property for the Text
Entry widget.

4-57
4-58 Widget Properties

4.3.11 Radio Buttons Widget

Use this widget when you want the user to make a single
specific choice from a list of mutually exclusive choices
(normally a maximum of 3; if more than 3, use an enumeration
widget or other appropriate widget).

Figure 4.46

Radio Button Properties

The properties available for a Radio Button widget are described
in the table below:

Object Description
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Real or Enum that you have created in the Object
Manager.
Target By making a selection from this drop-down list, you are
Widget instructing the radio buttons widget to receive its
information from the Target Widget. When a target widget
is selected, the target moniker must correspond to a
variable associated with the target widget.
For an example, see the Target Widget property for the text
entry widget.

4-58
 Extension View Editor 4-59

Object Description
Insert Adds another entry in to the radio button details matrix
wherever the focus happens to be, but the entry will not be
named and will have no assigned value. The symbol +++ is
shown in the label cell.
Delete Deletes the entry from the radio button details matrix
wherever the focus happens to be.
Use This is not functional.
Template
Radio Button There are six columns in the matrix in which you can
Details specify details for the radio button widget:
Matrix • Label. Whatever is entered here will be shown as the
text next to the radio button. Place an ampersand (&)
before the character that will get the hot key
(underscore) designation.
• Value. Each radio button must have a unique value,
such that it can be used in code, if need be. The value
can be integer or real, it simply needs to be unique
within the scope of the particular widget.
• X. X coordinate of the particular radio button on the
DefaultView form. For information concerning the
units used, refer to the Position section under
Common Widget Properties.
• Y. Y coordinate of the particular radio button on the
DefaultView form. For information concerning the
units used, refer to the Position section under
Common Widget Properties.
• Width. Width of the widget. If you input different
values for each radio button, the largest value will be
honoured. For information concerning the units used,
refer to the Position section under Common Widget
Properties.
• Placement. Choice for where you want to place the
label, in reference to the radio button. Either On Left
or On Right.

4-59
4-60 Widget Properties

4.3.12 Graphic Button Widget

Use this widget to send specific instructions to its base object
when it is clicked by the user. More functionality is offered with
this widget than with the regular button widget. For instance,
you can have a picture appear on the button face and have the
button stick in its pressed state.

Figure 4.47

Graphic Button Properties

The properties available for a Graphic Button widget are
described in the table below:

Object Description
Main Icon Double-click on this cell to make a choice for the icon that
will appear on the button.
Focus Icon Double-click on this cell to make a choice for the icon that
will appear with the Main Icon on the button when the
button has focus. The default for Focus Icon is the regular
dotted outline that appears with most Windows programs.

4-60
 Extension View Editor 4-61

Object Description
Message This is the command(s) that will be executed/fired when
the button is pressed. For the button shown above, the
property view of the upstream unit operation will be shown.
You can click the Ellipsis icon to access the Edit Messages
view, which provides a list of the current messages that are
being used for the particular button. From this view, you
can add new messages, delete existing ones, edit the list or
re-arrange the order in which the messages are fired. If
you have created variables of type Message in the Objects
Manager, these will be available for addition to the Edit
Messages view.
Source Allows you to choose a widget that will provide required
Widget information when the button is fired. It is used to ‘populate’
the arguments for the Message. For example, the index
value of an object in a list could be provided to the button
so the button can perform some action on the particular
object. You can use placement holder type syntax (i.e.,%d
for an integer).
Target Allows you to choose a widget which holds a collection of
Widget objects. The selected object or multiple selected objects will
be affected by the firing of the button. For an example,
refer to the Target Widget section for the Button widget.
Value Type Allows you to choose what type of data is held or passed
when the button is pressed. You can choose one of the
following:
• None. The button’s only purpose is to fire its message
when it is pressed. The View Next Downstream
Operation button is an example of the use of this
option.
• Number. A numeric value is held when the button has
been pressed. The Colour Scheme button on the PFD
is an example of the use of this option.
• Object Type. An object type string is held when the
button is pressed. All unit operation and stream
buttons on the Object Palette use this option.
Repeat In these two fields, Initial and Fast, you can enter values
Delays that respectively represent the time that elapses before the
first message is sent and the time interval that will pass
before the sending of each subsequent message if the
button is held down. The units used for the time entries are
milliseconds.
This is used for the rotation of plots, where the user
presses and holds a button down to continually rotate the
plot until the desired view is attained.

4-61
4-62 Widget Properties

Object Description
Sticky These options allow you to set whether or not the button
Options will remain in its pressed state (Stuck) when it is pressed
and also if it is in its pressed state, whether or not pressing
the button again will remove it from its pressed state
(Released).
You can assign a variable (normally of type Boolean) in the
Variable cell to the option, which will allow you to monitor
the state of the button (Stuck or Released).
By providing values in the Stuck and Released cells, you
can assign one of two behaviours for the button:
• Pressing a Stuck button releases the button - provide a
unique value in each cell (i.e. 50 and 65)
• A Stuck button is released by another object - provide
the same value in each cell. This behaviour is exhibited
by the unit operation and stream buttons on the
Objects Palette. For instance, pressing a Cooler
operation button will make it stuck. You cannot release
the button by pressing it again. You must click the
Cancel button (the red X), click the Add button (the
green +), click another unit operation or stream button
in the palette or click on the PFD to add the operation.
Requires Activating this checkbox limits selection in the source
Single widget to a single item. Continuing the example cited in the
Source Source Widget discussion, activating this checkbox will
allow the user to select only a single fluid package in the
list.
Requires Activating this checkbox limits selection in the target
Single Target widget to a single item. If the button deletes items from a
list, you may want to limit the user to only a single deletion
per button click.
Accepts Check this checkbox if you want the button to take away
Focus the focus when it is pressed or to have the ability to accept
the focus when its tab order number is selected by pressing
the TAB key.
For instance, none of the buttons in the PFD toolbar have
this checkbox checked, and as such, do not accept the
focus when they are pressed. Focus remains with whatever
was selected in the PFD. Also, you cannot access the
buttons by pressing the TAB key.
Support Drag Check this checkbox if the button widget will be drag and
drop compliant. All unit operation and stream buttons in the
Object Palette have this checkbox checked, and thus, when
a button is selected with the secondary mouse button and
dragged, the value can be dropped onto another widget
(i.e. the PFD).

4-62
 Extension View Editor 4-63

4.3.13 Group Widget

Use this widget to organize related information within a titled
border on the application’s view.

Figure 4.48

Group Properties
The properties available for a Group widget are described in the
table below:

Object Description
Title Enter a title for the group. Use the ampersand (&) before the
character that is the accelerator key or hot key.

4-63
4-64 Widget Properties

4.3.14 Page Tabs Widget

Use this widget to increase the amount of information that can
appear on the application’s view. The widget can then be used in
conjunction with the Visibility Manager to organize the
information on particular tabs.

Figure 4.49

Page Tab Properties

The properties available for a Tab widget are described in the
table below:

Object Description
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Real or Enum that you have created in the Object
Manager.
Static Tabs In this group, supply a Label and a unique Value for each
tab that will appear in this widget.
The unique Value that is supplied for each tab should match
the High/Low values that you provide in the Visibility
Controller Properties view. Refer to the Section 4.2.3 -
Visibility Manager for more information.

4-64
 Extension View Editor 4-65

Object Description
Draw Border check this checkbox if would like a rectangular area around
the tabs to have a three-dimensional sunken effect. The
tabs in UniSim Design do not have this option enabled.
Dynamic There are three areas in this group, each of which deals with
Tabs the changing of the tabs at run-time:
• Label Moniker. Supply a variable in this cell if you
have to adapt the view according to user input at run-
time. For instance, the results view for the case study
tool in UniSim Design has a Label moniker (variable)
since the user can create as many case studies as
required in the simulation. The view must show one
tab per case study created.
• First Value. Provide a unique value in this cell such
that the first tab added at run-time does not conflict
with any of the values for the static tabs. This value
should be greater than the largest unique value that
you are using in the Static Tabs group.
• Move Tab Message. Allows you to input a custom
message, which will be defined in your code, to enable
the movement/re-ordering of the tabs at run-time by
the user. This functionality is found in the Workbook,
where you can select a tab, drag down below the tab
and then drag to the side where you would like to
move the tab. All tab contents are moved with the tab.
Controlled The widget selected in this drop-down list will receive the
Widget focus when a tab is selected. This functionality provides
visual appeal in that the tab seems to be part of the
controlled widget. The user does not have to click within the
controlled widget after selecting a tab. Normal use of this
option occurs when the selected widget is the only other
widget on the DefaultView form or when there is a clearly
dominant widget that will be the main focus of the user.
This functionality is used in the Workbook and in the PFD, in
which you can select a particular tab and the focus is
automatically placed within the particular Workbook sheet
or PFD pane.
Target By making a selection from this drop-down list, you are
Widget instructing the tabs widget to receive its information from
the Target Widget. When a target widget is selected, the
target moniker must correspond to a variable associated
with the target widget.
For an example, see the Target Widget property for the text
entry widget.

4-65
4-66 Widget Properties

4.3.15 Ply Picker Widget

This widget, used in conjunction with the tabs widget, provides a
way to further organize information while retaining a clean look
for the application’s view. With an enormous amount of
information, using this widget avoids the creation of tabs in the
double digits on a single view.

Figure 4.50

4-66
 Extension View Editor 4-67

Ply Picker Properties

The properties available for a Page Picker widget are described
in the table below:

Object Description
Title In this group you can provide a title for the ply picker
Options widget. Refer to the example widget shown previously,
which has the title Design, to see where the title is placed.
You see a different input cell in this group depending on the
radio button selection. The radio button selections are:
• Fixed. Choose this option if you want to supply a static
title, and then supply the text in the Title input cell.
• Dynamic. If you would like the title to be dynamic (i.e.
ability to change at run-time), select this option and
then associate the title with a variable in the Title
Moniker cell. Any variables of type Text that you have
created in the Object Manager will be shown when you
click the Ellipsis icon.
• Other Widget. Select this option if you want to choose
a widget that will supply the ply picker title with
information. You can then select a widget from the
Source Widget drop-down list. For example, you could
select the tabs widget and have the tab label appear as
the ply picker title widget. This is how the ply picker
widget on the UniSim Design unit operation property
views are configured.
Enum Allows you to associate an enumeration variable to the
Moniker widget so that the name of each individual ‘ply’ can appear
on the widget. For example, the widget shown previously,
the enumeration contains the names Connections,
Parameters, User Variables and Notes.
Target This is the variable to which you put your widget data and/or
Moniker from which you get your widget data. It is the variable that
is associated with the widget. Clicking the Ellipsis icon gives
Ellipsis icon a list of available options, including any variables of type
Real or Enum that you have created in the Object Manager.
Target By making a selection from this drop-down list, you are
Widget instructing the ply picker widget to receive its information
from the Target Widget. When a target widget is selected,
the target moniker must correspond to a variable associated
with the target widget.
For an example, see the Target Widget property for the Text
Entry widget.

4-67
4-68 Widget Properties

4.3.16 Attachment Name

Widget
Use this widget to display variables of type Attachment in a
drop-down list format.

Figure 4.51

Attachment Name Properties

The properties available for a Attachment Name widget are
described in the table below:

Object Description
Number of In this cell, you specify the size of the list that is shown
Entries when the drop-down list is accessed. If more objects
exist than the value specified, a scroll bar is
automatically added to the drop-down list.
Target Moniker This is the variable to which you put your widget data
and/or from which you get your widget data. It is the
variable that is associated with the widget.Clicking the
Ellipsis icon Ellipsis icon gives a list of available options, including
any variables of type Attachment that you have
created in the Object Manager.
Target Widget By making a selection from this drop-down list, you are
instructing the attachment name widget to receive its
information from the Target Widget. When a target
widget is selected, the target moniker must correspond
to a variable associated with the target widget.
For an example, see the Target Widget property for the
Text Entry widget.

4-68
 Extension View Editor 4-69

Object Description
Attach Message Allows you to specify a command(s) that will be
executed/fired when a choice is made in the
attachment name widget. All variables of type Message
that you created in the Objects Manager will be
available if you click the Ellipsis and then click the
Insert button on the Edit Messages view.
Allow creation Check this checkbox if you want the user to be able to
type directly in the attachment name widget and have
the application create a new object of type Attachment
with the user input name.
Most unit operation views that have attachment name
widgets will allow the creation of a new attached
stream when the user types a name directly in the
widget.
Use drop list Check this checkbox if you want the widget to show its
drop-down list when checked. If this checkbox is
unchecked, the widget appears as though it is a text
entry widget.
Match using Check this checkbox if you want the focus in the drop-
abbreviations down list to move to the first occurrence of the letter or
letter combination that the user types.
This checkbox is available only when the Use drop list
checkbox is checked.
Drop List Sorting Select one of the radio buttons to instruct the widget
on how you would like the items in the drop-down list
shown:
• Ascending. Items are shown alphabetically.
• Descending. Items are shown in reverse
alphabetical order.
• None. Items are shown in the order in which they
are added to the application.

4-69
4-70 Widget Properties

4.3.17 Enumeration Widget

Use this widget to display a list of names in a drop-down list
format.

Figure 4.52

Enumeration Properties
The properties available for a Enumeration widget are described
in the table below:

Object Description
Number of In this cell, you specify the size of the list that is shown
Entries when the drop-down list is accessed. If more objects
exist than the value specified, a scroll bar is
automatically added to the drop-down list.
Target Moniker This is the variable to which you put your widget data
and/or from which you get your widget data. It is the
variable that is associated with the widget. Clicking the
Ellipsis icon Ellipsis icon gives a list of available options, including
any variables of type Enumeration that you have
created in the Object Manager.
Target Widget By making a selection from this drop-down list, you are
instructing the enumeration widget to receive its
information from the Target Widget. When a target
widget is selected, the target moniker must correspond
to a variable associated with the target widget.
For an example, see the Target Widget property for the
Text Entry widget.

4-70
 Extension View Editor 4-71

Object Description
Match using Check this checkbox if you want the focus in the drop-
abbreviations down list to move to the first occurrence of the letter or
letter combination that the user types.
Drop List Sorting Select one of the radio buttons to instruct the widget
on how you would like the items in the drop-down list
shown:
• Ascending. Items are shown alphabetically.
• Descending. Items are shown in reverse
alphabetical order.
• None. Items are shown in the order in which they
are added to the application.

4.3.18 Unit Enumeration

Widget
Use this widget to display a list of units in a drop-down list
format.

Figure 4.53

4-71
4-72 Widget Properties

Unit Enumeration Properties

The properties available for a Unit Enumeration widget are
described in the table below:

Object Description
Number of In this cell, you specify the size of the list that is shown
Entries when the drop-down list is accessed. If more objects exist
than the value specified, a scroll bar is automatically added
to the drop-down list.
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Text that you have created in the Object Manager.
Target By making a selection from this drop-down list, you are
Widget instructing the unit enumeration widget to receive its
information from the Target Widget. When a target widget
is selected, the target moniker must correspond to a
variable associated with the target widget.
For an example, see the Target Widget property for the
text entry widget.
Unit Type/ This cell along with its corresponding radio buttons (Fixed
Unit Type and Source) are for historical purposes only.
Moniker
Match using Check this checkbox if you want the focus in the drop-
abbreviations down list to move to the first occurrence of the letter or
letter combination that the user types.
Drop List Select one of the radio buttons to instruct the widget on
Sorting how you would like the items in the drop-down list shown:
• Ascending. Items are shown alphabetically.
• Descending. Items are shown in reverse
alphabetical order.
• None. Items are shown in the order in which they are
added to the application.

4-72
 Extension View Editor 4-73

4.3.19 Text List Widget

Use this widget to display a list of object related information in
text format, from which the object can usually be accessed.

Figure 4.54

Text List Properties

The properties available for a Text List widget are described in
the table below:

Object Description
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Text that you created in the Objects Manager. Any
variables of type Text that you create must have Vector
selected in the N Dimensions drop-down list.
Message This is the message that is executed/sent when the user
presses ENTER or double-clicks on the selection in the
widget. Normal use would have the object’s property view
open.
Delete This is the message that will be executed/fired when the
Message user presses DELETE on the selection in the widget. Normal
use would have the object being deleted.
Insert This is the message that will be executed/fired when the
Message user presses INSERT while the focus is within the widget.

4-73
4-74 Widget Properties

Object Description
Track Supply a variable in this cell which will allow you to keep a
Moniker record of the selected object in the list or set the selected
object in the list, depending on how it is used in your code.
When there is multiple selection in the list, the first
(topmost) object in the selection will be accessed through
the track moniker. The track moniker will not correspond to
the object that has focus when multiple selection is made
from the top down, as the bottom most object will have the
dotted outline or focus.
Sorting Select one of the options in the drop-down list to instruct
the widget on how you would like the items in the widget
to be shown:
• Ascending. Items are shown alphabetically.
• Descending. Items are shown in reverse
alphabetical order.
• None. Items are shown in the order in which they are
added to the application.
Multi- Check this checkbox if you want to allow more than a
Selectable single selection in the widget.
Sticky Last If this checkbox is checked, placing the focus on the last
Entry entry will keep the focus on the last entry in the widget
even when additions are being made to the widget. Refer
to this option in the Matrix widget for an example.
Append Extra Check this checkbox if you want a blank row to always be
Blank present at the end of the list. This is useful when the user
is able to select the position of new entrants to the list. By
placing the focus on the blank row at the end, the new list
entrant will added to the end of the list. Placing the focus
on an existing list entry will have the new list entrant
added above this selection. This behaviour is exhibited in
the Current Component List on the Components tab of the
Fluid Package view.
Initially Check this checkbox if you want to have an item selected
Selected in the widget when the view is re-opened. This option
retrieves the list item identified in the track moniker and
tries to match this information to an item that you may
have coded (i.e. by name). If no match is found, the first
item in the list becomes the selected item and this
information is sent to the track moniker. A selected item
does not necessarily have the focus.
Source Allows you to choose a widget that will provide required
Widget information when any message is fired. It is used to
‘populate’ the arguments for a message.
Target By making a selection from this drop-down list, you are
Widget instructing the text list widget to receive its information
from the Target Widget. When a target widget is selected,
the target moniker must correspond to a variable
associated with the target widget.
For an example, see the Target Widget property for the
text entry widget.
Abbrev Keys Check this checkbox if you want the focus in the list to
move to the first occurrence of the letter or letter
combination that the user types.

4-74
 Extension View Editor 4-75

Object Description
Draw Border Check this checkbox if you would like a rectangular area
around the text list to have a three-dimensional sunken
effect.
Tab Stops Add values here which correspond to the use of ‘\t’, the tab
character, in the text strings that will populate the text list
widget.
If there are two occurrences of the tab character in the
text strings that will fill the widget, there should be two tab
stops, indicating the position to start the string after the
tab. With 2 tab stops, it will seem as though there are
three columns of information in the text list widget.
Column If you provide a value (the width of each column) in this
Width cell, list entries will wrap to the right in to a new column
when the current widget size has been reached. If no value
is provided, the list will keep expanding in a single column
with the appearance of scroll bars when the widget height
has been reached.

4.3.20 Enumeration List

Widget
Use this widget to display a list of the labels in an enumeration.

Figure 4.55

4-75
4-76 Widget Properties

Enumeration List Properties

The properties available for a Enumeration List widget are
described in the table below:

Object Description
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget.Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Enumeration that you created in the Objects Manager.
Message This is the message that is executed/sent when the user
presses ENTER or double-clicks on the selection in the
widget. Normal use would have the object’s property view
open.
Delete This is the message that will be executed/fired when the
Message user presses DELETE on the selection in the widget. Normal
use would have the object being deleted.
Insert This is the message that will be executed/fired when the
Message user presses INSERT while the focus is within the widget.
Track Supply a variable in this cell which will allow you to keep a
Moniker record of the selected object in the list or set the selected
object in the list, depending on how it is used in your code.
When there is multiple selection in the list, the first (top
most) object in the selection will be accessed through the
track moniker. The track moniker will not correspond to the
object that has focus when multiple selection is made from
the top down, as the bottommost object will have the
dotted outline or focus.
Sorting Select one of the options in the drop-down list to instruct
the widget on how you would like the items in the widget to
be shown:
• Ascending. Items are shown alphabetically.
• Descending. Items are shown in reverse alphabetical
order.
• None. Items are shown in the order in which they are
added to the application.
Multi- Check this checkbox if you want to allow more than a
Selectable single selection in the widget.
Sticky Last If this checkbox is checked, placing the focus on the last
Entry entry will keep the focus on the last entry in the widget
even when additions are being made to the widget. Refer
to this option in the Matrix widget for an example.
Append Extra Check this checkbox if you want a blank row to always be
Blank present at the end of the list. This is useful when the user
is able to select the position of new entrants to the list. By
placing the focus on the blank row at the end, the new list
entrant will be added to the end of the list. Placing the
focus on an existing list entry will have the new list entrant
added above this selection. This behaviour is exhibited in
the Current Component List on the Components tab of the
Fluid Package view.

4-76
 Extension View Editor 4-77

Object Description
Initially Check this checkbox if you want to have an item selected in
Selected the widget when the view is re-opened. This option
retrieves the list item identified in the track moniker and
tries to match this information to an item that you may
have coded (i.e. by name). If no match is found, the first
item in the list becomes the selected item and this
information is sent to the track moniker. A selected item
does not necessarily have the focus.
Source Allows you to choose a widget that will provide required
Widget information when any message is fired. It is used to
‘populate’ the arguments for a message.
Target By making a selection from this drop-down list, you are
Widget instructing the enumeration list widget to receive its
information from the Target Widget. When a target
widget is selected, the target moniker must correspond to
a variable associated with the target widget.
For an example, see the Target Widget property for the
text entry widget.
Abbrev Keys Check this checkbox if you want the focus in the list to
move to the first occurrence of the letter or letter
combination that the user types.
Draw Border Check this checkbox if you would like a rectangular area
around the enumeration list to have a three-dimensional
sunken effect.
Tab Stops Add values here which correspond to the use of ‘\t’, the tab
character, in the enumeration labels that will populate the
enumeration list widget.
If there are two occurrences of the tab character in the
enumeration labels that will fill the widget, there should be
two tab stops, indicating the position to start the label after
the tab. With 2 tab stops, it will seem as though there are
three columns of information in the enumeration list
widget.
Column If you provide a value (the width of each column) in this
Width cell, list entries will wrap to the right in to a new column
when the current widget size has been reached. If no value
is provided, the list will keep expanding in a single column
with the appearance of scroll bars when the widget height
has been reached.

4-77
4-78 Widget Properties

4.3.21 Attachment List Widget

Use this widget to display a list of related objects.

Figure 4.56

Attachment List Properties

The properties available for a Attachment List widget are
described in the table below:

Object Description
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Attachment that you created in the Objects Manager.
Any variables of type Attachment that you create must
have Vector selected in the N Dimensions drop-down list.
Message This is the message that is executed/sent when the user
presses ENTER or double-clicks on the selection in the
widget. Normal use would have the object’s property view
open.
Delete This is the message that will be executed/fired when the
Message user presses DELETE on the selection in the widget. Normal
use would have the object being deleted.
Insert This is the message that will be executed/fired when the
Message user presses INSERT while the focus is within the widget.

4-78
 Extension View Editor 4-79

Object Description
Track Supply a variable in this cell which will allow you to keep a
Moniker record of the selected object in the list or set the selected
object in the list, depending on how it is used in your code.
When there is multiple selection in the list, the first
(topmost) object in the selection will be accessed through
the track moniker. The track moniker will not correspond to
the object that has focus when multiple selection is made
from the top down, as the bottommost object will have the
dotted outline or focus.
Sorting Select one of the options in the drop-down list to instruct
the widget on how you would like the items in the widget to
be shown:
• Ascending. Items are shown alphabetically.
• Descending. Items are shown in reverse alphabetical
order.
• None. Items are shown in the order in which they are
added to the application.
Multi- Check this checkbox if you want to allow more than a single
Selectable selection in the widget.
Sticky Last If this checkbox is checked, placing the focus on the last
Entry entry will keep the focus on the last entry in the widget
even when additions are being made to the widget. Refer to
this option in the Matrix widget for an example.
Append Check this checkbox if you want a blank row to always be
Extra Blank present at the end of the list. This is useful when the user is
able to select the position of new entrants to the list. By
placing the focus on the blank row at the end, the new list
entrant will be added to the end of the list. Placing the
focus on an existing list entry will have the new list entrant
added above this selection. This behaviour is exhibited in
the Current Component List on the Components tab of the
Fluid Package view.
Initially Check this checkbox if you want to have an item selected in
Selected the widget when the view is re-opened. This option
retrieves the list item identified in the track moniker and
tries to match this information to an item that you may
have coded (i.e. by name). If no match is found, the first
item in the list becomes the selected item and this
information is sent to the track moniker. A selected item
does not necessarily have the focus.
Source Allows you to choose a widget that will provide required
Widget information when any message is fired. It is used to
‘populate’ the arguments for a message.
Target By making a selection from this drop-down list, you are
Widget instructing the attachment list widget to receive its
information from the Target Widget. When a target widget
is selected, the target moniker must correspond to a
variable associated with the target widget.
For an example, see the Target Widget property for the text
entry widget.
Abbrev Keys Check this checkbox if you want the focus in the list to
move to the first occurrence of the letter or letter
combination that the user types.

4-79
4-80 Widget Properties

Object Description
Hide Tags Check this checkbox if you do not want to show name of
the flowsheet with the name of the object in the list. The
flowsheet name will only appear when the object is being
shown outside its home flowsheet.
For instance, in a list of material streams, a stream
representing the reflux to a column, which is internal to the
column environment, may appear in a list in the main
flowsheet as Reflux@COL1 if the Hide Tags checkbox is
unchecked. With this checkbox checked, the user would
only see Reflux.
Draw Border Check this checkbox if you would like a rectangular area
around the attachment list to have a three-dimensional
sunken effect.
Allow Detach Check this checkbox if you want the object pointer to be
replaced by NULL when the attachment is deleted. If this
option is used, the code must account for this scenario. The
Allow Detach option is only valid when the Delete Message
is not being used.
Column If you provide a value (the width of each column) in this
Width cell, list entries will wrap to the right in to a new column
when the current widget size has been reached. If no value
is provided, the list will keep expanding in a single column
with the appearance of scroll bars when the widget height
has been reached.

4-80
 Extension View Editor 4-81

4.3.22 Level Widget

Use this widget to display a numerical value along with a
graphical representation of the value as a percentage of its full
range.

Figure 4.57

Level Properties
The properties available for a Level widget are described in the
table below:

Object Description
Format Specify the format for the value in the widget. Clicking the
Ellipsis icon brings up the Real Format Editor view.
Fixed Units Enter a unit here if you want to force the value in the
Ellipsis icon widget to remain as this unit type regardless of the unit set
selection in the Session Preferences. For a temperature
moniker, you could enter ‘C’ and have the value always in
Celsius.
For information concerning the format of entries in this
field, refer to Section 12.3.1 - Units Page from the
UniSim Design User Guide.
Variable This is for historical purposes only and is no longer relevant
Type (the method GetEDVarType is used internally).
Moniker

4-81
4-82 Widget Properties

Object Description
Target This is the variable to which you put your widget data and/
Moniker or from which you get your widget data. It is the variable
that is associated with the widget. Clicking the Ellipsis icon
Ellipsis icon gives a list of available options, including any variables of
type Real Number or Enumeration that you have created in
the Object Manager.
Orientation The radio button selection in this group provides
instructions on how to draw the graphical portion of the
widget. The choices are:
• Horizontal. The line representing the current value in
the range will be vertical. The use of Horizontal stems
from the fact that the ‘used’ portion and ‘unused’
portion of the range are seen one beside the other.
• Vertical. The line representing the current value in
the range will be horizontal. The use of Vertical stems
from the fact that the ‘used’ portion and ‘unused’
portion of the range are seen one above the other.
Increment Enter a value here which is used as the incremental step
size when the current value pointer is dragged in the level
widget. For the OP cell in a face plate, you can click on the
current value (when the controller is in Manual) with the
mouse and drag the line to a new output value. The
increment value for the OP cell is 0.01.
Minimum The Minimum cell as shown has no relevance. Both the
Minimum and Maximum values in the target moniker range
should be determined through monikers or through the
code.
Maximum The Maximum cell as shown has no relevance. Both the
Minimum and Maximum values in the target moniker range
should be determined through monikers or through the
code.
Show Unit Check this checkbox if you want to show the unit associated
with the moniker with the value in the widget.
View Only Check this checkbox to make the widget read-only.
Target By making a selection from this drop-down list, you are
Widget instructing the level widget to receive its information from
the Target Widget. When a target widget is selected, the
target moniker must correspond to a variable associated
with the target widget.
For an example, see the Target Widget property for the Text
Entry widget.

4-82
 Extension View Editor 4-83

Object Description
Display Mode The display mode represents the graphical portion of the
widget. Select either radio button:
• Percent. The graphical bar representing the current
value in the level widget will be shown at the
percentage value in the range. If you are monitoring a
temperature between 0 and 200°C, and the current
value is 20°C, the bar shows up at the 10% point in
the range.
• Actual. The graphical bar representing the current
value in the level widget will be shown at the current
value in the range. If you are monitoring a
temperature between 0 and 200°C, and the current
value is 20°C, the bar shows up at the 20°C point in
the range.
It is recommended that you select the same radio button
choice in both the Display Mode and the Value groups.
Value The value represents the numeric value shown in the
widget. Select either radio button:
• Percent. The numeric value in the level widget is
shown as the percentage value in the range. If you are
monitoring a temperature between 0 and 200°C, and
the current value is 20°C, you see 10 in the widget
representing 10% of the range.
• Actual. The numeric value in the level widget is
shown as the actual value in the range. If you are
monitoring a temperature between 0 and 200°C, and
the current value is 20°C, you see 20°C in the widget.
It is recommended that you select the same radio button
choice in both the Display Mode and the Value groups.

4-83
4-84 Widget Properties

4.3.23 Plot Widget

Use this widget to show a two-dimensional or three-dimensional
graph. The appropriate plot is shown according to the values
sent through code.

Figure 4.58

Plot Properties
The properties available for a Plot widget are described in the
table below:

Object Description
Draw Check this checkbox if you would like a rectangular area
Border around the plot to have a three-dimensional sunken effect.
Plot Enter a description (with no spaces in the name) here such
Description that you can access the widget through code.
Target This is the variable to which you put your widget data and/or
Moniker from which you get your widget data. It is the variable that is
associated with the widget. Clicking the Ellipsis icon gives a
Ellipsis icon list of available options, including any variables of type Real
Number or Enumeration that you have created in the Object
Manager.

4-84
 Extension View Editor 4-85

4.3.24 Worksheet Matrix

Widget
When a Worksheet Use this widget to display related information in an organized
Matrix (i.e., the
Workbook matrix) is
fashion. The Worksheet Matrix provides all the functionality of
resized by the user, the the Matrix widget in addition to the built-in run-time wrapping
number of columns capabilities.
dynamically change
according to the current
size of the view. Figure 4.59

4-85
4-86 Widget Properties

Worksheet Matrix Properties

The properties available for a Worksheet Matrix widget are
described in the table below:

Object Description
For more information on Data Sets In this list, you can Edit or Delete a selected data set or
the data set type Insert a new data set by clicking the appropriate button.
properties see DataSet The View Editor requires a minimum of one data set at all
Properties found in times for the worksheet matrix widget.
Section 4.3.9 - Matrix
When the Insert button is clicked, you must choose the
Widget.
type of data set from the Select a Data Type view. Each
type has its own set of properties. Only the most frequently
used data set types are described:
• Attachment. For objects such as streams, pump
curves, etc.
• Boolean. Shows a checkbox (or other designated
symbol) for true/false type situations.
• Enumeration. Shows the enumeration label for the
given enumeration value.
• Numeric. For any numeric value, real or integer.
• Text. For text values or labels.
• Unit. Used to show and specify the unit being used
(i.e., for time units, choose between seconds,
minutes, hours, etc.) for other data in the matrix;
provides a link for overriding the Session Preferences
unit set for other matrix data.
Vertical If this checkbox is checked, data sets are added one below
Direction the next (vertical direction).
Multi- If this checkbox is checked, you are able to select multiple
Selectable cells in the matrix, horizontally, vertically and diagonally.
Sticky Last If this checkbox is checked, placing the focus on the last
Entry entry will keep the focus on the last entry in the matrix
even when additions are being made to the matrix. For
instance, while the solver is performing iterations, run time
data can enter a matrix. If you always wanted to see the
last entry in the list, you would check the Sticky Last Entry
checkbox and place the focus on the last entry in the
matrix. Placing the focus anywhere but on the last entry
will keep the focus on that particular entry, which is also
the behaviour which will be exhibited if the checkbox is
unchecked.
Position Allows you to assign different monikers to the x and y
Track locations in the matrix so you can keep track of the exact
Monikers location of the focus. An example of this functionality is in
the Workbook. The Show Name Only button compresses all
the stream information to show only the names of the
streams. The current focus can be on any of the stream
properties (i.e. name, temperature, molar flow) when
uncompressed information is shown. When the Show Name
Only button is clicked the focus moves to the name of the
stream that held the focus, which would be a different row
number.

4-86
 Extension View Editor 4-87

Object Description
Labels The Labels group has two drop-down lists, a numerical
entry cell and a cell for a label moniker:
• Unnamed. The first option is unnamed, but allows
you to choose where you would like labels shown in
the matrix. Your options are None, Row (place the
labels in the left column of each row), Column (place
the labels along the top row on each column) and
Both.
• Show Units. A drop-down list which you can choose
to display units along with label on the Row, in the
Column or on Both or choose None. This will likely
coincide with your choice of whether or not to display
units.
Cells In this group, you can set global Width, Height and Wrap
values for the worksheet matrix widget. The cell width can
be overridden in the individual data set properties. The cell
height of 9 is the standard that is used in all UniSim Design
views. The value for Wrap allows you to force a particular
number of columns of data to be displayed in the matrix.
After this value is reached the next column of data will start
at the far left. An example of this behaviour is on the
Worksheet tab of the Column unit operation (its value is set
to 5).
Enter Motion Select a direction for the focus movement when the ENTER
key has been pressed in the matrix. The options include:
• None. Stay in the same cell.
• Right. Move to the cell to the right.
• Down. Move to the cell directly below.
• Complement. Move to the complementary matrix cell
(i.e. if focus is in row 2, column 4 move to row 4,
column 2). An example of this behaviour is in the
binary coefficients matrix for the Chien Null activity
model.
• Right Wrap. Use this option in conjunction with the
Wrap cell. When data in the last cell of the rightmost
column has been input, the focus moves to the next
line in the leftmost column. This is used in the view for
molecular weight/density/viscosity assay data input.
• Right if Empty. If the value in the cell was <empty>
before input, then move to the right; if it held a value
and the user is simply editing, then stay in that cell.
• Down if Empty. If the value in the cell was <empty>
before input, then move down one cell; if it held a
value and the user is simply editing, then stay in that
cell.
• Complement if Empty. If the value in the cell was
<empty> before input, then move to the
complementary matrix cell; if it held a value and the
user is simply editing, then stay in that cell.

4-87
4-88 Widget Properties

Object Description
Grids Specify whether you want the matrix grid shown for each
Column, each Row, Both rows and columns or None at all.
Target By making a selection from this drop-down list, you are
Widget instructing the worksheet matrix widget to receive its
information from the Target Widget. When a target widget
is selected, the target moniker must correspond to a
variable associated with the target widget.
For an example, see the Target Widget property for the Text
Entry widget.

4.3.25 ACTIVEX Container

Widget
This widget allows you to incorporate ActiveX objects in to your
DefaultView form.

Figure 4.60

ActiveX Container Properties

The properties available for a ActiveX Container widget are

4-88
 Extension View Editor 4-89

described in the table below:

Object Description
Control CLSID Clicking the Ellipsis icon opens the Select an ActiveX
Control view which displays a list of ActiveX Controls.
Selecting a control inserts the Class Identity currently
Ellipsis icon available on your computer.
Custom Clicking this button displays the custom properties
Properties associated with the ActiveX Control.
The Control CLSID field must first be selected before this
button can be used.
Associations Opens the Set Associations with ActiveX Properties and
Events that allows you to tie the control to an event or the
custom properties to a variable.
The Control CLSID field must first be selected before this
button can be used.
Unique Tag This the internal designation of the control.
Caption Text The text associated with the control.
Menu Title The text label that appears in the menu bar when the
control has focus.
Draw Border Draws a border around the ActiveX Control.
Container can This checkbox is for internal use only and should not go
alter extent unchecked.

4-89
4-90 Widget Properties

4-90
 User Variables 5-1

5 User Variables

5.1 Introduction................................................................................... 2

5.2 Adding a User Variable................................................................... 2

5.3 Importing/Exporting User Variables .............................................. 6

5.4 User Variable View......................................................................... 8

5.5 Data Types ................................................................................... 10

5.5.1 Real Data Type....................................................................... 11
5.5.2 Enumeration Data Type ........................................................... 12
5.5.3 Message Data Type................................................................. 13
5.5.4 Code Only Data Type .............................................................. 13

5.6 User Variables Tabs ..................................................................... 13

5.6.1 Macros Tab ............................................................................ 14
5.6.2 Attributes Tab ........................................................................ 16
5.6.3 Filters Tab ............................................................................. 18
5.6.4 Security Tab .......................................................................... 19
5.6.5 Defaults Tab .......................................................................... 20

5.7 Code Editor .................................................................................. 21

5.8 User Variable Examples ............................................................... 22

5.8.1 Dew Point Temperature Variable ............................................... 22
5.8.2 Automatic Pump Energy Stream ............................................... 26

5-1
5-2 Introduction

5.1 Introduction
For example, you could User Variables help you to increase the internal functionality of
attach a User Variable to UniSim Design objects, such as streams and unit operations, by
a stream to ensure that
the flow rate is specified dynamically attaching variables and code to those objects from
lower than a certain within UniSim Design itself. User Variables are indistinguishable
value. Or, you could
have a view appear from the variables built into UniSim Design objects and, as such,
when a vessel can be added to spreadsheets, targeted by logic controllers,
temperature exceeds a have their values specified by your input, etc.
certain value.

User Variables let you attach code written in a Visual Basic©

compatible macro language to simulation objects and specify
when that code is to execute. In doing so, you have a simple
means of adding extra functionality to any UniSim Design
simulation.

5.2 Adding a User Variable

You can add User Variables on three levels within your case:
• Flowsheet Object. User Variables can be added to most
UniSim Design flowsheet objects in the User Variables
matrix located on the User Variables page or the User
Variables tab, of the object's property view.

Figure 5.1
Regardless of where the
User Variables matrix is
located, the matrix is
the same as the one
shown in the figure on
the right.

5-2
 User Variables 5-3

• Flowsheet. If you want to attach a User Variable to the

flowsheet on which you are working, open the
Flowsheet menu in the menu bar and select Flowsheet
User Variables command.

Figure 5.2

• Simulation. If you want to add a User Variable to your

simulation, open the Simulation menu in the menu bar
and select Simulation User Variables command.

Figure 5.3

The User Variables view contains all the User Variables currently
attached to the object. There is a drop-down list that serves as a
filter to sort the displayed User Variables by Data Type.

There is no User Variables page or tab attached directly to

the Column view. User Variables can be attached to the
individual components of the Column (tray section, reboiler
etc.) only when you are in the column sub-flowsheet
environment.

The User Variables matrix lists the User Variables of the object
owning the view. The name of the variable appears in the left
column, and the value appears in the right. Un-initialized values

5-3
5-4 Adding a User Variable

of type Real displays <empty> in the right column. Un-

initialized non-scalar values displays <Multidimensional>.

The User Variables are listed in their execution order. You can
change the execution order using the icons in the toolbar.

Before you add the first The toolbar above the matrix lets you create, edit, and delete
User Variable to an
object, only the Create
variables as well as filtering and ordering the list. Until one or
a New User Variable and more User Variables are added to an object, some of the icons
the Sort Alphabetically at the top of the view are disabled. The drop-down list, on the
and Sort by Execution
Order buttons are left side of the icons, filters the matrix by data type and
active. customer user type.

The following table outlines User Variables view icon

functionality:

Name Icon Function

Create a New When this icon is clicked, the Create a New
User Variable User Variable view opens.

You can also open the Edit the Selected Select an existing User Variable and click this
edit view of a User User Variable icon to open the view of the existing User
Variable by double- Variable for editing.
clicking on its name in
Delete the Select the User Variable you want to delete
the matrix.
Selected User and click this icon.
Variable UniSim Design requires confirmation before
proceeding with the deletion. If a password
has been assigned to the User Variable, the
password is requested before proceeding with
the deletion.
Sort Click this icon to sort the User Variable list
Alphabetically alphabetically.

Sorting by execution Sort by Click this icon to sort the User Variable list
order is important if Execution Order according to the order by which they are
your User Variables executed by UniSim Design.
have order
Move Selected Click this icon to move the selected User
dependencies in their
Variable Up In Variable up in execution order.
macro code. Normally, Execution Order
you should try and
avoid these types of Move Selected Click this icon to move the selected User
dependencies. Variable Down In Variable down in the execution order.
Execution Order
Show/Hide Shows or hides the Variable Enabling
Variable checkboxes associated with each User
Enabling Variable. By default, the checkboxes are not
Checkbox displayed.

5-4
 User Variables 5-5

To add a User Variable:

1. Access the User Variables matrix in the object where you
want to associate the User Variables.
2. In the User Variables view, click the Create a New User
Variable icon. The Create New User Variable view appears.
3. Fill in the parameters for your new User Variable in the
Create New User Variables view. Refer to the figure below for
information on how to fill in the User Variable parameters.

Figure 5.4

Select the data type from Click this icon to hide

this drop-down list. the variable details.
You can define your own
filters on the Filters tab
of the User Variable Enter the User
editing view. Variable name
here.

Use these tabs

to specify
further
information.

Code field

Allows you to
add password
security to the
User Variable.

5-5
5-6 Importing/Exporting User

5.3 Importing/Exporting
User Variables
You may import and export User Variables between cases via
the Import Export User Variables view.

Figure 5.5

Exporting a User Variable

The following general procedure can be used to export User
Variables:
1. Select Import and Export User Variables command from
the Simulation menu. This opens the Import and Export

5-6
 User Variables 5-7

User Variables view.

Figure 5.6

A list of User Variables currently attached to the case

appears in the User Variables In Case group. The list on the
right displays a list of variables attached to the object
selected in the list on the left.
2. In the User Variables In Case group, select the object
containing the User Variable you want to export from the left
list, then select the User Variable you want to export from
the right list.
3. Click the Export button. This opens the User Import/Export
Variable File view.

Figure 5.7

4. Select the path you want to save the file in.

5-7
5-8 User Variable View

5. In the File name field type the name of the file you want to
save the User Variables to and click the Save button.
The file is saved with *.huv file extension.

Importing a User Variable

The following general procedure should be used for importing
User Variables to a case.
1. Select Import and Export User Variables command from
the Simulation menu. This opens the Import and Export
User Variables view.
2. Click the Select File button. This opens the User Variable
Import/Export File view.
3. Find the *.huv file that contains the User Variables you want
to import and click the Save button.

The file name you selected should now appear in the User
Variables In Export File group under the Current Export
File: text. A list of user variables in the file should appear in
the list in this group.
4. Select the variable you want to import and click the Import
button.

5.4 User Variable View

When you add a User Variable to an operation, the Create a New

5-8
 User Variables 5-9

User Variable view, shown in the figure below, appears.

Figure 5.8

For more information on The only entry fields common to all user variable data types are
using security
passwords, see Section the Name and Tag fields. The Name specified is the visible name
5.6.4 - Security Tab. of the variable used throughout UniSim Design. The Tag is the
unique identifier used to access this user variable
programmatically. These two strings are often identical and the
variable tag automatically defaults to be the same as the
variable Name, if not specified. You are prompted to provide an
alternate Name or Tag if they are not unique among all User
Variables attached to the object. You are also prompted to
provide a cryptic tag if the User Variable uses a security
password.

Finally, the Show or Hide Variable Details icon, in the upper-right

corner of the editing view, expands or shrinks the Code Editor.
Hide Variable Details
This icon either hides or reveals most of the attribute fields of
the User Variable. Normally, once a User Variable has been
defined, its attributes remain fairly static and most effort is
directed toward editing and debugging its macro code. For this
Show Variable Details
reason, the code field is presented in its expanded position when
debugging or editing the User Variable, and in its reduced

5-9
5-10 Data Types

position when creating the variable.

5.5 Data Types

Type Drop-down List
Five data types are available from the Type drop-down list:

Figure 5.9

• Real (double precision floating point number)

• Enumeration
• Text
• Code Only
• Message

The drop-down list at the top of the User Variables view can
change, depending on the additional requirements for the
specified data type.

5-10
 User Variables 5-11

Dimensions Drop-down List

When a Real, Enumeration or Text data type is specified, the
Dimensions drop-down list is available on the User Variables
view. Data dimensions available from the drop-down list
include:
• Scalar
• Vector (array)
• Matrix
• Cube (3 dimensions)

5.5.1 Real Data Type

Units Drop-down List
The Units drop-down list is available only when Real is selected
as the Data Type.

Figure 5.10

From this drop-down list you can select one of the existing
variable types built into UniSim Design in order to determine
units and valid numeric range for the new variable. For example,
selecting Temperature results in a User Variable displaying units
of temperature that accepts input in Celsius, Kelvin, Rankin or
Fahrenheit. That same variable would also automatically
disallow out of range input such as a negative Kelvin value or a
Celsius value less than -273.15.

5-11
5-12 Data Types

This drop-down list defaults to variable type Index, which is a

unitless, generic type. The Variable Changing macro can be used
to provide custom filtering of input values for a user variable if
desired. See the Section 5.6.1 - Macros Tab for more details.

5.5.2 Enumeration Data Type

When you select Enumeration as the User Variable type, the
Enumeration Values button appears directly below the
Dimensions drop-down list:

Figure 5.11

Click this button and the Enumeration Values view, containing a

two-column matrix appears:

Figure 5.12

Entering text labels in the left column and corresponding

numeric values in the right column to define the enumeration.
The resulting Enumeration Variable appears in UniSim Design
views as a drop-down list containing these text labels. Selecting
one of these labels assigns the corresponding value to the User
Variable.

5-12
 User Variables 5-13

5.5.3 Message Data Type

Type Message variables have a single purpose: to execute their
Fire macro when the user variable is invoked programmatically,
usually in response to you clicking a button. Message User
Variables are currently applicable mainly to UniSim Design
Extensions.

5.5.4 Code Only Data Type

A user variable of type Code Only allocates no storage space for
itself but still serves as a host for attaching macro code. If you
want to write macro code that does not preserve any results or
state information, then a Code Only User Variable is the most
efficient choice.

5.6 User Variables Tabs

Additional settings appear in the central pane of the User
Variable editing view and are grouped under five tabs:
• Macros
• Attributes
• Filters
• Security
• Defaults

5-13
5-14 User Variables Tabs

5.6.1 Macros Tab

The Macros tab lists the macros that can be enabled for the
variable currently being edited. The macros listed on the left
side of the tab vary depending on the level within your
simulation that the User Variable was created. These macros are
described in the following table:

Object Macros
Flowsheet PreExecuted. Invoked when the Steady State solver is
Object about to execute the flowsheet object that owns this
variable.
PostExecuted. Invoked immediately after the Steady
State solver executes the flowsheet object that owns this
variable.
Flowsheets PreSolve. Invoked before the Steady State solver begins
solving the flowsheet.
PostSolve. Invoked after the Steady State solver
completes the flowsheet solution.
Simulation Run. Explicitly invoked when the Run button on the
Case Simulation Case User Variables view is clicked.

Enable the macro by activating the checkbox to the right of the

macro name, as shown in the figure below. This User Variable is
attached to a flowsheet object and, as such, has a Pre-Execute
and Post-Execution macro. Once checked, the empty sub-
routine code for the macro is initialized in the Code Editor.

Figure 5.13

5-14
 User Variables 5-15

The checkboxes in the Variable group on the right of the Macros

tab enables macros that are invoked when the value of the User
Variable is modified or accessed.

The sub-routines that are added to the User Variable when the
checkboxes, in the Variable group, are checked include:

Sub-routine Initialization
Variable Called when an attempt is made to specify a new value for
Changing the User Variable from any source other than the variable’s
own macro code.The new value is available for inspection
using the ActiveVariableWrapper macro keyword. If the
Variable Changing code chooses to disallow the change, it
must set the AllowThisChange property to false.
Variable Invoked immediately after a new value has been assigned
Changed to the variable.
Variable Invoked whenever the value for a User Variable is about to
Query be read.

The following code example demonstrates simple bounds

checking for a numeric User Variable using a Variable Changing
sub-routine:

Code Example
Sub VariableChanging()
If ActiveVariableWrapper.NewRealValue > 100 Or
ActiveVariableWrapper.NewRealValue < 1 Then
AllowThisChange = False
MsgBox "Valid values are in the range 1-100", vbOkOnly,
"User Variable"
End If
End Sub

The presence of code for a particular macro sub-routine is not

sufficient to have that code invoked - the macro's checkbox
must also be enabled. If you disable a macro, UniSim Design
requires confirmation before it proceeds with this action. Pasting
or typing macro sub-routine code in to the Code Editor causes
the specific macro to be automatically enabled.

If you disable a macro with its code still present and then
type or paste in the Code Editor, the macro is automatically
re-enabled.

5-15
5-16 User Variables Tabs

5.6.2 Attributes Tab

The Attributes tab has two associated groups:
• Activation
• Solver

Activation Group
The Activation group refers to the scope of the variable. A User
Variable is defined for an entire class of objects but can be
optionally enabled only in specific instances of these objects or
made to appear automatically in all instances. Specify the
activation by choosing from either the Automatic or User
Enabled radio button.

Figure 5.14

Automatic User Variables appear in all instances of the object

type for which it is defined within a simulation. Most objects
have a discrete type such as pumps or mixers. However, some
types can manifest themselves in different forms. For example,
streams can be either material or energy streams and share
their User Variables. That is, variables created in material
streams are also available to energy streams, and vice versa. If
you do not want a User Variable to be available universally
across an object type, you can specify it to be User Enabled
setting by selecting the User Enabled radio button.

5-16
 User Variables 5-17

With the User Enabled radio button selected, specific variables

appear only in certain instances of an object type. The variable
can be turned on or off for specific instances of objects of that
type. To do this, use the enabling column of the User Variables
matrix in the objects' property views.

Figure 5.15

Enabling
column
checkboxes

The Enable In <Object Name> checkbox of the Activation group

is a short-cut for checking the enable switch of the variable in
the current object.

The Automatic setting overrides any previous User Enable

settings. UniSim Design, however, preserves the user setting
and if the variable is switched back to User Enabled, the
previously specified setting is restored. This means that you can
easily switch specific variables on and off across an entire object
type simply by editing the variable from any object instance and
changing it between Automatic and User Enabled.

Even if no instances of a particular object type exist in a

simulation case, any User Variables previously defined for that
object type are preserved. If new instances of the type are ever
added to the case, they automatically inherit the previously
defined User Variables.

5-17
5-18 User Variables Tabs

Solver Group
The Solver group of the Attributes tab contains a single
checkbox labelled Trigger Solve. This checkbox is only available
Solver group for Real and Enumeration data types. When enabled, the User
Variable causes the object instance that owns it to recalculate
whenever the value of the variable is changed. This is analogous
to the UniSim Design Process Variable.

5.6.3 Filters Tab

The Filters tab provides a mechanism for creating and assigning
custom variable types that can be used to filter User Variables
lists.

Figure 5.16

To add a new filter type, click the Edit button. The Filter Names
view opens:

Figure 5.17

From this view you can create new filter names. Once the new
filter names have been specified, click the OK button to return to
the User Variable view. If you do not want to keep the filter
names you specified, click the Cancel button. New filter names
appear in the list on the right of the Filters tab.

5-18
 User Variables 5-19

The native data type (Real, Text, etc.) is always included in the
list of active filters. It cannot be deleted. To include a newly
created filter name with the active filters, highlight the filter
name on the right and click the Add button. To remove a filter
from the active list, click the Remove button.

Filtering can only be applied using the drop-down list of the

User Variable page of Unit Operation views.

5.6.4 Security Tab

There are two levels of User Variable protection available on the
Security tab. The two levels are split into two groups on the tab:
• Password to Edit/Delete
• Variable

Figure 5.18

Password to Edit/Delete Group

When you have assigned a password, you are required to enter
that password before the variable can be edited or deleted. As a
convenience, if the password is entered correctly when
requested it is not requested again until the next time the case
is opened. However, you are always required to enter the
password if you are attempting to delete a User Variable.
Combining a password with the Automatic attribute would
guarantee that a User Variable is always present in any instance
of its owning object.

A suitably cryptic variable Tag is highly recommended when

using a password in order to protect against programmatic
access to the variable.

5-19
5-20 User Variables Tabs

Variable
The second level of security is the Calculate Only setting. Check
this checkbox to ensure that only the User Variable’s macro code
can change its value.

5.6.5 Defaults Tab

The Defaults tab lets you assign a default value to the User
Variable. Default value may only be assigned to scalar variables
of type Real, Enumeration, and Text. Without an explicit default
value, scalar variables of these types are initially created with
empty values.

Figure 5.19

To assign a default
value, check the
Assign Default Value
checkbox and enter
the desired value in
the field.

5-20
 User Variables 5-21

5.7 Code Editor

The Code Editor is where you write, using the Visual Basic®
compatible macro language, and debug the macro code that you
are attaching to a simulation object. You can add break points to
the code by simply clicking in the bar that borders the left side
of the Code Editor. If there are no break points in your code, the
macros execute seamlessly as part of your UniSim Design case.
The Code Editor is shown below:

Figure 5.20

Once changes are made

to your code in the Code
Editor, click the Start
Solver icon to continue Code Editor
with the UniSim Design toolbar.
calculations.

Break Point

Tool Tip Text

A single quote (') preceding text in the Code Editor indicates a
Visual Basic® user comment. For UniSim Design User Variables,
any user comments written in the first three lines of the Code
Editor appears as a tool tip when the cursor is placed over the
User Variable name in the matrix on the User Variable page or
tab. See Figure 5.28.

5-21
5-22 User Variable Examples

5.8 User Variable

Examples
5.8.1 Dew Point Temperature
Variable
The following User Variable example can be applied to any
UniSim Design simulation. In it, you create a new User Variable
that calculates and displays, in the User Variable Matrix, the
Dew Point Temperature for a material stream.
1. Open any material stream in your simulation to the User
Variables page:

Figure 5.21

2. Click the New User Variable icon at the top of the user
variable matrix. The Create New User Variable view opens.
New User Variable icon

5-22
 User Variables 5-23

3. In the Create New User Variable view, enter the following

information in the indicated fields:

Field Input
When you specify a Name DewPt Temp
Name, it is
Type Real
automatically copied to
the Tag field. Units Temperature

4. On the Attributes tab, select the User Enabled radio

button in the Activation group. You are then required to
manually enable the variable in any of the material streams
that requires this variable.

Figure 5.22

5-23
5-24 User Variable Examples

This step is a 5. On the Security tab, check the Calculate Only checkbox.
convenience and not a This ensures that no one attempts to specify a value for this
requirement for macro
User Variable other than its macro.
execution.

Figure 5.23

6. On the Macros tab, check the PostExecute() checkbox. An

empty sub-routine automatically appears in the Code Editor.
Enter the PostExecute macro as follows:

Macro Code
Sub PostExecute()
On Error GoTo ErrorHandler
Dim myFluid As Object
ActiveVariableWrapper.Variable.Erase
Set myFluid = ActiveObject.DuplicateFluid
FS = 0
FS = myFluid.PVFlash(ActiveObject.PressureValue, 1.0)
If FS = 0 Then ' fsFlashOK

ActiveVariableWrapper.Variable.SetValue(myFluid.Temperature.GetValue)
End If
ErrorHandler:
Exit Sub
End Sub

The error checking is in place to so that the macro can

handle <empty> values. If the value is <empty> the
macro exits the sub-routine and continue on to the next one.

A new User Variable of type Temperature, named DewPt Temp,

now exists in all current and future instances of streams in this
case. The DewPt Temperature automatically calculates its value
during a steady state solve pass immediately after its owning
stream executes.

5-24
 User Variables 5-25

The user variable exists in both Material and Energy streams,

but the dew point calculation only applies to Material
streams. The variable fails to calculate a value in energy
streams; this is harmless, but the macro could be modified to
test for the stream type before performing its calculations.

Re-calculate the stream and the dew point temperature value

appears in the User Variables page for all the streams in your
simulation.

The figure below shows two streams views with the calculated
values:

Figure 5.24

5-25
5-26 User Variable Examples

5.8.2 Automatic Pump Energy

Stream
The User Variable created in this example automatically adds an
energy stream to a pump operation whenever both Feed and
Product streams are connected. This is accomplished through an
Enumeration type User Variable. The code is such that the work
of creating and connecting the Energy stream to a pump is
performed only once, unless otherwise specified. The energy
streams added is named using the operation name, followed by
“_W.” For instance, the energy stream for pump P-100 is named
P-100_W.
1. Install a pump into the PFD, if the simulation case does not
already have a pump. Open the pump property view.
2. Go to the User Variables page on the Design tab.
3. Click the New User Variable icon from the top of the
matrix.
New User Variable icon
Figure 5.25

4. Enter the following information for the fields in the resulting

Create New User Variable view, as specified in the following
table.

Field Input
Name QStream
Type Enumeration

5-26
 User Variables 5-27

5. Edit the enumeration values by clicking the Enumeration

Values button. Create two labels in the left column of this
view named Not Yet Run and Has Run; assign the values 0
and 1 to them, respectively.

Figure 5.26

6. When completed as shown in the figure above, click the OK

button.

The Label names are not important, but the numeric values
of the two must match the NotYetRun and HasRun constants
used in the associated code.

7. On the Attributes tab, select the Automatic radio button in

the Activation group. This creates the variable in all current
and future instances of pumps in your simulation case.

5-27
5-28 User Variable Examples

8. Check the PostExecute() checkbox found on the Macro

tab. Enter the following PostExecute macro in the Code
Editor.

Macro Code
' Automatically add and connect an energy stream once feed and product
' streams are connected.
' The process will not repeat unless this variable is reset to NotYetRun.

' Global constants matching the enumeration values of this user variable.
' Note that only constant values are useful here. Non-constant global
' variables will lose their values
' between invocations of this macro code. Create user variables when
' storing persistent 'information.
Const NotYetRun = 0
Const HasRun = 1

' The use of both late and early binding are demonstrated here.
' Late binding should be used during development and testing since it is
' more robust and produces more useful error messages.
' Early binding should be used where performance is an issue as it is
' slightly faster. Or when an explicit 'cast' to a certain interface of
' an object is required.
Sub PostExecute()
' Error handling minimized for clarity.
On Error GoTo UnknownError

'Early binding of PumpOp object.

Dim pump As PumpOp
'ActiveObject is the object that owns this user variable.
Set pump = ActiveObject

' Early binding of RealVariable object.

Dim thisvar As RealVariable
' ActiveVariableWrapper is the InternalVariableWrapper containing this
' user variable.
Set thisvar = ActiveVariableWrapper.Variable
' Only run once. If the user wants me to run again,
' change my value to "Not Yet Run'
If thisvar.Value = HasRun Then GoTo AlreadyAdded
If Pump.FeedStreamVar.IsKnown = False Then
Exit Sub
ElseIf Pump.ProductStreamVar.IsKnown = False Then
Exit Sub
ElseIf Pump.EnergyStreamVar.IsKnown = False Then

5-28
 User Variables 5-29

Macro Code
'Late binding of Streams collection and Stream object.
Dim strs As Object
Dim newstr As Object
Set strs = ActiveCase.Flowsheet.MaterialStreams
Dim strName As String
strName = Pump.name + "_W"
Set newstr = strs.Add(strName)
newstr.IsEnergyStream = True
Pump.EnergyStream = newstr
thisvar.Value = HasRun
Else
thisvar.Value = HasRun
End If
Exit Sub
AlreadyAdded:
Exit Sub
UnknownError:
End Sub

Now, whenever both inlet and outlet streams are connected to

any pump in the case, and no energy stream is currently
connected to that pump, a new energy stream is automatically
created and connected to that pump.

For the pump and streams shown on the left of the figure below,
once the inlet and outlet streams are connected, the stream
PUMP_W is automatically created, as shown to the right:

Figure 5.27

5-29
5-30 User Variable Examples

The first three lines of comment in your code appear as tool tip
fly by when the cursor hovers over the variable in on the User
Variables page:

Figure 5.28

This process changes the value of the Enumeration User Variable

containing the code to Has Run, as shown above. This ensures
that the work of creating and connecting the energy stream is
not repeated for that pump.

Toggling the setting back The User Variable enumeration can be explicitly toggled for any
to Not Run Yet would
allow the macro to once pump instance by changing its value in the User Variable Matrix
again add and connect a on the User Variables page. Select the value in the right column
new Energy stream
of the matrix and then access the drop-down list (see the figure
during a steady state
execution of the pump below). You can select Not Yet Run from the list.
when inlet and outlet
streams are connected.
Figure 5.29

5-30
 User Unit Operation 6-1

6 User Unit Operation

6.1 Introduction................................................................................... 2

6.2 Adding a User Unit Operation......................................................... 2

6.3 User Unit Op Property View ........................................................... 5

6.3.1 Design Tab .............................................................................. 6
6.3.2 Worksheet Tab ....................................................................... 11

6.4 Dehumidifier Example.................................................................. 12

6-1
6-2 Introduction

6.1 Introduction
The User Unit Operation is a UniSim Design unit operation much
like any other, except that its behaviour is defined entirely with
Visual Basic® compatible code that you provide. It allows you to
create additional unit operation types without the complexity
involved in creating an Extension Unit Operation.

With properly designed code, a user-defined unit operation type

can be seamlessly integrated in to UniSim Design cases and for
use by third parties. However, this level of sophistication and
user-friendliness is not necessary for all user ops - you may
want to quickly create a type that is specialized for use in
specific situations or at a specific location in a case.

6.2 Adding a User Unit

Operation
Adding a User Unit Operation to a case requires you to follow a
slightly different procedure than is normally followed when
adding the standard UniSim Design unit operations. Before you
can add the initial User Unit Operation to a case, you must first
create an operation Type. The Type is simply a classification for
the User Unit Operation, much like Pumps or Heaters are types
for unit operations that currently exist in UniSim Design.

To add a User Unit Operation:

1. Do one of the following:
• Open the Object Palette (press F4) and double-click the
User Ops icon from the Object Palette.
• Select Add Operation command from the Flowsheet
User Ops icon menu, or press F12. The UnitOps view appears. Select
User Unit Ops from the Available Unit Operations group
on the UnitOps view.

If you use the User Ops filter on the UnitOps view, the left
side of the view changes to include the same buttons that
appear in the view on Figure 6.1.

6-2
 User Unit Operation 6-3

2. When the User Unit Operation has been added, the following
view appears:

Figure 6.1

The view shown above lists the available User Unit Operation
types, lets you add new operations of existing types, and
lets you create or delete operation types.
3. Click the Create Type button to add a new type to the list.
The following view opens:

Figure 6.2

4. Enter a descriptive name for the operation type you want to

create and click the OK button. This type is added to the
Available User Unit Operation Types group in the Add a User
Unit Operations view.

6-3
6-4 Adding a User Unit Operation

5. To add an operation of that type, highlight the type you

created and click the Add button. The User Unit Op view
appears:

Figure 6.3

By default, the second

feed and product
nozzles, as well as the
energy nozzles are
checked.

Importing and Exporting a User Unit

Op
The Add a User Unit Operation view contains two buttons:
Import and Export that allow you to transfer User Unit
Operations between cases.

Exporting a User Unit Op

1. To export a User Unit Op, simply select the User Unit Op type
you want to export and click the Export button.
2. The Export User Unit Op view appears. Type the name of the
file you want to save under in the File name field.
3. Choose the path you want to save the file to.
4. Click the Save button.
5. The file is saved with *.huo file extension.

6-4
 User Unit Operation 6-5

Importing a User Unit Op

1. Click the Import button on the Add a User Unit Op view.
2. From the Import User Unit Op view, select the *.huo file that
contains the User Unit Op type you want to import.
3. Click the Open button. This should add the User Unit Op to
the list of Available User Unit Operation Types.

6.3 User Unit Op Property

View
Unlike most other UniSim Design unit operations, the User Unit
Op view consists of only two tabs: Design and Worksheet.

Figure 6.4

By default, the second

feed and product
nozzles, as well as the
energy nozzles are
checked.

6-5
6-6 User Unit Op Property View

6.3.1 Design Tab

There are five pages associated with the Design tab:
• Connections
• Code
• Variables
• Notes
• Export

Connections Page
On the Connections page you can specify the Name of the
operation, and attach Feed, Product, and Energy streams.

Figure 6.5

You can add as many Feed and Product streams as your

operation requires. Each User Unit Operation has two material
feed nozzles, two material product nozzles, one energy feed
nozzle, and one energy product nozzle available. Each of these
nozzles can accept multiple stream attachments. UniSim Design
provides default nozzle names - Feed1, Product1, etc. These
names can be changed to better describe the functioning of your
operation.

The first feed and first product nozzles are always active, but the
other four nozzles can be activated or deactivated depending on
the type of requirements of your User Unit Operation. Attach

6-6
 User Unit Operation 6-7

streams to the nozzles in the matrices directly below the nozzle

names. Highlight the <empty> cell and select an available
stream name from the drop-down list, or enter the stream name
directly. To change the name of the nozzle, simply click on the
appropriate field and begin typing.

If you want a second nozzle for feed or product streams, check

the checkbox directly to the right of the second stream nozzle
field (Feed2 or Product2). The Connections page changes and
activates another matrix. This matrix allows you to attach the
streams to a second stream nozzle.

If your User Unit Operation requires Energy streams, check the

checkboxes to the right of the Energy In or Energy Out fields
and once again, a stream matrix becomes visible.

Nozzles can also be configured programmatically. This is the

preferred mechanism when designing a User Unit Operation that
may be added multiple times to a flowsheet or different cases.
See the code in Section 6.4 - Dehumidifier Example for an
example of automatically configuring nozzles in the Initialize
sub-routine.

Code Page
On the Code page, you add the Visual Basic® compatible code
that defines the behaviour of your User Unit Operation.

Figure 6.6

6-7
6-8 User Unit Op Property View

The code environment in the User Unit Operation is very similar

to that described for the User Variables, see Chapter 5 - User
Variables for more information.

Code can be added by clicking the Edit button. This opens the
Edit Existing Code view. The view in the figure below shows the
three empty sub-routines that appear before you begin adding
code in the view.

Figure 6.7

6-8
 User Unit Operation 6-9

The three User Unit Operation sub-routines are described in the

following table:

Sub-routine Action
Initialize() Called immediately before the first time Execute is
called. This sub-routine should be used to set up the
unit operation. Decide which nozzles are valid and
name them; create any variables that will be needed
and give them initial values, etc.
Execute() Called whenever a trigger solve variable of the unit
operation is changed, and whenever any of its attached
streams re-calculates. This sub-routine should perform
all of the unit operation’s calculations. In this sub-
routine only, it is permissible (and recommended) to
use the Calculate method to write data to variables of
the operations attached streams. These variables are
then displayed in black in UniSim Design, and cause an
inconsistency error if any other object attempts to
calculate their values.
StatusQuery() Called whenever UniSim Design wants to update the
status information for its objects. This sub-routine
should be used to provide warning and error messages
for any missing connections, missing variable values,
etc. These messages will be displayed in the UniSim
Design status bar, as well as at the bottom of the User
Unit Operation’s view.

Empty versions of these three sub-routines are automatically

generated for each new User Unit Operation Type.

It is recommended that any sub-routine that you do not

want to be implemented be deleted or turned in to comments
by preceding each line with the single-quote comment
character. This ensures that UniSim Design does not waste
time calling an empty sub-routine. The sub-routine can be
implemented or un-commented at any time.

The left border of the Code page is a development tool for you to
use as you add code to your operation. You may add break
points in this border thereby allowing you to step through your
code. Simply click the primary mouse button in the margin on
the left side of the code pane next to the line you want to insert
the break for.

6-9
6-10 User Unit Op Property View

The standard debugging view is shown as follows:

Figure 6.8

Variables Page
User Variables do not You can attach User Variables to the User Unit Operation, as you
have the PreExecute and
PostExecute macro
can to any flowsheet object, to further customize your
options. simulation case.
The Execute macro of
the User Unit Operation User Unit Operation User Variables can be used to store
itself is intended to
perform all calculations calculation results, persistent state information, etc. These
required to implement variables can be created manually from the Variables page, or
the operation and its programmatically using the CreateUserVariable method of the
variable values.
Active Object interface.

For more information on adding code and implementing this

option, see Chapter 5 - User Variables.

6-10
 User Unit Operation 6-11

Notes Page
The Notes page provides a text editor where you can record any
comments or information regarding the User Unit Operation, or
pertaining to your simulation in general.

Export Page
The Export page allows you to export the User Unit Operation,
by clicking the Export button and entering the file name and file
path for the User Unit Operation. The file is saved with *.huo file
extension.

You can also add a description about the User Unit Operation in
the Type Description group.

6.3.2 Worksheet Tab

The Worksheet tab provides the same information as the default
Material Streams page of the Workbook. However, this page only
displays the streams that are currently attached to the User Unit
Operation.

6-11
6-12 Dehumidifier Example

6.4 Dehumidifier Example

The following example shows how to create a new User Unit
Operation. This operation will function as a dehumidifier. From a
single feed stream containing water, the operation copies the
conditions and composition of its feed stream in to two product
streams. The first product consists of the stream composition
minus any water; the second is a pure water stream.
1. Begin by creating a new case. Click the New Case icon.
2. Create the following fluid package and then enter the Main
New Case icon Simulation Environment:

Property Package Components

PRSV Methane, Ethane, Propane, i-Butane, n-Butane, i-
Pentane, H2O

3. Specify a material stream Feed, with the following

properties:

Stream Properties Value

Temperature [C] 23.0000
Pressure [kPa] 303.9750
Molar Flow [kgmole/h] 100.0000
Comp Mole Frac [Methane] 0.40
Comp Mole Frac [Ethane] 0.20
Comp Mole Frac [Propane] 0.15
Comp Mole Frac [i-Butane] 0.10
Comp Mole Frac [n-Butane] 0.05
Comp Mole Frac [i-Pentane] 0.05
Comp Mole Frac [H2O] 0.05

4. Add two more material streams: Dry Product and Wet

Product.
5. Add a new User Unit Operation to your case. Double-click the
User Ops icon from the Object Palette. The Add a User Unit
Operation view appears.
User Ops icon

6-12
 User Unit Operation 6-13

6. Click the Create Type button on the Add a User Unit

Operation view. Enter Dehumidifier as the New User
Operation Type name field and click the OK button.

Figure 6.9

The Dehumidifier operation type is added to the list of User

Ops types for the current case.
7. After you click the OK button, both New User Operation Type
Name and Add a User Unit Operation views close, and User
Unit Op view for the dehumidifier appears as shown in the
figure below.

Figure 6.10

This operation requires that a single feed nozzle and both

product nozzles are active. As no energy stream is required
for the operation, the energy nozzles can be left unchecked.
At this point, the op-100 is unable to perform any
calculations on any attached streams.

6-13
6-14 Dehumidifier Example

8. To add code, switch to the Code page and click the Edit
button. This opens the Edit Existing Code view where you
can enter the following code:

Dehumidifier Code
Sub Initialize()
' Of the four optional nozzles, we only want the second products:
ActiveObject.Feeds1Name = "Feed"
ActiveObject.Products1Name = "Dry Product"
ActiveObject.Feeds2Name = "Inactive Feed"
ActiveObject.Feeds2Active = False
ActiveObject.Products2Name = "Water Product"
ActiveObject.Products2Active = True
ActiveObject.EnergyFeedsName = "Inactive Energy In"
ActiveObject.EnergyFeedsActive = False
ActiveObject.EnergyProductsName = "Inactive Energy Out"
ActiveObject.EnergyProductsActive = False
End Sub
Sub Execute()
On Error GoTo EarlyExit
' get the feed stream
Dim feed As Object
Set feed = ActiveObject.Feeds1.Item(0)
If feed Is Nothing Then GoTo EarlyExit
' get the dry product stream
Dim prod As Object
Set prod = ActiveObject.Products1.Item(0)
If prod Is Nothing Then GoTo EarlyExit
' get the water product stream
Dim wtr As Object
Set wtr = ActiveObject.Products2.Item(0)
If wtr Is Nothing Then GoTo EarlyExit
' find the position of water in the current Fluid Package's component
list
Dim theComps As Object
Set theComps = ActiveObject.Flowsheet.FluidPackage.Components
waterPosn = theComps.index("H2O")
' get the array of component molar flows from the feed stream
Dim CMFs As Variant
CMFs = feed.ComponentMolarFlowValue
WaterFlow = CMFs(waterPosn)
DryFlow = Feed.MolarFlowValue - WaterFlow
' calculate the Temperature, Pressure, and Flow of the water product

6-14
 User Unit Operation 6-15

Dehumidifier Code
stream
wtr.Pressure.Calculate(feed.PressureValue)
wtr.Temperature.Calculate(feed.TemperatureValue)
wtr.MolarFlow.Calculate(WaterFlow)
' remove the water from the CMF array
CMFs(waterPosn) = 0.0
' calculate Temperature, Pressure, and ComponentMolarFlows of the dry
stream
prod.Pressure.Calculate(feed.PressureValue)
prod.Temperature.Calculate(feed.TemperatureValue)
prod.MolarFlow.Calculate(DryFlow)
' calculate the composition of the dry stream
For i = 0 To theComps.Count - 1
CMFs(i) = CMFS(i) / DryFlow
Next i
prod.ComponentMolarFraction.Calculate(CMFs)
' calculate the composition of the water stream (pure water)
For i = 0 To theComps.Count - 1
CMFs(i) = 0.0
Next i
CMFs(waterPosn) = 1.0
wtr.ComponentMolarFraction.Calculate(CMFs)
' tell the Solver we're done
' (this will remove the "Not Solved" status message)
ActiveObject.SolveComplete
Exit Sub
EarlyExit:
' not enough info to calculate
End Sub
Sub StatusQuery()
On Error GoTo ThatsAll
Dim GotOne As Boolean
GotOne = False
If ActiveObject.Feeds1.Count = 0 Then
GotOne = True
ActiveObject.AddStatusCondition(slMissingRequiredInformation, 1,
"Feed Stream Required")
End If
If ActiveObject.Products1.Count = 0 Then
GotOne = True
ActiveObject.AddStatusCondition(slMissingRequiredInformation, 2,
"Dry Product Stream Required")
End If

6-15
6-16 Dehumidifier Example

Dehumidifier Code
If ActiveObject.Products2.Count = 0 Then
GotOne = True
ActiveObject.AddStatusCondition(slMissingRequiredInformation, 3,
"Water Product Stream Required")
End If
' If we're missing an attachment, don't bother checking for any other
problems
If GotOne = True Then GoTo ThatsAll
On Error GoTo NoWater
waterPosn =
ActiveObject.Flowsheet.FluidPackage.Components.index("H2O")
GoTo AfterWaterCheck
NoWater:
GotOne = True
ActiveObject.AddStatusCondition(slError, 11, "No Water in Current Fluid
Package")
AfterWaterCheck:
On Error GoTo ThatsAll
Dim feed As Object
Set feed = ActiveObject.Feeds1.Item(0)
If Not feed.Temperature.IsKnownThen
ActiveObject.AddStatusCondition(slMissingOptionalInformation, 12,
"Feed Temperature Unknown")
GotOne = True
End If
If Not feed.Pressure.IsKnownThen
ActiveObject.AddStatusCondition(slMissingOptionalInformation, 13,
"Feed Pressure Unknown")
GotOne = True
End If
If Not feed.MolarFlow.IsKnown Then
ActiveObject.AddStatusCondition(slMissingOptionalInformation, 14,
"Feed Flow Unknown")
GotOne = True
End If
' The composition's IsKnown will return a Variant containing an array of
Booleans.
' We must make a variable containing the array before we attempt to
access a data
' member.
' (i.e., "feed.ComponentMolarFraction.IsKnown(0)" will probably not
work)
CMFsKnown = feed.ComponentMolarFraction.IsKnown

6-16
 User Unit Operation 6-17

Dehumidifier Code
If Not CMFsKnown(0) Then
ActiveObject.AddStatusCondition(slMissingOptionalInformation, 15,
"Feed Composition Unknown")
GotOne = True
End If
If GotOne = True Then GoTo ThatsAll
If ActiveObject.Feeds1.Count > 1 Then
GotOne = True
ActiveObject.AddStatusCondition(slWarning, 20, "Additional Feed
Stream(s) Ignored")
End If
If ActiveObject.Feeds1.Count > 1 Then
GotOne = True
ActiveObject.AddStatusCondition(slWarning, 20, "Additional Feed
Stream(s) Ignored")
End If
If ActiveObject.Products1.Count > 1 Then
GotOne = True
ActiveObject.AddStatusCondition(slWarning, 21, "Additional Dry
Product Stream(s) Ignored")
End If
If ActiveObject.Products2.Count > 1 Then
GotOne = True
ActiveObject.AddStatusCondition(slWarning, 22, "Additional Water
Product Stream(s) Ignored")
End If
Dim BogusCnxn As Boolean
BogusCnxn = False
If ActiveObject.Feeds2.Count > 0 Then
BogusCnxn = True
ElseIf ActiveObject.EnergyFeeds.Count > 0 Then
BogusCnxn = True
ElseIf ActiveObject.EnergyProducts.Count > 0 Then
BogusCnxn = True
End If
If BogusCnxn = True Then
GotOne = True
ActiveObject.AddStatusCondition(slWarning, 7, "Connection(s) to
Inactive Nozzles")
End If
ThatsAll:
End Sub

6-17
6-18 Dehumidifier Example

When this code has been inserted, the Dehumidifier

operation is complete. Any additional Dehumidifier objects
added to the case will automatically access the same code,
and function identically to the one already created.
9. Click the OK button to close the Edit Existing Code view and
return to the Code page of the User Unit Op view.

Figure 6.11

The original instance of The Initialize sub-routine code automatically configures the
the Dehumidifier may
invoke Initialize before nozzles appropriately.
you have entered the 10. Click the Initialize button in the Manual Invoke group to
example code.
ensure that the nozzles are reconfigured.
Any future instances of Dehumidifier will not require this
explicitly extra Initialize once the macro code has been
entered and debugged.

6-18
 User Unit Operation 6-19

Deactivate the extra 11. Complete the Connections page by attaching streams as
nozzles by clearing the shown in the figure below:
checkboxes to the right
of the nozzle names.
Figure 6.12

When a stream is connected to the first nozzle attachment, the

Initialize sub-routine should run. The Execute and StatusQuery
sub-routines should also run, because the attachments are fully
defined.

If streams had not already been attached to the nozzles on the

Connections page, the StatusQuery would have prompted you to
provide sufficient attachments and information for the Execute
to run successfully.

6-19
6-20 Dehumidifier Example

The PFD for the solved case, along with an attached stream
table, is shown in the figure below:

Figure 6.13

6-20
 Customization FAQ A-1

A Customization FAQ

A.1 Automation FAQ............................................................................. 2

A.2 Extensibility FAQ.......................................................................... 10

A.2.1 General Extensibility............................................................... 10
A.2.2 Unit Operation Extensions ....................................................... 13
A.2.3 Kinetic Reaction Extensions ..................................................... 32

A-1
A-2 Automation FAQ

A.1 Automation FAQ

1. Whenever I change the Basis using Automation, UniSim
Design displays a view “Do you want to be left in HOLDING
mode...” which freezes the Automation application (Visual
Basic, Excel, etc.). How do I make changes and avoid the
view?
Ans: When changing the Basis via Automation, use the
following syntax:

hyCase.Solver.CanSolve = False
hyCase.BasisManager.StartBasisChange
{make Basis changes}
hyCase.BasisManager.EndBasisChange
hyCase.Solver.CanSolve = True

Where hyCase is a SimulationCase object. This will prevent

the view from appearing by putting the simulation into hold
mode before making the Basis changes and taking the
simulation out of hold mode once the Basis changes are
complete.
2. How do I add a property package to UniSim Design or
change the existing property package using Automation?
Ans: UniSim Design property packages must be referred to
by their internal name when using Automation. A list of the
name is below:

External UniSim Design Property

Internal Name
Package Name
PengRob PR
SRK SRK
SourPR Sour PR
SourSRK Sour SRK
KDSRK Kabadi Danner
ZJRK Zudkevitch Joffee
PRSV PRSV
Wilson Wilson
Uniquac UNIQUAC
Nrtl NRTL
VanLaar van Laar

A-2
 Customization FAQ A-3

External UniSim Design Property

Internal Name
Package Name
Margules Margules
CNull Chien Null
ExtNRTL Extended NRTL
GenNRTL General NRTL
CS Chao Seader
GSD Grayson Streed
Antoine Antoine
BraunK10 BraunK10
EssoTabular Esso K
AsmeSteamPkg ASME Steam
Steam84Pkg NBS Steam
Amine Amine
TabularPkg Tabular Package
LKP Lee-Kesler Plocker

The text below is a UniSim Design macro which

demonstrates the above.

Sub Main
Set hyApp = Application
Set hyCase =
hyApp.SimulationCases.Add("C:\Temp.USC")
Set hyBasis = hyCase.BasisManager
Set hyFldPkgs = hyBasis.FluidPackages
Set hyFldPkg = hyFldPkgs.Item(0)
Set hyPropPkg = hyFldpkg.PropertyPackage
hyFldPkgs.Add "Steam"
Set hyFldPkg = hyFldPkgs.Item("Steam")
hyFldPkg.PropertyPackageName = "asme steam"
End Sub

3. How do I use Automation to attach multiple feed and product

streams to unit operations which can accept them (such as
the tee, balance, separator, etc.)?
Ans: The Add method of the Feeds property is used to add
multiple feed streams to a unit operation object one at a
time.

A-3
A-4 Automation FAQ

For example, if hyMix refers to a Mixer unit operation object

and hyFeed1 and hyFeed2 refer to material stream objects,
the following syntax would add the material streams as
feeds to the mixer.

hyMix.Feeds.Add hyFeed1
hyMix.Feeds.Add hyFeed2

The same is true for the Products property of unit operations

which can have multiple products. For example,

hyMix.Products.Add hyProduct1
hyMix.Products.Add hyProduct2

The following code is a UniSim Design macro which

demonstrates the above.

Sub Main
' This macro assume an active sheet which has the
following Streams: Feed1, Feed2, Product
Set hyCase = ActiveCase
Set hyFS = hyCase.Flowsheet
Set hyOpers = hyFS.Operations
Set hyFeed1 = hyFS.MaterialStreams("Feed1")
Set hyFeed2 = hyFS.MaterialStreams("Feed2")
Set hyProduct = hyFS.MaterialStreams("Product")
' Add a Mixer named Mix-100
hyOpers.Add ("Mix-100", "MixerOp")
' Set an Object reference To the Mixer
Set hyMix = hyOpers.Item("Mix-100")
' **Add feed Streams To the Mix-100 (must be added
one at a Time, can’t use an Array of Streams)
hyMix.Feeds.Add hyFeed1
hyMix.Feeds.Add hyFeed2
hyMix.Product = hyProduct
End Sub

A-4
 Customization FAQ A-5

4. How do I use Automation to refer to a stream name which is

a number?
Ans: UniSim Design assumes any variable which contains a
number (regardless of whether it is text or numeric format)
is an index number. For example,

Stream_Name = "2"
hyStream = Streams.Item(Stream_Name)

hyStream refers to the stream object with an index

number of 1, not the stream named 1. An index number is
used to identify the order in which a stream was added. Thus
in the above examples hyStream refers to the second
stream added to the flowsheet, regardless of its name.
To be able to use numeric stream names, the following
syntax must be used:

Stream = Streams.Item(CStr(Stream_Name))

CStr converts whatever is in the parentheses in to a string,

regardless of its original format. Therefore, a 1 is interpreted
as a “1” and Feed is interpreted as “Feed”.
5. How do I obtain a viscosity (or WatsonK or surface tension or
any number of other physical properties) from a Fluid
object?
Ans: A viscosity cannot be obtained from the Fluid object, it
must be obtained from the FluidPhase objects within the
Fluid object (FluidPhases, VapourPhase, LightLiquidPhase,
HeavyLiquidPhase). For example, if there is a heavy liquid
phase then to obtain the viscosity (in UniSim Design internal
units of cP), the following syntax is used:

hyViscosity = hyFluid.HeavyLiquidPhase.ViscosityValue

where:

hyFluid = a Fluid object

A-5
A-6 Automation FAQ

6. How do I obtain component mass/molar/volume fractions

from a Fluid object?
Ans: Unfortunately, the Fluid object differs from the
ProcessStream object with regards to accessing component
mass/molar/volume fractions. The following table shows the
property object which is used to access the different types of
component fractions from the Fluid and ProcessStream
objects.

Object Fluid ProcessStream

Mass MassFractions ComponentMassFraction
Molar MolarFractions ComponentMolarFraction
Volume IdealLiquidVolumeFractions ComponentVolumeFraction

7. Why can’t I use the Calculate or CalculateAsFluid methods to

set a value as Calculated?
Ans: The Calculate and CalculateAsFluid methods can only
be used in the Execute function of an extension unit
operation.
8. Can I access the UniSim Design Optimizer using
Automation?
Ans: Unfortunately, the UniSim Design Optimizer is not
currently available to Automation. However, there is a
workaround, which uses the SendKeys command. SendKeys
is used to send keystrokes to an application as if they were
typed at the keyboard. There are a few caveats:
• UniSim Design must be visible to use the SendKeys
command.
• UniSim Design must be the active view to use the
SendKeys command, SendKeys does not wait between
keystrokes, so if an application does not respond quickly
enough, then SendKeys will fail. To reduce the possibility
of SendKeys failing, a Windows “Sleep” function is used
to add a 0.1 second pause between each keystroke.
• Since there is currently no way to determine when the
UniSim Design Optimizer has completed its calculations,
the Windows “Sleep” function is used to wait a specified
number of seconds for the UniSim Design optimizer to
solve. After this period of time, a user-defined check can
be used to determine if the optimizer is complete. If not,
the “Sleep” for another period of time and check again.

A-6
 Customization FAQ A-7

9. How do I determine if an object reference actually points to

an object?
Ans: When an object reference is made, the reference may
point to an object which does not exist. For example, when
using the UniSim Design Macro Language Editor, the
ActiveCase object is an object reference to the currently
open case. If no case is currently open, then the ActiveCase
reference points to nothing. Use the Is keyword to compare
the object reference to Nothing. The following code
demonstrates this:

Set hyCase = ActiveCase

If hyCase Is Nothing Then
MsgBox "No UniSim Design Case Is Open."
End If

10. How does UniSim Design represent empty or null values

internally?
Ans: UniSim Design uses the integer -32767 to represent
empty or null values. Empty values are shown as <empty>
in UniSim Design. For example, if Automation is used to
access the temperature of a process stream on which a
temperature has not been specified, a value of -32767 is
returned.
11. How do I use UniSim Design Macro Language (WWB) files?
Ans: In the UniSim Design desktop, select Macro Language
Editor command from the Tools menu. The UniSim Design
Macro Language Editor view appears. Right-click anywhere
on the Macro Language Editor view, and select File | Open
command from the Object Inspect menu. In the Open view,
select the UniSim Design Macro Language (*.WWB) file to
open.
12. How do I access column specification values?
Ans: The column unit operation is special in that it has its
own flowsheet. The flowsheet is where most information
about the column is stored, so it must be used as the access
the column specifications. Access the column flowsheet as
shown below (hyCase is an object reference to the

A-7
A-8 Automation FAQ

simulation case, and A-100 is the column name):

Set hyCol = hyCase.Flowsheet.Operations.Item("A-

100").ColumnFlowsheet

Now directly access the column specifications by name:

hyCol.Specifications("EtOH OH Mass Frac").GoalValue =

0.001
hyCol.Specifications("MeOH Btms Mass Frac").GoalValue
= 0.001

13. How do I access a SpreadSheet unit operation via

Automation?
Ans: Use the following syntax:

Set SS = hyCase.Flowsheet.Operations.Item("SSName")
A1Value = SS.Cell("A1").CellValue

Where, hyCase is a reference to the current UniSim Design

simulation case, SSName is the name of the spreadsheet
being referenced in UniSim Design, and SS is an object
reference to the spreadsheet. The second line uses the SS
object reference to set the value of the variable A1Value
equal to the value of cell A1 in the referenced spreadsheet.
14. Can I access UniSim Design utilities via Automation?
Ans: Currently the UniSim Design utilities cannot be
accessed directly through Automation. However, the utilities
(and most other objects in UniSim Design) can be accessed
indirectly by the SpeadSheet unit operation. Simply attach
the utility inputs and results to the SpreadSheet and access
the SpreadSheet via Automation as shown in #13.
15. How can I determine if UniSim Design is already running?
Ans: The following code demonstrates how the GetObject
function can be used to determine if UniSim Design is
currently running:

Set hyApp = GetObject(, "UniSim Design.Application")

A-8
 Customization FAQ A-9

If UniSim Design is not running, then the above line

generates error number 429 in Office 97 and 483 in Office
95. Error trapping can be used to catch the error and
determine if UniSim Design is running. For example:

On Error GoTo ErrorTrap

Set hyApp = GetObject(, "UniSimDesign.Application")
'{Code here which will be executed only If UniSim
Design Is running}
Exit Sub
ErrorTrap:
If Err.Number = 429 Or Err.Number = 483 Then
MsgBox "UniSim Design Is Not currently running,
please start UniSim Design."
Else
MsgBox "The following Error occurred: " &
Err.Description
End If

16. How do I make UniSim Design visible when accessing it via

Automation?
Ans: By default, when UniSim Design or a UniSim Design
simulation case is opened using Automation, it is a hidden
process, with only the UniSim Design splash screen
indicating that UniSim Design is running. The Visible Boolean
property, available in both the Application and
SimulationCase objects is used to make UniSim Design
visible to the user.
For example,

hyCase.Visible = True

where:

hyCase = an object reference to UniSim Design or a

UniSim Design simulation case.

A-9
A-10 Extensibility FAQ

A.2 Extensibility FAQ

A.2.1 General Extensibility
1. What is the difference between registering the EDF instead
of the DLL?
Ans: Registering the EDF allows you to interactively run and
debug the extension using Visual Basic. However, a warning
message will appear since no DLL was registered. If you
want to interactively run and debug the reaction extension,
use the following sequence:
a. Register the EDF file. This displays a warning message
which you can ignore.
b. Click the Run button in Visual Basic. This brings up the
debug view.
c. Load UniSim Design and add a reaction.
If everything is working properly, your reaction extension
will appear in the list. During this time, you can switch to
Visual Basic and add breakpoints to check variable values,
debug, etc. Once you are complete with debugging and want
the reaction extension to be available, use the following
sequence:
a. Compile the reaction extension into a DLL.
b. Register the DLL file.
c. Load UniSim Design and add a reaction. If everything is
working properly, your reaction extension will appear in
the list.
2. How can I interactively run an extension?
Ans: Use the following procedure:
a. Register the extension definition file (EDF).
b. Load the extension Visual Basic project (VBP) file, select
Project command from the View menu and double-click
on the class module (the file will have the *.cls suffix).
c. Right-click on an appropriate line of code and select
Toggle command - Breakpoint sub-command from the
Object Inspect menu. The line turns red, indicating a
breakpoint at which the execution of the code will be
paused.

A-10
 Customization FAQ A-11

d. Click the Start icon on the Visual Basic toolbar. The

Debug view appears.
e. Load a UniSim Design simulation case and install the
Start icon extension by, pressing F12 (to open the UnitOps view)
and double-clicking on name of the extension in the
Available Unit Operations list.
UniSim Design calls the f. Select extension attachments and parameters as
extension three times
(one Forgetting pass and
appropriate to make the extension calculate. When Visual
two Execute passes). Basic reaches the breakpoint in the extension, it will move
UniSim Design is inactive in front of UniSim Design. The code will be paused at the
while the extension is breakpoint. You can step through the code line-by-line
being stepped through.
interactively while the extension is running. Use the F8
key to step through the code line-by-line and F5 to stop
stepping through the code and run the remainder non-
interactively. While stepping through the code you can
interactively view and set values in the Debug view.
For example, typing ?StreamName.TemperatureValue
and pressing ENTER will return the temperature of the
stream named StreamName in UniSim Design internal
units (°C).
3. How do I reference streams and variables in the EDF?
Ans: Use the FindVariable method of the Container object.
For example, the following code makes an object reference
to the stream object with the Tag name “Feed” in the EDF.

Set hyFeed =
hyContainer.FindVariable("Feed").Variable.Object

The following code makes an object reference to the real

value object with the tag name “PrdTmp” in the EDF.

Set hyProdTemp =
hyContainer.FindVariable("PrdTmp").Variable

4. When using FindVariable to set an object reference to an

object in the EDF, when do I use .Variable and when do I use
.Variable.object?
Ans: .Variable is used to access the value of variables in the
EDF, such as numeric entry widgets, radio buttons, and so
forth. .Variable.object is used to reference an object directly

A-11
A-12 Extensibility FAQ

so that the extension is able to access the object properties

and methods. Typically, .Variable is only used for EDF
variables and .Variable.object is only used for process
stream attachments.
5. How do I determine if an object reference actually points to
an object?
Ans: When an object reference is made, the reference may
point to an object which does not exist. For example, when
FindVariable is used to set an object reference to an object
in the EDF. If there is no object (for example, when a feed
stream has not been attached), then the reference points to
nothing. Use the Is keyword to compare the object
reference to Nothing. The following code demonstrates this:

Set hyFeed = hyContainer.FindVariable("FeedStream")

.Variable.Object
If hyFeed Is Nothing Then Exit Sub

A-12
 Customization FAQ A-13

A.2.2 Unit Operation

Extensions
1. What is the Container for a unit operation extension?
Ans: The ExtnUnitOperationContainer is the Container object
for unit operation extensions. It contains the properties and
methods which are available to them. You can view this
object with an object browser (such as is contained in Visual
Basic) or you can read the extension help file
(xUniSimDesign.chm) which is installed in the UniSim Design
directory when the extension SDK is installed.
2. What is the calculation sequence for an extension?
Ans: When a change is made to a variable which affects the
extension, UniSim Design performs a Forgetting pass and
two Calculation passes. The Forgetting pass is used to
identify the streams, unit operations, etc. affected by the
change. The first Calculation pass is used to allow the
extension to complete its internal calculations. The second
Calculation pass is made so that external references made
by the extension use correct values. If the extension makes
no external references, then the second pass can be
bypassed using the SolveComplete method of the Container
object.
3. How do I prevent the second Calculation pass?
Ans: Add the following near or at the end of the Execute
code.

hyContainer.SolveComplete

where:

hyContainer = an object reference to the Container object

made in the Initialize function

This method of the Container object prevents the second

Calculation pass from occurring. SolveComplete should only
be used when the extension does not make an external
reference to a product stream. If the extension makes no
external references, then it is recommended that this line be
included to increase efficiency and prevent other calculation

A-13
A-14 Extensibility FAQ

problems.
4. How do I set default values for numeric input or text boxes?
Ans: Use the following procedure:
Make object references to the numeric input boxes in the
Initialize function and then set their defaults using the Value
property. For example,

Set hyContainer = Container

Set hyEff = hyContainer.FindVariable("Eff").Variable
If IsRecalling = False Then hyEff.Value = ".50"

The first line sets an object reference to the container calling

the extension unit operation. The second line sets hyEff as
an object reference to the eff real number variable in the
EDF. The Eff variable is the target moniker of a numeric input
widget. The third line determines if the unit operation is
being recalled from a saved case. If not, then the Value
property of hyEff is set to 0.50.
5. How do I create an “Ignore This Unit Operation During
Calculations” checkbox?
Ans: Use the following procedure:
a. Add a standard checkbox to the extension view.
b. Double-click on the checkbox or right-click and select
Check Box Properties command.
c. Double-click the Target Moniker field or click the
Ellipsis icon directly beside it.
Ellipsis icon d. Select Object is Ignored in Calculations from the
Select Number Variable view.
e. Change the text in the Label field to &Ignore Unit
Operation.
6. How do I create a Delete button?
Ans: Use the following procedure:
a. Add a standard button to the extension view.
b. Double-click on the button widget or right-click and select
Button Properties command from the Object Inspect
menu.
c. Double-click the Message field or click the Ellipsis icon
Ellipsis icon
directly beside it.

A-14
 Customization FAQ A-15

d. Click the Insert button.

e. Select Delete Object from the list and click the OK
buttons on the Select Message view and Edit Message
view.
f. Change the text in the Label field to &Delete.
7. How do I add Radio Buttons?
Ans: Use the following procedure:
a. Go to the Views Manager view and click the Object
Manager icon beside the Selected Objects drop-down
Objects Manager icon
list.
b. In the Variables of Selected Object matrix, type the
Tag name in the Tag column, enter the name in the Name
column, and select Real Number in the Type column. For
example:

Tag Name Type

List List Real Number

c. Check the Persistent checkbox and the Triggers Solve

checkbox, select None in the N Dimensions drop-down
list and select Index in the Numeric Type drop-down list.
d. Close the Object Manager view and open the form by
double-clicking on it in the Existing Views list.
e. Add a Radio Buttons widget and open the Radio Button
Properties view by double-clicking on the widget. Double-
Ellipsis icon click the Target Moniker field or click the Ellipsis icon
beside it to open the Select Number Variable view. Select
the Real Number tag created in the Objects Manager
view and click the OK button.
f. In the matrix at the bottom of the Radio Buttons
Properties view, add Labels for the Radio Buttons, the
value sent to the extension when the Radio Button is
selected, the X, Y and width of the Radio Button and its
placement (justification).
g. Save the *.edf file.

A-15
A-16 Extensibility FAQ

h. In the extension code, use the value of the enumeration

as appropriate:

Code Description
Dim hyRef as Object Dimension hyRef as an
object in the declaration
section.
Set hyRef = Use hyRef to set a reference
hyContainer.FindVariable("Ref").Variable to the Status object in the
extension definition file
(EDF).
Set hyRef = The Initialization function
hyContainer.FindVariable("Ref").Variable in the extension code is
used to set the default value
If IsRecalling = False Then for the Radio Buttons.
hyRef.Value = 0

IsRecalling is only false when the extension is first added to

the simulation, so that is when the default value of hyRef is
set to 0, which corresponds to a Radio Button value.
8. How do I add status text and status colour?
Ans: Use the following procedure:
a. Go to the Views Manager view and click the Objects
Manager icon beside the Selected Objects drop-down
Objects Manager icon
list.
b. In the Variables of Selected Object matrix, type the Tag
name in the Tag column, enter the name in the Name
column, and select Real Number in the Type column. For
example,

Tag Name Type

Status Status Real Number

Make sure the Persistent checkbox is checked, that None is

selected in the N Dimensions drop-down list, and that Index
is selected in the Numeric Type drop-down list.
c. Close the Object Manager view and open the form by
double-clicking on it in the Existing Views list.
d. Add Static Text objects of the exact same size in the
exact same place on the bottom of the form (this can be
easily accomplished using the Position and Size matrix).
Give them appropriate Names (such as OK and Error),
Background Colours (yellow for informative text, green
for converging and converged and red for errors) and

A-16
 Customization FAQ A-17

Fixed Text (such as OK and Error). Check the Framed

checkbox for each. Make sure the Enable Moniker field is
empty.
e. Create a Visibility Controller to view the Static Text
objects:
i. Right-click on the form and select Open Visibility
Manager command from the Object Inspect menu.
ii. Click on the Create Controller button and then click the
Edit button.
iii. On the Visibility Controller Properties view, enter Status in
the Name field.
iv. Double-click the Moniker field or click the Ellipsis icon
directly beside it.
Ellipsis icon v. Select Status from the list (the object variable added
earlier), and click the OK button.
vi. Type the Static Text object Labels in the Name column of
the States matrix.
vii. Type in the same value for both the Low and High columns.

Name Low High

OK 0.0 0.0
Error 1.0 1.0

viii. This value determines which Static Text object will be

displayed.
ix. Click the Select Widgets button. The names of the objects
on the form appear in the first column and the names of the
States added to the earlier matrix appear in the first row.
For the Static Text objects added earlier named OK and
Error, check the Controlled checkbox in the second column.
For the OK Static Text object, check the checkbox in the
column entitled OK. For the Error Static Text object, check
the checkbox in the column entitled Error. For example,

Controlled OK Error
OK X X
Error X X

x. Click the OK buttons to close the Visibility Controller Widget

Selections view and the Visibility Controller Properties view.
xi. The Visibility Controller for the Status is now shown on the
Visibility Manager view. Clicking on one of the radio buttons

A-17
A-18 Extensibility FAQ

displays the appropriate text.

xii. In the extension code to set the value of Status as
appropriate:
f. Dimension hyStatus as an object in the declaration
section. For example:

Dim hyStatus as Object

g. Use hyStatus to set a reference to the Status object in the

extension definition file (EDF). For example:

Set hyStatus =
hyContainer.FindVariable("Status").Variable

h. Set the value of hyStatus as appropriate to show the

appropriate Static Text object. The message which will be
shown based on the value that was determined in step
#ix.
9. How do I add a drop-down (enumeration) list?
Ans: Use the following procedure:
a. Go to the Views Manager view and press the Objects
Manager icon beside the Selected Objects drop-down
Objects Manager icon
list.
b. In the Variables of Selected Object matrix, type the Tag
name in the Tag column, enter the name in the Name
column, and choose Enumeration in the Type column.
For example,

Tag Name Type

List List Enumeration

c. Check the Persistent checkbox and select the dimension

in the N Dimensions drop-down list (none is for a single
selection, vector is for an array of selections).
d. Click the Enumeration Values button and type in the label
(the text that will appear in the drop-down list) and the
value (the value which will be used in the unit operation
extension when an enumeration is chosen from the list).
e. Close the Object Manager view and open the form by
double-clicking on it in the Existing Views list.

A-18
 Customization FAQ A-19

f. Add an Enumeration widget. Double-click on the Target

Moniker field or click the Ellipsis icon beside it and select
the enumeration tag created in the Objects Manager. The
Ellipsis icon number of entries in the drop-down list, the order in
which they appear, and how they are matched can also be
set here.
g. Save the *.edf file.
h. In the extension code, use the value of the enumeration
as appropriate:

Code Description
Dim hyList as Object Dimension hyList as an
object in the declaration
section.
Set hyList = Use hyList to set a reference
hyContainer.FindVariable("List").Variable to the Status object in the
extension definition file
(EDF).

10. How do I force the simulation to solve?

Ans: Add a new sub-procedure named VariableChanged to
the unit operation extension class module. This procedure is
called whenever a variable in the extension is changed. An
InternalVariableWrapper object is passed to it as an
argument. This object is used to identify the name of the
variable and take an appropriate action, such as triggering a
solve. For example,

Public Sub VariableChanged(ByVal VariableName As

InternalVariableWrapper)
If VariableName.Tag = "Name" Then
hyContainer.TriggerSolver
End Sub

If the Tag property of the VarableName object is equal to

NAME then the hyContainer object uses the TriggerSolve
method to triggers a solve. NAME is the name of the
enumeration widget (or any other widget) in the EDF file.

A-19
A-20 Extensibility FAQ

hyContainer is an object referenced to the Container object

which is made in the Function Initialize section of the class
module. For example,

Public Function Initialize(ByVal Container As Object,

ByVal IsRecalling As Boolean) As Long
Initialize = extnCurrentVersion
Set hyContainer = Container
End Function

11. How do I add a single-column Matrix which lists one type of

information (for example, Component names)?
Ans: Use the following procedure:
a. Open the UniSim Design extension view editor with the
extension definition file (EDF) to be modified.
b. Go to the Views Manager view and click the Objects
Manager icon beside the Selected Objects drop-down
Objects Manager icon list.
c. In the Variables of Selected Object matrix, enter the
following in the Tag, Name and Type columns.

Tag Name Type Triggers N Numeric

Persistent Solve Dimensions Type
ComponentNames ComponentNames Text Checked Unchecked Vector N/A
MatrixData MatrixData Real Checked Checked Matrix Index

ComponentNames is the Text object used to put the

component names in the matrix column row and column
header. MatrixData is the Real Number object used to hold
the matrix data.

Tag Name which is used to access the object from Visual

Basic.
Name Alternate name used in the extension view editor (used
to be more descriptive).
Type The object type.
Persistent Stores object values with the UniSim Design simulation
case.
Triggers Solve Will a change in the object force a solve.
Numeric Type The type of real number. Index is used for unitless
numbers. This only applies to objects of the Real
Number type.

A-20
 Customization FAQ A-21

d. Close the Object Manager view and open the extension

view by double-clicking on it in the Existing Views list.
e. Add a Matrix widget by right-dragging from the Widgets
Palette. View the Matrix properties by double-clicking on
it.
i. Vertical Direction and Sticky Last Entry should be
unchecked. Multi-Selectable should be checked.
ii. In the Labels group, the first drop-down list should be
Column, the Show Units drop-down list should be None
and the Left Width field should be 0.
iii. In the Cells group, the Width field should be 50, the Height
field should be 9, the Wrap field should be empty, the
Grids drop-down list should be Both and the Enter
Motion drop-down list should be None (this determines
how the selected cell moves on the matrix when the user
presses ENTER).
iv. The Target Widget drop-down list should be set to
<Self>.
f. Double-click on MatrixDataSet1 in the Data Sets list or
select MatrixDataSet1 and click the Edit button.
i. Double-click on the Moniker field or press the Ellipsis icon
and select ComponentNames from the Select Number
Variable view.
Ellipsis icon
ii. In the Label group, select the Fixed radio button and type
ComponentNames in the field below the radio buttons.
iii. Check the View Only checkbox (this prevent the user from
changing the values).
iv. Click the OK button to close the Data Set Properties view.
g. Click the OK button to close the Matrix Properties view.
h. Ensure that the Matrix widget is wide enough to
accommodate a scroll bar on the right side if required.
Typically, one-quarter of a column should be adequate.
i. Save the *.edf file.
Next add the following extension code:
j. Add the following to the global declarations section:

Dim hyComponentNames As InternalTextFlexVariable

Dim ComponentNames As Object

A-21
A-22 Extensibility FAQ

k. Add the following to the Execute function:

' Reference the variables ComponentNames variable In

the EDF
Set hyComponentNames =
hyContainer.FindVariable("ComponentNames").Variable
' Make an Object reference To the ComponentNames
collection Object
Set ComponentNames =
hyContainer.Flowsheet.FluidPackage.Components
' Set the size of the hyComponentNames vector using the
SetBounds method
hyComponentNames.SetBounds ComponentNames.Count, 0, 0
' Set the values of hyComponentNames equal To the
ComponentNames() vector
hyComponentNames.Values = ComponentNames.Names

12. How do I add a Component Matrix (a matrix with Component

names along the row and column headers in to the body of
which numbers can be entered)?
Ans: Use the following procedure:
a. Open the UniSim Design extension view editor with the
extension definition file (EDF) to be modified.
b. Go to the Views Manager view and press the Object
Manager icon beside the Selected Objects drop-down
Objects Manager icon list.
c. In the Variables of Selected Object matrix, enter the
following in the Tag, Name and Type columns.

Tag Name Type Triggers N Numeric

Persistent Solve Dimensions Type
ComponentNames ComponentNames Text Checked Unchecked Vector N/A
MatrixData MatrixData Real Checked Checked Matrix Index

ComponentNames is the Text object used to put the

component names in the matrix row and column header.
MatrixData is the Real Number object used to hold the
matrix data.

Tag Name which is used to access the object from Visual Basic.
Name Alternate name used in the extension view editor (used to
be more descriptive).
Type The object type.

A-22
 Customization FAQ A-23

Persistent Stores object values with the UniSim Design simulation

case.
Triggers Will a change in the object force a solve.
Solve
Numeric The type of real number. Index is used for unitless
Type numbers. This only applies to objects of the Real Number
type.

d. Close the Object Manager view and open the extension

view by double-clicking on it in the Existing Views list.
e. Add a Matrix widget by right-dragging from the Widgets
list. View the Matrix properties by double-clicking on it.
i. Vertical Direction and Sticky Last Entry should be
unchecked. Multi-Selectable should be checked.
ii. In the Labels group, the first drop-down list should be
Both, the Show Units drop-down list should be None and
the Left Width field should be 45 (a good width for typical
Ellipsis icon component names). Double-click on the Moniker field or
click the Ellipsis icon and select ComponentNames from
the Select Text Variable view.
iii. In the Cells group, the Width field should be 40, the Height
field should be 9, the Wrap field should be empty, the Grids
drop-down list should be Both and the Enter Motion drop-
down list should be None (this determines how the
selected cell moves on the matrix when the user presses
ENTER).

iv. The Target Widget drop-down list should be set to <Self>.

f. Double-click on MatrixDataSet1 in the Data Sets list or
select MatrixDataSet1 and click the Edit button.
i. Double-click on the Moniker field or click the Ellipsis icon.
Select MatrixData from the Select Number Variable view
and click the OK button.
Ellipsis icon
ii. In the Label group, select the Moniker radio button and
double-click in the field or click the Ellipsis icon. Select
ComponentNames from the Select Text Variable view and
click the OK button.
iii. Select the number format desired by double-clicking the
Format field or clicking the Ellipsis icon. Typically 0.5
fixed is best for interaction parameters.
iv. Enter the text used when a cell is empty in the matrix in the
Empty Text field. <empty> is the UniSim Design
standard.
v. Enter the text used when a cell is uneditable in the Matrix in
the Hidden Text field. --- is the UniSim Design standard,

A-23
A-24 Extensibility FAQ

though the default value listed is ***.

vi. In the Units group, the Auto radio button should be
selected, Shows Units in Cell should be unchecked and
Hide Units in Label should be unchecked.
vii. Click the OK button to close the Data Set Properties view.
g. Click the OK button to close the Matrix Properties view.
h. Save the *.edf file.
Next add the following extension code:
i. Add the following to the global declarations section:

Dim ComponentNames As InternalTextFlexVariable

Dim MatrixData As InternalRealFlexVariable
Dim DummyMatrix As Variant

j. Add the following to the Initialization function:

Code
Set ComponentNames = hyContainer.FindVariable("ComponentNames").Variable
Set MatrixData = hyContainer.FindVariable("MatrixData").Variable
' IsRecalling Is only False when the extension Is first added To the
simulation.
If IsRecalling = False Then
Set hyComponents = hyContainer.Flowsheet.FluidPackage.Components
ComponentNames.SetBounds hyComponents.Count, 0, 0
ComponentNames.Values = hyComponents.Names
DummyMatrix = MatrixData.Values
ReDim DummyMatrix(hyComponents.Count, hyComponents.Count)
' This Is used To Set default values For the matrix. Note that the
diagonal Is Set To -32768, which makes it uneditable
For i = 0 To hyComponents.Count - 1
For j = 0 To hyComponents.Count - 1
If i = j Then
DummyMatrix(i, j) = -32768
Else
DummyMatrix(i, j) = 0
End If
Next j
Next i
MatrixData.SetBounds hyComponents.Count, hyComponents.Count, 0
MatrixData.Values = DummyMatrix
End If

A-24
 Customization FAQ A-25

k. Add the following to the Execute function:

DummyMatrix = MatrixData.Values
For i = 0 To hyComponents.Count - 1
For j = 0 To hyComponents.Count - 1
if i = j Then DummyMatrix(i, j) = -32768
Next j
Next i
MatrixData.Values = DummyMatrix

13. How do I change the name of an unit operation extension in

the PFD?
Ans: A Text Entry widget must be added to the EDF file to
allow the name of the extension to be changed. Use the
following procedure:
a. Add a Static Text widget and double-click it or right-click
and select Static Text Properties command from the
Object Inspect menu.
b. Change Fixed Text to &Name. The & is used to determine
the hot key for the view. (ALT + hot key gives the focus
to this widget). The hot key is shown as underlined.
c. Add a Text Entry widget and double-click it or right-click
and select Text Entry Properties command from the
Object Inspect menu.
d. Double-click the Target Moniker field or click the
Ellipsis icon directly beside it, select Object Name from
Ellipsis icon the Select Text Variable list and click the OK button.
14. How do I set the compositions of a stream in UniSim Design?
Ans: Compositions must be set using a Variant array which
has been initialized. To initialize the array, set it equal to the
ComponentMolarFractionValue,
ComponentMassFractionValue, or
ComponentVolumeFractionValue of the stream whose
compositions are going to be changed.

A-25
A-26 Extensibility FAQ

The following code demonstrates this:

Dim Compositions As Variant

Compositions = hyFeed.ComponentVolumeFractionValue
Compositions(0) = .5
Compositions(1) = .2
Compositions(2) = .3
hyFeed.ComponentVolumeFraction.Values = Compositions

where:

hyFeed = an object reference to a material stream in

UniSim Design

15. How do I display results in the EDF?

Ans: Use the following procedure:
a. Open the UniSim Design extension view editor with the
extension definition file (EDF) to be modified.
b. Go to the Views Manager view and press the Object
Manager icon beside the Selected Objects drop-down
Objects Manager icon list.
c. In the Variables of Selected Object matrix, enter the Tag,
Name and Type of the variables which are to be displayed.
Ensure that the Persistent checkbox is checked, the
Triggers Solve checkbox is unchecked, N Dimensions
is None, and the selected Numeric Type as appropriate.
d. Add Static Text widgets to the EDF to describe the
output data. Add Numeric Input widgets beside the
appropriate description. Double-click the Numeric Input
widget or right-click and select Numeric Input
Properties command from the Object Inspect menu.
e. Check the View Only checkbox. Select the appropriate
variable in the Target Moniker field.

A-26
 Customization FAQ A-27

f. Add the following code to the extension:

hyContainer.FindVariable("EDFVariable").Variable =
ExtnVariable

where:

EDFVariable = the name of the variable in the EDF and

ExtnVariable is the name of the variable in the
extension code whose value in going to be displayed
in the EDF

17.) How do I make a button perform a calculation when

clicked?
Ans: Use the following procedure:
a. Open the UniSim Design extension view editor with the
extension definition file (EDF) to be modified.
b. Go to the Views Manager view and click the Object
Manager icon beside the Selected Objects drop-down
Objects Manager icon list.
c. In the Variables of Selected Object matrix, enter the
following:

Tag Name Type

ActionButton Action Button Message

The Triggers Solve checkbox should be checked or

unchecked as appropriate if the calculations affect the
extension.
d. Add a Button widget to the EDF. Double-click the Button
widget or right-click and select Button Properties
command from the Object Inspect menu.
e. Change the Label to &About.
f. Double-click on Message field or click on the Ellipsis
icon beside it. Click the Insert button, and select
Ellipsis icon AboutButton from the Select Message list.
g. Click the OK buttons to close the Select Message view,
Edit Message view, and Button Properties view.

A-27
A-28 Extensibility FAQ

h. Add the following Public Sub to the unit operation

extension code:

Public Sub VariableChanged(ByVal VariableName As

InternalVariableWrapper)
On Error GoTo ErrorCatch
If VariableName.Tag = "AboutButton" Then
{Enter you code here}
End If
ErrorCatch:
End Sub

When a variable is changed in the EDF, Sub VariableChanged

is executed if it is present. The Code above checks the Tag of
the variable which was changed, if the tag of the variable is
AboutButton, then the code in the braces is executed.
Custom calculation code is entered between the braces.
16. How do I automatically set the Calc Level (calculation level)
of an extension?
Ans: Add the following to the Initialize function of the
extension code:

Set hyContainer = Container

Set hyInterface = hyContainer.ExtensionInterface
hyInterface.CalcLevel = 1000

where:

Both hyContainer and hyInterface are declared as Objects

17. How do I automatically attach an existing stream to a Unit

Operation Extension when it is added to the PFD?
Ans: In the Initialize function of the extension, make an
object reference to the stream which will be attached to the
extension. Then use FindVariable to set the name of the
stream defined in the EDF equal to the stream object
reference.

A-28
 Customization FAQ A-29

The following code demonstrates this:

Dim hyFeed As Object

Set hyFeed =
hyContainer.Flowsheet.MaterialStreams("Feed")
hyContainer.FindVariable("Feed").Variable.Object =
hyFeed

18. What is a “Forget” Pass?

Ans: UniSim Design unit operations can calculate “product”
variables based on “feed” variables, “feed” variables based
on “product” variables, or a combination of the two. This can
lead to very complicated interdependency between the
variables in a flowsheet. When a variable is changed, UniSim
Design must first “forget” all of the variables that were
calculated based on the original value, and then re-calculate
based on the new value. If the values are not forgotten, an
attempt to calculate a new value is misinterpreted by UniSim
Design as an inconsistency.
To illustrate this, assume that the temperature of the inlet
stream to a unit operation is changed from 10°C to 41°C.
The following sequence occurs:
a. The stream will “forget” its temperature, as well as any
variables it calculated based on temperature (e.g., vapour
fraction, density).
b. The unit operation will get an Execute pass, with
IsForgetting = True. If the unit operation asks its inlet
stream for any of the forgotten variables it will receive
<empty> (which can be an E_FAIL error, or the value -
32767).
c. The unit operation is unable to calculate any of the
variables it had calculated based on the inlet stream’s
forgotten variables. UniSim Design causes these variables
to be forgotten as well. Their owners (e.g., the unit
operations’s outlet stream) will then receive a similar
Execute.
d. When the Forget pass has propagated through the
flowsheet, the inlet stream recalculates using the new
temperature value. An Execute pass - with IsForgetting =
False - will propagate through the flowsheet.

A-29
A-30 Extensibility FAQ

19. What should my Execute do during a Forget?

Ans: Given the above description of the purpose of the
Forget pass, it would seem to make sense for a unit
operation’s Execute to return immediately if IsForgetting =
True. All of the variables it had calculated would be
‘forgotten’ by UniSim Design, but recalculated during the
subsequent Execute. If a unit operation’s Execute performs
no calculations during the Forget pass, this is exactly what
will happen. Indeed, this is a valid method for a unit
operation. Neglecting to perform any calculations during a
forget will not cause any errors, but can cause some
inefficiency because more variables than necessary are
forgotten.
If efficiency becomes a concern, a solution may be to
calculate some variables during the Forget. Non-extension
unit operations generally calculate as much as possible
during their Forget, so as to minimize unnecessary
propagation of the Forget. As an example, consider a Cooler
operation that has the following specification:
• Inlet Pressure
• Inlet Temperature
• Pressure Drop
• Outlet Temperature
The Cooler calculates its Duty and Outlet Pressure based on
these values. If the inlet temperature is changed, the Cooler
will get a Forget, in which the inlet temperature appears
<empty>, but the inlet pressure is available. If the Cooler
does not calculate anything, the outlet Pressure will be
forgotten, and the Forget will propagate through all objects
downstream of the Cooler. If, however, the Cooler re-
calculates its outlet pressure during the Forget, the outlet
stream will remain fully calculated, and will not receive any
Execute calls. Only the Cooler’s duty will be forgotten.
It is important for any unit operation to avoid using variables
that it has previously calculated for the calculation of other
variables. In the above example, the Cooler can “see” its
outlet temperature and its duty (which it had calculated)
during its Forget. These two values can (erroneously) be
used to calculate its inlet temperature. In this case, this
would cause an inconsistency error, as the calculated value

A-30
 Customization FAQ A-31

would not match the new specified value. Often, the problem
is subtler, and results in the two values being calculated,
each thinking that the other is a specification. To avoid this,
the Cooler must check that it is not a variable’s “CalcBy”
object, before using that variable’s value to calculate other
variables.
20. Why do I get Three Execute calls?
First-time extension writers are almost always surprised to
receive a second non-Forgetting Execute call from UniSim
Design. In fact, non-Extension unit operations only receive
two Execute passes. An additional Execute is necessary for
some extensions that need to see the results of the Balance
calls they make during their Execute.
When a unit operation calculates a value to a stream’s
variable, the unit operation cannot then “see” the value until
the stream has recalculated. If the unit operation calculates
a stream’s temperature during its Execute, and needs to use
the stream’s temperature later in the Execute, it will not be
able to ask the stream for the value. When the unit
operation’s Execute knows the value (as in this case), it can
simply keep the value itself as long as it needs to.
A problem arises when the unit operation uses a “Balance”
call to calculate the compositions and flow of its streams.
The “Balance” performs all the logic to detect which values
are specified and which need to be calculated, combines
multiple feeds to produce a single product, etc., all without
the unit operation needing to be aware of the calculations.
Unfortunately, the results of these calculations will be
unavailable to the unit operation until after the streams have
had their Executes. If the unit operation wants to display,
e.g., the flow of a key component in each of its attached
streams, these values will be unavailable. However, the unit
operation will receive a third Execute, after the streams have
had theirs, during which the values “Balance” had calculated
will be available. Proper use of the third Execute for this
purpose is tricky, as the unit operation must avoid repeating
the work of the previous Execute.

A-31
A-32 Extensibility FAQ

Relatively few unit operations require the third Execute call.

If a unit operation can perform all of its calculations in the
first Execute, it should call “SolveComplete”, which will
prevent the third Execute call from being made by UniSim
Design.
21. Why is my Unit Operation’s PFD icon yellow?
Ans: UniSim Design will outline a unit operation in yellow if it
cannot complete its calculations. Usually, the unit operation
uses its StatusQuery method to provide the user with a
specific reason why the solve can not be completed, but the
“Not Solved” warning is provided by default.
To prevent this warning from being added, the unit operation
must call “SolveComplete” when it has satisfactorily
completed its calculations. This unit operation’s Execute is
responsible for determining whether it has calculated all of
the variables it wants to calculate.

A.2.3 Kinetic Reaction

Extensions
1. What is the Container for a Kinetic Reaction Extension?
Ans: The ExtnKineticReactionContainer is the Container
object for Kinetic Reaction Extensions. It contains the
properties and methods which are available to them. You can
view this object with an object browser (such as is contained
in Visual Basic) or you can read the extension help file
(xUniSimDesign.chm) which is installed in the UniSim Design
directory when the extension SDK is installed.
2. Why is the Triggers Solve checkbox greyed out in the Objects
Manager in the EDF?
Ans: For Kinetic Reaction Extensions, the Triggers Solve box
must always checked, which is why it is disabled (greyed
out).

A-32
 Customization FAQ A-33

3. How do I access the liquid phase if my reaction only occurs

in the vapour phase? If I select combined phase, then my
reaction rate changes.
Ans: UniSim Design multiplies the reaction rate, which you
pass to it, by the volume of the phase selected. This is
wherein the problem lies as UniSim Design should actually
only use the volume of the Liquid Phase instead of the
volume of the Combined Phase. Here is the workaround:

Code Description
hyContainer.Phase = ptCombinedPhase Set the Phase property to
ptCombinedPhase.
Temp = Fluid.HeavyLiquidPhase.MolarDensityValue Access the Liquid phase for your
rate calculations (make sure to
identify it as
HeavyLiquidPhase or
LightLiquidPhase).
rate = rate * (1 - Fluid.VapourFractionValue) Multiply the rate you calculate
by (1 -
Fluid.VapourFractionValue)

The corrected rate will now be used by UniSim Design.

A-33
A-34 Extensibility FAQ

A-34
 Index

A dehumidifier (user unit operation) 6-12

Extensibility
Assays 2-28
definition 1-4
Assays Collection Object 2-28
ExtensionObject Interface 3-22
Automation
ExtensionPPkgInit structure 3-43
definition 1-3
Extensions
starting a case 2-11, 2-12
creating in C++ 3-12
B creating in VB 3-8
interface 3-21
Blend(s) 2-29 kinetic reaction 3-22
C property package 3-41
registering 3-17
CLSID 3-17 Unit Operations 3-47
Code Editor 5-21 ExtnContainer Interface 3-21
Collection Objects 2-15 ExtnKineticReaction Interface 3-24
ColumnFlowsheet Object 2-36 ExtnKineticReactionContainer Interface 3-25
ColumnOp Object 2-36 ExtnPPkgContainer Interface 3-44
ColumnSpecification(s) Object 2-37 ExtnPropertyPackage Interface 3-45
ColumnStage(s) Object 2-38 ExtnUnitOperation Interface 3-49
Component(s) Object 2-25 ExtnUnitOperationContainer Interface 3-48
Container Object 3-3
Container Objects 2-19 F
Count 2-15 Fixed Attachments 2-42
CreateObject 2-10 Flowsheet(s) Object 2-21
Customization 1-2 Fluid Object 2-33
D Fluid Phase Object 2-34
FluidPackage(s) Object 2-23
Data Types For Each loop 2-15
code only 5-13 For loop 2-15
enumeration 5-12 Form View 4-11, 4-34
field 5-10 object inspect menu 4-34
message 5-13
real 5-11 G
dot function 2-13 GetObject 2-10
E GetValue 2-40

EDF H
creating a new 4-5 Hypotheticals Object 2-26
Examples

I-1
I-2 Index

I S
Index 2-15 Security
Integrator 2-43 See User Variables.
Interfaces SeparationStage Object 2-38
implementing 3-5 Set 2-10
Item 2-15 SetValue 2-40
Solver 2-43
K
SpreadsheetCell(s) 2-44
Kinetic Reaction SpreadsheetOp 2-44
example 3-26 Stream Objects 2-30
extension definition files 3-22 Support Objects 2-39
M T
Macros 5-14 Tab Order 4-11
Matrix 4-48 Tabs 4-19
Methods 2-2, 2-13 Tool Tip Text 5-21
Moniker Specification 4-29 Type Library 2-4
navigating 2-6
O
U
Object
hierarchy 2-3, 2-13 Unit Operation Extension
Object Browser 2-4 example 3-51
accessing 2-5 User Unit Operation
Object Definition Matrix 4-24 adding 6-2
Objects code page 6-7
collection 2-15 dehumidifier example 6-12
declaring 2-9 sub-routines 6-9
definition 2-2 variables page 6-10
UniSim Design 2-19 User Variable
Objects Manager View 4-23 example 5-22
Oil Manager Object 2-27 User Variable Tabs 5-13
Oils Objects 2-27 User Variable View 5-8
Operation Objects 2-35 User Variables 5-2
Operations Object 2-35 buttons 5-4
filters 5-18
P security 5-19
Passes 3-49 V
calculate 3-50
Process Stream Object 2-31 Variants 2-17
ProgID 3-17 View Editor
Properties 2-2, 2-13 accessing 4-4
Property Package using 4-8
extensions 3-41 Views Manage 4-27
Property Package Object 2-24 Visibility Manager 4-16

R W
RealFlexVariable 2-40 Widgets
RealVariable 2-40 ActiveX Container 4-88

I-2
 Index I-3

aligning 4-15
attachment name 4-68
button 4-35, 4-39
format entry 4-45
level 4-81
manipulating 4-8
numerical input 4-46, 4-48
plot 4-84
properties 4-28, 4-29
rich text 4-44
static text 4-40
text entry 4-42

I-3
I-4 Index

I-4