Pipeline Studio Excel Add-In User Documentation
Pipeline Studio Excel Add-In User Documentation
Pipeline Studio Excel Add-In User Documentation
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:
This button displays an About dialog box showing the version number of the Add-in and
hyperlinks for contacting Energy Solutions.
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.
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.
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.
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.
6
This must be used from Microsoft Excel as an array function.
Returns:
Returns the available attribute names for the specified object type.
Remarks:
This must be used from Microsoft Excel as an array function.
PLSAttributeNamesAvailableV and PLSAttributeNamesUsedV return substantially the
same list. However, PLSAttributeNamesAvailableV may report some attributes that are
not actually available through the Add-in interface.
Returns:
Returns all the attribute names used in this case for the specified object type.
Remarks:
This must be used from Microsoft Excel as an array function.
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.
Returns:
Returns the time corresponding to the time. If the time is not a valid timestep time, the
function returns -1.
Returns:
Returns True if the specified workbook is a newly-opened report workbook.
Remarks:
This function is designed for Energy Solutions internal use only.
8
StrCase String Name of the case
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.
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.
9
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 all the names of all objects of the specified type in this case.
Remarks:
This must be used from Microsoft Excel as an array function.
Returns:
Returns the number of objects of the specified type in this case.
10
Returns:
Returns the names of the object type groups which are available for this case.
Remarks:
This must be used from Microsoft Excel as an array function.
11
Returns:
Returns the requested distance information.
Remarks:
This must be used from Microsoft Excel as an array function.
Returns:
Returns the requested distance information.
Remarks:
This must be used from Microsoft Excel as an array function.
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
StrObj String Pipe name (e.g. "Pipe0001")
This element must exist in the specified case.
StrProp String Property name (e.g. "Pressure (Tail)") (must be valid for
the type of object specified by strObj)
12
nTimeIndex Integer The (0-based) index of the timestep at which you want
the value.
Returns:
Returns the requested distance information.
Remarks:
This must be used from Microsoft Excel as an array function.
Returns:
Returns the number of profile points in the specified pipe.
Arguments:
Name Type Description
strDataType String The type of data to retrieve (report or trend)
13
strCasePath String Full path of case (e.g. "c:\temp6\Demo")
strCase String Name of the case
StrObj String Pipe name (e.g. "Pipe0001")
This element must exist in the specified case.
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:
Returns the requested profile information.
Remarks:
This must be used from Microsoft Excel as an array function.
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
StrObj String Pipe name (e.g. "Pipe0001")
This element must exist in the specified case.
strProp String Property name (e.g. "Pressure (Tail)") (must be valid for
the type of object specified by strObj)
nTimeIndex Integer The (0-based) index of the timestep at which you want
the value.
Returns:
Returns the requested profile information.
Remarks:
This must be used from Microsoft Excel as an array function.
14
strCase String Name of the case
Returns:
Returns the selected time for the specified case.
Returns:
Returns the selected time index (0-based) for the specified 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
15
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
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
Returns:
Returns the time corresponding to the specified (0-based) timestep index.
16
PLSTimeIndexesV(strDataType As String, strCasePath As String, strCase As String)
As Variant
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
Returns:
Returns the list of (0-based) time indexes for the specified case.
Remarks:
This must be used from Microsoft Excel as an array function.
Returns:
Returns the number of timesteps in the specified case.
Returns:
Returns the list of times for the specified case as an array of strings.
17
Remarks:
This must be used from Microsoft Excel as an array function.
Returns:
Returns the unit category for the specified object and property in the specified case.
Returns:
Returns the unit category for the specified object type and property in the specified case.
18
strProp String Property name (e.g. "Pressure (Tail)") (must be valid for
the type of object specified by strObj)
Returns:
Returns the units for the specified object and property in the specified case.
Returns:
Returns the units for the specified object type and property in the specified case.
Returns:
Returns the units for the specified unit category in the specified case.
19
strObj String Network element name (e.g. "Pipe0001")
This element must exist in the specified case.
strProp String Property name (e.g. "Pressure (Tail)") (must be valid for
the type of object specified by strObj)
Returns:
Returns the specified value at the currently-selected time for the case.
Returns:
Returns the specified value at the specified time.
20
Returns:
Returns the specified value at the specified (0-based) timestep index.
Returns:
Returns the specified value.
Returns:
Returns array of Strings containing alarm information.
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:
Name Type Description
strCasePath String Full path of case (e.g. "c:\temp6\Demo")
strCase String Name of the case
nIndex Integer Zero based index of the alarm to retrieve
Returns:
Returns an alarms.
Returns:
Returns an array of strings containing the value for each alarm.
Returns:
Returns a value for the given property of the alarm at the given index.
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.
Data Source:
PipelineStudio report data
for the selected case
Report definition
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:
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!
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.
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.
PLSDetailName
The name of the object to which the report block applies is substituted wherever a
PLSDetailName tag appears within a report block.
Cell contents in the generated worksheet
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? Type Description
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).
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.
Cell contents in the generated worksheet
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.
PLSObjectType
The type of the object to which the report block applies is substituted wherever a
PLSObjectType tag appears within a report block.
Cell contents in the generated worksheet
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.
Cell contents in the generated worksheet
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
which the report was run.
Cell contents in the generated worksheet
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.
Cell contents in the generated worksheet
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
which the report was run.
Cell contents in the generated worksheet
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? Type Description
Required String The name of the argument.
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.
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.
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