Pipeline Studio Excel Add-In User Documentation

PipelineStudio Excel Add-in User Guide
Contents
Contents ............................................................................................................................... 1
Introduction ........................................................................................................................... 2
Installation............................................................................................................................. 2
The PipelineStudio Excel Toolbar ......................................................................................... 3
Energy Solutions logo button............................................................................................. 3
Run Report button ............................................................................................................. 3
Add Times button .............................................................................................................. 3
Reload Data button ........................................................................................................... 3
Options button ................................................................................................................... 3
Custom Functions ................................................................................................................. 6
Using Custom Functions ................................................................................................... 6
Function List...................................................................................................................... 6
Examples of using PipelineStudio Add-in functions ......................................................... 22
Using Custom Functions from Microsoft Excel macros .................................................... 23
Running PipelineStudio Reports ......................................................................................... 24
Introduction ..................................................................................................................... 24
How to run a report ......................................................................................................... 24
Running Reports How It Works .................................................................................... 24
Cell References in report definitions ................................................................................ 25
Expansion of profile functions in Pipe report blocks ......................................................... 26
Expansion of alarm function that return arrays ................................................................ 26
Report Tags .................................................................................................................... 26
Creating Report Definitions Other Information .............................................................. 31
PipelineStudio Excel Template ........................................................................................ 31
Integration with PipelineStudio ........................................................................................ 31
Miscellaneous Information .................................................................................................. 32
Troubleshooting .................................................................................................................. 32
Notation .............................................................................................................................. 32
1
Introduction
The PipelineStudio Excel Add-in provides access to PipelineStudio reporting and trending
data from within Microsoft Excel worksheets.
The Add-in must be installed and selected for use in Microsoft Excel before it can be used.
Installation
For detailed installation and uninstall information for the PipelineStudio Excel Add-in,
including information on supported Versions of Microsoft Office and information on Macro
Security, please refer to the Installing the PipelineStudio Excel Add-in and Uninstalling the
PipelineStudio Excel Add-in sections in the PipelineStudio Installation Guide which can be
found on the PipelineStudio CD or Download:
[CD/Download]\PipelineStudio_Installation_Guide.pdf
2
The PipelineStudio Excel Toolbar
The PipelineStudio Excel Add-in includes a PipelineStudio toolbar which is added to
Microsoft Excel. The buttons on this toolbar are described in this section:
Energy Solutions logo button
This button displays an About dialog box showing the version number of the Add-in and
hyperlinks for contacting Energy Solutions.
Run Report button
This button runs a PipelineStudio report.
Add Times button
This button creates a timestep hyperlink in a cell.
Reload Data button
This button displays a dialog so that you can reload data for a case.
Options button
This button displays a dialog to change the options for the Add-in.
Display Error Messages Option

If this is checked, any functions which result in an error will return the reason for the error in
the cell. The error message will have the following format:
#ERROR Reason for the error
Date/Time format
This specifies the format pattern which is used to format date/time values which are returned
to Microsoft Excel.
Note: This pattern does not affect relative time values for simulations run using relative time:
The following table lists the format characters used to represent standard format patterns.
The format characters are case-sensitive; for example, 'g' and 'G' represent slightly different
patterns.
Format Character Example Format Pattern

d MM/dd/yyyy
D dd MMMM yyyy
f MMMM dd yyyy HH:mm
F MMMM dd yyyy HH:mm:ss
g MM/dd/yyyy HH:mm
G MM/dd/yyyy HH:mm:ss
m, M MMMM dd
r, R ddd, dd MMM yyyy HH':'mm':'ss 'GMT'
s yyyy'-'MM'-'dd'T'HH':'mm':'ss
3
t HH:mm
T HH:mm:ss
u yyyy'-'MM'-'dd HH':'mm':'ss'Z'
U dddd, dd MMMM yyyy HH:mm:ss
y, Y yyyy MMMM
The following table lists the available patterns which can be combined. The patterns are
case-sensitive; for example, "MM" is recognized, but "mm" is not. If the custom pattern
contains white-space characters or characters enclosed in single quotation marks, the output
string will also contain those characters. Characters not defined as part of a format pattern or
as format characters are reproduced literally.
Format Pattern Description
d The day of the month. Single-digit days will not have a leading zero.
dd The day of the month. Single-digit days will have a leading zero.
ddd The abbreviated name of the day of the week.
dddd The full name of the day of the week.
M The numeric month. Single-digit months will not have a leading zero.
MM The numeric month. Single-digit months will have a leading zero.
MMM The abbreviated name of the month.
MMMM The full name of the month.
y The year without the century. If the year without the century is less than 10, the
year is displayed with no leading zero.
yy The year without the century. If the year without the century is less than 10, the
year is displayed with a leading zero.
yyyy The year in four digits, including the century.
gg The period or era. This pattern is ignored if the date to be formatted does not
have an associated period or era string.
h The hour in a 12-hour clock. Single-digit hours will not have a leading zero.
hh The hour in a 12-hour clock. Single-digit hours will have a leading zero.
H The hour in a 24-hour clock. Single-digit hours will not have a leading zero.
HH The hour in a 24-hour clock. Single-digit hours will have a leading zero.
M The minute. Single-digit minutes will not have a leading zero.
MM The minute. Single-digit minutes will have a leading zero.
s The second. Single-digit seconds will not have a leading zero.
ss The second. Single-digit seconds will have a leading zero.
f The fraction of a second in single-digit precision. The remaining digits are
truncated.
ff The fraction of a second in double-digit precision. The remaining digits are
truncated.
fff The fraction of a second in three-digit precision. The remaining digits are
truncated.
ffff The fraction of a second in four-digit precision. The remaining digits are
truncated.
fffff The fraction of a second in five-digit precision. The remaining digits are
truncated.
ffffff The fraction of a second in six-digit precision. The remaining digits are truncated.
fffffff The fraction of a second in seven-digit precision. The remaining digits are
truncated.
t The first character in the AM/PM.
tt The AM/PM.
z The time zone offset ("+" or "-" followed by the hour only). Single-digit hours will
not have a leading zero. For example, Pacific Standard Time is "-8".
zz The time zone offset ("+" or "-" followed by the hour only). Single-digit hours will
4
have a leading zero. For example, Pacific Standard Time is "-08".
zzz The full time zone offset ("+" or "-" followed by the hour and minutes). Single-digit
hours and minutes will have leading zeros. For example, Pacific Standard Time
is "-08:00 ".
: The default time separator.
/ The default date separator.
%c Where c is a format pattern if used alone. The "%" character can be omitted if the
format pattern is combined with literal characters or other format patterns.
\c Where c is any character. Displays the character literally. To display the
backslash character, use "\\".
5
Custom Functions
Using Custom Functions
The Add-in provides various custom functions that you can use in worksheet cells using the
familiar Microsoft Excel =function notation. You can use these in any Microsoft Excel
worksheet (not just in report definitions).
You can see the list of functions that are available by choosing Function from the Insert
menu to display Microsoft Excels Insert Function dialog and then choosing the User
Defined category from the list of function categories. All the PipelineStudio functions begin
with the characters PLS. However, no help is available for the PipelineStudio functions
through this dialog.
Function Parameters
Most functions require parameters. Common parameters include:
strDataType the type of data to retrieve (report or trend)
strCasePath the path to the case for which you want data
strCase the path to the case for which you want data
If you specify report for strDataType, you get data at the report times.
If you specify trend for strDataType, you get data at the trend times.
Timestep Indexes
Timestep indexes are all 0-based. Timestep index 0 represents steady or the initial state,
while timestep index 1 represents the first transient step, and so on.
Getting data for the System Data object

To get system-wide data (that is, data for the System Data object type), use the object name
options.
Object Types
For functions that require an object type (for example, PLSAttributeNamesAvailableV), you
can use specific object types, for example Pipe.
You can also use names of groups of object types, e.g. Equipment. The available group
names are included in the list of object type names returned by the
PLSObjectTypesAvailableV and PLSObjectTypesAvailableH functions and can also be
obtained from the PLSObjectTypeGroupsAvailableV and PLSObjectTypeGroupsAvailableH
functions.
Function List
Most functions typed as returning String or Variant return an error message if an error
occurs.
PLSAttributeNamesAvailableH(strDataType As String, ByVal strCasePath As String,

ByVal strCase As String, ByVal strObjType As String) As Variant
Similar to PLSAttributeNamesAvailableV except that the returned array is a horizontal
array.
Remarks:
It is expected that the V version of the function will be more useful.
6
This must be used from Microsoft Excel as an array function.
PLSAttributeNamesAvailableV(strDataType As String, ByVal strCasePath As String,

ByVal strCase As String, ByVal strCEType As String) As Variant
Returns the available attribute names for the specified object type unless there's an
error, in which case this returns a string starting with #ERROR.
Arguments:
Name Type Description
strDataType String The type of data to retrieve (report or trend)
strCasePath String Full path of case (e.g. "c:\temp6\Demo")
strCase String Name of the case
strObjType String The type of object for which you want attribute names.
Returns:
Returns the available attribute names for the specified object type.
Remarks:
PLSAttributeNamesAvailableV and PLSAttributeNamesUsedV return substantially the
same list. However, PLSAttributeNamesAvailableV may report some attributes that are
not actually available through the Add-in interface.
PLSAttributeNamesUsedH(strDataType As String, ByVal strCasePath As String, ByVal

strCase As String, ByVal strCEType As String) As Variant
Similar to PLSAttributeNamesUsedV except that the returned array is a horizontal array.
Remarks:
PLSAttributeNamesUsedV(strDataType As String, ByVal strCasePath As String, ByVal

strCase As String, ByVal strObjType As String) As Variant
Returns all the attribute names used in this case for the specified object type.
Arguments:
StrCase String Name of the case
Returns:
Returns all the attribute names used in this case for the specified object type.
Remarks:
7
PLSAttributeNamesAvailableV and PLSAttributeNamesUsedV return substantially the
same list. However, PLSAttributeNamesAvailableV may report some attributes that are
not actually available through the Add-in interface.
PLSIndexForTime(strDataType As String, strCasePath As String, strCase As String,

strTime As String) As Integer
Arguments:
StrTime Integer The time at which you want the value
Returns:
Returns the time corresponding to the time. If the time is not a valid timestep time, the
function returns -1.
PLSIsNewlyOpenedReportWorkbook(wb As Workbook) As Boolean

Returns True if the specified workbook is a newly-opened report workbook.
Arguments:
Wb Workbook The workbook to check.
Returns:
Returns True if the specified workbook is a newly-opened report workbook.
Remarks:
This function is designed for Energy Solutions internal use only.
PLSObjectTypesAvailableH(strDataType As String, ByVal strCasePath As String,

ByVal strCase As String) As Variant
Similar to PLSObjectTypesAvailableV except that the returned array is a horizontal array.
Remarks:
PLSObjectTypesAvailableV(strDataType As String, ByVal strCasePath As String,

ByVal strCase As String) As Variant
Returns all the object types available for this case.
Arguments:
8
Returns:
Returns all the object types available for this case.
Remarks:
1. This must be used from Microsoft Excel as an array function.
2. This function includes groups of object types in the returned list, whereas the
PLSObjectTypesUsedV and PLSObjectTypesUsedH functions do not.
PLSObjectTypesUsedH(strDataType As String, ByVal strCasePath As String, ByVal

strCase As String) As Variant
Similar to PLSObjectTypesUsedV except that the returned array is a horizontal array.
Remarks:
PLSObjectTypesUsedV(strDataType As String, ByVal strCasePath As String, ByVal

strCase As String) As Variant
Returns all the object types used in this case.
Arguments:
Returns:
Returns all the object types used in this case.
Remarks:
1. This must be used from Microsoft Excel as an array function.
2. This function does not include groups of object types in the returned list, whereas
the PLSObjectTypesAvailableV and PLSObjectTypesAvailableH functions do.
PLSObjectNamesH(strDataType As String, ByVal strCasePath As String, ByVal

Similar to PLSObjectNamesV except that the returned array is a horizontal array.
Remarks:
PLSObjectNamesV(strDataType As String, ByVal strCasePath As String, ByVal

Returns all the names of all objects of the specified type in this case.
9
Arguments:
Returns:
Returns all the names of all objects of the specified type in this case.
Remarks:
PLSObjectCount(strDataType As String, ByVal strCasePath As String, ByVal strCase

As String, ByVal strObjType As String) As Variant
Returns the number of objects of the specified type in this case.
Arguments:
Returns:
Returns the number of objects of the specified type in this case.
PLSObjectTypeGroupsAvailableH(strDataType As String, ByVal strCasePath As

String, ByVal strCase As String) As Variant
Similar to PLSObjectTypeGroupsAvailableV except that the returned array is a horizontal
array.
Remarks:
PLSObjectTypeGroupsAvailableV(strDataType As String, ByVal strCasePath As

String, ByVal strCase As String) As Variant
Returns the names of the object type groups which are available for this case.
Arguments:
10
Returns:
Returns the names of the object type groups which are available for this case.
Remarks:
PLSProfileDistanceH(strDataType As String, strCasePath As String, strCase As

String, strObj As String) As Variant
Similar to PLSProfileDistanceV except that the returned array is a horizontal array.
Remarks:
PLSProfileDistanceHAtTime(strDataType As String, strCasePath As String, strCase

As String, strObj As String, strProp As String, strTime As String) As Variant
Similar to PLSProfileDistanceVAtTime except that the returned array is a horizontal
array.
Remarks:
PLSProfileDistanceHAtTimeIndex(strDataType As String, strCasePath As String,

strCase As String, strObj As String, strProp As String, nTimeIndex As Integer) As
Variant
Similar to PLSProfileDistanceVAtTimeIndex except that the returned array is a horizontal
array.
Remarks:
PLSProfileDistanceV(strDataType As String, strCasePath As String, strCase As

String, strObj As String) As Variant
Retrieves distance information for a PipelineStudio profile as a vertical array of doubles
unless there's an error, in which case this returns a string starting with #ERROR.
This version doesn't require a property or a time index to be specified.
Arguments:
StrObj String Pipe name (e.g. "Pipe0001")
This element must exist in the specified case.
11
Returns:
Returns the requested distance information.
Remarks:
PLSProfileDistanceVAtTime(strDataType As String, strCasePath As String, strCase As

String, strObj As String, strProp As String, strTime As String) As Variant
Retrieves distance information for a PipelineStudio profile at the specified as a
horizontal array of doubles unless there's an error, in which case this returns a string
starting with #ERROR.
Arguments:
StrProp String Property name (e.g. "Pressure (Tail)") (must be valid for
the type of object specified by strObj)
StrTime String The time at which you want the value
Returns:
Remarks:
PLSProfileDistanceVAtTimeIndex (strDataType As String, strCasePath As String,

strCase As String, strObj As String, strProp As String, nTimeIndex As Integer) As
Variant
Retrieves distance information for a PipelineStudio profile at the specified timestep index
as a horizontal array of doubles unless there's an error, in which case this returns a
string starting with #ERROR.
Arguments:
StrProp String Property name (e.g. "Pressure (Tail)") (must be valid for
12
nTimeIndex Integer The (0-based) index of the timestep at which you want
the value.
Returns:
Remarks:
PLSProfileHAtTime (strDataType As String, strCasePath As String, strCase As String,

strObj As String, strProp As String, strTime As String) As Variant
Similar to PLSProfileVAtTime except that the returned array is a horizontal array.
Remarks:
PLSProfileHAtTimeIndex(strDataType As String, strCasePath As String, strCase As

String, strObj As String, strProp As String, nTimeIndex As Integer) As Variant
Similar to PLSProfileVAtTimeIndex except that the returned array is a horizontal array.
Remarks:
PLSProfilePointCount(strDataType As String, strCasePath As String, strCase As

String, strPipe As String) As Variant
Returns the number of profile points in the specified pipe.
Arguments:
StrPipe String The name of the pipe.
Returns:
Returns the number of profile points in the specified pipe.
PLSProfileVAtTime (strDataType As String, strCasePath As String, strCase As String,

strObj As String, strProp As String, strTime As String) As Variant
Retrieves data for a PipelineStudio profile at the specified time as a vertical array of
doubles unless there's an error, in which case this returns a string starting with #ERROR.
Arguments:
13
strProp String Property name (e.g. "Pressure (Tail)") (must be valid for
strTime String The time at which you want the value
Returns:
Returns the requested profile information.
Remarks:
PLSProfileVAtTimeIndex(strDataType As String, strCasePath As String, strCase As

String, strObj As String, strProp As String, nTimeIndex As Integer) As Variant
Retrieves data for a PipelineStudio profile at the specified timestep index as a vertical
array of doubles unless there's an error, in which case this returns a string starting with
#ERROR.
Arguments:
the value.
Returns:
Returns the requested profile information.
Remarks:
PLSSelectedTime(strDataType As String, strCasePath As String, strCase As String)

As String
Arguments:
14
Returns:
Returns the selected time for the specified case.
PLSSelectedTimeIndex(strDataType As String, strCasePath As String, strCase As

String) As Variant
Arguments:
Returns:
Returns the selected time index (0-based) for the specified case.
PLSSetSelectedTime(strDataType As String, strCasePath As String, strCase As

String, strNewTime As String) As String
Sets the selected time for the specified case.
Arguments:
strNewTime String The new selected time (which should be a valid time for
that case)
Returns:
Returns a blank string if it worked, otherwise returns an error message that the new time
is not valid.
Remarks:
This function is provided principally so that you can write your own macros rather than
using this function directly from a worksheet. There are some considerations to be aware
of when using this function:
1. Don't use more than one on a sheet
2. You should probably force a sheet recalculation using Microsoft Excel's
Calculate worksheet function since there are some recalculation ordering
issues involved here
PLSSetSelectedTimeIndex(strDataType As String, strCasePath As String, strCase As

String, nNewTimeIndex As Integer) As String
Sets the selected time index (0-based) for the specified case.
15
Arguments:
nNewTimeIndex Integer The new (0-based) selected time index (which should
be a valid time index for that case)
Returns:
Returns a blank string if it worked, otherwise returns an error message that the new time
is not valid.
Remarks:
This function is provided principally so that you can write your own macros rather than
using this function directly from a worksheet. There are some considerations to be aware
of when using this function:
1. Don't use more than one on a sheet
2. You should probably force a sheet recalculation using Microsoft Excel's
Calculate worksheet function since there are some recalculation ordering
issues involved here
PLSTimeForIndex(strDataType As String, strCasePath As String, strCase As String,

nTimeIndex As Integer) As Variant
Arguments:
nTimeIndex Integer (0-based) index of the timestep at which you want the
value
Returns:
Returns the time corresponding to the specified (0-based) timestep index.
PLSTimeIndexesH(strDataType As String, strCasePath As String, strCase As String)

As Variant
Similar to PLSTimeIndexesV except that the returned array is a horizontal array.
Remarks:
16
PLSTimeIndexesV(strDataType As String, strCasePath As String, strCase As String)
As Variant
Arguments:
Returns:
Returns the list of (0-based) time indexes for the specified case.
Remarks:
PLSTimesH(strDataType As String, strCasePath As String, strCase As String) As

Variant
Similar to PLSTimesV except that the returned array is a horizontal array.
Remarks:
PLSTimestepCount(strDataType As String, strCasePath As String, strCase As String)

As Variant
Arguments:
Returns:
Returns the number of timesteps in the specified case.
PLSTimesV(strDataType As String, strCasePath As String, strCase As String) As

Variant
Arguments:
Returns:
Returns the list of times for the specified case as an array of strings.
17
Remarks:
PLSUnitCategoryFromObjectName(strDataType As String, strCasePath As String,

strCase As String, strObj As String, strProp As String) As String
Arguments:
strObj String Network element name (e.g. "Pipe0001")
Returns:
Returns the unit category for the specified object and property in the specified case.
PLSUnitCategoryFromObjectType(strDataType As String, strCasePath As String,

strCase As String, strObjType As String, strProp As String) As String
Arguments:
strObjType String Network element type (e.g. "Pipe").
This must be a valid object type.
Returns:
Returns the unit category for the specified object type and property in the specified case.
PLSUnitsFromObjectName(strDataType As String, strCasePath As String, strCase As

String, strObj As String, strProp As String) As String
Arguments:
18
Returns:
Returns the units for the specified object and property in the specified case.
PLSUnitsFromObjectType(strDataType As String, strCasePath As String, strCase As

String, strObjType As String, strProp As String) As String
Arguments:
strObjType String Network element type (e.g. "Pipe").
This must be a valid object type.
Returns:
Returns the units for the specified object type and property in the specified case.
PLSUnitsFromCategory(strDataType As String, strCasePath As String, strCase As

String, strUnitCategory As String) As String
Arguments:
strUnitCategory String The unit category for which we want the units
(e.g. Pressure)
Returns:
Returns the units for the specified unit category in the specified case.
PLSValue(strDataType As String, strCasePath As String, strCase As String, strObj As

String, strProp As String) As Variant
Retrieves a PipelineStudio value at the currently-selected time for the case.
Arguments:
19
Returns:
Returns the specified value at the currently-selected time for the case.
PLSValueAtTime(strDataType As String, strCasePath As String, strCase As String,

strObj As String, strProp As String, strTime As String, Optional nDecimals As Variant)
As Variant
Retrieves a PipelineStudio value at the specified time.
Arguments:
strTime String The time at which you want the value
nDecimals Integer (Optional) Number of decimal places
Returns:
Returns the specified value at the specified time.
PLSValueAtTimeIndex(strDataType As String, strCasePath As String, strCase As

String,
strObj As String, strProp As String, nTimeIndex As Integer) As Variant
Retrieves a PipelineStudio value at the specified timestep index.
Arguments:
the value.
20
Returns:
Returns the specified value at the specified (0-based) timestep index.
PLSValueStr(strDataType As String, strCasePath As String, strKey As String) As

Variant
Retrieves a PipelineStudio value from a string key.
Arguments:
strKey String Key with the form:
timestamp$casename:object:property
where timestamp may be:
omitted, meaning use the currently-selected time
a (0-based) integer, meaning use that timestep
index
a time , meaning use that timestep time
Returns:
Returns the specified value.
PLSAlarms(strCasePath As String, strCase As String) As Variant

Retrieves all PipelineStudio alarms.
Arguments:
Returns:
Returns array of Strings containing alarm information.
PLSAlarmsCount(strCasePath As String, strCase As String) As Variant

Retrieves the number of PipelineStudio alarms.
Arguments:
Returns:
Returns the number of alarms.
21
PLSAlarmsIndex(strCasePath As String, strCase As String, nIndex As Integer) As
Variant
Retrieves a PipelineStudio alarms at a give zero based index.
Arguments:
nIndex Integer Zero based index of the alarm to retrieve
Returns:
Returns an alarms.
PLSAlarmProperty(strCasePath As String, strCase As String, strProperty As String)

As Variant
Retrieves give property of all PipelineStudio alarms.
Arguments:
strProperty String Property of the alarm (Time, Level, Name or Message)
Returns:
Returns an array of strings containing the value for each alarm.
PLSAlarmPropertyIndex(strCasePath As String, strCase As String, strProperty As

String, nIndex As Integer) As Variant
Retrieves a value of a PipelineStudio alarms give the zero based index and property.
Arguments:
strProperty String Property of the alarm (Time, Level, Name or Message)
nIndex Integer Zero based index of the alarm
Returns:
Returns a value for the given property of the alarm at the given index.
Examples of using PipelineStudio Add-in functions

The workbook PLS Add-in Test.xls located in the PLStudio\Reporting directory has
examples of using most of the Add-in functions.
It is recommended that you put commonly-used arguments into their own cells and reference
them using Microsoft Excel cell references rather than hard coding the argument values into
the function calls. For example, most of the functions in the example workbook PLS Add-in
22
Test.xls reference the case path and case name stored in cells in the worksheet rather than
hard coding these in the function references.
Using Custom Functions from Microsoft Excel macros

You can also use the custom functions from Microsoft Excel macros that you write.
When using functions from macros, bear in mind the following:
1. For functions that return arrays, use the H versions of the array functions.
2. Most functions return a variant data type. This is so that the function can return an
error message in the case of an error and also return a blank value if the value is not
set. You will need to check for this when using the functions by checking to see if the
variant is of type String.
23
Running PipelineStudio Reports
Introduction
A report definition is a Microsoft Excel workbook with the file extension .rptdef.xls which
contains one or more cells containing special values called report tags. You can run a macro
which uses one or more report definition workbooks as input and which generates report
worksheets as output.
A report file is an XML file which contains a list of report definitions.
Report definitions are stored in the PLStudio\ReportData\Report Definitions
directory or any subdirectory of that directory.
Report files are stored in the PLStudio\ReportData\Reports directory.
Report workbooks are created by running a report, and are created in the same directory as
the case for which you are running the report.
How to run a report

You can run a report by:
1. Clicking the Run Report button on the Microsoft Excel PipelineStudio toolbar
2. Requesting that a report is run automatically at the end of a PipelineStudio steady-
state or transient simulation. You do this using the Reports tab in the Simulation
Options dialog in PipelineStudio.
3. Use the PipelineStudio Excel report template provided (see the PipelineStudio Excel
template section).
Running Reports How It Works

It is important when editing or creating new report definitions to understand the report
generation process. It is particularly important to have a good understanding of relative and
absolute cell references in Microsoft Excel.
The process of running a report is illustrated below:
Data Source:
PipelineStudio report data
for the selected case
Report definition
workbook
Report macro One or more

worksheets containing
Report definition PipelineStudio data
workbook
When you run a report, you are prompted to choose one or more report definitions as input
to the report (this list may be contained in a report.xml file, but ultimately it is a list of report
definitions). You are also prompted to choose a case path and name as the data source for
the report.
24
When a report macro runs, the following happens:
For each source report definition workbook:

One sheet is created in the output report workbook for each sheet in the report definition
workbook.
The report definition workbook is then closed.
Note that report definition workbooks are never changed by the report macros.
For each new sheet in the output report workbook:
For each report block:
For all specified timesteps (see note (1) below):
For all objects of the specified type (see note (2) below):
Copy the range within the report block,
substituting the value of any PLSDetailName,
PLSDetailNameHyperlink or PLSDetailTimeIndex tags
Next object
Next timestep
Next report block
Process PLSTimestep tags

Process PLSDocPath tags
Process PLSDocName tags
Process PLSReportGeneratedTime tags
Process PLSArgument tags
Next sheet
Next source report definition workbook
Notes:
(1) The For all specified timesteps loop is only used if there are one or more
PLSDetailTimeIndex tags in the report block
(2) The For all objects of the specified type loop is only used if there are one or more
PLSDetailName or PLSDetailNameHyperlink tags in the report block
(3) Mixing both PLSDetailName or PLSDetailNameHyperlink and
PLSDetailTimeIndex tags within a report block means that the block will be
repeated for all objects for all times. This could potentially create a very large
report!
Cell References in report definitions

The format of cell references used in report definitions is important in order to achieve
correct results when running reports. When a report is run, the macro copies each report
block for each object or timestep. Microsoft Excel will adjust cell references in the copied
report block depending on whether the cell references are absolute or relative cell
references.
It is worth bearing in mind that the way report blocks are copied when a report is run is
similar to using Microsoft Excels Auto Fill function, dragging the handle downwards.
25
The example report definitions included with PipelineStudio demonstrate how to use
absolute, relative and mixed cell references to achieve correct results.
Expansion of profile functions in Pipe report blocks

If you use the following profile functions in a single cell in a pipe report block, they are
automatically expanded to cover all profile points in the pipe for that report block:
PLSProfileDistanceV
PLSProfileDistanceVAtTime
PLSProfileDistanceVAtTimeIndex
PLSProfileVAtTime
PLSProfileVAtTimeIndex
Expansion of alarm function that return arrays

If you use the following alarm functions in a single cell, they are automatically expanded
include all alarms:
PLSAlarms
PLSAlarmProperty
Report Tags
Report tags are used in report definition worksheets. Report tags are cells containing text
that the report generation macros recognize and process into values. You place report tags
in report definition workbooks and these are replaced by the report generation macros in the
corresponding generated report worksheets - in some cases by a blank cell, sometimes by a
Microsoft Excel hyperlink and sometimes by other text.
The available report tags are listed below. Unless otherwise specified, the tag appears on its
own in a cell. If one or more arguments are specified, these are generally delimited by
spaces in the cell.
Report Tag List
PLSDetailStart and PLSDetailEnd

PLSDetailStart and PLSDetailEnd tags must appear in matching pairs in the worksheet.
They do not have to be on the same row of the worksheet (although they may be).
A pair of PLSDetailStart and PLSDetailEnd tags creates a report block, which delimits
one or more rows of the worksheet which are duplicated for each object of the specified
type for which the report is run.
Arguments for PLSDetailStart:
Required? Type Description
Required String The type of network element (e.g. Supply) to which
the block applies
26
Required String Must be set to AllObjects or Normal .
AllObjects means that all objects of this type will be
reported in this report block, regardless of any list of
specific objects of this type that have been selected.
Normal means that if specific objects of this type
have been selected (or none), only the selected
objects will be reported in this report block.
Optional String Any text which is to appear in that cell in the final
report. It is not necessary to surround this text with
quotes.
Arguments for PLSDetailEnd:

Optional String Any text which is to appear in that cell in the final
report. It is not necessary to surround this text with
quotes.
Cell contents in the generated worksheet

Any text specified in the optional argument.
Remarks:
Use the Normal setting for PLSDetailStart tags unless you have a good reason to use
the AllObjects setting. In particular, any report which will be invoked via a hyperlink
should use the Normal setting, otherwise when you click on the hyperlink, all objects of
the type of object on which you clicked will be reported instead of just that object.
Restrictions:
1. Pairs of PLSDetailStart and PLSDetailEnd tags may not overlap.
2. There must be at least one row in the worksheet after the last PLSDetailEnd tag.
3. There may not be two PLSDetailStart tags in the same spreadsheet row.
4. PLSDetailStart and PLSDetailEnd tags must be used in cells on their own (not as
part of a formula).
Example:
PLSDetailStart Supply Normal This text remains in the cell
This would delimit the start of a report block which is repeated for all supplies for which
the report is run. In the final report, the cell in which this appears would contain the text
This text remains in the cell.
PLSDetailName
The name of the object to which the report block applies is substituted wherever a
PLSDetailName tag appears within a report block.
The name of the object to which the report block applies.
27
Remarks:
Using this tag within a report block means that the block will be repeated for all objects
specified when the report is run.
Restrictions:
The PLSDetailName tag must be used in a cell on its own (not as part of a formula).
PLSDetailNameHyperlink
A hyperlink containing the name of the object to which the report block applies is
substituted wherever a PLSDetailNameHyperlink tag appears within a report block.
Clicking on the hyperlink runs the linked report. For the type of object which was clicked,
only that object will be included in report blocks of that type.
Arguments:
Required String The name of the report definition to run when the
hyperlink is clicked. If the report definition is in a
subdirectory of the ReportData\Report Definitions
directory, then the subdirectory name should be
included (see the examples below).

A hyperlink containing the name of the object to which the report block applies.
Remarks:
Using this tag within a report block means that the block will be repeated for all objects
specified when the report is run.
Restrictions:
The PLSDetailNameHyperlink tag must be used in a cell on its own (not as part of a
formula).
Example:
PLSDetailNameHyperlink SupplyDetail.rptdef.xls
This would create a hyperlink which, when you clicked it, would run a report using the
SupplyDetail.rptdef.xls report definition.
PLSDetailNameHyperlink test\SupplyDetail.rptdef.xls
This would create a hyperlink which, when you clicked it, would run a report using the
SupplyDetail.rptdef.xls report definition stored in the
ReportData\Report Definitions\test directory.
PLSDetailTimeIndex
The timestep index to which the report block applies is substituted wherever a
PLSDetailTimeIndex tag appears within a report block.
The 0-based time index for the report block.
28
Remarks:
1. Using this tag within a report block means that the block will be repeated for all times.
2. The PLSDetailTimeIndex tag would normally be used in a cell on its own, but it may
also be used as part of a formula.
Example:
=PLSValueAtTimeIndex($E$3,$E$4,$B14,D$12,PLSDetailTimeIndex)
This would return the value of a property for the time to which the report block applies.
PLSRepeatStart and PLSRepeatEnd

PLSRepeatStart and PLSRepeatEnd tags must appear in matching pairs in the
worksheet. They do not have to be on the same row of the worksheet (although they will
usually be).
The purpose of these tags is to allow specification of formulas (totals, etc.) for a report
block which consists of a single row. A pair of these tags delimits one or more rows of
the worksheet which are removed from the generated report worksheet.
The cells are removed.
Restrictions:
1. Pairs of PLSRepeatStart and PLSRepeatEnd tags may not overlap.
2. A PLSRepeatStart tag may not appear on the same row as the next PLSDetail tag.
3. PLSRepeatStart and PLSRepeatEnd tags must be used in cells on their own (not as
part of a formula).
PLSObjectType
The type of the object to which the report block applies is substituted wherever a
PLSObjectType tag appears within a report block.
The type of the object to which the report block applies.
PLSDocPath
PLSDocPath tags are replaced in the generated worksheet by the path of the case for
which the report was run.
The path of the case for which the report was run.
Remarks:
The PLSDocPath tag may be used in a cell on its own or as part of a formula.
PLSDocName
PLSDocName tags are replaced in the generated worksheet by the name of the case for
The name of the case for which the report was run.
29
Remarks:
The PLSDocName tag may be used in a cell on its own or as part of a formula.
PLSTimestep
PLSTimestep tags are replaced in the generated worksheet by a hyperlink containing the
currently selected time for the case.
Clicking on the hyperlink displays a dialog from which you can choose the current time
for the case.
A hyperlink containing the currently selected time for the case.
Restrictions:
The PLSTimestep tag must be used in a cell on its own (not as part of a formula).
PLSReportGeneratedTime
PLSReportGeneratedTime tags are replaced in the generated worksheet by the time at
The time at which the report was run.
Remarks:
1. In a report definition worksheet, you should normally set the format of a cell which
contains a PLSReportGeneratedTime tag to a Date or Time format (using the
Number tab on the Format Cells menu item in Microsoft Excel).
2. The PLSReportGeneratedTime tag would normally be used in a cell on its own, but it
may also be used as part of a formula.
PLSArgument
PLSArgument tags specify arguments whose values are specified when a report was run
using the report definition containing the PLSArgument tags. The values are normally
specified by the user entering values on a dialog which appears when the report is run.
Arguments:
Required String The name of the argument.

The value of the argument.
Remarks:
The PLSArgument tag may be used in a cell on its own or as part of a formula.
Example:
PLSArgument HighPressure
This would create an argument named HighPressure for which the user is prompted to
enter a value when a report is run using that report definition.
30
Creating Report Definitions Other Information
Using PipelineStudio user defined functions
Report definition files normally contain PipelineStudio user defined functions (see separate
section describing the functions which are available).
The PipelineStudio Add-in will not evaluate PipelineStudio user defined functions in a report
definition worksheet. The functions are only evaluated in normal worksheets. This makes it
easier to edit report definition worksheets.
Using Microsoft Excel formulas

You can use Microsoft Excel formulas in report definitions to display the result of a
calculation involving cells which use PipelineStudio user defined functions. For example, you
could create a formula which calculates the pressure drop per mile based on the upstream
and downstream pressures in a pipe and the length of the pipe.
Setting the number of decimal places in reports

You can use Microsoft Excels regular built-in formatting capabilities to do things like set the
number of decimal places for a given column in a report. You would do this by editing the
report definition and using the Number tab on the Format Cells menu item in Microsoft
Excel.
PipelineStudio Excel Template

The PipelineStudio add-in includes a template for creating PipelineStudio reports. Choose
File New in Microsoft Excel and then:
Use the New Workbook task pane to select PLSReport.xlt from the New from
template section.
A new workbook is created and a report is run in the normal manner.
Integration with PipelineStudio

PipelineStudio Reporting Options
By default at installation, PipelineStudio will run reports automatically at the end of a
transient simulation but not at the end of a steady-state simulation. You can change these
settings by using the Reports tab on the Simulation Options dialog in PipelineStudio.
When choosing a report to be run automatically by PipelineStudio, you must choose a report
file and not just a report definition file.
The Reports tab allows you to specify the times at which report data is generated during a
transient simulation. Steady-state report data is always generated.
See the help in PipelineStudio for description of the other options available on the Reports
tab).
Running reports on demand from PipelineStudio

Once a simulation is complete, you can run new reports (or re-run a report) using the
Create/Run menu item on the Report menu. You do not need to re-run the simulation in
order to re-run a report or run a new report.
31
Miscellaneous Information
The PipelineStudio Microsoft Excel Interface: Other Uses
The PLSReportArguments.xml file and RunPLSExcelReports program are used internally
by PipelineStudio to transfer data between PipelineStudio and Microsoft Excel and to run
Excel reports from PipelineStudio. A similar process could also be used by other external
programs to automate the reporting process.
This is not something for which we currently offer detailed technical support, but if you call
PipelineStudio Technical Support, we can discuss using this interface for your customized
situation.
Temporary files generated by Microsoft Excel

You might find various vb0000.tmp files in the PLStudio\ReportData\Report
Definitions directory (where 0000 is a number). It is safe to delete these files, which are
created by Microsoft Excel.
Troubleshooting
Should you encounter any problems please contact the PipelineStudio technical support
team at ESI.Support@Emerson.com.
Notation
PipelineStudio, TNet and Energy Solutions are registered trademarks of Energy Solutions International.
Windows, Excel and SQL Server are registered trademarks of Microsoft Corporation.
Intel is a registered trademark of Intel Corporation.
SentinelRMS* 1989-2008 SafeNet, Inc. All rights reserved
SafeNet, Sentinel, SentinelLM, and Sentinel RMS are either trademarks or registered trademarks of SafeNet, Inc.
All other product names referenced herein are trademarks or registered trademarks of their respective
manufacturers.
32

Pipeline Studio Excel Add-In User Documentation

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Pipeline Studio Excel Add-In User Documentation

Uploaded by

Copyright:

Available Formats

PipelineStudio Excel Add-in User Guide

Energy Solutions logo button

Run Report button

This button runs a PipelineStudio report.

Add Times button

This button creates a timestep hyperlink in a cell.

Reload Data button

Display Error Messages Option

Format Character Example Format Pattern

Getting data for the System Data object

PLSAttributeNamesAvailableH(strDataType As String, ByVal strCasePath As String,

PLSAttributeNamesAvailableV(strDataType As String, ByVal strCasePath As String,

PLSAttributeNamesUsedH(strDataType As String, ByVal strCasePath As String, ByVal

PLSAttributeNamesUsedV(strDataType As String, ByVal strCasePath As String, ByVal

PLSIndexForTime(strDataType As String, strCasePath As String, strCase As String,

PLSIsNewlyOpenedReportWorkbook(wb As Workbook) As Boolean

PLSObjectTypesAvailableH(strDataType As String, ByVal strCasePath As String,

PLSObjectTypesAvailableV(strDataType As String, ByVal strCasePath As String,

PLSObjectTypesUsedH(strDataType As String, ByVal strCasePath As String, ByVal

PLSObjectTypesUsedV(strDataType As String, ByVal strCasePath As String, ByVal

PLSObjectNamesH(strDataType As String, ByVal strCasePath As String, ByVal

PLSObjectNamesV(strDataType As String, ByVal strCasePath As String, ByVal

PLSObjectCount(strDataType As String, ByVal strCasePath As String, ByVal strCase

PLSObjectTypeGroupsAvailableH(strDataType As String, ByVal strCasePath As

PLSObjectTypeGroupsAvailableV(strDataType As String, ByVal strCasePath As

PLSProfileDistanceH(strDataType As String, strCasePath As String, strCase As

PLSProfileDistanceHAtTime(strDataType As String, strCasePath As String, strCase

PLSProfileDistanceHAtTimeIndex(strDataType As String, strCasePath As String,

PLSProfileDistanceV(strDataType As String, strCasePath As String, strCase As

PLSProfileDistanceVAtTime(strDataType As String, strCasePath As String, strCase As

PLSProfileDistanceVAtTimeIndex (strDataType As String, strCasePath As String,

PLSProfileHAtTime (strDataType As String, strCasePath As String, strCase As String,

PLSProfileHAtTimeIndex(strDataType As String, strCasePath As String, strCase As

PLSProfilePointCount(strDataType As String, strCasePath As String, strCase As

PLSProfileVAtTime (strDataType As String, strCasePath As String, strCase As String,

PLSProfileVAtTimeIndex(strDataType As String, strCasePath As String, strCase As

PLSSelectedTime(strDataType As String, strCasePath As String, strCase As String)

PLSSelectedTimeIndex(strDataType As String, strCasePath As String, strCase As

PLSSetSelectedTime(strDataType As String, strCasePath As String, strCase As

PLSSetSelectedTimeIndex(strDataType As String, strCasePath As String, strCase As

PLSTimeForIndex(strDataType As String, strCasePath As String, strCase As String,

PLSTimeIndexesH(strDataType As String, strCasePath As String, strCase As String)

PLSTimesH(strDataType As String, strCasePath As String, strCase As String) As

PLSTimestepCount(strDataType As String, strCasePath As String, strCase As String)

PLSTimesV(strDataType As String, strCasePath As String, strCase As String) As

PLSUnitCategoryFromObjectName(strDataType As String, strCasePath As String,

PLSUnitCategoryFromObjectType(strDataType As String, strCasePath As String,

PLSUnitsFromObjectName(strDataType As String, strCasePath As String, strCase As

PLSUnitsFromObjectType(strDataType As String, strCasePath As String, strCase As

PLSUnitsFromCategory(strDataType As String, strCasePath As String, strCase As

PLSValue(strDataType As String, strCasePath As String, strCase As String, strObj As

PLSValueAtTime(strDataType As String, strCasePath As String, strCase As String,

PLSValueAtTimeIndex(strDataType As String, strCasePath As String, strCase As

PLSValueStr(strDataType As String, strCasePath As String, strKey As String) As

PLSAlarms(strCasePath As String, strCase As String) As Variant

PLSAlarmsCount(strCasePath As String, strCase As String) As Variant

PLSAlarmProperty(strCasePath As String, strCase As String, strProperty As String)

PLSAlarmPropertyIndex(strCasePath As String, strCase As String, strProperty As

Examples of using PipelineStudio Add-in functions

Using Custom Functions from Microsoft Excel macros

How to run a report

Running Reports How It Works

Report macro One or more

For each source report definition workbook: