EDAS to PI Data Reconciliation Utility

E-DAS to PI
Data Reconciliation Utility

Version 1.1.0.105
Rev A

1

UniInt End-User Interface to the PI System

How to Contact Us

• Brazil
• Middle East/North Africa
• Republic of South Africa
• Russia/Central Asia

• South America/Caribbean
• Southeast Asia
• South Korea
• Taiwan

1

UniInt End-User Interface to the PI System

Table of Contents

Introduction

Reference Manuals

Supported Features

Running EPR Interactively

Connecting to the Servers

Specifying the Tag Criteria

Retrieving and Selecting Tags

Reconciling Tags

Logging Messages

Loading a Configuration File

Specifying Auto-Load Information

Determining Version

Running EPR Automatically

Setting up a Configuration File

Running EPR from the Command Line

Editing the PI Trust Table

Logging Messages in Automated Mode

Using EPR with the Windows Scheduler

Other Considerations

Appendix A: Using Time Offsets

Revision History

1

E-DAS to PI Data Reconciliation Utility1

Introduction

PI-EDAS is the interface between PI and the Environmental Systems Corporation (ESC) E-DAS software application. In the E-DAS system it is common for users to qualify data. For qualification, averaged data is processed with a set of certified calculations and the original data is then replaced with the qualified data for that time period. Then it is usual to send this updated data to PI. The EDAS to PI Data Reconciliation utility (EPR) is the tool with which a user can import edited (qualified) values from the EDAS system into PI after making manual qualification adjustments to the existing data. This action is termed reconciliation. With EPR, the user browses for the PI tags, given certain criteria such as point source, interface ID number, and E-DAS data type, and then updates them for given a time range (reconciliation period).

It is possible to use EPR interactively from a graphical user interface or to run it from the command line. When EPR runs from the command line, the user can schedule reconciliations to run automatically, reducing the need for manual intervention.

The PI-EDAS to PI Reconciliation Utility (EPR) has the following system requirements.

• Windows NT 4.0 / Windows2000 or later for Intel Processors.
• 64 MB RAM (Windows NT systems), or 128 MB RAM (Windows 2000 systems).
• 5 MB available disk space.
• Intel Pentium Processor.
• PI-API.
• PI-SDK.
• At least one remote E-DAS Expert for UNIX or E-DAS EMR for Windows Server and the E-DAS API. The E-DAS API must be resident on the same computer system that the EPR will run on.

Reference Manuals

OSIsoft

• Environmental System E-DAS interface to the PI System

Environmental Systems Corporation

• E-DAS Expert for UNIX User’s Guide, or E-DAS EMR for Windows User’s Guide
• E-DAS API Installation Instructions

Supported Features

* See paragraphs below for further explanation.

Source of Time Stamps

The time stamps used by the EPR Utility are taken from the E-DAS server and converted to UTC (Coordinated Universal Time) before being sent to the PI System. This ensures that all timestamps are unambiguous, even when transporting values and timestamps across time zone boundaries. When values are retrieved from the PI System their time stamps will be relative to the PI System’s local time. For example, if the EPR Utility reads a value from the E-DAS server with a time stamp of 6:00 P.M., and the E-DAS server is in the Eastern Standard Time Zone (UTC – 5), the time stamp will be adjusted to 11:00 P.M. and then sent to the PI System. If the PI System is in the Pacific Standard Time Zone (UTC – 8) it understands UTC and that the time stamp should actually be 3:00 P.M. Because we are using UTC this also handles cases where the E-DAS server and the PI System are observing different daylight savings time settings. Please see Appendix A: Using Time Offsets for more information on how time stamps are handled.

Vendor Software Required

The E-DAS API (provided by ESC) communicates only with the E-DAS Server. You must install the E-DAS API (edasapi.dll and supporting files) on the same PI-API node as the E-DAS to PI Reconciliation Utility (EPR).

1

E-DAS to PI Data Reconciliation Utility1

Running EPR Interactively

The E-DAS to PI Data Reconciliation Utility (EPR) supports two modes of operation, interactive operation and automated operation.

• For interactive operation the user must start the application and do all required operations manually. This operation is described in this section.
• For Automated operation the user must start EPR from the command line using parameters that specify a configuration file. Automated operation, described in the “Running EPR Automatically” section, requires no further intervention on the part of a user.

To start EPR interactively, follow the steps below.

1. On the Start menu, point to Programs.
2. Point to PI System and click E-DAS to PI Reconciliation Utility. The E-DAS Reconciliation Utility dialog box appears as shown below.

Connecting to the Servers

After starting EPR, you need to connect to PI and the EDAS servers. Follow the steps below.

1. Connect to PI by clicking the PI Connections button, as shown below. The Connections dialog box appears.

1. If your desired PI Server appears in the Servers field, select it and click Connect. If your desired PI server is not in the list, click Add to define a new connection. After you click Connect and close the Connections dialog box, the PI Server appears in the Active PI Server list with the status Connected, as shown below. This is the PI Server that will be used for reconciliation.

Note: To connect automatically to this PI Server each time you start EPR, select the Reconnect each time EPRUtil is startedcheckbox.

After you connect to the PI Server, connect to the E-DAS server. Follow the steps below.

1. Connect to the EDAS Server by entering the server name in the E-DAS Server field, as shown below.
2. Click Connect. A Connected message appears in the Status field.

Note: To connect automatically to this EDAS Server each time you start EPR, select the Reconnect each time EPRUtil is startedcheckbox.

Specifying the Tag Criteria

After you have connected to the PI and E-DAS servers, you need to display the tags that you want to update in PI. Follow the steps below.

1. Click the Tag Search Criteria tab.

1. Select the Point Source or enter the Point Source value manually.
2. Select the Interface Instance ID # or enter the ID # manually.

1. Select the E-DAS data types to search for.
2. Enter a value for the Average value starting system digital state.
3. To retrieve the tags, see the Retrieving and Selecting Tags section.

Retrieving and Selecting Tags

This section assumes that you have already specified the tag search criteria as described in the “Specifying the Tag Criteria” section.

1. Click the Reconciliation tab.
2. Enter a search maskin the Tag Mask field to restrict the tag search. If you leave this field blank or enter an asterisk (*), the search returns all tags specified on the Tag Search Criteria tab. If you enter text into the Tag Mask field with no asterisk (*) the search attempts to return a tag with a name matching the text exactly as it is typed. In short, the asterisk (*) is used to specify a “wildcard” character or string.

Examples of using the Tag Mask functionality:

1. After entering the Tag Mask, click Get Tags to retrieve the tags from PI. The tag names appear in the Tag Selection field. To stop the tag search, click Stop.

The figure below shows the use of the Tag Mask feature to restrict the tags returned to those that have a name that begins with the text EDAS.

1. To select a tag for reconciliation, click its name in the Tag Selection field. A selected tag will be colored blue. You can also click Expanded View and select tags in the dialog box that appears. To select multiple tags press and hold the control (Ctrl) key while clicking each additional tag name. To select tags on multiple adjacent rows, click the uppermost or lowermost row and press and hold the shift key while clicking another row.

Click a heading (Tag Name, Extended Descriptor, etc.) to sort the entire list of tags based on the values within that column.

1. To reconcile the tags, see the Reconciling Tags section.

Reconciling Tags

This section assumes that you have already retrieved and selected the tags as described in the “Retrieving and Selecting Tags” section.

To reconcile the tags (update them in the PI database), follow the steps below.

1. Enter a starting and ending time in the Starting Time and Ending Time fields. The times can each be relative times or absolute times.

An absolute time must take the following form: dd-mmm-yy hh:mm:ss where dd represents a 2 digit day, mmm represents a 3 letter English abbreviation for a month such as Jan for January or Feb for February, yy represents a 2 digit year, hh represents a 1 or 2 digit hour, mm represents a 2 digit minute, and ss represents a 2 digit second (seconds may be omitted if desired). If the entire hour, minute, second portion of the timestamp is omitted it will default to midnight (00:00:00) but will not be displayed.

In the use of relative times, note that the asterisk character (*)will resolve to the current local time as defined on the EPR computer system. Therefore *-7d resolves to the time “Now” minus 7 days, or seven days previous to the current time. For example, if the starting time is specified as *-72h and the ending time is specified with an asterisk (*), the reconciliation updates data from the previous 72 hours until “Now”, where “Now” is the current local time for the computer running EPR.

Be sure that the starting time is before the ending time, especially when you are using one relative time and one absolute time, or two relative times.

1. This step involves the Time Offset setting, which is optional, and not recommended for most cases. If you are running EPR in a situation where the EDAS Server is in a different time zone than the PI Server, and/or the PI Server observes daylight savings time (while the E-DAS server does not), and you wish to translate timestamps to be relative to a time zone other than that on the E-DAS server, than you may use the Time Offset feature to accomplish this. To do so, select the Use Time Offset checkbox as shown below. The Time Offset field and its associated Set button become available.

Note: This is a major change from previous versions of the E-DAS to PI Reconciliation Utility. This version of EPR internally converts all timestamps to UTC (Coordinated Universal Time) before sending values from E-DAS to PI. This maintains unique time stamps across time zones and DST settings making the use of the Time Offset undesirable in most cases. More detailed information about using the Time Offset functionality can be found in Appendix A.

Enter the time offset. Time offsets should be entered and viewed as being relative to the E-DAS Server. Only hour and minute intervals are recognized, and they must be formatted in the form of a plus or minus, followed by an integer, immediately followed by an h, for hours, or m, for minutes. For example, enter +1h if the E-DAS Server is 1 hour ahead of the PI Server. Enter -5h if the E-DAS Server is 5 hours behind the PI Server.

Click the Set button associated with the Time Offset field. EPR validates the time offset. EPR also validates the time offset prior to each reconcile; that is, when the Reconcile button is clicked or when an automated reconcile is executed.

1. Click Reconcile to update the tags in PI.

The Status field displays the progress and any error messages that occur. Messages from the Status field are also sent to the pipc log file. To help with readability EPR messages in the pipc log file are prefaced with “EPR>”.

Logging Messages

EPR logs its messages to anEPR-specific log file in a folder named “Logs”, to the PIPC.log file of the Active PI Server, and to the Status field of EPR when it is running in interactive mode. The EPR-specific log file is named EPRUtil_dd-mm-yyyy.log where dd represents a 1 or 2 digit day, mm represents a 1 or 2 digit month, and yyyy represents a 4 digit year. Each log file contains only the messages for the day which it represents. EPR creates a new log file each day, but only if EPR is run on that day and messages need to be logged.

EPR always writes to the PIPC.log file of the Active PI Server when a connection to a PI server exists. This behavior cannot be altered. However, it is possible to configure how EPR handles its own log files.

To access thelogging options, on the Options menu click Logging. The EPRUtilLogging dialog box appears, as shown below:

To disable the logging feature, select the Enable EPRUtil Logging checkbox to remove the check.

Specify the lifetime for the log files by entering a value in the Number of Days to Maintain Log Files field. This allows you to control the amount of disk space used for EPR logging and makes it easier to find logs for a specific date. The number of log files maintained in the Logs folder will not exceed the value specified in this field.

Note: When you need to create a new log file, any file in the Logs folder with a name matching the form of EPRUtil_*.Log, and that was created prior to the length of time specified in the Number of Days to Maintain Log Files field will be deleted.

To prevent the deletion of a log file, rename it so that it does not match the form of EPRUtil_*.Log, or remove it from the Logs directory.

EPR-specific log files that are currently in the Logs folder appear in the Current Log Files field. To open a file in Notepad, double-click the name.

Loading a Configuration File

It is possible to save an EPR configuration and reload it instead of choosing options manually every time you need to reconcile data. To do this, on the File menu, click Save Configuration and enter a file name for the configuration file. To load the configuration, on the File menu, click Load Configuration and select the configuration file to load.

When a configuration file is saved any specified PI tags, along with their configuration, are saved in the configuration file. Then when an EPR reconcile is executed using the saved EPR configuration the specified PI tags, and their configurations, are read from the file so that the utility knows which tags to reconcile. The current PI tag configuration for each specified PI tag is then pulled from the PI Server and compared against the PI tag configuration saved in the EPR Configuration file. If a change is detected a message will be written to the log files and the reconciliation will be marked as failed; that is it will return a status of 0x01. However, the reconciliation will be attempted for each specified PI tag, even those where a change has been detected, using the configuration read from the PI Server. This mechanism is in place to detect changes in tag configuration and report them to the user. It will not prevent the reconciliation from executing. To prevent the messages from being displayed the user should run “Get Tags” to get the latest tag configuration from the PI Server and re-save the EPR configuration file.