Transcript
HSEPIS-RM020A-EN-E
8/8/07
10:41 AM
Page 1
Historian SE
PI SERVER REFERENCE GUIDE PUBLICATION HSEPIS-RM020A-EN-E–September 2007
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
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.
PI Server Reference Guide
Page iii
Preface - Using this Guide
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
Page iv
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.
Preface - Using this Guide
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
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.
Bold text
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
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.
Consolas monospace is used for:
To list current Snapshot information every 5 seconds, use the piartool -ss command. For example:
Monospace type: "Consolas" font
Files, Directories, Paths Emphasis New Terms Fields References to a chapter or section
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
Light Blue Underlined
Links to URL / Web sites, and email addresses
PI Server Reference Guide
http://support.rockwellautomation.com
Page v
Preface - Using this Guide
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.
Page vi
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 vii
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.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
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. 2.1
2.2
PI Data Flow...............................................................................................................11
Data Flow from Data Sources into the PI Archive........................................................11 2.1.1
The Snapshot .......................................................................................................13
2.1.2
The Archive Subsystem........................................................................................13
Data Retrieval from the Archive .....................................................................................15 2.2.1
2.3
The Archive Read Cache .....................................................................................15
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
PI Server Reference Guide
Page ix
Table of Contents
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
3.5
3.6
Annotation Files....................................................................................................23
Digital State Table ...........................................................................................................25 3.5.1
System State Set for All Points ............................................................................25
3.5.2
Defining a Custom Digital State Set .....................................................................26
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
Page x
Table of Contents
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
PI Server Reference Guide
Page xi
Table of Contents
5.4
5.5
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
Editing a Point’s Point Class Attribute..........................................................................82 5.5.1
5.6
Point Database Audit ......................................................................................................83 5.6.1
5.7
Conversion of CC Class to and from a Native PI Class .......................................83 Audit Records .......................................................................................................84
Thread-safety ...................................................................................................................86
Chapter 6.
PI Point Type Edit......................................................................................................89
6.1
Introduction......................................................................................................................89
6.2
Error handling ..................................................................................................................94
Chapter 7. 7.1
7.2
Exception Reporting and Compression Testing ...................................................95
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
Compression Testing......................................................................................................98 7.2.1
Chapter 8.
Step Flag ............................................................................................................101
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. 9.1
9.2
9.3
Page xii
PI SQL Subsystem ..................................................................................................105
Architecture....................................................................................................................105 9.1.1
Statement Handles .............................................................................................105
9.1.2
Concurrency .......................................................................................................106
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
Configuration .................................................................................................................108 9.3.1
Hierarchy of PI SQL Subsystem Settings...........................................................108
9.3.2
Initialization File Settings ....................................................................................109
Table of Contents
9.3.3 9.4
Command Line Arguments.................................................................................109
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.3
9.2.1
Specifying Standard or Daylight Savings Time ..................................................120
9.2.2
Examples ............................................................................................................121
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
PI Server Reference Guide
Page xiii
Table of Contents
9.1.5 9.2
totals ...................................................................................................................142
Predefined Point Classes .............................................................................................142
Technical Support and Resources...............................................................................................143 Index of Topics...............................................................................................................................145
Page xiv
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 xv
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 xvii
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.
PI Server Reference Guide
Page 1
Chapter 1 - The PI Server
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.
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.
Messages are routed to the Windows Event log or UNIX standard output if this subsystem is not available.
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.
Page 2
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.
PI Server Reference Guide
Page 3
Chapter 1 - The PI Server
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.
Page 4
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 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.
PI Server Reference Guide
Page 5
Chapter 1 - The PI Server
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.
Page 6
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
PI Server Reference Guide
Page 7
Chapter 1 - The PI Server
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.
Page 8
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.
PI Server Reference Guide
Page 9
Chapter 2 - PI Data Flow
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.
Page 10
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.
PI Server Reference Guide
Page 11
Chapter 2 - PI Data Flow
SnapShot
New Event
1 2 3 4 5
Queue(s) Compress
file(s)
n Cache
RecNo
0
m
0
n
Primary Archive
Other On-Line Archives
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
Page 12
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.
PI Server Reference Guide
Page 13
Chapter 2 - PI Data Flow
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.
Page 14
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.
PI Server Reference Guide
Page 15
Chapter 2 - PI Data Flow
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.
Page 16
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.
PI Server Reference Guide
Page 17
Chapter 2 - PI Data Flow
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.
Page 18
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.
PI Server Reference Guide
Page 19
Chapter 3 - PI Server Databases
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.
Page 20
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.
PI Server Reference Guide
Page 21
Chapter 3 - PI Server Databases
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.
Page 22
3.5 - Digital State Table
• •
3.5
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.
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.
PI Server Reference Guide
Page 23
Chapter 3 - PI Server Databases
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.
Page 24
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
_Bac kupTimeout
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
_Thr eadCount
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.
PI Server Reference Guide
Page 25
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max (Default)
Read
Description
All
_Ma xThreadsPerClientQ uery
depend on value of _ThreadC ount (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
_Writ eModTimesToFileP eriod
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_AutoArchiv eFileRoot
(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_"
Page 26
3.6 - Timeout Database
Subsystem
Name
Min – Max (Default)
Read
Description
Archive
Archive_BackupCut offDate
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_BackupLea dtime
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_CacheClea nCycle
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_CacheHigh PctLimit
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_CacheLow PctLimit
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_CacheReco rdPool
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_CacheReco rdsPerPoint
4 – cache epool / 2 (512 records)
startup + end of each flush cycle
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_CacheTrim Percent
1 – 75 (40 %)
startup only
Percentage to trim the read and write cache when low physical memory resources are detected.
PI Server Reference Guide
Page 27
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max (Default)
Read
Description
Archive
Archive_DataCoerci onPolicy
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_EventQueu eThreadCount
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_FlushThrea dCount
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_FlushQueu eSize
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_LowDiskSp aceMB
(256 MB)
once a minute with a dynamic primary archive + on shifts when Archive_Au toArchiveFi leRoot 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_MaxAnnota tions
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_MaxIdleCle anCycles
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_MaxWriteC achePerPoint
0 – 2,048 (256 events)
startup + end of each flush cycle
Maximum number of write cache events per point. Events of a given point will be flushed to disk when this limit is reached.
Page 28
3.6 - Timeout Database
Subsystem
Name
Min – Max (Default)
Read
Description
Archive
Archive_MinCacheR ecordPool
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_MinMemAv ail
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_MinPercent MemAvail
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_MinWriteCa chePerPoint
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_PointLockL ogging
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_PointLockTi meout
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_SecondsBe tweenFlush
1 – 86,400 (900 sec)
startup only
Archive cache flush cycle or maximum time between consecutive disk flushes for a given point.
Archive
Archive_ShiftFreeTi me
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.
PI Server Reference Guide
Page 29
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max (Default)
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_ShiftRecord Count
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_WriteLockT imeout
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
ArcInsertRecOnOO O
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
BreakCrossRefOnD elete
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.
Page 30
3.6 - Timeout Database
Subsystem
Name
Min – Max (Default)
Read
Description
Archive
piarchss
1– 10000000 (100000 sec)
startup only
Subsystem wait time after every main loop iteration.
Archive
BatchDb_MaxSearc hRecords
-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_SearchLo okBackDays
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_ArchiveCut offDate
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_NumArchiv es
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 command.
PI Server Reference Guide
Page 31
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max (Default)
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_CleanPe riodSec
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_MaxIdle CleanSec
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)
startup only
Subsystem wait time after every main loop iteration.
Base
PointDb_CleanPerio dSec
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_MaxIdleCle anSec
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
RecreateServerTrus t
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
WindowsAuthenticat ion
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
00xFFFFFFF F (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.
Page 32
3.6 - Timeout Database
Subsystem
Name
Min – Max (Default)
Read
Description
Batch
pibatch
1– 10000000 (12000 µsec)
startup only
Subsystem wait time after every main loop iteration.
Message
pimsgss
1– 10000000 (12000 µsec)
startup only
Subsystem wait time after every main loop iteration.
NetManager
backlog
5 – 1000 (5)
startup only
Maximum number of pending TCP/IP connections.
NetManager
connectionlocktimeo ut
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)
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.
PI Server Reference Guide
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.
Page 33
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max (Default)
Read
Description
NetManager
minbufsize
1 – 1000 (8 KB)
startup only
TCP/IP send and receive buffers
NetManager
pinetmgr
1– 10000000 (10000 µsec)
startup only
Subsystem wait time after every main loop iteration.
NetManager
ReadCompletionTim eout
120 0xFFFFFFF F (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
reversenamelookupf lag
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
PESchedule r
pipeschd
1– 10000000 (50000µsec)
startup only
Subsystem wait time after every main loop iteration.
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)
startup only
Subsystem wait time after every main loop iteration.
Snapshot
SnapFlushCycle
60 – 3600 (900)
startup only
Snapshot table flush cycle or maximum time between consecutive flushes for a given point.
Page 34
3.6 - Timeout Database
Subsystem
Name
Min – Max (Default)
Read
Description
Snapshot
Snapshot_EventQu euePageSize
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_EventQu euePath
(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_EventQu eueSize
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_LowDisk SpaceMB
(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_EventQu eueFlushPeriod
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)
startup only
Subsystem wait time after every main loop iteration.
Totalizer
pitotal
1– 10000000 (12000µsec)
startup only
Subsystem wait time after every main loop iteration.
UpdateMan ager
MaxUpdateQueue
(4095)
startup only
Maximum number of events per consumer held in the Update Manager.
UpdateMan ager
PIUPD_MaxConsTi meout
0 – 7200 (0 sec)
startup only
Maximum value of client-supplied cleanup time for inactive consumer signups.
UpdateMan ager
PIUPD_MinConsTi meout
0 – 7200 (600 sec)
startup only
Minimum value of client-supplied cleanup time for inactive consumer signups.
UpdateMan ager
PIUPD_TimeoutKill Cons
0–1 (0)
startup only
Remove timed out consumers in addition to removing all pending events.
UpdateMan ager
piupdmgr
1– 10000000 (12000 µsec)
startup only
Subsystem wait time after every main loop iteration.
PI Server Reference Guide
Page 35
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max (Default)
Read
Description
UpdateMan ager
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)
startup only
Subsystem wait time after every main loop iteration.
Utilities
piconfig
1 – 1000000 (1000µsec)
startup only
Subsystem wait time after every main loop iteration.
Utilities
pigetmsg
1 – 1000000 (1000µsec)
startup only
Subsystem wait time after every main loop iteration.
Utilities
pilistupd
1 – 1000000 (1000µsec)
startup only
Subsystem wait time after every main loop iteration.
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
Page 36
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.
PI Server Reference Guide
Page 37
Chapter 3 - PI Server Databases
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.
Page 38
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
PI Server Reference Guide
Page 39
Chapter 3 - PI Server Databases
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
Page 40
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.
PI Server Reference Guide
Page 41
Chapter 4 - PI Point Classes and Attributes
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 tagnaming 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 casesensitive. 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.
Page 42
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.
PI Server Reference Guide
Page 43
Chapter 4 - PI Point Classes and Attributes
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.
Page 44
4.2 - Base Class Point Attributes
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.
PI Server Reference Guide
Page 45
Chapter 4 - PI Point Classes and Attributes
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.
Page 46
4.2 - Base Class Point Attributes
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.
PI Server Reference Guide
Page 47
Chapter 4 - PI Point Classes and Attributes
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.
Page 48
4.2 - Base Class Point Attributes
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
PI Server Reference Guide
Page 49
Chapter 4 - PI Point Classes and Attributes
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
Page 50
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:
4.3.6
Code
Time Constant (Sec.)
1
10
2
60
3
120
4
600
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 16bit integers, which meant that the maximum value of each was 65,535 seconds. This will
PI Server Reference Guide
Page 51
Chapter 4 - PI Point Classes and Attributes
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.
Page 52
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
PI Server Reference Guide
Page 53
Chapter 4 - PI Point Classes and Attributes
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
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
Base
Scan
On
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
System-assigned
System-assigned On, Off, 1, or 0
This must be specified when the point is created.
4.6 - System-Assigned Attributes
Point Class
Field Name
Default Value
Classic
Totalcode
0
Base
TypicalValue
50
Classic
UserInt1
0
Classic
UserInt2
0
Classic
UserReal1
0
Classic
UserReal2
0
Base
Zero
0
Other
Limits
Zero ≤ x ≤ (zero + span)
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.
PI Server Reference Guide
Page 55
Chapter 4 - PI Point Classes and Attributes
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.
Page 56
Chapter 5.
5.1
PI POINT CLASS EDIT
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.
PI Server Reference Guide
Page 57
Chapter 5 - PI Point Class Edit
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 PISDK, 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.
Page 58
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.
PI Server Reference Guide
Page 59
Chapter 5 - PI Point Class Edit
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”)
Page 60
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.
PI Server Reference Guide
Page 61
Chapter 5 - PI Point Class Edit
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
Page 62
5.3 - Attribute Sets Database Edit
@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.
PI Server Reference Guide
Page 63
Chapter 5 - PI Point Class Edit
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. PIartool –standalone 0
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 defaultonly 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
Page 64
5.3 - Attribute Sets Database Edit
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.
PI Server Reference Guide
Page 65
Chapter 5 - PI Point Class Edit
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 systemassigned 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. PIartool –standalone 1
List the existing attributes in piconfig utility: @table piatrset @mode list @ostru set @ostru attrib,type,default @ostru ... @select set=MyAttribSet @ends
Suppose the attributes and their types and defaults of this attribute set show as follows. MyAttribSet MyAttrib1,Int32,22
Page 66
5.3 - Attribute Sets Database Edit
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 attrib,type,default @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 attrib,type,default @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 attrib,type,default @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.
PI Server Reference Guide
Page 67
Chapter 5 - PI Point Class Edit
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. PIartool –standalone 0
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.
Page 68
5.3 - Attribute Sets Database Edit
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.
PI Server Reference Guide
Page 69
Chapter 5 - PI Point Class Edit
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.
Page 70
5.4 - Point Classes Database Edit
In-use point classes may not be deleted. Example of Creating a Point Class In command window PIartool –standalone 1
In piconfig @table piptcls @mode delete @istru class MyPtClass @ends
Back to normal mode. PIartool –standalone 0
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.
PI Server Reference Guide
Page 71
Chapter 5 - PI Point Class Edit
Example of Editing a Point Class If a point class list in piconfig shows the following * (Ls - ) PIconfig> @table * (LS - PIPTCLS) PIconfig> * (Ls - PIPTCLS) PIconfig> * (Ls - PIPTCLS) PIconfig> * (Ls - PIPTCLS) PIconfig> * (Ls - PIPTCLS) PIconfig> MyPtClass base,classic *----------
piptcls @mode list @ostru class @ostru set,... @select class=MyPtClass @ends
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 attrib,type,default @istru ... MyAttributeSet MyAttribute1,string,my default string MyAttribute2,int32,22
Then check it was correctly created. @table piatrset @mode list @ostru set @ostru attrib,type,default @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. PIartool –standalone 1
In piconfig define the attribute sets that should belong to the point class. @table piptcls @mode edit
Page 72
5.4 - Point Classes Database 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:
PI Server Reference Guide
Page 73
Chapter 5 - PI Point Class Edit
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
-
filtercode Int16 D: 0 C: instrumenttag String D: C: location1 Int32 D: 0 C: location2 Int32 D: 0 C: location3 Int32 D: 0 C: location4 Int32 D: 0 C: location5 Int32 D: 0 C: myattribute1 String D: my default string C: myattribute2 Int32 D: 22 C: PointID Int32 D: 0 C: pointsource String D: Lab C: pointtype String D: Float32 C: PtAccess String D: o:rw g:r w:r C: PtClassName String D: MyPtClass C: PtGroup String D: piadmin C: PtOwner String D: piadmin C: Recno Int32 D: 1 C: scan BYTE D: 1 C: shutdown BYTE D: 1 C: SourceTag String D: C: span Float32 D: 100. C: squareroot Int16 D: 0 C: srcptid Int32 D: 0 C: step BYTE D: 0 C: totalcode Int16 D: 0 C: typicalvalue Float32 D: 50. C: userint1 Int32 D: 0 C: userint2 Int32 D: 0 C: userreal1 Float32 D: 0. C: userreal2 Float32 D: 0. C: zero Float32 D: 0. C:
Place the system back in normal mode. PIartool –standalone 0
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.
Page 74
5.4 - Point Classes Database Edit
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
PI Server Reference Guide
Page 75
Chapter 5 - PI Point Class Edit
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.
Page 76
5.6 - Point Database Audit
@ptclass Totalizer @mode edit @istru tag,ptclassname,location4,pointsource
The following error will be returned. *piconfig Err> Unknown parameter 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.
PI Server Reference Guide
Page 77
Chapter 5 - PI Point Class Edit
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 defaultonly 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
Page 78
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
Audit Record Definition 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 Audit Record Definition Field
Description
PI UserName
User who made change
Action Time
Time and Date of change
PI Database
PIPointClasses
Audit Action
Add, Remove, Edit
AuditRecordID
Unique ID assigned to audit record
DB RecordName
Name of affected point class
DB RecordID
Affected record ID in database (point class ID)
Changes
Table of specific changes
PI Server Reference Guide
Page 79
Chapter 5 - PI Point Class Edit
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 point class is treated as if it was an attribute and is shown as Name item. PI Points DB Audit Record Definition Field
Description
PI UserName
User who made change
Action Time
Time and Date of change
PI Database
PIPoint database
Audit Action
Change action: Add, Remove, Edit
AuditRecordID
Unique ID assigned to audit record
DB RecordName
Name of affected point
DB RecordID
Affected record ID in database (PI point ID)
Changes
Table of specific changes
Change Record Definition
5.7
Property
Before
After
New_attrib_name
NULL
Default
Deleted_attrib_name
Old value
NULL
Edited_attrib_name
Old value
New value
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
Page 80
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.
PI Server Reference Guide
Page 81
Chapter 6.
6.1
PI POINT TYPE EDIT
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.
PI Server Reference Guide
Page 83
Chapter 6 - PI Point Type Edit
6-Oct-2005 6-Oct-2005 6-Oct-2005 6-Oct-2005
13:51:53,27 14:21:54,32767 14:44:56,4 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.
Page 84
6.1 - Introduction
Enter Record #, 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 $]:: 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 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 Enter Record #, next rec (p)rev (e)vents (a)rchive # (q)uit:
Then type 96688 and press Enter to open this Index record: PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]:: Point ID: 1219 Record Number: 96688 Chain Record Number - Next: 96730 Prev: 0 Index: 130 Record Version: 3 Data type: 6 Flags - Index:0 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: 22 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 Enter Record #, next rec (p)rev (e)vents (a)rchive # (q)uit:
Press Enter to see the next record. Notice the Data type for the following record is “8”, which is Int328: PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]:: Point ID: 1219 Record Number: 96730
8 Point type enumeration: int16 = 6, int32 = 8, float16 = 11, float32 =12, float64 = 13, digital = 101, Blob = 102, timestamp = 104, string = 105
PI Server Reference Guide
Page 85
Chapter 6 - PI Point Type Edit
Chain Record Number - Next: 96687 Prev: 96688 Index: 130 Record Version: 3 Data type: 8 PI Server 3.4.370 Installation and New Feature Guide Page 89 Flags - Index:0 Step:0 Del:0 Dirty:0 Sizes - Record 1024 Data: 998 Parent Archive 00000000 Data Head: 26 Event Count: 2 Storage (bytes) - Available: 998 Used: 14 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 Enter Record #, next rec (p)rev (e)vents (a)rchive # (q)uit:
Then press Enter to see the next record. Notice the Data type is now “6”, which is Int16: PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]:: Point ID: 1219 Record Number: 96687 Chain Record Number - Next: 96686 Prev: 96730 Index: 130 Record Version: 3 Data type: 6 Flags - Index:0 Step:0 Del:1 Dirty:0 Sizes - Record 1024 Data: 998 Parent Archive 00000000 Data Head: 26 Event Count: 1 Storage (bytes) - Available: 998 Used: 8 1 Event(s): 0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0 Enter Record #, next rec (p)rev (e)vents (a)rchive # (q)uit:
Press Enter again to see the next record. The Data type is now “8” again: PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]:: Point ID: 1219 Record Number: 96686 Chain Record Number - Next: 0 Prev: 96687 Index: 130 Record Version: 3 Data type: 8 Flags - Index:0 Step:0 Del:1 Dirty:0 Sizes - Record 1024 Data: 998 Parent Archive 00000000 Data Head: 26 Event Count: 1 Storage (bytes) - Available: 998 Used: 10 1 Event(s): 0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0 Enter Record #, next rec (p)rev (e)vents (a)rchive # (q)uit:
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.
Page 86
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 int16
int32
float16
float32
float64
digital
string
blob
timestamp
ok
ok5
ok
ok
ok
ok
N/A
N/A
ok5
ok
ok
ok3
ok
N/A
ok
ok
ok
ok3
ok
N/A
N/A
ok
ok3
ok
N/A
ok
ok3
ok
N/A
ok
ok
N/A
N/A
N/A
ok
int32
ok1
float16
ok1
ok2
float32
ok1
ok2
ok5
float64
ok1
ok2
ok5
ok
digital
ok
ok
ok
ok
ok
string
ok
ok
ok
ok
ok
ok4
blob
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 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
PI Server Reference Guide
Page 87
Chapter 6 - PI Point Type Edit
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.
Page 88
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.
PI Server Reference Guide
Page 89
Chapter 7 - Exception Reporting and Compression Testing
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.
Page 90
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.
PI Server Reference Guide
Page 91
Chapter 7 - Exception Reporting and Compression Testing
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.
Page 92
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.
PI Server Reference Guide
Page 93
Chapter 7 - Exception Reporting and Compression Testing
This value will be archived.
Eng Unit Value
A compression deviation blanket drawn to this point would not include all points since the most recently archived value, so the previous value would be archived.
Most recently archived value Compression Deviation Specification
Compression Deviation Blanket
Time 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.
Page 94
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.
PI Server Reference Guide
Page 95
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.
PI Server Reference Guide
Page 97
Chapter 8 - Security
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.
Page 98
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.
PI Server Reference Guide
Page 99
0 - Table of Figures
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
Page 100
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).
9.2.2
PI SQL query
Returns PIPoint “base” class attribute…
Select pointid from PIPoint…
Recno
Select pointnumber from PIPoint…
Pointid
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.
PI Server Reference Guide
Page 101
0 - Table of Figures
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,
Page 102
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.
PI Server Reference Guide
Page 103
0 - Table of Figures
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.
Page 104
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
PI Server Reference Guide
Page 105
0 - Table of Figures
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:
Page 106
9.4 - Troubleshooting
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 commaseparated 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 casesensitive. 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"
PI Server Reference Guide
Page 107
0 - Table of Figures
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
Page 108
9.4 - Troubleshooting
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,¶ms) 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.
PI Server Reference Guide
Page 109
0 - Table of Figures
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.
Page 110
9.4 - Troubleshooting
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.
PI Server Reference Guide
Page 111
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.
PI Server Reference Guide
Page 113
0 - Appendix A: PI Time Format
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: 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: 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
Page 114
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
PI Server Reference Guide
00:00:00 on the 2nd of the current month
Page 115
0 - Appendix A: PI Time Format
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.
9.3
8:30.01
Ambiguous, 8 could be minutes or hours
:8:30.01
Ambiguous, 8 could be minutes or hours
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
Page 116
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.
PI Server Reference Guide
Page 117
0 - Appendix B: PI Time Conversions
Universal Coordinated Time
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 Universal Coordinated 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
Page 118
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 Universal Coordinated 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
PI Server Reference Guide
Page 119
0 - Appendix B: PI Time Conversions
Universal Coordinated Time
Local Time
PI 2 System Time
Offset
PI Server Time
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 Universal Coordinated Time
Local Time
PI 2 System Time
Offset
PI Server 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
Page 120
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
Universal Coordinated Time
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.
PI Server Reference Guide
Page 121
0 - Appendix B: PI Time Conversions
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.
Page 122
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
PI Server Reference Guide
Page 123
0 - Appendix C: PI API and Toolkit Usage
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.
Page 124
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
PI Server Reference Guide
Page 125
0 - Appendix C: PI API and Toolkit Usage
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.
Page 126
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.
PI Server Reference Guide
Page 127
0 - Appendix C: PI API and Toolkit Usage
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
Page 128
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.
PI Server Reference Guide
Page 129
0 - Appendix C: PI API and Toolkit Usage
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 ( ).
Page 130
APPENDIX D: PREDEFINED ATTRIBUTE SETS AND POINT CLASSES 9.1
Predefined Attribute Sets
9.1.1
alarmparam Attribute
Type
action1
String
action2
String
action3
String
action4
String
action5
String
AutoAck
String
ControlAlg
String
ControlTag
String
Deadband
Float32
Options
String
ReferenceTag
String
Srcptid
Int32
test1
String
test2
String
test3
String
test4
String
test5
String
txt1
String
txt2
String
txt3
String
txt4
String
txt5
String
PI Server Reference Guide
Default
yes
0.
0
Page 131
0 - Appendix D: Predefined Attribute Sets and Point Classes
9.1.2
9.1.3
base Attribute
Type
Default
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
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.
-5
classic
Page 132
Attribute
Type
Default
Convers
Float32
1.
Filtercode
Int16
0
Instrumenttag
String
location1
Int32
0
location2
Int32
0
9.1 - Predefined Attribute Sets
9.1.4
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.
Attribute
Type
Default
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
ProductTag
String
ReferenceTag
String
ResetTag
String
SQCAlarmPriority
Int32
0
Srcptid
Int32
0
Stratification
String
sqcalm_parameters
PI Server Reference Guide
no
Page 133
0 - Appendix D: Predefined Attribute Sets and Point Classes
9.1.5
9.2
TestStatusTag
String
Trend
String
UCLTag
String
USLTag
String
WaitOnLimitChange
String
false
Attribute
Type
Default
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.
totals
Predefined Point Classes Alarm base alarmparam
Page 134
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.
PI Server Reference Guide
Page 135
Technical Support and Resources
•
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: • •
Page 136
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
PI Server Reference Guide
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
Page 137
Index of Topics
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
Page 138
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
PI Server Reference Guide
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
Page 139
Index of Topics
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
Page 140
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
PI Server Reference Guide
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
Page 141
Index of Topics
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
Page 142
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
PI Server Reference Guide
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
Page 143
Index of Topics
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
Page 144
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
PI Server Reference Guide
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
Page 145
Index of Topics
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
Page 146
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
PI Server Reference Guide
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
Page 147
Index of Topics
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
Page 148
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
