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 2^nd 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:

MBAL.MB.TANK[{Lower05}].OOIP

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:

DoSet "MBAL.MB.TANK.PRODHIST.RESET", ""

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:

DoSet "MBAL.MB.TANK.PRODHIST[3].DELETE", ""

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"