Beruflich Dokumente
Kultur Dokumente
PRO/II 9.3
COM Server
Programmers Guide
and Tutorial
May 2014
All rights reserved. No part of this documentation shall be reproduced, stored in a retrieval
system, or transmitted by any means, electronic, mechanical, photocopying, recording, or
otherwise, without the prior written permission of Invensys Systems, Inc. No copyright or patent
liability is assumed with respect to the use of the information contained herein. Although every
precaution has been taken in the preparation of this documentation, the publisher and the author
assume no responsibility for errors or omissions. Neither is any liability assumed for damages
resulting from the use of the information contained herein.
The information in this documentation is subject to change without notice and does not represent
a commitment on the part of Invensys Systems, Inc. The software described in this documentation
is furnished under a license or nondisclosure agreement. This software may be used or copied
only in accordance with the terms of these agreements.
For comments or suggestions about the product documentation, send an e-mail message to
ProductDocumentationComments@invensys.com.
All terms mentioned in this documentation that are known to be trademarks or service marks have
been appropriately capitalized. Invensys Systems, Inc. cannot attest to the accuracy of this
information. Use of a term in this documentation should not be regarded as affecting the validity
of any trademark or service mark. Invensys, Invensys logo, PRO/II, and SimSci are trademarks of
Invensys plc, its subsidiaries and affiliates.
Table of Contents
1 Introduction ..............................................................4
1.1 Summary ................................................................................ 4
1
4.6 Perform Units-of-Measure Conversion .................................. 16
2
7.3 Calculating Stream Properties .............................................. 30
3
1 Introduction
1.1 Summary
The PRO/II COM Server provides read/write access to information in a PRO/II simulation
database from COM-aware applications and languages. You can write applications to
access data (both input and calculated) in PRO/II simulation databases using Microsoft
Excel, Microsoft Visual Basic, and C++ (using the MFC or ATL frameworks).
The PRO/II COM server also provides calculation utilities, which allow a client application
to:
Client applications can also modify information in the PRO/II simulation database and
rerun the flowsheet simulation. However, the PRO/II COM Server is not intended as a
complete replacement for using the PROVISION GUI or PRO/II keyword file to define a
complete simulation. Additional information on the effects of modifying an existing
database using the PRO/II COM Server is explained in Chapter 4 under the Modifying
information in the Database.
Introduction 4
1.3 About this Document
The purpose of this document is to provide information on using the PRO/II COM Server.
Visual Basic is a common language used for COM application development and is
included in many Microsoft products, including Excel. The examples in this document are
written primarily in Visual Basic.
Chapter 6 contains many example applications for performing common operations with
the PRO/II COM Server.
The primary reference materials for Visual Basic, Excel, and other Microsoft
Technology are the documents and reference material included with the
Microsoft products. The website msdn.microsoft.com is the primary starting
point for developers needing more information on specific Microsoft technologies.
Introduction 5
2 Hardware and Software
Requirements
To develop PRO/II COM applications a PC with an installed version of PRO/II is required.
Refer to the PRO/II Installation Guide for specific hardware and software requirements for
specific versions of PRO/II.
You will also need the appropriate development environment or development tool for
writing COM applications. This includes (but is not limited to):
Visual Basic
Visual C++
Microsoft Excel
The applications you create using the PRO/II COM Server can run on any platform that:
Supports the runtime environment required by the development tool you are
using
Some calculation features of the PRO/II COM server also require a valid PRO/II license.
Familiar with the specific development language or tool you are planning to use,
such as Visual Basic or C++
Knowing how to access and use COM objects from the chosen development
language
If the chosen development tool is Microsoft Excel, then it is helpful to be familiar with some
of the advanced features of Microsoft Excel, including:
Accessing values in spreadsheet cells using Visual Basic, the macro language of
Excel
Using the pre-defined Excel objects in Visual Basic, such as the Application,
Workbook, Worksheet, and Range objects
Refer to the on-line help for your Microsoft product. You can also visit
http://office.microsoft.com and http://msdn.microsoft.com search for "Excel Object
Model Overview") for more information.
The PRO/II COM Server provides the support for the COM interface into PRO/II.
COM applications written in Excel, Visual Basic, C++, and other COM-aware
languages interact with this interface. The COM Server is called p2oledbs.exe
and is located in the BIN directory under the PRO/II installation path
The PRO/II Server consists of the various DLLs used by PRO/II with PROVISION
for GUI and keyword support. This support includes the functions that access
and manage the PRO/II data objects. It also includes many calculation features
of PRO/II such as solving a flowsheet, calculating stream properties, and
performing flash calculations
The PRO/II Database (with extension "prz") contains the simulation data
The various client applications, which can access the PRO/II COM server, include the
following:
VB Script
Visual Basic for Application: VBA is the macro language of Microsoft Office and
certain other applications. Microsoft Office components Excel and Access would
be typical applications to use the PRO/II COM Server
C++, C#, or other COM applications: many languages provide support for access
to COM objects and methods
PRO/II Class Library: The PRO/II Class Library is another COM Server that can
be used to access information in the PRO/II Server. This server is called
p2wrap81.dll (for PRO/II 8.1). Excel macros, Visual Basic applications, and
applications written in other COM-aware languages can access the PRO/II Class
library to ultimately gain access to the PRO/II COM Server
Most simple unit operations store all their data into a data object of one class. For
example, the Mixer unit operation stores all of its data, input and calculated, into the
"Mixer" data object class. Complex unit operations and streams, however, store their data
into multiple data object classes. A stream, for example, stores its input data in the
"StreamIn" class, the calculated process conditions in the "Stream" class, and the
calculated stream properties in several additional data classes (such as the "StrBulkProp"
class). Refer to the PRO/II COM Server Reference Guide to identify the specific data
object classes containing the desired input or calculated data.
There is a common set of methods in the PRO/II COM Server to access the PRO/II data
objects. The common tasks for these data objects are as follows:
Loading ("activating") an existing data object from the database into memory
Reading and writing attribute data from and to the data object
The methods to perform these tasks are described briefly in this document and in detail in
the PRO/II COM Server Reference Guide.
Text data is divided into subcategories. Raw text data, such as the "NotesIn" attribute of
unit operations, contains simple text. Other text data is considered as a type of "identifier",
or ID type.
PRO/II uses several ID data types described in the following table. These "ID" datatypes
are used to identify text strings as being names of actual objects in the database. These
names typically have syntax limitations, such as string length, as described in the table
below.
2. Open a database
5. Save the data object back to the database (if it was modified) and free the object
These seven steps are performed using three types of objects provided by the PRO/II
COM Server as outlined below.
Server Object: This is the main server object and is used to initialize and manage
interaction with the PRO/II COM Server.
Database Object: This object is used to interact with a specific simulation database.
The PRO/II COM Server can open only one database at a time.
Data Object: Each data object is used to interact with a specific object in PRO/II:
components, thermodynamic systems, streams, and unit operations. Data are read from
and written to these objects using the GetAttribute and PutAttribute methods.
For more information on each of these objects, refer to the PRO/II COM Server Reference
Guide.
Basic Operations 12
The basic sequence of operations for an application using the PRO/II COM Server is
shown in Figure 2.
The following sections describe each of these steps in more detail. The examples are
illustrated using the Visual Basic language.
Basic Operations 13
Since multiple versions of PRO/II may coexist on the same machine, the application must
specify the exact version of the PRO/II COM Server to be used. The specific value of
"progid" depends on the version of PRO/II to be used and is outlined in table 3.
Table 3: Progid
Progid PRO/II version
SimSciDbs.Database.81 PRO/II 8.1.x
SimSciDbs.Database.80 PRO/II 8.0.x
SimSciDbs.Database.71 PRO/II 7.1.x
SimSciDbs.Database.70 PRO/II 7.0.x
SimSciDbs.Database.601 PRO/II 6.01
After the Server object has been created, it must be initialized using the Initialize method.
The simple form of this method is:
P2SRV.Initialize
The simple form will use default values of all arguments. The full form allows the
application to specify individual values for the PRO/II configuration file ("proii.ini"), the
database schema file, and the debug output file. The full form is typically used for
advanced diagnostic and debugging only.
Once the PRO/II COM Server has been created and initialized, a simulation database can
be opened.
This statement will open the PRO/II database file "R3R.prz". Note that file names must be
specified with full path.
Basic Operations 14
Only one database can be open at any given time. If the application needs to
access a second database, it must first close the one opened earlier.
Once the database has been opened, the application can then load data objects into
memory.
The first argument is the name of the data object class. The second argument is the name
of the object. The PRO/II COM Server Reference Guide lists all the object classes
available.
Once the object is in memory, its information can be accessed and modified using the
GetAttribute and PutAttribute methods.
dTemp = P2OBJ.GetAttribute("Temperature")
dFrac = P2OBJ.GetAttribute("TotalComposition", 0)
To modify data, use the PutAttribute method. This method also uses an index to specify
the element of a vector attribute. To change the value of a scalar attribute, supply a
dummy index (which will be ignored) or do not supply the index at all:
P2OBJ.PutAttribute(NewValue, "ScalarAttribute")
Basic Operations 15
To change the value of a single element of an array attributes:
(In these two examples, "ScalarAttribute" and "ArrayAttribute" are used as examples, and
do not represent actual attributes of the "Stream" object.) The available attribute names
for each object class and their data types (Real, Integer, String, Scalar, Array) are listed in
the PRO/II COM Server Reference Guide.
Please see Modifying Information in the Database section at the end of the chapter for
complexities in writing data to the database to be used in future simulations.
For example, the following code reads the stream temperature and displays it in a
message box:
The string TEMP refers to the Temperature unit of measure class. The complete list of
recognizable Unit of Measure classes is given in Appendix A of the PRO/II COM Server
Reference Guide.
P2OBJ.Commit
When the application has finished interacting with the data object, it should release the
object from memory by assigning "Nothing" to the object variable:
If the object is released without first being committed to the database, then all the
changes will be lost.
Basic Operations 16
4.8 Save and Close the Database
To save and close a database, assign the "Nothing" value to the object variable:
where P2DB is the object variable returned by the original OpenDatabase method.
At this point, all objects and database files will be released from memory and the database
will be closed.
Along with the actual input values, many of the PRO/II objects contain one or
more flags that must be properly initialized for a valid simulation file to be created
The COM server does not automatically handle inter-object side effects of
modified data. For instance, if you delete a stream, you must remove all
references to that stream from other objects
The COM Server does perform some automatic resizing of objects based on the
values of other attributes. But reducing the size of an array attribute always
discards data from the end of the array. If you want to remove entries from the
middle of an array, then you must perform the required packing operations
Normally, this complexity is hidden by the PROVISION interface and the keyword input
processing.
Basic Operations 17
5 Writing Applications in
Different Languages
This section shows how all the steps of a COM application described previously work
together to form a complete application. A sample application will be presented and its
implementation demonstrated in several programming languages.
cout<<"Fraction("<<_com_util::ConvertBSTRToString(vName.bstrVal)<<")= ";
SafeArrayGetElement(vFrac.parray, &lIndex, &vFracElement);
cout << vFracElement.dblVal << endl;
}
p2Database = "c:\SimSci\proii81\user\Applib\R3R.prz"
WScript.echo "Open database " & p2Database
set P2DB = P2SRV.OpenDatabase(p2Database)
To run a VBScript program, open a Command Prompt window and use the
"cscript.exe" program:
cscript myscript.vbs
G2_Deethanizer
G5_Expander_plant
The example excel spreadsheet that have been developed will enable the users
The steps explained below will help the users in customizing the spreadsheet.
Note: Users need to ensure that Comments Indicator Only option is checked under
View Tab of Options dialog box. (Tools/Options). Based on comments, the
information is read from the database and written into the database.
Note: The simulation database should be in the same directory as the Excel
spreadsheet in order for it to open automatically when the sheet is selected. If this is
not the case, Excel will ask for the location of a simulation with that name. Once an
alternate file location is chosen, it becomes the default file path.
Add comments to the cells by clicking Insert/Comments from the menu bar.
Edit the comment window before entering the syntax as shown below.
Note: The Unix pipe symbol or vertical bar symbol ( | ) is used as the delimiter in the
comment statement.
|Read|Write|Class|Name|Attribute|Index|UOM|Location
Where:
Syntax Description
Read Information should be read from the simulation database on file open or
read the simulation results after the simulation has converged.
Write Write cell contents (input data) to the simulation database. Write is not
relevant for simulation results, but the embedded vertical bar should be
present to maintain proper sequential order of information.
In some cases like stream object, there is an input class StreamIn to write
and read input data and there is an output class Stream to read
simulation results back from the PRO/II database.
Index Optional. Number of the element in Attribute vector if data is in the form of
an array. Most attributes have only one element (value), but some
attributes like Stream Composition have an index indicating the component
number for which the composition has to be retrieved. Index is not
relevant where the attribute is a single element, but the embedded vertical
bar should be present to maintain proper sequential order of information.
UOM Optional. Units of Measure (UOM) class to be used in converting the value
retrieved/written. See Appendix A of PRO/II COM Server Reference Guide
for Units of Measure Class codes. For example, the UOM for temperature
is TEMP.
Location Optional. If present, the printable version of the UOM will be displayed in a
cell relative to the one the comment belongs to. For example, if the location
value is C1, the UOM (E.g. C for Temperature in English Units) will be
placed one cell to the right of the cell with the comment and if the location
value is C-1, then the UOM will be placed one cell to the left of the cell with
the comment.
Examples:
|Read|Write|StreamIn|100|Composition|0
The above syntax indicates will read and write the first (0) component from the
composition of object StreamIn named 100.
|Read||Expander|X1|WorkActualCalc||WORK|C2
Reads the actual work parameter from the X1 expander. Convert the retrieved value using
UOM class WORK and display the printed version of the UOM (e.g. HP) two cells towards
the right of the current cell with the comment.
|Read|Write|Spec|COL1SPEC1|SpecValue
Both read and write the spec value for spec COL1SPEC1.
It is possible to nest this syntax. For example, this is useful when retrieving the name of a
specification from a column. Subsequently, use the name and retrieve or write a value.
From column T1, read the name of the spec object in the Spec Class corresponding to the
column T1 specification. Subsequently, use this name to retrieve and write the value from
this object.
|Read|Write|Define|(|Read||Compressor|C1|DefineData)|RefValue
From compressor C1, read the name of the define object. Subsequently, use this name to
retrieve and write the reference value from this object.
Figure 4. Properties
If the value for an attribute is retrieved as Zero from the PRO/II database while it is
not the desired value, then the attribute name is incorrect. Check the spelling for the
attribute name carefully.
If database operations such as Read, Write are not working properly, then carefully
check for syntax and spelling mistakes.
The COM Server would automatically shut down when an error is encountered in the
information provided. In such cases the error should be rectified and the operator
interface application should be re-opened.
dTemp = P2OBJ.GetAttribute("Temperature")
dPres = P2OBJ.GetAttribute("Pressure")
dRate = P2OBJ.GetAttribute("TotalMolarRate")
MsgBox "Temperature = " & dTemp2 & " " & uomT, vbOKOnly, "Temperature"
MsgBox "Pressure = " & dPres2 & " " & uomP, vbOKOnly, "Pressure"
MsgBox "Flowrate = " & dRate2 & " " & uomR, vbOKOnly, "Flowrate"
Composition Compositions of the overall stream; the liquid and vapor phases are
stored in the Stream object class.
Refinery Common refinery properties such as TVP and RVP are calculated for the
Properties various phases and stored in the SrBulkProp object class.
Refinery Will only be calculated if the appropriate methods have been selected in
Inspection the thermodynamic data section. Only then will these properties be
Properties calculated for the bulk phase and stored in the SrRefProp object class.
When PRO/II solves a flowsheet, it uses the information in the StreamIn class and
process flowsheet conditions to calculate and store the attributes of the "Stream" class.
The data for the other classes is not automatically calculated for reasons of efficiency.
That information must be calculated and stored by calling the CalculateStreamProps
method.
To determine if the stream properties have been calculated, check to see if the
"SrBulkProp" object exists. If not, then call CalculateStreamProps. The following
example code demonstrates the procedure:
Some stream properties are not directly available as individual attributes in the
database, but they can be calculated from attributes that are available. For instance, to
calculate the total mass flowrate of a stream:
Set P2STREAM = P2DB.ActivateObject("Stream","1")
Set P2BULK = P2DB.ActivateObject("SrBulkProp","1")
MoleRate = P2STREAM.GetAttribute("TotalMolarRate")
InertRate = P2STREAM.GetAttribute("InertWeightRate")
MolecWt = P2BULK.GetAttribute("BulkMwOfPhase")
TotalWtRate = MoleRate * MolecWt + InertRate
Set P2STREAM = Nothing
Set P2BULK = Nothing
For a list of the specific attributes available in each stream class, consult the PRO/II Com
Server Reference Guide.
TrayProp object
Refer to the PRO/II Com Server Reference Guide or a list of supported properties.
CopyTrayToStream method
P2SRV.GetSecuritySeat (2)
Dim P2OBJ1 As Object
Dim P2OBJ2 As Object
Dim retCode As Boolean
For i% = 1 To nTrays
retCode = P2DB.CopyTrayToStream( _"COL1", i%, 0, 0, 1, tmpStream$)
retCode = P2DB.CalculateStreamProps(tmpStream$)
Set P2OBJ1 = P2DB.ActivateObject("Stream", tmpStream$)
Set P2OBJ2 = P2DB.ActivateObject("SrBulkProp", tmpStream$)
dTemp = P2OBJ1.GetAttribute("Temperature")
dTotRate = P2OBJ1.GetAttribute("TotalMolarRate")
dLDens = P2OBJ2.GetAttribute("LiqDensityAct")
dVDens = P2OBJ2.GetAttribute("VapDensityAct")
Set P2OBJ1 = Nothing
Set P2OBJ2 = Nothing
Next
P2SRV.ReleaseSecuritySeat
2. Modify the PRO/II initialization file (proii.ini) to add the new macro into the menu
selections
3. Start the PRO/II COM Server and initialize it using the information from INIFile
4. Open the simulation database file specified by the PRO/II PROVISION GUI and
requested in step 2 using "TempDbFile"
5. Activate an object
10. Notify the PRO/II PROVISION GUI that the spreadsheet macro has completed its
operations. To do this, use the DDERequest command to send the IAmDone
message. This message tells the PRO/II GUI that it can reopen the temporary
database
11. Use Visual Basics command DDETerminate to close the DDE channel
Steps 1, 2, 10, and 11 are the additional tasks that must be performed.
Before the spreadsheet macro is invoked from the PRO/II GUI, PRO/II closes the
temporary database to allow the spreadsheet macro read/write access to the data. When
the spreadsheet macro is complete, it must notify the PRO/II PROVISION GUI that its
operations are complete and that PRO/II can safely reopen the temporary database. This
is done by sending the DDE command IAmDone to the PRO/II PROVISION GUI.
Sub ShowStream()
' Open up a DDE channel to PRO/II to get information
iChannel = Application.DDEInitiate("PVISION", "PFDInfo")
If IsError(iChannel) Then
Exit Sub
End If
' Data from a DDE Request comes back as an array and must
' be put into a Variant variable.
' Get the name of the initialization file.
DDEData = Application.DDERequest(iChannel, "INIFile")
sINIFile = ""
If Not IsError(DDEData) Then
sINIFile = DDEData(1)
End If
After the spreadsheet macro has been modified, it can be added as a menu option into the
PRO/II PROVISION interface. To do so, modify the PRO/II initialization file "proii.ini":
1. Start up an ASCII editor (Notepad, PFE, or WordPad) and open the initialization
file (proii.ini)
2. Locate the [Spreadsheet] section, update the Number= parameter, and add a
new snnn= line to the section:
[Spreadsheet]
Number=4
s000=...
s001=...
s002=...
Where:
snnn is the spreadsheet number beginning with 's' and using a 3-digit number with leading
zeros. (Use s000= for the first menu item.)
menu_bar_text is the text that goes in the PROVISION menu bar under
Tools/Spreadsheet. Place an ampersand (&) in front of the character to be underlined.
xls_filename is the name of the file in which you macro is located (a *.xls or *.xla file).
extra_info is any extra information you want to be available. In the supplied examples,
this is used to identify the spreadsheet template file that will be used as the basis of the
reports.
At this point, PRO/II can be restarted and the new item will appear in the "Tools /
Spreadsheet" menu.
P2SRV.ClearMsgs
sResults$ = P2DB.FlashStream("1")
MsgBox sResults$, vbOKOnly, "Flash Results"
nMsg% = P2SRV.MsgCount
If nMsg% > 0 Then
For i% = 0 To (nMsg% - 1)
sMessage$ = P2SRV.MsgText(i%)
Next
End If
A PRO/II COM Server application can also create a new database, define components
and thermodynamic data, define a new stream, and perform a flash calculation on that
new stream. The following example demonstrates this approach:
Sub Main()
Dim P2SRV As Object
Set P2SRV = CreateObject("SimSciDbs.Database.81")
P2SRV.Initialize
If isDefault = 1 Then
Set P2OBJ = P2DB.ActivateObject("ThermoGlob", " ")
P2OBJ.PutAttribute thID, "DfltMethInp"
P2OBJ.Commit True
Set P2OBJ = Nothing
End If
End Sub
PRO/II uses "internal" streams for storing intermediate results. Internal streams are
objects with a name that begins with a "$" sign. These streams are normally not included
in the list of stream objects retrieved with the GetObjectNames method.
Internal streams are used to store the outlet conditions of many unit operations before the
outlet products are split into the individual vapor, liquid, and decant water products. To
access the internal stream representing the overall outlet conditions, use the
"MergedProduct" attribute. Using this name, an application can load the internal stream
into memory and access the outlet conditions like any other stream object.
This example reads the outlet conditions from the "MergedProduct" of the Flash "FL1" unit
operation of the R3R application.
dTemp = P2OBJ.GetAttribute("Temperature")
dPres = P2OBJ.GetAttribute("Pressure")
dRate = P2OBJ.GetAttribute("TotalMolarRate")
MsgBox "Temperature = " & dTemp2 & " " & uomT, vbOKOnly, "Temperature"
MsgBox "Pressure = " & dPres2 & " " & uomP, vbOKOnly, "Pressure"
MsgBox "Flowrate = " & dRate2 & " " & uomR, vbOKOnly, "Flowrate"