Historian SE

PI SERVER REFERENCE GUIDEPUBLICATION HSEPIS-RM020A-EN-E–September 2007

Historian SE

HSEPIS-RM020A-EN-E 8/8/07 10:41 AM

Contact Rockwell

Customer Support Telephone — 1.440.646.3434

Online Support — http://support.rockwellautomation.com

Copyright Notice

© 2007 Rockwell Automation Technologies, Inc. All rights reserved. Printed in USA.

This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation Technologies, Inc. Any reproduction and/or distribution without prior written consent from Rockwell Automation Technologies, Inc. is strictly prohibited. Please refer to the license agreement for details.

Trademark Notices

FactoryTalk, Rockwell Automation, Rockwell Software, the Rockwell Software logo are registered trademarks of Rockwell Automation, Inc.

The following logos and products are trademarks of Rockwell Automation, Inc.:

FactoryTalk Historian Site Edition (SE), RSView, FactoryTalk View, RSView Studio, FactoryTalk View Studio, RSView Machine Edition, RSView ME Station, RSLinx Enterprise, FactoryTalk Services Platform, and FactoryTalk Live Data.

The following logos and products are trademarks of OSIsoft, Inc.:

PI System, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK.

Other Trademarks

ActiveX, Microsoft, Microsoft Access, SQL Server, Visual Basic, Visual C++, Visual SourceSafe, Windows, Windows ME, Windows NT, Windows 2000, Windows Server 2003, and Windows XP are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Adobe, Acrobat, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

ControlNet is a registered trademark of ControlNet International.

DeviceNet is a trademark of the Open DeviceNet Vendor Association, Inc. (ODVA).

Ethernet is a registered trademark of Digital Equipment Corporation, Intel, and Xerox Corporation.

OLE for Process Control (OPC) is a registered trademark of the OPC Foundation.

Oracle, SQL*Net, and SQL*Plus are registered trademarks of Oracle Corporation.

All other trademarks are the property of their respective holders and are hereby acknowledged.

Restricted Rights Legend

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)

of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Warranty

This product is warranted in accordance with the product license. The product’s performance may be affected by system configuration, the application being performed, operator control, maintenance, and other related factors. Rockwell Automation is not responsible for these intervening factors. The instructions in this document do not cover all the details or variations in the equipment, procedure, or process described, nor do they provide directions for meeting every possible contingency during installation, operation, or maintenance. This product’s implementation may vary among users.

This document is current as of the time of release of the product; however, the accompanying software may have changed since the release. Rockwell Automation, Inc. reserves the right to change any information contained in this document or the software at anytime without prior notice. It is your responsibility to obtain the most current information available from Rockwell when installing or using this product.

Version: 9.00.05

PI Server Reference Guide Page iii

PREFACE – USING THIS GUIDE

About this Guide

The PI Server Reference Guide provides comprehensive information and instructions that System Administrators need to understand, plan, administer and troubleshoot the PI Server, PI subsystems, and PI System interfaces.

This guide includes the following topics:

Overview of all PI Databases

Data flow in the PI System

PI Point Classes and Attributes

Class Edit and Type Edit

Exception Reporting

Compression Testing

Security

SQL Subsystem

PI Time Format and Conversions

Overview of the PI Application Programming Interface (PI API)

This guide assumes that the System Administrator has a working understanding of PI Server tools and utilities such as PIConfig, PIDiag and PIArtool. For additional information about these command-line tools and other PI System setup and configuration procedures, see the PI Server System Management Guide.

For a broader overview of the PI System architecture and system administration, see Introduction to PI System Management.

Preface - Using this Guide

Page iv

The PI Server Documentation Set

The PI Server Documentation Set provides complete PI Server information and system management procedures. It includes seven user guides, described below. These documents are included on the FactoryTalk Historian SE installation CD under Redist > Docs

Title Subject Matter

Introduction to PI System Management

A guide to the PI Server for new users and administrators. It explains PI system components, architecture, data flow, utilities and tools. It provides instruction for managing points, archives, backups, interfaces, security and trusts, and performance. It includes a glossary and resource guide.

PI Server Installation and Upgrade Guide

A guide for installing, upgrading and removing PI Servers on Windows and UNIX platforms, including cluster and silent installations.

PI Server System Management Guide

An in-depth administration guide for the PI Server, including starting and stopping systems, managing the Snapshot, Event Queue and Data Archive, monitoring system health, managing backups, interfaces, security, and moving and merging servers. Includes comprehensive instructions for using command-line tools: PIConfig, PIDiag, and PIArtool, and in-depth troubleshooting and repair information.

PI Server Reference Guide

A comprehensive reference guide for the system administrator and advanced management tasks, including: databases; data flow; PI Point classes and attributes, class edit and type edit; exception reporting; compression testing; security; SQL subsystem; PI time format; and overviews of the PI API, and PI-SDK System Management Tool (SMT).

Auditing the PI Server

An administration guide that explains the Audit Database, which provides a secure audit trail of changes to PI System configuration, security settings, and Archive Data. It includes administration procedures to enable auditing, to set subsystem auditing mode, to create and archive database files, and to export audit records.

PI Server Applications User Guide

A guide to key add-on PI Server Applications: Performance Equations (PE), Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical Quality Control). Includes a reference guide for Performance Equations, and Steam calculation functions.

PINet and PIonPINet User Guide

A systems administration guide, including installation, upgrade and operations, for PINet for OpenVMS and PIonPINet, which support migration and interoperability between PI2 and PI3 Systems.


PI Server Reference Guide Page v

Conventions Used in this Guide This guide uses the following formatting and typographic conventions.

Format Use Examples

Title Case PI Client Tools PI System Elements PI Server Subsystems

Use the client tool, FactoryTalk Historian ProcessBook, to verify that all data has been recovered.

All incoming data is queued in the Event Queue by the Snapshot Subsystem.

Italic text Files, Directories, Paths Emphasis New Terms Fields References to a chapter or section

The backup script is located in the \PI\adm directory. Archive files can be either fixed or dynamic. The archive receiving current data is called the Primary Archive.

See Section 4.2, Create a New Primary Archive.

Bold Italic text References to a publication See the PI Server Reference Guide.

System and Application components: Subsystems Tools / Utilities Processes / Scripts / Variables Arguments / Switches / Options Parameters / Attributes / Values Properties / Methods / Events /

Functions

The Archive Subsystem, piarchss, manages data archives. Piarchss must be restarted for changes to take effect.

On UNIX, invoke site-specific startup script, pisitestart.sh, and on Windows, invoke pisrvsitestart.bat.

Three Point Database attributes affect compression: CompDev, CompMin, and CompMax. These are known as the compression specifications.

Procedures and Key Commands On the Tools menu, click Advanced Options. Press CTRL+ALT+DELETE to reboot

Bold text

Interface components Menus / Menu Items Icons / Buttons / Tabs Dialog box titles and options

Click Tools > Tag Search to open the Tag Search tool.

Click the Advanced Search tab. Use the search parameters PImean Value = 1.

Monospace

type:

"Consolas" font

Consolas monospace is used for: Code examples Commands to be typed on the command line (optionally with arguments or switches)

System input or output such as excerpts from log files and other data displayed in ASCII text

Bold consolas is used in the context of a paragraph

To list current Snapshot information every 5 seconds, use the piartool -ss command. For example:

Light Blue - Underlined

Links to URL / Web sites, and email addresses

http://support.rockwellautomation.com


Page vi

Related Documentation

Rockwell Automation provides a full range of documentation to help you understand and use the PI Server, PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client application has its own online help and/or user guide.

The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is recommended reading for PI Server system managers. Many PI Interfaces are based upon UniInt, and this guide provides a deeper understanding of principals of Interface design.

Using PI Server Tools

The PI Server provides two sets of powerful tools that allow system administrators and users to perform system administration tasks and data queries.

The PI Server includes many command-line tools, such as pidiag and piartool. The PI Server Documentation Set provides extensive instruction for performing PI Server administrative tasks using command-line tools.

The PI System Management Tools (SMT) is an easy-to-use application that hosts a variety of different plug-ins, which provide all the basic tools you need to manage a PI System. You access this set of tools through a single host application. This host application is sometimes referred to as the SMT Host, but it is more commonly called System Management Tools or SMT.

In addition to extensive online help that explains how to use all of the features in the SMT, the SMT includes the Introduction to PI System Management user guide.

PI Server Reference Guide Page vii

QUICK TABLE OF CONTENTS

Chapter 1. The PI Server ...............................................................................................................1

Chapter 2. PI Data Flow...............................................................................................................11

Chapter 3. PI Server Databases .................................................................................................21

Chapter 4. PI Point Classes and Attributes...............................................................................43

Chapter 5. PI Point Class Edit ....................................................................................................63

Chapter 6. PI Point Type Edit......................................................................................................89

Chapter 7. Exception Reporting and Compression Testing ...................................................95

Chapter 8. Security ....................................................................................................................103

Chapter 9. PI SQL Subsystem ..................................................................................................105

PI Server Reference Guide Page ix

TABLE OF CONTENTS

Preface – Using this Guide ..............................................................................................................iii

Table of Tables.................................................................................................................................xv

Table of Figures .............................................................................................................................xvii

Chapter 1. The PI Server ...............................................................................................................1 1.1 PI Server Subsystems.......................................................................................................1 1.2 Configuration and Administrative Utilities .....................................................................3

1.2.1 Using Command-Line Tools Remotely...................................................................4 1.2.2 Displaying the PI Version Number .........................................................................4 1.2.3 Checking Snapshot Values (apisnap and pisnap) .................................................5

1.3 Interfaces Installed with the PI Server.............................................................................5 1.3.1 Interfaces to Other Data Sources...........................................................................5

1.4 PI Application Programming Interface (API)...................................................................6 1.5 PI Directory Structure .......................................................................................................6

1.5.1 Windows Directory Structure..................................................................................6 1.5.2 Windows File System Concerns.............................................................................7 1.5.3 UNIX Directory Structure ........................................................................................8

Chapter 2. PI Data Flow...............................................................................................................11 2.1 Data Flow from Data Sources into the PI Archive........................................................11

2.1.1 The Snapshot .......................................................................................................13 2.1.2 The Archive Subsystem........................................................................................13

2.2 Data Retrieval from the Archive.....................................................................................15 2.2.1 The Archive Read Cache .....................................................................................15

2.3 PI Data Retrieval with Foreign Data Sources................................................................16 2.3.1 Point Configuration ...............................................................................................17 2.3.2 Retrieval of Snapshot Data...................................................................................18 2.3.3 Retrieval of Archive Data......................................................................................18 2.3.4 Archive Files .........................................................................................................19

Table of Contents

Page x

2.3.5 Exception Reporting .............................................................................................19 2.3.6 Compression ........................................................................................................20 2.3.7 Point Security .......................................................................................................20

Chapter 3. PI Server Databases .................................................................................................21 3.1 Point Database.................................................................................................................21 3.2 Data Archive.....................................................................................................................21

3.2.1 Archive Size Considerations ................................................................................22 3.3 Snapshot ..........................................................................................................................22 3.4 Annotations......................................................................................................................23

3.4.1 Annotation Files....................................................................................................23 3.5 Digital State Table ...........................................................................................................25

3.5.1 System State Set for All Points ............................................................................25 3.5.2 Defining a Custom Digital State Set .....................................................................26

3.6 Timeout Database............................................................................................................27 3.6.1 Table of Configurable Timeout Database Parameters.........................................27

3.7 Firewall Database ............................................................................................................40 3.8 Proxy Database................................................................................................................40 3.9 Trust Database.................................................................................................................40 3.10 User Database..................................................................................................................40 3.11 Group Database...............................................................................................................41 3.12 Module Database .............................................................................................................41 3.13 Batch Database................................................................................................................41 3.14 List of Database Files......................................................................................................41

Chapter 4. PI Point Classes and Attributes...............................................................................43 4.1 About Point Classes........................................................................................................43 4.2 Base Class Point Attributes ...........................................................................................44

4.2.1 Tag........................................................................................................................44 4.2.2 PtClassName........................................................................................................45 4.2.3 PointType..............................................................................................................45 4.2.4 NewTag ................................................................................................................47 4.2.5 Descriptor .............................................................................................................47 4.2.6 ExDesc .................................................................................................................47 4.2.7 TypicalValue .........................................................................................................47 4.2.8 DigitalSet ..............................................................................................................47 4.2.9 Zero ......................................................................................................................48 4.2.10 Span .....................................................................................................................48

Table of Contents

PI Server Reference Guide Page xi

4.2.11 Impact of Changing Zero and Span .....................................................................48 4.2.12 EngUnits ...............................................................................................................49 4.2.13 PointSource ..........................................................................................................49 4.2.14 SourceTag ............................................................................................................50 4.2.15 ExcDev, ExcMin, ExcMax and ExcDevPercent....................................................50 4.2.16 Scan Flag..............................................................................................................50 4.2.17 Compressing Flag ................................................................................................50 4.2.18 CompDev, CompMin, CompMax and CompDevPercent .....................................51 4.2.19 Archiving...............................................................................................................52 4.2.20 Step ......................................................................................................................52

4.3 Classic Point Class Attributes .......................................................................................54 4.3.1 Instrument Tag .....................................................................................................54 4.3.2 Location1, Location2, Location3, Location4, and Location5 ................................54 4.3.3 SquareRoot ..........................................................................................................55 4.3.4 UserInt1, UserInt2, UserReal1 and UserReal2 ....................................................55 4.3.5 Filtercode..............................................................................................................55 4.3.6 Totalcode..............................................................................................................55 4.3.7 Srcptid...................................................................................................................55 4.3.8 Convers ................................................................................................................56 4.3.9 Ranges of ExcMax and CompMax.......................................................................56

4.4 COM Connector Point Attributes ...................................................................................56 4.5 Default Values for Point Attributes................................................................................57 4.6 System-Assigned Attributes ..........................................................................................62

4.6.1 Creator..................................................................................................................62 4.6.2 CreationDate ........................................................................................................62 4.6.3 Changer ................................................................................................................62 4.6.4 ChangeDate .........................................................................................................62 4.6.5 PointID..................................................................................................................62 4.6.6 RecNo...................................................................................................................62

Chapter 5. PI Point Class Edit ....................................................................................................63 5.1 Introduction......................................................................................................................63 5.2 Overview...........................................................................................................................64 5.3 Attribute Sets Database Edit ..........................................................................................66

5.3.1 Attribute Set Creation ...........................................................................................66 5.3.2 Attribute Set Deletion............................................................................................69 5.3.3 Attribute Set Edit...................................................................................................70

Table of Contents

Page xii

5.4 Point Classes Database Edit ..........................................................................................76 5.4.1 Point Class Creation.............................................................................................76 5.4.2 Point Class Deletion .............................................................................................76 5.4.3 Point Class Edit ....................................................................................................77

5.5 Editing a Point’s Point Class Attribute..........................................................................82 5.5.1 Conversion of CC Class to and from a Native PI Class .......................................83

5.6 Point Database Audit ......................................................................................................83 5.6.1 Audit Records .......................................................................................................84

5.7 Thread-safety ...................................................................................................................86

Chapter 6. PI Point Type Edit......................................................................................................89 6.1 Introduction......................................................................................................................89 6.2 Error handling..................................................................................................................94

Chapter 7. Exception Reporting and Compression Testing ...................................................95 7.1 Exception Reporting .......................................................................................................95

7.1.1 ExcDev and ExcDevPercent ................................................................................97 7.1.2 ExcMin..................................................................................................................97 7.1.3 ExcMax.................................................................................................................97 7.1.4 Turning Off Exception Reporting ..........................................................................98

7.2 Compression Testing......................................................................................................98 7.2.1 Step Flag ............................................................................................................101

Chapter 8. Security ....................................................................................................................103 8.1 User Name and Password ............................................................................................103 8.2 Point Security.................................................................................................................103 8.3 Database Security .........................................................................................................103 8.4 Trust Access ..................................................................................................................104

Chapter 9. PI SQL Subsystem ..................................................................................................105 9.1 Architecture....................................................................................................................105

9.1.1 Statement Handles .............................................................................................105 9.1.2 Concurrency .......................................................................................................106

9.2 Differences between PI 2.x and PI 3.x .........................................................................106 9.2.1 The PIPoint Table...............................................................................................106 9.2.2 Using Performance Equation Subsystem Built-In Functions..............................107

9.3 Configuration .................................................................................................................108 9.3.1 Hierarchy of PI SQL Subsystem Settings...........................................................108 9.3.2 Initialization File Settings ....................................................................................109

Table of Contents

PI Server Reference Guide Page xiii

9.3.3 Command Line Arguments.................................................................................109 9.4 Troubleshooting ............................................................................................................112

9.4.1 Using the ipisql Utility .........................................................................................112 9.4.2 Generating a Trace File......................................................................................114 9.4.3 Output from the TRACE Option..........................................................................114 9.4.4 Clearing Expensive Query Problems .................................................................116 9.4.5 Performance Counters .......................................................................................117 9.4.6 Technical Support and Problem Reports ...........................................................117

Appendix A: PI Time Format.........................................................................................................119 9.1 Relative Time .................................................................................................................119 9.2 Absolute Time................................................................................................................119

9.2.1 Specifying Standard or Daylight Savings Time ..................................................120 9.2.2 Examples............................................................................................................121

9.3 Combined Formats........................................................................................................122 9.3.1 Examples............................................................................................................122

Appendix B: PI Time Conversions ...............................................................................................123 9.1 Timestamps on PI 2 Systems.......................................................................................123 9.2 Daylight Savings Time Changes on PI 2 Systems .....................................................123 9.3 Timestamps across Time Zones on PI 2 Servers.......................................................124 9.4 Timestamps on PI Server Systems..............................................................................125 9.5 Translating PI 2 Timestamps to PI Server Systems...................................................125 9.6 Translating PI Server Timestamps to PI 2 Based Timestamps.................................127 9.7 How PI Client Applications Handle DST Changes .....................................................127 9.8 PI in the 21st Century....................................................................................................128

Appendix C: PI API and Toolkit Usage ........................................................................................131 9.1 Overview.........................................................................................................................131

9.1.1 PI API..................................................................................................................131 9.2 PI API Usage on PI Server ............................................................................................131 9.3 PI Toolkit Usage on PI Server.......................................................................................138

Appendix D: Predefined Attribute Sets and Point Classes .......................................................139 9.1 Predefined Attribute Sets .............................................................................................139

9.1.1 alarmparam ........................................................................................................139 9.1.2 base....................................................................................................................140 9.1.3 classic .................................................................................................................140 9.1.4 sqcalm_parameters ............................................................................................141

Table of Contents

Page xiv

9.1.5 totals ...................................................................................................................142 9.2 Predefined Point Classes .............................................................................................142

Technical Support and Resources...............................................................................................143

Index of Topics...............................................................................................................................145

PI Server Reference Guide Page xv

TABLE OF TABLES

Table 2–1. COM Connector Point Attributes............................................................................17 Table 3–1. Typical Digital States..............................................................................................25 Table 3–2. ConfigurableTimeout Parameters ..........................................................................28 Table 4–1. Point Types ............................................................................................................45 Table 4–2. Point Database Default Table ................................................................................58 Table 9–1. Default Attributes in BASE Point Class................................................................106 Table 9–2. Command Line Arguments ..................................................................................109 Table 9–3. Command Line Option Tokens ............................................................................110 Table 9–4. Command Line Arguments Supported by ipisql ..................................................113 Table B-1 PI 2 Standard Time to Daylight Savings Time ...................................................124 Table B-2 PI 2 Daylight Savings Time to Standard Time ...................................................124 Table B-3 PI2 Timestamps across Time Zones .................................................................125 Table B-4 PI Server Standard Time to Daylight Savings Time ..........................................126 Table B-5 PI Server Daylight Savings Time to Standard Time ..........................................126 Table B-6 PI Examples of Timestamp conversions for California-based systems.............127

PI Server Reference Guide Page xvii

TABLE OF FIGURES

Figure 2-1. Processing of New Events.....................................................................................14 Figure 2-2. Data Flow through Snapshot Subsystem, Redirector, and COM Connector ........18 Figure 2-3. DataFlow through Archive Subsystem, Redirector, and COM Connector ............19 Figure 5-1. Formation of a point class......................................................................................63 Figure 7-1. Swinging Door Compression ...............................................................................100 Figure 9-1. Windows Control Panel Services Applet .............................................................111

PI Server Reference Guide Page 1

Chapter 1. THE PI SERVER

The PI System is a set of software modules for plant-wide monitoring and analysis. It acts as a data server for Microsoft Windows-based client applications. Operators, engineers, managers, and other plant personnel use a variety of client applications to connect to the PI Server to view plant data stored in the PI Archive or in external data storage systems.

The PI Server typically runs on one computer, while PI interfaces and client applications run on a variety of other computers on the network. Such a distributed data collection architecture offers several advantages over a monolithic architecture, including scalability, robustness, and flexibility.

A PI Server includes:

PI Server Subsystems: The processes, called subsystems, that comprise the PI Server.

Configuration and administrative utilities.

Interfaces, including Random and Ramp Soak for simulated data, and PerfMon, SNMP and Ping for monitoring purposes.

PI API and PI-SDK. This software is included with the PI Server for internal use by the applications on the PI Server.

This chapter provides an introduction to these elements of the PI Server, and explains the structure of the PI Server File system.

1.1 PI Server Subsystems

The PI Server consists of several interlocking processes, which this book refers to as subsystems. The executable for each of the PI subsystems is installed in the PI\bin directory. Six PI subsystems make up the core PI Server. Generally, the system cannot function to a minimum level without these subsystems. Some subsystems depend on other subsystems for proper behavior. All subsystems will wait for any dependent subsystems. The core PI subsystems are listed in the following table.

Chapter 1 - The PI Server

Page 2

Subsystem Executable What It Does Dependency Issues

Archive piarchss.exe Stores and serves the data after it comes out of the Snapshot subsystem. Data consists of multiple timestamped measurements for each data point. This includes values such as on/offs, pressures, flows, temperatures, setpoints, etc.

Requires the PI Snapshot Subsystem.

Base pibasess.exe Maintains the Point Database, Digital State Table and configuration databases for user and group security. It also hosts the PI Module Database.

Requires the PI Update Manager

License Manager

pilicmgr.exe Maintains licensing information for the PI Server and all connected applications

Message pimsgss.exe Records status and error messages for the PI Server in a control log file.

Messages are routed to the Windows Event log or UNIX standard output if this subsystem is not available.

Network Manager

pinetmgr.exe Manages communication between PI Server subsystems, client applications and interfaces. Also validates clients at time of connection. Clients may be standard products such as FactoryTalk Historian ProcessBook, or they may be user-written PI API or PI SDK programs.

Snapshot pisnapss.exe Stores the most recent event for each point. Applies compression, sends data to the Event Queue, and serves Snapshot events to the client applications.

Requires the PI Update Manager.

Update Manager

piupdmgr.exe Sends notifications of changes in values or point attributes to any interface or client application that is signed up for notification.

These services are essential for proper operation of a PI Server; it is required by most of the PI Subsystems and most client applications.

In addition to the core PI Subsystems, the PI Server includes additional subsystems such as Batch and Performance Equation Scheduler. These subsystems do not need to be running in order for PI to be running. Some of these subsystems are licensed separately and might not be installed on your PI Server.

1.2 - Configuration and Administrative Utilities


Other Subsystems

Subsystem Executable What It Does

Alarm* pialarm.exe Provides alarm capabilities for PI points.

Backup pibackup.exe Manages backups of PI.

Batch* pibatch.exe Detects and records batch activity.

Performance Equations*

pipeschd.exe Performs PI Performance Equation calculations for PI calculated points.

Recalculator pirecalc.exe Automatically adjusts values of Performance Equation (PE) points.

Redirector piudsrdr.exe The Base, Archive, and Snapshot Subsystems use the Redirector to obtain data from the external systems.

Shutdown pishutev.exe Determines when the PI system was stopped and writes shutdown events to points configured to receive these events (runs only at startup and then stops)

SQL pisqlss.exe Prepares and executes SQL statements directed at the PI Server. The primary users of this subsystem are the PI ODBC Driver and the PI SDK.

Totalizer* pitotal.exe Performs postprocessing calculations on a point in the snapshot, storing the results in a PI “Totalizer” point.

* indicates a separately licensed subsystem

1.2 Configuration and Administrative Utilities

The PI Server for Windows and UNIX includes several utilities that are used to configure points, monitor the data flow, manage the archives, and configure the security settings.

The PI Server comes with a wide variety of configuration and administrative utilities:

Utility Location Description

apisnap PI\adm A tool for checking snapshot values.

piarchss PI\bin PI Offline Archive Utility. This is actually the archive subsystem executable—which you can run with command-line options, as a utility.

piarcreate PI\adm Archive creation utility. Once created, Archive files can be mounted using piartool.

piartool PI\adm PI Archive Tool. This utility includes many commands to monitor, inspect or modify the state of a running PI Server.

piconfig PI\adm A tool for configuring PI Server databases, such as the Point database and the Digital State table.


Page 4

Utility Location Description

pidiag PI\adm A tool for PI diagnostics and repair.

pigetmsg PI\adm A tool for viewing PI Server messages.

pilistupd PI\adm A tool for monitoring the Update Manager, specifically for looking at Event Queues.

pipetest PI\adm Performance equation test utility.

pisetpass PI\adm A tool for changing user passwords

pisnap PI\adm Starts apisnap against the local PI Server

pisqlss PI\bin Pisqlss is actually the SQL Subsystem—which you can run with command-line options, as a utility.

piversion PI\adm Use piversion –v to get the version and build numbers of the PI Server.

To view usage information for any of these utilities, use the -? argument. For example:

pilistupd -?

1.2.1 Using Command-Line Tools Remotely It is useful to be able to run the PI administration tools remotely. A piconfig session may be run remotely by issuing the Login command.

The piartool, pigetmsg and pilistupd utilities can be run remotely by specifying four parameters:

PI Server home node host name or IP address

PI user account name

PI user account password

Port ID (defaults to 5450)

For example:

pilistupd -remote

This requires PI-SDK installation on the client.

1.2.2 Displaying the PI Version Number Get PI Server version and build numbers by typing:

piversion –v

From the PI\adm directory.

If you have applied a patch to your PI Server, the version numbers of the executable modules affected will be different from that shown by piversion -v.

When a module is executed using the -v option, the module is not actually started; only the version number is displayed.

1.3 - Interfaces Installed with the PI Server


1.2.3 Checking Snapshot Values (apisnap and pisnap) On both Windows and UNIX platforms, there is a utility in the PI\adm directory called apisnap that shows the current value (Snapshot) for a specified point.

When you run the apisnap utility on the PI Server, it prompts you for a point name. (To quit the utility, press <Enter> instead of entering a point name).

The apisnap utility accepts as a parameter the network name (and optionally, a TCP/IP port number) of a computer running a PI Server. For example, to connect to a PI Server running on the same computer, you would enter:

apisnap localhost:5450

There is also a script in the PI\adm directory called pisnap.bat on Windows and pisnap.sh on UNIX. This script runs the apisnap utility and connects to PI on the same computer.

1.3 Interfaces Installed with the PI Server

Each PI Server includes several interfaces. Two of these, Random and Ramp Soak, are simulator interfaces. They can be configured to simulate random, sinusoidal, and batch data. These are installed on the PI Home Node, but may be run remotely.

Three additional interfaces are useful for monitoring the health of your system and network. Each is limited to a maximum of 512 performance points in the Point Database and can only be run on the PI Home node.

PerfMon reads Performance Counters on Windows systems and stores the values in PI points,

SNMP collects performance data from computer systems and network routers using the Simple Network Management Protocol, and stores the values in PI points.

Ping monitors the network availability of computer systems by pinging them and stores the response times in PI points.

A version of the interface without the 512-point limit may be purchased separately.

1.3.1 Interfaces to Other Data Sources Interfaces are software modules for collecting data from any computing device with measurements that change over time. Typical data sources are Distributed Control Systems (DCSs), Programmable Logic Controllers (PLCs), lab systems, and process models. Most interfaces can also send data in the reverse direction, from PI to the foreign system.

1.4 PI Application Programming Interface (API)

The PI Application Programming Interface (PI API) is a library of functions that allow programmatic access to the PI System, both for data archiving and for retrieval. OSIsoft uses the API internally to create interfaces that run on a variety of platforms. Users may also use the API for their own applications.


Page 6

The PI API is a library of functions that may be called from C, Visual Basic, or other languages. These functions let you read and write values from the PI Server. They also let you retrieve point configuration information.

The PI API also provides the ability to buffer data that is being sent to PI. This allows PI to be taken offline for software or hardware upgrades without compromising data collection. When PI becomes available again, the buffered data are then forwarded to PI.

API nodes are UNIX or Windows workstations that run programs such as interfaces that are based on the PI API.

1.5 PI Directory Structure

The PI Server file organization is a little different for Windows and UNIX platforms. Refer to the section for the appropriate operating system.

1.5.1 Windows Directory Structure By default, PI installs its files in a folder called PI on the disk with the most available space, but you can choose a different location for PI during installation. Within the PI directory, PI installs a few subdirectories.

Directory Contents

PI\adm Contains administrative tools.

PI\bin Contains subsystem or PI service executables.

PI\dat Contains databases such as points and digital states. This is also the default directory for Archive files and the Event Queue.

PI\interfaces Contains interfaces that were installed with previous versions of PI. Is not present on new PI Server installations, but might be present on Servers that are running upgrades.

PI\log Contains log files.

PI\setup Contains files for install and uninstall.

The PI directory structure for Windows systems differs depending on whether the system is a new installation or an upgrade.

PI Interfaces Directory on Windows PI installs interfaces in a directory called PIPC. The PIPC directory tree, if it does not exist, is created during the installation of the PI-SDK. Refer to the PI-SDK documentation for more information about the PI-SDK installation.

Previous versions of PI installed interfaces in a directory called interfaces under the main PI directory. If your PI Server is based on an upgrade, rather than a new install, then older interfaces might be located in the PI/interfaces directory. For upgrades, interfaces that have been installed in the PI directory tree will remain in the PI directory tree. All other interfaces are installed in the PIPC directory tree.

1.5 - PI Directory Structure


1.5.2 Windows File System Concerns When running PI on Windows, Rockwell Automation recommends the following:

Disable virus scanning on the archive and database folder. Virus scanning may corrupt active files (e.g. the primary archive). The problem with virus scanning is that, because the data is random, it might have a bit pattern that matches a known virus signature. The virus scanning software then locks and quarantines the PI Server file.

Don't use the Windows File System Compression feature on the PI Server. When you use compressed files, you slow down PI's access to Archive files. The compression might save disk space, but it requires more CPU resources.

The following sections explain these recommendations in more detail.

Windows File Compression Using compressed files can slow down the access to the Archive files, and thus degrade the performance of the whole system. This is especially true on files that are constantly changing, such as the primary archive, the Event Queue or the current message log file.

Rockwell Automation recommends that you do not use the File System Compression feature of Windows. If you use this compression, while it may save disk space, it will require more CPU resources each time data arrives at the Archive or database files or is accessed by clients.

Using Anti-Virus Software Rockwell Automation recommends against using anti-virus software to scan the directories containing PI Server database and Archive files on systems collecting production data.

To be effective, anti-virus software must be configured to immediately scan files whose contents change. The contents of the PI Server Archive files change constantly as archive cache records are regularly flushed from memory to disk. Archive files tend to be large, which means that the time required to scan can be quite long. In addition, if any random bit pattern in an Archive file happens to match a known virus signature, the anti-virus software can lock or otherwise quarantine the Archive file. This corruption of the Archive file system has happened at several sites, resulting in the unrecoverable loss of production data. The same situation can occur for other PI Server database files, although these files change less often.

Anti-virus software should be configured to exclude scanning the PI\dat directory and any directory containing Archive files. The PI\dat directory does not contain any executable programs or scripts.

Another effective technique for protecting a production PI Server from Internet hackers is to install a firewall between the Internet and the server. For maximum protection, the firewall can be configured so that it stops all incoming Internet traffic except for those packets which (1) originate from safe, user-specified IP addresses, and (2) are destined for TCP/IP port 5450 on the PI Server computer. Downloaded files, or files from an unverifiable source could be scanned for viruses on a separate "quarantine" computer before moving them to the PI Serve


Page 8

Other Files on Windows Systems On Windows systems, the PI System may use the file, WINNT\system32\pdh.dll – this is the Microsoft Performance Data Helper library, which is used by the PI Performance Monitor interface. This file is loaded or upgraded on your system during the normal installation procedure.

Additionally, the PI-SDK places some Windows files during installation. The files placed by the PI-SDK are listed in the PI-SDK Release Notes, which are installed in the SDK subdirectory of the directory indicated by the pihome entry of the pipc.ini file.

1.5.3 UNIX Directory Structure The PI directory structure for UNIX systems:

Directory Contents

PI/adm Contains administrative tools.

PI/bin Contains the PI System executables.

PI/dat Contains data files such as the Point Database

PI/interfaces Contains subdirectories with executables for each of the interfaces.

PI/lib Contains libraries used by PI.

PI/log Contains all PI log files. Log files for the interfaces may also be found in the PI\interfaces subdirectories.

PI/patches Contains miscellaneous files that may be needed for some installations.

Other Files on UNIX Systems There are a few files used by the PI System that are not located under the PI directory. On UNIX systems, the following files may be used by the PI System:

/etc/piparams.default - This file is created during PI installation.

/etc/passwd - This file is modified to create the piadmin and OSI login accounts.

/etc/group - This file is modified to create the pigrp group.

/usr/lib/libC.ansi.sl - This file is needed only on some platforms. The file name may vary.

/usr/piadmin/.profile - This file is modified by the System Administrator to define the shared library path environment variable if using the Korn shell. It is needed only on some platforms. The path may vary, depending on the installation The environment variable varies depending on the platform.

/usr/piadmin/.chsrc - This file is modified by the System Administrator to define the shared library path environment variable if using the Korn shell. It is needed only on some platforms. The path may vary, depending on the installation. The environment variable varies depending on the platform.


Chapter 2. PI DATA FLOW

This chapter describes the flow of data through a PI Server and interfaces. PI typically stores data in the PI Data Archive, which is managed by the PI Archive Subsystem. However, Windows-based PI Servers can also retrieve data from foreign data-storage systems. Foreign data-storage systems are, for the purposes of this book, any data systems other than the PI Data Archive.

This chapter begins by explaining the flow of data from data sources to the PI Data Archive. Later sections discuss data retrieval, both from the PI Data Archive and from foreign data storage systems. This chapter contains the following sections:

Data Flow from Data Sources into the PI Archive begins on page 11

Data Retrieval from the Archive begins on page 15

PI Data Retrieval with Foreign Data Sources begins on page 16

Note: In the PI Server for UNIX, there is no COM Connector capability. All data must be stored in the PI Data Archive.

2.1 Data Flow from Data Sources into the PI Archive

The fundamental unit of data storage in the PI System is called an event. An event consists of a timestamp, a value, and a status. In the simplest terms, interfaces collect data from data sources, then send these data to the PI Server in the form of events. The PI Server then stores these events in the PI Archive. This simple view of PI data flow is shown in the following illustration.

Chapter 2 - PI Data Flow

Page 10

In reality, the data flow is more complex than the preceding illustration indicates. The most important thing to understand about PI data flow is that PI does not save every single event that an interface collects. Instead, PI stores only significant events. A significant event is one that is essential for recreating the original data. PI discards events that are not significant.

This section provides a more detailed description of the data path that an event follows from the data source to the PI Data Archive and describes the places in the data path where PI evaluates a point to see whether it is significant. The basic steps along the path are as follows:

1. The interface collects the data from the data source. The data sources can be almost anything, including Distributed Control Systems (DCSs), Programmable Logic Controllers (PLCs), lab systems, Supervisory Control and Data Acquisition systems (SCADA), process models, and other business information systems. PI Performance Equations, ACE, and Totalizer are also all data sources.

2. Each different data source needs a PI interface that can interpret it. Most PI interfaces run on a separate computer, called an Interface Node. (The Interface Node is sometimes also called the API Node.)

3. The PI interface uses exception reporting to determine which events to pass on the PI Server and which are not needed. Exception reporting is a simple linear test that determines whether the incoming value is significantly different from the existing value. You set the specifications for exception reporting in the tag attributes for each point. By tuning these exception specifications, you can ensure that the interface passes on only values that are of interest to you.

4. The interface sends significant events to the buffering service, if the buffering service is configured for that interface.

5. The buffering service sends the events on to the PI Server or, if the Interface Node cannot connect to the PI Server, the buffering service holds the data until the Server connection is restored. This is an important mechanism for safeguarding your data, so it’s important to configure buffering for your interfaces, where possible.

2.1 - Data Flow from Data Sources into the PI Archive


6. When an interface sends an event to the PI Server, it goes first into the Snapshot Subsystem. The Snapshot Subsystem holds a “snapshot” of each point in the point configuration database. This snapshot includes: the current value of the point, the last archived value, compression specifications, and security attributes.

7. The Snapshot uses the information about each point to decide what to do with incoming events for that point. If an event is out of order, the Snapshot sends it straight to the archive. If the event is not out of order, the Snapshot Subsystem applies the compression test.

8. PI uses the compression test to decide whether an event is significant. As in exception reporting, you set the specifications for compression in the tag attributes for each point. Unlike exception reporting though, compression testing is not linear. PI uses a very sophisticated compression algorithm to determine whether it needs a particular value in order to accurately reconstruct the data curve for a particular point.

9. If the event passes the compression test, the Snapshot sends it to the PI Event Queue.

10. The Archive Subsystem retrieves events from the Event Queue. Since the Event Queue is a memory-mapped file, the events in it are persistent. This means that they are recoverable in cases of unexpected crashes or delays.

2.1.1 The Snapshot A new event entering the PI System from an interface or manual input program is sent to the Snapshot Subsystem. The Snapshot is the most recent event for a point. It can be viewed as a buffer that is only one element deep. When a new event comes in, it becomes the new Snapshot. The previous Snapshot is evaluated according to the compression specifications and is either sent to the Event Queue or discarded.

Any event that has a timestamp older than the Snapshot will not become the Snapshot. Instead, it is sent to the Archive Subsystem through the Event Queue.

Event values are always stored in full precision in the Snapshot. Scaling, if applicable, is applied when the event is stored into the Archive. For more information on scaling, see the section on point types in Chapter 3, PI System Databases.

When the archive events for a point are listed or trended by FactoryTalk Historian ProcessBook and other tools, the Snapshot is automatically included in the list.

The Snapshot Table resides in memory. It is flushed to disk (piarcmem.dat) by the Snapshot Subsystem at least every 15 minutes.

2.1.2 The Archive Subsystem The PI Snapshot sends events that pass compression to the Archive Subsystem. When events enter the Archive Subsystem, they do not go directly to Archive files for storage. Instead, they go first to the Archive Event Queue, which sends them to the Archive Write Cache. Finally the Archive Write Cache sends the events to the Archive Files themselves for storage.


Page 12

SnapShot 1 2 3 4 5

n

RecNo

New Event

Queue(s)

Compress

Cache0

0 m

n PrimaryArchive

OtherOn-LineArchives

file(s)

Figure 2-1. Processing of New Events

The Event Queue Events that have passed the compression filter are placed in the Event Queue. This includes events that are out of order, events for points whose status has changed, and events for points with the Compression attribute set to OFF.

The Event Queue has the job of buffering the incoming process data on the way to the Archive. The operation of the queue protects the data against loss should any of the following system upsets occur:

Loss or failure of the Archive Subsystem

Surge of process data from process or other upset

Temporary CPU loading of the computer running PI

The memory-resident Event Queue is always backed up on disk (pimapevq.dat). If the queue becomes full due to long delays in the Archive Subsystem, up to 65,535 additional queues may be created. When the Archive is able to recover from the cause of the upset, all the queues are processed in the order created.

The default size of the Event Queue is 64 megabytes but it may be configured from 8 megabytes to 128 gigabytes. The amount of free space on the disk is generally the only limitation on the size and number of queues.

The Event Queue is located in the PI\dat directory, but can be on a different volume. The System Manager should ensure that adequate free disk is maintained on that volume. When the Archive Subsystem is unavailable, you may need an average of 5 kilobytes of free space per point per day. This assumes 250 events per point per day for a floating-point tag.

The Write Cache When the Event Queue sends an event to the Archive Subsystem, the Archive keeps it first in the Write Cache, which is a memory array that stores events for each point. The Write Cache

2.2 - Data Retrieval from the Archive


stores events for a point in memory until the data reaches certain configurable limits on size and/or time since the last write to disk. Then the Write Cache data for that point is written to the Archive files. By holding events for each point up to the specified limits, PI reduces the frequency of disk access, improving overall performance.

Specifically, write cache events are flushed to disk at the following times:

When the Write Cache for a particular point reaches the maximum size, the data for that point (and just for that point) is flushed to disk. The maximum number of events in the Write Cache for each point is 256, but this is configurable by the Archive_MaxWriteCachePerPoint setting in the timeout table.

Every record in the Write Cache is flushed at least once every Flush Cycle. The default cycle is 900 Seconds (15 minutes) and can be configured using the timeout parameter Archive_SecondsBetweenFlush.

2.2 Data Retrieval from the Archive

Many applications request data from the PI Server system, for example, trends or FactoryTalk Historian DataLink. Every such request translates into a low level call to the archive that retrieves the raw data, values and timestamps. This raw data is always exactly what was put into the archive by the interface. However, there are two exceptions where the data-retrieval functions generate an extra event.

When the request spans a time period with no mounted Archive files, a digital state of Arc OffLine is inserted one second after the end of the last scanned Archive file. This prevents the interpolation of data over an unknown period, for example when an archive is offline for maintenance.

This option is active by default but can be disabled by setting the timeout parameter:

MarkArchiveGaps, 0

Similarly, when requests for data go into the future, a NoData digital state is inserted one second after the current time. If the Snapshot is in the future, then the NoData digital state is inserted one second after the Snapshot, in order to prevent data extrapolation into the future. The PI server rejects Snapshots more than 10 minutes into the future.

Requests for data before the oldest registered archive also return NoData.

Since these two digital states are used within the PI Server, we recommend not inserting them into the archive as this can lead to misinterpretation of data-retrieval results.

2.2.1 The Archive Read Cache The read cache is a piece of memory that contains a linked list or records for each point. The read cache has a one-to-one relationship with records in the Archive. When a client asks for data from the Archive, the Archive translates that data to Record Number, and then figures out if the data being requested is in the Read Cache already. If not, it determines in which Archive to go look for the data.


Page 14

The size of the Read Cache is configurable and, by default, a single point can use as many as 512 records from the pool. This number is configurable with the Archive_CacheRecordsPerPoint parameter (the maximum value is half the cache pool). Assuming enough memory resources, the limit on the total number of records in the Read Cache is set to 4 times the point count, but can be manually overwritten by the Archive_CacheRecordPool parameter.

You can use piartool -cas (cache statistics) to view cache information for a point, and piartool -cad (cache diagnostics) to dump the information in both the read and write caches.

2.3 PI Data Retrieval with Foreign Data Sources

Data are sometimes not stored in the Archive or Snapshot Subsystem. They may be stored in an external or ‘foreign’ data source. The Base, Archive, and Snapshot Subsystems can request data from foreign data storage systems through modules called COM Connectors. Each COM Connector is coded to interact with a specific foreign data system. A separate COM Connector must be installed to communicate with each specific foreign data system.

A PI Server system may have any number of COM Connectors installed. Since the identity of the COM Connector to use is determined on a point-by-point basis, a single PI Server system can access any number of foreign data systems. It is not necessary to dedicate an installation of PI Server strictly to communication with external systems.

The core Subsystems of the PI Server do not communicate directly with COM Connectors. Instead, the Subsystems send requests to the PI Server Redirector, which acts as a request broker. The Redirector loads one or more COM Connectors and forwards the requests to them.

Note: The Redirector is a module in PI Server for Windows only. PI Server for UNIX does not support the use of COM Connectors or the Redirector.

The Redirector and the COM Connectors are COM objects, implemented using Microsoft Component Object Model (COM) technology. The Redirector is installed as part of the PI Server. COM Connectors are installed separately.

COM Connectors are installed on the PI Server, but are not loaded into the Server’s memory until needed. When PI shuts down, the Redirector and all COM connectors are automatically unloaded from memory.

COM Connectors may be in-process or out-of-process COM objects. In-process COM objects are .dll files, while out-of-process COM objects are .exe files. OSIsoft has developed some COM Connectors to specific data systems. Others may be available from vendors or integrators. In general, the decision to build an in-process vs. an out-of-process COM object is made by the COM Connector developer.

The PI Server Redirector is an out-of-process COM object. It does not run as a service, which means it will not be found in the Services control panel applet. When the Redirector is running, system managers will be able to see a process called piudsrdr.exe in the Processes tab of the Windows Task Manager.

2.3 - PI Data Retrieval with Foreign Data Sources


Client applications are not aware of the difference between data retrieval from the PI Data Archive and data retrieval from a foreign data storage system using a COM Connector. In all cases, the application connects to the PI Network Manager. Each point from which data are retrieved is identified by a tag, and has attributes stored in the PI Point Database, regardless of the source of the data. The differences in data flow are implemented by the Snapshot and Archive Subsystems. Details are in the sections Retrieval of Snapshot Data and Retrieval of Archive Data, below.

The PI Server sends data to client applications in exactly the same way, regardless of whether the data is stored in the Archive Subsystem or in a foreign data source. The same is true of data requests from PI Server Subsystems such as the Totalizer, the Alarm Subsystem, and the Performance Equation Scheduler.

The PI Server can put new data into a foreign data system if it is supported by the COM Connector for the foreign data system.

2.3.1 Point Configuration In order to interact with a point on a foreign system, a corresponding point, called a mapped point or COM Connector point, must be created in the PI Server Point Database.

A mapped point in the Point Database is simply one that links to data in a foreign-system.

To build a mapped point, you must select a point class that includes three specific attributes, as well as the normal attributes of a point class. These three point attributes are shown in the following table:

Table 2–1. COM Connector Point Attributes

Attribute Name Description

ctr_progid COM program ID, as stored in the Windows registry. This name is used to invoke the COM Connector object when needed.

ctr_lmap Longword mapping parameter. ctr_lmap and ctr_strmap are passed to the COM Connector so that it can locate the appropriate foreign system point.

ctr_strmap String mapping parameter. ctr_lmap and ctr_strmap are passed to the COM Connector so that it can locate the appropriate foreign system point.

PI Server ships with a point class called classicctr that contains these three point attributes as well as the base and classic attribute sets. You can create this point class by executing the script PI\adm\classicctr.dif using the piconfig utility. You may also use the contents of this script as a basis for your own point class definition.

You construct points according to the specifications of the point class. A complete list of point attributes is listed in PI Server Databases on page 21 in the Point Database section. Point creation and maintenance are done using the PI TagConfigurator, a Microsoft Excel spreadsheet-based tool, or piconfig, a script-based tool.

Whenever the point information indicates that the requested point is a mapped point, the Redirector will obtain data values from the corresponding foreign system point.


Page 16

2.3.2 Retrieval of Snapshot Data When the PI Server Snapshot Subsystem starts, it is notified of the presence of mapped points by the Base Subsystem. When a client application requests a Snapshot value, the Network Manager routes the request to the Snapshot Subsystem.

If the point’s data are normally stored in the PI Data Archive, the Snapshot value would be retrieved from the Snapshot Subsystem and then returned to the Network Manager.

If a Snapshot value for a mapped point is requested, the data path is different. In this case, the Snapshot Subsystem requests the value from the Redirector, which in turn requests the value from the appropriate COM Connector. The COM Connector obtains the value from the foreign data storage system and returns it to the Redirector, which sends it to the Snapshot Subsystem. Then it is routed to the Network Manager for transmission to the client.

Figure 2-2. Data Flow through Snapshot Subsystem, Redirector, and COM Connector

2.3.3 Retrieval of Archive Data The retrieval of Archive data from the COM Connector by the PI Server Archive Subsystem is similar to Snapshot retrieval by the Snapshot Subsystem. When the PI Server Archive Subsystem starts, it is notified of the presence of mapped points by the Base Subsystem. When a client application requests archive values, the request is routed to the Archive Subsystem by the Network Manager as before. The archive values are retrieved from the subsystem and returned to the Network Manager for transmission to the client.

2.3 - PI Data Retrieval with Foreign Data Sources


If archive values for a mapped point are requested, the data path is different. In this case, the Archive Subsystem requests the value from the Redirector, which in turn obtains the value from the appropriate COM Connector

Figure 2-3. DataFlow through Archive Subsystem, Redirector, and COM Connector

2.3.4 Archive Files Even though Archive files are not used if data are retrieved using COM Connectors, the files must exist and must be sized as if all points on the PI Server were PI Data Archive points.

Normal maintenance and backup procedures apply to the Archive files, with one exception: if a PI Server installation consists entirely of mapped points, it will not be necessary to back up the Archive files.

2.3.5 Exception Reporting The COM Connection mechanism includes support for exception reporting. There is a ‘sign up’ method that the PI Server Snapshot Subsystem will call in the COM Connector if a client signs up for exceptions on a mapped point. The Snapshot Subsystem will obtain exception values from the COM Connector by way of the Redirector.

If the foreign system does not support exception handling, it may be coded to return a standard COM error code indicating that the method is not implemented.


Page 18

2.3.6 Compression PI Server does apply the PI Data Archive’s data compression algorithm to mapped foreign points. If the COM Connector supports putting new data values into the foreign system, then that system is responsible for their storage. The foreign system may or may not support compression.

2.3.7 Point Security Data retrieved from foreign data system is subject to the same security as data values retrieved from storage within the PI Data Archive. Every PI point, whether mapped or not, carries a security descriptor that defines the access PI users may have to data.


Chapter 3. PI SERVER DATABASES

The PI Server includes several databases that store PI configuration information and process data. The two main databases are the Point Database and the Data Archive. Other parts of the system, including the Snapshot Subsystem, the Digital State Table, and Module Database, support the main databases.

System Management Tools as well as a set of command line utilities are used to configure and manage the PI Server.

See also PI Server System Management, and documentation about free System Management tools.

3.1 Point Database

The most important configuration database is the Point Database. This contains the list of points that are either recorded in the PI Data Archive or mapped to points in foreign data systems when COM Connectors are used. The points whose data are stored in PI Data Archive are sometimes called native PI points. The points whose data are stored in foreign data systems are interchangeably referred to mapped points or COM Connector points. The Point Database stores configuration information for each point as a list of point attributes. Attributes are grouped into attribute sets, which in turn are grouped into point classes. The Base class, Totalizer class and Classic class are some of the point classes commonly used in PI. When a point is created, it is assigned a point class, which restricts the point to a specific set of attributes.

For a complete explanation of the PI point classes and point attributes, refer to PI Point Classes and Attributes on page 43.

3.2 Data Archive

The most important process information database is the Data archive. The archive is a historical record of values for each point in the Point Database.

The Data Archive contains the time-stamped values for all the points in the Point Database. The time-stamped values are stored in a set of disk files. Each file covers a different, non-overlapping time period. Three archive files are created during installation. Additional archives can be created when needed, using the utilities provided. The archive files may vary in size.

Chapter 3 - PI Server Databases

Page 20

3.2.1 Archive Size Considerations When an archive value is replaced, the new value is flagged in the archive as modified. This results in additional storage being allocated for the replaced value. For numeric values the size approximately doubles.

Caution: When you delete a point, the records for that point in the current archive are made available for reuse. A consequence of this is that all history is irrecoverably lost for the deleted point. Records in old Archive files that contain data for the deleted point are not directly accessible. However, the data can be recovered using the Offline Archive Utility using an ID-conversion table.

3.3 Snapshot

The Snapshot Database contains the most recent value, status, and time stamp for each point in the Point Database.

The Snapshot database piarcmem.dat contains mostly frequently updated data. If this file is damaged it can be rebuild using pibasess –snapfix. Snap fix rebuilds this file based on the point database and sets all values to a Shutdown status; normal data collection quickly replaces Shutdown statuses with new values. Many PI Systems have a few points that update very infrequently; in this case these values will remain at Shutdown until a new Snapshot value is received.

The PI Snapshot Subsystem actually maintains several databases. The pimapevq.dat maintains the Event Queue. If pimapevq.dat (or pimq####.dat, where #### is a hexadecimal number between 0000h and FFFFh) is corrupted, pisnapss may not be able to start. In this case the file can be renamed and pisnapss will create a new one. Offline archive recovery tools can be used to recover data from this file. The file pilastsnap.dat maintains the Snapshot time of the newest event. This is used to determine the PI Server shutdown time. This file is overwritten every 10 minutes and during PI Server shutdown.

File name Description

piarcmem.dat Snapshot database

pimapevq.dat Event queue (could also be pimq0000.dat, pimq0001.dat…)

pilastsnap.dat Time of newest event

Two utilities provide access to the Snapshot Database. The pisnap.sh (UNIX) or pisnap.bat (NT) utility can be used to view the contents of the Snapshot. The piconfig utility can be used to both view and modify the contents of the Snapshot.

3.4 Annotations

Every value in the Snapshot or the Archive may be annotated. An annotation can be of any data type.

3.4 - Annotations


Annotations can be accessed via the PI-SDK. Text annotations can be added and edited using piconfig. This option should only be used for testing and verification.

Applications using the PI-SDK can add/edit annotations for a specified Archive event.

The Batch Database uses annotations to store the following object types:

PIBatches

PIUnitBatches

PITransferRecords

3.4.1 Annotation Files Annotations are store in an Annotation file. Each Archive file has a single associated Annotation file. An annotation is a variant associated with a PI Event.

Note: The PI SDK supplies a programmatic interface for creating, accessing and editing annotations. The PI SDK User Guide and online help are the best source for details on valid variants for annotations.

Annotations are best understood with a simplified description of creating and accessing them. For example:

1. A PI-SDK based application creates a variant. Variants can be of many types, such as strings, an array of strings, various numeric types, etc. For this example, the variant is an array of strings. The first string may be a lab technician’s name, the second string may be a comment.

2. This same application creates a timed value, for example, a value and timestamp that represent a manual measurement made on a piece of lab equipment. The variant created above is associated with the timed value—the value is now annotated. The PI-SDK is used to make this association. In this example, the annotation contains the technician making the measurement and an associated comment.

3. The annotated value is then sent to the PI Snapshot. This is sent just as any other event. The difference is that the event also contains the annotation.

4. Annotated events will always bypass compression. Upon reaching the Snapshot, the annotated event is sent to the Archive via the Event Queue.

5. From the queue, the annotated event is written to the cache. Then, a few special steps are taken writing the annotated event to the Archive.

First the target Archive and the Archive’s Annotation file is found. The variant that represents the annotation is written to the Annotation file. On writing to the file, the annotation is assigned a handle. The handle represents where in the Annotation file the annotation was written.

Finally, the annotation handle is written to the event and the event is written to the Archive. The event contains the timestamp, value and handle to the associated annotation.


Page 22

6. Annotation retrieval starts by accessing the event. The event is accessed by normal PI-SDK data access, such as get plot values or get archive value. Annotations may be quite large, so annotations are never returned by normal Archive access. The PI-SDK represents events as timed values.

7. The PI-SDK timed value, if annotated, supports retrieving the annotation. Annotation retrieval requires a call the PI Server, where the annotation handle is used to read the annotation from the Annotation file and return it to the caller.

8. Annotations may be edited and posted back to the PI Server to replace an existing annotation. This works like any Archive event edit, except the event is annotated.

Filling an archive will cause a shift of both the Archive and Annotation file; filling an Annotation file will cause a shift of both the Archive and Annotation file.

Annotation files grow as annotations are added; they generally use significantly less space than the Archive. On most systems the Archive fills before the Annotation file.

The annotation size is limited by the Event Queue page size, which has a default size of 1MB and a maximum size of 8MB. You set Event Queue page size using the timeout parameter, Snapshot_EventqueuePageSize.

Annotation file statistics are shown with the archive listing utility piartool –al. The following is output from an archive listing:

Archive[0]: D:\PI\dat\piarch.033 (Used: 1.8%) PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: $]::

Version: 7 Path: D:\PI\dat\piarch.001

State: 4 Type: 0 Write Flag: 1 Shift Flag: 1

Record Size: 1024 Count: 131072 Add Rate/Hour: 1.7

Offsets: Primary: 20/65536 Overflow: 128673/131072

Annotations: 10826/65535 Annotation File Size: 434144

Start Time: 19-Oct-05 12:39:10

End Time: Current Time

Backup Time: Never

Last Modified: 19-Dec-05 13:10:32

In the above listing, the Archive file is d:PI\arc\piarch.033. The corresponding Annotation file is d:PI\arc\piarch.033.ann. There are 10,826 annotations; with room for a total of 65,535. This number is configurable with the parameter Archive_MaxAnnotations, which only controls the number of annotations in the primary archive. Note however that Annotation files are limited to 2GB in size. In the above example, the Annotation file is 434,144 bytes (or 424KB).

The Annotation file always is identical path and name to the archive with the .ann suffix. As archives are loaded, Annotation files are loaded, using this naming convention. The Annotation file is created if it does not exist. It is important the Archive and Annotation files remain together—most importantly when a backed up archive is restored.

System management needs for Annotation files are simple—keep the Archive file and corresponding Annotation file together: • Archive backups should copy the Annotation file to the same backup location.

3.5 - Digital State Table


• When an Archive is moved to a new location, move the corresponding Annotation file to the same location.

• When an Archive file is deleted, delete the corresponding Annotation file to avoid future name collisions.

3.5 Digital State Table

The Digital State Table contains the digital state sets. A digital state set has a name and consists of a list of states, sometimes called digital state strings. For example, we can define the digital state set Valve-state-set as containing the two states OPEN and CLOSE.

When retrieving digital state strings using the PI API, note that the state strings will be truncated to 79 characters.

3.5.1 System State Set for All Points The default set is called the System Digital State Set and contains over 300 digital states that may apply to any tag. The following table describes some of these pre-defined digital states:

Table 3–1. Typical Digital States

State Use

I/O Timeout Interfaces use this state to indicate that communication with a remote device has failed.

No Data Data-retrieval functions use this state for time periods where no archive values for a tag can exist. 10 minutes into the future or before the oldest mounted archive.

Under Range For float16 point types, this state indicates a value that is less than the zero for the tag.

Over Range For float16 point types, this state indicates a value that is greater than the top of range (zero+span) for that tag.

Pt Created A tag is given this state when it is created. This is the value of a tag before any values have been put into the system for that tag.

Shutdown All tags that are configured to receive shutdown events get set to this state on system shutdown.

Arc Off-line Used by data-retrieval functions to indicate a period of time not covered by any mounted archive.

Bad Input Interfaces use this state to indicate that a device is reporting bad status.

The System Digital State Set also contains all of the digital state strings found in the PI 2.x Digital State Table. See the PI Server System Management Guide for details on how to get a list of these.


Page 24

Note: The last possible state in the System Digital State Set (number 16383) is reserved for the PI System’s internal usage. Rockwell Automation recommends minimizing changes to the System Digital State Set. At most, you can translate the states into another language without changing their meaning. Digital points should use a user-defined digital set. Not the System Digital State Set.

3.5.2 Defining a Custom Digital State Set For a digital tag, there are typically only a small number of valid states. Before defining the tag, a custom digital state set containing just those valid states is defined. When the tag is defined, it is assigned the custom digital state set.

There is no need to include System states in custom sets because the System states contained in the System state set will be used where needed by the PI Server. You may define up to 16383 state sets with up to 16383 states in each set.

For example, suppose a valve position is reported by an instrument system as having a digital code value of 0 or 1. The value 0 means that the valve is closed, while the value 1 means the valve is open.

Before configuring this tag, it is necessary to establish a digital state set with two strings, CLOSED and OPEN. You might name it Valve Position. Other tags that also have states of CLOSED and OPEN could be defined to use the same digital state set, Valve Position. Tags that have states of ON and OFF would use a different digital state set, which you might have called Switch Position.

The digital code value (0 or 1) is determined by the PI Server according to the position of the state (digital state string) in the Digital State Table. The first value is 0 (zero), the second one is 1, the third is 2, etc. This is termed digcode in PI API.

When retrieving state strings, PI API returns a maximum of 79 characters.

Editing the Digital State Table The Digital State Table may be viewed and edited using the piconfig utility or the PI System Management Tools (SMT), which are discussed in PI Server System Management Guide.

Changing a state string affects the retrieval of values already in the archive. If you change the first state string in the example above from CLOSED to SHUT, all values in the archive are reported with the new state string instead of the old one.

If you wish to affect only new values being received by the archive, you can define a new state set and change the point attribute to use this new state set. In this example, values of 0 recorded before you change the DigitalSet point attribute have a value of CLOSED. Values of 0 recorded after the point attribute edit will have a value of SHUT.

Deleting a Digital State Set Once a set has been defined, it cannot be deleted. Attempting to delete a complete set will result in a set named DIGSET_nn, where nn is the set number. This is to ensure that old archive events can always refer to a valid set.

3.6 - Timeout Database


Capitalization of Digital State Names Like tags, digital state names are not case-sensitive. If you define a state with all capital letters (for example OFF) then any later references to that state are not case sensitive (so off or Off are valid references to your state set called OFF). for display purposes. Leading and trailing blanks are removed from state names. Blank states are not allowed.

3.6 Timeout Database

The PI Timeout database, also called the Timeout Table contains a variety of PI Server configuration parameters. Originally the PI Timeout database contained only timing parameters, but other PI Server settings are now included in the Timeout database. In most cases, the default values for these parameters are best, however in some situations you might want to adjust one or more parameters to tune the PI Server performance.

3.6.1 Table of Configurable Timeout Database Parameters The following table lists the Timeout Table Parameters that are configurable. To edit Timeout database parameters, use piconfig or the Timeout Table editor in the PI System Management Tools (SMT). Modifications to the Timeout Database will only be recognized upon restarting PI.

Table 3–2. ConfigurableTimeout Parameters

Subsystem Name Min – Max (Default)

Read Description

All <subsysname>_BackupTimeout

30 – 86400 (1800)

Periodically when in system backup mode

This is the maximum number of seconds to remain in system backup mode. This timeout parameter only pertains to the piartool –systembackup command, which is used to take the audit databases offline. The parameter has no effect for VSS backups or non-VSS backups that are started with the piartool –backup command.

All <subsysname>_ThreadCount

1 – - (4 threads)

startup only Size of the subsystem message thread pool. Message threads are dedicated to RPC request processing. Depending on the number of processors on the machine, this value may be increased so more RPC requests can be handled simultaneously. If all the threads are busy, RPCs are queued up and processed in chronological order. Note: the default for the Archive Subsystem (piarchss_ThreadCount) is 8 worker threads instead of 4 for all other subsystems.


Page 26


Read Description

All <subsysname>_MaxThreadsPerClientQuery

depend on value of <subsysname>_ThreadCount (0)

startup only Limits the number of concurrent, identical queries from a client. The possible value range depends on the number of RPC threads for a subsystem. For example, if the number of threads is 8, then the possible values range from -7 to 7. A negative value means that the same request from the same client can consume all but that number of threads concurrently. A positive value means that the same request from the same client can consume a maximum of that number of threads concurrently. A value of 0 implies no limits. When exceeding the number of concurrent threads allowed, the client gets the following error message: “[-10767] Client exceeded maximum concurrent queries in RPC thread pool.”

All SBHThreshold 0 – 1920 (128 bytes)

startup only Threshold for CRT library small block heap memory allocation

All <subsysname>_WriteModTimesToFilePeriod

10 – 900 (60 sec)

Startup only PI internally keeps track of the last modified date of most of the files that it needs to back up. The last modified times for each subsystem are updated every WriteModTimesToFilePeriod. The smaller the period, the more accurate the last modified time will be. A complete list of backed up files along with their last modified dates can be listed with the piartool –backup –identify -verbose command. For archives, the last modified date can also be viewed with piartool –al. Note for Archive files: When a value is written to a PI point, the value is not actually written to the archive until the archive cache is flushed. The maximum period between archive flushes is set with the Archive_SecondsBetweenFlush timeout parameter. After the cache is flushed, the last modified time will be updated within WriteModTimesToFilePeriod seconds.

Archive Archive_AutoArchiveFileRoot

- (path + name prefix)

before every shift

Automatic Archive file creation on shifts. If present, this parameter defines the path and file name prefix to be used for new archives. Example: "C:\PI\arc\auto_"




Read Description

Archive Archive_BackupCutoffDate

01-Jan-70 – NA (01-Jan-70)

Before every backup

Archives that contain data more recent than the Archive_BackupCutoffDate will be backed up. For example, if “*-30d” is specified, then at least 30 days of data will be backed up.

Archive Archive_BackupLeadtime

5 – 86400 (1800 sec)

On backup startup

Number of seconds before the predicted archive shift that a non-VSS archive backup may start. The PI Backup Subsystem will wait up to 30 minutes for the archive shift to complete. This timeout parameter has no effect on VSS backups.

Archive Archive_BSTimeout 1 – 86400 (1800 sec)

Once a minute

This timeout parameter is now obsolete.

Archive Archive_CacheCleanCycle

1 – Flush Cycle (10 sec)

startup only Frequency at which read-only cache cleanup operations are performed. Setting this limit too low may affect the performance of the Archive Subsystem.

Archive Archive_CacheHighPctLimit

100 – 200 (110 percent)

startup only High cache cleanup threshold, in percentage of the Archive_CacheRecordPool value. Oldest cache records are deleted when the read-only cache pool is above this limit, regardless of Archive_MaxIdleCleanCycles.

Archive Archive_CacheLowPctLimit

20 – 100 (80%)

startup only Low cache cleanup threshold, in percentage of the Archive_CacheRecordPool value. Oldest cache records stop being deleted when the read-only cache pool is below this limit.

Archive Archive_CacheRecordPool

2048 – 1048576 (4 x ptcount records)

startup + end of each flush cycle

Maximum number of archive cache records for read access queries. The actual size of the read-only cache pool may lower due to low physical memory resources.

Archive Archive_CacheRecordsPerPoint

4 – cache epool / 2 (512 records)


Maximum number of archive cache records per point. In the default configuration, up to 512 records may be allocated to a single point.

Archive Archive_CacheTrimPercent

1 – 75 (40 %)

startup only Percentage to trim the read and write cache when low physical memory resources are detected.


Page 28


Read Description

Archive Archive_DataCoercionPolicy

0 – 3 (0)

startup only Error handling policy of archive event coercion after point type changes. Archive events are preserved (i.e. not modified) when the type of a point is modified after its creation. When clients request these events, automatic data coercion is performed. This parameter decides what the Archive Subsystem should do when this coercion fails. For more details, please refer to the chapter “PI Point Type Edit” on page 89.

Archive Archive_EventQueueThreadCount

1 – 255 (5 threads)

startup only This parameter is now obsolete in version 3.4.370, a single Event Queue thread now exists (see Archive_FlushThreadCount below).

Archive Archive_FlushThreadCount

1 – 255 (4 threads)

startup only Number of Flush threads responsible for saving write cache events to disk. These threads communicate with the Event Queue thread via a Flush Queue (see also Archive_FlushQueueSize).

Archive Archive_FlushQueueSize

16 – 8192 (256 flush tasks)

startup only Size of the Flush Queue between the EVQ (Event Queue) thread and the Flush threads. A flush task is created when a point’s write cache events must be saved to disk. Increasing this parameter may improve the archive write throughput in some cases.

Archive Archive_LowDiskSpaceMB

- (256 MB)

once a minute with a dynamic primary archive + on shifts when Archive_AutoArchiveFileRoot is set

Minimum amount of free disk space to leave on Archive file volumes. A dynamic primary archive will stop growing if this limit is reached and a shift will be triggered.

Archive Archive_MaxAnnotations

128 – 134217728 (65,535 annotations)

startup only Maximum number of event annotations per Archive file (annotations are stored in the parallel file with the .ann extension).

Archive Archive_MaxIdleCleanCycles

1 – 60 (2 flush cycles)

startup only Maximum idle time of archive cache records before being discarded. This number is expressed in number of flush cycles (Archive_SecondsBetweenFlush).

Archive Archive_MaxWriteCachePerPoint

0 – 2,048 (256 events)


Maximum number of write cache events per point. Events of a given point will be flushed to disk when this limit is reached.




Read Description

Archive Archive_MinCacheRecordPool

1,024 – 102,400 (2,048 records)

startup only Minimum size of the record pool when doing cache trimming due to low-memory conditions.

Archive Archive_MinMemAvail

0 – 1,024 (10 MB)

startup only Minimum amount of free physical memory to leave for OS and other subsystems. The Archive Subsystem will start trimming its cache when physical memory resources go below this or the Archive_MinPercentMemAvail percentage.

Archive Archive_MinPercentMemAvail

0 – 50 (0%)

startup only Minimum percentage of free physical memory to leave for OS and other subsystems. The Archive Subsystem will start trimming its cache when physical memory resources go below this or the Archive_MinMemAvail value.

Archive Archive_MinWriteCachePerPoint

1 – 1,024 (8 events)

startup only Minimum number of write cache events per points when doing cache trimming due to low-memory conditions.

Archive Archive_PointLockLogging

0 – timeout (5,000 ms)

startup only Archive lock delay reporting option. By default, threads taking longer than 5 seconds to acquire a lock will report in the message log. A value of 0 disables lock time reporting.

Archive Archive_PointLockTimeout

1000 – 270,000 (120,000 ms)

startup only Maximum time RPC (query) threads can wait accessing archive points. Default is 2 minutes (120 seconds).

Archive Archive_SecondsBetweenFlush

1 – 86,400 (900 sec)

startup only Archive cache flush cycle or maximum time between consecutive disk flushes for a given point.

Archive Archive_ShiftFreeTime

0 – 86,400 (1,800 sec)

startup only Number of seconds to substract from the predicted time to determine the actual shift time. Setting this parameter to something greater than zero will leave the corresponding free archive space (default is 30 minutes). This parameter and/or the Archive_ShiftRatio are useful on systems where backfilling or out-of-order events are expected.


Page 30


Read Description

Archive Archive_ShiftRatio 4 – 2048 (512 ratio)

startup only Ratio of total records to free records at which archive shifts are triggered. The inverse of this parameter defines the percentage of free records to leave in Archive files (default is 1/512 = 0.2%). This parameter and/or the Archive_ShiftFreeTime are useful on systems where backfilling or out-of-order events are expected.

Archive Archive_ShiftRecordCount

256 – 16384 (2048 records)

before every shift

Number of records to process in one chuck during Archive file initializations. When shifting or initializing new archives, this parameter partly defines the speed of archive initializations. However, setting this parameter higher than the default may impact system performance as more memory will be consumed.

Archive Archive_WriteLockTimeout

5000 – 900,000 (270,000 ms)

startup only Maximum time Flush (writer) threads can wait accessing archive points. Default is 4.5 minutes (270 seconds).

Archive ArcInsertRecOnOOO

0 – 1 (1 boolean)

startup only Break the chain and insert new records when out-of-order events need to be inserted into full overflow records. When set to 0 (false), this parameter makes the Archive Subsystem to revert back to the event cascading algorithm of PI 3.3 and earlier versions.

Archive ArcMaxCollect - (15000 events)

startup only Maximum number of compressed events that can be retrieved by a single query. This number does not affect interpolated event retrieval or archive summary calls.

Archive BreakCrossRefOnDelete

0 – 1 (1 boolean)

startup only Break reference between UnitBatch and PIBatch on deletion of UnitBatch.

Archive Cache_FreelistSize 1000 – 100000 (10000 records)

startup only Size of the list of reusable cache records that were discarded from the read-only record pool. This parameter should only be changed upon recommendation from a technical support engineer.

Archive MarkArchiveGaps 0 – 1 (1 boolean)

startup only Return special "Arc Off-line" events when Archive files are taken offline or when time gaps are detected in mounted archives. The archive offline markers are primarily useful to prevent any mis-interpolation of data across missing archives.




Read Description

Archive piarchss 1 – 10000000 (100000 sec)

startup only Subsystem wait time after every main loop iteration.

Archive BatchDb_MaxSearchRecords

-1 – 1,000,000 (-1)

startup only Maximum size (number of records) of batch queries returned by the Archive Subsystem. Very large batch searches can lead to performances problems with the PI Archive Subsystem. This applies to PIUnitBatches, PIBatches and PICampaigns. If set, exceeding the limit causes the search to be terminated, no records returned and the following error: [-16029] Batch database search exceeded maximum allowed records.

Archive BatchDb_SearchLookBackDays

1 – 365 (31 days)

startup only Controls the batch search look back period. Batch searches are performed internally this many days in the past from the start time provided. This can be set from 1 to 365 (days). The default value is 31 days (one month).

Backup Backup_ArchiveCutoffDate

01-Jan-70 – NA (01-Jan-70)

Before every backup

If the cutoff date is not explicitly specified in arguments to the pibackup.bat backup script, then this timeout parameter defines the default cutoff date. Archives that contain any data between Backup_ArchiveCutoffDate and current time will be backed up. For example, if “*-30d” is specified, then at least 30 days of data will be backed up. Both Backup_NumArchives and Backup_ArchiveCutoffDate restrict the number of archives for backup. Whichever timeout parameter is most restrictive takes precedence.

Backup Backup_NumArchives

1 – 1000000 (3)

Before every backup

If the number of archives to be backed up is not explicitly specified in arguments to the pibackup.bat backup script, then this timeout parameter defines the default number of archives to be backed up.

Backup Backup_TraceLevel 0 – 1000 (0)

Startup only This is the default backup trace level. Non-zero backup trace levels cause debug messages to be written to the PI Message Log. The default trace level can be overridden while the PI Backup Subsystem is running with the piartool –backup –trace <level> command.


Page 32


Read Description

Base BatchDbEditLogging 0 – 1 (0 boolean)

startup only Logging of Batch Database edits and deletions to the message log. This parameter does not apply to PIBatch Subsystem and is superceded by the Audit feature (EnableAudit) of the PI Server.

Base ModuleDb_CleanPeriodSec

30 – 3600 (300 sec)

startup only Frequency at which checks for idle modules are performed. Setting this limit too low may affect the performance of the Base Subsystem.

Base ModuleDb_MaxIdleCleanSec

0 – 604800 (3600 sec)

startup only Maximum idle time of MDb modules before being unloaded from memory. Checks are performed every ModuleDb_CleanPeriodSec seconds.

Base pibasess 1 – 10000000 (10000 µsec)


Base PointDb_CleanPeriodSec

30 – 3600 (300 sec)

startup only Frequency at which checks for idle points are performed. Setting this limit too low may affect the performance of the Base Subsystem.

Base PointDb_MaxIdleCleanSec

0 – 604800 (3600 sec)

startup only Maximum idle time of PI Points before being unloaded from memory. Checks are performed every PointDb_CleanPeriodSec seconds.

Base PointEditLogging 0 – 1 (0 boolean)

startup only Logging of point edits and deletions to the message log. This parameter is superceded by the Audit feature (EnableAudit) of the PI Server.

Base RecreateServerTrust

0 – 1 (1 boolean)

startup only Recreate missing trust entries for local machine access. These trust settings are used by SDK or API applications or interfaces running on the server node.

Base WindowsAuthentication

0 – 1 (1 boolean)

startup only Perform windows user authentication against a domain controller. This feature should only be disabled upon recommendation from a technical support engineer.

Base, Snapshot, Archive

EnableAudit 0 - 0xFFFFFFFF (0 bitmask)

startup only Auditing mask, -1 (or 0xFFFFFFFF) enable the audit of all databases. See Auditing the PI Server for details on acceptable values.




Read Description

Batch pibatch 1 – 10000000 (12000 µsec)


Message pimsgss 1 – 10000000 (12000 µsec)


NetManager backlog 5 – 1000 (5)

startup only Maximum number of pending TCP/IP connections.

NetManager connectionlocktimeout

1 – 1000 (90 sec)

startup only Amount of time to wait for a connection locked by another thread.

NetManager connectionwait 1000 – 1000000 (30000 msec)

startup only Amount of time for a new TCP/IP connection to become writable.

NetManager DefaultUserAccess 0 – 1 (1 boolean)

startup only Enable guest (or "world") access to the PI Server.

NetManager HealthCheckInterval 60 – 1000000 (1800 sec)

startup only Frequency at which health checks are performed between NetManager and the PI Subsystems. NetManager will close connections if subsystems don't respond to health checks.

NetManager keepalive -1 – 1 (-1 sec)

startup only TCP/IP keepalive option. A value of -1 is the system default, 0 indicates disabled.

NetManager linger_on 0 – 1 (0 boolean)

startup only Socket closure behavior (see linger_time).

NetManager linger_time 0 – NA (0 sec)

startup only Time in seconds to linger on socket closure, if linger_on is set

NetManager MaxConnIdleTime 300 – NA (see description)

By default, NetManager will not close connections regardless of idle time. NetManager can be configured to close inactive connections by setting MaxConnIdleTime to a value greater than or equal to 300 seconds. Entries less than 300 seconds or no entry results in the default behavior of no enforcement of disconnecting idle connections.

NetManager MaxMessageLength 10 – 512 (256 MB)

startup only Maximum size of messages handled by NetManager, PI3 Subsystems and PI SDK applications.

NetManager maxzerobytereads 0 – 1000 (100 bytes)

startup only Assume a connection close when receiving a series of zero-byte messages.


Page 34


Read Description

NetManager minbufsize 1 – 1000 (8 KB)

startup only TCP/IP send and receive buffers

NetManager pinetmgr 1 – 10000000 (10000 µsec)


NetManager ReadCompletionTimeout

120 - 0xFFFFFFFF (300 sec)

startup only Amount of time to block for read completion.

NetManager readretry 1 – 10000000 (250)

startup only Maximum retry attempts on read stream errors

NetManager readtimeout 1 – 50000000 (50000 µsec)

startup only Read timeout on network I/Os

NetManager reversenamelookupflag

0 – 1 (1)

startup only Translate IP addresses to IP host names on new connections.

NetManager ThreadStackSize 0 – 10 (0 MB)

startup only Stack of Net Manager worker thread. A value of 0 means the same as NetManager's main thread.

NetManager writeretry 1 – 10000000 (250)

startup only Maximum retry attempts on write stream errors

NetManager writetimeout 1 – 5000000 (50000µsec)

startup only Write timeout on network I/Os

PEScheduler

pipeschd 1 – 10000000 (50000µsec)


Snapshot EditDays 0 - (0)

startup only Number of past days where events can be modified in the Snapshot or Archive databases. A value of zero means no time check is done.

Snapshot pisnapss 1 – 10000000 (1000µsec)


Snapshot SnapFlushCycle 60 – 3600 (900)

startup only Snapshot table flush cycle or maximum time between consecutive flushes for a given point.




Read Description

Snapshot Snapshot_EventQueuePageSize

64 – 8192 (1024 KB)

startup only Size of the memory pages from the memory mapped Event Queue. This number must be a multiple of 64.

Snapshot Snapshot_EventQueuePath

- (path)

startup only Path where the memory-mapped queues are created (default is PI\dat). The primary queue name is always pimapevq.dat and overflow queues are pimq0000.dat, pimq0001.dat ... pimqFFFF.dat.

Snapshot Snapshot_EventQueueSize

8 – 131072 (64 MB)

startup only Size of the primary and overflow Event Queues on disk. This parameter should be adjusted according to archive event rate to avoid the creation of overflow queues.

Snapshot Snapshot_LowDiskSpaceMB

- (256 MB)

when overflow Event Queues are created

Minimum amount of free disk space to leave when creating overflow Event Queues (pimqXXXX.dat).

Snapshot, Archive

ArchiveEditLogging 0 – 1 (0)

startup only Logging of event edits and deletions to the message log. This parameter is superceded by the Audit feature (EnableAudit) of the PI Server.

Snapshot, Archive

Snapshot_EventQueueFlushPeriod

1 – 3600000 (30000 msec)

startup only Frequency at which the memory-mapped queue is flushed to disk by the Snapshot and Archive Subsystems.

SQL pisqlss 1 – 10000000 (12000µsec)


Totalizer pitotal 1 – 10000000 (12000µsec)


UpdateManager

MaxUpdateQueue - (4095)

startup only Maximum number of events per consumer held in the Update Manager.

UpdateManager

PIUPD_MaxConsTimeout

0 – 7200 (0 sec)

startup only Maximum value of client-supplied cleanup time for inactive consumer signups.

UpdateManager

PIUPD_MinConsTimeout

0 – 7200 (600 sec)

startup only Minimum value of client-supplied cleanup time for inactive consumer signups.

UpdateManager

PIUPD_TimeoutKillCons

0 – 1 (0)

startup only Remove timed out consumers in addition to removing all pending events.

UpdateManager

piupdmgr 1 – 10000000 (12000 µsec)



Page 36


Read Description

UpdateManager

TotalUpdateQueue - (100000 events)

startup only Maximum number of events in Update Manager for all consumers.

Utilities CheckUtilityLogin 0 – 1 (0)

startup only Force an interactive login from console utilities (piconfig, pisetpass).

Utilities piartool 1 – 10000000 (1000µsec)


Utilities piconfig 1 – 1000000 (1000µsec)


Utilities pigetmsg 1 – 1000000 (1000µsec)


Utilities pilistupd 1 – 1000000 (1000µsec)


Timeout Database Parameters for UNIX-based Systems On UNIX-based PI Systems, the low-level I/O routines use several PI Timeout table parameters. You might change the values of some of these parameters to get better performance for the specific version of UNIX you are running, the size of the PI System and so on.

The Timeout table parameters are stored in PI/dat/pitimeout.tbl. You can use piconfig to edit the values of Timeout Table parameters. Modifications to the PITimeout Table do not go into effect until PI is restarted.

The timeout table contains the entries shown below, where the time values are specified in microseconds:

$ piconfig

* (Ls - ) piconfig> @table pi_gen, pitimeout

* (Ls - PI_GEN) piconfig> @ostructure name, value

* (Ls - PI_GEN) piconfig> @select name=*

(Ls - PI_GEN) piconfig> @endsection

piarchss,10000

piartool,1

pibasess,10000

pimsgss,12000

pinetmgr,3000

pipeschd,50000

pisnapss,1000

piupdmgr,12000

readtimeout,50000

readretry,250

3.7 - Firewall Database


writetimeout,50000

writeretry,250

piconfig,1

pigetmsg,1

pilistupd,1

Most of the entries define a messaging timeout for the PI subsystems and utilities.

The other entries in the PItimeout Table are used as follows.

Readtimeout Time in microseconds to block in select call while reading and assembling a message

Readretry Number of retries to attempt while reading and assembling a message. Retries are attempted only on fatal errors, which are: EAGAIN, EWOULDBLOCK, ENOBUFS, and EIO.

Writetimeout Same as readtimeout, except acts on send call

Writeretry Same as readretry but acts on send call

The following message in pinetmgr.log (PI 3.1 build 2.74 and later) indicates that the READTIMEOUT or WRITETIMEOUT timing parameter reached the set limit.

PIstream::recv(SOCK_Stream *, int): select failed1 0

The following message in the application standard out indicates that the READRETRY or WRITERETRY timing parameter reached the set limit.

PIstream::recv(SOCK_Stream *, int): max retries exceeded

3.7 Firewall Database

The PI Firewall is a security feature that allows the PI Server Manager to control access to the PI Data Archive at the IP network address level. System administrators can allow or deny access by specific computers this way. More information is available in PI Server System Management Guide, Chapter 1, PI System Management.

3.8 Proxy Database

As of release 3.3, the Proxy Database is no longer in use. The Trust Database replaces it. During upgrade, existing proxy entries are converted to trust entries.

3.9 Trust Database

The Trust Database is used to grant PI client application access to the PI Server automatically. This is necessary for PI API and PI-SDK applications that run unattended, such as interfaces. It also allows for PI-SDK applications to support single user logons. The process authorizes the use of the access rights of a specific PI Server user.


Page 38

The PI System Administrator creates records in the Trust Database, mapping credential attributes such as Domain name, IP host name, IP address, Application name, and Operating System Username to a PI user.

Trusts can be specified exactly or by allowing entry, for example, to a group of users from a given domain.

The connecting application and PI Server obtain information about the client’s credentials. During client connection, the Trust Database is scanned for a match with the client’s credentials. If a match is found, the application is granted the access rights of the specified PI user.

It is possible that more than one trust record matches the incoming entry specifications. In such cases, the entry that matches the entry most closely will be granted access.

See PI Server System Management Guide, Chapter 1, PI System Management, for more details on configuring trust database records.

The Trust Database includes all the previously defined PIproxy records.

3.10 User Database

The PI User Database is where all PI users are defined. They may be assigned to groups. Groups must already be defined in the PI Group Database. Passwords are also stored here. Users maintain their passwords using the pisetpass utility.

3.11 Group Database

The PI Group Database is where all PI groups are defined. Members of each group may be viewed here. Membership is assigned only in the PI User Database.

3.12 Module Database

The PI Module Database stores and maintains all the data objects associated with the Module Database. This includes PIModules, PIHeadingSets, and PIHeadings. PIBasess maintains this database. All access to the PI Module Database is provided by the PI-SDK.

3.13 Batch Database

The PI Batch Database is the database for the PI Batch objects supported by the PI-SDK. This database is independent of the PI Batch Subsystem and the databases it maintains. The PI Batch Database is actually part of the PI Archive and is therefore, maintained by the PI Archive Subsystem. All access to the PI Batch Database is provided by the PI-SDK.

3.14 - List of Database Files


3.14 List of Database Files

The following table provides a list of database files for your reference. The files are organized by the subsystem to which they belong.

PIbasess Databases

File name Description

pipoints.dat Point Database

piptattr.dat Attribute Set Database

piptclss.dat Point Class Database

pidigst.dat Digital Set Database

pidignam.dat Digital State Name Database

piusr.dat User Database

piusrgrp.dat Group Database

PIModuleDb.dat Pi Module Database

piusrctx.dat User Context Database

pitrstrl.dat Trust Database

piptunit.dat Database reserved for future use.

piptalia.dat Database reserved for future use.

piptsrcind.dat Point Source index file. This is an index that allows for quick lookup by pointsource. This file is rebuilt automatically if it does not exist.

PIModuleUnitDb.dat Batch process unit index--an index of all modules with the IsPIUnit flag set to true. Automatically rebuilt if it does not exist.

piptcomind.dat Index of com connector points. Automatically rebuilt if it does not exist.

PIMsgss Databases

pimsgtxt.dat Message text resource

pimsg_yymmdd.dat Message logs where “yymmdd” represents date covered by file

PINetmgr Databases

pifirewall.tbl Firewall database

pitimeout.tbl Timeout database

pisubsys.cfg Inter-process communication info file

pisysid.dat Identifier data file


Page 40

PIbasess Databases

PIShutev Databases

shutdown.dat Shutdown event configuration file

Pisnapss Databases

piarcmem.dat Snapshot database

pimapevq.dat Event queue

pilastsnap.dat Time of newest event

PISqlss Databases

pisql.ini Site specific initialization file

Pisql.res Parsing resource


Chapter 4. PI POINT CLASSES AND ATTRIBUTES

A point is any measurement or calculation that is stored in the data archive. Points can represent transmitter readings, manual inputs, status control limits, and so on.

Note: The terms point and tag are sometimes used interchangeably, but the tag is actually the name of the point.

The configuration information for each point is stored as a list of attributes in the Point Database.

4.1 About Point Classes

The Point Database has several different point classes, such as Base and Classic.

Point class is assigned when the point is created. Each point class has a different set of attributes which define the parameters that describe a point. Default is Base point class.

The Base point class contains 39 attributes. Other point classes, such as Totalizer and Classic, include more attributes, in addition to the 39 attributes from the Base point class. The Totalizer Point Class is discussed in the PI Server Applications Guide.

Use the piconfig ptclass command to access the attributes belonging to a particular point class. For example, to display the attributes of the Classic point class, you would type:

@table pipoint

@ptclass classic

@?atr

As a shortcut, you can specify the point class name while setting the pipoint table with a single piconfig command:

@table pipoint,classic

The piconfig command ptclass is not to be confused with the attribute ptclassname.

4.2 Base Class Point Attributes

The Base class is a common set of attributes that all other point classes include. This section describes the user-assigned base class point attributes. The Base class also includes a set of system-assigned attributes that users cannot edit. See System-Assigned Attributes on page 62.

Chapter 4 - PI Point Classes and Attributes

Page 42

4.2.1 Tag The Tag attribute is the name of the point. Each Tag must be unique to a PI System. Since the tag is the name that identifies the point to users, it’s a good idea to use a consistent tag-naming convention that is meaningful to people in your organization. For example, you could reserve the first two characters of a tag to indicate a unit name or an area of the plant. You could reserve another 6 characters to match the standard instrument tag, and so on.

Tags may be any length and can include letters, numbers, and spaces. Tags are subject to the following constraints:

The first character must be alphanumeric, ‘_’, or ‘%’

No control characters are allowed; such as linefeeds or tabs

The following characters are not allowed: * ’ ? ; { } [ ] | \ ` ‘ “

(However, these characters are allowed in other tag attributes, such as the descriptor.)

Any tags that follow the above rules are, technically, allowed. However, be aware some legal characters, such as the ‘_’, are used by other applications in special ways. For example, SQL uses ‘_’ as a wild card. Using these in tags, may cause problems with these applications.

Note: The PI API functions pipt_tag and pipt_updates truncate the tag to 12 characters. Routines pipt_findpoint, pipt_wildcardsearch, pipt_taglong, and pipt_tagpreferred will report only the first 80 characters.

Case Sensitivity The system preserves the case of all strings, including the tag, but searches are not case-sensitive. For example, a string entered as BatchStart is stored exactly as entered. Subsequent retrievals of this string retain the same capitalization. A search for this string does not require that the capitalization match.

Changing Tag Names To change the tag attribute, use the piconfig utility and the NEWTag attribute in the PIPoint table. Keep in mind that when you change a tag, certain programs that retrieve data using that tag, such as FactoryTalk Historian DataLink spreadsheets, might also have to be updated. FactoryTalk Historian ProcessBook displays automatically use the new tag name.

4.2.2 PtClassName The PtClassName attribute needs to be defined at point creation time. PtClassName defines what attributes a point is to have. Prior to PI 3.4.370 the point class of a point could not be changed once the point was created. In versions 3.4.370.x or greater it can be edited. See Point Class Edit.

4.2 - Base Class Point Attributes


4.2.3 PointType There are many point types in the PI Server. PointType is assigned when the point is created. Prior to PI 3.4.370.x this attribute could not be changed, but in versions 3.4.370 or later it can be edited. See Point Type Edit.

Table 4–1. Point Types

Point Type How It Is Used

Digital Used for points whose value can only be one of several discrete states, such as ON/OFF or Red/Green/Yellow. Nearest equivalent to the PI 2.x Digital type.

Int16 Used for points whose values are 15-bit unsigned integers (0 to 32767). Nearest equivalent to the PI 2.x Integer type.

Int32 Used for points whose values are 32-bit signed integers (-2147450880 to 2147483647). PI reserves the lowest 32K values of the 32bit range for digital states.

Float16 Used for floating point values, scaled. The accuracy is one part in 32767. Nearest equivalent to the PI 2.x Real type.

Float32 Used for single-precision floating-point values, not scaled.

Float64 Used for double-precision floating-point values, not scaled.

String Used to store string data of up to 976 characters.

Blob Binary large object – Used to store any type of binary data up to 976 bytes.

Timestamp Used to store values of type Timestamp. Any Time/Date in the Range 1-jan-1970 to 1-Jan-2038

Choosing Point Type For points collected automatically, use the point type that most closely matches the point type in the source system. For example, if the point originates from a transmitter that supplies an analog measurement with 14 bits of accuracy, use the float16 point type. This point type provides 15 bits of precision.

For accumulators and other high precision values, use the higher precision point types:either float32 or float64.

The higher precision point types require more disk space for each stored value. Float16 points use 16 bits or 2 bytes per value. Float32 and float64 use 4 and 8 bytes per value, respectively. Int16 and int32 values use 2 and 4 bytes, respectively. Int16 is similar to a PI 2 integer type; it supports only 15-bit unsigned integers.

If you want to store negative integers, select the int32 point type. Note that PI reserves some values in the negative range of a 32-bit integer. The smallest value that can be stored is shown in the table above.

Interface manuals sometimes refer to point types R (real), I (integer), and D (digital).

Use float16 or float32 for type R. If the data are coming from an analog-to-digital converter (ADC); float16 is sufficient.


Page 44

Use int16 or int32 for type I or integer values.

Use digital for type D or discrete values.

Float16 vs. Float32 Rockwell Automation recommends using float32 as the default type for floating point data. Only tags with very large amounts of data (more than 1000 values per day) that is frequently retrieved should be configured as float16, and their configuration should match the input device.

The space saving of float16 can reduce the amount of I/O. This is significant only on very large data retrievals, for example yearly average calculations or long term trends. There is no impact on the initial storage of incoming data.

Attributes that Depend on Point Type Some point attributes are not relevant for some point types:

Only Digital type tags use the DigitalSet attribute. It is irrelevant for other type tags and can be ignored.

For Digital, string and Blob type tags, the values of CompDev, CompDevPercent, ExcDev and ExcDevPercent are not applicable. The value of these attributes is automatically returned to applications as zero.

For Digital, string and Blob type tags, the Span and Zero attributes are not applicable. For digital tags, Zero and Span will be automatically set to the digital set number and the number of states minus 1 in the set, respectively.

4.2.4 NewTag The NewTag attribute is used for renaming tags.

4.2.5 Descriptor The Descriptor is a text field that appears on various client application displays and may be used in reports. It may be of any length up to 65,535 characters. When this value is read through the PI API it is truncated to 26 characters.

Be aware that some interfaces use the descriptor for tag configuration on external system. Having quotes or wild card characters might lead to confusion when these attributes are passed to other applications.

4.2.6 ExDesc The Extended Descriptor is a text field of any length (although it is truncated to 80 characters when reported through PI API). For most points, it is used only to provide additional information for documentation. Several interfaces use this attribute to encode additional configuration information.



4.2.7 TypicalValue The Typical Value is used only to document an example of a reasonable value for this point. For a numeric tag, it must be greater than or equal to the zero, and less than or equal to the zero plus the span.

4.2.8 DigitalSet Only Digital type tags use the DigitalSet attribute. It is irrelevant for other type tags and can be ignored.

A collection of digital states is called a digital state set. For example, a digital state set can consist of two states {OPEN, CLOSED}. You might also define a digital state set that consists of {RED, GREEN, BLUE, YELLOW, and ORANGE}. Typically there will be many digital state sets defined for a system.

For digital points, the DigitalSet attribute specifies the name of the digital state set associated with the tag. The DigitalSet attribute has no meaning for non-digital tags. However all tags are associated with the system state set. The system state set contains a collection of all the states that may be used for any point. Examples are Shutdown, Over Range, I/O Timeout, etc.

4.2.9 Zero A zero is required for all numeric data type points to indicate the lowest value possible. It does not have to be the same as the instrument zero, but that is usually a logical choice. Certain interfaces require that the zero and span match the instrument system range; see the interface documentation for details.

The zero is the bottom of the range used for scaling float16 values in the PI Archive. If the value for a float16 type point is less than the bottom of range, it is recorded in the archive as Under Range. The digital state is substituted for the under range value when the archive cache is flushed to disk. The zero is also used when defining a FactoryTalk Historian ProcessBook trend with a vertical scale of database.

This attribute is not used for non numeric points.

4.2.10 Span The Span is the difference between the top of the range and the bottom of the range. It is required for all numeric data type points.

For float16 point types, the span is used with the zero for scaling values in the archive. The span must be a positive value. If the value for a point type float16 point is greater than the top of range, it is recorded in the archive as “Over Range.” For other point types, zero and span do not affect the values recorded in the archive.

The span is also used when defining a FactoryTalk Historian ProcessBook trend with a vertical scale of database.

This attribute is not used for non numeric points.


Page 46

4.2.11 Impact of Changing Zero and Span The Zero and Span for a tag can be changed without affecting data already in the archive. For points of type Float16, the old zero and span are used for retrieving the archive data collected before the edit. The new zero and span are used for data collected after the edit. When span is changed, the exception and compression deviation percents are preserved. This means that the excdev and compdev fields, which are expressed in engineering units, are modified internally. If any of the deviation fields is specified in the editing operation they take precedence.

Note: Some interfaces might use Zero/Span information to filter incoming data. These interfaces often convert out of range data to digital states over range and under range, however, interfaces might use Zero/Span configuration in other ways. The PI Server itself does not change out of range data except for tags of type Float16.

4.2.12 EngUnits The engineering unit string describes the units of the measurement. You may use any string, and the string may be of any length. However, the PI API will retrieve only the first 12 characters. The PI-SDK does not truncate the string.

Examples include:

DEGF

Degrees Centigrade

Gal/Min

Gallons Per Minute

‘“Hg

Engineering unit strings are case preserving and case-insensitive. The system trims leading and trailing blanks are trimmed during input.

A single quote (‘) in a string must be preceded by a double quote (“). Similarly, a double quote in a string must be preceded by a single quote. Long strings can be used for more readable engineering units.

4.2.13 PointSource The PointSource attribute is a string that associates a tag with an interface or PI module. In order for an interface to read or write to a point, the PointSource attribute must match the point source setting for that interface.

The default point source is “Lab.” Use this for points that are not associated with any interface to specify lab-input points.

The ‘%’ (percent) character has also special meaning for SQL and other applications. Using it as a point source can lead to confusion. Similarly, it is advisable to avoid using ‘?’ or ‘*’ as point source character.



4.2.14 SourceTag For data output to other systems, the SourceTag is the PI tag of the data source. For example, you can define a tag ABC to receive data using point source A, then define another tag DEF to send this information to another instrument system using point source B. The source tag for tag DEF would be ABC. This attribute is used by some interfaces, while other interfaces use the extended descriptor (ExDesc) for this information.

The SourceTag attribute is not stored in the Point Database. It is only a more readable representation of the srcptid attribute which holds the source point ID. srcptid does not exist in all point classes. For example, it is part of the classic point class but not of base. If you try to edit SourceTag for points of point-classes that do not have the attribute, you get an error.

4.2.15 ExcDev, ExcMin, ExcMax and ExcDevPercent Most interface programs use exception-reporting specifications to determine when to send data to the Snapshot. The exception reporting specifications consist of a deviation (ExcDev), a minimum time (ExcMin), and a maximum time (ExcMax). ExcDevPercent is similar to CompDev, but it specifies the compression deviation in percent of Span rather than in engineering units. If one is changed by user, the other is automatically changed to be compatible. If both are changed at once ExcDevPercent takes precedence.

For digital, string and Blob tags, ExcDev and ExcDevPercent are ignored. They are displayed by applications as zero.

4.2.16 Scan Flag Some interface programs use a Scan flag. Interfaces that honor this attribute will not update points whose scan flag is set to OFF. Refer to the documentation to see if your interface program uses it.

4.2.17 Compressing Flag Compression should be turned on for all real-time points in the system. Set compression OFF for laboratory and manually entered tags so every value is recorded in the archive. Even with compression turned off, the number of events for these tags is usually small.

To turn compression on, set the Compressing attribute should be set to ON (1) for most points. With compression off, every value sent to the Snapshot is saved in the archive.

Compression affects digital points, since a new value is recorded only when the current value changes. Points of types Blob and string have a similar behavior; new events pass compression only when the value changes. String values are compared ignoring case. (“VaLuE” and “valUe” are equal) . For Blob events, any change is significant.

4.2.18 CompDev, CompMin, CompMax and CompDevPercent When a new Snapshot arrives, the previous one is evaluated according to the compression specifications to see if it is a significant event. If so, it is sent to the Event Queue. If not, it is discarded. The result is that only significant data are written to the archive. This process is called compression.


Page 48

The compression specifications consist of a deviation (CompDev), a minimum time (CompMin), and a maximum time (CompMax):

CompMin: An event is archived if the elapsed time since the previous event is greater than or equal to the minimum time and the value has changed by more than the deviation. For points associated with interfaces that send exception reports, the CompMin should be 0.

CompMax: Events are also archived if the elapsed time is greater than the maximum time. The recommended maximum time specification is one work shift (e.g., 8 hours). Duplicate values will be archived if the elapsed time exceeds CompMax. Under no circumstances does this cause PI to generate events; it only filters events that are externally generated.

CompDev: The most important compression specification is the deviation, CompDev. Setting this value too low causes too little data compression and wastes space in the archive. Setting this value too high causes loss of useful data. For most flows, pressures, and levels, use a deviation specification of 1 or 2 percent of span. For temperatures, the deviation should usually be 1 or 2 degrees.

CompDevPercent: This is similar to CompDev, but it specifies the compression deviation in percent of Span rather than in engineering units. If one is changed by user, the other is automatically changed to be compatible. If both are changed at once CompDevPercent takes precedence.

For non numeric tags, CompDev and CompDevPercent are ignored. They will be displayed by applications as zero.

Out of Order Events Events that are sent to the PI Server out of time order bypass the compression calculation and are sent to the archive.

Turning off Compression To turn off compression (that is, to archive every event), set the Compressing attribute to OFF (0).

4.2.19 Archiving The Archiving flag must be set to ON (1) for a point to be archived. This flag can be set to OFF (0) to stop archiving of a point.

4.2.20 Step The Step flag affects only numeric points. It defines how numeric archived values are interpolated. The default behavior, step OFF (0), treats archived values as a continuous signal. Adjacent archived values are linearly interpolated. For example, at 12:00:00, the value 101.0 is archived and at 12:01:00, the value 102.0 is archived. A request for the archive value at 12:00:30 would return 101.5.

A step flag of ON (1) treats the archived values discretely. Adjacent archived values are not interpolated; an archived value is assumed constant until the next archived value.



For example:

At 12:00:00, the value 101.0 is archived,

At 12:01:00, the value 102.0 is archived,

A request for the value at 12:00:30 would return 101.0.

In general, data coming from continuous signals should be archived in points with the step flag OFF. Examples might include signals from thermocouples, flow meters, etc. Data coming from discrete measurements should be archived in points with the step flag on. Examples are sampled lab data, batch charge weight.

In addition, the step flag affects the compression calculation. When it is ON (1) a linear change of value greater than or equal to CompDev passes compression. This is essentially the same as the exception calculation explained above. When the step flag is OFF (0) the complete swinging-door algorithm is applied.

PtOwner , PtGroup, PtAccess, DataOwner, DataGroup, DataAccess The access permission specifications allow restricted access to be configured independently for both point attributes and point data. Users are defined in the PI User Database. Groups are defined in the PI Group Database.

A PtOwner is assigned to own the point attributes. A DataOwner is assigned to own the data. PtOwner and DataOwner can be the same. The default for both attributes is the creator of the point.

A group is assigned to be the group for the point and for the data (PtGroup and DataGroup).

Read/write access permissions for owner, group, and world (default) are set using the PtAccess and DataAccess attributes. Some examples of access permissions are:

o:rw g:rw w:rw (everyone can read and write)

o:rw g:r w:r (owner write; everyone read)

o:rw g:r w: (owner write; owner and group read)

See the Security section in PI Server System Management Guide for a full discussion on security.

DisplayDigits The DisplayDigits attribute controls the format of numeric values on screens and in reports. Zero or a positive number indicates the number of digits to display to the right of the decimal point. A negative number indicates the number of significant digits to display. In this case, the absolute value of DisplayDigits is the number of significant digits.

The following table shows how a value of 23.45 would appear on the screen for different values of DisplayDigits:

DisplayDigits Format

3 23.450


Page 50

DisplayDigits Format

2 23.45

1 23.5

0 23.

-1 2E+001

-2 23.

-4 23.45

Shutdown Flag In some cases it is useful to record, to PI Points, when the Archive was shut down. That way there is a clear indication of a gap in the data collection. Points may be configured so that PI will automatically add a shutdown event with the timestamp of the PI Server shutdown. These events are called shutdown events.

The shutdown flag for a point is set to TRUE (1) to indicate that shutdown events should be recorded for this tag. The default is TRUE.

For points collected from interfaces on distributed collection nodes, set this flag to FALSE (0) because data buffering in PINet or PI API will retain the data until the home node is running again. Therefore, there are no data gaps to identify with shutdown events.

Many sites configure points that store laboratory test values so that the lab test points will not receive shutdown events. Lab values are assumed to be constant between tests. Inserting shutdown events for these points can be misleading.

The shutdown flag is used in conjunction with the configuration file dat\shutdown.dat.

4.3 Classic Point Class Attributes

Standard OSI interfaces rely on classic attributes. Use the Classic point class for all points using a PI interface that uses the InstrumentTag or location code attributes.

4.3.1 Instrument Tag When a value is retrieved from or sent to an external system such as a DCS, the instrument tag is used by some interfaces as the tag in the external system. The InstrumentTag field can be any length. However, most interfaces only use the first 32 characters of this attribute. Some interfaces use the extended descriptor (ExDesc) instead.

4.3.2 Location1, Location2, Location3, Location4, and Location5 There are five integer location codes. Their meaning depends on the interface.

For many PI interfaces, you use the Location1 attribute to specify the interface ID number and the Location4 attribute to assign scan class. For instrument interfaces, the location codes

4.3 - Classic Point Class Attributes


often describe a hardware or software address for reading or writing the value. Refer to the interface documentation to set these point attributes.

4.3.3 SquareRoot Some interface programs use the square root code. Check the manual for your interface.

4.3.4 UserInt1, UserInt2, UserReal1 and UserReal2 PI reserves these four attributes for user applications. Most PI applications do not use these attributes. UserInt1 and UserInt2 are 32-bit integers. UserReal1 and UserReal2 are 32-bit floating-point numbers.

4.3.5 Filtercode The Filtercode indicates the time constant of a first-order filter used to smooth incoming data. Rockwell Automation recommends not altering incoming data by leaving this code at its default value of 0. The other options are:

Code Time Constant (Sec.)

1 10

2 60

3 120

4 600

4.3.6 Totalcode The Totalcode was used by the PI System for OpenVMS to control Totalizer processing. PI for Windows and UNIX do not use Totalcode. See Totalizer Subsystem in the PI Server Applications Guide for instructions on configuring the Totalizer for PI for Windows and UNIX.

4.3.7 Srcptid This is the PI point number corresponding to the tag specified in the SourceTag attribute. If this attribute is edited, PI will change SourceTag to the corresponding tag. This attribute should not be altered directly; change SourceTag instead.

4.3.8 Convers The Convers attribute was used by the PI System for OpenVMS to control Totalizer processing. PI for Windows and UNIX does not use Convers. See Totalizer Subsystem in the PI Server Applications Guide for instructions on configuring the Totalizer for PI for Windows and UNIX.

4.3.9 Ranges of ExcMax and CompMax In early releases of PI 3, the values of these two point attributes were stored as unsigned 16-bit integers, which meant that the maximum value of each was 65,535 seconds. This will


Page 52

continue to be true for existing systems upgraded to PI 3.3 or greater, but from PI 3.4.370.x or greater these attributes can be edited to uint32 type. See Attribute Sets Database Edit.

In new installations of PI 3.3 or greater releases, the values of these two point attributes are stored as unsigned 32-bit integers, and the maximum value of each is 4,294,967,295 seconds.

The PI API protocol defines the ExcMax and CompMax attributes as a signed 16-bit integer. If the PI Server stores a value that is larger than 32,767, the value returned by the PI API will be 32,767.

PI-SDK applications will obtain from the PI Server a signed 32-bit integer values for ExcMax and CompMax.

4.4 COM Connector Point Attributes

COM Connectors allow the PI Server to obtain data from foreign data systems. To do this, you must create a special PI Server point whose attributes identify the location of the data in the foreign system.

The term map is used throughout this manual to mean making a relationship between a point on the foreign system and a point on the PI Server. During PI Server operation, clients make requests for data by using PI Server point information. The PI Server will then obtain data from the foreign system point to which the PI Server point is mapped.

The PI Server does not use a specific value of the PointSource attribute to identify mapped points. A specific point class name is not needed either. Instead, you must define a point class that includes the following attributes:

Attribute Name Description

ctr_progid COM Program ID, as stored in the Windows registry. This name is used to instantiate the COM Connector object.

ctr_lmap Longword mapping parameter.

ctr_strmap String mapping parameter.

A point is identified as a PI Server mapped point if it includes these three attributes.

The ctr_progid is used by the PI Server to load the COM Connector. The mapping parameters ctr_lmap and ctr_strmap are passed to the COM Connector through a COM method call so that it can locate the appropriate foreign system point. The usage of these two attributes is always specified in the manual for any COM Connector.

The PI Server has a script file called classicctr.dif that can be processed by the piconfig utility to define a point class called classicctr. This point class has all the attributes of the classic point class plus the three attributes that define mapped points. The classicctr.dif file can be used directly, or as a template for custom point class definitions.

4.5 - Default Values for Point Attributes


4.5 Default Values for Point Attributes

When you create a point, at a minimum you must specify the tag attribute. For all other attributes, if you don’t assign a value to that attribute, then PI uses the default value. The default values for PI point attributes are listed in the following table.

Table 4–2. Point Database Default Table

Point Class

Field Name

Default Value

Limits

Base Archiving On On, Off, 1, or 0

Base ChangeDate System-assigned

Base Changer System-assigned

Base CompDev 2 (eng units)

Base CompDevPercent Comes from CompDev 0 ≤ x ≤ 100

Base CompMax 28800 (sec) see next subsection

Base CompMin 0 (sec) 0 ≤ x ≤ 65535

Base Compressing On On, Off, 1, or 0

Classic Convers 1

Base Creationdate System-assigned

Base Creator System-assigned

Base DataAccess O:rw g:r w:r Owner, group, and world may be assigned read, write, or no access (blank)

Base DataGroup Piadmin In PI Group Database

Base DataOwner Piadmin In PI User Database

Base Descriptor blank

Base DigitalSet no default Used only for digital tags This must be specified when the point is created.

Base DisplayDigits -5 -20 ≤ x ≤ 10

Base EngUnits blank

Base ExcDev 1 (eng units)

Base ExcDevPercent Comes from ExcDev 0 ≤ x ≤ 100

Base ExcMax 600 (sec) see next subsection


Page 54

Point Class

Field Name

Default Value

Limits

Base ExcMin 0 (sec) 0 ≤ x ≤ 65535

Base ExDesc blank

Classic Filtercode 0

Classic InstrumentTag blank

Classic Location1 0

Classic Location2 0

Classic Location3 0

Classic Location4 0

Classic Location5 0

Base NEWTag

Base PointID System-assigned

Base PointSource Lab

Base PointType Float32

Base PtAccess O:rw g:r w:r Owner, group, and world may be assigned read, write, or no access (blank)

Base PtClassName Base Base, classic, Totalizer, alarm

Base PtGroup Piadmin In PI Group Database

Base ptOwner Piadmin In PI User Database

Base RecNo System-assigned

Base Scan On On, Off, 1, or 0

Base Shutdown True

Classic SourceTag blank

Base Span 100 x ≥ 0

Classic SquareRoot 0 On, Off, or 0 <= x <= 10

Classic Srcptid 0

Base Step Off

Base Tag no default This must be specified when the point is created.

4.6 - System-Assigned Attributes


Point Class

Field Name

Default Value

Limits

Classic Totalcode 0

Base TypicalValue 50 Zero ≤ x ≤ (zero + span)

Classic UserInt1 0

Classic UserInt2 0

Classic UserReal1 0

Classic UserReal2 0

Base Zero 0

Other The Totalizer Point class includes other attributes, which are discussed in the PI Server Applications Guide, Chapter 6, "Totalizer Subsystem."

Note: Programmatic access to some of the attributes may be limited or unavailable from the PI API.

4.6 System-Assigned Attributes

When you create a point, several attributes are assigned by the system. You cannot change the values of these attributes.

4.6.1 Creator The user who created the point.

4.6.2 CreationDate The date and time when the point was created.

4.6.3 Changer The last user to edit the attributes for this point.

4.6.4 ChangeDate The date and time when the attributes for this point were last edited.

4.6.5 PointID The PointIdentifier is a unique number that identifies the point internally. PointID is never reused, even when a point is deleted. This is the PI PointIDentifier that is passed as a parameter to most of the PI API functions. In the PI API Manual, this identifier is referred to as the point number, or PtNum.


Page 56

4.6.6 RecNo The record number is a read-only point attribute that contains the point's primary record number in the archive. This is useful when using tools such as piartool -aw to examine the archives. RecNo is not to be confused with the PointID attribute.


Chapter 5. PI POINT CLASS EDIT

5.1 Introduction

A PI point consists of a set of attributes. What attributes a point has is uniquely determined by its point class. A PI point class consists of a group of PI point attribute sets, each of which consists of some attributes. The attributes of a point is therefore built by grouping attributes into attribute sets, and then grouping the attribute sets into a point class and assigning the point to this point class. A PI point class cannot consist of attribute sets that have overlapping attributes.

Figure 5-1. Formation of a point class

Point class is assigned to a point when it is created. Prior to PI 3.4.370 it was not possible to change the attributes of a point once it is created and assigned to a point class. In PI 3.4.370.x or greater users can edit and delete attribute sets and point classes.

Chapter 5 - PI Point Class Edit

Page 58

1. Attributes ExcMax and CompMax in base attribute set may now be edited from uint16 to uint32.

2. It is now also possible to switch a point from one class to another, new or existing, so that the same point can continue to collect data seamlessly even though its collection mechanism has changed. For example, one can convert a Totalizer point to a PE point, which belongs to classic point class, or vice versa, while keeping the same tag.

3. The user can also change the attributes of a point by adding or removing or changing the types of attributes in the point class of the point. This affects all points that belong to that point class.

4. By allowing addition, removal and edit of the attributes of point classes, we can allow the same points to retain their history and continue to collect new data even when the attribute requirements of the data collecting applications change.

5.2 Overview

Changing the attributes of a point can be accomplished as follows:

1. Edit the PtClassName attribute of the point to the point class that contains the desired attributes.

2. Edit the point class directly so that it contains the desired attributes. A point class can be edited by changing the attribute sets that make up the point class. That is, attribute sets can be added to or deleted from it.

3. Edit the point class implicitly by editing one or more attribute sets that form the point class. Editing an attribute set triggers edits of all point classes that use the set.

4. Editing a point class, implicitly or directly, triggers edits of all points in that point class. Therefore a point’s attributes can be modified by editing one or more attribute sets via implicit edits of point classes and points.

This chapter discusses in detail each of theses processes:

Editing an Attribute Set

Editing a Point Class

Editing the PtClassName Attribute of the Point

Only piadmin is allowed to delete and/or edit attribute sets and point classes. This restriction was imposed to prevent cases where implicit point class and point edits might fail due to varying ownerships and permissions.

Attribute sets and point classes may be edited or deleted only in stand alone mode in which PINetmgr will close the TCP/IP listener and disallow any client connections. Existing PI-SDK, PI API and PI Server Application connections will be closed, and reconnection attempts refused for the duration of the stand alone mode. Subsystems and locally run utilities such as piconfig and piartool can connect. Default-only attribute edits are supported in Normal mode.

5.2 - Overview


The command PIartool –standalone 1 puts the system in stand alone mode (no clients can connect), and PIartool –standalone 0 sets it in normal operating mode. PIartool –standalone 2 queries what mode the system is in.

There are some restrictions on which attribute sets and point classes may be edited or deleted. Below is a summary of the restrictions:

Allow adding attribute(s) to any set except for the Base attribute set.

Note: Any attribute added to a predefined set cannot be removed due to rules 2b, 7a and 9a below: the predefined attribute sets are required by predefined point classes and predefined point classes may not be deleted. So, they are always in-use. It is recommended that the user create a new attribute set with new attributes when expanding a point class rather than adding new attributes to a predefined set. For the list of predefined attribute sets and point classes see Appendix.

Allow deleting attributes from a set except from predefined sets (those created by OSI) if they are required attributes

In-use attribute sets

Disallow renaming attributes

Allow renaming attribute sets except • Predefined attribute sets

Allow deleting attribute sets except • Predefined attribute sets • In-use attribute sets

Allow adding attribute sets to any point class

Allow deleting attribute sets from a point class except from • Predefined classes (created by OSI) if they are required attribute sets1 • In-use point classes

Allow renaming point classes except • Predefined point classes

Allow deleting point classes except • Predefined point classes

In-use point classes

These restrictions were imposed to protect the attribute sets and point classes that PI system itself uses as building blocks. These restrictions can limit the user’s ability to easily undo

1 Predefined point classes and their required attribute sets are listed in the Appendix.


Page 60

some actions. To demonstrate how involved undoing some actions can be, suppose that a user added an attribute set to a point class by mistake. In order to restore the original point class, all the tags in this class need to be edited to belong to another class so that the class is no longer in-use. Then the undesired attribute set can be removed from the point class. Finally, the points can be edited back to the original point class.

It is CRUCIAL to make a backup of the point database before attempting to edit attribute sets or point classes. One can delete attribute sets from predefined point class as long as the class is not in use and the set to be deleted is not a required set for that point class. Remember that any attribute added to a predefined attribute set cannot EVER be removed.

piconfig utility can be used to perform these edits and deletes after placing PI server in stand alone mode using PIartool utility as discussed above. Examples are shown in the following sections as appropriate.

5.3 Attribute Sets Database Edit

The following sub-sections discuss three operations that modify the PI Attribute Set database:

Attribute Set Create

Attribute Set Delete

Attribute Set Edit

5.3.1 Attribute Set Creation An attribute set can be created by specifying the set name and the attribute names, types and default values. If the type is not specified float32 is assigned. If default value is not specified, it is set by PI. Allowed types and defaults (in parentheses) are listed below. Types not listed below are not supported, and will either be rejected outright at attribute set creation time or have unexpected behavior.

Supported Attribute Types and Defaults String (“”)

Int16 (0)

Int32 (0)

BYTE (0)

UBYTE (0)

Uint16 (0)

Uint32 (0)

Timestamp (“31-Dec-69 16:00:00”)

5.3 - Attribute Sets Database Edit


Float32 (0)

Bool (0)2

Disallowed Attribute Names The following attribute names are not allowed in any user-defined attribute set:

Built-in attribute names:

PointID

PtClassName

Recno

PtOwner

PtGroup

PtAccess

DataOwner

DataGroup

DataAccess

DigitalSet

Excdevpercent

Compdevpercent

SourceTag

NEWtag

Reserved names:

NEWCLASS

NEWSET

Set

Class

Base attribute names

Tag

Descriptor

exdesc

2 Note that Boolean values will show as either 1 or 0 instead of true or false. All non-zeros are interpreted as true, and 0 is interpreted as false.


Page 62

typicalvalue

engunits

zero

span

pointtype

pointsource

scan

excmin

excmax

excdev

shutdown

archiving

compressing

step

compmin

compmax

compdev

creationdate

creator

changedate

changer

displaydigits

The built-in attributes are added to all points. Their types and defaults cannot be modified by user. However, the values of non system-assigned attributes such as PtOwner, PtGroup, PtAccess, DataOwner, DataGroup, DataAccess, DigitalSet, ExcDevPercent, CompDevPercent, SourceTag and NEWTag can be modified by user.

Base attribute set is created by OSI and its edit is severely restricted. See Attribute Set Edit for further details. Attribute name checks are case-insensitive.

Example of Creating an Attribute Set Below is an example of how to create an attribute set in piconfig utility. Stand alone mode is not required for creating an attribute set.

@table piatrset

@mode create

@istru set



@istru attrib,type,default

@istru ...

MyAttributeSet

MyAttribute1,BYTE,

MyAttribute2,int32,2

MyAttribute3,string,”Default string”

MyAttribute4,,

@ends

MyAttribute4 will be assigned the type float32, and default of 0.0. The

following lists the attribute set just created.

@table piatrset

@mode list

@ostru set

@ostru attrib,type,default

@ostru ...

@select set=MyAttributeSet

@ends

The output will look like

MyAttributeSet

MyAttribute1,BYTE,0

MyAttribute2,Int32,2

MyAttribute3,String,Default string

MyAttribute4,Float32,0.

* End Repeat...

*----------

5.3.2 Attribute Set Deletion An attribute set can be removed by simply specifying the set name.

Predefined attribute sets are used as building blocks for PI point classes and may not be removed from the database. When an attribute set deletion is requested, whether it is a removable attribute set is checked. If not a removable set, an error is returned. The following sets are predefined sets and may not be removed.

Alarmparam

Base

Classic

Sqcalm_parameters

Totals

If the set to be removed is in use by any point class, an error is returned.

Example of Deleting an Attribute Set An example of how to remove an attribute set is given below.

First place the system in standalone mode using PIartool in command window.


Page 64

PIartool –standalone 1

Then launch piconfig in command window, and type the following.

@table piatrset

@mode delete

@istru set

MyAttributeSet

@ends

When finished place the system back in normal mode.


5.3.3 Attribute Set Edit An attribute set can be edited by adding, removing attributes and/or changing attribute types and default values.

Edits other than default-only edits require that the system be put in Stand Alone mode by running piartool utility as follows.

PIartool –StandAlone 1

PIartool –StandAlone 0 puts the system back in Normal mode. Default-only edits do not require stand alone mode.

Internally, an attribute set edit (except for default-only edits) is actually done in 4 steps:

Rename the original set to a temporary name, “OriginalName~someGUID”.

Create a new set with desired attributes under the original name.

Trigger implicit point class edits, which in turn will trigger implicit point edits.

Remove the original set from the database after successful implicit edits.

These steps are transparent to the user, but each of these steps is audited if auditing is enabled for the base subsystem.

Default-only edits modify the existing sets directly instead of following the above steps. Default edit triggers implicit point class edits but point edits. This is because the new defaults will only be applied to new points. In the rest of this document an edit implies non default-only edits unless explicitly stated otherwise.

Implicit Point Class and Point Edits When an attribute set is edited, all dependent point classes and points are edited without user intervention. These edits are referred to as implicit edits.

Implicit point edits keep the existing attribute values if they are still in the edited attribute set that triggered the implicit point edit and are compatible with the new types. If the new attribute type is not compatible with the old one, the new default takes precedence over the existing attribute’s value. This situation can arise if the old attribute’s type changed, for example, from string to int32. If the original string value of the attribute cannot be converted to an int32, the new default for this attribute type will prevail. Another example is the case



the existing value no longer fits in the new type. For example, if the type changed from float32 to BYTE, and the existing value was 128.0, then the value will be set to 0.

Note that implicit point edit does not validate the point configuration. That is, if a point with improper configuration (e.g. a Totalizer point with no sourcetag) is implicitly edited, the implicit edit will succeed although direct edit of the point would have failed validation.

In implicit point edits, additional, if any, attributes are assigned default values until the user explicitly edits them later. That is, consider a point belonging to a class with base attribute set and another attribute set called MyAttributeSet. Suppose that MyAttributeSet originally contained MyAttribute1, MyAttribute2, and MyAttribute3, but was edited to include another attribute called MyAttribute4. The point will be implicitly edited and will now have the additional attribute MyAttribute4. This attribute will be set to the default by the implicit edit process.

Base Attributes and Allowed Types Base attribute set edit is disallowed except to convert the types of CompMax and ExcMax attributes from uint163 to uint32 and to change the default values of any attributes in this set.

Name Allowed type

Descriptor String

Exdesc String

Typicalvalue float32

Engunits string

Zero float32

Span float32

Pointtype ubyte

Pointsource string

Scan uint16

Excmin uint16

Excmax uint16 or uint32

Excdev float32

shutdown byte

Archiving byte

3 PI versions earlier than 3.3 were shipped with uint16 type for excmax and compmax.


Page 66

Name Allowed type

Compressing byte

Step byte

Compmin uint16

Compmax uint16 or uint32

Compdev float32

Creationdate timestamp

Creator uint16

Changedate timestamp

Changer uint16

Displaydigits byte

Built-in Attributes Built-in attributes are part of every PI point, but do not belong to any particular attribute set. The types and defaults of built-in attributes, which are frequently mistaken as belonging to the base attribute set, do not belong to any attribute set explicitly and cannot be edited. This is not to say that individual point’s built-in attribute values cannot be edited. Non system-assigned attribute values may be edited.

Example of Editing an Attribute Set If an attribute set is edited, its dependent point classes and, subsequently, dependent points are edited internally by the PI Base Subsystem. No explicit editing of the PI point classes database by a user is necessary. Such indirect edits are henceforth referred to as implicit edits.

To illustrate, suppose a user wishes to change a set called MyAttributeSet. First place the system in stand alone mode using piartool utility.


List the existing attributes in piconfig utility:

@table piatrset

@mode list

@ostru set


@ostru ...

@select set=MyAttribSet

@ends

Suppose the attributes and their types and defaults of this attribute set show as follows.

MyAttribSet

MyAttrib1,Int32,22



MyAttrib2,BYTE,0

MyAttrib3,Float32,5.

To change the attribute MyAttrib2 to type String and add another attribute, MyAttrib4 of type uint16 in PIConfig:

@table piatrset

@mode edit

@istru set


@istru ...

MyAttribSet

MyAttrib1,int32,22

MyAttrib2,String,default string

MyAttrib3,float32,

MyAttrib4,uint16,1

@ends

Now list the resulting set:

@table piatrset

@mode list

@ostru set


@ostru ...

@select set=MyAttribSet

@ends

MyAttribSet

MyAttrib1,Int32,22

MyAttrib2,String,default string

MyAttrib3,Float32,0.

MyAttrib4,Uint16,1

Editing an attribute set works just like PI digital set edit. Attribute name, type and default should all be explicitly redefined. If a pre-existing attribute is not specified in the new definition, it will be permanently removed from the set. If the user had not wanted to edit the existing attributes, but only wanted to add a new attribute MyAttrib4, he still would have had to specify all attributes in his definition. That is, doing the following

@table piatrset

@mode edit

@istru set


@istru …

MyAttribSet

MyAttrib4,uint16,1

@ends

would have produced MyAttribSet containing only one attribute, namely MyAttrib4.

If an attribute set is edited, and its pre-existing attribute name is specified, but not the type and default, float32 and value 0.0 will be assigned overwriting the original type and default.


Page 68

If only the type is specified by the user, a new default will be assigned even if the type is identical to the previous one. The default of MyAttrib3 attribute was changed to 0.0 from the original 5.0 because it was not explicitly specified in the edit.

When done with the edit, place the system back in normal mode so that applications can connect.


Renaming an attribute set does not trigger any implicit edits of point classes or points and does not require standalone mode either.

Restrictions on Attribute Set Edit All restrictions are delineated in the beginning of this chapter. To repeat a few, attributes may be added to any attribute set, including the predefined sets, except for the base attribute set; Removing attributes in an attribute set that is in use is not allowed; Removing attributes in a predefined attribute set is not allowed; Renaming a predefined attribute set is not allowed.

Informational Messages Messages such as will not be directly returned to the edit initiating application (e.g. piconfig) are sent to the PI Message subsystem. Examples of these messages are information regarding the status (success or failure) of 4 steps involved in edit (rename the old set, add a new set, implicitly edit dependent point classes and points, and remove the old set) and the number of dependent point classes found, etc. These messages are useful in verifying that the steps are carried out correctly during the edit.

Rollback Attribute set edit triggered point class edits, and their dependent point edits are all committed to disk as they occur. If an error occurs during implicit edits the remaining edits are aborted. Those edits that already succeeded are rolled back, and the original set is restored. Then the user can resolve the cause of the edit failure and re-edit.

Note: In rollback all implicitly edited point classes and points are reconstructed from the original attribute set which is still in the database under a temporary name. Since no attribute may be removed from its set if the set is in use, the original attributes should have remained in the set and retained their values in implicit point edits unless the new type and original type were incompatible and the values had to be set to the new defaults. In such a case, the original attribute values of the affected points cannot be recovered.

Successful rollbacks are audited if the base subsystem is enabled for auditing4. Like any other types of edits, unsuccessful rollbacks are not audited.

4 Any action that changes an attribute set, a point class or a point in the database will be audited if auditing is enabled and the edit was successfully completed.



Regardless of success of the rollback the error for the failed edit will be returned to the user. Additional messages may be found in PI message log.

If the rollback fails an error is logged in PI Message log, and the rollback is aborted. PI points database may end up with some points belonging to the original point class (under a temporary name) and others to the new point class (under the original class name) containing the new attribute set. The cause of the rollback failure needs to be resolved and then the system needs to be restored manually. This can be done by using a good system backup or by following the procedure outlined in the next section. Once the system is restored, the user can resolve the cause of the actual edit failure and then re-edit.

System Restore Procedure after Rollback Failure In general, these steps can be taken to restore the system to the original state. Note that whether it is implicit edit or direct edit, the original set or class would have the temporary name (original name~GUID) and the new set or class the original name and the edited attributes.

1. Fix the cause of the rollback failure first (e.g. PI Snap Subsystem down, global lock re-acquisition failure, etc.). More on lock re-acquisition failure later in thread-safety section.

2. If some implicit edits (of point classes and points) already completed successfully, start with points. Then fix the point classes, and lastly the attribute set.

3. Edit the ptclassname attribute of the implicitly edited points to the original point class with the temporary name. When done with this step, there should be no points belonging to the new point class.

4. Remove the new point class.

5. Rename the original class from the temporary name to the original name.

6. Remove the new attribute set.

7. Rename the original set from the temporary name to the original name.

8. Internally the points refer to their point classes by their unique IDs, and the point classes refer to the attribute sets by their IDs. After renaming point classes their dependent points should correctly refer to the new names.

9. Once the system is in its original state, determine the cause of the edit failure and fix it. Then re-edit the attribute set. This procedure should cover most failure cases. If this procedure doesn’t seem to cover your particular situation please call Rockwell Automation Technical Support.

As mentioned earlier if a predefined set gets stuck with undesirable attributes they can not be deleted. This is because each predefined set is one of the required attribute sets in at least one predefined point class which cannot be removed. Since the set is required, it cannot be removed from the point class, and therefore is always in use. Attributes may not be removed from in-use attribute set. In order to add more attributes to a point class, it is better to create a new attribute set and add that attribute set to the target point class rather than adding the attributes to one of the existing member attribute sets of the point class, especially if that set is predefined.


Page 70

To remove undesired attributes from a non-predefined attribute set:

1. Create a new set with the desired attributes.

2. Create new point classes that include this attribute set, and edit the dependent points to belong to these new classes so that the set and classes to be fixed are not in use.

If keeping the original attribute set name or point classes is not important user can stop here and just delete the original point classes and the attribute set. If it is necessary to keep the original set and the point classes, continue.

1. Edit the original dependent point classes to exclude the set that contains undesired attributes.

2. Edit the original attribute set removing the undesirable attributes.

3. Add this set back to the original point classes.

4. Edit the points back to the original classes.

Once the dependent points are all converted back to the original classes in the previous step, the interim point classes and the set created in step 1 and 2 can now be deleted.

5.4 Point Classes Database Edit

Indirect (i.e. implicit) edit of PI point class database was discussed in the Attribute Set Edit section. Point class database can also be directly modified by a user via one of the following three operations: creation, deletion and edit.

5.4.1 Point Class Creation Once a new point class is created, the user can start assigning points to this class.

A point class is created using piconfig by specifying which attribute sets to include. This does not require standalone mode.

All point classes must include the base attribute set.

Example of Creating a Point Class In piconfig

@table piptcls

@mode create

@istru class

@istru set,...

MyPtClass

Base,MyAttribSet

@ends

5.4.2 Point Class Deletion Predefined point classes (see Appendix) may not be deleted.

5.4 - Point Classes Database Edit


In-use point classes may not be deleted.

Example of Creating a Point Class In command window


In piconfig

@table piptcls

@mode delete

@istru class

MyPtClass

@ends

Back to normal mode.


5.4.3 Point Class Edit A point class can be explicitly edited by adding/removing attribute sets that form the point class.

piconfig version 3.4.370.x or higher can display which attribute sets form a point class:

@table piptcls

@ostru class

@ostru set,...

@select class=MyPtClass

@ends

This feature makes it easier to see what attribute sets are currently being used to form the point class.

If there are problems with getting the set names, this operation will return an error but it will also return as many set names as it can get with the failing set’s name replaced with “???” (without the quotes). This allows for editing the class to remove the problematic set as a means to fix a corrupted database.

Internally a point class edit is carried out in four steps:

1. Rename the original point class to a temporary name. It is constructed by concatenating the original name with a GUID e.g. OriginalName~GUID.

2. Create a new point class with desired attribute sets under the original name.

3. Edit the points that belong to the point class to belong to the new class.

4. Remove the original point class from the database after successful implicit point edits.

These steps should be transparent to the user if all steps complete successfully.


Page 72

Example of Editing a Point Class If a point class list in piconfig shows the following

* (Ls - ) PIconfig> @table piptcls

* (LS - PIPTCLS) PIconfig> @mode list

* (Ls - PIPTCLS) PIconfig> @ostru class

* (Ls - PIPTCLS) PIconfig> @ostru set,...

* (Ls - PIPTCLS) PIconfig> @select class=MyPtClass

* (Ls - PIPTCLS) PIconfig> @ends

MyPtClass

base,classic

*----------

Let’s add attributes MyAttribute1 (string) and MyAttribute2 (int32) to this point class. In order to do this, create an attribute set, say MyAttributeSet, as follows.

@table piatrset

@mode create

@istru set


@istru ...

MyAttributeSet

MyAttribute1,string,my default string

MyAttribute2,int32,22

Then check it was correctly created.

@table piatrset

@mode list

@ostru set


@ostru ...

@select set=MyAttributeSet

@ends

You should see

MyAttributeSet

MyAttribute1,String,my default string

MyAttribute2,Int32,22

* End Repeat...

*----------

Edit MyPtClass to include this attribute set. The system needs to be in standalone mode. Type the following in command window.


In piconfig define the attribute sets that should belong to the point class.

@table piptcls

@mode edit



@istru class

@istru set,...

MyPtClass

base,classic,MyAttributeSet

Check that these attributes now form MyPtClass. You should see

* (Ed - PIPTCLS) PIconfig> @mode list

* (Ls - PIPTCLS) PIconfig> @ostru class

* (Ls - PIPTCLS) PIconfig> @ostru set,...

* (Ls - PIPTCLS) PIconfig> @select class=MyPtClass

* (Ls - PIPTCLS) PIconfig> @ends

MyPtClass

base,classic,MyAttributeSet

*----------

To see all attributes that are in this point class type the following.

@table pipoint

@ptclass MyPtClass

@?atr

The following list will appear

1 - Tag String D: !#!#!# C:

2 - NEWTag String D: C:

3 - archiving BYTE D: 1 C:

4 - changedate TimeSta D: 31-Dec-69 16:00:00 C:

5 - changer Uint16 D: 0 C:

6 - compdev Float32 D: 2. C:

7 - Compdevpercent Float32 D: 2 C:

8 - compmax Uint32 D: 28800 C:

9 - compmin Uint16 D: 0 C:

10 - compressing BYTE D: 1 C:

11 - convers Float32 D: 1. C:

12 - creationdate TimeSta D: 31-Dec-69 16:00:00 C:

13 - creator Uint16 D: 0 C:

14 - DataAccess String D: o:rw g:r w:r C:

15 - DataGroup String D: piadmin C:

16 - DataOwner String D: piadmin C:

17 - descriptor String D: C:

18 - DigitalSet String D: system C:

19 - displaydigits BYTE D: -5 C:

20 - engunits String D: C:

21 - excdev Float32 D: 1. C:

22 - Excdevpercent Float32 D: 1 C:

23 - excmax Uint32 D: 600 C:

24 - excmin Uint16 D: 0 C:

25 - exdesc String D: C:


Page 74

26 - filtercode Int16 D: 0 C:

27 - instrumenttag String D: C:

28 - location1 Int32 D: 0 C:





33 - myattribute1 String D: my default string C:

34 - myattribute2 Int32 D: 22 C:

35 - PointID Int32 D: 0 C:

36 - pointsource String D: Lab C:

37 - pointtype String D: Float32 C:

38 - PtAccess String D: o:rw g:r w:r C:

39 - PtClassName String D: MyPtClass C:

40 - PtGroup String D: piadmin C:

41 - PtOwner String D: piadmin C:

42 - Recno Int32 D: 1 C:

43 - scan BYTE D: 1 C:

44 - shutdown BYTE D: 1 C:

45 - SourceTag String D: C:

46 - span Float32 D: 100. C:

47 - squareroot Int16 D: 0 C:

48 - srcptid Int32 D: 0 C:

49 - step BYTE D: 0 C:

50 - totalcode Int16 D: 0 C:

51 - typicalvalue Float32 D: 50. C:

52 - userint1 Int32 D: 0 C:

53 - userint2 Int32 D: 0 C:

54 - userreal1 Float32 D: 0. C:

55 - userreal2 Float32 D: 0. C:

56 - zero Float32 D: 0. C:

Place the system back in normal mode.


Restrictions on Attribute Set Edit Some restrictions on point class edits are:

Edited point class should still contain the base attribute set.

Any attribute set may be added to a point class.

Attribute sets may not be deleted from in-use point classes.

Required attribute sets may not be deleted from predefined point classes even if they are not in use.

Predefined classes may not be renamed.



If the sets in the point class edit definition are not different from the existing ones, then no further action is taken and success status is returned. If the attributes of one or more attribute sets have changed, the attribute set edit itself should have taken care of implicit point class - and point edits.

Renaming a point class does not trigger any implicit edits of points.

Informational Messages Messages such as will not be directly returned to the user are sent to the PI Message subsystem. Examples of these messages are information regarding the status of four steps involved in point class edit (rename the original class, add a new class, implicitly edit dependent points, remove the original class) and the number of dependent points found, etc.

Rollback As in the case of an attribute set edits point class edit triggers implicit point edits. If an implicit point edit fails, all previously successful implicit point edits are rolled back. New class is deleted, and the original class’s name is restored.

System Restore Procedure after Rollback Failure If an implicit point edit fails the rest of the edits are aborted. The old class is left in the database under the temporary name, and the new class will remain also. The edit will return failure status. Where possible, the failing point name and error description will be returned as well.

Restoring the system to its original state requires similar procedure as outlined in Attribute Edit rollback section.

1. First, fix the cause of the rollback failure. For example, if it failed because of Snapshot Subsystem being off-line, the following repair procedure cannot be carried out anyway.

2. It may be possible after this step to just edit the remaining points manually to the new point class. If that is not possible, all dependent points should then be edited to belong to the original class under the temporary name. Remove the new point class.

3. Rename the original class from the temporary name to the original name. If this is impossible, restore from backup.

4. Identify the cause of the edit failure and fix it. Then re-edit the point class.

In PI 3.4.370 or greater PIConfig can display the attribute sets that form a point class. Previously, it had only been possible to display the individual attributes in a point class. The sets are listed by name. Note that the operation edit in piconfig actually makes two calls, one for a listing the current set IDs and a second call to do the edit. As long as there are no errors returned for edit itself, messages like below just means this point class’ original set IDs


Page 76

contained a set ID (110 in this case) that refers to a set that does not exist anymore5, but the edit succeeded.

* (Ls - PIPTCLS) PIconfig> @mode edit

* (Ed - PIPTCLS) piconfig> @istru class

* (Ed - PIPTCLS) piconfig> @istru set,...

* (Ed - PIPTCLS) piconfig> Totalizer2

*> Totalizer2

* (Ed - PIPTCLS) piconfig> testatrset,base,totals

*> testatrset,base,totals

Warning: error getting point class' set name list:

*** Start of PIvariant dump ***

setid 110 [-12002] Code Not Found in PInt

*** End of PIvariant dump ***

5.5 Editing a Point’s Point Class Attribute

In some cases, it is more desirable to modify the value of point’s ptclassname attribute (of type string) to another point class rather then editing the point class it belongs to. A PI point’s ptclassname attribute edit is supported just as any other point edit.

As in the case of implicitly edited point, the attributes of the point are rebuilt. The important difference is that unlike in an implicit point edit, some existing attributes may get removed. The reason is that a point class edit disallows removing any attributes if there are any dependent points. This effectively prevents points losing existing attributes inadvertently. However, if the user deliberately moves a point from one class to another and the new point class does not contain some of this point’s current attributes, they are deleted without prompting.

When a point’s ptclassname attribute is changed, the new point class’ attributes will be compared against the existing ones. New attributes will be added and set to default values. Existing ones will be copied if they are in the new point class. Compatible types retain their values and incompatible types are set to new defaults value. Attributes that do not belong to the new point class are removed.

When editing a point via piconfig new attributes can be modified simultaneously. That is, it is ok to edit the ptclassname attribute and include new attributes that only belong to the new point class and did not previously belong to the point’s old class. However, the target class needs to be set before such an edit is attempted.

To illustrate, try editing a point that belongs to Totalizer point class to Classic point class in piconfig as follows.

@table pinpoint

5 This scenario is unlikely, but if it ever happens, it can be rectified by editing the class.

5.6 - Point Database Audit


@ptclass Totalizer

@mode edit

@istru tag,ptclassname,location4,pointsource

The following error will be returned.

*piconfig Err> Unknown parameter <location4> in structure

*@istru tag,ptclassname,location4,pointsource

*piconfig Err> Complete Structure line removed

*@istru tag,ptclassname,location4,pointsource

This is because @ptclass Totalizer sets the environment for this edit to Totalizer point class, which does not have location4 attribute. Set the environment to the target point class, Classic, by using @ptclass Classic first if you want to edit the ptclassname attribute and new attributes unique to the target point class at the same time.

@ptclass classic

@istru tag,ptclassname,location4,pointsource

tagname,classic,1,C

If it is not necessary to edit the ptclassname attribute and new attributes at the same time, issuing

@ptclass classic

is not necessary since ptclassname is a built-in attribute and every point has this attribute.

Point class of a point can be edited using piconfig in PI 3.4.370 or higher.

5.5.1 Conversion of CC Class to and from a Native PI Class A special handling is required in case of a native PI point’s ptclassname edit to a COM Connector point class or vice versa. The difficulty arises from the fact that in order to allow transparent retrieval of data for a point that has some data in a foreign database and some in PI Archive, PI needs to be aware of the cutoff times and go to the correct source. The possibility that the conversion may occur multiple times adds to the complexity.

As of PI3.4.370.xx, history of the conversions is ignored and data request will be directed to the current data source.

5.6 Point Database Audit

Both Attribute Sets and Point Classes have been added to the Audit database. EnableAudit parameter in PITimeout Table bit6 will be used for Attribute Sets audit database and bit 4 for Point Classes audit database. Note that audit records will cascade if dependent point classes and points are implicitly edited.

6 Starts from 0.


Page 78

Database Bit Value to Enable (decimal)

Point DB 0 1

Attribute Sets DB 2 4

Point Classes DB 4 16

See Auditing chapter for more details.

A new attribute set create generates an audit record.

An attribute set delete generates an audit record.

Each step involved in editing an attribute set will be audited. That is, renaming the original set to a temporary name, adding a new one under the original name, implicit point class and point edits, removing the original set will all be audited. In default-only audit, however, only the set edit, and implicit point class edits are audited as the original set and classes are not renamed and no implicit point edits are triggered.

A failed operation does not produce an audit record since the DB is not changed. This means that if there is an error at any stage in the 4 steps involved in an edit, the audit trail will stop at the audit of the previous successful step. Any changes to the database during the rollback, however, will be audited.

A new point class create generates an audit record.

A point class delete generates an audit record.

Each step involved in editing a point class (renaming the original to a temporary name, adding new one with the desired attribute sets, implicitly editing dependent point, and then removing the old one) will be audited.

Just as in the attribute set edit a failed operation does not produce an audit record since the DB is not changed.

5.6.1 Audit Records The following are Audit Record and Change Record Definitions for attribute sets database edit.

PI Point Attribute Sets DB

Audit Record Definition

Field Description

PI UserName User who made change

Action Time Time and Date of change

PI Database PIPointAttributeSets

Audit Action Add, Remove, Edit

5.6 - Point Database Audit



AuditRecordID Unique ID assigned to audit record

DB RecordName Name of affected attribute set

DB RecordID Affected record ID in database (set ID)

Changes Table of specific changes

Change Record Definition

Property Before After

New_attribute NULL New default

Deleted_attribute Old default NULL

Modified_attrib Old default New default

The name of the attribute set is treated as if it was an attribute and is shown as Name item.

The audit DB exported in XML format also indicates what type the attribute’s value is.

The following are Audit Record and Change Record Definitions for point classes database edit.

PI Point Classes DB


Field Description



PI Database PIPointClasses

Audit Action Add, Remove, Edit


DB RecordName Name of affected point class

DB RecordID Affected record ID in database (point class ID)



Page 80



New_attribute NULL New default

Deleted_attribute Old default NULL

Modified_attrib Old default New default

The name of the point class is treated as if it was an attribute and is shown as Name item.

PI Points DB


Field Description



PI Database PIPoint database

Audit Action Change action: Add, Remove, Edit


DB RecordName Name of affected point

DB RecordID Affected record ID in database (PI point ID)




New_attrib_name NULL Default

Deleted_attrib_name Old value NULL

Edited_attrib_name Old value New value

5.7 Thread-safety

Attribute set and point class edits rely on the locking mechanism at the global level for thread safety. Both of these edits lock the entire points database, and it will not be accessible to the user. That is, two users cannot simultaneously initiate attribute sets and or point classes.

Point edits, however, get the lock (same global lock as attribute set edits and point class edits) per point basis. To be more specific, a point edit thread releases the global lock while it

5.7 - Thread-safety


updates the Snapshot, and re-acquires it when the snap update is completed. While the thread is waiting for the synchronous RPC to PI Snap subsystem to return, the point’s edit status flag is set, and no other thread can edit the point. If another thread has acquired the lock in that time, the point edit thread cannot re-acquire the lock and the point edit fails.

This temporary lock release mechanism during point edit was implemented to optimize PI Base Subsystem’s performance and ensure other requests can still be serviced should the synchronous RPC to update PI Snap take a long time.

Because of this mechanism, it is possible that while an implicit point edit is in progress it releases the lock, another (but explicit) point edit acquires the lock, and the implicit point edit as well as all remaining implicit edits fail or vice versa. The scenario described above is rarely anticipated, but the users should be aware of it, and should NOT attempt to initiate both attribute set or point class edits and explicit edits simultaneously. Since client applications ore remote piconfig sessions cannot connect while the system is in stand alone mode, this situation can be easily avoided if the administrator does not simultaneously launch multiple point edits and point class edits simultaneously in parallel (local) piconfig sessions.


Chapter 6. PI POINT TYPE EDIT

6.1 Introduction

In PI 3.4.370.x or greater a point’s type can be edited just like other attributes. That is, if listing the point's type as shown below shows the point type as int32,

@mode list

@ostru tag,pointtype

@istru tag

MyTag

only the following operation is needed in piconfig to change its point type to float32.

@mode edit

@istru tag,pointtype

MyTag,float32

@ends

Under the hood, changing a point’s point type causes the Archive Subsystem to close the current archive record and start a new one with the new type info in the header.

When a point’s pointtype attribute is changed, already archived history of the point will not change unless the archive is processed off-line. Off-line archive processing will actually convert the old type events to events of the new type. This allows the user a choice between keeping the old data type events and converting them all to the new type.

Upon archive record activation, the old type event will be coerced to the new point type if possible.

If the value does not fit in the new point type, Coercion Failed digital state will be returned by default. If Archive_DataCoercionPolicy parameter (see below) is defined in PI timeout table, an appropriately translated digital state will be returned. PI Server does not log a warning in PI Message subsystem upon point type edit.

Also if the current Snapshot value cannot be coerced to the new type at the time of the point type edit, the edit will fail even though the value will actually be archived in the record of the old type. The point will remain the previous type, and the archived data will look as before. However, piartool –aw will show two new records since the last archived event’s record. One will be for the attempted new type, and another for the previous (i.e. current type). The first of these (the record created for the attempted new type) will remain un-filled thereafter.

To illustrate, suppose a point named int16_typedit had the following archived values and was of type int16.

Chapter 6 - PI Point Type Edit

Page 84

6-Oct-2005 13:51:53,27

6-Oct-2005 14:21:54,32767

6-Oct-2005 14:44:56,4

6-Oct-2005 14:51:51,Pt Created

Then it was edited to type int32, and three new values were added.

6-Oct-2005 14:52:01,-10

6-Oct-2005 14:52:03,2147483647

6-Oct-2005 14:52:05,-16

The last value -16 is still in the Snapshot. Try editing the point back to int16 type again by typing the following in piconfig.

@table pinpoint

@ptclass classic

@mode edit

@istru tag,pointtype

int16_typedit,int16

@ends

The edit will fail and the following error will be returned to piconfig since int16 type doesn’t allow negative values.

[-10005] Subscript Under Range

Note that this is an error status. An error status like this returned by a point type edit operation should be distinguished from Coercion Failed which is a System Digital State which acts as a place holder for an event that failed to coerce.

To see what happens to the archive records when a user tries to edit a point’s type and the operation fails, launch archive walk by typing

piartool –aw

Something like the following will be shown:

Enter Archive Number: 0

Enter Record Number: 130

Point ID: 1219 Record Number: 130

Chain Record Number - Next: 0 Prev: 0 Index: 0

Record Version: 3 Data type: 8

Flags - Index:1 Step:0 Del:0 Dirty:0

Sizes - Record 1024 Data: 998

Parent Archive 00000000 Data Head: 26

Event Count: 4

Storage (bytes) - Available: 998 Used: 29

7 There are events in this example before Pt Created event because data were back-filled to create the example.

6.1 - Introduction


Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:

Type “e” (without the quotes) and press Enter to view the events for the point.

PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::







Event Count: 4


4 Event(s):

0: 29-Sep-05 14:00:03, S,O,A,S,Q [0,0,0,0,0]: 96688

1: 6-Oct-05 14:52:01, S,O,A,S,Q [0,0,0,0,0]: 96730

2: 6-Oct-05 14:58:57, S,O,A,S,Q [0,0,0,0,0]: 96687

3: 6-Oct-05 14:58:57, S,O,A,S,Q [0,0,0,0,0]: 96686


Then type 96688 and press Enter to open this Index record:








Event Count: 4


4 Event(s):

0: 6-Oct-05 13:51:53, S,O,A,S,Q [0,0,0,0,0]: 2

1: 6-Oct-05 14:21:54, S,O,A,S,Q [0,0,0,0,0]: 32767

2: 6-Oct-05 14:44:56, S,O,A,S,Q [0,0,0,0,0]: 4

3: 6-Oct-05 14:51:51, S,O,A,S,Q [0,253,0,0,0]: 0


Press Enter to see the next record. Notice the Data type for the following record is “8”, which is Int328:



8 Point type enumeration:

int16 = 6, int32 = 8, float16 = 11, float32 =12, float64 = 13, digital = 101, Blob = 102, timestamp = 104, string = 105


Page 86



PI Server 3.4.370

Installation and New Feature Guide Page 89




Event Count: 2


2 Event(s):

0: 6-Oct-05 14:52:01, S,O,A,S,Q [0,0,0,0,0]: -10

1: 6-Oct-05 14:52:03, S,O,A,S,Q [0,0,0,0,0]: 2147483647


Then press Enter to see the next record. Notice the Data type is now “6”, which is Int16:








Event Count: 1


1 Event(s):

0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0


Press Enter again to see the next record. The Data type is now “8” again:








Event Count: 1


1 Event(s):

0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0


At this time, the point is of type int32. The offset 16382 is a special marker that acts as a placeholder in the new overflow record created when a point’s type is edited. The first valid new data for the new type should replace this marker but in record 96687 this marker will remain there and the record will never be filled since the edit failed.

6.1 - Introduction


A tricky situation arises if a value stays in a Snapshot for a long time before a new Snapshot arrives and the point undergoes several point type conversions meanwhile. This is very important: the Snapshot undergoes a coercion process every time the tag’s type is successfully edited. When a new value finally arrives at the Snapshot, the old Snapshot is coerced back to the type it was originally sent as before being sent to the appropriate record in the archive. Therefore if the Snapshot event went through several point type conversions and it cannot be coerced from its latest type to the original type, the value will be rejected by the archive and lost.

An example of the situation mentioned in the preceding paragraph would be a point going from an integer type to a digital type and then to a string and then back to integer. If the last Snapshot for this tag was of type int16 and value 1, the integer would have been coerced to a digital and the appropriate digital state during the subsequent type edit. This digital state would have been coerced to a string after that. By the time the point is edited back to integer type, we have a string (whatever the digital state representation was, say, “Closed”) that needs to be coerced to int16 and can’t. It would only be coercible if it were a digital because the coercion process would use the offset.

Out of order events that are sent to the archive after the point type change will go into the archive as the point type that was in effect at the time of the event’s timestamp.

Below is the matrix of allowed type coercions.

int16 int32 float16 float32 float64 digital string blob timestamp

int16 ok ok5 ok ok ok ok N/A N/A

int32 ok1 ok5 ok ok ok3 ok N/A ok

float16 ok1 ok2 ok ok ok3 ok N/A N/A

float32 ok1 ok2 ok5 ok ok3 ok N/A ok

float64 ok1 ok2 ok5 ok ok3 ok N/A ok

digital ok ok ok ok ok ok N/A N/A

string ok ok ok ok ok ok4 N/A ok

blob N/A N/A N/A N/A N/A N/A N/A N/A

timestamp N/A ok ok ok ok N/A ok N/A

1. Assuming values in the range of 0 to 32767

2. Assuming values in the range of -2,147,450,880 to 2,147,483,647

3. Assuming positive, integer values (lower than number of digital states)

4. Assuming exact match (case insensitive) with a state string

5. Assuming the range of the source is compatible with the range of the target


Page 88

6.2 Error handling

If coercion is impossible from the stored type to the current point type, what is returned or whether a value will be returned, is determined by Archive_DataCoercionPolicy. This PI timeout parameter can have one of the following values:

0 DTC_MarkBad Failed events are returned as DS -315 (“Coercion Failed”)

1 DTC_Leave Original events are returned (mixed types)

2 DTC_Zero Returned as 0 or blank depending on the type

3 DTC_Hide Hidden (skip that event)

If coercion fails during off-line archive processing, values will be replaced as dictated by the above policy.


Chapter 7. EXCEPTION REPORTING AND COMPRESSION TESTING

Exception reporting and compression testing offer you the opportunity to tune your PI points for maximum efficiency. Each PI point has attributes that you can set to specify compression and exception reporting specifications for that point. How you set those specifications will impact the flow of data from the Interface Node to the Server for that point (exception reporting) and the efficiency of data storage in the Archive for that point (compression testing). Exception reporting and compression testing are sometimes confused, but it’s important to understand the distinctions:

Exception Reporting: Exception reporting takes place on the Interface Node. The point of Exception reporting is to reduce the communication (I/O) burden between the PI Server and the Interface Node by filtering out “noise”. As networks have improved and I/O capacity has become less of an issue, some PI System Managers have essentially turned exception reporting off, by setting the exception deviation to zero. Rockwell Automation recommends that you set the exception deviation to slightly smaller than the precision of the instrument.

Compression Testing: Compression testing takes place on the Server. The Snapshot Subsystem performs the compression test. The point of compression testing is to store data efficiently in the PI Data Archive. More efficient data storage allows for longer periods of on-line data on the same disk-space. The idea here is not to store an event that PI can essentially “recreate” by extrapolating from surrounding events. Unlike exception reporting, which is a simple linear test, the compression test uses a sophisticated algorithm, called the swinging door compression algorithm, to determine whether an event is significant.

7.1 Exception Reporting

The exception reporting process is the process that interfaces use to evaluate new events to determine whether they are significant. The interface sends the significant events to the PI Server and discards the events that are not significant. The purpose of exception reporting is to avoid sending random changes—changes that are smaller than the instrument can actually measure—from the interface to the PI Server.

The interface compares each new value to the previously sent value. The interface sends the new value to the PI Server only if it is different from the previous value by an amount larger than the value in the ExcDev attribute.

Chapter 7 - Exception Reporting and Compression Testing

Page 90

Exception reporting uses a simple dead band algorithm to determine whether to send events to PI. For each point, you set exception reporting specifications (the ExcDev, ExcMin and ExcMax attributes) to create the dead band. The interface ignores values that fall inside the dead band.

Interface programs that do exception reporting apply the following algorithm whenever a new value is received. A new value is compared to the last value reported. If the new value does not fall within the dead band, an exception occurs. When an exception occurs, the interface sends the event (both timestamp and value) that caused the exception and the previous event to the Snapshot.

The new value is not reported unless:

The difference between the new value and the last value is greater than the exception deviation specification

and

The difference between the times of the new and last values is greater than or equal to the exception minimum time specification

or

The difference between the timestamp of the new value and the timestamp of the last reported value is greater than or equal to the exception maximum time specification.

Note that the time between exception reports might be greater than the exception maximum time if no new values are received by the interface for a point. Neither the PI Server nor the interface will ‘create’ data.

Some interfaces do not support exception reporting. See the documentation for your interface to determine whether it supports this capability. Manually entered data are not normally reported by exception so that every value can be retained.

Most OSIsoft interfaces report new events on exception. The exception algorithm relies on the following parameters:

Exception Maximum: Maximum time span between exceptions, expressed in seconds. This value is configured for each point in the attribute "ExcMax".

Exception Minimum: Minimum time span between exceptions, expressed in seconds. This value is configured for each point in the attribute "ExcMin".

ExcDev: Dead band when exceeded causes an exception. This is configured for each PI Point in either the ExcDev or ExcDevPercent attribute.

OldEvent: Value/status/timestamp of last event sent to the Snapshot--this is the last event that passed exception report.

PrevEvent: Value/status/timestamp of last event compared to determine whether or not to send to the Snapshot.

NewEvent: Value/status/timestamp of event to test for exception.

Exception reporting works by comparing the new event to the old event as follows.

7.1 - Exception Reporting


If the time new event timestamp and old event timestamp is greater than or equal the excmax, the new event is sent to the Snapshot.

For digital points, if the new value differs from the old value, the new event is sent to the Snapshot regardless of excmin time.

For numeric points, if the status changes from good to bad, or bad to good, the new event is sent to the Snapshot.

For numeric points, if the time between the old event and the new event is greater than or equal to excmin and the absolute value of the difference between the new value and the old value is greater than excdev, the value is sent to the Snapshot.

If the new event was sent to the Snapshot, the old event is replaced by the new event.

The last step is a test to see if the PrevEvent should also be sent the Snapshot. If the PrevEvent was not equivalent to the original OldEvent, the PrevEvent is sent to the Snapshot. The only time the PrevEvent is not sent to the Snapshot is when two consecutive exception reports send the new event to the Snapshot. The PrevEvent is used to accurately indicate what really happened to the value; without it, a step change would look like a ramp change. Basically, if a measurement holds steady for hours, then makes a step change, just sending the new value to the Snapshot results in interpolating between the old value and the new value. By also sending the PrevEvent, the step change is stored.

7.1.1 ExcDev and ExcDevPercent The ExcDev attribute (Exception Deviation) specifies in engineering units how much a value may differ from the previous value before it is considered to be a significant value. The ExcDevPercent attribute specifies the same thing as a percentage of the Span attribute. A typical value is 1% of Span. The exception deviation should be less than the compression deviation by at least a factor of 2.

You can set either the ExcDev or the ExcDevPercent attribute. If you change one, the other is automatically changed to be compatible. If you try to change both at once, ExcDevPercent takes precedence.

7.1.2 ExcMin The ExcMin attribute (Exception Minimum) is a dead band after the previous value. This is used to suppress noise. It is specified in seconds. A new data value that is received before the end of the ExcMin interval will be discarded.

7.1.3 ExcMax The ExcMax attribute (Exception Maximum) puts a limit on the length of time that values can be discarded due to exception testing. For example, it is possible for the incoming data to be a single value for many days. If ExcMax is set to 28800 seconds (8 hours) then a value will not be discarded due to exception if the previous event timestamp was more than 28800 seconds before that. Note that the interface does not manufacture data. If there are no incoming values within 28800 seconds, then nothing will be passed to the PI Server.


Page 92

7.1.4 Turning Off Exception Reporting To turn off exception reporting (that is, to generate an exception for every event), set ExcMax = 0 and Excmin = 0.

7.2 Compression Testing

The Snapshot Subsystem uses compression testing to determine which events it should pass to the Archive for storage. The point of compression testing is to store just enough data to accurately reproduce the original signal.

For example, in the following illustration, all the events fall on the same straight line. In a simple case like this, you don’t actually need to store all the points on the line. If you store just two points, you can exactly recreate the point value for any other time.

This line can be reconstructed from any two of these events. So the most efficient storage would be to store only the first and last events (A and B) rather than storing all the events. Further, no accuracy is sacrificed. If a user wants to retrieve the value at any point along the line, it can be interpolated from the values that have been stored.

This simple example illustrates how PI applies data compression. In practice, the curves are more complex than straight lines, and the compression specifications for each tag must be tuned properly to achieve a balance between storage efficiency and accuracy.

The same principle applies to compressing real-world data. PI uses a sophisticated compression algorithm to determine which events it needs to keep in order to provide an accurate data history. The CompDev, CompMin and CompMax attributes allow you to control the “granularity” of the compression algorithm.

When a new Snapshot arrives, the previous one is evaluated according to the compression specifications to see if it is a significant event. If so, it is sent to the Event Queue. If not, it is discarded. This process is called compression.

There are three instances where an event will bypass the compression process and be put in the Event Queue:

If the Compressing attribute for the point is set to OFF.

If the timestamp is older than the timestamp of the current snapshot. Such an event is considered out of order.

7.2 - Compression Testing


If the Status attribute of the Point has changed.

The compression method used by PI allows PI to keep orders of magnitude more data online than conventional scanned systems. The data are also much more detailed than in an archiving system based on averages or periodic samples.

The compression method is called ‘swinging door compression.’ Swinging door compression discards values that fall on a line connecting values that are recorded in the Archive. When a new value is received by the Snapshot Subsystem, the previous value is recorded only if any of the values since the last recorded value do not fall within the compression deviation blanket. The deviation blanket is a parallelogram extending between the last recorded value and the new value with a width equal to twice the compression deviation specification.

Each point has three attributes that comprise the compression specifications: CompDev (compression deviation), CompMin (compression minimum time), and CompMax (compression maximum time). CompDev is the half-width of the deviation blanket (as shown in the illustration). CompDevPercent is similar to CompDev, but it specifies the compression deviation in percent of Span rather than in engineering units.

The compression specifications work in a similar way to the exception specifications. Just like exception reporting, compression is a filter. The difference is that the exception specifications determine which events should be sent to PI, whereas the compression specifications determine which of the events sent to PI should go into the Archive.

CompMin and CompMax are limits that refer to the time between events in the Archive. A new event is not recorded if the time since the last recorded event is less than the compression minimum time for the point. A new event is always recorded if the time since the last recorded event is greater than or equal to the compression maximum time.

Note: The maximum time specification does not guarantee that a value will be written to the Archive within a certain time. The Archive waits for events to be sent to it. It does not check to see if a point has timed out. It does not 'create' new values.


Page 94

EngUnitValue

Time

Most recentlyarchived value

CompressionDeviationSpecification

This value will be archived.

Compression Deviation Blanket

A compression deviation blanketdrawn to this point would notinclude all points since the mostrecently archived value, so theprevious value would bearchived.

Figure 7-1. Swinging Door Compression

You can adjust the compression parameters to produce efficient archive storage without losing significant data. The compression maximum time is usually set to one value for all points in the system. It should be large enough that a point that does not change at all uses very little archive space. A compression maximum time of one work shift (for example, 8 hours) is often a good choice.

Use the compression minimum time (CompMin) to prevent an extremely noisy point from using a large amount of archive space. This parameter should be set to zero for any point coming from an interface that does exception reporting. In this case, the exception minimum time should be used to control particularly noisy points. For a data acquisition system with a slow scan time, this parameter is not important. There are few cases where you want to use a non-zero compression minimum time.

The most significant compression parameter is the deviation specification, CompDev. This parameter is often adjusted after the point is defined. A reasonable starting point is one or two percent of span for transmitters and 0.5 to 1.0 degrees for thermocouples. Look at trend displays to find points for which the reproduction of the data is not acceptable. The goal is to filter out instrument and process noise and still record significant process changes. The effect of changing the compression deviation is not predictable.

For digital points, any change is a significant change. Only the compression maximum and minimum time are important. The compression deviation specification is ignored for digital points.

7.2 - Compression Testing


7.2.1 Step Flag The step attribute setting affects both display and compression.

Data for points with this attribute set to 1 is assumed to remain fixed between events, whereas for points with step=0 data is assumed to change linearly between valid numeric events.

The swinging-door compression, explained above, is not used when the step flag is set. Instead, an exception calculation is applied using the CompDev value. If the absolute difference between the current Snapshot and the last archive value is greater than CompDev then the Snapshot is sent to the archive.

Compression maximum and minimum limits work the same as for tags with the step flag not set.


Chapter 8. SECURITY

The PI Server is typically used in production systems in which correct and reliable operation is important. For this reason, a number of security mechanisms are available to protect against both willful and accidental tampering with the system. These include operating system security, physical security, network security, and several levels of PI System security. See the PI Server System Management Guide for details on managing the PI Server security.

8.1 User Name and Password

The PI Firewall provides a first level of access control, based on the network address of the client. If a connection request successfully passes the PI Firewall, the user ID and password provide another level of PI access security.

The PI Server has its own user identification and password security.

Client applications are responsible for prompting the user for the login name and password, and passing this information to the PI Server for authentication.

Users control their own passwords. Use the pisetpass utility to change user passwords. A null password is allowed but is not generally recommended.

8.2 Point Security

Security applies to point data and point attributes. The archive data for a point is assigned an owner and a group. The attributes of the point (such as zero, span, compression specifications, etc.) may be assigned to a different owner and different group, with independently assigned access permissions.

Users may be assigned to multiple groups, but they don’t have to be assigned to any groups. There is not necessarily any relationship between the owner and the group.

8.3 Database Security

Security applies to databases owned by the PI Server. Access can be controlled to the Batch, Campaign, Digital State, Heading Sets, Modules, Point, Transfer Records, User, and Individual Subsystem Thread and Auditing Table. Each table can be assigned to a different owner and different group. Access permissions can be different for the owner and the group.

Chapter 8 - Security

Page 98

8.4 Trust Access

A mechanism for proxy access is provided, primarily to allow interfaces to access the PI Server for Windows without modifications such as adding login code. The mechanism is called PI Trust Logins.


Chapter 9. PI SQL SUBSYSTEM

The PI SQL Subsystem (pisqlss) prepares and executes SQL statements directed at the PI Server. The primary users of this subsystem are the PI ODBC Driver and the PI-SDK. This driver conforms to the ODBC API standards and makes PI data appear to be organized into data tables. PI ODBC 1.1.2 or later is required to connect to PI Server.

Rockwell Automation’s implementation of SQL gives applications access to the PI Point Database, Snapshot, and Archive.

This chapter begins with a discussion of the architecture of the PI SQL Subsystem. It then outlines the available configuration methods for the PI SQL Subsystem and discusses testing and troubleshooting techniques. Supporting information, such as details of Rockwell Automation’s implementation of SQL, can be found in the PI ODBC Driver Manual.

SQL processing capability is also implemented in the PI System for OpenVMS. Differences between the two are discussed in this chapter.

9.1 Architecture

This subsection outlines the operation of the PI SQL Subsystem and its interaction with the PI API.

This discussion is provided as background material. You do not need to understand the details of the subsystem’s operation in order to use it.

9.1.1 Statement Handles Most interactions between PI clients and the PI Server do not require the Server to maintain any context, that is, any record of the client’s operation. Any request for point information or archive data can be serviced using only the information provided by the client in the request itself.

The processing of SQL statements is different. When an SQL statement is processed, the Server must maintain a record of the statement’s status in order to be able to perform subsequent operations.

This is done by having the PI SQL Subsystem allocate a statement handle when a client wishes to start processing an SQL statement. The client retains the handle’s identifier and provides it to the server with every request.

The details of handle allocation and de-allocation are managed internally by a PI API based client application, such as the PI ODBC Driver.

0 - Table of Figures

Page 100

If connection between the client and Server is lost, the PI SQL Subsystem retains any statement handles allocated by the client. These handles become orphaned and cannot be accessed again. The handles will be de-allocated when the PI SQL Subsystem shuts down. During shutdown, pisqlss will report the total number of handles allocated during its run, and how many orphaned handles were aborted.

9.1.2 Concurrency The PI SQL Subsystem handles SQL processing for all client connections to the PI Server for Windows and UNIX.

Operations such as parsing an SQL statement and fetching results are relatively inexpensive. Execution, however, can potentially take time and system resources as data are obtained from other subsystems.

9.2 Differences between PI 2.x and PI 3.x

There are some differences in SQL processing between the PI Server for Windows and UNIX and the PI System for OpenVMS. This section outlines these differences.

9.2.1 The PIPoint Table This subsection outlines the differences between the implementation of the PIPoint Table between the two styles of PI System.

Classic vs. Base Point Attributes The columns of the PIPoint Table are exactly the same as the point attributes of a Classic point. In the PI System for OpenVMS, all points have a design that closely resembles the Classic point. The PI Server for Windows and UNIX has a few extra attributes relating to point ownership and access permissions.

In the PI Server for Windows and UNIX, the lowest common set of point attributes is called the Base point class. When querying attributes of base class points, the PIPoint columns that represent attributes of classic points will appear to have default values.

This table lists the point attributes that will have default values when querying base class points:

Table 9–1. Default Attributes in BASE Point Class

PIPoint Column Default value

Convers 0.0

Filtercode 0

location1, location2, location3, location4, location5

0

PointID Same as base class attribute recno

9.3 - Configuration


PIPoint Column Default value

See next subsection.

Recordtype If base class attribute step is 1, then 0, otherwise 1.

Res If base class attribute step is 1, then 4, otherwise 1.

Squareroot 0

Totalcode 0

The keyword pointnumber originally came from the pidiff utility in PI for OpenVMS. This name is also used in the PI API User Guide. Most PI API calls require a 32-bit integer PointIdentifier (pt or ptnum - referenced in the PI API User Guide as PI point number).

PI SQL query Returns PIPoint “base” class attribute…

Select pointid from PIPoint… Recno

Select pointnumber from PIPoint… Pointid

9.2.2 Using Performance Equation Subsystem Built-In Functions Built-in functions in the Performance Equations Subsystem can be called in the SQL select list, or in the WHERE clause. In most cases, the function syntax is the same as in Performance Equations.

The exception is calling functions that take a tag argument according to PI Server Applications Guide, Chapter 2, Performance Equations Subsystem. In performance equations, the syntax for a tag argument is:

'tag'

When calling these functions in PI SQL, the syntax must be:

TagNum("tag")

The TagNum function explicitly converts a character string argument to a PI PE tag type, just as the Date function explicitly converts a character string to a time type.

For example, to call PrevEvent in PI SQL in order to obtain the value of point sinusoid before noon, you must write:

PrevEvent(TagNum("sinusoid"), Date("12:00"))

9.3 Configuration

No advance configuration is necessary to start pisqlss. It is started and stopped exactly the same way as other subsystems. On Windows, pisqlss can be run as a service.


Page 102

Some tuning of pisqlss performance is possible. Settings can be changed using an initialization file, pisqlss command line parameters, and through settings on a client product, such as the PI ODBC Driver.

Note: The use of an initialization file may change in a later release to an alternate method. At that time, any site-specific settings found in the initialization file will be migrated.

This section outlines configuration using the initialization file and command line arguments. Refer to client product documentation for instructions on changing SQL processing settings from the client application.

9.3.1 Hierarchy of PI SQL Subsystem Settings Since it is possible to set parameters using more than one technique, some of the settings may be in conflict. The actual value of the settings employed follows this priority scheme:

Initialization file settings

pisqlss command line arguments

Client product settings

Settings made lower in the list override settings higher up. For example, if the SQL query timeout is set to 45 seconds in the initialization file and to 60 seconds on the pisqlss command line, the value used will be 60 seconds.

9.3.2 Initialization File Settings The initialization file is called pisql.ini and can be found in the PI\dat\ directory of your PI Server. The file contains defaults for all settings. You may change the settings by editing the file.

The initialization file settings are read when a new statement is allocated. Any change to this file will be reflected in the next new statement.

Note: On a PI System for OpenVMS, the initialization file is PISysDat:pisql.ini. The interpretation of the file settings is exactly the same for both PI Servers.

Details of the settings can be found in Appendix B of the PI ODBC Driver Manual.

9.3.3 Command Line Arguments This section outlines the pisqlss settings that can be altered using command line arguments.

The mechanism for specifying command line arguments differs between supported platforms. This subsection outlines the techniques.

Arguments Supported by Pisqlss In general, an argument is specified by an argument token, one or more spaces, and then the argument value. The argument token always begins with a leading dash ( - ). For example,

9.3 - Configuration


pisqlss -t 60 -ts 7200 -o trace,aggrtimestart

In this example, SQL query timeout is set to 60 seconds, the default timestep (for queries against the piinterp table) is set to 7200 seconds (that is, 2 hours) and the trace and aggrtimestart options have been set.

The PI SQL Subsystem supports the following command line arguments:

Table 9–2. Command Line Arguments

Command Line Argument

Description

-o (Letter “o”, not zero). Options. The options are specified in a comma-separated list of tokens. The interpretation of the tokens is not case-sensitive. See the following table for the list of supported options.

-t SQL query timeout, in seconds. If this time expires, pisqlss will cause the query to return either a timeout error, or a subset of the actual results, if the “SUBSET” option is set. See the table of options below.

-ts Default value of the timestep column in the PIINTERP table. This value can be overridden for any query by specifying a timestep constraint in your SELECT statement.

The -o argument is followed by a comma-separated list of option tokens with no space between the tokens. The supported options are as follows:

Table 9–3. Command Line Option Tokens

Option Token Description

AGGRTIMESTART Causes all queries of the aggregate tables to use the time at which the interval starts to identify the aggregate; the default is to use the time at which the aggregate period ends.

EXECSAFE If set, the query will not execute if the PI SQL determines that a query is too unspecific and would take too long to execute.

LOG Writes a summary of every operation by pisqlss on a statement handle to the file sqltrace.log in your \pi\log\ directory. See also the Trace option below. (See Note 1, below.)

QEP Causes the gateway to dump a query execution plan to a file called pisql_n.qep in the \pi\log\ directory on the PI Server. “n” in the file name represents the handle number.

SUBSET If a query times out while this option is in effect, pisqlss will return a subset of the actual results with no error. (See Note 2, below.)

TRACE Writes a summary of every Prepare (that is, query parsing) and Execute operation by pisqlss to the file sqltrace.log in your \pi\log\ directory. See also the “LOG” option above.


Page 104

Note 1: This file is generated in all PI Server configurations, except while not running as a service on Windows. In this case, output is directed to standard output, which is the command window.

Note 2: If this option is in effect, it is important to note that the results returned do not represent the actual final results of the query. When query development is complete, this option should be removed.

Refer to the Troubleshooting section in this chapter for details of the information generated in the sqltrace.log file by the LOG and TRACE options.

Specifying Command Line Arguments on UNIX Command line arguments can be added to the pisqlss startup by editing the PI Server startup file pistart.sh. Add any desired arguments to the end of the line that starts pisqlss.

Note: pistart.sh is overwritten at every PI Server upgrade.

Specifying Command Line Arguments on Windows There are two different methods for providing command line arguments on Windows, depending on how the PI Server is started.

Starting pisqlss in a Command Window Command line arguments can be provided to a Windows program by listing them after the program name. You can edit the file pistart.bat to include command line arguments when starting subsystems.

Starting the PI Server this way results in a command window for every subsystem. You cannot log off Windows in this configuration and leave the system running.

Use caution in editing pistart.bat. This file is overwritten at every PI Server upgrade.

Starting pisqlss as a Windows Service Subsystems can be started using the Services applet in the Control Panel, or by using the pisrvstart.bat file in your PI\adm directory.

The only way to pass command line arguments to pisqlss running as a Windows service is to use the Services applet in the Control Panel. Open the Services applet, select the PI SQL Subsystem, right click and choose properties. Stop the service, and enter the arguments into the Start parameters window. Click the start button to restart the pisqlss.

9.4 - Troubleshooting


Figure 9-1. Windows Control Panel Services Applet

This examples shows a system manager about to restart the PI SQL Subsystem while setting the default timestep to 7200 seconds and turning on TRACE mode.

Note: This works one time only. If you close the Services applet, then reopen and reselect your service, you will not see your command line arguments from the last run. This method cannot be used to provide command line parameters to services started automatically when your Windows system boots.

9.4 Troubleshooting

Unexpected errors may be generated when using an ODBC application to communicate with the PI Server for Windows and UNIX.

This section outlines techniques to help you validate the operation of the PI SQL Subsystem and to log its processing steps.

9.4.1 Using the ipisql Utility This utility is an interactive program that executes SQL statements directed at the PI Server. It uses the PI API to connect to the PI Server.

The ipisql utility can be found in the PI\adm\ directory. Start the utility by typing its name at a command prompt. The utility will connect to the default PI Server, write version information to the screen, and then prompt for input:

D:\pi\adm\ipisql


Page 106

Connecting to default PI System...Done

iPISQL Copyright (c) 1993-2000, OSI Software, Inc. All rights reserved.

PI API Version 1.3.4 PINet Protocol Version 00011101

Connected to PI 3.3 Build 361.43 on node "figaro"

PISQL>

To exit ipisql, type the command exit followed by a semi-colon. The error code from the processing of the last SQL statement is the return code of the ipisql utility. This allows error detection if ipisql is used in a script.

Submitting Queries SQL statements can be typed at the prompt and terminated with a semi-colon ( ; ). This causes the query to be sent to PI. The query can span multiple lines. The prompt for subsequent lines looks like:

_PISQL>

You can use as many lines as you like.

You can also process queries stored in a text file using the FILE command:

PISQL>file myquery.txt;

A query in a file need not be terminated with a semi-colon; the query will be processed when the end of the file is reached.

A query file may contain more than one query. If this is the case, a semi-colon must be used to separate the queries.

Query files may contain the FILE command.

ipisql Options The ipisql utility supports several options that can be specified on the command line.

Most of the options are exactly the same as the command line options for the PI SQL Subsystem itself, specifically timeout (-t), timestep (-ts) and options (-o). For more information, see Command Line Arguments on page 109.

The options argument supports the same option tokens as pisqlss, except LOG and TRACE. In addition, ipisql supports the option token ANSISQLVAL, which is not supported as a command-line option for pisqlss.

The full list of command line arguments are supported by ipisql is as follows:



Table 9–4. Command Line Arguments Supported by ipisql

Command Line Argument

Description

-csv Write results to standard output in comma-separated variable format suitable for importing into a spreadsheet. The query text, column headings, row count and error information are written to standard error, also in comma-separated variable format. No command prompts are displayed.

-f Identifies a query file. If this argument is used, ipisql executes the query in the specified file and exits. A command prompt will not be displayed.

-node Identifies the PI Server node to which to connect. The name to use is the PI Server computer’s network name. When connecting to a PI Server for Windows and UNIX, you must either suffix “:5450” to this name, or specify “-port 5450”.

-o Options. The options are specified in a comma-separated list of tokens with no space between tokens. The interpretation of the tokens is not case-sensitive. For a list of supported options, see the table in the "Configuration" section on page 108.

-p0...-pn SQL parameter values. The first parameter is –p0 (i.e. zero), the second is –p1, and so on. You may specify as many SQL parameters as you like, and need not specify all of them; ipisql will prompt for any additional parameter values needed. The SQL parameter values are in effect throughout the entire ipisql session.

- password Password. This argument is interpreted only if the “-username” argument is supplied. If “-username” is provided, but “-password” is not, ipisql will prompt you for a password.

-port TCP\IP port number. Default value is 545. You may choose to add “:portnum” to the end of the node name when providing the “node” argument.

-t SQL query timeout, in seconds. If this time expires, pisqlss will cause the query to return either a timeout error, or a subset of the actual results, depending on the “SUBSET” option in effect for pisqlss.

-ts Default value of the timestep column in the piinterp table. This value can be overridden for any query by specifying a timestep constraint in your SELECT statement.

-username Username. If this argument is not present, ipisql will not attempt to validate your identity; default access rights will apply.

For example, to execute query in the file myquery.txt against the PI 3.2 System larry using a default timestep of 2 minutes, issue the command:

ipisql –ts 120 –f myquery.txt –node larry:5450

If the file myquery.txt contains the statement:

select * from picomp where tag = ? and time >= ?

you might avoid the prompt for SQL parameter values by issuing the command:

ipisql –f myquery.txt –p0 sinusoid –p1 "today"


Page 108

9.4.2 Generating a Trace File A trace file can be generated by starting the PI SQL Subsystem with the LOG or TRACE options. Instructions on how to do this are in the Configuration section.

The options LOG and TRACE are similar. Both generate information in the sqltrace.log file in the PI\log\ directory. The LOG option provides more detail.

The options can be used together. Output from the two is interspersed.

9.4.3 Output from the TRACE Option Invoking the TRACE option shows a summary of SQL statement preparation and execution only.

Statement Preparation Output Output lines are of the form:

Prepare[HandleNum]>[ErrorCode][ElapsedTime] query string

Elapsed time is given in seconds. For example,

Prepare[1]>[0][0.012s] select * from picomp

where tag = "sinusoid" and time > ?

This statement contains one parameter, identified by a question mark ( ? ), whose value will be provided at run time. Run-time parameters are discussed in detail in the PI ODBC Driver Manual.

Statement Execution Output Output lines are of the form:

Execute[HandleNum]>[ErrorCode][ElapsedTime] Parameters: NParams Columns: Ncols

Rows: Nrows

If the number of run-time parameters is non-zero, this message is followed by one line for every provided parameter:

Pnn [DataType Length] parameter value

where “nn” is the run-time parameter number, starting with 0.

For example, the Execution message following the above Prepare message might read:

Execute[1]>[0][0.041s] Parameters: 1 Columns: 4 Rows: 16

P00 [time32 ] 21-Jul-97 00:00:00

The query in this example returned 16 rows of 4 columns. The query was provided with one run-time parameter: a timestamp.

Output from the LOG Option Output from the LOG option is more detailed. It reflects directly the argument list of the Remote Procedure Calls (RPCs) implemented by the PI SQL Subsystem. Most of the



information generated should be forwarded to Rockwell Automation in the event of a query processing problem.

In general, the first argument of each RPC is the handle ID. The only exception is the newstatement function, which is the routine that generates the handle ID. In this case, the returned handle ID is the second argument.

Function Summary Format The LOG option generates output that looks like this:

FunctionName(arg1, arg2,…) [ErrorCode]

During query execution, progress messages are written to the log file. Each progress message is of the form:

(HandleId): Calls: n PctDone: n Etime: n Limit: n

The items reported are:

Number of calls to get PI data from other subsystems,

Percent complete, based on an initial estimate,

Elapsed time since the start of execution, in seconds,

Timeout (Limit) in seconds. If this number is 0, no timeout limit has been set.

For example:

newstatement(8,21) [0]

clear(21,1) [0]

clear(21,0) [0]

Prepare[21]>[0][0.431s] select * from picomp

where tag = "sinusoid" and time > "y"

execute(21,&params) begins...

callback(21): Calls: 1 PctDone: 0 Etime: 1 Limit: 0

fetch(21,*results) [0]

clear(21,1) [0]

9.4.4 Clearing Expensive Query Problems It is possible that an ODBC client application sends an incomplete query, or a query that returns too many results, to PI.

If this occurs, the client application’s connection to PI will probably time out. The user is then free to reconnect to PI to continue query development.

In some cases, however, execution of this query continues on the PI Server. If the subsystem is left to process an unreasonably large query when the client has timed out and disconnected, it tends to consume large amounts of virtual memory and can consume a large amount of CPU time.

This sub-section outlines techniques for clearing runaway queries on the PI Server. The technique to use varies with the PI Server platform.


Page 110

Windows When running as a service on Windows, the PI SQL Subsystem can be directed to abort processing the current statement and to release the virtual memory it has acquired without shutting down.

To do this, you must send a pause command to the pisqlss. Three techniques are available for doing this:

Start the Services control panel applet. Select the PI SQL Subsystem from the list and click the “Pause” button.

From a command line prompt, issue the command: net pause pisqlss

From a command line prompt, issue the command: \pi\bin\pisqlss –pause

A message will be written to the message log indicating that the pisqlss has been paused. The query in progress when this command is issued will return immediately with an error –10743 (i.e., RPC resolver temporarily off-line). Attempting execution of any new query when the subsystem is in this state will also return this error.

To resume normal operation, you must send a continue command to the pisqlss. There are three techniques available for doing this:

Start the Services control panel applet. Select the PI SQL Subsystem from the list and click the Continue button.

From a command line prompt, issue the command: net continue pisqlss

From a command line prompt, issue the command: \pi\bin\pisqlss –continue

A message will be written to the message log indicating that the pisqlss has been continued.

Shutting down and restarting the subsystem can be done at any time and is equally effective. This is the only option available when running the PI SQL Subsystem on Windows interactively.

UNIX Shutting down and restarting the PI SQL Subsystem is the only technique currently available for aborting expensive queries on UNIX. Use the kill –2 command to stop the pisqlss.

9.4.5 Performance Counters In PI Server for Windows, several aspects of PI SQL Subsystem processing can be monitored continuously using the Performance Monitor application. A summary of these counters appears in the PI Performance Counters section of PI Server System Management Guide, Chapter 1, PI System Management.



9.4.6 Technical Support and Problem Reports If the PI SQL Subsystem consistently returns an error when processing SQL statements, or appears to generate incorrect results, you should stop pisqlss and then restart with the TRACE and LOG options enabled. Send the resulting sqltrace.log to Rockwell Automation Technical Support.


APPENDIX A: PI TIME FORMAT

Many PI System utilities prompt for a date and time. The PI time formats are:

Relative

Absolute

Combined

9.1 Relative Time

Relative time is some number of days, hours, minutes, or seconds. The leading sign (+ or -) is required.

+/- d | h | m | s

The default starting point for relative time is usually the current time. Therefore, a time of -8h is eight hours before the current time. Fractional times may be entered. For example, use -1.5d for one and one-half days. Only a single operator is supported, + or -. For example, this is not supported:

-1d+1h

9.2 Absolute Time

Absolute times have one of the following formats:

DD-MMM-YY hh:mm:ss.ssss - day-month-year hour:minute:second

* - current time.

T - 00:00:00 on the current day (TODAY)

Y - 00:00:00on the previous day (YESTERDAY)

Monday - 00:00:00 on the most recent Monday

Sun,Mon,Tue,Wed,Thu,Fri,Sat - 00:00:00 on the most recent Sunday, Monday, ..., Saturday

For the DD-MMM-YY hh:mm:ss.ssss format, if any of the date fields are left out, they default to the current date. Time fields default to 00.

0 - Appendix A: PI Time Format

Page 114

9.2.1 Specifying Standard or Daylight Savings Time In almost all cases, PI can accurately determine whether or not daylight savings time is in effect. If you wish to be specific, you may suffix the DD-MMM-YY hh:mm:ss.ssss absolute time format with S for standard time, D for daylight time, or the appropriate time zone name. Examples of time zone names include PST for Pacific Standard Time and MET for Middle European Time.

You can find the names of your time zones by using pidiag –tz. This sample output was generated on Windows NT:

c:\pi\adm>pidiag -tz

TZ environment variable: <not set>

Standard Time Name: Pacific Standard Time (PST)

Daylight Time Name: Pacific Daylight Time (PDT)

StartYear, EndYear, Month, Week, Day, Time, Offset

1970, 2038, 4, 1, 1, 7200, -3600

1970, 2038, 10, 5, 1, 7200, 0

The PI System on Windows supports both long time zone names (such as Pacific Standard Time) and short time zone names (such as PST). You may specify either name. Comparisons are not case sensitive. The following time strings are equivalent:

25-Oct-98 01:30 Pacific Daylight Time

25-Oct-98 01:30 pdt

25-Oct-98 01:30 D

UNIX platforms support only the short names. PIdiag –tz shows you the names to use.

For time zones that observe daylight savings time, there is one hour per year in which an unqualified absolute time string is ambiguous. This always occurs during the last hour of daylight savings time before the beginning of standard time. In the Northern Hemisphere, this occurs in the fall. In the Southern Hemisphere, this occurs in the spring. The above time string of 25-Oct-98 01:30 in North America is an example. PI cannot determine from this time string alone whether standard time or daylight savings time is intended.

If the unqualified time is passed, PI uses the current time to resolve the ambiguity. This means that 25-Oct-98 01:30 will be considered daylight savings if the translation takes place before 25-Oct-98 02:00:00 Pacific Daylight Time, and will be considered standard time otherwise. If this is not your intent, suffix your time string with the appropriate time zone name.

To determine if a specific time string is considered ambiguous, you can use pidiag –tz:

c:\pi\adm>pidiag -tz "25-oct-98 1:30:00"

TZ environment variable: <not set>

Standard Time Name: Pacific Standard Time (PST)

Daylight Time Name: Pacific Daylight Time (PDT)

StartYear, EndYear, Month, Week, Day, Time, Offset

1970, 2038, 4, 1, 1, 7200, -3600

1970, 2038, 10, 5, 1, 7200, 0

Passed Time: 25-Oct-98 01:30:00* PST Local: 909279000 UTC: 909307800

9.2 - Absolute Time


The last line of the output reflects the passed time. It is marked with an asterisk (*) which means that the time string would be ambiguous if specified without the time zone name.

Other features of the pidiag –tz command are outlined in PI Server System Management Guide, Chapter 12, Finding and Fixing Problems: the pidiag Utility.

For the DD-MMM-YY hh:mm:ss.ssss format, if any of the date fields are left out, they default to the current date. Time fields default to 00.

9.2.2 Examples

25 00:00:00 on the 25th of the current month

25-Aug-86 00:00:00 on that date

8: 08:00:00 on the current date

25 8 08:00:00 on the 25th of the current month

21:30:01.02 9:30:01.0200 PM on the current date

Caution should be used with the default settings. Here are some examples of timestamps that may be confusing.

8: 08:00:00 on the current date

:8 08:00:00 on the current date

::8 00:08:00 on the current date

:::8 00:00:08 on the current date

0:8 00:08:00 on the current date

The confusion comes from the ambiguity in the first two examples above. Following this theme, when minutes are added to the next examples, the time stamps are still similar.

8:01 08:01:00 on the current date

:8:01 08:01:00 on the current date

The difference in the two notations is evident when a date is added to the time. When a date is added to the front of the time the default notation is hh:mm:ss.ssss not :hh:mm:ss.ssss.

2 8: 08:00:00 on the 2nd of the current month

2 :8 00:08:00 on the 2nd of the current month

2 ::8 00:00:08 on the 2nd of the current month

If extra colons and times are added that is greater than the given DD-MMM-YY hh:mm:ss.ssss format the last part of the time will be disregarded.

2 :::8 00:00:00 on the 2nd of the current month

0 - Appendix A: PI Time Format

Page 116

2 :::8 00:00:00 on the 2nd of the current month

2 8:01:30 08:01:30 on the 2nd of the current month

2 :8:01:30 00:08:01 on the 2nd of the current month

A value for the seconds must be used if sub-seconds are used. Hence caution should also be used when considering timestamps containing sub-seconds.

8::30.01 08:00:30.0100 on the current date

:8::30.01 08:00:30.0100 on the current date

14 :8::30.01 00:08:00 on the 14th of the current month

Here are examples of timestamps that do not work.

8:30.01 Ambiguous, 8 could be minutes or hours

:8:30.01 Ambiguous, 8 could be minutes or hours

9.3 Combined Formats

Combined time scales use both an absolute and a relative time. The absolute part of the time can be *, T, Y, or a day of the week.

9.3.1 Examples

T + 8h 08:00:00 AM on the current day (today)

Y - 8h 04:00:00 PM on the day before yesterday

Mon + 14.5h 02:30:00 PM on the most recent Monday

* - 1h One hour ago

9.1 - Timestamps on PI 2 Systems


APPENDIX B: PI TIME CONVERSIONS

This section describes how timestamps are converted between Windows and UNIX PI Servers (PI Servers) and OpenVMS (PI 2.x). The PI API is based on PI 2.x timestamps; all references to PI 2 System time also apply to PI API time.9

9.1 Timestamps on PI 2 Systems

PI 2 Systems timestamp is based on number of seconds since January 1, 1970 00:00:00 local time. It is important to emphasize local time. There are at least two limitations to this convention: daylight savings time changes and PI data access from time zones outside of the PI System Server time zone.

9.2 Daylight Savings Time Changes on PI 2 Systems

Daylight Savings Time transitions on PI 2 Systems cause one hour of duplicate timestamps during the transition from daylight saving time (DT) to standard time (ST) and a one-hour discontinuity during the ST-DT transition. The ST-DT transition only causes data display problems. The DT-ST transition, unless special procedures are followed, overwrites one hour of data, resulting in data loss. The following two tables show actual timestamps during these two transitions for an PI 2 Server in California, USA.

Table B-1 PI 2 Standard Time to Daylight Savings Time

Universal Coordinated Time

Local Time

PI 2 System Time

7-Apr-96 08:30:00 7-Apr-96 00:30:00 PST 828837000

7-Apr-96 09:00:00 7-Apr-96 01:00:00 PST 828838800

7-Apr-96 09:30:00 7-Apr-96 01:30:00 PST 828840600

9 The extended PI API introduces a time object consisting of time zone information. The discussion applies to non-extended PI API. See the PI Application Programming Interface manual for detail.

0 - Appendix B: PI Time Conversions

Page 118


Local Time

PI 2 System Time

7-Apr-96 10:00:00 7-Apr-96 02:00:00 PST 828842400

7-Apr-96 10:00:00 7-Apr-96 03:00:00 PDT 828846000

7-Apr-96 10:30:00 7-Apr-96 03:30:00 PDT 828847800

7-Apr-96 11:00:00 7-Apr-96 04:00:00 PDT 828849600

7-Apr-96 11:30:00 7-Apr-96 04:30:00 PDT 828851400

Table B-2 PI 2 Daylight Savings Time to Standard Time


Local Time

PI 2 System Time

27-Oct-96 07:30:00 27-Oct-96 00:30:00 PDT 846376200

27-Oct-96 08:00:00 27-Oct-96 01:00:00 PDT 846378000

27-Oct-96 08:30:00 27-Oct-96 01:30:00 PDT 846379800

27-Oct-96 09:00:00 27-Oct-96 02:00:00 PDT 846381600

27-Oct-96 09:00:00 27-Oct-96 01:00:00 PST 846378000

27-Oct-96 09:30:00 27-Oct-96 01:30:00 PST 846379800

27-Oct-96 10:00:00 27-Oct-96 02:00:00 PST 846381600

27-Oct-96 10:30:00 27-Oct-96 02:30:00 PST 846983400

The first table shows two identical moments in time represented by two different times in the PI 2 Server. The second table shows two unique one-hour spans sharing the same times in the PI 2 Server.

9.3 Timestamps across Time Zones on PI 2 Servers

The following table compares a timestamp generated on a PINet/VMS node to a timestamp on a PI 2 Server in a different time zone.

Table B-3 PI2 Timestamps across Time Zones

Time zone Universal Coordinated Time Local Time PI 2 System Time

EST (PINet/VMS node)

17-Nov-96 10:00:00 17-Nov-96 05:00:00

848206800

PST (PI 2 Server) 17-Nov-96 10:00:00 17-Nov-96 02:00:00

848196000

9.4 - Timestamps on PI Server Systems


Both timestamps represent the same moment in time, but have different values. An interface running on the PINet/VMS node would write values that the Server treats as three hours in the future.

9.4 Timestamps on PI Server Systems

The PI Servers solve this problem by internally storing time based on Coordinated Universal Time (or UTC:Universal Time, Coordinated). A given moment in time is represented by the same timestamp regardless of PI Server location. Feeding data from multiple PI Server satellite nodes scattered around the world into one PI Server poses no time problems.

9.5 Translating PI 2 Timestamps to PI Server Systems

Data sources based on the PI API or data from PI 2 Net nodes pose a conversion problem. The timestamps arrive at the Server in PI 2 Server format and must be converted to PI Server format.

PI 2 Server timestamps are converted to PI Server format on the PI Server. Therefore all conversions assume the local time and ST/DT state of the PI Server. Conversions are applied to incoming data (such as data arriving from an interface) and outgoing data (such as archive values for a PI Process Book trend). Data from a PINet/VMS node in a time zone different from the PI Server will have conversion errors. Likewise, data from a PI Server destined to a PI API-based application in a different time zone will also have conversion errors.

PI Servers contain a translation layer that identifies connections from PINet/VMS nodes and PI API applications. The layer translates calls to appropriate PI Server calls and translates values and timestamps to PI Server values and timestamps.

The timestamp conversion algorithm is quite simple. The offset between local time and Universal Coordinated Time is calculated and used as shown in the following two equations:

OpenVMS PI Server based time = PI Server based time – offset

PI Server based time = OpenVMS PI Server based time + offset

The offset calculation requires the PI Server’s operating system to be correctly configured to the correct time zone and ST/DT status. The offset value will vary by one hour during the year on systems that honor ST/DT. For example a computer in California will have an offset of 8 hours during standard time and 7 hours during daylight time. The offset is updated within 5 minutes of actual DT/ST transitions.

The following two tables show time conversions from a PI API-based interface flowing into a PI Server in California during daylight savings time transitions.

Table B-4 PI Server Standard Time to Daylight Savings Time


Local Time PI 2 System Time

Offset PI Server Time

7-Apr-96 08:30:00 7-Apr-96 00:30:00 PST 828837000 28800 828865800


Page 120




7-Apr-96 09:00:00 7-Apr-96 01:00:00 PST 828838800 28800 828867600

7-Apr-96 09:30:00 7-Apr-96 01:30:00 PST 828840600 28800 828869400

7-Apr-96 10:00:00 7-Apr-96 02:00:00 PST 828842400 28800 828871200

7-Apr-96 10:00:00 7-Apr-96 03:00:00 PDT 828846000 25200 828871200

7-Apr-96 10:30:00 7-Apr-96 03:30:00 PDT 828847800 25200 828873000

7-Apr-96 11:00:00 7-Apr-96 04:00:00 PDT 828849600 25200 828874800

7-Apr-96 11:30:00 7-Apr-96 04:30:00 PDT 828851400 25200 828876600

Table B-5 PI Server Daylight Savings Time to Standard Time




27-Oct-96 07:30:00 27-Oct-96 00:30:00 PDT 846376200 25200 846401000

27-Oct-96 08:00:00 27-Oct-96 01:00:00 PDT 846378000 25200 846403200

27-Oct-96 08:30:00 27-Oct-96 01:30:00 PDT 846379800 25200 846405000

27-Oct-96 09:00:00 27-Oct-96 02:00:00 PDT 846381600 25200 846406800

27-Oct-96 09:00:00 27-Oct-96 01:00:00 PST 846378000 28800 846406800

27-Oct-96 09:30:00 27-Oct-96 01:30:00 PST 846379800 28800 846408600

27-Oct-96 10:00:00 27-Oct-96 02:00:00 PST 846381600 28800 846410400

27-Oct-96 10:30:00 27-Oct-96 02:30:00 PST 846983400 28800 846412200

These two tables demonstrate how the PI Server solves the data overlap problem of the DT to ST transition and the continuity problem of the ST to DT transition. However, there is a limitation to this conversion algorithm. It is assumed that arriving timestamps are from the current DT/ST state, that is, a timestamp from ST written to the PI Server during DT will be converted using the DT offset.

9.6 Translating PI Server Timestamps to PI 2 Based Timestamps

Data flowing from a PI Server to a PI API based application uses a slightly different timestamp conversion algorithm. If the timestamp conversion algorithm from PI 2 to PI Server were reversible, the PI Server’s ability to solve the data overlap and discontinuity problems of DT/ST transitions would not be viewable from a PI API application. Conversion from PI Server timestamps to PI 2 Server based timestamps uses a constant offset value, that is, the offset value is not a function of the timestamp being converted. The current offset value in effect is used to convert any archive value regardless of whether the archive value

9.7 - How PI Client Applications Handle DST Changes


represents a value during daylight time or standard time. Here’s a table of examples, again representing systems in California, USA:

Table B-6 PI Examples of Timestamp conversions for California-based systems

PI Server Time of Archive Value


DT/ST

Returned PI 2 System Time

Local Time Offset

824851800 20-Feb 21:30:00 ST 824823000 20-Feb 13:30:00 PST 28800

840538800 20-Aug 12:00:00 ST 840510000 20-Aug 04:00:00 PDT 28800

824851800 20-Feb 21:30:00 DT 824826600 20-Feb 13:30:00 PST 25200

840538800 20-Aug 12:00:00 DT 840513600 20-Aug 04:00:00 PDT 25200

This table shows conversion of identical PI Server timestamps when called during ST and during DT; the resulting PI 2 System Time is different in each case. Although this appears to be ambiguous behavior, it allows preservation of correct DT/ST transitions.

The PI API time parsing/formatting routines have been modified to handle this behavior. The PI API detects the server type and invokes parsing/formatting routines that account for this behavior. Applications that make no assumption of PI timestamps and use PI parsing and formatting routines will behave correctly. Applications that invoke non-PI time formatting techniques may report invalid times.

9.7 How PI Client Applications Handle DST Changes

Archive timestamps in PI Server are stored as universal times; thus the PI Server is not impacted by daylight savings time. This is in contrast to PI 2.x, where there is a one-hour hole in the data during the springtime change, and one hour of data is discarded during the fall time change.

The client applications reflect the daylight savings time changes as follows: it is up to the displayer to apply an interpretation. Rockwell Automation does not choose the day that the changes take place; our software responds to the system time of the local machine.

The PI API will interpret the time according to the local client machine's settings. The time zone setup information is part of the PC configuration. The PI API queries the operating system to find out if a time is in daylight savings time or not. Operating systems other than OpenVMS have the dates of the daylight savings transition times built in. A table of transition dates is maintained which spans decades.

It is interesting to examine a FactoryTalk Historian ProcessBook trend that spans a daylight savings time change. On the day of the springtime change, against a PI Server System, a trend would show continuous and complete data for 23 hours (midnight to midnight). If the time changes on 3 April at 2:00 a.m., one could watch a theoretical clock during this transition and at exactly 01:59:59.99999999999... the clock would change to 3:00:00. The x-axis will be missing the 60 minutes between 2 a.m. and 3 a.m. There will not be a 2:00:00 marker.


Page 122

On the day of the fall time change, against a PI Server System, a trend would show continuous and complete data for 25 hours (midnight to midnight) on the day of the fall time change. If the time changes on 31 October at 2:00 am, one could watch a theoretical clock during this transition and at exactly 01:59:59.99999999999... the clock would change to 1:00:00. The x-axis will have the 120 minutes between 1a.m. and 2 a.m. There will be two consecutive 2:00:00 markers.

On the day of the springtime change, against a PI 2.x system, a trend would show continuous data for 24 hours (midnight to midnight). If the time changes on 3 April at 2:00 am, one could watch a theoretical clock during this transition and at exactly 01:59:59.99999999999... the clock would change to 3:00:00. The PI 2.x Server must adjust its time, and will interpolate (adding records to the archive as necessary) in order to span the 1-hour gap. The x-axis will show the 60 minutes between 2 a.m. and 3 a.m., and the values displayed are the interpolated data.

On the day of the fall time change, against a PI 2.x system, a trend would show discontinuous and incomplete data for 24 hours (midnight to midnight). If the time changes on 31 October at 2:00 a.m., one could watch a theoretical clock during this transition and at exactly 01:59:59.99999999999... the clock would change to 1:00:00.

The PI 2.x Server must adjust its time, and the System Administrator gets to choose which hour of data to discard. This data is lost forever, and will never be displayed by any application. The x-axis will show only 60 minutes between 1 a.m. and 2 a.m., with no indication that data was discarded.

9.8 PI in the 21st Century

Archive timestamps in PI Server are stored as the number of seconds past January 1, 1970. Two-digit years from 00 through 69 are interpreted as 21st century. Two-digit years from 70 through 99 are interpreted as the 20th century (1900s). For example, 70 translates to 1970; 00 translates to 2000; and 37 translates to 2037.


APPENDIX C: PI API AND TOOLKIT USAGE

9.1 Overview

9.1.1 PI API The PI API is a library of routines originally written to access a PI 2.x System programmatically. Before the PI-SDK, all of the Microsoft Windows-based PI client applications (such as FactoryTalk Historian ProcessBook) were based on the PI API. Today most PI interfaces continue to use the PI API, and the library is the only programming method supported on both Windows and UNIX.

The PI API routines reflect the PI 2.x architecture. For example, in PI 2.x, tag descriptors are limited to 26 characters, while in PI Server the limit is 65535. The PI API routine pipt_descriptor ( ) returns a maximum of 26 characters even when the PI Server is running on Windows or UNIX.

PI API version 1.2 first introduced features to take advantage of the PI 3.x architecture. This included:

Sub-second timestamps

Access to string data types

Beginning with PI API 1.4, new functions were added to take further advantage of the PI 3.x architecture. This includes support for long tag names, multi-character point sources, and reading UTC time from the server. These features are only supported when accessing PI 3.4.370 and later.

The PI Server contains a translation layer to provide backward compatibility with most PI API routines. The translation layer translates calls to appropriate PI Server calls and translates values and timestamps to PI Server values and timestamps. However, limitations do exist. These limitations are documented in this appendix.

9.2 PI API Usage on PI Server

This section assumes knowledge of the PI API. Refer to the PI Application Programming Interface Manual for details.

Error codes of piar_ routines All archive interface routines interact with the Snapshot Subsystem. Some routines such as piar_deletevalue() or piar_putarcvaluex() require an existing event at the passed time. The

0 - Appendix C: PI API and Toolkit Usage

Page 124

Snapshot Subsystem does not have information about archive events unless the passed time is the Snapshot itself or the latest archive event. In all other cases, these routines return 0 (success) and pass the request to the archive subsystem via the Event Queue. If the required event does not exist the archive subsystem sends an error to the PI event log.

piar_replacevalue ( ) This routine replaces a single value for the passed time. Replaced archived values require approximately twice the archive space to accommodate “edited” flags. Therefore, replacing large amounts of archived values requires significant free archive space.

piar_panvalues ( ) This routine, if passed a count of 0 will always return error -1. PI 2 behavior is to return the timestamp if an event exists at the passed timestamp or -103 if now events exist at the passed timestamp.

piel_addevnt ( ) A call to piel_addevent will create an entry in the PI System message log as follows:

0 Eventlogger 19-Sep-96 11:31:02

>> [Group,3,Type,4,timestamp,19-Sep-96 11:31:02]

This is where the message text goes.

The user name will always be Eventlogger. The timestamp is the time the message arrived in the Message Subsystem. The second line contains group, type, and passed timestamp in square brackets, followed by the passed message text.

piel_evntactn ( ) This is not supported in the current version of PI Server.

pipt_compspecs and pipt_compspecseng Compmin and compmax are passed internally as short integers. This limits the values to +/- 32767. If the compmax value for a point is larger than 32767, it will be returned as 32767.

pipt_dates ( ) Rather than returning a PI user name, the creator and changer arguments return a string containing a number. The number is associated with the PI user name internally on the Server.

pipt_descriptor ( ) Although the length of a point descriptor has no practical limit, this PI API function returns a maximum of 26 characters, for compatibility with PI 2.x.

pipt_digcode ( ) Although the length of a digital state string has no practical limit, this PI API function uses only the first 12 characters, for compatibility with PI 2.x.

9.2 - PI API Usage on PI Server


PI Server is designed to support multiple digital state sets, whereas PI 2.x supports a single state set. The System Digital State Set is provided for backward compatibility with PI 2.x.

The same digital state string may appear multiple times in the System Digital State Set; it may appear a single time in a custom state set. In PI Server, the state number and the digital state code both refer to the same number.

Pipt_digcode ( ) returns the first instance it finds, using the following algorithm:

Search through the digital state sets, from lowest set number to highest. This means that the System Digital State Set (number 0) will always be searched first.

Search through the given digital state set, from lowest state number to highest.

If found, the digital state is returned as a 32-bit value. The high bit is set; this makes it a negative number. The next 15 bits indicate the state set number. The low 16 bits indicate the state number. There is no way to request a subsequent instance of the string.

pipt_digcodefortag ( ) Although the length of a digital state string has no practical limit, this PI API function uses only the first 12 characters, for compatibility with PI 2.x.

pipt_engunitstring ( ) Although the length of an engineering unit string has no practical limit, this PI API function returns at most the first 12 characters.

pipt_engunstring( ) This function is called with the point number substituted for the engineering unit code parameter.

pipt_excspecseng Excmin and excmax are passed internally as short integers. This limits the values to +/- 32767. If the excmax value for a point is larger than 32767, it will be returned as 32767.

pipt_exdesc ( ) Although the length of an extended descriptor has no practical limit, this PI API function returns a maximum of 80 characters.

pipt_findpoint ( ) Although the length of a tag name has no practical limit, this PI API function uses a maximum of 80 characters.

pipt_nextptwsource ( ) Although the length of a point source string has no practical limit, this PI API function requires that the point source be a single character only. It will not recognize point source strings longer than a single character. The passed point number is not used. The first call to this function begins searching for the matching point source at point number 1. Subsequent


Page 126

calls return the next point in the PI Server point database that matches the passed point source.

pipt_pointid ( ) This function should not be used; use pipt_findpoint ( ) instead.

pipt_pointsource ( ) Although the length of a point source string has no practical limit, this PI API function returns the first character only.

pipt_recordtype ( ) and pipt_rescode ( ) On PI 2, tags with rescode 1, 2 and 3 store their times as steps. If you display a trend of these tags, the values are interpolated between events, resulting in a smooth curve.

Tags with rescode 4, however, store their times as full timestamps. If you display a trend of these tags, the values are not interpolated between events, resulting in a step curve.

On a PI 2 system, pipt_recordtype will return a 1 for tags with rescodes 1, 2, or 3. It will return a 0 for tags with rescode 4.

On PI Server, there are no rescodes. However, there is the step attribute. In PI Server, if you display a trend of tags with a step attribute = 0, the values are interpolated between events, resulting in a smooth curve. If you display a trend of tags with a step attribute = 1, the values are not interpolated between events, resulting in a step curve.

For compatibility, on a PI Server system, pipt_rescode returns a 1 if the step attribute = 0, and it returns 4 if the step attribute = 1. It will never return 2 or 3.

For compatibility, on a PI Server system, pipt_recordtype returns 1 if the step attribute = 0, and it returns 0 if the step attribute = 1.

Keep in mind that pipt_rescode and pipt_recordtype are not very useful on a PI Server system. They are implemented only to provide compatibility for API programs that were already written.

pipt_tag ( ) Although the length of a tag name has no practical limit, this PI API function uses a maximum of 12 characters. Delimiters are not included, as this was a PI 2.x concept.

pipt_taglong ( ) and pipt_tagpreferred Although the length of a tag name has no practical limit, this PI API function uses a maximum of 80 characters for compatibility with PI 2.x. Delimiters are not included, as this was a PI 2.x concept.

pipt_totalspecs ( ) This is not supported in the current version of PI Server.

9.2 - PI API Usage on PI Server


pipt_updates ( ) Although the length of a tag name has no practical limit, this PI API function uses a maximum of 12 characters for compatibility with PI 2.x.

pipt_wildcardsearch ( ) Although the length of a tag name has no practical limit, this PI API function uses a maximum of 80 characters for compatibility with PI 2.x. Subfields are not used, as this is a PI 2.x concept.

pisn_“X” ( ) {etc.} The following discussion is for pisn_getsnapshot ( ), pisn_getsnapshots, pisn_putsnapshot ( ), pisn_putsnapshotq ( ), pisn_putsnapshots ( ), pisn_sendexceptionq ( ) and pisn_sendexceptions ( ).

Sending Digital States to PI2 In PI2, there is one digital state table with 1024 entries, with entries 193-320 reserved for Rockwell Automation error codes.

The interface should send the negative of the table offset if it is an error code.

For example, if the error is IO Timeout then the interface should send -246.

The interface should send the positive relative offset from the digstartcode if it is a valid digital state.

For example, if the tag has digstartcode defined to be 20, and the two valid states are put in offsets 20 and 21 in the Digital State Table, then the interfaces should send 0 and 1 in order to get states 20 and 21, respectively. Note that the interface could send -20 and -21 and this would work, but this is not the recommended algorithm.

Sending Digital States to PI Server In PI Server, the System Digital State Set is provided, primarily for compatibility with PI2. This contains 10240 entries, with entries 193-320 reserved for Rockwell Automation error codes.

The interface should send the negative of the table offset if it is an error code.

For example, if the error is "IO Timeout" then the interface should send -246.

The interface should send the positive offset in the custom digital set if it is a valid digital state.

For example, if the tag has a custom digital set defined with two states, then the interfaces should send 0 and 1. Note that the customer could opt to put the two states in the System Digital State Set, at offsets 20 and 21 for example. Then the interface could send -20 and -21 and this would work, but this is not the recommended algorithm.

If you retrieve a digital state (istat) from PI, it will be a negative number. You do NOT have to change this into a positive number in order to send it back to PI.


Page 128

Retrieving Digital States from PI2 In PI 2, a negative istat is interpreted as a digital state (rather than an integer). The absolute value of the istat gives the offset into the digital state table that corresponds to the state string.

Retrieving Digital States from PI Server In PI Server, a negative istat is interpreted as a digital state (rather than an integer). To decode the state, first take the absolute value of the istat. The upper 16 bits now indicate the digital set number. The lower 16 bits now indicates the digital state number for the given digital set. The System Digital State Set has a number of 0.

pitm_formtime ( ) or pitm_systime ( ) Sometimes the PI API appears to be off by several hours when translating the time. This is usually a configuration problem.

You must set the time zone and daylight savings time correctly on both server and client machines. In WinNT and Win95, set this using Control Panel, Date/Time.

For 16-bit applications, you can set the TZ environment variable. Thirty-two-bit applications should not use this, especially if the site is not in the United States.

The TZ environment variable will overwrite the settings of the Time zone settings of the Operating System in the Control Panel. If you use the TZ variable, the Daylight Saving Time change will be calculated with a fixed algorithm, which is only valid for the United States. The result is that if you are anywhere else in the world, DST will start and end at the wrong time. For 16-bit software there is no solution to get this working properly for non-U.S. sites at the moment.

If you use pitm_systime to retrieve number of seconds past Jan 1, 1970, you should also use pitm_formtime to translate this to a string. If you mix PI API time functions with Microsoft C++ time functions (time and localtime) you may get results that are off by several hours.

Here is an excerpt from Microsoft's MSDN Run-time Library Reference:

The _tzset function uses the current setting of the global environment variable TZ to assign values to three global variables:

_daylight, _timezone, and _tzname.

TZ is a Microsoft extension and not part of the ANSI standard definition of localtime. These variables are used by the _ftime and localtime functions to make corrections from coordinated universal time (UTC) to local time, and by the time function to compute UTC from system time.

Use the following syntax to set the TZ environment variable:

set TZ=tzn[+ | -]hh[:mm[:ss] ][dzn]

where

9.3 - PI Toolkit Usage on PI Server


Tzn = Three-letter time-zone name such as PST. You must specify the correct offset from UTC.

Hh = Difference in hours between UTC and local time. Optionally signed.

Mm = Minutes. Separated from hh by a colon (:).

Ss = Seconds. Separated from mm by a colon (:).

Dzn = Three-letter daylight-savings-time zone such as PDT. These three letters can be anything you like. If DST is never in effect in the locality, set TZ without a value for dzn.

For example, to set TZ to correspond to the current time zone in Germany, you can use one of the following statements:

set TZ=GST1GDT

set TZ=GST-1GDT

These strings use GST to indicate German standard time, assume that Germany is one hour ahead of UTC, and assume that DST is in effect.

If TZ is not set, _tzset attempts to use the time zone information specified by the operating system. If _tzset cannot obtain this information, it uses PST8PDT by default, which signifies Pacific Time zone.

Localtime corrects for the local time zone if the user first sets the global environment variable TZ.

9.3 PI Toolkit Usage on PI Server

This section assumes knowledge of the PI Toolkit. Refer to the PI System Manual, Volume II, for OpenVMS for details.

GetCompSpecs ( ) See comments for the PI API function pipt_compspecs ( ).

GetCompSpecsEng ( ) See comments for the PI API function pipt_compspecs ( ).

GetDigCode ( ) See comments for the PI API function pipt_digcode ( ).

GetDigPointers( ) See comments for the PI API function pipt_digpointers ( ).

GetEngCode( ) This function returns with engUnitCode equal to 0.


Page 130

GetEngUnits( ) This function returns with engUnitCode equal to pt if pt is less than 32768, else it returns with engUnitCode equal to 0.

GetEngUnString (engUnitCode, engUnitStr, error) See comments for the PI API function pipt_engunstring ( ).

GetExcSpecsEng( ) See comments for the PI API function pipt_excspecseng ( ).


APPENDIX D: PREDEFINED ATTRIBUTE SETS AND POINT CLASSES

9.1 Predefined Attribute Sets

9.1.1 alarmparam

Attribute Type Default

action1 String

action2 String

action3 String

action4 String

action5 String

AutoAck String yes

ControlAlg String

ControlTag String

Deadband Float32 0.

Options String

ReferenceTag String

Srcptid Int32 0

test1 String

test2 String

test3 String

test4 String

test5 String

txt1 String

txt2 String

txt3 String

txt4 String

txt5 String

0 - Appendix D: Predefined Attribute Sets and Point Classes

Page 132

9.1.2 base


Archiving BYTE 1

Changedate TimeStamp 31-Dec-69 16:00:00

Changer Uint16 0

Compdev Float32 2.

Compmax Uint32 28800

Compmin Uint16 0

Compressing BYTE 1

Creationdate TimeStamp 31-Dec-69 16:00:00

Creator Uint16 0

Descriptor String

Displaydigits BYTE -5

Engunits String

Excdev Float32 1.

Excmax Uint32 600

Excmin Uint16 0

Exdesc String

Pointsource String Lab

Pointtype UBYTE 12

Scan BYTE 1

Shutdown BYTE 1

Span Float32 100.

Step BYTE 0

Typicalvalue Float32 50.

Zero Float32 0.

9.1.3 classic


Convers Float32 1.

Filtercode Int16 0

Instrumenttag String

location1 Int32 0

location2 Int32 0

9.1 - Predefined Attribute Sets


location3 Int32 0

location4 Int32 0

location5 Int32 0

Squareroot Int16 0

Srcptid Int32 0

Totalcode Int16 0

userint1 Int32 0

userint2 Int32 0

userreal1 Float32 0.

userreal2 Float32 0.

9.1.4 sqcalm_parameters


AutoAck String yes

ChartType Int32 0

ClearOnLimitChange String true

ClearOnStart String false

CLTag String

CommentTag String

LCLTag String

LSLTag String

Mixture String

OneSideofCL String

Options String

OutsideControl String

OutsideOneSigma String

OutsideTwoSigma String

PIProductLimits String no

ProductTag String

ReferenceTag String

ResetTag String

SQCAlarmPriority Int32 0

Srcptid Int32 0

Stratification String

0 - Appendix D: Predefined Attribute Sets and Point Classes

Page 134

TestStatusTag String

Trend String

UCLTag String

USLTag String

WaitOnLimitChange String false

9.1.5 totals


CalcMode String timeweighted

CompValue String ON

Conversion Float32 1.

EventExpr String

FilterExpr String

Function String Total

MovingCount Int16 2

Offset String +0m

Offset2 String +0m

Options String

PctGood Float32 85.

Period String +1h

Period2 String +2m

RateSampleMode String natural

ReportMode String Running

Srcptid Int32 0

TotalCloseMode String clock

Zerobias Float32 0.

9.2 Predefined Point Classes

Alarm base alarmparam

Base base

Classic base classic

SQC_Alarm base sqcalm_parameters

Totalizer base totals


TECHNICAL SUPPORT AND RESOURCES

Technical Support Options

Contact Rockwell Automation Technical Support at the following:

• Customer Support Telephone — 1-440-646-3434 • Online Support — http://support.rockwellautomation.com

Knowledge Center The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center in the Technical Support Web site.

• The Search feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including User Manuals, Release Notes, and White Papers).

• System Manager Resources include tools and instructions that help you manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving Time configuration, PI Server security, PI System sizing and configuration, PI Trusts for Interface Nodes, and more.

Before You Call or Write for Help

When you contact Rockwell Automation Technical Support, please provide:

• Product name, version, and/or build numbers • Computer platform (CPU type, operating system, and version number) • The time that the difficulty started • The message log(s) at that time

Find Version and Build Numbers To find version and build numbers for each PI System subsystem (which vary depending on installed upgrades, updates or patches) use either of the following methods:

• If you have PI System Management Tools (PI SMT) installed, select Start > Programs > PI System > PI System Management Tools. In PI SMT, select the server name, then under System Management Plug-Ins, open Operation > PI Version. The PI Version tree lists all versions.

Technical Support and Resources

Page 136

• If you do not have PI SMT installed, open a command prompt, change to the pi\adm directory, and enter piversion –v. To see individual version numbers for each subsystem, change to the pi\bin directory and type the subsystem name followed by the option –v (for example, piarchss.exe –v).

View Computer Platform Information To view platform specifications:

• In Windows, right-click on My Computer and choose Properties. For more detailed information, select Start > Run, and enter msinfo32.exe

• In UNIX, enter uname –a


INDEX OF TOPICS

Absolute Time, 113 Access permissions, 49

attributes, 49 Accumulators

data types for, 43 Adm directory, 6 Annotation, 20

file, 21 Anti-virus software

OSIsoft recommendation, 7 API Node, 10 API, see PI API, 5 Apisnap, 5, 20 Application Programming Interface

see PI API, 5 Applications, point attributes for,

51 Architecture

SQL Subsystem, 99 Archive

archiving flag, 48 Files, 19

foreign data sources, 17 flag, 53 Size

Considerations, 20 write cache, 13

Archiving attribute, 48 Archiving flag, 48 Argument

Token SQL Subsystem, 102

Attributes and point classes, 41 archiving, 48

base class, 41 changeDate, 55 changer, 55 changing tag names, 42 changing zero/span, 46 compDev, compMin, compMax, 48 compressing, 47 Compression, 18, 93 convers attribute, 51 creationDate, 55 creator, 55 ctr_lmap, 52 ctr_progid, 52 ctr_strmap, 52 dataAccess, 49 dataGroup, 49 defaults, 53 Descriptor, 44 digitalSet, 45 displayDigits, 49 engUnits, 46 exception reporting, 89 exDesc, 44 for classic points, 50 for COM connectors, 52 for user-written programs, 51 instrument tag attribute, 50 location attributes, 50 newTag, 44 pointID, 55 PointSource, 46 PointType, 43 ptAccess, 49 PtClassName, 42

Index of Topics

Page 138

ptGroup, 49 recNo, 56 scan, 47 shutdown, 50 sourceTag, 47 span, 45 squareRoot attribute, 51 srcptid attribute, 51 step, 48 system-assigned, 55 tag name restrictions, 42 totalcode attribute, 51 typicalValue, 45 userInt and userReal attributes, 51 zero, 45

Bad Input digital state, 23 Bad status, 23 Base class, 41 Base Point Class

Point Attributes, 100 Batch Database, 38 bin directory, 6 Blob point type, 43 Buffering

PI API, 6 Build number, 4 C language, 6 Capitalization

case sensitivity in searches, 42 digital state sets, 25

Case sensitivity digital state names, 25 for tags, 42

ChangeDate, 53 point attribute, 55 Point attribute, 55

Changer, 53 point attribute, 55

Changing zero/span, 46 Chsrc file

UNIX, 8

Classes PtClassName attribute, 42

Classes, base point class, 41 Classic Point

Definitions, 100 Classic Point class, 50 classicctr point class, 52 classicctr.dif, 52 Client Applications

Security, 97 COM connectors, 14

classicctr.dif file, 52 creating point class for, 52 longword mapping parameter, 52 mapped points, 52 point attributes for, 52 program ID parameter, 52 string mapping parameter, 52

COM objects, 14 Combined Time Format, 116 Command

Ptclass, 41 Command Line Arguments

SQL Subsystem, 102 UNIX, SQL Subsystem, 104 Windows, SQL Subsystem, 104

CompDev, 92, 93 Point attribute, 53

CompDev attribute, 48 CompDevPercent, 53, 93 CompDevPercent attribute, 48 CompMax, 92, 93

Point attribute, 53 CompMax attribute, 48 CompMax Point attribute range of

values, 51 CompMin, 92, 93

Point attribute, 53 CompMin attribute, 48 Compressing attribute, 47

Index of Topics


Compression, 47, 92 Deviation, 93, 94 flag, 47, 53 foreign data sources, 18 Maximum, 93 Minimum, 93 out of order events, 48 Specifications, 53 swinging door, 93 Windows

recommendation against, 7

Computer platform Information, 136

Concurrency, 100 Configuration

SQL Subsystem, 101 Configuration files

shutdown.dat, 50 Configuration parameters, 25 Constraints on tag names, 42 Conventions, naming tags, 42 Convers point attribute, 51, 53, 100 Conversion

factor, 55 CreationDate, 53

point attribute, 55 Creator, 53

point attribute, 55 ctr_lmap, 15 ctr_lmap attribute, 52 ctr_progid, 15 ctr_progid attribute, 52 ctr_strmap, 15 ctr_strmap attribute, 52 Current snapshot values, 5 dat directory, 6 Data

compression, 47, 92 foreign data sources, 14 retrieval

from foreign data sources, 16

Data Archive Database, 19 Expensive queries, 109

Data Compression specifications, 48

Data flow overview, 9

Data output sourceTag attribute, 47

Data permissions, 49 Data sources

non-PI, 14 Data types

for accumulators, 43 for negative integers, 43 pointType attribute, 43

DataAccess Point attribute, 49

DataAccess Point Attribute, 53 Database

Batch, 38 Firewall, 37 Group, 38 Module, 38 Point, 19, 20 Proxy, 37 Snapshot, 20 Trust, 37 User, 38

Databases non-PI, 14 timeout database, 25

DataGroup Point attribute, 49, 53

DataOwner Point attribute, 49, 53

Daylight Savings Time, 114, 128 Changes, 117

PI Client Applications, 121

Index of Topics

Page 140

to Standard Time, PI 3 Server, 120

Default Digital State Set, 23 point attributes, 53

Descriptor Point attribute, 53

Descriptor attribute, 44 Deviation

Compression, 94 Differences

in PI Systems SQL Subsystem, 100

Digcode, 24 Digital code value, 24 Digital point type, 43 Digital State

Decoding, 128 Retrieving from PI Server, 128 Retrieving from PI2, 128 Sending to PI Server, 127 Sending to PI2, 127 strings, 23 Table, 23

Editing, 24 Digital State Set, 23

defining, 24 deleting, 24

Digital state sets, 45 case sensitivity, 25

Digital states digitalSet attribute, 45

Digital tag, 24, 94 DigitalSet, 53 DigitalSet attribute, 45 DIGSET_nn, 24 Digstartcode, 127 Directories

PI file system, 6 structure, 6 UNIX, 8

DisplayDigits

Point attribute, 53 DisplayDigits attribute, 49, 50 Documentation

conventions, v for interfaces, vi

Engineering units, 46 EngUnitCode, 130 EngUnits

Point attribute, 53 EngUnits attribute

about, 46 single quotes in, 46

EngUnitStr, 130 Environment variable, 8, 25 Event

Out of order, 93 processing, 11

Event Queue, 11, 12 Events

definition of, 9 shutdown events, 50 significant event, 10

ExcDev, 89, 91 Point attribute, 53

ExcDev attribute, 91 ExcDevPercent, 53 ExcDevPercent attribute, 91 Exception Deviation, 91 Exception Maximum, 91 Exception reporting

about, 89 foreign data sources, 17 minimum, 94 specifications, 47 turning off, 92

ExcMax, 89 Point attribute, 53, 91

ExcMax Point attribute range of values, 51

ExcMin, 89 Point attribute, 54, 91

ExDesc, 47

Index of Topics


Point attribute, 54 ExDesc attribute, 44 Executables for the PI System, 8 Expensive Queries

clearing, 109 UNIX, 110

Extended descriptor Point attribute, 54

File System Compression recommendation against, 7

Files archive, 19 PI file system, 6

Filtercode, 54 Point Attribute, 100

Filtercode point attribute, 51 Filtering

turning off exception reporting, 92

Filtering data Exception reporting, 89

Filtering, zero/span, 46 Firewall, 7, 97

Database, 37 float16

changing zero/span, 46 out of range data, 46 span attribute, 45 zero attribute, 45

float16 point type, 43 float32

Point type, 54 float32 point type, 43 float64 point type, 43 formatting values

displayDigits attribute, 49 getCompSpecs ( ), 129 getCompSpecsEng ( ), 129 getDigCode ( ), 129 getDigPointers( ), 129 getEngCode( ), 129 getEngUnits( ), 130

getEngUnString, 130 getExcSpecsEng( ), 130 Group

assigning users to, 38 Database, 38 file, UNIX, 8 Security, 97

Handle. See Statement Handle I/O

Timeout, 23 Initialization

SQL Subsystem, 102 Installation

PI-SQL Checklist, 102 Instrument tag

point attribute, 50 Instrument Tag

Point attribute, 54 int16 point type, 43 int32 point type, 43 Integer point type, 43 Interface

definition of, 5 PerfMon, 5 Ping, 5 Random and ramp soak, 1 sending digital states, 127 Sending to PI Server, 127 Simulators, 5 SNMP, 5

Interfaces downloading documentation for, vi exception reporting, 89 PointSource attribute, 46

Interpolation, 126 of numeric values, 48

IP Address, 37 ipisql Utility, 105

options for, 106 Istat, 128 Korn Shell, 8

Index of Topics

Page 142

Lab point source, 46 LibC.ansi.sl

UNIX, 8 Libraries, 8 Localtime, 117, 128, 129 Location Codes

Point attribute, 50, 54, 100 location1 point attribute, 50 location2, 54 location2 point attribute, 50 location3 point attribute, 50 location4 point attribute, 50 location5 point attribute, 50 log directory, 6 Log files

location, 8 LOG option

SQL Subsystem, 108 Login, remote

command-line tools, 4 Longword mapping parameter, 52 Mapped point, 15, 52 Maximum

Compression, 93 Messages

Timeout, 37 Microsoft Common Object Model

(COM) technology, 14 Minimum

Compression, 93 Module Database, 38 Naming tags, restrictions, 42 Negative integers

data types for, 43 New Event Processing, 11 NewTag, 54 NewTag attribute, 44 No Data digital state, 23 NT Services

pisqlss, 104 ODBC Driver, 99 Offset

Calculation for timestamp, 119 OSIsoft

Error codes, 127 Out of order events

compression, 48 Out of range

for float16, 46 Output to other systems

sourceTag attribute, 47 Over Range, 45, 46

digital state, 23 Parameters

COM program ID, 52 longword mapping, 52 server configuration, 25 string mapping, 52

Password, 38, 97 file, UNIX, 8

Performance impact of file system compression, 7

Performance Equations use in SQL Subsystem, 101

Performance tuning configuration parameters, 25

Permissions point and data, 49

PI 2 Daylight Savings Time Changes, 117 timestamps, 117

PI API, 123 Buffering, 6 Timestamp Translation to Windows and UNIX PI Systems, 119 Timestamps, 117

PI point number, 51 PI Server

databases, 19 Daylight Savings Time to Standard Time, 120

Index of Topics


Standard Time to Daylight Savings Time, 119 Time Format, 113 Timestamps, 119 Toolkit Usage, 129

PI System API Time, 117

piadmin, 54 piapi32.dll, 8 piar_replacevalue, 124 piartool

remote login, 4 piconfig, 20 piel_addevnt ( ), 124 piel_evntactn ( ), 124 pigetmsg

remote login, 4 pigrp, 8 pilistupd

remote login, 4 PINet/OpenVMS

Nodes Time conversions, 119

PI-ODBC Driver Minimum version, 99

piparams.default UNIX, 8

PIPoint Table, 100

PIproxy records, 38 pipt_compspecs, 124 pipt_compspecseng, 124 pipt_dates ( ), 124 pipt_descriptor ( ), 123, 124 pipt_digcode ( ), 124 pipt_digcodefortag ( ), 125 pipt_engunitstring ( ), 125 pipt_engunstring( ), 125 pipt_excspecseng, 125 pipt_exdesc ( ), 125 pipt_findpoint ( ), 125 pipt_nextptwsource ( ), 125

pipt_pointid ( ), 126 pipt_pointsource ( ), 126 pipt_recordtype ( ), 126 pipt_rescode ( ), 126 pipt_tag ( ), 126 pipt_taglong ( ), 126 pipt_tagpreferred, 126 pipt_totalspecs ( ), 126 pipt_updates ( ), 127 pipt_wildcardsearch ( ), 127 PI-SDK, 99 pisetpass utility, 97 pisn_getsnapshot ( ), 127 pisn_getsnapshots, 127 pisn_putsnapshot ( ), 127 pisn_putsnapshotq ( ), 127 pisn_putsnapshots ( ), 127 pisn_sendexceptionq ( ), 127 pisn_sendexceptions ( ), 127 pisnap, 5

pisnap.bat, 20 pisnap.sh, 20

pisnapss, 20 pisqlss, 99, 102

configuring, 101 continue command, 110 NT services, 101 pause command, 110 performance tuning, 102 pisql.ini, 102 starting as an NT service, 104

PISysDat pisql.ini, 102

PITimeout Table, 36, 37 pitm_systime ( ), 128 Point

deleting, 20 security, 18, 97 Source data attribute, 54

Point Attributes archiving, 48

Index of Topics

Page 144

base class, 41 changeDate, 55 changer, 55 changing tag names, 42 changing zero/span, 46 classic, 50 compressing, 47 Convers, 100 convers attribute, 51 creationDate, 55 creator, 55 ctr_lmap, 52 ctr_progid, 52 ctr_strmap, 52 dataAccess, 49 dataGroup, 49 defaults, 53 Descriptor, 44 digitalSet, 45 displayDigits, 49 engUnits, 46 exDesc, 44 Filtercode, 100 filtercode attribute, 51 for classic points, 50 for COM connectors, 52 instrument tag attribute, 50 location attributes, 50 Location Code, 100 newTag, 44 pointID, 55 Pointid, 100 PointSource, 46 pointType, 43 ptAccess, 49 PtClassName, 42 ptGroup, 49 recNo, 56 Recordtype, 101 Res, 101 scan, 47

shutdown, 50 sourceTag, 47 span, 45 Squareroot, 101 squareRoot attribute, 51 srcptid attribute, 51 step, 48 system assigned, 55 tag name restrictions, 42 tag, case sensitivity, 42 Totalcode, 101 totalcode attribute, 51 typicalValue, 45 userInt and userReal attributes, 51 zero, 45

Point Class, 15 Point classes

base class, 41 classic, 50 classicctr point class, 52 for COM connectors, 52 PtClassName attribute, 42

Point Configuration, 15 Point Database, 19

default attribute values, 53 Point types

for accumulators, 43 for negative integers, 43

PointID, 54 point attribute, 55 Point attribute, 55, 100

Points about, 41 access permissions, 49 archiving attribute, 48 attribute defaults, 53 base class, 41 case sensitivity, 42 changing tag names, 42 changing zero/span, 46 classic point class, 50

Index of Topics


compDev, compMin, compMax, 48 compressing attribute, 47 compression on/off, 47 convers attribute, 51 data types, 43 dataAccess, 49 dataGroup, 49 Descriptor attribute, 44 digitalSet attribute, 45 displayDigits attribute, 49 engUnits attribute, 46 exDesc attribute, 44 filtercode attribute, 51 instrument tag attribute, 50 interpolation of values, 48 location attributes, 50 mapped, 52 naming restrictions, 42 newTag attribute, 44 PointSource attribute, 46 ptAccess, 49 PtClassName attribute, 42 ptGroup, 49 scan attribute, 47 shutdown attribute, 50 sourceTag attribute, 47 span attribute, 45 squareRoot attribute, 51 srcptid attribute, 51 step attribute, 48 totalcode attribute, 51 turn off data collection, 47 typicalValue attribute, 45 userInt and userReal attributes, 51 viewing snapshot value, 5 zero attribute, 45

PointSource attribute, 46 PointType, 54 PointType attribute, 43 Precision, 11

Priorities in SQL configuration methods, 102

Profile File

Unix, 8 Program ID parameter, 52 Programs, point attributes for, 51 Proxy Access

Security, 98 Proxy Database, 37 pt Created digital state, 23 ptAccess

Point attribute, 49, 54 ptclass command, 41 ptClassName attribute, 42 ptGroup

Point attribute, 49, 54 ptOwner

Point attribute, 49, 54 Queries

SQL Subsystem, 106 Range

the span attribute, 45 the zero attribute, 45

Real point type, 43 RecNo, 54

point attribute, 56 Point attribute, 56

Records record number attribute, 56

Recordtype point attribute, 101 Redirector, 14 Relative Time, 113 Remote adminstration, 4 Res point attribute, 101 Rescode, 126 Restrictions on tag names, 42 Scan attribute, 47 Scan Flag, 54 Scan time

slow, 94

Index of Topics

Page 146

Script files classicctr.dif, 52

Security, 97 access permissions, 49 Firewall, 37 foreign data sources, 18

Servers Time Conversions among, 117

Shutdown digital state, 23 flag, 50 Point attribute, 54

Shutdown attribute, 50 Shutdown Events, 23 Shutdown.dat file, 50 Significant events, 10 Simulator interfaces, 5 Slow scan time, 94 SMT

about, vi, 24 Snapshot

definition of, 11 from foreign data sources, 16 viewing current values, 5

Snapshot Subsystem database, 20 definition of, 11

Source tag, point number, 51 Source, point source, 46 SourceTag, 54 SourceTag attribute, 47 Span

Point attribute, 54 Span attribute, changing, 46 SQL Subsystem, 99

architecture, 99 argument, 102 Command line arguments, 102 configuration, 101

methods, conflicts in, 102 Generating a Trace, 108

Initialization file, 102 LOG option, 108 NT services, 101 statement handles, 99 Submitting Queries, 106 TRACE Option, 108 Troubleshooting, 105 tuning, 101

Square root code Point attribute, 54, 101

SquareRoot point attribute, 50, 51

srcptid attribute and sourceTag attribute, 47

srcptid point attribute, 54 srcptid point attribute, 51 Standard Time, 117

to Daylight Savings Time, PI 3 Server, 119

State 16383, 24 State sets, 45 Statement Handle, 99

Handle ID PI-SQL, 109

Step flag, 95 Point attribute, 54

Step attribute, 48 Step flag, 48 String

Data Types, 123 String mapping parameter, 52 String point type, 43 Subsecond timestamps, 123 Subsystem

PI-SQL, 99 Snapshot, 11

Subsystems dependencies among, 1

Swinging door compression, 93 System

state set, 45

Index of Topics


State Set, 24 Time, 121

System Management Tools, vi, 24 System-assigned attributes, 55 Table

Digital State, 23, 24 PIPoint, 100

Tables timeout, 25

Tag Digital, 94 system digital state set, 23

Tag attribute, changing, 42 Tag names

capitalization, 42 Tagname

Point attribute, 54 Tagnames

constraints, 42 in external systems, 50

Tags. See points archiving attribute, 48 changing names, 42 changing zero/span, 46 compDev, compMin, compMax, 48 compressing attribute, 47 compression on/off, 47 constraints, 42 dataAccess, 49 dataGroup, 49 Descriptor attribute, 44 digitalSet attribute, 45 displayDigits attribute, 49 engUnits attribute, 46 exDesc attribute, 44 in external systems, 50 interpolation of values, 48 mapped, 52 newTag attribute, 44 PointSource attribute, 46 ptAccess, 49

ptGroup, 49 scan attribute, 47 shutdown attribute, 50 sourceTag attribute, 47 span attribute, 45 step attribute, 48 turn off data collection, 47 typicalValue attribute, 45 viewing snapshot value, 5 zero attribute, 45

Time API Time, 117 between events, 93 Changes

Daylight Savings to Standard, 120 PI 2 Systems, 117 PI Client Applications, 121

conversions, 117 Format, 113 Local time, 117 System Time, 121 transitions

from Open VMS and PI API to Windows and UNIX, 119 PI 2 Systems, 117 PI Server Systems, 119

translations PINet nodes, 119

Zone, 117, 128 Timeout database, 25 Timeout table, 25 Timestamp

across time zones on PI 2 System, 118 Conversions

algorithm, 119 PI 3 & PI 2, 117 PI Server, 119 Subsecond, 123

Index of Topics

Page 148

year 2000, 122 Timestamp point type, 43 Timing parameters, 25

UNIX, 36 Toolkit Usage, 129 Totalcode point attribute, 51 Totalcode Point Attribute, 101 TRACE Option

SQL Subsystem, 108 Trend

seasonal time changes, 122 Trends

formatting numbers, 49 Troubleshooting

SQL Subsystem, 105 Tuning the PI Server

configuration parameters, 25 Turning off exception reporting, 92 Types

about point types, 43 for accumulators, 43 for negative integers, 43

TypicalValue Point attribute, 55

TypicalValue attribute, 45 TZ environment variable, 128 UCT, 119 Under Range, 45, 46 Under Range digital state, 23 UniInt

downloading documentation for, vi

Units, engineering, 46 Universal Coordinated Time, 117,

119, 128

Universal Interface downloading documentation for, vi

UNIX directory and file structure, 8

UNIX directory structure, 8 User

Database, 38 User programs, point attributes for,

51 UserInt1 point attribute, 51 UserInt2, 55 UserInt2 point attribute, 51 UserReal1, 55 UserReal1 point attribute, 51 UserReal2, 55 UserReal2 point attribute, 51 UTC, 128 Utility

ipisql, 105 piconfig, 20 pisetpass, 38 pisnap.bat, 20 pisnap.sh, 20

Version PI Server, 4

Visual Basic, 6 Windows

Directory and file structure, 8 Year 2000

Timestamps, 122 Zero

Point attribute, 55 Zero attribute, 45 Zero attribute, changing, 46

Historian SE

Documents

Transcript of Historian SE