Professional Documents
Culture Documents
Downloading PI SDK.................................................................................................. 7
Archives.................................................................................................................. 85
Fixed or dynamic archive files........................................................................................................................ 85
Primary archive files.................................................................................................................................. 85
Archive records......................................................................................................................................... 86
Index records.............................................................................................................................................86
PI interfaces........................................................................................................... 153
PI interface utilities...................................................................................................................................... 153
Interface maintenance............................................................................................................................. 153
Troubleshooting..................................................................................................... 171
Troubleshooting checklist............................................................................................................................ 171
General troubleshooting tasks..................................................................................................................... 174
Verification that PI Data Archive processes are running............................................................................ 174
Connection checking................................................................................................................................ 177
Specific issues.............................................................................................................................................. 177
PI ProcessBook trend flatlines.................................................................................................................. 177
Issues with COM connectors.................................................................................................................... 179
Pending update limit................................................................................................................................ 179
Repairs.................................................................................................................. 181
Repair the archive manager data file............................................................................................................ 181
Archive file corruption................................................................................................................................. 182
Recovery of a non-primary archive........................................................................................................... 182
Recover a primary archive........................................................................................................................ 182
Correction of archive event time stamps...................................................................................................... 183
Time conversion file format..................................................................................................................... 184
Snapshot recovery.......................................................................................................................................184
Recover from future times in the snapshot...............................................................................................185
Rebuild the snapshot file.......................................................................................................................... 185
Removal of future-time snapshots........................................................................................................... 187
Database repair........................................................................................................................................... 187
Repair the PI Module Database................................................................................................................ 188
Diagnose and repair PI Data Archive database files......................................................................................188
List the header and index......................................................................................................................... 188
Compress a file base file...........................................................................................................................189
Recover file-base file................................................................................................................................189
Recover from accidental system time change.............................................................................................. 190
Recover from accidental time change at interface node that uses PI Buffer Subsystem............................ 191
PI System overview
The PI System collects, stores, and manages data from your plant or process. The PI System
includes the following types of products.
Note:
Many introductory and training videos are available on the OSIsoftLearning YouTube
channel (https://www.youtube.com/user/OSIsoftLearning).
• Data sources
Data sources are the instruments that generate data. They can connect to interface nodes in
various ways. PI Performance Equations, PI ACE, and Totalizer are also considered data
sources, even though they may be hosted on a PI Server.
◦ PI Data Archive
PI Data Archive receives or retrieves data and serves it in real time throughout the PI
System and your entire information infrastructure. With PI Data Archive, everyone works
from a common set of real-time data. Operators, engineers, managers, and other plant
personnel use client applications to connect to the PI Server and view manufacturing
data from the PI data archives or external data storage systems.
We recommend running PI Data Archive on a separate computer from those that run PI
interfaces and client applications. This distributed data collection architecture is
scalable, robust, and flexible. When the high availability (HA) architecture is used, PI
Data Archive runs on two or more synchronized computers that act as one logical PI Data
Archive collective. For more information, search for "high availability" in PI Live Library
(https://livelibrary.osisoft.com/).
• Developer tools
Developer tools support the development of custom applications on top of the PI System, as
well as the integration of PI System data with other applications and business systems such
as Microsoft Office or SQL Server, enterprise resource planning systems, reporting and
analytics platforms, web portals, and geospatial and maintenance systems.
◦ PI API
The PI Application Programming Interface (PI API) provides a programmatic interface to
PI information from PI Data Archive. PI API also provides utilities for data collection
interfaces and user application development. Code written with the PI API is portable
across multiple hardware and software environments.
◦ PI SDK
The PI Software Development Kit (PI SDK) is a programming library that uses an object-
oriented, hierarchical approach to provide read and write access to PI Server features.
The PI SDK software consists of an in-process COM server, several common controls and
dialogs, and supporting code libraries. The kit includes documentation, example code,
support files, and tools.
• PI AF SDK
The PI AF Software Development Kit (PI AF SDK or AFSDK) provides programmatic access
to PI Server data (PI Data Archive and PI AF).
• Client applications
Operators, engineers, managers, and other plant personnel use a variety of client
applications to connect to PI Data Archive, PI AF, and PI application servers to view plant
data. PI Vision, PI ProcessBook, PI DataLink, and PI WebParts are all client applications.
Subdirectory Contents
Program Files\PI\setup Files for install and uninstall.
In addition to the PI directory, the PI Data Archive installation creates the pipc directory
during the PI SDK installation. The pipc directory contains files for the PI SDK and other tools
and utilities, including PI SMT, Collective Manager, and PI ICU. The PIHOME environment
variable points to this directory.
PI System Tray
PI System Tray help you monitor PI Data Archive and PI AF servers.
PI System Tray displays as an icon on your Windows task bar. The icon shows the status of the
PI Data Archive and PI AF servers that it monitors, and shows alerts when issues occur. PI
System Tray also provides shortcuts for viewing system messages, starting and stopping PI
Data Archive and PI AF, and starting PI System Management Tools (SMT) and PI System
Explorer.
By default, PI System Tray monitors the default PI Data Archive server or collective and the PI
AF application service associated with the default PI AF server. You can monitor additional
servers or change the monitored servers as needed.
PI System Tray launches automatically when you install PI SMT. To manually launch it, select
Start > All Programs > PI System > PI System Tray.
PI Builder
PI Builder is a Microsoft Excel add-in that allows you to work with PI Asset Framework and PI
Data Archive objects in bulk. Use PI Builder to create, delete, and edit PI objects, such as points,
elements, and attributes.
In PI Server 2014 and later, PI Builder replaces PI Tag Configurator.
For more on PI Builder, see the PI Server topics under "PI Builder" in Live Library (https://
livelibrary.osisoft.com).
ICU is included in the PI SMT installation, see the OSIsoft Knowledge Base article, How do I
download PI System Management Tools (PI SMT), on the customer portal: OSIsoft Customer
Portal (https://my.osisoft.com/).
To run the ICU, select Start > All Programs > PI System > PI Interface Configuration Utility.
PI Collective Manager
Use PI Collective Manager to manage high availability (HA) collectives in PI Data Archive. You
can create PI Server collectives, configure existing collectives and their servers, and view the
status of collectives.
PI Collective Manager is included in the PI SMT installation.
To run Collective Manager, select Start > All Programs > PI System > PI Collective Manager.
PI SDK Utility
Many clients and some interfaces communicate with the PI Data Archive server through the PI
SDK. PI SDK Utility provides troubleshooting features, such as checking connectivity,
performing point searches, viewing message logs, and enabling tracing. PI SDK Utility replaces
About PI-SDK.
To run PI SDK Utility, select Start > All Programs > PI System > PI SDK Utility.
PI System Explorer
PI System Explorer provides a graphical user interface for creating, editing, and managing PI
AF objects and assets, including analytics and event frames, in PI AF server. Use PI System
Explorer to create and manage your asset framework, including PI AF databases, elements, and
templates. If you are new to PI Asset Framework, start with PI System Explorer.
To run PI System Explorer, select Start > All Programs > PI System > PI System Explorer.
Buffering Manager
Buffering Manager helps you set up buffering with the PI Buffer subsystem. When upgrading
from an older version of the PI Buffer subsystem or from API Buffer Server, Buffering Manager
helps ensure that buffering is configured properly for existing interfaces. After upgrading, you
can also use Buffering Manager to add PI Data Archive servers or collectives that will receive
buffered data.
With Buffering Manager, you can also:
• Modify buffering settings for the computer that Buffering Manager is running on, specific
servers, and collectives receiving buffered data.
• View buffering status, estimated buffer capacity, number of events sent and queued, and any
point errors for servers and collectives.
• Export files containing detailed information about the status of buffering on a computer.
• View messages with additional information for troubleshooting issues.
1. Interface sends data to PI Data Archive. PI interfaces collect data from the data sources and
pass them on to the server in the form of events. An event consists of a time stamp, a value,
and a status. Before sending an event to PI Data Archive, the interface evaluates the event: it
sends significant events to PI Data Archive and discards the others. This is called exception
reporting. Interfaces complete the following steps:
a. Get data and create an event.
b. Perform exception testing to determine if event is significant.
c. Send significant events to PI Data Archive and discard the rest.
d. If buffering is configured, save the events on disk in case PI Data Archive is unavailable.
Note:
The buffering service may also perform compression testing and fans data to all
members of a PI collective. This is called n-way buffering.
2. PI Snapshot Subsystem receives all data. On PI Data Archive, all new events are handled first
by PI Snapshot Subsystem. PI Snapshot Subsystem holds a single value for each PI point. If
data comes in time order, incoming events become new snapshot values.
When a new value comes in, PI Snapshot Subsystem evaluates the old value by performing
compression testing. Based on the results of the compression testing, PI Snapshot Subsystem
either discards the old value or sends it to the event queue. PI Snapshot Subsystem
completes the following steps:
a. Get a new event and make this event the new snapshot value.
b. If the new event is out-of-order, send it directly to the event queue without performing
any compression testing. Otherwise, perform compression testing between the old and
new events.
c. Send significant events to the event queue and discard the rest.
3. PI Archive Subsystem reads data from the event queue. PI Archive Subsystem continuously
reads data in the event queue and stores it in a memory cache, and eventually into archive
files. However, when PI Archive Subsystem is shut down or unable to receive data, the event
queue holds the data, serving as a high-speed buffer. When available, PI Archive Subsystem
resumes data processing. PI Archive Subsystem completes the following steps:
a. Read events out of the event queue.
b. Validate and store events in the write cache.
c. Periodically move data from the write cache into archive files.
4. Users access the data through client applications. The ultimate goal of a PI System is to
distribute information across the enterprise or organization to those who use it to make key
decisions. To achieve this goal, OSIsoft produces a number of client tools that display PI Data
Archive data in various formats.
• Snapshot
• Compression testing
• Event queue
Exception reporting
Exception reporting ensures that a PI interface only sends meaningful data, rather than
sending unnecessary data that taxes the system.
Exception reporting uses a simple deadband algorithm to determine whether to send events to
PI Data Archive. For each point, you can set exception reporting specifications that create the
deadband. The interface ignores values that fall inside the deadband.
In the preceding illustration, the interface reports values A, D, and C to PI Data Archive. Value A
is the last reported value. Values B and C fall within the exception deadband, but value D falls
outside the deadband. The interface reports value D along with the previous value: in this case,
value C. Compression testing will determine if C needs to be preserved, or if A and D are
sufficient to recreate the original signal with the required fidelity.
The interface uses the point's ExcDev, ExcMin, and ExcMax attributes to determine whether to
report the new value to PI Data Archive. For details on setting exception-reporting attributes,
see ExcDev, ExcDevPercent, ExcMax, and ExcMin.
Note:
Some interfaces do not support exception reporting. See your interface documentation to
determine whether the interface supports this capability.
Procedure
1. Set the ExcMax point attribute to 0.
2. Set the ExcDev or ExcDevPerc point attribute to 0.
Snapshot
PI Snapshot Subsystem gets the new data from the interface node and holds the most recent
value for each point. This most recently acquired value for a point is called the snapshot.
PI Data Archive evaluates the previous snapshot according to the compression specifications
and either sends the old value to the event queue or discards it.
Note:
Sometimes an event enters PI Snapshot Subsystem with a time stamp that is older than
the current snapshot value. This is called an out-of-order event. PI Data Archive sends
out-of-order events directly to the event queue for archiving, without compression
testing.
These values in PI Snapshot Subsystem are called snapshot events or just snapshots. The
collection of all the snapshot values for all the points is the Snapshot Table.
Note:
The out-of-order event is the incoming event with the older timestamp of the last event in
the system.
Compression testing
Compression testing ensures that you store just enough data to accurately reproduce the
original signal.
PI Snapshot Subsystem uses compression testing to determine what events need to be saved in
the archive. For example, in the following illustration all the events fall on the same straight
line. In a simple case like this, you do not need to store all the points on the line. If you store
just two points, you can recreate the point value for any other time.
The same principle applies to compressing real-world data. PI Data Archive uses a compression
algorithm to determine which events to store. The compression test can essentially recreate
other events through extrapolation of surrounding events. This compression method is called
swinging-door compression.
When the PI Snapshot Subsystem receives a new value, the value's time stamp is the last
snapshot value that was received before the latest snapshot value. This value is recorded only if
any of the values since the last recorded value do not fall within the compression deviation
blanket.
Any data point which was excluded via compression would have been within the above
parallelogram.
Note:
For more information on compression testing, see the OSIsoft Learning Channel video:
watch?v=.
Each point has three attributes that comprise the compression specifications: CompDev or
CompDevPercent (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). For details, see CompDev, CompDevPercent, CompMax, and
CompMin.
An event bypasses the compression process and is put in the event queue in the following
instances:
• The Compressing attribute for the point is set to Off.
• The event's time stamp is older than the time stamp of the current snapshot. Such an event
is considered out of order.
• The Status attribute of the point has changed.
• The event is annotated.
Swinging-door compression is not used when the Step attribute is set to On. 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. For more information, see Step attribute in PI points.
Compression guidelines
Compression gives you the flexibility to configure on a per-point basis, with the option of
archiving relevant information. Compression impacts performance, bandwidth, and data
access. Compression not only saves storage space, it also helps you to store only meaningful
data. PI Data Archive stores the actual values received from the source, not interpolations,
averages, or approximations. This dramatically improves performance for users and does not
cause loss of significant data.
You have complete control over the amount of compression used, from the most compression
(lossy) to the least compression (lossless). For example:
• Turn compression on for noisy signals.
• Turn compression on and set the compression deviation (CompDev) attribute to zero. With
this setting, successive identical values (or values aligning perfectly) are not archived. This
is more efficient than turning compression off.
• Turn compression off for manually entered and totalized data, and for points where each
event is significant and not merely representative of an underlying flow (such as lab
measurements). When compression is turned off, all exceptions are recorded.
A PI Data Archive installation with default compression values is appropriate for most cases.
Setting compression requires you to apply your process knowledge about the nature of the
signal. One compression-deviation specification does not work for all measurements. Consider
sensor type, instrument accuracy, and so on. Fortunately, there are broad categories of
measurements in a process plant. Similar flow meters, pressure gauges, and thermocouples
have the same degree of repeatability and reproducibility in their measurements.
Event queue
The event queue serves as a memory and disk buffer between the snapshot subsystem and
archive subsystem. PI Snapshot Subsystem adds data to the queue and PI Archive Subsystem
removes data from the queue.
Normally the event queue passes events to the archive as quickly as they arrive, but in some
circumstances PI Archive Subsystem might be busy or unavailable. When this happens, the
event queue stores the data, filling until the archive is again available. This is called archive
queuing.
Shutdown events
PI points have a configurable attribute, Shutdown, to determine whether shutdown events are
written. The time stamp of the shutdown event normally represents the actual shutdown time
of PI Data Archive as recorded by PI Snapshot Subsystem. If PI Data Archive shuts down
ungracefully, this time stamp is accurate to within 15 minutes by default.
Valid values for the Shutdown attribute are 1 (On) and 0 (Off). If a point's Shutdown attribute is
1, then PI Shutdown Subsystem writes a shutdown event whenever PI Data Archive shuts
down. Unless you configure points to receive shutdown events, only test points such as
sinusoid and sinusoidu receive shutdown events.
For points collected by remote interfaces that are configured for buffering or high availability
(HA), OSIsoft recommends the default setting of 0 (Off). This is because if you run remote
interfaces with buffering or PI Server collectives, shutdown events are not an accurate
indicator of data loss when PI Data Archive shuts down. With properly configured buffering,
data simply queues up for PI Data Archive while it is shut down, provided the remote interfaces
continue running. Also, if PI Data Archive is part of a collective, shutting down one member has
no effect on the other members' ability to continue receiving and serving data.
Many sites configure points that store laboratory test values so that the lab test points do not
receive shutdown events. Lab values are assumed to be constant between tests. Inserting
shutdown events for these points can be misleading.
Note:
OSIsoft recommends that you do not run interfaces on the same machine as PI Data
Archive. However, if you do use such a configuration, configure these local interfaces for
shutdown events. Unlike most PI Data Archive subsystems, PI Shutdown Subsystem exits
after completion.
Note:
Do not specify additional tags by appending comma-separated tag masks or by using
additional lines. You can specify only one tag mask. You must specify at least one tag
mask to enable the shutdown system to operate without errors. To prevent all shutdown
events, specify a tag mask that does not match any tag.
You can use other point attributes and values in addition to, or instead of, the shutdown flag.
All conditions are logically combined with AND. If no point attributes are specified, all tags
specified by the tag mask are selected to receive shutdown events.
For example, this configuration file entry selects only tags that start with s, have the location1
attribute set to 0, and the point source set to H. No other tags receive shutdown events:
! tag mask
s*
! point attributes
location1,0
pointsource,H
PI time
You can use a special syntax, called PI time, to specify inputs for time stamps and time
intervals. PI time uses specific abbreviations, which you combine to create time expressions.
PI time abbreviations
When specifying PI time, you can use specific abbreviations that represent time units and
reference times.
Time-unit abbreviations
Abbreviation Full version Plural version Corresponding time unit
s second seconds Second
m minute minutes Minute
h hour hours Hour
d day days Day
To specify time units, you can specify the abbreviation, the full version, or the plural version of
the time unit, such as s, second, or seconds. You must include a valid value with any time unit.
If specifying seconds, minutes, or hours, you can specify a fractional value, such as 1.25h. You
cannot specify fractional values for other time units.
Reference-time abbreviations
Abbreviation Full version Corresponding reference time
* Current time
t today 00:00:00 (midnight) of the current day
y yesterday 00:00:00 (midnight) of the previous day
sun1 sunday 00:00:00 (midnight) on the most recent Sunday
jun2 june 00:00:00 (midnight) on the current day in June of the current
year
dec DD december DD 00:00:00 (midnight) on the DDth day of December in the
current year
YYYY 00:00:00 (midnight) on the current day and month in year
YYYY
M-D or M/D 00:00:00 (midnight) on the Dth day of month M in the
current year
DD 00:00:00 (midnight) on the DDth day of the current month
1: Use the first three letters as an abbreviation for any day of the week: sun, mon, tue, wed, thu, fri,
or sat.
2: Use the first three letters as an abbreviation for any month of the year: jan, feb, mar, apr, may, jun,
PI time expressions
PI time expressions can include fixed times, reference-time abbreviations, and time offsets. A
time offset indicates the offset direction (either + or -) and the offset amount (a time-unit
abbreviation with a value).
For example, PI time expressions can have the following structure:
Structure Example
Fixed time only 24-aug-2012 09:50:00
Reference-time abbreviation only t
Time offset only +3h
Reference-time abbreviation with a time offset t+3h
Include at most one time offset in an expression; including multiple time offsets can lead to
unpredictable results.
Time-stamp specification
To specify inputs for time stamps, you can enter time expressions that contain:
• Fixed times
A fixed time always represents the same time, regardless of the current time.
Input Meaning
23-aug-12 15:00:00 3:00 p.m. on August 23, 2012
25-sep-12 00:00:00 (midnight) on September 25, 2012
• Reference-time abbreviations
A reference-time abbreviation represents a time relative to the current time.
Input Meaning
* Current time (now)
3-1 or 3/1 00:00:00 (midnight) on March 1 of the current year
2011 00:00:00 (midnight) on the current month and day in the year 2011
25 00:00:00 (midnight) on the 25th of the current month
t 00:00:00 (midnight) on the current date (today)
y 00:00:00 (midnight) on the previous date (yesterday)
tue 00:00:00 (midnight) on the most recent Tuesday
• Time offsets
Entered alone, time offsets specify a time relative to an implied reference time. The implied
reference time might be the current clock time or another time, depending on where you
enter the expression.
Input Meaning
-1d One day before the current time
+6h Six hours after the current time
Time-interval specification
Time-interval inputs define intervals for collecting or calculating values during a time period.
For example, you might specify a 60-minute interval to compute an hourly average over a 12-
hour period. To specify time-interval inputs, enter a valid value and time unit:
• Positive values define intervals that begin at the earlier time in the period and that finish at
or before the later time in the period.
Start time 2:00:00
End time 3:15:00
Time interval 30m
Returned intervals 2:00:00 to 2:30:00
2:30:00 to 3:00:00
• Negative values define intervals that finish at the later time in the period and that begin at
or after the earlier time in the period.
Start time 2:00:00
End time 3:15:00
Time interval -30m
Returned intervals 2:15:00 to 2:45:00
2:45:00 to 3:15:00
The pidiag utility returns several lines of output, including your time zone names. For
more detailed results, use the pidiag -tz display options.
See Customize standard and Daylight Saving Time changes to change this setting.
• time_string [time_zone]
Display the Local and universal time (UT) times in seconds for the specified time string.
With the optional time_zone, displays time zone information and converts the time as if the
specified time zone were in effect.
• -check
Indicates if the time zone settings on your system are invalid. If the time-zone settings are
valid, the command generates no output.
• -dump [-brief]
Dumps the entire time zone table, including fall and spring changes in every year. The dump
is in comma-separated variable (CSV) format, which you can load into a spreadsheet with all
time-change information for the local time zone.
With the optional -brief, the output includes the year and spring and fall time changes,
each marked with D or S to denote daylight or standard time.
• -full
Displays additional information about the localhost.tz file, such as the file’s UID, creator,
and creation time. The information is valid only if PI Data Archive successfully loaded
localhost.tz.
Procedure
1. Open a command window and navigate to the PI\adm directory.
2. Type:
pidiag -tz "timeString"
For example:
C:\Program Files\PI\adm>pidiag -tz * GMT0BST
Procedure
1. Open a command window and navigate to the PI\adm directory.
2. Type:
pidiag -tz "timeString"
The asterisk in the above line indicates that this is an ambiguous time string unless you
include the time zone name.
Other commonly used time zone codes include S for standard time, D for daylight time, and
MET for Middle European Time.
This provides translation between time string formats and internal formats: If time_stamp
starts with 0 (zero) an integer format (seconds since 1-jan-70) is translated to string
representation. pidiag assumes local time, unless you use the U or UTC argument, in which
case the argument is taken to be universal time (UTC). If the first character is not 0, the time
argument is treated as time string, absolute or relative, and translated into an integer value.
Both local time and UTC integer values are displayed.
Procedure
1. To determine the archives that would be included with the first incremental backup, run the
command:
piartool.exe -backup -identify -type incremental -verbose
2. Examine the list. If you want to exclude any archives from your incremental backup or if any
archives are marked as read only, identify the most recent archive in the list that you want to
exclude. The most recent archive has the most recent End Time (as displayed by the
piartool -al command). Use this end time in the following -identify command.
piartool.exe -backup -identify -type incremental -verbose
-excludeArchivesWithEndTimesOlderThan EndTime
3. Examine the list. It should not include the archives that you excluded. Use the same end time
to modify the command line of the scheduled task that you create in Customize the default
backup.
Procedure
1. On the PI Data Archive computer, log in with a Windows account that has administrator
privileges.
2. Open a command prompt window.
3. Change to the PI\adm directory.
For example, if PI Data Archive is installed on the D drive, you would type:
cd /d "%piserver%adm"
4. Select a target directory for your backups, for example e:\pibackup. Ideally, the backup
drive is a separate drive from the system drive or the drive where your archives are stored.
pibackup e:\pibackup -install
We do not recommend UNC paths because the PI Backup Subsystem does not retry if network
errors occur. If you do use a UNC path, you can specify a path to a shared directory on a remote
computer, but you cannot use mapped network drives.
Procedure
• Change backup time.
The default time is 3:15 AM.
• Change the Windows user under which the task runs.
By default, the task runs under the System account. If you are using the pisitebackup.bat
script to back up files to a remote computer, then run the scheduled task as a user that has
sufficient privileges to write to the target directory on the remote computer.
• Change the path to the scheduled backup directory.
• If you need to exclude old backups as determined in Exclude old archives from backup?,
append the command line of the scheduled task with the following:
-excludeArchivesWithEndTimesOlderThan EndTime
Procedure
1. On the PI Data Archive computer, log on to a Windows account that has administrator
privileges.
2. In Control Panel, open Scheduled Tasks.
3. Double-click the PI Server Backup task.
4. In the Properties dialog box, click the Triggers tab, then click Edit.
5. Specify the settings you want.
6. Click OK.
Third-party software reduces your backup administrative tasks. For example, typical third-
party backup software can be configured to discard old backups after a specified period.
Also, IT can typically manage third-party backup software so that the PI system manager
can attend to other tasks.
Add the PIPC directory to the PI Data Archive daily backup task
If you choose not to use third-party software to back up the files in the pipc directory, you can
configure the scheduled backup task to include them.
Procedure
1. On the PI Data Archive computer, log on to a Windows account that has administrator
privileges.
2. Open a Windows command window.
3. Change to the PI\adm directory: cd %piserver%adm
4. Find the file called pisitebackup.bat.example.
Procedure
1. To monitor messages that are written to the PI Message log during the backup, start PI SMT
and select Operation > Message Logs.
2. In the Windows Task Scheduler, right-click the PI Server Backup scheduled task and select
Run. Files are backed up to the following directories.
◦ Archives are backed up to E:\pibackup\arc.
◦ Files from C:\pi\dat, C:\pi\adm, C:\pi\log, and C:\pi\bin are backed up to E:
\pibackup\dat, E:\pibackup\adm, E:\pibackup\log, and E:\pibackup\bin,
respectively.
3. Monitor the PI Message Log messages from SMT. At the beginning of the backup, you should
see the message Backup operation started. When the backup is complete, you
should see the Backup operation completed successfully message.
Alternatively, to find out if the backup is complete, check the task status in the Windows
Task Scheduler.
4. After the backup is complete, examine the backup log in E:\pibackup. The log name
format is pibackup_dd-MMM-yy_hh.mm.ss.txt. The log file includes the following
information:
◦ Near the beginning of the log, the currently registered archives are listed. This archive list
can be helpful during restore operations. For example, when restoring PI Data Archive, it
is helpful to know at the time of the backup which archive was the primary and which
directories the archives were in.
◦ If the backup is successful, at the end of the log you should see the message
pibackup.bat script completed successfully.
◦ A Verbose File Backup Report indicating which files were copied to the backup
directory.
◦ The list of subsystems that were registered for backup and the subsystem version
numbers.
◦ A summary of the backup that looks similar to the following.
Backup in Progress: FALSE
Files Copied: 24
Files Skipped: 36
File Copy Failures: 0
Total File Count: 60
Last Backup Start Pending: 1-Nov-09 03:15:05
Last Backup Start: 1-Nov-09 03:15:26
End: 1-Nov-09 03:15:42
Status: [0] Success
Last Backup Type: INCREMENTAL, VSS, Component Mode
Last Backup Event: BACKUPSHUTDOWN
Last Backup Event Time: 1-Nov-09 03:15:43
Verification Start Time: 1-Nov-09 03:15:42
VSS Supported: TRUE
The type of the backup should be INCREMENTAL. The first incremental backup of a
newly installed PI Data Archive should be equivalent to a full backup. A backup type of
NUMARCH/CUTOFF is possible only if the backup task is left over from an upgrade.
5. Restore the PI Data Archive server from the backup, as described in Restore a backup to an
existing PI Data Archive server, then check the restored server to make sure the backup and
restore were successful.
Note:
Right-click a column heading to see a complete list of columns you can display.
• Copy
The backup type for unscheduled backups, that is, those run with the Backups tool.
• Incremental
The backup type for the regularly scheduled PI Data Archive backups.
• Differential
A backup type if you are using third-party backup software to back up PI Data Archive.
• Full
A backup type if you are using third-party backup software to back up PI Data Archive.
• Numarch/Cutoff
The backup type for regularly scheduled backups that were configured on PI Server
versions 3.4.370 or 3.4.375.
Note:
For more information on PI Data Archive back up types, see https://
customers.osisoft.com/s/knowledgearticle?knowledgeArticleUrl=KB01032.
Procedure
1. Open PI SMT.
2. Under Collectives and Servers, select the server you want to check.
3. Under System Management Tools, select Operation > Tuning Parameters.
4. In the Tuning Parameters tool, click the Backup tab.
5. Double-click Backup_MaxHistory and set the parameter value.
Procedure
• Select a backup in the Backup History table to view information about the backup in the
Summary fields below the table:
◦ Method
Information about the backup method:
▪ Type
Backup types include incremental, copy, full, differential, or Numarch/Cutoff (see PI
Data Archive backup types).
▪ VSS/non-VSS
True for VSS backups; False for non-VSS backups.
Note:
PI Server 2015 and later versions only support VSS backups.
▪ Component Mode
Meaningful only for third-party backups. Some third-party backup applications
cannot do component mode backups and do not provide information to PI Data
Archive about the success or failure of the backup.
▪ Third party
Appears if PI Backup Subsystem is not the application used to perform the backup.
◦ Start Time
The time the backup started.
◦ Duration
The time taken for the backup to complete.
Procedure
• Double-click a backup in the Backup History table to open the Backup Details window. The
Backup Details window shows a summary of backup details and a list of backed up files.
The index number represents the order in which the backup occurred, relative to the other
backups in the list. Use these options to see details for a different backup:
• The following backup statistics for each subsystem and archive included in the backup:
◦ Freeze Transition
Time spent for all subsystems to go from an unfrozen to frozen state.
◦ Initialization Duration
Time elapsed between the issue of the backup request and the start of the backup.
• A list of the subsystems that were available for backup at the time the backup was executed.
• Total Files
Number of files selected for backup.
• Files Backed Up
Number of files that were backed up.
The table at the bottom of the tab shows lists the backed-up files:
Column Description
File Name The name of the backup file
Source Directory The full pathname of the directory where the backup file is located
Report The action taken or the reason the backup failed
Destination The name of the directory to which this file was backed up
Status A status code: success for a successful backup or an error for an
unsuccessful backup
Size The size of the file in KB
Component Description The name of the component to which the file belongs
You can:
• Click a column heading to sort the list by that column.
• Right-click a column heading to select the columns you want to display.
If any errors occur during a backup, the output of this command is automatically dumped to
the backup script log.
To display all messages related to backup, use a command of the following form:
pigetmsg -src pibackup –st starttime –et endtime
To display only those messages from the PI Backup subsystem itself, use a command of the
following form:
pigetmsg -pr pibackup –st starttime –et endtime
• Windows application event log
Look for messages from VSS and COM+ event sources.
• Windows system event log
Look for messages from VOLSNAP and NTFS event sources.
• Sometimes the system can get into a state where the ole32.dll becomes unregistered. If
ole32.dll is unregistered, backups do not work. To resolve this issue, re-register
ole32.dll with the following command:
regsvr32 ole32.dll
• Backups can fail if either of the following services is disabled:
◦ Microsoft Software Shadow Copy Provider
◦ Volume Shadow Copy
◦ COM+Event System
• Typically, the Volume Shadow Copy service should not be running. It is started on demand
whenever it is needed. If the service is running, it may be stuck in a bad state. To stop the
service, enter the following command:
net stop "Volume Shadow Copy"
If this command does not work, use Windows Task Manager to end the VSSVC.exe process.
• Backups of PI Data Archive have been known to fail when the OfmProvider from St. Bernard
software is installed on the PI Data Archive computer. To determine if this software is
installed, run the vssadmin list providers command and look for OfmProvider in the
output.
• All archives to be backed up must be on the PI Data Archive computer. If the archive to be
backed up is on a remote drive, such as a UNC path, the backup will fail unless the file is
marked read only, and the pibackup service is configured to run as an account that has
appropriate permissions.
• Backups require at least one NTFS partition on the machine where PI Data Archive is
installed.
Backup start failed, Status: [16896] RPC Resolver offline for a subsystem to
which the backup subsystem is communicating. Find -10733 error in message log to
identify problematic RPC
Two messages will appear in the PI Data Archive message log with the -10733 error similar to
the following:
E 19-Oct-09 13:54:57 pibackup (5059)
>> Callback failed for <pibatch> for the IDENTIFY event. Error [10733]
PINET: RPC Resolver is Off-Line.
E 19-Oct-09 13:54:57 pibackup (5061)
>> Error [10733] PINET: RPC Resolver is Off-Line., failed to send the IDENTIFY
backup event to pibatch
To fix the problem, you can either start the subsystem that is not running, or you can do the
following, if the subsystem was purposefully stopped:
1. Run the command piartool -backup -query and make note of the subsystems that are
currently registered for backup.
2. Restart PI Backup Subsystem.
3. Wait for the previously registered subsystems to register for backup again, with the
exception of the problematic subsystem. Subsystems may take up to 5 minutes to re-register
for backup after the backup subsystem has been restarted.
Procedure
1. In the Backups window, select the data server from the PI Server list.
2. Click Backup Now .
3. In the server Backup window, select the PI Data Archive components to back up.
As you make a selection, the right side of the window shows the list of files that will be
backed up.
4. In the Backup Location field, enter or browse to the target directory path.
You can specify a UNC or a local path on the server that you are backing up.
Note:
If you are not running PI SMT on the same PI Data Archive server that you are backing
up, then you cannot use the browse button unless you have Windows administrator
access to that server.
5. Click Backup.
Results
The Backup History window shows the backup details, including a backup's progress and
whether it was successful or aborted.
Procedure
1. Click the Export Backup Reports button to open the Save Backup History As window.
2. Browse to the save location.
3. Enter the file name.
4. Click Save.
• pibackup.bat
Use this script to launch a backup or to install a backup as a scheduled task.
• pibackuptask.bat
This script calls pibackup.bat and redirects the standard output to a log file.
• pisitebackup.bat
This custom backup script does not exist by default.
• pintbackup.bat
This custom backup script does not exist by default and typically should not be
implemented unless you have upgraded PI Data Archive.
• pibackup_3.4.370.bat
PI Data Archive installation creates this script only when upgrading from 3.4.370 to 3.4.375
or greater.
With the exception of installing a backup task with pibackup.bat, you do not need to run any
of these backup scripts directly.
Note:
If the PI AF server is installed on the same computer as the PI Data Archive server, then
an additional script, called afbackup.bat, is installed in the pipc directory (pipc\AF
\sql).
• pintbackup_3.4.370.bat
• afbackup.bat
pibackuptask.bat
The scheduled backup task calls the pibackuptask.bat script to launch the backup. The
script calls pibackup.bat and redirects the standard output to a backup log. The backup log is
written to the target directory of the backup and the log file has a name of the form:
pibackup_dd-mmm-yy_hh.mm.ss.txt
For example:
pibackup_5-Aug-05_14.16.22.txt
pibackup.bat
This script is used to install a backup as described in Create the scheduled backup task. The
pibackup.bat script performs the actual backup of PI Data Archive and calls the
pisitebackup.bat script after backing up. When the backup task runs, the
pibackuptask.bat script is called directly, which itself then calls pibackup.bat.
The pibackup.bat script starts the backup of PI Data Archive by running a single piartool
-backup command.
After you run pibackup.bat to set up the backup service, you do not need to run it directly
again. To launch a backup prior to its scheduled time, open the Scheduled Tasks Windows
control panel and run the PI Server Backup scheduled task from there. To run a manual backup
(one that does not change the last backup time for your scheduled backups) use the Backups
tool in PI SMT. For more information, see Perform an on-demand PI Data Archive backup.
Note:
Do not directly customize the pibackup.bat script. This script is overwritten on PI Data
Archive upgrades.
pisitebackup.bat
After the backup of PI Data Archive has completed, pibackup.bat calls pisitebackup.bat,
provided that pisitebackup.bat exists.
The pisitebackup.bat script can be used to:
Note:
The pisitebackup.bat script is not overwritten when PI Data Archive is upgraded.
pintbackup_3.4.370.bat
The pibackup_3.4.370.bat script is created by the PI Data Archive installation only when
upgrading from 3.4.370. The pibackup_3.4.370.bat script maintains the behavior of
backups from version 3.4.370 so that a user’s site-specific backup is not broken by the upgrade.
afbackup.bat
The pibackup.bat script calls afbackup.bat, if it exists. Since afbackup.bat is part of the
AF SQL database scripts, it exists on the PI Data Archive computer only if the AF SQL database
scripts is installed on the same computer as PI Data Archive. The afbackup.bat script is
installed in the pipc directory under pipc\AF\sql.
By default, the afbackup.bat script backs up an instance of SQL Server called ./sqlexpress.
If the PI AF database is called sqlexpress and is located on the PI Data Archive computer,
then the scheduled backup task backs up that database. The PI AF database backup is written
to:
pibackupdir\AF\
If the backup fails verification, the files are left in the precommit directory, and the reason for
the failed backup is written to a pibackupverify_*.log file in the PI Data Archive backup
directory. If successive backups fail verification, files will start accumulating in the precommit
directory. After the next successful backup, all files are copied to their final destination.
The following table shows commands that the PI Backup subsystem spawns to perform the
verification.
Component Verification Command
Archive components pidiag -archk
pibasess pibasess -verifydb
pibasess pidiag -fb
Although only the primary archive is verified by default, the number of archives to be verified
can be set with the BackupVerification_NumArch tuning parameter. Alternatively, all
verification can be suppressed by setting the BackupVerification tuning parameter to 0.
Although the last good backup should not be corrupt, it is still imperative to backup the PI Data
Archive backup directory, preferably with third-party backup software. For example, if you
accidentally delete a PI point and subsequently perform a backup, the PI point is deleted in the
last good backup as well. To retrieve the deleted PI point, you might need to restore a previous
backup. If you are not keeping multiple backups of your PI Data Archive backup directory, there
will be no means to do this restore.
Procedure
1. Isolate your PI Data Archive server from the network.
For more information, see Isolate a PI Data Archive server from incoming process data.
2. Stop PI Data Archive.
\%PISERVER%\adm\pisrvstop.bat
3. Delete the following file:
\%PISERVER%\dat\PIModuleUnitDb.dat
This file is automatically regenerated when you restore from backup.
4. Restore the backup to a temporary directory, such as C:\TempRestoreDir.
For example, if you back up your backup directory with a third-party backup application,
restore the desired backup to C:\TempRestoreDir. Alternatively, if you are restoring the
latest backup, you can restore the PI Data Archive server directly from the latest backup
directory. This procedure assumes that you have restored the desired backup to a folder of
the name C:\TempRestoreDir.
5. Copy the files from C:\TempRestoreDir\dat to %PISERVER%\dat.
6. Copy the files from C:\TempRestoreDir\adm to %PISERVER%\adm.
7. Copy the files from C:\TempRestoreDir\bin to %PISERVER%\bin.
Note:
Do not copy executable files with extension .exe.
8. Copy the files from C:\TempRestoreDir\log to %PISERVER%\log.
9. Copy the archive files from the C:\TempRestoreDir\arc directory in your backup folder
to their original location on PI Data Archive.
If you are not sure where your archive files were located on PI Data Archive, look in the
backup log file in C:\TempRestoreDir\. The log contains the archive list at the time of the
backup.
Because you are restoring to an existing server, you do not have to restore all archives. At a
minimum you must restore the primary archive. Restore other archives as needed.
10. If a site backup was performed (if, for example, C:\TempRestoreDir\sitebackup exists),
then copy the files from the site backup directories to the %PIHOME% directory.
11. Restart PI Data Archive.
12. Restore the PI Data Archive connection to the network.
13. Use the MDB to AF Synchronization tool in PI SMT to check the status of the synchronization
between MDB and AF. See Tools for editing PI AF and PI MDB objects.
14. If MDB and AF are out of sync, then use the MDB to AF Synchronization tool to reset MDB.
Procedure
1. Change the computer name of the new computer to the name of the old PI Data Archive
computer. Restart the computer.
2. Restore the backup to a temporary directory, such as C:\TempRestoreDir.
For example, if you have been backing up your backup directory with a third-party backup
application, restore the desired backup to C:\TempRestoreDir. Alternatively, if you are
restoring the latest backup, you can restore the PI Data Archive server directly from the
latest backup directory. This procedure assumes that you have restored a previous backup
to a folder of the name C:\TempRestoreDir.
3. Copy the installation kit to the new computer.
The installation kit should be for the same version of the PI Data Archive server as the
version you are restoring. Do not try to upgrade PI Data Archive as part of a restore.
Note:
If you are restoring an old backup, use the PI Data Archive server version that was
installed at the time that the backup was taken. The version is typically found in the
backup log, which should have been restored to C:\TempRestoreDir.
4. Disconnect the computer from the network.
This step ensures that data is not lost from buffered interfaces in subsequent steps.
5. Run the PI Data Archive installation kit. Install on the same drive letter and directory path
as on the old PI Data Archive computer.
6. Verify that the PI Data Archive computer is disconnected from the network.
7. Start PI Data Archive.
8. Confirm that PI Data Archive started up correctly and then stop PI Data Archive.
This accomplishes the "run once" functions performed after an installation. Since the PI
Data Archive computer is disconnected from the network at this point, data is not lost from
buffered server nodes.
9. Using Windows Explorer or the copy command, restore all files from the C:
\TempRestoreDir\dat\ directory to the new %PISERVER%\dat\ directory.
10. Restore all the message log files (pimsg_xxxxxxx.dat) from the C:\TempRestoreDir
\log\ to the %PISERVER%\log directory.
11. Restore all files from the C:\TempRestoreDir\adm\ directory to the new %PISERVER%
\adm\ directory.
12. Restore all files from the C:\TempRestoreDir\bin\ directory to the new %PISERVER%
\bin\ directory.
13. Restore the archives from the C:\TempRestoreDir\arc\ directory to the same directory
that they were installed on the old PI Data Archive computer. You can determine the
directories from the archive list in the restored backup log.
If you restore the archives to a different directory, you must also use PI SMT to register the
primary archive in the new location (Operation > Archives). If you are uncertain which of
the backed up archives is the primary archive, then examine the archive dates. The primary
should have the latest start date and an end date of Current time.
14. Start PI Data Archive.
15. Register additional archives in PI SMT as needed.
16. Use piartool -al and the client tools (such as PI DataLink) to verify that all the data has
been recovered. Run the clients locally, since the PI Data Archive computer is isolated from
the network. If the data is intact, then the restoration is complete.
Caution:
Failing to perform this step before exposing the restored server to buffered data could
cause data loss.
17. Connect PI Data Archive to the network. Verify it is reachable from clients on the network.
Monitor all buffered interface nodes.
18. Use the MDB to AF Synchronization tool in PI SMT to check the status of the synchronization
between MDB and AF.
19. If MDB and AF are out of sync, then use the MDB to AF Synchronization tool to reset MDB.
Case sensitivity
The PI System preserves the case of all strings, such as point and digital state names, but
searches are not case sensitive. For example, a string entered as BatchStart is stored exactly as
entered. A search for "batchstart" would return "BatchStart".
You can create, edit, and delete point classes and attribute sets. Editing and deleting point
classes and attribute sets is rarely necessary and can pose risks.
Base base
Classic base
classic
Totalizer base
totals
alarmparam
Attribute Type Default value
action1 String
action2 String
action3 String
action4 String
action5 String
AutoAck String yes
ControlAlg String
ControlTag String
Deadband Float32 0
Options String
ReferenceTag String
Srcptid Int32 0
test1 String
test2 String
test3 String
test4 String
test5 String
base
For descriptions of each of these attributes, see Base class point attributes.
Attribute Type Default value Limits
Archiving BYTE 1 ON, OFF, 1, or 0
Changedate Timestamp 31-Dec-69 System-assigned
16:00:00
Changer String piadmin System-assigned
Compdev Float32 0.2
Compmax Uint32 28800
Compmin Uint16 0 0 ≤ x ≤ 65535
Compressing BYTE 1 ON, OFF, 1, or 0
Creationdate Timestamp 31-Dec-69 System-assigned
16:00:00
Creator String piadmin System-assigned
Descriptor String
DisplayDigits BYTE -5 -20 ≤ x ≤ 10
EngUnits String
Excdev Float32 0.1
ExcMax Uint32 600
ExcMin Uint16 0 0 ≤ x ≤ 65535
ExDesc String
Future UBYTE 0
PointSource String Lab
PointType String Float32
Scan BYTE 1 ON, OFF, 1, or 0
Shutdown BYTE 1
Span Float32 100. x³0
Step BYTE 0
TypicalValue Float32 50. Zero ≤ x ≤ (Zero + Span)
Zero Float32 0.
classic
Attribute Type Default value Limits
Convers Float32 1.
Filtercode Int16 0
InstrumentTag String
location1 Int32 0
location2 Int32 0
location3 Int32 0
location4 Int32 0
location5 Int32 0
Squareroot Int16 0 On, Off, or 0 ≤ x ≤ 10
Srcptid Int32 0
Totalcode Int16 0
userint1 Int32 0
userint2 Int32 0
userreal1 Float32 0.
userreal2 Float32 0.
sqcalm_parameters
Attribute Type Default value
AutoAck String yes
ChartType Int32 0
ClearOnLimitChange String true
ClearOnStart String false
CLTag String
CommentTag String
LCLTag String
LSLTag String
Mixture String
OneSideofCL String
Options String
OutsideControl String
OutsideOneSigma String
OutsideTwoSigma String
PIProductLimits String no
ProductTag String
ReferenceTag String
ResetTag String
totals
Attribute Type Default value
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
Archiving
The Archiving attribute 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.
Compressing
Turns compression on (when set to 1) or off (when set to 0). Set compression to On for most
points. Set compression Off for laboratory and manually entered tags, so that 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. For Blob events, any change is significant.
Compression CompMax Specifies the maximum time in seconds between events in the
maximum archive. If the time since the most recent snapshot event is
greater than or equal to the point's CompMax value, the
current snapshot value is recorded in the archive. This
attribute is usually set to one value for all points in the
system. The recommended maximum time specification is 8
hours. Duplicate values are archived if the elapsed time
exceeds CompMax.
Note:
The CompMax 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.
Descriptor
The Descriptor is a text field that appears on various client application displays and can be
used in reports. It can be of any length up to 65,535 characters. When this value is read through
the PI API it is truncated to 26 characters.
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.
DigitalSet attribute
The DigitalSet attribute specifies the name of the digital state set associated with the tag (see
Digital state sets). This attribute applies to digital type tags only. It is ignored for all other types
of tags.
There is a special digital state set called the System digital state set (see The SYSTEM digital
state set). All tags, regardless of type, are associated with the System digital state set.
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 default value of DisplayDigits is -5. The minimum value is -20, and the maximum is 10.
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
2 23.45
1 23.5
0 23
-1 2E+001
DisplayDigits Format
-2 23
-4 23.45
-5 23.450
EngUnits
The Engineering Unit string describes the units of the measurement. Note that PI Data Archive
does not interpret the engineering units, this string is simply a label.
You can a string of any length, however, the PI API retrieves 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, but not case sensitive on search. The system
trims leading and trailing blanks during input.
Exception ExcMax Specifies the maximum time (in seconds) between events
Maximum that the interface reports to PI Data Archive. After the
specified ExcMax time elapses, the interface sends the new
value to PI Data Archive, regardless of whether the new value
is different from the last reported value. For example, it is
possible for the incoming data to be a single value for many
days. If ExcMax is set to 600 seconds (10 minutes) then a
value is not discarded due to exception if the previous event
time stamp was more than 10 minutes before that.
Exception ExcMin Specifies the minimum time (in seconds) between events that
Minimum the interface reports to PI Data Archive. For example, if
ExcMin is 5, the interface discards any values collected
within five seconds of the last reported value. Typically, you
set ExcMin to zero.
Note:
• Exception reporting parameters are used by interfaces only; they are not used by the
PI Server subsystems.
• Some interfaces do not support exception reporting.
Future
When set to Allowed (1), specifies that the point is intended to store future data.
When this attribute set to Disallowed (0), the point is considered "historical". Historical points
reject data with time stamps that are greater than 10 minutes beyond the current time.
Once a point is created, you cannot change this attribute.
For more information, see Future PI points.
Name
The Tag attribute, which specifies a point's unique name, appears as "Name" in some
applications, such as PI SMT and PI Builder. For details, see Tag.
NewTag
The NewTag attribute is used for renaming tags.
PointSource
The PointSource attribute is a string that associates a tag with an interface or PI application. An
interface uses the point source to retrieve all its points.
The SMT Point Source Table tool lists the currently used point sources.
Avoid using these characters as point sources:
• % (percent)
• ? (question mark)
• * (asterisk)
• _ (underscore)
PointType
The PointType value is assigned when the point is created. For details on editing this value,
see "Change PI point type." in Live Library (https://livelibrary.osisoft.com)
Point Type Used for points with
Digital Values that can only be one of several discrete states, such as ON/OFF and Red/
Green/Yellow.
Int16 Integer values between 0 and 32,767 (15-bit unsigned integers).
Int32 Integer values between -2147450880 and 2147483647 (32-bit signed integers).
The PI System reserves the lowest 32,767 values of the 32-bit range for digital
states.
Float16 Floating point values, scaled. The accuracy is one part in 32,767.
Float32 Single-precision floating-point values, not scaled.
Float64 Double-precision floating-point values, not scaled.
String String data of up to 972 characters if annotated, 976 otherwise.
Blob Any type of binary data up to 972 bytes if annotated, 976 otherwise.
Timestamp Any time/date in the range 1-jan-1970 to 1-Jan-2038 Universal Time (UTC).
Point types
For points collected by interfaces, use the point type that most closely matches the point type
in the source system.
For accumulators and other high precision values, use the higher precision point types: 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 supports numbers from 0 to
32,000.
• Only Digital type points use the DigitalSet attribute. It is irrelevant for other type points.
• For non-numeric type points, the CompDev, CompDevPercent, ExcDev, and ExcDevPercent
values are not applicable. These attribute values are returned as 0.
• For non-numeric type points, the Span and Zero attributes are not applicable. For digital
points, Zero is automatically set to the digital set number.
• For non-numeric type points, the step flag is set to On (or 1).
PtClassName
PtClassName specifies the point class. The point class must be defined before the point is
created.
The default PI point classes are:
• Alarm
Used for alarms. See the PI Data Archive Applications Guide for more information on Alarm
points.
• Base
A common set of attributes that all point classes include. The Base class includes both
system-assigned and user-assigned attributes.
• Classic
Includes attributes used by interfaces. Points that represent data from a PI interface are
always in the Classic point class.
• SQC_Alarm
Used for SQC alarm points. See the PI Data Archive Applications Guide for more information
on SQC alarm points.
• Totalizer
Used for points that represent a running total of data. For more information on Totalizer
points, see the PI Data Archive Applications Guide and the PI SMT Help topic for the
Totalizers tool.
In some cases, you can edit point classes. For details, see Modification of PI point classes.
Scan flag
Some interface programs use a Scan flag. Interfaces that honor this attribute do not update
points whose scan flag is set to OFF. See the interface documentation to find out if your
interface program uses it.
Shutdown flag
The Shutdown flag specifies whether shutdown events are written. Valid values for the
Shutdown attribute are 1 (On) and 0 (Off). For more information, see Shutdown events.
The Shutdown flag is used in conjunction with the configuration file dat\shutdown.dat.
Span
The Span is the difference between the maximum and minimum of the range. It is required for
all numeric data type points.
For float16 point types, Span is used with Zero for scaling values in the archive. The Span value
must be positive. If the value for a point type float16 point is greater than the maximum 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 trends in client tools (such as PI ProcessBook) with a
vertical scale of database.
For digital points, the PI Data Archive server assigns the value for this attribute and ignores any
edits made to it, such as with PI Builder.
This attribute is not used for non-numeric points.
You can change the Span for a point without affecting data already in the archive. For points of
type float16, the old Span is used for retrieving the archive data collected before the edit. The
new Span is used for data collected after the edit. If you change Span, the exception and
compression deviation percentages are preserved but the ExcDev and CompDev fields, which
are expressed in engineering units, are modified internally. If you specify any of the deviation
fields in the editing operation, they take precedence.
Note:
Some interfaces use Span information to filter incoming data. These interfaces often
convert out-of-range data to digital states over range and under range. However,
interfaces can use Span configuration in other ways. The PI Server computer itself does
not change out-of-range data, except for points of type float16.
Tag
The Tag attribute is the unique name of a point. The Tag attribute appears as "Name" in some
applications, such as PI SMT and PI Builder.
When naming points, use a consistent, meaningful convention.
The Tag attribute can be any length and can include letters, numbers, and spaces. It has the
following constraints:
• The first character can be alphanumeric, an underscore (_), or a percent sign (%).
Caution:
Avoid using the underscore (_) and percent sign (%) characters in the Tag attribute, as
some applications use them in special ways. For example, SQL uses these characters as
wild cards.
• Control characters, such as linefeeds or tabs, are not allowed.
• The following characters are not allowed:
* ? ; { } [ ] | \ ` ' " ,
These restrictions do not apply to other tag attributes, such as the descriptor.
Some functions and components restrict tag length. PI SQL Subsystem (pisqlss) can process
tags with up to 1,016 characters. Joins involving longer tags return no row found. Queries
without joins return rows but truncate tags to 1,016 characters. For more information about PI
SQL Subsystem , see "pisqlss" in Live Library (https://livelibrary.osisoft.com).
TypicalValue
The TypicalValue attribute documents an example of a reasonable value for this point. For a
numeric points, TypicalValue must be greater than or equal to the Zero attribute value, and less
than or equal to the Zero plus the Span attribute values. Some interfaces use TypicalValue as an
initial or default value.
Zero
The Zero attribute indicates the lowest value possible. It does not have to be the same as the
instrument's lowest value, but that is usually a logical choice. Some interfaces require that the
Zero and Span match the instrument system range. See the interface documentation for details.
This attribute is required for numeric data type points.
The Zero is the bottom of the range used for scaling float16 values in the archive. If the value
for a float16 type point is less than the bottom of range, the value is recorded in the archive as
the Under range state when the archive cache is flushed to disk. The Zero is also used when
defining trends in client tools (such as PI ProcessBook) with a vertical scale of database.
For digital points, the PI Data Archive server assigns the value for this attribute and ignores any
edits made to it, such as with PI Builder.
This attribute is not used for non-numeric points.
A point's Zero attribute can be changed without affecting data already in the archive. For points
of type float16, the old Zero is used for retrieving the archive data collected before the edit. The
new Zero is used for data collected after the edit.
Note:
Some interfaces use Zero information to filter incoming data. These interfaces often
convert out-of-range data to digital states over range and under range. Interfaces might
also use Zero configuration in other ways. PI Data Archive itself does not change out-of-
range data except for points of type float16.
Conversion
Conversion is a number that multiplies the raw Totalizer result. It is used to convert the rate
tag units to the proper units for the totalization.
For TimeWeighted totals, the total is computed with the assumption that the rate tag is in units
per day. If the rate tag units are not in units per day, use Conversion to convert the rate tag to
units per day.
For example, suppose the rate tag units are megawatts (MW) and the desired total is kilowatt
hours (kWh). First, convert the input rate tag to units per day: 1 MW = 1 MJ/sec, so the
conversion factor is (1 MJ/sec) x (86400 sec/day). The totalizer tag's unit of measure would
then be MJ. Next, convert the totalized value from MJ to kWh. 1 kWh = 3.6 MJ, so the conversion
factor is:
Filtercode
The Filtercode indicates the time constant of a first-order filter used to smooth incoming data.
While it does impact the compressed data, it does not affect exception reporting.
We recommend not altering incoming data by leaving this code at its default value of 0. The
other options are:
Code Time Constant (Seconds)
1 10
2 60
3 120
4 600
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.
Note:
For more information, see PI Interfaces.
For example, if you are using PI Interface for OPC DA version 2.7.0, refer to the documentation
for that specific interface version.
SquareRoot
Some interface programs use the square root code. Check the manual for your interface.
Srcptid
Srcptid is a read-only attribute that represents the PI point number corresponding to the tag
specified in the SourceTag attribute.
Built-in attributes
Built-in attributes are a part of every PI point, but do not belong to any particular attribute set.
The types and defaults of built-in attributes cannot be edited.
System-assigned attributes
When you create a point, several attributes are assigned by the system. You cannot change the
values of these attributes.
ChangeDate
The date and time when the point was last edited.
Changer
The last user to edit the point.
CreationDate
The date and time when the point was created.
Creator
The user who created the point.
PointID
The unique number that identifies the point internally. PointID is never reused, even when a
point is deleted. PointID is the PI point identifier 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.
RecNo
The record number 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.
Create points
The easiest way to create a point is to copy an existing point that is similar to the point you
want to create, then edit its attributes as needed.
Point Builder in PI SMT provides an easy way to edit and create a small number of PI points. If
you have Microsoft Excel, use PI Builder to create a large number of points.
Note:
To create new points, you need read/write access to the PIPOINT table. See Where to set
access permissions.
Note:
Some interfaces use the pointsource bit and not the scan bit to turn off points. To
decommission points for such an interface, change the pointsource attribute to a value
that you use only for decommissioned points.
7. To publish the changes:
a. Click Publish.
b. In the Edit Mode list, select Edit only.
c. Click OK.
Procedure
1. Stop the PI interface that collects data for the point you plan to change.
2. Open PI SMT.
3. Navigate to Points > Point Builder.
4. Search for and select the point for which you would like to change the type attribute.
5. In Point type, select the desired point type.
6. Save your changes.
Data from the previous type is coerced to the current type at retrieval time.
If an event cannot be coerced to the edited point type, the digital state Coercion Failed is
returned by default. The Coercion Failed digital state acts as a placeholder for an event that PI
Snapshot Subsystem failed to coerce. Out-of-order events may also result in a Coercion Failed
digital state.
Use the parameter Archive_DataCoercionPolicy to translate a digital state. For details, see
Configure error handling.
In the following table, allowable point type coercions are shown with a check mark (✓).
3Assuming positive, integer values that are lower than number of digital states
5Assuming the range of the source is compatible with the range of the target
Note:
When you change point types to int16 or digital, you must enter a value for the Zero and
Span attributes.
reconnect are refused. Subsystems and locally run utilities such as piconfig and piartool
can connect. Default-only attribute edits are supported in normal mode.
• You cannot rename attributes.
• You can add attribute sets to any point class.
• You can delete attribute sets from a point class (only if not used by any point) except:
◦ Required attribute sets contained in predefined point classes (see Predefined point
classes)
◦ In-use point classes
• You can rename any point classes, except predefined point classes.
• You can delete any point classes, except:
◦ Predefined attribute sets
◦ In-use point classes
These restrictions may limit your ability to undo some actions. Before editing point classes,
back up the PI Point Database.
Procedure
1. In a command prompt window, change to the PI\adm directory.
2. Type:
piartool -sys -standalone on
3. At the piconfig prompt, type:
@table piptcls
@mode create
@istru class
@istru set,...
MyPtClass
Base,MyAttribSet
@ends
4. To go back to normal mode, enter:
piartool -sys -standalone off
Procedure
1. In a command prompt window, change to the PI\adm directory.
2. Type:
piconfig
3. At the piconfig prompt, type:
@table piptcls
@mode delete
@istru class
MyPtClass
@ends
This feature makes it easier to determine what attribute sets are being used to form the point
class.
Procedure
1. Add the attributes MyAttribute1 (string) and MyAttribute2 (int32) to this point class. To do
this, create an attribute set, MyAttributeSet, as follows.
@table piatrset
@mode create
@istru set
@istru attrib,type,default
@istru ...
MyAttributeSet
MyAttribute1,string,my default string
MyAttribute2,int32,22
2. Check that the attribute was correctly created:
@table piatrset
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttributeSet
@ends
Informational messages
Some messages are not directly returned to the user but instead are sent to the PI Message
Subsystem. Such messages include information regarding the status of the steps involved in a
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.
Procedure
1. In a command prompt window, change to the PI\adm directory.
2. Type:
piconfig
3. At the piconfig prompt, type:
@table piptcls
@mode edit
@istru class,newclass
MyPointClass,MyNewPointClass
@ends
To illustrate, try editing a point that belongs to Totalizer point class to Classic point class in
piconfig as follows:
@table pipoint
@ptclass Totalizer
@mode edit
@istru tag,ptclassname,location4,pointsource
This is because @ptclass Totalizer sets the environment for this edit to Totalizer point
class, which does not have the location4 attribute. To edit the PtClassName attribute and
new attributes unique to the target point class at the same time, set the environment to the
target point class, Classic, by using @ptclass classic first:
@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
because PtClassName is a built-in attribute and every point has this attribute.
The meaning of a particular SYSTEM digital state always depends on the interface or source
application that wrote the event. For example, the Arc Off-line state is returned when there
is an archive gap, but in rare situations Arc Off-line can be sent for other reasons.
Additionally, your site might have programmed use of a particular SYSTEM digital state in a
non-standard way. For example, to indicate a graceful shutdown by an interface the default
SYSTEM digital state is Intf Shut. But it is possible to configure UniInt interfaces to write any
of the SYSTEM digital states to points at shutdown.
Note:
You can view all of the SYSTEM digital state names and numbers in PI SMT. Go to Points >
Digital States and select the SYSTEM set.
251 Under Range For Float16 type points, indicates a value that is less
than the bottom of range (Zero attribute) for the point.
For other point types, this state is usually the result of a
substitution coming from the data source.
252 Over Range For Float16 type points, indicates a value that is greater
than the top of range (Zero+Span attributes) for the
point.
For other point types, this state is usually the result of a
substitution coming from the data source.
255 Bad Input Written by the interface, if the data received was invalid.
For example:
• The data does not match the point type (such as
writing a float value to an integer point).
• The quality flag of the data received from the data
source was invalid.
For more information on the specific cause, see the
interface message log close to the event's timestamp.
315 Coercion After the data type of a point is changed, data from the
Failed previous type is coerced to the current type at retrieval
time. If an event cannot be coerced to the edited point
type, Coercion Failed is returned. See Allowable point
type coercions for more details.
316 snapfix The snapfix procedure has been used on the PI Data
Archive server to fix a corrupted snapshot table. After a
new value arrives, the value of snapfix is replaced and
not archived.
317 Invalid Float A point of floating-point data type received an invalid
value (for example, a string value).
318 Future Data The notion of the current value of a future PI point
Unsupported depends on the usage and requirements of the client
application. Therefore, for the end-of-stream value for a
future PI point, PI Data Archive returns Future Data
Unsupported.
For more information, see Future data.
PI Server determines the digital code value, such as 0 or 1, based on the position of the digital
state string in the Digital State Table. The first value is 0, the second is 1, the third is 2, and so
on.
You can define up to 16,383 state sets with up to 16,383 states in each set. For details, see The
SYSTEM digital state set.
Archive records
PI Data Archive stores archive events as data records. Data records are either primary records
or overflow records. Each point in the PI point database has one primary record allocated in
every archive file. Primary records are stored at the very beginning of the archive file. When
the primary record for a point fills up, the data for that event goes to an overflow record in the
archive file. Overflow records start at the end of the archive file and are filled backwards. Each
record is one kilobyte.
A point can have as many overflow records as needed. Points that receive events at a slow rate
might never need to allocate an overflow record, whereas points that receive events at a fast
rate might need to allocate many overflow records. PI Data Archive uses index records to keep
track of multiple overflow data records for a point.
Index records
Index records are records that index the overflow data of a point by time. After one overflow
record for a point is full, PI Data Archive creates an index record for that point and a new
overflow record. Archive data retrieval for points with chains of index records are marginally
slower than for points with zero or one index records.
The size of a dynamic archive file is flexible, enabling disk space to be allocated only as needed.
Dynamic archives cover a specific time range. The archive file grows as overflow records are
added, up to a specified maximum size or, at most, 2TB.
Archive management
The topics in this section explain how to perform tasks in PI SMT wherever possible and
provide command-line instructions where necessary. For more information on using
command-line tools for managing archives, see the PI Data Archive Reference Guide.
Note:
For information on managing future archives that are used to store future data, see
Future data. To use future data, you must install PI Data Archive 2015 or later versions.
• Archive Editor
View, edit, insert, and delete values for events in a PI archive. In SMT, select Data > Archive
Editor.
• Archives tool
Monitor and manage archive use. The tool displays a list of registered archives for each
connected PI Data Archive server, including the status and properties of each archive. In
SMT, select Operation > Archives.
Command-line utilities
For information on using command-line tools to manage archives, see the PI Data Archive
reference topics "PI Data Archive command-line utilities" in Live Library (https://
livelibrary.osisoft.com).
• piartool
Manage most archive management tasks, including creating, registering, and unregistering
archives, forcing archive shifts, and listing archive file details.
• piarchss
Use as an offline processor to reorganize (combine and split) and repair archive files.
Procedure
1. Start PI SMT and select the PI Data Archive server on which you want to view the archives.
2. Under System Management Tools, click Operation > Archives. The Archives tool opens. The
Archive File column lists all the archives registered on the selected server and displays the
full path for each. The primary archive is first on the list.
Caution:
On systems collecting production data, do not use anti-virus software to scan the
directories containing PI Data Archive database and archive files.
Procedure
1. Open PI SMT.
2. Under System Management Tools, click Operation > Tuning Parameters, and then click the
Snapshot tab.
3. Double-click the Snapshot_EventQueuePath parameter. The parameter window opens.
4. Set Value to the desired path for the event queue. Make sure the path is on a different disk
from the primary archive. Run the command pidiag -updateFolderSecurity to make
sure proper permissions are set in the new path.
5. Restart PI Snapshot Subsystem. This moves the event queue file location. You can delete the
old event queue file.
The following performance counters record information about automatic event-queue reset.
Performance counter Description
Event Queue Error Count Number of times that an error reading or writing
an event queue has occurred.
Reset Folder Count Number of event-queue reset folders currently on
disk.
Event Queue Reset State Set to ON (or 1) during an automatic queue reset,
and OFF (or 0) once the queue reset completes
successfully. This performance counter is a
Boolean value.
For lists of other performance counters that gather statistics, see the PI Data Archive reference
topic, "PI performance counters" in Live Library (https://livelibrary.osisoft.com).
Create an archive
Procedure
1. Select Start > PI System Management Tools > Operation > Archives.
2. Click the Create a New Archive button ( ).
3. In the Create a New Archive dialog box, select Single archive.
4. Click the browse button to change the archive path, if desired.
You can store an archive in any local or network directory that is accessible by PI Data
Archive. Local storage with other archives provides a convenient option for managing
archives.
5. If you do not want to use the chronologically numbered default name, enter a name in
Archive name.
If the text field is yellow, then the archive name is already in use by another file, possibly an
unregistered archive. You may want to cancel the procedure and use the existing archive, if
empty.
6. Select a source option to create the archive:
◦ Clone primary archive fixed size: creates an empty archive of fixed type that's based on
the size of the current primary archive.
◦ Create archive with a custom fixed size: creates an empty archive with a different size
(typically larger) than the current primary archive. In the accompanying field, specify the
size in megabytes (MB). The size must be equal to or greater than the size of the current
primary archive, up to a maximum of 2 TB.
◦ Create archive with fixed start and end time: creates an empty archive to be used only for
a specified time period. If you select this option, for the Type option, select Fixed.
Note:
Start and end times cannot overlap an existing archive.
7. Click OK.
The Archives tool creates and registers the archive.
Procedure
1. Select Start > PI System Management Tools > Operation > Archives.
2. Right-click an archive file from the target PI Data Archive server and choose Create New.
3. In the Create a New Archive dialog box, select Multiple archives for backfilling.
4. Click the browse button to change the archive path, if desired.
5. Enter a prefix for the file in Archive name, or accept the default prefix.
The start time and end time will be automatically appended to the archive name depending
on the archives being created.
6. Define the Maximum archive duration for each new archive file.
7. Enter Start time and End time for the new archive files using PI time format.
Note:
Start and end times must not overlap an existing archive.
8. Click OK.
The Archives tool registers the newly created archives automatically.
Archive names
Use a naming convention for your PI archives that is valid for the underlying operating system
and ensure that the file location has sufficient disk space. There are no other limitations to
name PI archives.
The default archive file names are piarch.xxx, where xxx is 001, 002, 003, and so on.
The associated annotation file has the same full path name as its archive file with .ann
appended. For example, the annotation file for the piarch.001 archive file would be piarch.
001.ann.
Archive size
Archive size affects backups, backfilling, frequency of shifting, and total number of points
allowed.
To determine archive size, use the following guidelines:
• If you are backfilling data, see Backfilling management.
• Allow at least 2 KB for each point in the system.
• An archive file cannot exceed 2 TB. However, if your PI Data Archive server will have 50,000
points or fewer, then you can safely use the default value.
• If you have more than 50,000 points, run 64-bit PI Data Archive on a 64-bit Windows
operating system and set the archive size to 4-8 KB times the total number of points, with
the following consideration on memory resources.
Select a size that allows at least two archive files to fit in the Windows File System Cache
(FSC). At most times, PI Data Archive writes to and reads from the two or three most recent
archive files. The FSC is capped at approximately 1 GB on 32-bit systems, but can use all of
the RAM on 64-bit systems. Therefore, a safe upper limit for archive files is 256 MB for 32-
bit systems and (RAM ÷ 3) for 64-bit systems.
Tip:
Many administrators size their archives based on a size that is convenient to use with
their desired backup media. As a rule of thumb, set your Snapshot Event Queue to half of
the archive size.
• Backup device
• Available disk space
• Average incoming data rate
Archive registration
The PI Data Archive archive registry contains the name, location, size, record count, and record
size for each archive file. This information is stored in the binary file, PI\dat\piarstat.dat.
Register archives
For PI Data Archive to recognize a file as an archive file, you must register the file. After an
archive is registered, it is available to the system and participates in shifts and storage and
retrieval of event data.
Procedure
1. Select Start > PI System Management Tools > Operation > Archives. The Archives tool lists
all the archives registered on the selected server.
2. Right-click an archive file from the target PI Data Archive server and select Register Archive.
3. Browse to the archive file you want and click Open.
Unregister archives
To move or reprocess an archive file, you must unregister the archive, make your changes, and
then re-register the file. You cannot unregister a primary archive. If the PI Data Archive server
is not on the local machine, this task requires read and write access on the PIARCADMIN
database.
Procedure
1. Select Start > PI System Management Tools > Operation > Archives.
2. Right-click an archive file from the target PI Data Archive server and select Unregister
Archive.
3. Click Yes.
Procedure
1. Select Start > PI System Management Tools > Operation > Archives.
2. In the toolbar, click Display Unregistered Archive .
3. Browse to the correct directory, select the unregistered archive file, and click Open.
PI SMT adds the unregistered archive to the list of archives.
Procedure
• To register archives, use the piartool -ar command. The syntax is:
piartool -ar path
The specified path must be the absolute path of an existing archive file.
For example, to register a single archive called piarch.006 in the PI\dat directory on the
D drive:
piartool -ar D:\PI\dat\piarch.006
You can use the wildcard characters * and ?. The symbol * matches all possibilities with any
number of characters. The symbol ? matches a single character and may be used any
number of times.
For example, to register all archive files in the PI\dat directory that begin with the
piarch.0 prefix:
piartool -ar D:\PI\dat\piarch.0*
Note:
When working with wildcards, wildcards will try and register all archives including
the ones that have been manually registered. This will not cause any issues.
Procedure
• To unregister an archive, use the piartool -au command. The syntax is:
piartool -au path
For example, to unregister an archive called piarch.006 in the PI\dat directory on the D
drive:
piartool -au D:\PI\dat\piarch.006
You can use the wildcard characters * and ? to register archives in bulk. The symbol *
matches all possibilities with any number of characters. The symbol ? matches a single
character and may be used any number of times.
For example, to unregister all archive files that begin with the piarch.0 prefix and are
located in the PI\dat directory:
piartool -au D:\PI\dat\piarch.0*
Archive shifts
The primary archive is the archive that receives current data. At some point, you'll need an
archive shift so that a new archive file is created and becomes the primary archive. The archive
shift is triggered when the primary archive is nearly full.
Note:
During an archive shift, you cannot add, edit, or delete points.
You can handle archive shifts in the following ways.
• Automatic archive shifts: The archive shift is triggered when the primary archive is nearly
full.
• Scheduled archive shifts: You specify the date and time that you want the archive to shift.
Note:
If you schedule archive shifts, then automatic shifts do not occur. However, you can
still force an archive shift, if necessary.
Archive_AutoArchiveFileSize Specifies the size of new primary archives that are created via
automatic archive creation. When set to 0 (the default
setting), the size of the new primary archive is always the
same as the current primary archive. When set to any other
value, specifies the size of the new primary archive when an
automatic archive create shift occurs. If you make the size
smaller than the current primary archive, the specified size
must be large enough to satisfy the primary records for
points currently in use.
Note:
On a PI Data Archive server, you can set tuning parameters by using PI SMT. Open SMT
and click Operation > Tuning Parameters. Click the Archive tab, double click the tuning
parameter you want to edit, enter the value you want, click OK.
Note:
If the Archive_AutoArchiveFileRoot is modified, and the Archive subsystem does not
have proper permissions to this new path, then run the command pidiag -
updateFolderSecurity to set proper permissions.
Procedure
1. Select Start > PI System Management Tools > Operation > Tuning Parameters.
2. Click the Archive tab
3. Select the Archive_AutoArchiveFileRoot parameter and clear the Value field (leave it
blank).
Procedure
1. Open SMT
2. Click Operation
3. Click Archives
4. In the main panel, with the Historic tab selected, click Review and update parameters
5. Select the desired shift duration in the Shift Schedule list
6. Click Save
Note:
If Auto create size(MB) is set, and shift type is changed from natural shift to scheduled
shift, the size setting will be automatically removed by SMT. Auto create size(MB) is
the same as the Archive_AutoArchiveFileSize tuning parameter. When it is not
set, PI Archive Subsystem will automatically calculate the archive size based on past
data rate and the shift duration. If you still want to configure the size in the Auto
create size(MB) box, fill in the desired size and click save.
Force shifts
When scheduled shift is configured, if a force shift is issued within 10 minutes of the next
scheduled shift time, the shift will happen, the new primary archive's start time will be set to
the next scheduled shift time, and the next scheduled shift will be skipped.
Sample output:
Procedure
1. In PI SMT, select Operation > Archives.
2. In the list view, right-click an archive and select Make Non-shiftable or Make Shiftable.
Use this procedure to force a server to shift from one historical archive to another.
Procedure
1. Select Start > PI System Management Tools > Operation > Archives.
2. Right-click the server's primary archive in the list and select Force Shift.
Procedure
1. Click Start > Control Panel > Administrative Tools > Services
2. In the Services window, find the interface that you want to start or stop. For example, PI
Random Simulator (random) Interface X64.
3. Right-click the interface service and choose Start or Stop.
Annotations in PI SMT
Use annotations to associate arbitrary information, such as text comments and other binary
data, with a PI archive value.
Use the PI Annotations Editor in the PI SMT Archive Editor to view, edit, insert, and delete
annotations to PI point values. Annotations can include comments, notes, supplementary
values with specified data types, and files.
Every value in the snapshot or the archive may be annotated. Annotated events always bypass
compression. An annotation can be of any binary data type. The size of an annotation is
controlled by the Snapshot_AnnotationSizeLimit tuning parameter.
Each archive file has a single associated annotation file, with an .ann extension. The
annotation file is created if it does not exist. It is important to store archive and annotation files
together, especially when a backed up archive file is restored.
Note:
Any operation on an annotation translates into an actual I/O, bypassing archive caching.
Annotated events are less efficient than non-annotated events.
You can use the following modes to maintain annotations.
• Standard/Default mode
Provides a table format that can include alternate values with assigned data types. Use this
mode for simple string annotations, annotations that do not require structured data, and to
conform with legacy annotations from earlier versions of PI Data Archive.
• String/VARIANT mode
Stores annotation data as an unspecified VARIANT data type. Use this mode for annotation
data that is structured, read programmatically, or exported for use by another application.
Procedure
1. Select Start > PI System Management Tools > Operation > Archives.
All the archives registered on the selected PI Data Archive server are listed. Any archive gaps
are labeled and highlighted in red.
2. Right-click the line displaying the archive gap and select Create New.
The Create New Archive dialog box appears. The dialog box is already populated with the
correct start and end times to fill the archive gap.
3. Click OK.
The new archive is created and registered, and an archive gap no longer appears in the
archive list.
Archive reprocessing
Starting with PI Data Archive 2016, you can use the PI SMT Archives tool to reprocess archives
while they are online.
Note:
You still need to perform some reprocessing tasks when an archive is offline by using the
command-line tool, piarchss. For example, use piarchss to combine archive files or
divide a large archive file into smaller files. See Offline archive file management with
piarchss for more information.
Reprocessing an archive typically improves performance for so-called deep queries, which
read single points over a long time range, for example, in PI ProcessBook trends. However,
reprocessing an archive can worsen performance of queries that read multiple points over a
time range (for example, points associated with batches or event frames).
Outside these situations, there is no gain from reprocessing archives, and even potential
degradation of performance due to unnecessary contention for system resources on a
production system (RAM, disk space, CPU). In particular, it is not necessary to reprocess
archives after a PI Data Archive upgrade, or to schedule a nightly, weekly, or monthly task to
reprocess all archive files.
Archive_ReprocessThreadCount
The Archive_ReprocessThreadCount tuning parameter is the number of worker threads
dedicated to reprocessing an archive file. On a low memory machine, only 1 thread will be used
regardless of the value of this tuning parameter. The parameter takes effect before archive
reprocessing. The default setting is half the number of processors on the server, the min: 1, and
max: processor count.
• The [-16305] message indicates that the events within the archive record are not in order. It
is typically displayed in conjunction with [-16302].
• The [-16302] message indicates that the chain for the index and overflow record is broken.
These messages are informational and are typically non-fatal. In some cases, there might be
some data loss depending on the nature of the corruption.
If you get these messages during an archive integrity check, repair the affected archive by
reprocessing it. After the archive is reprocessed, a report of all errors that were encountered
and resolved is shown.
If you get these errors while reprocessing an archive, the messages are informational and the
reprocessing utility will attempt to repair the discrepancies that were found.
Message number Message text
-16300 Invalid backwards chaining of overflow
-16301 Invalid backwards chaining of index
-16302 Overflow record not found in index records
-16303 Index entry referenced by multiple overflow
records
-16304 Out-of-order overflow record in index record
-16305 Out-of-order event found in overflow record
-16306 Event marked as annotated with no annotation
handle
-16307 Annotation record not found for annotated event
-16308 Annotation record referenced by multiple events
-16309 Index not matching overflow record start time
-16310 Event before archive start time
-16311 Event after archive end time
-16312 Unexpected data type for index record
-16313 Index start time doesn't match archive start time
-16314 First overflow record has a previous record
-16316 Unexpected data type for index record
-16317 Invalid archive file number
-16318 Circular chaining of overflow record
-16319 Circular chaining of index record
-16320 Too many errors, filtering non-fatal errors
-16321 Event at archive end time
-16322 Archive consistency check detected errors
-16323 Too many warnings, filtering additional warnings
-16324 Too many index records
If you get these messages during an archive integrity check, repair the affected archive by
reprocessing it. To see how to run an archive integrity see "Verify the integrity of the archive
files " in Live Library (https://livelibrary.osisoft.com). After the archive is reprocessed, a report
of all errors that were encountered and resolved is shown.
If you get these errors while reprocessing an archive, the messages are informational and the
reprocessing utility will attempt to repair the discrepancies that were found.
Messag Message text Is corruption detected, setting the corrupt flag?
e
number
-11001 Record header version mismatch Yes
-11002 Record header data mismatch Yes
-11018 Corrupt overflow or primary record Yes
pointers
-11064 Record header recid mismatch Yes
-11065 Record header chain pointer Yes
mismatch
-11141 Too many events on record load, Yes
most likely a corruption
Procedure
• To set the number of archives monitored, specify a number in the
Archive_DisableArchivingOnIOErrorRange parameter.
PI Archive Subsystem monitors the specified number of files for read-write errors, starting
with the primary archive. For example, if set to 3 (the default value), PI Archive Subsystem
monitors the primary archive plus the two previous archives. A value of 0 indicates that PI
Archive Subsystem monitors all files.
Note:
If PI Archive Subsystem loses its connection to the storage device where the primary
archive resides, it does not try to reconnect to the archive. Data flows into the event
queue, but is not stored in the archive file. To reconnect and store data in the archive,
stop and restart the subsystem. For more information, see the Knowledge article
Supported storage device types for PI Data Archive archive files.
While it is possible to set an archive file to read-only, doing so can result in data loss. Read-only
archive files cannot participate in archive shifts or be modified.
Procedure
1. Select Start > PI System Management Tools > Operation > Tuning Parameters.
2. In the Collectives and Servers pane, select the appropriate PI Data Archive server.
3. Click the Snapshot tab for the subsystem where you want to edit the tuning parameter
value.
4. If necessary, add the EditDays tuning parameter to the list. See Add a tuning parameter to
the list.
5. Right-click the EditDays parameter and click Edit.
6. Enter a value and click OK. A zero value means no time check is done.
7. For the changes to take effect, restart the PI Data Archive server.
4. In the Save Archive List As window, select a location to store the archive file.
5. Click Save.
Procedure
1. Edit the Archive_AutoArchiveFileRoot tuning parameter to configure the full path to
the new archive directory. The new primary archive is created in the new directory. Run the
command pidiag -updateFolderSecurity to make sure proper permissions are set on
the new path.
The new primary archive is created in the new directory.
2. Force an archive shift.
3. Move the non-primary archives:
a. Unregister the non-primary archives.
b. Move the non-primary archives and associated annotation files to a new directory.
c. Re-register the non-primary archives.
Procedure
1. Back up your data.
2. In the Servers pane, select the server from where you want to remove data.
3. In the System Management Tools pane, select Data > Archive Editor.
4. Right-click the value you want to delete and select Delete.
5. Click Save.
Note:
There is no prompt to confirm deleting values.
Procedure
1. Copy the following commands into a text file called DELEVENTS.TXT and save it in the pi
\adm directory.
This example uses the PI point, cdt158.
*DELEVENTS.TXT
@table piarc
@mode list
@istructure tag, starttime, endtime, count
@ostructure tag, time, status
@ostructure ...
@timf 9
@sigd 9
@output tmpdelevents.dat
cdt158,*-6h,*,*
*@exit - uncomment this to exit and review before deleting
@mode edit
@modify mode=remove
@istructure tag, time, value
@input tmpdelevents.dat
@exit
2. Edit DELEVENTS.TXT and replace cdt158 with the PI points (tags) and time ranges from
which you want to delete.
If you want to delete events from multiple PI points, add multiple entries. For example:
cdt158,*-6h,*,*
cdm158,y,t,10000
sinusoid,*-1m,*,20
The format is: PI point name, starttime, endtime, count of events you want
to delete
3. Open a command prompt, go to the PI\adm directory and run piconfig with
DELEVENTS.TXT as input.
C:\PI\adm>piconfig < delevents.txt
Delete an archive
You must unregister an archive before you can delete its files.
Procedure
1. In PI SMT, select Operation > Archives.
2. Right-click the archive and select Unregister Archive.
3. Open Windows Explorer and navigate to the archives folder (by default, C:\Program
Files\PI\arc).
4. Delete the archive file (archive_name.arc) and the related annotation file
(archive_name.arc.ann).
Backfilling management
Backfilling is the process of importing historical data from another source into PI Data Archive.
OSIsoft offers several interfaces for backfilling, including the PI Relational Database (RDBMS
via ODBC), the RDBMSPI Interface, and the Universal File and Stream Loader Interface (UFL).
• To avoid any burden on your main production server and risk to your real data, do
backfilling jobs on an offline PI Data Archive server.
• To avoid archiving unnecessary data and ensure efficient backfilling, backfill with
compression.
• Points for all backfilled data must be defined in the point database.
• Process data from all points in small batches, such as one day each.
• Backfill data in chronological order, from oldest to newest, within each point. If you backfill
out-of-order data, it is not compressed.
For a large amount of data, follow these additional recommendations.
• Consider writing a custom application to do the backfilling.
• Before backfilling, run a backfill test with a smaller time range to ensure that the data
imports properly. During the test, check the archive and snapshot statistics to see how the
backfilling affects PI Data Archive performance, and troubleshoot any other issues as
needed.
Procedure
1. Install PI Data Archive, start the PI Data Archive server, create all points, and then stop the
PI Data Archive server.
2. Isolate the PI Data Archive server from all incoming process data.
To do this, follow one of these methods:
◦ Shut down PI interfaces on all PI API and PINet nodes.
◦ Disallow all PI API connections at the server. Start piconfig without starting PI Data
Archive. Disregard messages about failure to connect and enter:
@table pifirewall
@mode edit,t
@istr hostmask,value
"*.*.*.*",DISALLOW
Note:
Entries that allow access to specific names or addresses override the DISALLOW
option. Edit all other entries to DISALLOW. Local connections are not affected by
PIFirewall table entries; verify that applications that may write data are not
running.
3. Start the PI Data Archive server with the -base parameter. This ensures that PI Data
Archive starts up with only the minimum required subsystems. Enter the command:
pisrvstart.bat -base
4. Use piartool -acd to create and register one or more archive files for the backfilling
period. You can also use the Archives tool in PI SMT to create multiple files for backfilling.
For more information, see Create multiple archives for backfilling.
5. If the Snapshot_DoNotReplacePTCreatedOnOOO parameter is enabled, delete all the Pt
Created events from the snapshot. For more information, see Clear the Pt Created
snapshot.
6. Depending on whether you are using compression, do one of the following:
◦ To backfill with compression, send the source data in time-sequential order with the
oldest data first.
Note:
Make sure that data sources are not writing to any points that are being backfilled.
Otherwise, compression is bypassed for data that is written prior to the snapshot
time.
◦ To backfill without compression, specify the start time as the time stamp of the oldest
data to be backfilled; and specify the end time as the start time of the oldest archive as
listed by piartool -al. The data that you backfill is not compressed, since the start
time of the oldest archive occurs prior to the snapshot time.
If, after backfilling has started, you discover that the backfill archive requires more than 2
TB of disk space, delete the backfill archive and create multiple dynamic archives to store
the data. Divide the target time range between the dynamic archives, and then retry the
data backfilling.
7. If you used the technique of modifying the PIFirewall table in step 2 above, run piconfig to
either change the hostmask value to ALLOW or delete the hostmask.
8. Start the remaining PI Data Archive applications by running pisrvstart.bat without the
-base flag.
3. Use the PI SMT PI Archive Manager tool or the piartool -al command to check your
existing archive files. Note the start time, end time, and filename (including the path) of all
archives within the time range of the backfill data.
4. Back up your PI Data Archive server including all archives that you plan to backfill.
5. Data is compressed by default. If you do not want compression, enable the
Snapshot_DoNotReplacePTCreatedOnOOO tuning parameter.
6. Backfill the data.
Note:
For more information on backfilling data, see "Backfill data with a piconfig script" in
Live Library (https://livelibrary.osisoft.com).
Procedure
1. Create a piconfig script file called gettags.txt. Include the following commands in the
file:
@table pisnap
@select status = Pt Created, tag = *
@ostr tag, time
@output snap_to_delete.txt
@ends
2. Save and close the gettags.txt file.
3. Open a command prompt.
4. Go to the PI\adm directory.
5. Run piconfig, redirecting the previously created script file. (If you used a different path or
filename for your script file, substitute the actual path and file name of your script file for c:
\gettags.txt in the following example.)
Piconfig < c:\gettags.txt
6. Open the snap_to_delete.txt file from the PI\adm directory to verify which points have
Pt Created value in the snapshot. Edit the file to remove any points that you do not plan to
backfill.
7. Save the snap_to_delete.txt file.
8. Run piconfig with the following commands:
@table piarc
@mode edit, t
@istr tag, time
@modi mode = remove
@input snap_to_delete.txt
@ends
Procedure
1. Create a comma-separated text file containing the data.
Format your text file as follows:
◦ One tag value per line.
Each line must include the tag name, time stamp, and value. The time stamp must be in
the format that is shown in the following example:
A1HV074B,08-Aug-89 11:00:00,3659
Note:
For more information about PI time, see "PI time expressions" in Live Library
(https://livelibrary.osisoft.com).
◦ Values from multiple tags can be included in a single file.
◦ Values must be in time order (oldest to newest) for each tag to backfill with compression.
2. If you have a large amount of data, separate the data into smaller files so you can easily
manage and track the backfilling (for example, one day at a time)
3. Add the following piconfig script to the beginning of the file:
@mode edit,t
@table pisnap
@istr tag, time, value
A1HV074B,08-Aug-89 11:00:00,3659
... [followed by the rest of your data]
4. Save the file as a *.csv file, such as data.csv.
5. Test the piconfig script with a small sample of data.
Always run a backfill test with a small amount of data first, and then do the rest of the data.
This way you can verify your piconfig script and make sure that the data is importing
properly. Check the archive and snapshot statistics during the test to see how the backfilling
affects PI Data Archive performance.
Check the archive and snapshot statistics during the test to see how the backfilling affects PI
Data Archive performance.
6. Force an archive shift to avoid backfilling into a primary archive if you are backfilling on a
production system. The easiest way to do this is with the PI SMT Archive Editor plug-in.
7. Open a command prompt window.
8. Change to the PI\adm directory.
9. Run piconfig and redirect your previously prepared data file. Substitute the actual path
and file name of your prepared text file for c:\tags\data.csv in the example below:
piconfig < c:\tags\data.csv
10. Verify your data using DataLink or ProcessBook.
• The input archive’s integrity is checked prior to being used. To disable this behavior, use the
–noinputcheck option.
• By default, the offline archive utility creates dynamic archives. To specify a fixed archive, use
the -f option.
Note:
Dynamic archives become non-shiftable once a single overflow record is generated,
but remain shiftable if no overflow records are generated.
• You can run the offline archive utility while PI Data Archive including PI Archive Subsystem
is running. At a minimum, the PI Network Manager, PI Base Subsystem, and PI Snapshot
Subsystem must be running, because the utility needs to access the PI point database during
offline operations.
Procedure
1. At a command prompt, go to the PI\adm directory.
2. Type the following command:
pidiag -ahd path
where path is the path to the unregistered archive.
For example:
pidiag -ahd d:\pi\dat\piarch.001
The output is similar to the output from the piartool -al command for a single archive
file:
D:\PI\adm>pidiag -ahd d:\pi\dat\piarch.001
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 129 $]::
Version: 8 Path: D:\PI\dat\piarch.001
State: 3 Type: 0 (fixed) Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 27.9
Offsets: Primary: 1837/65536 Overflow: 106950/131072
Annotations: 1/65535 Annotation File Size: 2064
Start Time: 16-Aug-09 23:08:12
End Time: Current Time
Backup Time: 25-Aug-09 14:26:11
Last Modified: 24-Sep-09 14:31:27
Procedure
1. At a command prompt, go to the PI\bin directory
2. Type the following command:
piarchss -if inputPath -of outputPath
where inputPath is the full path (including file name) of the input archive file and
outputPath is the full path (including file name) of output archive file.
Results
The offline archive utility takes the input file, processes it according to the command
parameters, and then outputs the processed file to the specified location. The offline archive
utility does not modify the input file under any circumstances.
file that maps the source archive point ID into the target system point ID. When you specify an
ID conversion file, the offline archive utility processes and converts points included in the file.
Always use this option when bringing an archive file from another PI Data Archive server.
Create the binary file from an input text with the -idci option:
piarchss -idci ID_conversion_input_file -idco ID_conversion_binary_file
The ID_conversion_input_file is the full path and file name for the input text file.
The ID_conversion_binary_file is the full path and name for the binary file to be created.
The offline archive utility reports any point in the input file that does not exist in the target
system.
Time ranges
You can specify the time range of the records that the offline archive utility processes, and you
can specify the start time and end time of the output file that the offline archive utility
produces.
Time filters
To process events that occurred during a specific time period, use a filter flag with piarchss.
• -filter
Specifies the period between the start time and end time, and includes both the start time
and end time. The offline archive utility discards events outside this range. The usage is:
piarchss -filter starttime endtime
• -filter_ex
Specifies the period between the start time and end time, and includes the start time but
excludes the end time. The offline archive utility discards events outside this range. The
usage is:
piarchss -filter_ex starttime endtime
For both flags, the start time must be before the end time.
Option Description
input Sets the start time to the start time of the input file. This is the default
behavior.
event Sets the start time to the time of the first event in the input file.
time Sets the start time to the specified time string. The following rules apply:
• Specify times in fixed or reference PI time format. Time offsets are not
supported.
• Enclose times that contain spaces in double quotes.
• If only a date is specified, the time defaults to 00:00:00 (midnight).
• Output file start and end times must differ by at least one second.
Example time strings:
"22-JAN-17 23:59:59"
23-JAN-17
21-Feb
NFE Sets the start time to the time of the first event that passes the time filter.
Example
For example, the following command specifies the output archive start and end times.
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\january.dat
-filter_ex "1-jan-02" "1-Feb-02" -ost "1-jan-02" -oet "1-feb-02"
Note:
If the start or end time contains a space, for example 1-Jan-02 12:00:00, you must
enclose the date string in double quotes.
Option Description
NFE Sets the end time to time of last event which passes the time filter.
primary Sets the end time to indicate the archive is a primary archive.
NoChange End time is not altered.
Example
For example, the following command specifies the output archive start and end times.
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\january.dat
-filter_ex "1-jan-02" "1-Feb-02" -ost "1-jan-02" -oet "1-feb-02"
Note:
If the start or end time contains a space, for example 1-Jan-02 12:00:00, you must
enclose the date string in double quotes.
The optional -tfixend parameter allows you to specify a time stamp after which no time
stamp corrections are performed. For example, the following combination of -tfix and -
tfixend specifies to perform the time stamp corrections specified in the file
conversion_file.txt and to not modify any event time stamps at or after 13:00:00 January
1, 2010:
-tfix conversion_file.txt -tfixend "1-jan-2010 13:00:00"
StartTime can be expressed as UTC - seconds since 1/1/70 or as PI local time-stamp string.
UTC time stamps and strings cannot be intermingled, the first format is assumed for all
entries.
Offset is a number of seconds added to the time stamp of every event within the time range.
Fractional seconds are not supported. Offset applies from time stamp up to, but not
including, the next time stamp.
01-Jan-70 00:00:00,3600
01-Jan-30 00:00:00,3600
Apply a missed DST conversion to an archive that covers the summer of 2016:
01-Jan-16 00:00:00,0
13-Mar-16 02:00:00,3600
06-Nov-16 02:00:00,0
31-Dec-16 23:59:59,0
Apply the time adjustments for each time period as a series of UTC values and offsets:
814953600,-61200
828871200,-57600
846403200,-61200
860320800,-57600
In this example, bigfile.dat does not exist prior to the operation. The first session creates
the file and the second and third sessions add events to the file. By default, the utility creates
the file as a dynamic archive. After you create the file, you can register the archive and PI
Snapshot Subsystem can add events to the archive file.
Any of the three input files that were registered prior to the operation are unregistered during
the operation. When the operation is complete, you can register them again. Dynamic archives,
which are the default type created by the offline utility, are not shiftable.
You can move the output file's end time forward as required, but you cannot change the start
time after creation.
Archives with an unknown end time should be processed into a new archive to determine the
actual end time. The resulting archive can then be merged chronologically. Merging a series of
archives with overlapping dates requires processing the archive with the oldest start time first,
then process the remaining in chronological order based on the archive end times.
For more information about using the piarchss utility, see Offline archive utility command-
line options and Run the offline archive utility.
In this example, january.dat and february.dat do not exist prior to the operation. The
offline archive utility creates them as dynamic archives by default. After the offline archive
utility creates the files, you can register them with piartool -ar, and then add events to the
archive files in the usual way. Because these output archives are dynamic archives, they are not
shiftable.
The filter_ex option specifies the period between the start time and end time, and includes
the start time but excludes the end time.
The output archive start and end times are explicitly specified.
Note:
If the start or end time contains a space, for example 1-Jan-02 12:00:00, you must
enclose the date string in double quotes.
Excluding the -ost and -oet flags results in the default behavior. For more details, see Specify
a start time for the output file and Specify an end time for the output file.
If the input file was registered prior to the operation, it will be unregistered during the
operation. When the operation is complete, you can use piartool -ar to register the file
again.
For more information about using the piarchss utility, see Offline archive utility command-
line options and Run the offline archive utility.
For more information about using the piartool utility, see "piartool command-line options" in
Live Library (https://livelibrary.osisoft.com).
For information about avoiding duplicate events when you split an archive, see the OSIsoft
Knowledge Base article, How to avoid duplicate events at the archive boundary when splitting
a PI archive (https://customers.osisoft.com/s/knowledgearticle?
knowledgeArticleUrl=KB00590).
Security overview
PI Server security configuration has these main components:
Manage authentication
The following authentication methods are listed in order from most secure to least secure (not
recommended).
Before PI Data Archive 2016 R2, trusts were typically used to authenticate PI interfaces, while
mappings were used for single sign-on for Windows users on PI Data Archive servers. With PI
API 2016 for Windows Integrated Security, Windows authentication extends to PI interfaces.
OSIsoft does not recommend using PI trusts or explicit logins for authentication. For a more
secure environment, OSIsoft recommends Windows Integrated Security.
Note:
PI API 2016 for Windows Integrated Security extends Windows authentication to API-
based client applications. If you choose to install PI API 2016 for Windows Integrated
Security, you can use only Windows Integrated Security for authentication. Both trusts
and explicit logins will fail. For more information, see "Security configuration" in Live
Library (https://livelibrary.osisoft.com).
• PI Trusts
PI trusts allow applications to access PI Server without typing in a user name and password.
Do not use PI trusts for applications that support Windows authentication.
• Mapping management
• Manage PI identities in SMT
• On upgraded systems, you might have legacy users and groups that you need to use in
mappings (Manage PI Data Archive user accounts and groups)
For fundamental instructions on planning and implementing this type of configuration, see the
PI Data Archive Security Configuration Guide.
Mapping management
A mapping creates an association between an entity on Windows (such as an AD group) with
an entity on PI Data Archive (such as a PI identity).
You can create, delete and edit mappings using the PI SMT Mappings & Trusts tool.
Procedure
1. In the Collectives and Servers pane, select the server or collective.
2. In the System Management Tools pane, select Security > Mappings and Trusts.
3. Select the Mappings tab.
4. In the toolbar, click the New button to open the Add New Mapping dialog box.
5. In Windows Account, enter an AD principal or a local Windows group or user. To select the
account either:
◦ Click the browse button to browse for the account.
◦ Type the account name, then click the resolve SID button to verify that this is a valid
account. If the account is valid, an SID appears in the field. Otherwise, a dialog box with
an error message opens.
6. In Description, enter a description of the mapping. There are no restrictions on the contents
of this field, and the field is optional.
7. In Server, choose the server where you want to create the mapping. This drop-down list
contains all the PI Data Archive servers that are selected under Collectives and Servers and
that are version 3.4.380 or later versions. Earlier versions of PI Data Archive do not support
mappings.
8. In PI Identity, enter a PI identity, group, or user.
To choose, click the browse button and open the Select PI Identity, PI Group, or PI User
dialog box. Make a choice in Type to filter the choices. In the list, choose either a PI identity,
a PI group, or a PI user, and then click OK.
OSIsoft recommends choosing a PI identity. PI users and PI groups represent an older
security model that involves managing individual user accounts on PI Data Archive. PI user
accounts and passwords are not as secure as Windows accounts.
9. Click OK to create the mapping.
Note:
If you are not connected to one or more PI Data Archive servers of version 3.4.380 or
later, then the Identities tab does not appear.
Create a trust
Procedure
1. Under Servers (or if you have a collective deployment, Collectives and Servers), select the
server.
2. Under System Management Tools, select Security > Mappings & Trusts.
The Mappings & Trusts tool appears.
3. Select the Trusts tab.
4. Click the New button to open the Add Trust Wizard.
5. Select the PI Data Archive server name and enter a name for the trust (and, optionally, a
description). Click Next.
◦ Application Name
This is slightly different for PI API and PI SDK connections.
▪ API
Connecting PI API applications send an identifier called an application process name,
or procname. This is a four-character string with an E appended (for example, the
procname for the Perfmon interface is PIPeE).
▪ SDK
The full name of the connecting application, including the extension, but not the path
(for example, PI-ICU.exe).
◦ IP Address
The IP address of the interface node.
◦ Net Mask
The net mask for the interface node (for example, 255.255.255.255).
For SDK connections only, you also have the following optional fields:
◦ Windows Domain
The Windows domain of the user who runs the application (for example, osi).
◦ Windows Account
The Windows user name of the user who runs the application (for example, my_account).
8. Select the PI identity that you want to use for this trust.
Applications authenticated through this trust have all the access permissions granted to this
PI identity. Alternatively, you can select a PI group or a PI user for this step.
• PI API connection: Most PI interfaces use the PI API to connect to PI Data Archive.
• PI SDK connection: Most client applications use PI SDK to connect to PI Data Archive.
The PI API and PI SDK connections both support Windows authentication, which is the most
secure authentication method available for the PI Data Archive server. OSIsoft recommends
that you always use Windows authentication when possible.
If you are not sure which connection type an interface uses, then consult the documentation for
that interface.
• Applications that connect through the API send an identifier called an application process
name, or procname. This is a four-character string with an E appended. For example, the
procname for the Perfmon interface is: PIPeE
Note:
PI API versions before 1.6.0 always send a five-character string: 4 characters plus a
capital E. For PI API versions 1.6.0 and later, the name can be up to 8 characters,
without a trailing capital E.
• For applications that connect through the SDK, use the full name of the connecting
application, including the extension, but not the path. For example, the application name for
PI ICU is: PI-ICU.exe
If you are running the same PI interface on another PI Data Archive, then you can use PI SMT to
determine the correct application name. Select Operation > Network Manager Statistics. Find
the interface in the list. The application name is listed in the Name field.
IP Information
A PI trust can specify IP information about the computer running the PI interface or client
application for which you are defining the trust. To collect this information, run pidiag -host
on the computer where the interface or client application runs. This returns the connection
credentials as retrieved from the local operating system.
Note:
• Using pidiag -host does not guarantee that you will get the right information. The
results depending on many factors, including the type of interface, the version of the
SDK (if SDK-based), and whether there are firewalls or NAT devices between the
interface computer and the PI Data Archive computer. If you have difficulty configuring
the trust, contact OSIsoft Technical Support.
• When applications run on machines with multiple network cards, you cannot predict
which credentials the application will send to PI Data Archive for the trust
authorization. OSIsoft thus recommends that you either avoid such configurations or
create a PI trust for every IP address on the machine where the application runs.
• Windows Domain
The Windows domain of the user who runs the application.
• Windows Account
The Windows user name of the user who runs the application.
Default trusts
PI Data Archive includes default trusts that guarantee access to all applications running on the
local machine. These default trusts are automatically recreated every time the system starts, to
ensure that they are always configured in their default state. Different versions of PI Data
Archive have different default trusts. The following list includes default trusts for PI Server
3.4.375 and later.
Trust name Description PI Data Archive version
!Proxy_127! Allows access for local PI System All versions
applications.
PI Data Archive versions 3.4.380 and later do not need the FQDN trust and it is not included in
new installations. However, that trust is not removed if PI Data Archive is upgraded from an
earlier version.
You can assign users to one or more PI groups; each PI user has the access permissions defined
for that user, as well as the access permissions defined for all groups to which the user belongs.
PI users and PI groups are essentially legacy components. You can use PI users and PI groups in
trusts and in mappings. However, when you do that, you might create some confusion about
the role of the PI user or the PI group on the server. Do you use these components to manage
actual PI user accounts? Do you use them only for mappings and trusts? Or do you use them for
both? If you are creating a new component to use in a mapping or a trust, use a PI identity to
avoid confusion. For more information, see the OSIsoft YouTube video: watch?v=.
Manage users and groups through the PI SMT Security > Identities, Users, & Groups tool. By
default, the identities, users, and groups for all selected PI Servers appear in separate tabs. See
the PI SMT online Help for instructions on using the tool.
For more information about configuring security, see "Security configuration" in Live Library
(https://livelibrary.osisoft.com).
Manage authorization
Authorization consists of assigning and maintaining the access permissions defined for
resources on PI Data Archive.
You can control access to a wide variety of PI Data Archive resources, including points,
modules, archive configuration, backups, batches, audit trails, and so on.
Although the illustration shows PI identities, you can also define access permissions for PI
users and PI groups. There is no limitation on the number of users or groups. There is no
longer any concept of a resource owner or group, as there was in previous versions of PI Data
Archive.
PI Data Archive stores the settings for each object in an access control list (ACL). Each secure
object on PI Data Archive has an ACL that defines access permissions for that object. The ACL
lists each identity for which access permissions are set on that object. The ACL for the
TEST_POINT data in the illustration above would look like this:
Identity1:A(r,w) | Identity2:A(r,w) | Identity3:A(r) | IdentityN:A(r,w)
Access permissions for each PI identity are separated by a pipe (|) symbol. Each entry consists
of the PI identity name, then a colon (:) followed by the access specifier. The access specifier is
defined in the format: A(r,w). The A in this notation stands for Allow and r,w indicates the
allowed access rights – read and write, in this example.
Each resource has one (and only one) associated group. When a user is not the owner of a
particular PI resource (such as a point or database), PI Data Archive checks to see if the user is
a member of the group that is associated with that resource. If so, then the user gets whatever
access level the group has.
Since each resource has only one associated group, you sometimes need to create additional
groups to give access to all the users who need it. For example, the following figure illustrates
an organization with three groups: Developers, Managers and Operators. One user is a member
of both the Developers and the Managers group.
Suppose that all the users in the Developers and Managers groups need read-write access to a
particular resource, such as the attributes for the Sinusoid point. Because a resource can have
only one associated group, you could create a group called DevMan that contains all the
developers and all the managers and then associate that resource with the new group.
Typically, you create different PI groups for groups in your organization that need different
point access.
PI access levels
PI Server provides these standard levels of access permissions:
• Read-only access. Users can view the item, but they cannot edit it.
• Read-write access. Users can view and edit the item.
• No access. Users cannot view or edit the item.
Note:
No access is not the same as deny. There is no level for deny, as there is in Windows.
You can have different access permissions for a point's attributes than for the point's data. For
example, a user might be allowed to edit a point's data, but not to edit that point's attributes.
• Data Security
To view and edit point data, you also need read access to point security. If users do not have
permission to view a point's attributes, they cannot see that point's data, in most cases.
(This is because client applications need access to the point attributes in order to get the
data.)
• Point Security
To view point attributes, you need read access to PIPOINT, and read access to the point
security for the point itself. Similarly, to edit a point's attributes, you need read/write access
to PIPOINT, and read/write access to the configuration for the point itself.
The following table lists required access permissions for basic tasks.
• For PI Server 3.4.375.99 and earlier versions, the interface shows access permissions like
this:
Choose an owner and group, then specify the owner, group, and world access. See Servers
earlier than 3.4 for more information about this access permission model.
• For PI Data Archive 3.4.380 and later, the interface shows access permissions like this:
Select a PI identity, user, or group and then specify the read/write access permissions. See
Servers 3.4.380 and later for more information about this access permission model.
• PI SMT version 3.3.1.3 or later (includes Point Builder, Module Database tool, and Database
Security tool)
• PI Builder
• Module Database Builder version 1.2.1.3 or later
• PI ICU 1.4.7 or later
• PI APS 1.2.5.0 or later
Tighten security
This section describes the simple steps you can take to improve security on your PI Data
Archive. This is not a comprehensive list.
Procedure
1. In PI SMT, select a server under Collectives and Servers. You can change settings for only
one PI Data Archive at a time.
2. Open the Security Settings tool (Security > Security Settings.) The Security Settings tool
appears (only for PI Data Archive version 3.4.380 or later).
3. Choose the Blank password not allowed option.
4. Stop and then restart PI Base Subsystem to apply the changes.
Procedure
1. In PI SMT, select a server under Collectives and Servers. You can change settings for only
one PI Data Archive at a time.
2. Open the Security Settings tool (Security > Security Settings.) The Security Settings tool
appears (only for PI Data Archive servers running version 3.4.380 or later).
3. Choose the Explicit login not allowed option.
4. To apply the changes, stop and then restart PI Base Subsystem.
In addition, PI SMT 2015 and PI Collective Manager 2015 have been enhanced for future data
support. PI Audit Viewer also supports the same auditing abilities for future PI points as for
historical PI points.
OSIsoft products that do not support future data
Product Details
PI SDK, PI ACE In its released form, the PI SDK can be used to both read and write values in
the future, but there are limitations with future PI points such as the lack of
Event Pipe support. These limitations restrict the out-of-box support for
future data in PI SDK-based applications like PI ACE. For example, you cannot
use future PI points to naturally trigger PI ACE calculations directly, and the PI
ACE cache may not stay in sync and cannot be trusted to be accurate for
future PI points. PI ACE does offer clock-based calculation triggers, and the PI
ACE cache can be disabled globally, but these limitations may be too severe.
PI Performance Future PI points cannot be used as output, input, or trigger tags for
Equation Scheduler PIPESCHD.
(PIPESCHD)
PI EFGen PI EFGen cannot be used to trigger event frames for future PI points.
Future PI points
PI Data Archive 2015 provides a new point attribute called "future" that you can enable for a
new PI point intended to store future data. The “future” attribute is a part of all point classes,
including “base” and “classic”. PI points that do not have this attribute turned on, referred to as
"historical" PI points, will reject data with time stamps that are greater than 10 minutes
beyond current time. The future attribute of a PI point cannot be modified after the PI point
has been created; therefore, existing historical PI points cannot be converted to future PI
points. Additionally, the future attribute of a PI point is disabled (set to '0') by default because
it is anticipated that most new PI points are created to store real-time or continuous historical
data.
Choosing between historical or future PI points is a key decision that depends on whether the
data that must be stored is real-time data, that is, from sensors collecting continuous
measurements, or data that may not be close to current time or may be frequently revised (for
example, forecasts or predictions). Such critical distinction in stored values is unlikely to
change in the life of a PI point.
Caution:
Although future PI points can store data with both future and past time stamps, OSIsoft
strongly recommends against mixing predicted and measured data in the same PI point.
Use future PI points for forecast data and historical PI points for actual or measured data.
• PI Vision, or PI Coresight 2015 to 2016 R2. For more details, see the "PI Vision
documentation" in Live Library (https://livelibrary.osisoft.com) or "PI Coresight
documentation" in Live Library (https://livelibrary.osisoft.com).
• PI DataLink 2015 or later. For more details, see the "PI Datalink documentation" in Live
Library (https://livelibrary.osisoft.com).
• PI ProcessBook 2015 or later. For more details, see the "PI ProcessBook documentation" in
Live Library (https://livelibrary.osisoft.com).
• PI SMT 2015 or later. You must specify the PI point and an appropriate time range if you are
using the Archive Editor. If using Current Values, you may need to manually refresh the
Current Values to see updated values for future PI points.
Future archives
Creating future archives
To manage future data that is not continuous or sequential like real-time historical PI point
data, PI Data Archive uses separate archives called "future archives" that are created
automatically. Future archives have pre-determined time ranges and are created only when
data is received. Every future archive has an initial size of 1 MB, grows dynamically, and has a
time range always bound to one calendar month. For example, if a new PI value comes in on
January 7th at 08:00 AM and an archive file does not already exist for the month of January, PI
Data Archive creates one automatically. Future archives are optimized for non-sequential data
unlike real-time data stored in "historical" archives. Historical and future archives can be
managed independently based on your specific needs for data retention, availability,
performance, and reliability.
Data in future archives is never mixed or interchanged with data in historical archives. When
time passes and forecasted data moves into the past, it is still stored in the same future
archives; PI Data Archive does not discard or move the data.
In rare situations, you may want to manually create and register future archives because either
the initial size or the duration are not desirable. The automatic algorithm will fill in any “gaps”
before and after all existing future archives, and re-align new archives to calendar-month
duration. For example, if you manually create a future archive from 11:00 AM on January 7th to
09:00 AM on January 14th, PI Data Archive automatically creates an archive file from 12:00 AM
on January 1st to 11:00 AM on January 7th and a second archive file from 09:00 AM on January
14th to 12:00 AM on February 1st. PI Data Archive only creates these adjacent archives if data
is actually received for both of those time ranges.
Archive administration
You can manage historical and future archives by using the PI SMT Archives plug-in or
command-line utilities.
• Command-line utilities
Most command-line tools take an extra parameter: -hist or -future. This parameter
restricts a command to perform its action against the specified PI point or archive. For
example, consider the piartool command for listing archives:
Use piartool -al to list all archives.
Use piartool -al -hist to list only archives relevant to historical tags.
Use piartool -al -future to list only archives relevant to future tags.
Procedure
1. Verify your PI Server installation. See Weather example: Verify PI Server installation for
more information.
2. Create historical PI points for past weather data and future PI points for predicted weather
data. Populate the PI points with weather data collected from a public source. Weather
example: Create and populate PI points with weather data
3. Set up an AF element template and associated attribute templates that get their values from
configured historical and future PI points. Then create PI AF elements for several
geographical locations. See Weather example: Create PI AF elements and attributes
4. Using PI Vision or PI ProcessBook 2015 or later, generate trends over a specific time period
to see historical versus predicted trends for a particular weather attribute. Weather
example: Create trends and analyze data
Procedure
1. Verify that you have installed PI Server 2015 or later. PI Server includes PI Data Archive and
PI AF.
2. Verify that you have installed the latest version of a client tool such as PI Vision or PI
ProcessBook 2015 or later.
3. Start a PI Data Archive and a PI AF server.
Procedure
1. Navigate to World Weather Online Developer Portal (http://
developer.worldweatheronline.com).
2. Select the Free Weather API service.
3. Select "Get local weather". Enter the zip code of the location you wish to monitor, and select
a CSV file as output. You can select other options such as number of forecast days, time
intervals of forecasts and so on.
4. Load the CSV file into Excel.
5. Select the columns that are of interest to you, and using PI DataLink, create a table of
predicted PI point attribute values and time stamps. You may also have PI point attributes
for historical data such as "Current Temperature", which you can later compare with
"Predicted Temperature" data.
6. Configure your PI Data Archive with your weather PI points and values.
Note:
To extend this model to many thousands of locations, use PI Builder to configure your
PI points.
Procedure
1. Using PI System Explorer, create an element template called WeatherByLocation with
weather attributes such as:
◦ Current Temperature
◦ Predicted Temperature
◦ Predicted Precipitation
◦ Predicted WindDirection
◦ Predicted WindSpeed
◦ Sunlight
◦ Predicted Weather
2. Assign appropriate value types to the various element attributes such as "degree
Fahrenheit" for Predicted Temperature or "percent" for Predicted Precipitation.
You can effectively use the "enumerated set" type, for example, to configure an enumerated
set of weather codes for Predicted weather such as:
◦ 113
Sunny
◦ 116
Partly Cloudy
◦ 122
Overcast
Similarly, you can configure an enumerated set of directions on a 16-point compass for the
"Predicted wind direction" attribute.
3.
Note:
You must have created PI points corresponding to the weather attributes before
embarking on this step.
Create data references for each attribute. Link historical PI point attributes like "Current
Temperature" to the corresponding historical PI point, and future PI point attributes like
"Predicted Temperature" to the corresponding future PI point.
4. Create a few elements from the WeatherByLocation element template. The elements should
correspond to the geographical locations where you want to monitor predicted weather
conditions.
Procedure
1. In PI Vision, create a trend for the Current Temperature and Predicted Temperature
for a single location.
Select your start and end time to be relative to current time. The "now" line remains visible
if you have chosen a relative time range that straddles current time, such as *-2h to *+2h.
Trend cursors set for a future time show values for future PI points, but historical PI points
show No data.
2. You can use values from future PI points as inputs for your analyses.
For example, you can calculate the difference between Predicted Temperature and
Current Temperature and write it to an output attribute called DeltaTemperature, and
trend the DeltaTemperature values to see how closely your prediction matches actual
recorded values.
You may also trigger an event based on DeltaTemperature reaching a particular value.
PI interface utilities
• UniInt is an OSIsoft framework for interface development that provides interfaces with a
consistent feature set and behavior.
Interface maintenance
After you install and configure a PI interface, you can typically leave it running indefinitely
without any intervention. If you perform software upgrades or security patches, or if the
network infrastructure changes, you might need to perform a few basic tasks such as
authenticating your interface, configuring a trust, registering the ICU and setting up buffering.
Refer to your interface documentation for more information.
Note:
Starting with PI Server 2018 SP3, the Random and Ramp Soak interfaces are no longer
installed with PI Server. Optionally, you can install them by using separate install kits, the
PI Interface for Ramp Soak Simulator Data install kit and the PI Interface for Random
Simulator Data kit. For upgrades, older versions of Random and Ramp Soak will remain
and continue to retrieve data.
When the install kits are installed and running, the following default points will be
created:
• BA:ACTIVE.1
• CONC.1
• BA:LEVEL.1BA:PHASE.1
• BA:PHASE.1
• BA:TEMP.1
• CDEP158
• CDM158
• CDT158
• SINUSOID
• SINUSOIDU
Procedure
1. Click Start > Control Panel > Administrative Tools > Services
2. In the Services window, find the interface that you want to start or stop. For example, PI
Random Simulator (random) Interface X64.
3. Right-click the interface service and choose Start or Stop.
This table lists only a subset of the PI performance counters. For a comprehensive list, see the
PI Server topic "PI Performance counters" in Live Library (https://livelibrary.osisoft.com).
Procedure
1. To start PI SMT, select Start > All Programs > PI System > PI System Management Tools.
2. Select the PI Data Archive server on which you want to create the performance points.
3. Expand IT Points and select Performance Counters.
4. On the Tag Settings tab, select an existing PI Performance Monitor interface.
If no interface appears in the list, make sure PIPerfmon is installed and running on the PI
Data Archive server. You configure PIPerfmon by using PI Interface Configuration Utility
(ICU). For more information, see "Installing and configuring the PI PerfMon interface" in
Live Library (https://livelibrary.osisoft.com).
5. Click the Build Tags tab and select the performance monitor points you want to create from
the list of available counters. See Which performance counters to monitor.
6. Click Create Tags to create the performance monitor points.
You can also create notifications in PI Asset Framework to receive emails when any of the
performance counters indicate a problem. In order to do so, you need to install PI Asset
Framework and may have to first configure analyses and event frames. For more information,
see PI Server topic "Configuration of notification rules for analyses or event frames" in Live
Library (https://livelibrary.osisoft.com).
PI System messages
All PI Data Archive processes send messages to the PI Message Subsystem, which writes
messages to the PI message log. Various tools and utilities can query the message log. The PI
message definition file contains message IDs and definitions.
Procedure
1. Run PI SMT.
2. Select Operation > Message Logs.
Message structure
Messages contain the following information:
• Severity
One of the following severity levels (pigetmsg shows the severity level in a single-letter
code):
◦ Critical (C)
◦ Error (E)
◦ Warning (W)
◦ Information (I)
◦ Debug (D)
• Time stamp
The time when the component wrote the message.
• Source
The component that wrote the message.
• Message ID
The unique identifier of a particular message type.
• Text
The message text, which describes the event.
For example:
Severity levels
Severity level Description
Critical Loss of system functionality. Requires immediate attention.
Error Action failed.
Warning An anomaly occurred that does not impact the user.
Information Information about the action, such as a successful or unsuccessful login.
Debug Debug/tracing message.
In messages, the leading character indicates the severity level. For example:
• Critical
C 23-Jul-08 09:27:46.243 piarchss:piarcmgr (2050)
>> Primary archive file failed to load or has invalid dates. Archiving will
be turned off.
• Error
E 23-Jul-08 09:27:46.243 piarchss:piarcmgr (2049)
>> Failed to load archive file F:\PI archives\8-Sep-04_14-Sep-04: [3] The
system cannot find the path specified.
• Warning
W 23-Jul-08 09:41:32.733 piarchss:pievqreader (6012)
>> Invalid queue creation path "E:\PI\dat\", using default location
• Information
I 29-Jul-08 18:31:53.211 pinetmgr (7039)
>> Connection accepted: Process name: pigetmsg(6260) ID: 3
• Debug
D 29-Jul-08 15:22:59.421 pibackup (5136)
>> PIvsswriter::OnFreeze. succeeded
where errorcode is the error number displayed in the message log. Error code values may be
positive or negative.
For example, if the error code is -11137, enter:
pidiag -e -11137
You can also use the pidiag utility to translate operating system error codes, which are always
positive numbers.
If an RPC is made to a subsystem that is marked offline, you will see this message:
[–10733] PINET: RPC Resolver is Off–Line
The output will include details if only the first part of a message was retrieved. In this example,
the message contains the message length. However, a timeout occurred when pinetmgr
attempted to retrieve the rest of the message:
>> Deleting connection: pisnapss, Connection lost(1),
[-10731] PINET: incomplete message
Backups Verify that scheduled backups have been PI SMT: Operation > See PI Data Archive
running and that you have sufficient disk Backups backups
space for future backups.
piartool -al
IO rate counters I/O rate points monitor the flow of PI DataLink or PI ProcessBook
data from an interface. Every 10
minutes, each IO-rate point registers
the 10-minute average data transfer
rate to PI Server in events/second. If
the value stops updating in PI, the
interface may have stopped collecting
data.
Monthly
Component Task Tools
License limits and usage Perform monthly usage statistics and PI SMT: Operation > Licensing
point count checks for your PI System
piartool -lic
to anticipate license increase needs.
As Needed
Component Task Tools
PI point data Make sure PI point data references PI SMT: Data > Current Values
are updating.
pisnap.bat
pisnap.sh
Client connections If you are having client data flow PI SMT: Operation > Update Manager
issues, verify client connections to PI
pilistupd
Data Archive.
Connection history
PI Data Archive stores the history of connections from clients, interfaces, and other
applications. This history is stored on your local computer, and data is kept for 1 year, by
default. You can access this data to count client connections and associated information for
specified time periods, and optionally write the information to a file.
Use the pidiag command to retrieve connection history information, including
• IP address
• Name of the executable of the connecting application (product)
• Time the connection started
• Time the connection ended (if already disconnected)
• License information
To see information about pidiag command options for customizing your query, see the PI
Data Archive reference topic "Connection history information" in Live Library (https://
livelibrary.osisoft.com). For example, the following command returns information about
connections during a specified time range. It shows unique product connections between
March 30th, 2017, at 10:50 AM and March 31st, 2017, at 10:50 AM
pidiag -connectionhistory -u -s "30-Mar-17 10:50:00" -e "31-Mar-17 10:50:00"
Start time: 30-Mar-17 10:50:00
End time: 31-Mar-17 10:50:00
Product Number of node IPs Node IP address[es]
PI-IN-OS-RMP 1 127.0.0.1
pibasess 1 127.0.0.1
pimsgss 1 127.0.0.1
piarchss 1 127.0.0.1
PIPC Log Server 1 127.0.0.1
Number of unique products: 5
Procedure
1. Defragment the drive; run both the analysis and the defragmentation processes.
Note:
The archive files that are registered with the PI Data Archive server are analyzed but
not defragmented, because they are locked.
2. Use the fragmentation report to identify archive files that are highly fragmented.
3. Reprocess those archive files, online.
For more information, see Archive reprocessing.
Procedure
1. In the Collectives and Servers pane, select the PI Data Archive server on which you want to
add the parameter.
2. Clear the check boxes for all other PI Data Archive servers.
3. On the toolbar, click the New Parameter icon ( ).
4. In Parameter name, select the parameter that you want to add to the list. If you know the
name, you can enter it exactly.
5. Optional: Enter a value for the tuning parameter.
6. Click OK. The parameter is added to the list.
7. Stop and restart the PI Data Archive server or the subsystem associated with the updated
parameter.
Troubleshooting checklist
To troubleshoot issues, complete the steps in this checklist. If you have not resolved the
problem when you finish these steps, contact OSIsoft Customer Portal Contact Us page
(https://customers.osisoft.com/s/contactus).
Procedure
1. Look for error messages. If you know the specific error message, search the Technical
Support site for that error. If you do not yet have a specific error message, look at the
message logs on the server and client node. For server messages, use the Message Log tool
in PI SMT. Filter messages for a severity of Error and greater. See Severity levels.
You cannot look at a client node message log remotely. Run PI SMT directly on the client
node or use pigetmsg. For interface issues, examine the pipc\dat\pipc.log files directly
on the interface node. If this is a setup problem, look at the setup logs in the 32-bit pipc
\dat directory.
To get a text description for an error number, use:
pidiag -e errornumber
For more information on error messages, see PI System messages. For information about
pigetmsg, see the PI Data Archive Reference Guide.
2. Determine which computers exhibit the problem:
◦ Client computers
◦ Server computers
◦ Interface computers
To isolate the computers, run the questionable system against a system that is functioning
correctly and review the results.
◦ A network problem is likely if all computers exhibit the malfunction.
◦ A server problem is indicated if the malfunction occurs on all clients.
◦ A hardware or networking problem is likely if the applications that malfunction do not
use the PI System. Run telnet to further isolate the problem. If telnet works, then the
network is not likely the problem, although it might be a network issue such as DNS or
firewall blocking.
3. If this is a client problem, do the following:
8. Each PI System is distributed with a standard set of points including sinusoid, cdep158, and
cdm158.
Note:
Starting with PI Server 2018 SP3, the Random and Ramp Soak interfaces are no longer
installed with PI Server. Optionally, you can install them by using separate install kits,
the PI Interface for Ramp Soak Simulator Data install kit and the PI Interface for
Random Simulator Data kit. For upgrades, older versions of Random and Ramp Soak
will remain and continue to retrieve data.
When the install kits are installed and running, the following default points will be
created:
◦ BA:ACTIVE.1
◦ CONC.1
◦ BA:LEVEL.1BA:PHASE.1
◦ BA:PHASE.1
◦ BA:TEMP.1
◦ CDEP158
◦ CDM158
◦ CDT158
◦ SINUSOID
◦ SINUSOIDU
9. To troubleshoot backups, see PI Data Archive backups.
10. To troubleshoot PI collectives, use Collective Manager to check the status of all members.
Then, use piconfig < pisysdump.dif:
◦ isavailable should be 1 for all members
◦ lastsynctime indicates the last successful communication
◦ role should be 1 for a primary and 2 for a secondary
11. If the problem is with interfaces, try the following:
◦ Run an interface with only one point.
◦ Run the interface interactively.
◦ Run the interface without buffering. When running interactively you will most likely be
using a different account, so security can affect your results.
◦ Determine if the problem is with all points on all interfaces or just a few points on some
interfaces.
◦ Verify that authentication is configured for the node or interface.
◦ Check the PI Firewall database.
◦ Check the individual interface log files, if any; also check the PI Message Log on the
interface node. Use the pigetmsg utility, located in the pipc\adm folder, to check
messages in this file.
◦ If an API interface is not able to connect, try to connect with apisnap.
◦ Make sure the SDK can connect using the AboutPI-SDK utility.
◦ Run as the System Administrator. If the issue goes away, then you have a permission
issue.
◦ If this is the OPC interface, check DCOM settings. The settings are documented in the OPC
Interface Manual.
To list all processes that run as services, enter at the command prompt:
net start
If you are running a PI Data Archive process or interface interactively, that process has a
separate command window labeled with the process name.
PI Archive Subsystem
Run the piartool –al (archive listing), piartool –as (archive statistics), and pisnap
commands to test PI Archive Subsystem. If PI Archive Subsystem (piarchss) is not working
correctly, you will see:
C:\PI\adm>piartool -al
Getarchivefilelist Failed: [-10733] PINET: RPC Resolver is Off-Line.
C:\PI\adm>piartool -as
Getarcmemtablestatistics Failed: [-10733] PINET: RPC Resolver is Off-Line.
C:\PI\adm>pisnap
C:\PI\adm>apisnap localhost:5450
Snapshot value
Value = ERROR ERROR
Status = ERROR
Archive events are queued when PI Archive Subsystem is not operating correctly. Use the
piartool -qs command to view the event queue count.
PI Base Subsystem
Run the pisnap and piconfig utilities to test PI Base Subsystem. If PI Base Subsystem is not
working correctly, you will see:
C:\PI\adm>apisnap localhost:5450
PI License Manager
PI License Manager, pilicmgr, provides license services for PI programs including
subsystems, client applications, and interfaces. For example, PI Archive Subsystem registers
with PI License Manager to obtain a valid license. If it fails to get its license, it may not operate
properly.
Run the piartool -lic usage command to test PI License Manager. If pilicmgr is not
working correctly, you will see:
C:\PI\adm>piartool -lic usage
Continue after failure to register with License Manager. [-10733] PINET: RPC
Resolver is Off-Line.
PI Snapshot Subsystem
Run the piartool -ss and pisnap commands to test PI Snapshot Subsystem. If PI Snapshot
Subsystem is not working correctly, you will see:
C:\PI\adm>piartool -ss
Getsnaptablestatistics Failed: [-10733] PINET: RPC Resolver is Off-Line.
C:\PI\adm>pisnap
C:\PI\adm>apisnap localhost:5450
Snapshot value
Value = ERROR ERROR
Status = ERROR
1. pinetmgr
2. pimsgss
3. pilicmgr
4. piupdmgr
5. pibasess
6. pisnapss
7. piarchss
Connection checking
For information about connections, look at the Network Manager statistics. You can see these
in the PI SMT Network Manager Statistics tool (select Operation > Network Manager
Statistics). The pinetmgr process manages the remote procedure calls (RPCs) that PI Data
Archive subsystems and processes use to communicate with each other.
For example, if PI Snapshot Subsystem (pisnapss) sends an event to PI Archive Subsystem
(piarchss) for storage, the communication flows from pisnapss to pinetmgr to piarchss.
If PI Archive Subsystem writes a message to the System Message Log, the communication flows
from piarchss to pinetmgr to pimsgss.
The Network Manager Statistics tool shows a lot of information. Check for the following:
• In the BytesSent and BytesRecv columns, identify applications that are requesting or
sending unusual amounts of data. If the value for an application or interface is large
compared to other applications or interfaces of that type, then that might point to the
problem connection. (Values in the BytesSent and BytesRecv columns from PINetMgr are
always the highest.)
• What client processes are connected from which nodes.
• How long clients have been connected.
• In the RegAppType column, determine what type of application is connecting:
◦ OSISDKApp indicates an SDK application.
◦ OSIinterface indicates an interface.
• In the ProtocolVersion column, determine whether the connection is from an SDK or API
application. A version number of 1.x indicates an API application. A version number of 3.x
indicates an SDK application.
Specific issues
Topics in this section
• PI ProcessBook trend flatlines
• Issues with COM connectors
• Pending update limit
Procedure
1. Determine if only one or more specific points are affected. Check another trend in PI
ProcessBook to see if the issue is limited to only some points. If the issue involves multiple
points, go to step 2. If the issue involves only one point, go to step 4.
2. Try retrieving the data from the archive by closing and reopening the trend window. If the
trends appear normal, the issue may be in the update sign-up. Go to step 3. If the trends still
show no data, go to step 4.
3. If no tags are producing trends, run the PI SMT tool Operation > Update Manager and check
if PI ProcessBook is not being signed up for updates.
4. To determine whether the issue is with PI Data Archive or with the client application, view
the pending numbers in the results. Pending numbers represent the number of events
queued and not yet retrieved by the client such as PI ProcessBook. If data is not arriving
from the data source, the pending number remains at 0. If the client PI ProcessBook is not
retrieving the updates, the pending number continually grows and does not shrink.
5. If the pending updates are growing, restart the PI System. If this does not fix the issue,
contact OSIsoft Customer Portal Contact Us page (https://customers.osisoft.com/s/
contactus) for additional assistance. If the pending updates remain zero, go to step 4.
6. If all the points are signed up for updates and refreshing the data from the archive still
yields a flat-line trend, the issue could be in the archive, in the data source, or in
communications to the data source.
7. To determine if the server is working, create a trend for a point with data generated on the
server, such as sinusoid, which is generated by the Random interface on the server.
◦ If the trend for sinusoid appears correctly, the archive is working and communication
between the server and client is working. Go to step 6.
◦ If the trend for sinusoid does not appear correctly, go to step 5.
8. Use piartool -as or piartool -al command to verify that the archive is functioning
properly.
9. Using piconfig utility, PI DataLink, or the PI SMT Archive Editor tool, try inserting data
into a test point to create a trend. If this is successful, go to step 6. If not, contact OSIsoft
Customer Portal Contact Us page (https://customers.osisoft.com/s/contactus) for
additional assistance.
10. If all of these tests are successful, the data source for the flat-lined points may not be
working. Examine the source point attribute of the point to find out which interface is
feeding data for the point in question.
11. Check the OSIsoft Customer Portal Contact Us page (https://customers.osisoft.com/s/
contactus) website to verify that the interface program is running and connected to the
server.
12. Verify that the interface program is communicating with the external data source (DCS
system, RDB system, and so on). See the documentation for the specific interface for details.
13. If the data source is running successfully, go to step 14.
14. Examine the interface log files and the PI Data Archive message log files. Verify that both the
data source interface and PI ProcessBook have the correct access to the system.
15. Check the security settings to ensure that the interface has write access to all of the points
and PI ProcessBook has read access to all of the points.
Procedure
1. Copy the piarstat.dat file to a temporary location. Do not overwrite the original file.
Rename the file in case you need it later.
2. Stop the PI Data Archive server.
3. Run the pidiag -ad command, collect the dump of the piarstat.dat file, and verify the
output.
4. If the results of the dump look normal, attempt the automated recovery. Otherwise, use the
interactive one.
5. Restart the PI Data Archive server.
6. Check the message log to see if all archives are loaded. If the interactive version is used, only
the primary archive is loaded.
7. Register any remaining historical and future archives. If the interactive version was used, all
other archives must be registered.
In this example, the piarch1.fix file does not exist prior to the operation. It is created as a
fixed archive the same size as the input archive because the -f 0 option was specified. After it
is created, it can be registered using the piartool -ar command, and then data events can be
added to the archive in the usual way.
If the input file is registered prior to the recovery, it is unregistered during the operation. You
must register the input file when the recovery is complete.
Procedure
1. Stop PI Archive Subsystem.
2. Run piarchss and specify the parameters:
◦ Output archive is fixed size (-f 0)
◦ End time left open (-oet Primary)
3. After recovery:
a. Rename the old primary archive.
b. Rename the output file to the same path and filename of the original primary archive.
c. Restart PI Archive Subsystem.
In this example, the piarch.005.fix file does not exist prior to the operation. It is created as
a fixed archive the same size as the input archive because the -f 0 option was specified. The
end time of the output archive is left open because the -oet 0 option was specified.
The argument -tfix followed by full file specification is required. The arguments tfixend
and oeendtime are optional.
The first option, -tfixend, followed by a time stamp specifies the time to perform no
transformations. All events with time stamps greater than or equal to this time are not
transformed.
This option is used when only a portion of the archive has incorrect event time stamps. For
example, if a PI System was run for a period with incorrect system clock setting, then the clock
was set correctly and run for some period before applying a time transformation fix.
The second option, -oeendtime, followed by a time stamp specifies a time stamp to set as the
archive end time when conversion is complete. The archive end time is set to the passed value
if all events are older than this time; otherwise, the end time is set to the time of the oldest
archive event.
Example 1
The following example uses UTC seconds time format. The time stamp 0 is January 1, 1970, and
the time stamp 2000000000 is well into the 21st century. The offset is a positive 3600 (one
hour).
Therefore this data file will simply move all events ahead by one hour.
# Example 1, Moves entire archive ahead by 1 hour
0,3600
2000000000,3600
Example 2
Similar to the first example, this example uses local time stamps to specify a suitably large time
range to cover all events. The offset is -3600. This data file will move all events back by one
hour.
# Example 2, Also moves entire archive back by 1 hour
01-Jan-70 00:00:00,-3600
01-Jan-30 00:00:00,-3600
Example 3
This example applies a missed DST conversion for the Northern Hemisphere summer of 2003.
The first time stamp is set at 01-Jan-03 to include all events up to the DST transition; no offset
is applied up to, but not including 06-Apr-03 02:00:00. From 06-Apr-03 02:00:00 up to, but not
including, 26-Oct-03 02:00:00 one hour is added to all events. No offset is applied from 26-
Oct-03 02:00:00 to current time.
# Example 3, Applies a missed dst conversion to an
# archive that covers summer of 2003
01-Jan-03 00:00:00,0
06-Apr-03 02:00:00,3600
26-Oct-03 02:00:00,0
31-Dec-03 23:59:59,0
Snapshot recovery
There are two types of possible damage to the snapshot from which PI Data Archive can
recover:
• Snapshot times in the future. Accidentally moving the PI Data Archive system time into the
future can cause this; at a minimum all points collected locally will be in the future.
Snapshot events are replaced when a newer value is received; therefore these events remain
in the snapshot until actual time catches up. Events earlier than snapshot time bypass
compression. Events that bypass compression can put a large load on PI Data Archive.
• Damaged or corrupted snapshot file (piarcmem.dat). Corruption may be caused by disk or
power failures.
Procedure
1. Shut down PI Base Subsystem, PI Archive Subsystem, and PI Snapshot Subsystem.
2. At a command prompt, go to the PI\bin directory and type:
pibasess -snapfix [parameters]
Parameter Description
-file [filename] You cannot use this option with the -directory parameter.
Provides the full file name of an input file to use in place of the
default snapshot file, located in %PISERVER%\dat.
If filename refers to piarcmem_1.dat, this command processes
the file as a future snapshot file; otherwise it processes the file as
the historical snapshot file.
In both cases, the command implicitly processes the snapshot file
for the other set (future or historical) using the piarcmem*.dat
file in the default %PISERVER%\dat\ location. If you want to
explicitly process two files from a single directory, consider using
the -directory parameter.
Enter a filename only if you have a file that you want your new
piarcmem.dat file to be built from. To rebuild the snapshot file
based on the most current values in the snapshot, do not enter a
filename.
If a piarcmem.dat file exists, PI Base Subsystem renames the
piarcmem.dat file that contains the current snapshot values to
DD_MON_YY_piarcmem.dat. Then it builds a new piarcmem.dat
file from the renamed piarcmem.dat file. If there is no
piarcmem.dat file, a new file is created.
-directory directory This option cannot be used with the -file parameter.
Provides the directory of input files to use instead of the default
%PISERVER%\dat\ location.
To be processed, files in this directory must be named
piarcmem.dat or piarcmem_*.dat.
-ds state Specifies a system digital state that is inserted in the new file. Use
an existing digital state.
-maxtime time Sets the latest time stamp allowed in the snapshot; pisnapss -f
truncates at *+20 minutes. Indicates a time limit beyond which
the prior digital state of events will be replaced with SnapFix, or
the digital state you specify with the state parameter. This
parameter is only applicable to the historical snapshot file.
3. If duplicate points are found, use the ptpurge parameter to remove duplicate points:
pibasess -snapfix -ptpurgepointtopurge
or
pibasess -snapfix -ptpurge filelist
where pointtopurge is a single point, for example mypoint. If you want to use a file that
contains the names of multiple points, use filelist. For example, pointstodelete.dat.
When recovery is complete, PI Base Subsystem writes a final message to the screen and
exits.
4. Restart PI Base Subsystem, PI Archive Subsystem, and PI Snapshot Subsystem.
Current snapshot values are preserved in the rebuilt piarcmem.dat file. Points that have no
previous data use the SnapFix digital state, or the digital state you specify with the state
parameter, until the state is replaced by new snapshot values. Any snapshot record that
does not have a matching point is removed.
Tip:
You can run this snapshot recovery command while PI Data Archive is shut down.
Any combination of conditions can be used to select the events to be deleted, for example all
tags of a specific interface.
Note:
The significant digit command, @sigd 8, ensures that rounding errors do not cause
values to be missed.
Database repair
If PI Base Subsystem does not start due to a corrupted database, the log shows a message
indicating this. If there is no such message, start PI Base Subsystem in interactive mode and
observe the errors in the window. Database corruption is a relatively rare event. It is usually
due to hardware failure or improper shutdown. To repair all databases:
pibasess -copydb path
For example:
pibasess -copydb \pi\recovereddb
Following this command, the target path contains recovered copies of all the configuration
databases. Corrupted records are eliminated and related messages displayed.
Before you copy the recovered database files back into this directory, make a backup copy of
the \pi\dat\ directory.
After that, PI Base Subsystem should load all databases and work normally. The resulting files
are slightly smaller than the originals as they are compacted in the process.
Procedure
1. In a command line window, change to the PI\adm directory.
2. Type:
pidiag -fb path [-header | -dv]
where path is the complete path of the file.
Use the -header option to list only the header (no index). Use the -dv option to display
only the file’s version.
If the command returns an error, see Recover file-base file to fix the error.
With the header information, OSIsoft Technical Support can determine if there are any errors
in the structure of the file:
Procedure
1. Find the percentage of unused space in a file. See List the header and index.
2. In a command line window, change to the PI\adm directory
3. Type:
pidiag -fbcpath [-header]
where path is the complete path of the file.
Use the -header option to list only the header.
Procedure
1. In a command prompt window, change to the PI\adm directory
2. Type:
pidiag -fbf
inpath outpath
Results
In some cases, pidiag -fbf reports the following:
Error reading input record # nn [-10466] No Record Available for Passed recno
This is normal for records between the actual last record and the maximum allocated record.
The warning disappears if you run the utility a second time.
Procedure
1. Stop the PI System.
2. Correct the system time and the time on all connected nodes.
Note:
If you are using PI Buffer Subsystem to buffer data from PI interfaces, see Recover
from accidental time change at interface node that uses PI Buffer Subsystem.
3. Isolate the PI Data Archive server from interface nodes. The best technique is to disconnect
the server from the network. During this time, allow the data to buffer until the system is
verified up and running normally.
4. Rename the event queue file, pimapevq.dat, for later processing. The event queue may
contain many future events. Rename the following files located in the dat directory:
◦ pilastsnap.dat
◦ pilasttot_T.dat
◦ pilastalarm.dat
5. Create an empty archive file using PI SMT or the piarcreateutility.
6. Type pidiag -ar and register only the new empty archive.
7. There are two options for fixing the snapshot:
◦ If the erroneous future data can be discarded, start PI Snapshot Subsystem with -f flag
as described in Recover from future times in the snapshot.
◦ Otherwise, keep the current file, and after the system startup, delete or edit individual
values using the piconfig utility, as explained above.
8. Start the PI Data Archive server in base mode:
pisrvstart -base
This starts only the minimum required subsystems: PI Network Manager, PI Message
Subsystem, PI License Manager, PI Update Manager, PI Snapshot Subsystem, PI Archive
Subsystem, and PI Base Subsystem.
9. Register all the old archive files except for the previous primary, which contains future data.
10. Examine the unregistered archive file header to confirm the time boundaries of the various
archives involved before using offline archive processing to merge archives:
a. To look at the header of an unregistered archive:
pidiag -ahd
b. To look at registered archives:
piartool -al
11. Create a new primary archive using the piartool -ac command.
a. Specify a start time before any events that might be coming in. Specify the end-time as *.
This instructs PI Archive Subsystem to register the new archive as primary archive. The
start time specified must account for all buffered data. If you are unsure, set the start
time well before the time the problem was first encountered.
b. If necessary, use offline archive processing later to merge this data with existing archives.
12. Verify that the PI System is running correctly. Reconnect the server to the network.
13. Reprocess the old primary archive using the offline tool to filter out the future data, or
correct the archive's time by the required difference.
14. Reprocess the event queue into an archive file and correct time stamps as required.
15. If desired, combine two archives: the old primary and the result of the event queue.
16. Register the corrected archive file.
Recover from accidental time change at interface node that uses PI Buffer
Subsystem
If the time stamp on an interface node were changed to a future time stamp and that node uses
PI Buffer Subsystem, you must complete additional steps.
Procedure
1. Stop PI Buffer Subsystem.
2. Stop the interface nodes.
3. Delete the pibufmem.dat file.
4. Restart PI Buffer Subsystem.
5. Restart the interface nodes.