OpenServer
January 2011
User Manual
by Petroleum Experts Limited
OpenServer is designed to provide an Open Architecture for all the Petroleum Experts IPM products. This will allow the programs to be directly accessed and be driven by other third party programs.
Applications for OpenServer are in Connections to: • Third Party Reservoir Simulator.
• Process Simulators. • Economics Packages. • Data Base.
• Field Control System.
• In House and Proprietary Applications.
Specifically, the OpenServer allows other programs (such as Excel or programs written in Visual Basic) to access public functions in Petroleum Experts programs. An external program, in an automated procedure, can then access the Petroleum Experts products.
The copyright in this manual and the associated computer program are the property of Petroleum Experts Ltd. All rights reserved. Both, this manual and the computer program have been provided pursuant to a Licence Agreement containing restriction of use.
No part of this manual may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language, in any form or by any means, electronic, mechanical, magnetic, optical or otherwise, or disclose to third parties without prior written consent from Petroleum Experts Ltd., Petex House, 10 Logie Mill, Edinburgh, EH7 4HG, Scotland, UK.
© Petroleum Experts Ltd. All rights reserved.
IPM Suite, GAP, PROSPER, MBAL, PVTP, REVEAL, RESOLVE, IFM and OpenServer are trademarks of Petroleum Experts Ltd.
Microsoft (Windows), Windows (2000) and Windows (XP) are registered trademarks of the Microsoft Corporation
The software described in this manual is furnished under a licence agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license agreement. No part of this documentation may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems for any purpose other than the purchaser's personal use, unless express written consent has been given by Petroleum Experts Limited.
Address:
Petroleum Experts Limited Petex House 10 Logie Mill Edinburgh, Scotland EH7 4HG Tel : (44 131) 474 7030 Fax : (44 131) 474 7031 email: [email protected] Internet: www.petex.com
Copyright Notice
Table of Contents
0
Part 1 Technical Overview
2
... 4 1 Basic Functions
... 5 2 Calling Public Functions
Part 2 Support
8
Part 3 Using OpenServer
10
... 10 1 Tag Strings
... 11 2 Automation
... 11 Exam ple Macro
... 14 Macro Fram ew ork
... 15 DoCm d
... 16 DoSet Sub Com m and
... 16 DoCom m andAsync
... 17 DoGet Sub Com m and
... 18 3 Batch File
... 18 Running a Batch File
... 19 Form atting Com m ands
... 20 DoCom m and
... 20 SetValue
... 21 GetValue and GetValPrint
... 21 4 Arrays and List Variables
... 22 Special Array Operations
... 22 COUNT ... 22 NDIM ... 23 DIMSIZE ... 23 RESET ... 24 SORT ... 24 ADD ... 24 DELETE ... 25 INSERT ... 25 5 Multiple Values for Arrays
... 25 Multiple DoGet Values
... 26 Multiple DoSet Values
... 26 Using More than One Multiple Array
... 27 6 Units
... 29 7 Start/Shutdown Commands
Part 4 GAP and the OpenServer
32
... 32 1 Introduction and Variable Lists
... 33 Ctrl + Right m ouse click
... 34 Execute OpenServer Statem ent
OpenServer User's Manual January, 2011
... 35 Specific Units Handling Com m ands
... 36 Literal Constants
... 37 Date Handling w ithin GAP
... 38 OpenServer "Wild Cards"
... 39 Variables at Top Level
... 41 Variables at MOD Level
... 41 Model Options
... 46 Solver Setup and Calculation Log
... 48 Prediction Setup
... 52 Model Equipment List
... 53 Variables at Node Level
... 53 General fields found in nodes of any type
... 55 Fields specific to tanks
... 57 Fields Specific to Wells
... 58 Fields specific to all w ell models
... 60 Fields specific to w ells modelled using VLP/IPR intersection
... 65 Fields specific to w ells modeled using Performance Curves /
Interpolated Performance Curves
... 67 Fields specific to Stand-Alone Inflow s
... 67 Fields specific to Stand-Alone Outflow s
... 68 Equipment Control Section
... 69 PROSPER Online Models
... 70 Fields specific to pipelines
... 70 Pipeline Model Selection
... 70 GAP Internal Correlation Pipeline Models
... 74 GAP Lift Curves Pipeline Models
... 75 GAP PROSPER Online Pipeline Models
... 76 Fields specific to joints
... 76 Fields specific to pump/compressor nodes
... 77 Fields Common to Pumps and Compressors
... 78 Fields Specific to Compressors
... 79 Fields specific to separator / injection manifold nodes
... 80 Com position Records
... 80 Compositional Model Setup
... 80 Fluid Composition Setup - Wells
... 82 Fluid Composition Results
... 82 Enabling / Disabling Options
... 84 Scheduling ... 84 Schedule Count ... 84 Date ... 85 Event type ... 86 Constraint Type ... 86 Constraint Value ... 86 Schedule Reset ... 87 Apply Schedule To ... 87 Constraints ... 87 Constraint Level and Type
... 89 Binding Constraints
... 90 Constraints and Potential Calculations
... 91 Obtaining the Results
... 91 Solver Results
... 92 Prediction Results
... 94 Total System Results
... 94 Snapshot Results
... 95 SubFlow Sheets
... 95 2 GAP OpenServer Functions
... 96 GAP OpenServer Functions Overview
... 102 CALCCOMPDP (com p) / CALCPUMPDP (pum p)
... 103 CALCPIPEDP(pipe)
... 105 COPYITEM( EquipDest, EquipSrc )
... 105 DELITEM (node)
... 105 ISMEMBEROFGROUP(Group)
... 106 LINKITEMS ( equip1, equip2, linklabel )
... 106 NEWFILE( )
... 106 NEWITEM( type, label, iposcode, equip, m odel )
... 107 Working w ith Flow sheets
... 108 OPENFILE( filenam e )
... 109 PCCALC (equip, PcCurve)
... 110 PCGMAX (equip, PcCurve)
... 110 PCGSOLV (equip, PcCurve)
... 111 PCPSOLV (equip, PcCurve)
... 112 PREDDOSTEP (optim ise, potential)
... 113 PREDDOSOLVER (tim estepsize, optim ise, potential, m odel)
... 114 PREDEND(dorest, optim ise, potential)
... 115 PREDINIT (ignore internal tim estep, ignore internal scheduling)
... 116 PURGEALLRESULTS (m odel) ... 116 PURGEPREDLOG (m odel) ... 116 PURGEPREDRESULTS (m odel) ... 117 PURGEPREDSNAPSHOT (m odel) ... 117 PURGESOLVERLOG (m odel) ... 117 PURGESOLVERRESULTS (m odel) ... 117 REFITPC(w ell) ... 118 RESETSOLVERINPUTS () ... 118 SAVEFILE( filenam e ) ... 118 SHUTDOWN (save) ... 119 SOLVENETWORK() ... 120 TRANSFERPROSPERIPR (w ell, layernum ber, PVTMethod)
... 120 UNLINKITEMS (equip1, equip2)
... 121 VALIDATE (solverorpred)
... 121 VLPIMPORT (equip, filenam e)
... 122 VLPIPRPCGEN (w ell, autow hp)
... 122 WELLCALC (w ell)
... 123 MOD[i].CopyControls (from , to, SkipFNAs)
... 124 MOD[i].ResetControls (colum n)
... 124 MOD[i].RESETSCHEDULE (type, equiptype)
... 124 MOD[i].VALIDATE (solverorpred) ... 125 GROUPS ... 126 EQUIP[i].ADDTOGROUP (group) ... 126 EQUIP[i].BYPASS () ... 126 EQUIP[i].DISABLE () ... 126 EQUIP[i].ENABLE () ... 127 EQUIP[i].IsMem berOfGroup(group) ... 127 EQUIP[i].MASK () ... 127 EQUIP[i].REMOVEALLGROUPMEMBERSHIPS () ... 127 EQUIP[i].REMOVEFROMGROUP (group) ... 128 EQUIP[i].UNBYPASS () ... 128 EQUIP[i].UNMASK ()
OpenServer User's Manual January, 2011 ... 128 TANK[i].CalcDCTankCurPres(CurProd) ... 129 PIPE[i].DOMATCH () ... 129 IPR[i].CONINGMATCH () ... 129 IPR[i].DISABLE () ... 130 IPR[i].ENABLE () ... 130 IPR[i].IPRMATCH () ... 130 IPR[i].MASK () ... 131 IPR[i].UNMASK () ... 131 IPR[i].VALIDATE (solverorpred) ... 131 3 GAP Internal Script
Part 5 MBAL and the OpenServer
134
... 134 1 Finding a Variable Text String
... 135 2 Date Handling within MBAL
... 135 3 Commands
... 136 General
... 136 Material Balance Com m ands
... 138 Monte Carlo ... 138 1D Model ... 138 Decline Curve ... 138 Multi-Layer ... 138 Production Allocation ... 139 Tight Gas ... 139 PVT ... 140 4 OpenServer Code Examples
... 140 DoGet, DoSet and DoCm d Exam ple
... 141 List Variables
... 142 Material Balance Step-by-Step Prediction
... 144 Production Allocation Step-by-Step Prediction
... 145 5 Direct Access OPENSERVER
... 145 Overview
... 146 Sum m ary
... 147 High Level Exam ple
... 155 Low Level Exam ple
... 170 Datablock Variable Nam es
... 173 6 Variable Text Strings
... 173 1D Model ... 174 Monte Carlo ... 175 Decline Curve ... 175 Multi-Layer Tool ... 177 PVT ... 179 Material Balance ... 185 Production Allocation ... 186 Tight Gas ... 186 Relative Perm eability Curves
Part 6 PROSPER and the OpenServer
189
... 189 1 General Comments
... 190 Getting the strings through Ctrl+Right Click
... 190 List of variables in PROSPER file (NEW!!!)
... 195 Evaluate OpenServer Statem ent Section (NEW!!!!)
... 196 Setting the Units and Validation Lim its
... 198 Counting num ber of entry data points or calculated results
... 199 2 Options Summary Data
... 202 3 PVT Data Section
... 202 INPUT - Input Data
... 204 MATCH - PVT Match Data
... 205 TABLE - Setting data to the PVT Lookup Tables
... 206 CORREL – Correlation Matching Param eters
... 206 Black Oil - Oil
... 208 Black Oil - Gas
... 208 Black Oil - Retrograde Condensate
... 209 CALC - Calculation Results
... 211 EOS - Equation of State Data
... 214 DLL - External PVT DLL Data
... 215 EMULSION - Em ulsion Data
... 215 VISC - Viscosity Data
... 216 HYD - Hydrates Form ation Data
... 216 4 INPUT Data Section
... 217 IPR Data
... 217 Overview
... 217 Single Branch Data
... 217 Common Parameters
... 218 Model Selection and PVT Screen
... 219 Test/PI Entered Models
... 220 MultiRate Models
... 221 Darcy-based Models
... 223 External Entry Model Parameters
... 223 Multi-layer (no friction dP loss) Table
... 224 Horizontal Well w ith dP Friction Loss Table, Including Coning Screen
... 226 Multi-layer w ith dP Friction Loss Table
... 228 Skin Aide Model Parameters
... 231 Tw o-term Model Parameters
... 231 Fracture Model
... 232 SPOT
... 238 Mechanical Skin Parameters
... 239 Deviation Skin-Specific Parameters
... 240 Gravel Pack-Specific Parameters
... 241 Relative Permeability Screen
... 241 Gas Coning Parameters for Oil
... 242 Multi-lateral Well Data
... 242 Netw ork items
... 248 Branch, Layer and Segment Details
... 249 Calculation Control Data
... 249 Visualisation Data
... 250 Multilateral Results
... 251 Equipm ent Data
... 251 Overview
... 252 DEVN – Deviation Survey Equipment
... 252 TEMP – Flow ing Temperature Survey
... 253 GEO – Geothermal Gradient
... 253 SURF – Surface Equipment
... 254 TURF – Surface Equipment (Enthalpy Balance)
OpenServer User's Manual January, 2011
... 255 DOWN – Dow n Hole Equipment
... 256 TOWN – Dow n Hole Equipment (Enthalpy Balance)
... 256 SHC – Fluid Properties – Average Heat Capacities
... 257 ENV – Surface Environment Data (Enthalpy Balance / Rough Approx.)
... 257 DRILL – Drilling Data (Enthalpy Balance)
... 259 LITHO – Lithology (Enthalpy Balance)
... 259 DB – Databases (Enthalpy Balance)
... 260 Artificial Lift Data Section
... 261 Gas Lift (Continuous)
... 262 Electircal Submersible Pump
... 263 Hydraulic Drive Dow nhole PUmp
... 263 Progressive Cavity Pump
... 263 Coil Tubing Gas Lift
... 264 Jet Pump
... 264 Multiphase Pump
... 264 Sucker Rod Pump
... 265 Gas Lift (Intermittent)
... 265 5 Calculation Input Data
... 273 INF - Inflow Sensitivity Calculations
... 275 SYS - System Sensitivity Calculations
... 279 SYS - System Multi-Variable Calculations
... 281 GRD - Gradient Sensitivity Calculations
... 283 VL3 - VLP Sensitivity Calculations (3 Variables)
... 286 VL4 - VLP Sensitivity Calculations (4 Variables)
... 289 VLM - Multi-Variable
... 290 QLG - QuickLook – GasLift
... 291 QLE - QuickLook – ESP
... 292 QLH - QuickLook – HSP
... 293 TCC - Tubing Correlation Com parison
... 295 PCC - Pipeline Correlation Com parison
... 297 GMT - Gradient Matching
... 298 GDT - Gradient Test Data
... 299 VMT - VLP Matching
... 300 PMT - PipeLine Matching
... 301 CHK - Choke Perform ance
... 302 GEN - Generate For GAP
... 303 WHP - BHP from WHP
... 304 PLD - Plot Details
... 308 COR - Flow Correlation Data
... 309 THR - Correlation Threshold Data
... 309 CST - Constrained System Calculations
... 311 CVT - Constrained VLP Calculations
... 313 UST - Unconstrained System Calculations
... 315 UVT - Unconstrained VLP Calculations
... 318 UGT - Unconstrained Gradient Calculations
... 320 6 Artificial Lift Design Input Data
... 320 GasLift Design
... 324 Electical Subm ersible Pum p Design
... 324 Hydraulic Drive Dow nhole Pum p Design
... 325 Progressive Cavity Pum p Design
... 325 Jet Pum p Design
... 326 Sucker Rod Pum p Design
... 327 7 Calculation Results
... 328 INF - Inflow Sensitivity Calculations
... 329 SYS - System Sensitivity Calculations
... 338 GRD - Gradient Sensitivity Calculations
... 340 GRD - Flow Regime Number
... 343 QLG - QuickLook – GasLift
... 347 QLE - QuickLook – ESP
... 351 QLH - QuickLook – HSP
... 355 PCP - Pipeline Correlation Com parison
... 357 TCC - Tubing Correlation Com parison
... 360 GMT - Gradient Matching
... 362 VL3 - VLP Sensitivity Calculations (3 Variables)
... 364 VL4 - VLP Sensitivity Calculations (4 Variables)
... 366 GEN - Generate For GAP
... 369 SPD - Sensitivity PvD
... 372 SPT - Sensitivity PvD (Enthalpy Balance)
... 374 GLN - Gas Lift Design (New Well)
... 378 GLE - Gas Lift Design (Existing Well)
... 382 Gas Lift Design (Interm ittent)
... 382 ESP - ESP Design
... 384 HSP - HSP Design
... 385 CST - Constrained System Calculations
... 392 CVT - Constrained VLP Calculations
... 392 UST - Unconstrained System Calculations
... 399 UVT - Unconstrained VLP Calculations
... 400 UGT - Unconstrained Gradient Calculations
... 402 VLP Export ... 404 8 Commands ... 413 9 Functions ... 415 10 Code Samples
Part 7 PVTP and the Open Server
426
... 426 1 OverView
... 426 2 File and Streams
... 427 3 BLACKOIL
... 428 4 OPTIONS
... 431 5 STREAMBASE [stream no. or stream name]
... 435 6 STREAMRUN[stream no. or stream name]
... 437 7 CALCUL[stream no. or stream name]
... 444 8 Carrying out Calculations and Obtaining Results
... 447 Analysis
... 449 Flash Calculation
... 449 Sm all Separator Calculation
... 451 Saturation Pressure at Reference Conditions
... 451 Recom bination Calculation
... 452 Allocate: Blending to a Target GOR
Part 8 REVEAL and the OpenServer
455
... 455 1 Scope
OpenServer User's Manual January, 2011 ... 455 2 Commands ... 456 3 Script Data ... 457 4 Results Data ... 458 5 Runtime Data
Part 9 RESOLVE and the OpenServer
467
... 467 1 Overview
... 468 2 Top Level Variables
... 470 Module variables
... 473 Module Optimisation variables
... 474 SrcSnk variables ... 475 Driver variables ... 476 ModLink variables ... 477 Schedule variables ... 478 Scenario Manager Variables
... 478 Connection variables
... 479 Properties variables
... 479 Optim iser param eter variables
... 480 Optim iser schedule variables
... 481 3 Commands (COPY)
... 482 4 Sample macros
Part 10 OpenServer Examples
484
... 484 1 OpenServer VBA Template
... 484 2 GAP Examples
... 484 Basic Code Structure
... 487 Exam ple 1 – GAP Open Server Exam ple A
... 489 Exam ple 2 – GAP Open Server Exam ple B
... 500 Exam ple 3 – GAP Open Server Exam ple C
... 500 Exam ple 4 – GAP Open Server Exam ple D
... 503 3 MBAL Examples
... 504 Step-by-Step Material Balance Prediction Exam ples
... 505 4 Step-by-Step Production Allocation Examples
... 505 5 Direct Access Examples
... 505 6 PROSPER Example
Chapter
1
Technical Overview
OpenServer is a powerful utility that allows other programs (such as Excel, programs
written in Visual Basic) to access public functions in IPM to automate data input and model calculations.
Specifically, OpenServer allows other programs such as Excel or programs written in Visual Basic, to access public functions in the IPM Suite of tools. An external program, in an automated procedure, can then access the IPM Suite of tools.
OpenServer can be used to run the IPM Suite of tools in conjunction with other
software applications and exchange data between them. For example, a Visual Basic program or batch file could be used to successively initialize all IPR’s in GAP from
MBAL simulations then retrieve all current IPR data.
OpenServer provides seamless data transfer to and from the PETEX tools to other
applications and database utilities. Also, the client program can use any technique to access the values in the database, e.g. ODBC, DAO, SQL and then transfer them with
OpenServer to IPM.
Being able to automate data transfer, automate calculations and automatically interrogate existing IPM model inputs provides a basis to develop streamline work-flows that serves to free up valuable engineering time.
The following OpenServer uses is not an exhaustive list, and illustrates some
OpenServer possibilities:
Batch Runs
Consider a situation where a prediction calculation in MBAL has been set up and it is of interest to check the final recovery for a range of OOIP values.
A spreadsheet in Excel can be created that lists all the OOIP's to be used in the prediction.
A VBA macro can be written within Excel
which:-- Gets the first OOIP value from the spreadsheet and sets it in the MBAL tank - Runs a production prediction
- Queries the final recovery from the production results and writes into the spreadsheet.
- Repeat for the next OOIP, etc.
Custom Reporting
Although PETEX products provide a variety of report formats, it is possible that specific reporting structures are required. A VBA macro within Excel can be written to query the required values from a PETEX product and then written in the required format to the
spreadsheet.
Data Import/Export
The OpenServer can be used for transferring data to or from a database and PETEX programs. The client program can use any technique to access the values in the database (e.g. ODBC, DAO, and SQL) and then transfer them with OpenServer.
For example, production data may be stored in an Access database, a VBA macro can be written in Access to query the data from the database and then use OpenServer to set the data in MBAL for instance.
An example is available in the installed MBAL examples – OPENSERV.MDB.
Enhanced Prediction Runs in GAP
Using OpenServer with GAP provides the ability to control field development strategies during the prediction by performing a task such as well drilling and completing from using OpenServer to dynamically monitor an overall facilities rate constraint. This means that wells will now be drilled and completed based on the overall model response, rather than driving well drilling scheduling from a scheduled date perspective. Please see the GAP OpenServer Example D.GAR file that also contains the completed drilling queue macro.
Running PETEX programs with other engineering software applications
OpenServer can be used to run the PETEX programs in conjunction with other software applications and exchange data between them.
For example, a visual basic program or batch file could be used to successively: - Run a process simulator to calculate a feed separator pressure
- Set the separator pressure in GAP - Optimize the production system in GAP
- Pass the GAP rates onto the process simulator -Run the process simulator, etc.
It is important to note that dynamic links to industry standards process and numerical reservoir simulators are now available through RESOLVE.
1.1
Basic Functions
There are a number of public functions that have been made available. However the three most important functions are as follows.
DoGet
This function allows an external program to query a data value in a PETEX program. It should be possible to obtain the value of any data item that can normally be viewed using the user interface of the PETEX programs. Each data item is defined by a unique text string.
DoSet
This function allows an external program to change a data value in a PETEX program. It should be possible to change the value of any data item that can normally be viewed using the user interface of the PETEX programs. It should be possible to build a data set from scratch using the DoSet function.
However, it is recommended that the user interface is still used to build parts of a data set which do not require any automation. This will allow the normal quality checking to take place which is a very important aspect of the model building process.
Each data item is defined by a unique text string.
These basic functions are already setup in the OpenServer template provided with the software installation.
The OpenServer template is called OpenServer Template.xls and can be found at the following location:
- C:\Program Files\Petroleum Experts\IPM 7.0\Samples\openserver\Template This template should be used as a starting point when building an Excel based
OpenServer utility.
DoCmd
This function allows calculations to be performed in a PETEX program. Each calculation type is defined by a unique text string.
Only a subset of calculations available via the normal user interface of the PETEX products are available using the OpenServer.
In particular, the DoCommand function supports those calculations which are applicable to automated use e.g. a GAP prediction.
However it generally does not support those calculations that require the user interface for correct use e.g. MBAL graphical matching.
Different syntaxes can be used in certain cases to replace the command. These different syntaxes can be:
- DoCmd (used to perform a PROSPER calculation) - DoGAPFunc (used to perform a GAP calculation) - DoSlowCmd (See note below)
The code for these commands has already been setup in the OpenServer template provided with the software installation.
This OpenServer template is called OpenServer Template.xls and can be found at the following location:
- C:\Program Files\Petroleum Experts\IPM 6.0\Samples\openserver\Template. The OpenServer template can be used as a starting point when building an Excel based OpenServer utility. Also, the variety of OpenServer example files that have been constructed for each IPM tool can also be modified to meet individual needs.
Note:
Unfortunately, VBA was designed for use with simple functions that take only a few seconds. If a function is called that takes more than one minute to complete, a timeout error in Excel may occur depending on operating system, Excel version, setup etc. This is where the DoSlowCmd would be required to replace the DoCmd sub fuction.
The DoSlowCmd will also be required if the license server has high traffic where the speed of communication from the local PC to obtain a license has been reduced.
1.2
Calling Public Functions
There are two methods of calling public functions.
The following sections summarizes how to call the functions, syntax examples are also provided.
Automation
The OpenServer is an Automation server. This means that the public functions can be called from any program that can act as an Automation client.
There are many programs that can act as an Automation client and can therefore be used to call the public functions in the PETEX programs.
These include:
- Any VBA macro. These macros are available in Excel, Access and many other Microsoft products.
- Visual Basic programs can be written to act as an Automation client and therefore call the public functions.
- C++ programs can also be written to act as an Automation client and therefore call the public functions.
individual documentation.
Batch File
To avoid dependence on Automation, it is also possible to call the public functions in the PETEX programs using a simple batch file.
The functions required are typed into a text file.
A program is supplied by Petroleum Experts (PXBATCH) which will interpret the text file and call the functions in the PETEX programs.
It also writes the output of the DoGet function to another text file which can be viewed afterwards.
Chapter
2
Support
The main strength of the OpenServer is that users are now free to develop their own applications which utilise the public functions within PETEX products. However this does mean that a user of the OpenServer will require more computing knowledge than a user of the standard PETEX programs. This is particularly the case where a user writes a client application in VBA or Visual Basic. The user is expected to have (or be trained in) the requisite computing skills to write these client applications.
Petroleum Experts will not be able to undertake to train users in these computing skills.
The boundary of the PETEX products and the user’s applications needs to be defined with respect to support provided by Petroleum Experts of the OpenServer feature. Firstly, as with normal support, a maintenance agreement between the user and Petroleum Experts must be in place.
Unfortunately, Petroleum Experts will not be able to undertake development of
VBA macros, batch files or other OpenServer clients for a particular user. The
strength of the feature is to allow the user to implement these client applications without any further input by Petroleum Experts.
Similarly Petroleum Experts will be unable to assist in fixing bugs in users VBA macros, batch files or any other OpenServer client.
Petroleum Experts will undertake to support any user who can demonstrate (through a simple fragment of a batch file or VBA macro etc) that a public function call to a PETEX product fails to work correctly.
Chapter
3
Using OpenServer
This chapter describes in detail how to access the public function in PETEX programs. The TagStrings section describes how each data item is defined in the PETEX programs using a variable text string.
The Automation section describes how to call the public functions using Automation. We first describe the framework needed to use the OpenServer, then each function is described in detail.
The Batch File section describes how to call the public functions using a batch file system. We describe the framework and then describe each function in detail.
This section does not deal with specific issues relating to particular products e.g. GAP or MBAL.
To use the public function for a particular PETEX program, the tools must be installed on the local hard disk with access to a valid security authentication e.g. security key or HARDLOCK.
When the public functions are being called (either using Automation or a batch file), the appropriate PETEX product must be running. However, it does not need to be visible on the screen (i.e. it can be minimized). Commands are available to start each of the programs. Alternatively one can start the programs manually before running a macro/ batch file.
3.1
Tag Strings
Tag strings describe each data item in the PETEX programs. It is a string of characters which is broken into a number of subnames separated by full stops. As one moves from left to right along the string, the definition of the variable becomes more detailed.
The tag string of any data item in MBAL always begins with the subname “MBAL”. Similarly, any data item from GAP, PVTP, REVEAL, RESOLVE or PROSPER will begin with the subname “GAP”, “PVTP”, “REVEAL”, "RESOLVE" or “PROSPER” respectively.
The rest of the string depends on the section of the program. There may be several subnames if the data item is part of a complex hierarchy.
For example, for the start time in the material balance prediction we may have “MBAL. MB.PRED.STARTTIME".
For this tag string:
- MB – In the material balance tool - PRED – In the prediction section - STARTTIME – Start time
All tag strings are case insensitive (i.e. it does not matter if lower or upper case characters are used).
For specific details of the tag strings for each PETEX program, refer to the program specific sections below.
It is also possible to capture the OpenServer string details directly from the given IPM tool using a Ctrl + Right-Click keyboard and mouse work-flow.
Please note, it is not possible to capture an OpenServer string using the above keyboard and mouse work-flow for a calculation button. For a list of IPM OpenServer command strings, please review the corresponding OpenServer command reference information.
3.2
Automation
This section describes how to access the public functions using Automation. This is a Microsoft Windows standard (formally known as OLE Automation). This method requires software which can act as an Automation client to call the public functions. Probably the most commonly used example of such an Automation client that is used in the engineering industry is the VBA macro language within Excel. We will therefore demonstrate how the public functions are called by such macros – the same rules should extend to other Automation clients.
Rather than describing the functions in isolation, an example of an Excel VBA macro is presented that uses all the available public functions. Each function within this example will be described including macro error handling.
It is important to note that the OpenServer template already contains the necessary macro communication error handling already built in.
3.2.1 Example Macro
This example performs a simple set of operations in the MBAL program. These include:
- Open the OIL.MBI file
- Change the original oil in place to a new value - Run a prediction
- Get the first oil rate and display it in the Excel spreadsheet.
the directory C:\Program Files\Petroleum Experts\IPM 7.0\Samples\openserver\MBAL The macro is split into a number of subroutines and functions:
- The main subroutine is called DoAll().
- There are five other subroutines and functions which allow calls to be made to the PETEX public functions.
Option Explicit
Dim Server As Object Dim AppName As String Sub DoAll()
Connect 'establishes Excel communication link to IPM
AppName = "MBAL"
DoSlowCmd "MBAL.OPENFILE=C:\PETEX\SAMPLES\OIL.MBI"
'See below for an alternative "file open" approach
DoSet "MBAL.MB.TANK.OOIP", "250.0" 'set the tank OOIP value
DoSlowCmd "MBAL.MB.RUNPREDICTION" 'run the prediction
Range("C11") = DoGet("MBAL.MB.TRES[2][0][0].
OILRATE") 'retrieve the first oil rate
Disconnect 'Closes the server object connection to IPM
MsgBox "Macro completed" End Sub
Alternative File Open Approach
Ü If the MBAL file name was placed at a certain cell reference in Excel, then the following File | Open approach could be used: "MBAL.OpenFile(""" + Range ("E12") + """)"
OpenServer Template Error Handling Code
The following code is part of the OpenServer template and manages error handling between the application and macro:
Sub DoCmd(Cmd) Dim lErr As Long
lErr = Server.DoCommand(Cmd) If lErr > 0 Then
MsgBox Server.GetErrorDescription(lErr) Set Server = Nothing
End End If End Sub
Sub DoSet(Sv, Val) Dim lErr As Long
lErr = Server.SetValue(Sv, Val) lErr = Server.GetLastError(AppName) If lErr > 0 Then
MsgBox Server.GetErrorDescription(lErr) Set Server = Nothing
End End If End Sub
Function DoGet(Gv As String) As String Dim lErr As Long
DoGet = Server.GetValue(Gv)
lErr = Server.GetLastError(AppName) If lErr > 0 Then
MsgBox Server. GetErrorDescription(AppName) Set Server = Nothing
End End If End Function
Sub DoSlowCmd(Cmd)
Dim StartTime As Single Dim EndTime As Single Dim CurrentTime As Single Dim lErr As Long
Dim bLoop As Boolean
lErr = Server.DoCommandAsync(Cmd) If lErr > 0 Then
MsgBox Server.GetErrorDescription(lErr) Set Server = Nothing
End End If While Server.IsBusy(AppName) > 0 StartTime = Timer EndTime = StartTime + 2 Do CurrentTime = Timer DoEvents bLoop = True
Rem Check first for the case where we have Rem gone over midnight and the number of Rem seconds will go back to zero
If CurrentTime < StartTime Then bLoop = False
Rem Now check for the 2 second pause finishing
ElseIf CurrentTime > EndTime Then bLoop = False
End If
Loop While bLoop Wend
lErr = Server.GetLastError(AppName) If lErr > 0 Then
MsgBox Server.GetErrorDescription(lErr) Set Server = Nothing
End End If End Sub
Function DoGAPFunc(Gv As String) As String AppName = “GAP”
DoSlowCmd Gv
DoGAPFunc = DoGet("GAP.LASTCMDRET") End Function
3.2.2 Macro Framework
The Technical Overview section listed three main sub-commands that OpenServer uses to set data, perform calculations and retrieve results to an Excel based VB macro. The template OpenServer macro spreadsheet can be used to develop a macro for any one of the IPM suite of tools.
There are only a few lines of code that need to be in an Excel macro to use
OpenServer. Before using any of the public functions, an object must be declared to
establish the communication link from the VB macro with the PETEX programs:
Di m Ser ver As Obj ect
Next, the object will be connected to the OpenServer using the line:
Set Ser ver = Cr eat eObj ect ( " PX32. OpenSer ver . 1" )
Alternatively, the above line can be replaced by the Connect function that has been implemented in the OpenServer template.
The line then simply becomes:
Connect
functions from any or all of the PETEX programs, i.e.,
Ser ver . DoCommand( Command1) Ser ver . DoCommand( Command2) Ser ver . Get Val ue( Var 1)
Once the public functions in the macro have completed, the server object connection can be closed using:
Set Ser ver = Not hi ng
This line can be replaced by the Disconnect function that has been implemented in the
OpenServer template.
The line then simply becomes:
Di sconnect
These can be seen in the DoAll() subroutine above.
3.2.3 DoCmd
The DoCmd function is used to perform calculations and other functions such as file opening and saving in the PETEX programs.
Only a subset of the commands available using the user interface are available. The commands that are not supported are those that require some graphical interaction such as graphical history matching in MBAL.
In the above example, DoCmd is used twice. The first time it is used to open the Oil.
MBI data file.
The second time it is used for running a prediction. The text string after the DoCmd statement describes the command to be performed.
The text string always starts with the name of the program in which the calculation is to be done. The rest of the text string describes the command – check the following sections describing each PETEX program for a list of possible calculations.
There is no output to the PXR file for this command. If there is any error, a message will be written to PXBATCH.LOG.
Note that the abbreviation dc can be used in the batch file instead of DoCmd.
Note:
As previously mentioned, VBA was designed for use with simple functions that take only a few seconds. If a function is called that takes more than one minute to complete, a timeout error in Excel may occur depending on operating system, Excel version, setup etc. If this happens, the DoSlowCmd should be used instead of the DoCmd.
3.2.4 DoSet Sub Command
The DoSet command is used to set the value of a data item. It should be possible to change most of the values that can normally be accessed via the user interface. Each variable is identified by the unique text string that can be captured using a Ctrl +
Right-Mouse Click keyboard and mouse action.
In the above example, the DoSet function is used in the DoAll() subroutine to change the value of the initial oil in place to 250.0. The variable to be changed is determined by the first input text string. The new value for the variable is passed in the second input text string.
This function expects the value to be in the units currently displayed in the user interface. It is the responsibility of the user writing the macro to ensure that the second text string contains a valid number if the data item is numerical.
Unlike the DoCmd public function, the DoSet function does not return an error number. As can be seen in the example macro subroutine DoSet(), the GetLastError() public function must be called to check if any error occurred. This will return zero if the last public function call was successful or an error number if not.
It is recommended that the DoSet() macro subroutine shown in the example macro and provided in the OpenServer Template.xls file is used for all applications as it already has error handling built in.
Please also see the main on-line help of PROSPER, as it contains a listing of
OpenServer variables and commands.
3.2.5 DoCommandAsync
This function is a variation of the DoCmd function. It is nearly always used in conjunction with the IsBusy() function.
When a VBA macro is run, it executes and completes each line before moving onto the next line. So when the DoCmd function is called for a long prediction, it may take several minutes (or even hours) before the VBA can move onto the next line in the macro.
Unfortunately, VBA was designed for use with simple functions that take only a few seconds. If a function is called that takes more than one minute to complete, a timeout error in Excel may occur depending on operating system, Excel version, setup etc.. The DoCommandAsync functions to be called that take a long time to complete without any risk of timeouts. When a DoCommandAsync is called, the OpenServer starts the calculation in the PETEX program but lets the VBA carry immediately on to the next line in the macro. This avoids the timeout error in Excel.
Unfortunately it introduces another problem. What if the next line in the macro was a call to the GetValue function to get the results of the calculation? The macro is likely to try to
get the calculated value before the calculation is finished! So the VBA still needs some way of knowing when the calculation has finished.
Therefore it is usually necessary to append some VBA code after a call to DoCommandAsync which loops until the calculation is finished. The inserted code uses another function called IsBusy() to check if the calculation is finished.
This VBA code to do this is in the macro subroutine DoSlowCmd() in the example macro. The code loops round until the IsBusy function returns a value greater than zero. The only input argument is the name of the PETEX program in which the calculation was called. Within the loop the code will wait 2 seconds before looping again. It also calls the VBA function, DoEvents, which will allow other windows program to work whilst the VBA is waiting for the calculation to finish.
It is recommended that the DoSlowCmd macro subroutine shown in the example macro and provided in the OpenServer Template.xls file is used for all applications as it already has error handling built in as well as the code to wait for the function to finish.
3.2.6 DoGet Sub Command
The DoGet function is used to get the value of a data item or result. It should be possible to query most of the values that can normally be accessed via the user interface. Each variable is identified by a unique text string.
In the above example, the DoGet function is used in the DoAll() subroutine to get the value of the first oil rate in the prediction tank results. The variable to be retrieved is determined by the input text string. The return value of the function call is another text string containing the value of the data item. If the value is numerical data, the return text string will contain the formatted number and avoids having different functions for different data types. The value will be returned in the units currently displayed in the user interface.
As with the DoSet function, the GetLastError function must be used to check for errors in the SetValue function. Note that in the macro subroutine DoGet, we use a different function to get the actual error message using GetLastErrorMessage. This function returns the error message corresponding to the last public function call for the application specified by the input argument. If the last public function call was successful, it will return a blank error message.
It is recommended that the DoGet macro subroutine shown in the example macro and provided in the OpenServer Template.xls file is used for all applications as it already has error handling built in.
3.3
Batch File
This section describes how to access the public functions using a batch file. Each command is typed into an ASCII file. A program is supplied by Petroleum Experts which reads this ASCII file and calls the public functions in the PETEX programs and writes the output to another ASCII file.
3.3.1 Running a Batch File
The first step to calling the public functions from the batch file is to create the batch file itself. This is a simple ASCII file which can be created using NOTEPAD.EXE.
The only point to note is that when the batch file is saved it should have the file extension PXB e.g. TEST.PXB.
Each public function to be called should be listed on a separate line. Comment lines can be entered by starting the line with a # character e.g. # This is my first batch file
# 1st January 2009
The details of how to list the public functions are shown in the following sections.
Once the batch file has been created and the functions listed in the file, we can run the batch file:
Steps:
1. Run the latest version of the PETEX program that is going to be used e.g. MBAL and GAP
2. Copy the file PXBATCH.EXE into the same directory as the PXB batch file (this file can be found in the latest installation of the PETEX CD (C:/Program Files/Petroeum Experts/IPM 7)
3. Run the PXBATCH program with the PXB file name as an argument For example, if the batch file is called TEST.PXB, run PXBATCH –b TEST.
PXBATCH will call each public function in turn and two files will be created by PXBATCH. The first is called PXBATCH.LOG and will contain any error messages from the batch run so it is important to examine the file after every batch run to check for errors.
The second file will have the same file stem as the batch file but will have the extension PXR.
In the above case, the second output file will be called TEST.PXR. This file will contain any output from the public functions.
An example batch will be presented which shows calls to all the public functions in the PETEX products. Then each function used in the example batch file will be described in turn.
The example batch file is as follows (this file is available in the installed MBAL examples,
MBALTEST.PXB).:-# Example batch file
PRINT Example batch file output PRINT
docommand MBAL.OpenFile("C:\PETEX\SAMPLES\OIL.MBI")
setvalue MBAL.MB.TANK.OOIP 250.0
docommand MBAL.MB.RUNPREDICTION
getvalprint MBAL.MB.TANK.OOIP
PRINT "First oil rate =" PRINTTAB
PRINTTAB
getvalue MBAL.MB.TRES[2][0][0].OILRATE
PRINT " bbls/day" PRINT
PRINT End of example batch file output
The output PXR file from the above batch file is as follows:
250 ! MBAL.MB.TANK.OOIP
First oil rate = 16516.8 bbls/day End of example batch file output
3.3.2 Formatting Commands
There are two commands, PRINT and PRINTTAB that can be used to format and write text to the output PXR file.
The PRINT statement can be used in two ways:
- If some text is appended to the PRINT statement, the text will be printed out to the PXR file. If desired the text might be enclosed in quotations.
- If the PRINT command is used without any text, it will move the output onto the next line in the PXR file.
For example, consider the last three lines of the example batch file.
The first of these PRINT statements prints the text “ bbls/day”. The second PRINT statement moves the next output onto the next line. The third PRINT statement displays the text “End of example batch file output” on the next line of the PXR file. Note that if the second PRINT statement was not included, the output PXR file would look like:
The second formatting command is PRINTTAB. This command simply writes a tab character to the PXR file.
3.3.3 DoCommand
The DoCmd function is used to perform calculations and other functions such as file opening and saving in the PETEX programs.
Only a subset of the commands available using the user interface are available. The commands that are not supported are those that require some graphical interaction such as graphical history matching in MBAL.
In the above example, DoCmd is used twice. The first time it is used to open the Oil.
MBI data file.
The second time it is used for running a prediction. The text string after the DoCmd statement describes the command to be performed.
The text string always starts with the name of the program in which the calculation is to be done. The rest of the text string describes the command – check the following sections describing each PETEX program for a list of possible calculations.
There is no output to the PXR file for this command. If there is any error, a message will be written to PXBATCH.LOG.
Note that the abbreviation dc can be used in the batch file instead of DoCmd.
Note:
As previously mentioned, VBA was designed for use with simple functions that take only a few seconds. If a function is called that takes more than one minute to complete, a timeout error in Excel may occur depending on operating system, Excel version, setup etc. If this happens, the DoSlowCmd should be used instead of the DoCmd.
3.3.4 SetValue
This function is used to set the value of a data item. It should be possible to change most of the values that can normally be accessed via the user interface.
In the example we use SetValue once to change the original oil in place to 250.0. The first text string after SetValue defines the variable to be changed. The second text string defines the new value of the variable. This function expects the value to be in the units currently displayed in the user interface.
There is no output to the PXR file for this command. If there is any error, a message will be written to PXBATCH.LOG.
3.3.5 GetValue and GetValPrint
These two functions are both used to get the value of a data item and print it to the PXR output file. The only difference between the two functions is the format of the output to the PXR file.
GetValPrint is used once in the example batch file to get the value of the original oil in place – this is to verify that the preceding SetValue worked correctly. The text string after GetValPrint defines the variable to be written to the output PXR file. If the function works correctly, the variable is written to the PXR file followed by the variable text string, separated by an exclamation mark. It also moves the output onto the next line so any further Print functions will start on the next line. This format can be seen in the example PXR file above.
GetValue is also used once in the example batch file to output the first oil rate in the prediction tank results. The function is called as for GetValPrint. The only difference is that this function simply writes the value of the variable to the output PXR file without any formatting. This means that other Print commands will be needed to format the output – as shown in the example batch file.
Note that the abbreviation gvp can be used in the batch file instead of GetValPrint. The abbreviation gv can be used instead of GetValue.
3.4
Arrays and List Variables
Many of the variables in the programs have single values, such as a single reservoir pressure in PROSPER. However some of the variables are arrays such as a multi-tank system in MBAL. For this case, an index in the tag string must be specified.
Arrays in the programs can be variable or of a fixed size.
For example, if we have three tanks in an MBAL model then we access the OOIP of the first tank using the following tag string
:-MBAL.MB.TANK[0].OOIP
Note that the index is zero based. By this, we mean that the 1st item has an index of 0, the 2nd item will then have an index of 1, etc.
In some cases, one can identify an item in an array using the label of the item rather than an index. For example if the label of the 1st tank is Lower05, the OOIP can be
accessed using the following tag string:
One must place {} brackets around the label so the program will not interpret the label as a numerical index.
NOTE: The label is the only part of a tag string which is case sensitive.
If there is only one item in the list, then the index is optional. For example, if there is only one tank, the following tag string can be used:
MBAL.MB.TANK.OOIP
There are also some variables that are arrays with two or more dimensions. These variables will require two or more indices in the tag string.
For example, consider the prediction results for the material balance tool in MBAL. These have three indices where the first index indicates the result type, the second index is the tank and the third index is the row.
A tag string for a result may look like:
MBAL.MB[0].TRES[0][0][3].GASSAT
3.4.1 Special Array Operations
There are a number of special features that can only be used with arrays.
3.4.1.1 COUNT
The COUNT feature returns the number of items that exist in an array. This feature only works for arrays that have a variable size.
For example, the number of tanks in an MBAL model can be found using the command:
Range("C11") = DoGet("MBAL.MB.TANK.COUNT")
This command can also be used in multi-dimensional arrays to count the number of tank prediction results for instance using the command:
Range("C11") = DoGet("MBAL.MB.TRES[2][3].COUNT")
3.4.1.2 NDIM
The NDIM feature can only be used for fixed length arrays. It is used to find the number of dimensions in the array.
Consider a variable which is a three-dimensional array (this is not an actual variable). An item in the array may be accessed as follows:
Range("C11") = DoGet("MBAL.MB.TANK.PV[1][5][9]") One can find the number of dimensions by calling the following function:
Range("C11") = DoGet("MBAL.MB.TANK.PV.NDIM") This function will return the value 3.
3.4.1.3 DIMSIZE
The DIMSIZE feature can only be used for fixed length arrays. It is used to find the fixed number of items for a given dimension of the array.
Consider a variable which is a three-dimensional array (this is not an actual variable). Now, this array has 3 items in the 1st dimension, 8 in the 2nd dimension and 20 in the 3rd dimension. So the maximum indices we can access would be (remembering that the indices are zero based):
Range("C11") = DoGet("MBAL.MB.TANK.PV[2][7][19]")
One can find the fixed number of items in the second dimensions by calling the following function:
Range("C11") = DoGet("MBAL.MB.TANK.PV.DIMSIZE[1]") This function will return the value 8.
Similarly, DIMSIZE[0] will return 3 and DIMSIZE[2] will return 20.
3.4.1.4 RESET
The RESET feature can only be used for arrays with a variable number of items. It is used to delete all the items in the array and thus reduce the number of items in the array to zero.
For example, to delete all the items in the tank production history for an MBAL model, use the command:
3.4.1.5 SORT
The SORT feature can only be used for arrays with a variable number of items. It is used to sort all the items in the array in order. The method of sorting is the same as used in the corresponding dialog of the program.
For example, the tank production history for an MBAL model is sorted by the date of each item in the array.
To sort the production history, use the command:
DoSet "MBAL.MB.TANK.PRODHIST.SORT", ""
3.4.1.6 ADD
The ADD feature can only be used for arrays with a variable number of items. It is used to add a new item to the end of an array.
For example, to add two rows to an empty table of tank production history for an MBAL model, use the commands:
DoSet "MBAL.MB.TANK.PRODHIST.ADD", "" DoSet "MBAL.MB.TANK.PRODHIST[0].TIME", "01/01/2009" DoSet "MBAL.MB.TANK.PRODHIST[0].PRESS", "6980.0" DoSet "MBAL.MB.TANK.PRODHIST[0].CUMGAS", "0.0" DoSet "MBAL.MB.TANK.PRODHIST.ADD", "" DoSet "MBAL.MB.TANK.PRODHIST[1].TIME", "01/02/2009" DoSet "MBAL.MB.TANK.PRODHIST[1].PRESS", "6589.0" DoSet "MBAL.MB.TANK.PRODHIST[1].CUMGAS", "12.8" 3.4.1.7 DELETE
The DELETE feature can only be used for arrays with a variable number of items. It is used to delete a particular item in the list and it will reduce the number of items in the list by one.
For example, the following command will delete the 4th row in the production history table of an MBAL model:
3.4.1.8 INSERT
The INSERT feature can only be used for arrays with a variable number of items and it is used to insert a new item at a particular position in the list. All the items at and above the position to insert will be moved up one position in the list, so the new item can be inserted.
For example, the following command will insert a new row in the production history table of an MBAL model. The new row will become the 7th row:
DoSet "MBAL.MB.TANK.PRODHIST[6].INSERT", ""
DoSet "MBAL.MB.TANK.PRODHIST[6].TIME", "10/01/2000"
DoSet "MBAL.MB.TANK.PRODHIST[6].PRESS", "2700.0"
DoSet "MBAL.MB.TANK.PRODHIST[6].CUMOIL", "4.0"
DoSet "MBAL.MB.TANK.PRODHIST[6].CUMGAS", "4000.0"
3.5
Multiple Values for Arrays
This section describes how the DoSet / DoGet functions are used to retrieve and set more than one item in an array.
3.5.1 Multiple DoGet Values
Consider a situation where one wishes to extract tank pressures from a 5-tank MBAL model.
The following fragment of VBA code could be used:
Range("C1") = DoGet("MBAL.MB.TANK[0].PRESS")
Range("C2") = DoGet("MBAL.MB.TANK[1].PRESS")
Range("C3") = DoGet("MBAL.MB.TANK[2].PRESS")
Range("C4") = DoGet("MBAL.MB.TANK[3].PRESS")
Range("C5") = DoGet("MBAL.MB.TANK[4].PRESS")
A quicker method is to get all the pressures in one DoGet call, and there are two options to achieve the objective:
- Get the pressures for all the available tanks: Range("C1") = DoGet(" MBAL.MB.TANK[$].PRESS")
- Get the pressures for tank index zero through to tank index four: Range
("C1") = DoGet("MBAL.MB.TANK[0,1,2,3,4].PRESS")
The above example using multiple DoGet calls will return all the tank pressures in the model.
The values will be returned in a single text variable separated by the ‘|’ character e.g.
5132.0|4893.0|4598.3|4882.0|4976.6
There are several other variations which can be used to extract data from multiple tanks using the following syntax:
- Return the pressure for tank 0,1,2 and 4: Range("C1") = DoGet("MBAL
.MB.TANK[0:2,4].PRESS")
- Return the pressure for tank 1 and 3: Range("C1") = DoGet("MBAL.
MB.TANK[1,3].PRESS")
3.5.2 Multiple DoSet Values
The DoSet function can use multiple tag names in a similar manner to the DoGet function as previously described. All the different forms of the variable tag names used by the DoGet can be used for the DoSet function.
For the DoSet function, a text variable is passed to the function which contains a list of the values to set, separated by the ‘|’ character. For example, the following string can be used to set multiple OOIP's in a multi-tank system to tank 1, 4 and 5:
DoSet " MBAL. MB. TANK[ 1, 4, 5] . OOI P" , " 250. 0| 129. 0|
349. 0"
The above command will set the OOIP of tank index 1 to 250.0, tank index 4 to 129.0 and tank index 5 to 349.0.
There is an extra feature available with the DoSet function, where all tanks specified in the indices array [1,4,5] can have the same OOIP assigned using the following DoSet command:
DoSet " MBAL. MB. TANK[ 1, 4, 5] . OOI P" , " 250. 0"
The above technique can be used to set many items in a list to the same value.
3.5.3 Using More than One Multiple Array
The examples shown so far allow more than one index of a particular array to be accessed. However, we can also access multiple indices of more than one array at a time.
Consider the tag name for accessing the production data for an MBAL tank: MBAL.MB.TANK[2].PRODHIST[4].CUMOIL
tank.
We have already seen how we could access more than one production history record or more than one tank e.g. :
MBAL.MB.TANK[2].PRODHIST[3 :7].CUMOIL MBAL.MB.TANK[$].PRODHIST[4].CUMOIL
However we can also have multiple indices for both the production history records and the tank in the same tag name.
For example :
DoSet "MBAL.MB.TANK[1,2].PRODHIST[4:6]", "11.2|14.5|16.3|
5.2|6.1|7.5"
The above command sets indices 4, 5 and 6 of the production history for both tanks 1 and 2. The data in the values to set is ordered such that the index to the right varies first.
In other words the order is:
MBAL.MB.TANK[1].PRODHIST[4].CUMOIL MBAL.MB.TANK[1].PRODHIST[5].CUMOIL MBAL.MB.TANK[1].PRODHIST[6].CUMOIL MBAL.MB.TANK[2].PRODHIST[4].CUMOIL MBAL.MB.TANK[2].PRODHIST[5].CUMOIL MBAL.MB.TANK[2].PRODHIST[6].CUMOIL
As before, this method will work equally well for the DoGet function.
The example shown above has two arrays. However, it is possible to use multiple indices for any number of arrays in a tag string e.g. :
MBAL.MB.WELL[1:3].IPR[4,7].CONEMATCH[$][3,5:8].PRESS
3.6
Units
Units are handled the same way in all the IPM programs.
Use of Units in OpenServer:
By default, when a variable is accessed from the OpenServer using the DoGet function, the value returned is in the same units as defined for the current model.
For example, if a GAP model has degrees Celcius selected for the surface temperature variable of pipes, and the value entered for pipe ‘pipe3’ is 10 degrees C, then performing a DoGet on the tag “GAP.MOD[0].PIPE[{pipe3}].TMPSUR” will return 10.
Similarly, when a DoSet function is used, the value passed to the function is interpreted as being in the current unit displayed in the interface.
The units a variable is using can be queried using the UNITNAME(tag) function. This function will return the units label currently in use for that variable.
For example, performing a DoGet function on the string “GAP.UNITNAME(MOD[0]. PIPE[{pipe3}].TMPSUR)” would return the string “degrees C”.
The same information can be obtained by appending UNITNAME to a tag e.g. “GAP. MOD[0].PIPE[{pipe3}].TMPSUR.UNITNAME”
There are a number of ways of modifying the above behaviour.
Variables are normally stored internally in the programs in field units. To access a variable in field units, not the currently selected unit, use the RAWVAL(tag) function. For example, performing a DoGet on the string “GAP.RAWVAL(GAP.MOD[0].PIPE [{pipe3}].TMPSUR)” would return 50, since field units for temperature are degrees F. Similarly, if the RAWVAL modifier is used for a tag name with a DoSet function, the OpenServer will interpret the passed value as being in Oil Field units.
The automatic conversion of variable values from field units to user selected units can be switched off completely if desired. This is accomplished by setting the global variable DOUNITCONV, which is 1 by default, to zero. E.g.:
DoSet “PROSPER.DOUNITCONV”, “0”
Setting the above flag means all subsequent DoGet and DoSet calls will use Oilfield units. Note that unit conversion can be switched on again by setting the DOUNITCONV variable back to 1.
The currently selected units system can be set using the SETUNITSYS() function. Performing a DoCmd on the string “MBAL.SETUNITSYS(""Norwegian S.I."")” will set the input and output units to the Norwegian S.I. system for the current MBAL model.
Use of Units Validation Ranges in OpenServer:
There are also methods to get and set the minimum and maximum validation ranges as defined in the units system dialog.
To get the minimum value of variable, add UNITMIN to the end of the tag name e.g.
Range("C1") = DoGet("MBAL.MB.TANK[0].PRESS.UNITMIN") Similarly, the maximum validation range of a unit value can be obtained by appending