PI Data Archive 2015 Reference Guide en

PI Data Archive 2015
Reference Guide
OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
PI Data Archive 2015 Reference Guide

2009-2015 by OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or
by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission
of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset
Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI
BatchView, PI Coresight, PI Data Services, PI Event Frames, PI Manual Logger, PI ProfileView, PI Web API,
PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all
trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their
respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft,
LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR
52.227, as applicable. OSIsoft, LLC.
Version: 3.4.395
Published: 8 June 2015
Contents
About this document................................................................................................. 1
PI Data Archive command-line utilities........................................................................ 3

Remote operation of PI Data Archive utilities.................................................................................................. 3
apisnap..................................................................................................................... 5
ipisql......................................................................................................................... 7
Options for the ipisql command.......................................................................................................................7
Query submission............................................................................................................................................8
piarchss.................................................................................................................... 9
Options for the offline archive utility............................................................................................................... 9
Offline archive utility processing....................................................................................................................10
Run the offline archive utility......................................................................................................................... 11
Tips for using the offline archive utility.......................................................................................................12
Specify a start time for the output file........................................................................................................12
Specify an end time for the output file....................................................................................................... 13
Specify an ID conversion file.......................................................................................................................13
Time filters ................................................................................................................................................14
Offline archive utility exit codes................................................................................................................. 14
Event queue files and offline archives............................................................................................................ 15
Move event queue files.............................................................................................................................. 15
Load event queue into an offline archive....................................................................................................16
Correcting event timestamps (-tfix -tfixend).................................................................................................. 16
Time conversion file format....................................................................................................................... 16
Time conversion file examples................................................................................................................... 17
Combine or divide archives............................................................................................................................ 17
Combine multiple archives into a single archive......................................................................................... 17
Divide an archive into smaller archives.......................................................................................................18
piarcreate................................................................................................................ 19
piartool................................................................................................................... 21
Options for the piartool command.................................................................................................................21
piartool command-line tool for PI Data Archive backups............................................................................... 28
Launch backups with the piartool utility.................................................................................................... 28
Auxiliary backup commands for the piartool utility.................................................................................... 28
Options for the piartool -backup command............................................................................................... 32
Archive management with the piartool utility................................................................................................34
Archive creation.........................................................................................................................................34
Set maximum file size or maximum number of points for a dynamic archive.............................................. 37
Annotation files......................................................................................................................................... 37
Unregister an archive.................................................................................................................................38
Register an archive.................................................................................................................................... 39
Register archives in bulk............................................................................................................................ 39
List registered archives.............................................................................................................................. 39
PI Data Archive 2015 Reference Guide iii

Contents
View the next predicted archive shift time................................................................................................. 40

Enable archives to participate in shifts....................................................................................................... 41
Exclude archives from shift participation................................................................................................... 41
View an archive's shift-participation status................................................................................................ 41
Estimate archive utilization....................................................................................................................... 42
Monitor the flow of events to PI Archive Subsystem......................................................................................42
Archived events counter............................................................................................................................ 43
Out-of-order events counter......................................................................................................................43
Force an archive shift................................................................................................................................. 43
Events cascade counter............................................................................................................................. 43
Events read counter...................................................................................................................................44
Read operations counter........................................................................................................................... 44
Archive memory cache counters................................................................................................................44
Primary archive number............................................................................................................................ 45
Archive shift prediction..............................................................................................................................45
Archiving flag............................................................................................................................................ 45
Archive backup flag................................................................................................................................... 45
Archive loaded flag.................................................................................................................................... 45
Shift or system backup flag........................................................................................................................45
Failed archive shift flag.............................................................................................................................. 46
Overflow index record count..................................................................................................................... 46
Overflow data record count....................................................................................................................... 46
Monitor the event queue with piartool -qs.....................................................................................................46
Queue size................................................................................................................................................. 47
Page activity.............................................................................................................................................. 47
Queue capacity.......................................................................................................................................... 47
Event rates................................................................................................................................................ 47
Overflow queues........................................................................................................................................47
List buffered sources and points.................................................................................................................... 48
Release ownership of a buffered source's points............................................................................................48
Activity grid...................................................................................................................................................49
Check snapshot values.................................................................................................................................. 50
piconfig................................................................................................................... 53
Options for the piconfig command................................................................................................................ 53
Start the piconfig utility locally...................................................................................................................... 56
Exit piconfig...................................................................................................................................................57
PI table selection........................................................................................................................................... 57
View PI tables............................................................................................................................................ 57
Select a table............................................................................................................................................. 58
Display table attributes..............................................................................................................................58
PI Data Archive tables and primary keys........................................................................................................ 60
Attribute set table (PIATRSET).................................................................................................................. 61
Archive table (PIARC)................................................................................................................................ 62
Batch table (PIBATCH)...............................................................................................................................67
Batch alias table (PIBAALIAS)....................................................................................................................68
Batch unit table (PIBAUNIT)...................................................................................................................... 69
Collective table (PICOLLECTIVE)............................................................................................................... 69
Database security table (DBSECURITY)..................................................................................................... 70
Digital state table (PIDS)............................................................................................................................72
Digital state strings (PISTATE)................................................................................................................... 77
Firewall table (PIFIREWALL).......................................................................................................................77
Group table (PIGROUP)..............................................................................................................................77
iv PI Data Archive 2015 Reference Guide

Contents
Identity table (PIIDENT)............................................................................................................................. 78

Identity mappings table (PIIDENTMAP)..................................................................................................... 78
Network manager statistics table (PINETMGRSTATS)...............................................................................78
Point class (PIPTCLS).................................................................................................................................82
Point database table (PIPOINT)................................................................................................................. 84
Point source table (PIPTSRC).....................................................................................................................86
Snapshot table (PISNAP and PISNAP2)..................................................................................................... 87
Subsystem table (PISUBSYS).................................................................................................................... 89
Subsystem Statistics table (PISUBSYSSTATS).......................................................................................... 90
Server table (PISERVER)............................................................................................................................90
Thread table (PITHREAD).......................................................................................................................... 93
Timeout table (PITIMEOUT)...................................................................................................................... 94
Trust table (PITRUST)................................................................................................................................ 95
Users table (PIUSER)................................................................................................................................. 96
Enter piconfig commands..............................................................................................................................97
List information about a point....................................................................................................................97
Set a tuning parameter with piconfig example........................................................................................... 97
Modes of the piconfig utility.......................................................................................................................... 98
Combine create and edit modes................................................................................................................ 98
Use the check-only modifier...................................................................................................................... 98
Data structure types......................................................................................................................................99
Structure specifications persistence.......................................................................................................... 99
Delimited format..................................................................................................................................... 100
Fixed format............................................................................................................................................ 100
Keyword format.......................................................................................................................................100
Convert fixed format to delimited format.................................................................................................101
Display repeating attributes.........................................................................................................................101
Use the ellipsis construct..........................................................................................................................101
Select database records...............................................................................................................................102
Comparison operators............................................................................................................................. 102
Wildcards.................................................................................................................................................102
Trigger record processing............................................................................................................................ 102
Batch methods............................................................................................................................................ 103
Prepare input files.................................................................................................................................... 103
Pass an input file as a parameter.............................................................................................................. 104
Redirect an input file................................................................................................................................ 104
Capture output and errors in files............................................................................................................. 104
Pass commands as parameters................................................................................................................ 104
Redirect output........................................................................................................................................105
Reuse an output file as an input file.......................................................................................................... 105
Security for a piconfig session......................................................................................................................105
Helpful hints................................................................................................................................................ 105
Abbreviations.......................................................................................................................................... 105
Case sensitivity........................................................................................................................................ 105
Command input files................................................................................................................................105
Input line length.......................................................................................................................................106
Quoted strings.........................................................................................................................................106
Sending values as strings..........................................................................................................................107
Boolean values......................................................................................................................................... 107
Configuration persistence........................................................................................................................ 108
Command line parameters.......................................................................................................................108
Special characters in piconfig...................................................................................................................108
Display current settings with status command......................................................................................... 110
PI Data Archive 2015 Reference Guide v

Contents
Hexadecimal and octal numbers.............................................................................................................. 110

Use the login command to change to another server............................................................................... 110
Turn piconfig prompting on or off............................................................................................................ 110
pidiag.................................................................................................................... 111
Options for the pidiag command..................................................................................................................111
Display pidiag version number..................................................................................................................... 112
Interpret error codes.................................................................................................................................... 112
Archive management with the pidiag utility................................................................................................. 113
Dump the archive manager data file.........................................................................................................113
Create a new archive manager data file.................................................................................................... 113
Automatically recover the archive manager data file................................................................................114
Display unregistered archive information.................................................................................................114
Verify the integrity of the archive files...................................................................................................... 115
Find and report errors in archive files........................................................................................................116
Check data gaps in an archive...................................................................................................................117
Repair the archive manager data file........................................................................................................ 117
Check performance counters................................................................................................................... 118
Event queue files management....................................................................................................................118
View event queue file contents................................................................................................................ 119
View event queue file statistics................................................................................................................ 119
Licensing management............................................................................................................................... 119
Generate a signature file.......................................................................................................................... 119
Compare signatures.................................................................................................................................120
Extracting the signature from a license file...............................................................................................121
Miscellaneous commands............................................................................................................................ 121
Test for crash dump capability................................................................................................................. 121
Reset password to blank.......................................................................................................................... 122
Display network definitions..................................................................................................................... 122
Export and import certificates.................................................................................................................. 123
pigetmsg............................................................................................................... 125
pigetmsg command line options..................................................................................................................125
Continuous mode option......................................................................................................................... 129
Interactive mode option...........................................................................................................................129
Filtering pigetmsg output............................................................................................................................ 129
Search and sort messages............................................................................................................................130
Display message summary...........................................................................................................................130
Save messages to a file................................................................................................................................ 131
Read messages from a message log file....................................................................................................... 131
Display a message definition........................................................................................................................ 131
pilistupd................................................................................................................ 133
pilistupd command line options................................................................................................................... 134
pilistupd modifiers....................................................................................................................................... 134
pilistupd examples....................................................................................................................................... 134
Limit output to point updates example.................................................................................................... 134
Run pilistupd with PI ProcessBook display example..................................................................................135
Determine if client updates occur example...............................................................................................135
Producers and associated subsystems......................................................................................................... 136
pipetest................................................................................................................. 137
vi PI Data Archive 2015 Reference Guide

Contents
pisetpass............................................................................................................... 139
pisqlss................................................................................................................... 141
pisqlss command line options...................................................................................................................... 141
Start pisqlss as a Windows service............................................................................................................... 142
Start pisqlss in a command window............................................................................................................. 142
piversion................................................................................................................ 145
PI Data Archive database files................................................................................. 147

List of Database Files................................................................................................................................... 147
piarcmem.................................................................................................................................................... 149
piarstat.dat..................................................................................................................................................149
pidignam..................................................................................................................................................... 149
pidigst......................................................................................................................................................... 149
pilastsnap.................................................................................................................................................... 149
pimapevq.dat and pimaNNNN.....................................................................................................................150
pimsgtxt...................................................................................................................................................... 150
pipoints....................................................................................................................................................... 150
piptalia........................................................................................................................................................ 150
piptattr........................................................................................................................................................ 150
piptclss........................................................................................................................................................ 150
piptunit........................................................................................................................................................150
piusr.............................................................................................................................................................151
piusrctx........................................................................................................................................................ 151
piusrgrp....................................................................................................................................................... 151
shutdown.....................................................................................................................................................151
PI Performance Counters........................................................................................ 153

PI archive subsystem statistics..................................................................................................................... 153
PI authentication statistics...........................................................................................................................156
PI backup subsystem statistics..................................................................................................................... 157
PI base subsystem statistics......................................................................................................................... 158
PI Buffer Subsystem statistics......................................................................................................................159
PI collective statistics................................................................................................................................... 161
PI license entry statistics.............................................................................................................................. 161
PI license manager statistics........................................................................................................................ 161
PI license user statistics................................................................................................................................161
PI message subsystem statistics.................................................................................................................. 161
PI network manager statistics......................................................................................................................162
PI performance equation scheduler statistics............................................................................................... 163
PI Data Archive localhost statistics...............................................................................................................163
PI Data Archive statistics............................................................................................................................. 165
PI session statistics...................................................................................................................................... 166
PI snapshot subsystem statistics..................................................................................................................166
PI SQL subsystem statistics......................................................................................................................... 167
PI subsystem statistics.................................................................................................................................168
PI totalizer subsystem statistics................................................................................................................... 170
PI update consumer statistics.......................................................................................................................170
PI update manager statistics........................................................................................................................ 171
PI update producer statistics........................................................................................................................ 171
PI Data Archive 2015 Reference Guide vii

Contents
PI Message Subsystem example messages............................................................... 173

Client connection messages......................................................................................................................... 173
Subsystem connection messages.................................................................................................................174
Disconnect messages...................................................................................................................................175
RPC resolver messages................................................................................................................................ 176
Dead process timed out............................................................................................................................... 176
Technical support and other resources..................................................................... 177
viii PI Data Archive 2015 Reference Guide

About this document
The PI Data Archive Reference Guide provides a reference for the PI Data Archive command-
line utilities. It also discusses PI Data Archive database files, performance counters, and
messages.
This guide assumes that you have a basic knowledge of the PI Data Archive server and how to
perform typical system administration tasks. See the PI Data ArchiveIntroduction to System
Management Guide for this information. For more in-depth information about managing the PI
Data Archive server, see the PI Data Archive System Management Guide. For information on
configuring security (authentication and access permissions) on a PI Data Archiveserver, see
the PI Data Archive Security Configuration Guide.
Terminology change
OSIsoft is revising its terminology to reflect the growth of the PI System from its original
single-server architecture. In the revised terminology, PI Data Archive refers to the component
that stores time-series data (formerly called PI Server), and PI Server refers to both PI Data
Archive and PI Asset Framework. This document uses the revised terminology.
This convention started with the release of PI Server 2010, which included PI Data Archive
3.4.385. In this document, different versions of the PI Data Archive product are referred to by
the designated name at the time of release. That means we refer to versions of the software
prior to and including PI Data Archive 3.4.380 as PI Server. When we refer to versions later
than 3.4.380, or when we are not referring to a specific version, we call it PI Data Archive.
PI Data Archive 2015 Reference Guide 1

About this document
2 PI Data Archive 2015 Reference Guide

PI Data Archive command-line utilities
PI Data Archive includes several command-line utilities that you can use to configure points,
monitor data flow, manage archives, and configure security settings. Use the-? argument to
view details about any PI Data Archive command-line utility. For example:
pilistupd -?
Executable Location Purpose

apisnap.exe PI\adm Check snapshot values.
ipisql.exe PI\adm Execute SQL statements directed
at the PI Data Archive server.
piarchss.exe PI\bin Manage offline archive files.
piarcreate.exe PI\adm Create archive files.
piartool.exe PI\adm Mount archive files, and monitor,
inspect, or modify the state of a
running PI Data Archive.
piconfig.exe PI\adm Configure PI Data Archive
databases and tables, such as the
PI point database and the digital
state table.
pidiag.exe PI\adm Diagnose and repair the PI Data
Archive server offline.
pigetmsg.exe PI\adm View messages in the PI message
log.
pilistupd.exe PI\adm Monitor PI Update Manager,
update producers, update
consumers, and update queues.
pipetest.exe PI\adm Test PI Performance Equation
syntax.
pisetpass.exe PI\adm Change user passwords.
pisnap.bat PI\adm Start apisnap.exe against the
local PI Data Archiveserver.
piversion.exe PI\adm Find the version and build
numbers of the PI Data Archive
server.
Remote operation of PI Data Archive utilities

You can use the -node option to invoke the following PI Data Archive utilities remotely:
piconfig, piartool, pigetmsg and pilistupd.
-node Argument or Description
Option
computerID The remote PI Data Archive computer to connect to. Specify the IP address or host name. The
default is localhost.
-port portID Communicate with the remote PI Data Archiveserver over the specified TCP/IP port. The
default is the standard port, 5450.

PI Data Archive command-line utilities
-node Argument or Description

Option
-windows* Authenticate the connection to the remove computer with a Windows operating system
mechanism, either Active Directory or local Windows security.
-trust* Authenticate the connection to the remote computer with a PI trust.
-explicit* Authenticate the connection to the remote compute with password authentication (explicit
login). This is the default authentication method. Use additional options to specify the account
and password:
username piuser Log in to the remote computer using the account piuser. The default
account is piadmin.
password pipassword Log in to the remote computer using the password pipassword. The
default password is blank.
*Specify no more than one authentication method. For information on authentication methods,
see the PI Data ArchiveSecurity Configuration Guide.
For example, to run the piartool utility to show an archive list on a remote PI Data Archive
server named MyDataServer1 using Windows authentication, type:
piartool -node MyDataServer1 -Windows -al
To perform the same command using explicit login authentication with PI user mypiuser and
password march380, type:
piartool -node MyDataServer1 -explicit -username mypiuser -password march380 -al
If you are entering any piconfig arguments at a command prompt, enter them before the -
node option. For example:
piconfig input piarc.dif -node PISRV1-port 5450 -username piadmin -
password myadminpassword
Prior to PI Server version 3.4.380, the -remote option invoked utilities remotely. Current
versions continue to support the -remote option, but OSIsoft recommends that you use the -
node option instead.
Though you can run the pigetmsg utility remotely from a client computer, you must run other
utilities remotely from a PI Data Archive machine because of licensing requirements.

apisnap
Use the apisnap utility to check snapshot values. Run the utility from the ..\PI\adm
directory.
When you run apisnap, the utility prompts you for a point name. Enter either the point name
or the point ID prefixed by the \ character. For example, enter \1 to look up the point with a
point ID of one (if the default points are installed, this is sinusoid). To quit the utility, simply
press Enter at the prompt.
To check snapshot values on a different computer, enter the network node name or the node
name and TCP/IP port number when calling the apisnap utility. For example, to connect to
PISRV4 at port 5450, type:
apisnap PISRV4:5450
The pisnap.bat script, located in the PI\adm directory, runs the apisnap utility and
connects to PI Data Archive on the same computer.

apisnap

ipisql
Use theipisql utility to execute interactive SQL statements directed at the PI Data Archive
server. Run the ipisql utility from the ..\PI\adm directory. The utility uses PI API to
connect to PI Data Archive. When you run the utility, it connects to the default PI Data Archive
server, writes version information to the screen, and then prompts for input:
D:\pi\adm\ipisql
Connecting to default PI System...Done
iPISQL Copyright (c) 1993-2000, OSI Software, Inc. All rights reserved.
PI API Version 1.3.4 PINet Protocol Version 00011101
Connected to PI 3.3 Build 361.43 on node "figaro"
PISQL>
To exit the ipisql utility, type: exit;

The error code from the processing of the last SQL statement is the return code of the ipisql
utility. This allows error detection if the ipisql utility is used in a script.
Topics in this section

Options for the ipisql command
Query submission
Options for the ipisql command

The ipisql utility supports several options, which you can specify at a command prompt.
Most of the options are exactly the same as the command-line options for PI SQL Subsystem
(the pisqlss executable), specifically timeout (-t), time step (-ts), and options (-o). See
"pisqlss command-line arguments" in the PI Data ArchiveSystem Management Guide.
ipisql option Description
s
-csv Write results to standard output in comma-separated variable format suitable for
importing into a spreadsheet. The query text, column headings, row count and error
information are written to standard error, also in comma-separated variable format. No
command prompts are displayed.
-f Identifies a query file. If this argument is used, the ipisql command executes the query
in the specified file and exits. A command prompt is not displayed.
-node Identifies the PI Data Archive node to connect to. The name to use is the PI Data Archive
computer's network name. If the PI Data Archive node uses a port number other than
5450, you must specify the port number using either suffix port_number to this name
(for example, -node mynode:545), or specify -port port_number(for example, -node
mynode -port 545). If the port number is not specified, for Windows, the default is
5450.
-o Options. Specify the options in a comma-separated list of tokens with no space between
tokens. The interpretation of the tokens is not case-sensitive. The supported options are
AGGRTIMESTART, EXECSAFE, QEP, SUBSET, and ANSISQLVAL. When you set -o to
ANSISQLVAL, ipisqlreturns the values for integer points in the VALUE column. If you
do not set this option, ipisql returns the values for integer points in the STATUS
column. For a description of the other options, see "Arguments Supported by pisqlss" in
the PI Data ArchiveSystem Management Guide.

ipisql
ipisql option Description

s
-p0...-pn SQL parameter values. The first parameter is -p0 (zero), the second is -p1, and so on.
You may specify as many SQL parameters as you like, and need not specify all of them;
ipisql prompts for any additional parameter values needed. The SQL parameter values
are in effect throughout the entire ipisql session.
-password Password. This argument is interpreted only if the username argument is supplied. If -
username is provided, but -password is not, ipisql prompts you for a password.
-port TCP/IP port number. This argument is interpreted only if the -node argument is
supplied. For Windows, the default value is 5450. You may choose to add :portnum to
the end of the node name when providing the node argument.
-t SQL query timeout, in seconds. If this time expires, pisqlss will cause the query to
return either a timeout error, or a subset of the actual results, depending on the SUBSET
option in effect for pisqlss.
-ts Default value of the timestep column in the piinterp table. This value can be overridden
for any query by specifying a timestep constraint in your SELECT statement.
-username User name. If this argument is not present, the ipisql command does not attempt to
validate your identity; default access rights apply.
For example, to execute a query in the file myquery.txt against the PI Data Archive server
named larry with port number 5450 using a default timestep of two minutes, type: exit;
ipisql -ts 120 -f myquery.txt -node larry:5450
If the file myquery.txt contains the statement:

select * from picomp where tag = ? and time >= ?
You can avoid the prompt for SQL parameter values by typing:
ipisql -f myquery.txt -p0 sinusoid -p1 "today"
Query submission
To send a query to PI Data Archive, type SQL statements at the prompt and terminate with a
semicolon (;). The query can span multiple lines. The prompt for subsequent lines looks like:
_PISQL>
You can use as many lines as you like.

You can also process queries stored in a text file using the file command:
PISQL>file myquery.txt;
A query in a file need not be terminated with a semicolon; the query is processed when the end
of the file is reached.
A query file may contain more than one query. If this is the case, a semi-colon must be used to
separate the queries.
Query files may contain the file command.

piarchss
Use the offline archive utility to manage offline archive files. Run the offline archive utility from
the ..\PI\bin directory. PI Data Archive can be running when using the offline archive utility,
but the archives manipulated must be offline (that is, unregistered).
The offline archive utility uses the piarchss executable that runs PI Archive Subsystem.
The offline archive utility works with archive files that are not registered with a running PI
Data Archive server (that is, offline files). The running PI Data Archive can continue to store
current data, while you manipulate offline archive files. If you attempt to use the offline archive
utility on a registered archive file, the utility unregisters the file. You can use the offline archive
utility to:
Combine a number of archives together
Divide a large archive file into smaller archives
Extract a specific time period from an archive
Recover a corrupted archive
Recover events from an event-queue file
The offline archive utility can create fixed or dynamic archive files. Created files have the same
format as archive files created by piartool -ac. Every archive file has a parallel annotation
file created with the archive. The annotation file, which has the .ann file extension, must
remain in the same directory as its associated archive file.
To run the offline archive utility, run piarchss in console mode using special command-line
arguments.

Options for the offline archive utility
Offline archive utility processing
Run the offline archive utility
Event queue files and offline archives
Correcting event timestamps (-tfix -tfixend)
Combine or divide archives
Options for the offline archive utility

The offline archive utility supports several options. You may enter options in any order. The
offline archive utility requires the -if and -of options. Subsequent sections discuss how you
might use some of the options. Type piarchss -? to see a list of available options.
Option Name Description
-acceptprompts Accept all When specified, all prompts the utility present during the
prompts reprocessing are accepted by default.

piarchss

-dup Duplicate Allow input archive records with duplicate times. By default
records duplicates are ignored.
-evq Event queue Indicate that the input file is a PI 3 event-queue file (for
file example, pimapeq.dat).
-f size Make output Specify size in MB. If size = 0, the input file size is used. Default
archive a fixed is dynamic archive.
archive
-filter start end Filter Process events only within the time range (inclusive) specified.
Requires both timestamps. See Time filters.
-filter_ex start end Filter Process events only within the time range (inclusive of start
excluding end time; exclusive of end time) specified. Requires both
time timestamps. See Time filters.
-id pathname Specify ID Specify the ID conversion binary path and file name. See
conversion Specify an ID conversion file.
file
-idci input_file - ID conversion Create ID conversion file from specified input file.
idco outfile file creation
-if pathname Input archive Required. The full path, including drive letter is required. This
file is true for all file arguments passed.
-noinputcheck Disable input Disables the integrity check of the input archive.
check of input
archive
-oet option Output file Specify the end time for the output file. See Specify an end time
end time for the output file for details.
-of pathname Output Required.
archive file
-ost option Output file Specify the start time for the output file. See Specify a start
start time time for the output file for details.
-outputcheck Enables After reprocessing is complete, the output archive will be
checking checked to ensure it has integrity.
output
archive
-silent Silent mode Suppress warning messages.
-tfix Time fix Apply a specified time transformation to input data. See
Correcting event timestamps (-tfix -tfixend).
-tfixendtimestamp Time fix end Specify a timestamp after which no time transformation is to
be performed. Optional; only used in conjunction with tfix.
-tzf pathname Time zone Use when input is different from standard DST.
specification
file
-vah Validate Apply a validation algorithm. Multiple events referencing a
annotation single annotation are detected and fixed. Batch Database
handles annotations are checked for consistency.
Offline archive utility processing

During processing, the offline archive utility makes two passes through the input archive file:

piarchss
On the first pass, the utility:

Finds every record that contains valid data within the specified time range, and adds
them to a sorted list.
If required, converts point IDs using the specified conversion table.
Issues an error message for every record that does not have a corresponding point in the
local PI Data Archive server. You can suppress these messages, if desired.
During the second pass, the utility:
Creates the output archive file, if it does not already exist, and initializes the archive
header based on command-line specifications.
Filters or modifies the input data, if necessary, and writes all records from the sorted list
to the output file.
The offline archive utility displays statistics approximately every five seconds, at the end of the
first pass, and at the end of the second pass.
Run the offline archive utility

To run the offline archive utility (piarchss), enter an input archive file and an output archive
file, along with relevant command parameters.
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.

Tips for using the offline archive utility
Specify a start time for the output file
Specify an end time for the output file
Specify an ID conversion file
Time filters
Offline archive utility exit codes

piarchss
Tips for using the offline archive utility

When working with the offline archive utility, note the following.
The full path name of the input archive must be specified.
Note:
The piartool -al command lists only registered archives.
If the input file is registered, the offline archive utility unregisters it when processing
begins.
If the input archive is the primary archive, it cannot be unregistered. To work around this,
force an archive shift using the piartool -fs command or temporarily shut down PI
Archive Subsystem.
If the output file does not exist, the utility creates it.
If a full path name is not specified for the output archive, the utility places the output
archive in the current directory.
At the end of processing, neither the input nor the output archives are registered.
Starting in PI Server 2012, the input archives integrity is checked prior to being used. This
behavior can be disabled by specifying the noinputcheck option.
By default, the offline archive utility creates dynamic archives. Use the -f option to specify a
fixed archive.
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.
Specify a start time for the output file

Use the-ost flag to specify the start time for the output file. Type:
-ost option
Where option is one of the following:

input Sets the start time to the start time of input. This is the
default behavior.
event Sets the start time to time of first event in input.

piarchss
time (where time is specified in absolute PI time format) Sets the start time to the specified time string. Times are
specified in absolute PI time format. Relative times are
not supported. Times must be enclosed in double quotes
when containing spaces. If only date is specified the time
defaults to 00:00:00 (midnight) For example:
"22-JAN-02 23:59:59"
23-JAN-02
21-Feb
Output file start and end times must differ by at least one
second.
NFE Sets the start time to time of first event which passes the
time filter.
Specify an end time for the output file

Use the -oet flag to specify the end time for the output file. Type:
-oet option
where option is one of the following:

input Sets the end time to the end time of input file. This is the
default behavior.
event Sets the end time to the time of last event in input file.
time (where time is specified in absolute PI time format) Sets the end time to the specified time string. Times are
specified in absolute PI time format. Relative times are
not supported. Times must be enclosed in double quotes
when containing spaces. If only date is specified the time
defaults to 00:00:00 (midnight). For example:
22-JAN-02 23:59:59
23-JAN-02
21-Feb
Output file start and end times must differ by at least one
second.
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.
Specify an ID conversion file

Use the -id option to specify an ID conversion file when reprocessing archives, such as when
moving a PI archive file to a different PI Data Archive server. The ID conversion file is a binary
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 coverts 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

piarchss
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.
ID Conversion input file format

Every record of the input file must have this format:
Point ID, Recno, TagName
On a foreign PI Data Archive server you can create this file as follows:
e:\pi\adm>piconfig
* (Ls - ) Piconfig> @table pipoint
* (Ls - PIPOINT) Piconfig> @ostru pointid, recno, tag
* (Ls - PIPOINT) Piconfig> @output pointidconv.txt
@ends
The piarchss -idci input file does not allow for comment characters. The comment
character (*) generated by piconfig must be removed.
Time filters
To process events that occurred during a specific time period, use a filter flag.
-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:
-filter starttime endtime
Start time must be before end time.
-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:
-filter_ex starttime endtime
Start time must be before end time.
Offline archive utility exit codes

To facilitate batch file processing, the offline archive utility returns an exit code to the
operating system.
Code Definition
0 No errorsat least one input record processed.
1 Errors during input phase..
2 No processing errors0 records processed,
possibly an empty input file.

piarchss
Code Definition
<0 An error returned from the output processing
check log messages.
Event queue files and offline archives

In most cases the event queue is PI\dat\pimq0000.dat. However, it is possible to have
multiple event queue files. The utility piartool -qs indicates if your system uses multiple
queues. If multiple queues are used, the queue naming convention is pimqNNNN.dat, where
NNNN is a four-digit integer.
In version 3.3 and earlier, the event queue is pi\dat\pieventq.dat. Version 3.4 and later
does not support processing this format. These files should be processed before upgrading.
PI Data Archive versions 3.4 through 3.4.385 have a primary event queue file named
pimapevq.dat. If there is more than one queue file, these are named pimqNNNN.dat, where
NNNN is a four-digit integer. If these queue files are present during upgrade to PI Server 2012,
they will automatically be upgraded to the current format. If there are event queue files that
were moved into a separate directory for reprocessing prior to the upgrade, use the following
command for each event queue file to reprocess its events into an archive file:
piarchss -if D:\pi\dat\reprocess\pimq0000.dat -of D:\pi\dat\piarchss100.dat -evq
Note that the -if parameter is now only used with -evq when reprocessing event queue files
that were created in versions 3.4 through 3.4.385.
PI Server 2012 event queue files require the use of the -evqpath parameter instead.
The memory-mapped queue in PI Server 2012 has been improved to optimize throughput for
reading and writing. These improvements also extend to data recovery. If either the Snapshot
or Archive Subsystems terminate uncleanly, the PI Snapshot Subsystem will rigorously inspect
the event queue files and their contents to ensure that no corrupt events are present when it is
next restarted.

Move event queue files
Load event queue into an offline archive
Move event queue files

Occasionally, you might want to remove an event-queue from the system, such as when the
system cannot manage the load of a large backlog of events.
In most cases the event queue is PI\dat\pimq0000.dat. However, it is possible to have
multiple event queue files. The utility piartool -qs indicates if your system uses multiple
queues. If multiple queues are used, the queue naming convention is pimqNNNN.dat, where
NNNN is a four-digit integer.

piarchss
Procedure
1. Stop PI Snapshot Subsystem and PI Archive Subsystem.
2. Move PI\dat\pimq*.dat to a different folder than \PI\dat for later reprocessing. If you
configured the default event queue path to a different location than \PI\dat, move the
event queue files from this location
3. Restart PI Snapshot Subsystem and PI Archive Subsystem.
Load event queue into an offline archive

After you move PI\dat\pimq*.dat to a different folder than PI\dat for later reprocessing,
you can load the renamed event queue into an offline archive. The input path is the saved event
queue path. The argument -evq indicates that the offline archive mode is set to use event
queues. The resulting output archive might have dates that overlap existing archives. Offline
processing is required to combine these archives.
piarchss evqpath D:\pi\dat\saved_queue_files -of D:\pi\dat\piarch099.dat -evq
Correcting event timestamps (-tfix -tfixend)

Offsets, as a function of time, are defined in the time conversion file. This can be used to apply
corrections to times on some systems that had incorrect timestamps due to run-time library
problems, or non-standard DST setting.
This adds a given time offset to every event:
-tfix conversion_file
The optional -tfixend parameter allows you to specify a timestamp after which no
timestamp corrections are performed. For example, the following combination of -tfix and -
tfixend specifies to perform the timestamp corrections specified in the file
conversion_file.txt and to not modify any event timestamps at or after 13:00:00 January
1, 2010:
-tfix conversion_file.txt -tfixend "1-jan-2010 13:00:00"

Time conversion file format
Time conversion file examples
Time conversion file format

Lines starting with # are comments.
Empty lines and white spaces are ignored.
Data lines have the format:
StartTime, offset
StartTime may be expressed as UTC - seconds since 1/1/70 or as PI local timestamp string:
UTC timestamps and strings cannot be intermingled, the first format is assumed for all entries.

piarchss
Offset is a number of seconds added to the timestamp of every event within the time range.
Fractional seconds are not supported. Offset applies from timestamp up to, but not including
the next timestamp.
Time conversion file examples

Move entire archive ahead by 1 hour:
0,3600
2000000000,3600
Move entire archive ahead by 1 hour (another format):

01-Jan-70 00:00:00,3600
01-Jan-10 00:00:00,3600
Apply a missed DST conversion to an archive that covers the summer of 2002:
01-Jan-02 00:00:00,0
06-Apr-02 02:00:00,3600
26-Oct-02 02:00:00,0
31-Dec-02 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
Combine or divide archives

Archive files are organized according to the time ranges that they span. Occasionally, you
might find it useful to change the organization of your archive files. Use the offline archive
utility to:
Combine archive files with overlapping dates into one archive file.
Combine archive files with adjacent time ranges into one archive file.
Divide an archive file into smaller archive files, each covering a portion of the original time
span.

Combine multiple archives into a single archive
Divide an archive into smaller archives
Combine multiple archives into a single archive

To combine several archives, invoke the offline archive utility (piarchss) once for each input
file, using the same output file for all the input files. Start from the oldest input file and
continue in ascending time order (the offline archive utility will not work in descending or
random time order). For example:
piarchss -if D:\pi\dat\oldest.dat -of D:\pi\dat\bigfile.dat
piarchss -if D:\pi\dat\newer.dat -of D:\pi\dat\bigfile.dat
piarchss -if D:\pi\dat\newest.dat -of D:\pi\dat\bigfile.dat

piarchss
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 is the default type created by the offline utility, are not shiftable.
The end-time of the output file can be moved forward as required, but the start-time cannot be
changed 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.
Divide an archive into smaller archives

To break a single archive into smaller archives, invoke the offline archive utility once for each
output file and use the same input file for all the outputs. Each invocation, specify a different
start and end time in absolute PI time format.
For example, the following statements divide an archive into two smaller archives:
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\january.dat -filter "1-jan"
"31-jan-02 23:59:59" -ost "1-jan" -oet "31-jan-02 23:59:59"
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\february.dat -filter "1-feb"
"28-feb-02 23:59:59" -ost "1-feb" -oet "28-feb-02 23:59:59"
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 start time of january.dat is specified as 1-jan. This defaults to 1-jan, of the current
year, at 00:00:00. The filter end time is enclosed in double quotes because of the embedded
space character. The output archive start and end times are explicitly specified. 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.

piarcreate
Use the piarcreate utility to create archive files. Run the piarcreateutility from the ..\PI
\adm directory.
The piarcreate utility is a stand-alone utility that works on any computer, not just PI Data
Archive computers; the piarcreate utility does not require PI System components (for
example, PI SDK, PI API, pinetmgr, or any PI Data Archive subsystems) in order to run.
Note:
For common archive management tasks, use the piarchss utility.
The following table lists the options for the piarcreate utility.
Option Name Action
path size Archive Create a new fixed archive.
path is the name of the archive file.
size is the size of the archive in Mb.
-d path maxpoints Dynamic archive Create a new dynamic archive.
maxsize path is the name of the archive file.
maxpoints is the maximum number of points the archive can
contain.
maxsize is the maximum size of the archive file in Mb.
-v Version Get version and build information.

piarcreate

piartool
Use the piartool utility to mount archive files, create PI Data Archive backups, and monitor,
inspect, or modify the state of a running PI Data Archive server. Run the piartool utility from
the ..\PI\adm directory. PI Data Archive must be running to use the piartool utility. For
common archive management tasks, use the piarchss utility.

Options for the piartool command
piartool command-line tool for PI Data Archive backups
Archive management with the piartool utility
Monitor the flow of events to PI Archive Subsystem
Monitor the event queue with piartool -qs
List buffered sources and points
Release ownership of a buffered source's points
Activity grid
Check snapshot values
Options for the piartool command

At a command prompt, type piartool -? to list available options.
-ac Archive create Create an archive of fixed size. Fixed-sized archives are typically
preferred to dynamic archives for performance reasons. Also, a
fixed size archive will turn into a dynamic archive if there is not
enough space available in the archive.
Note:
For PI Server 2015, you can use the -future option with
the piartool -ac command.
-acd Dynamic archive Create a PI archive that grows dynamically in size. The maximum
create archive size is 2 TB for an archive that is created with the
piartool -acd command. To create a dynamic archive that has
a maximum size less than 2 TB, you must use the piarcreate
utility instead.
-ads path Archive disable shift Remove specified archive from shift participation.
-aes path Archive enable shift Add specified archive to shift participation.

piartool

-afl AF link Monitor the link between PI AF server and PI Data Archive. Use
with one of these suboptions:
-dump
Return the state of the link between PI Data Archive and PI AF
server. You can specify an optional parameter:
-verbose
Display all information related to the configuration and
status of the link available from PI Base Subsystem in
addition to PI AF Link Subsystem.
-mdbstat
Return the state of the MDB. The returned value corresponds
to the state:
0
OK
1
Starting up
Other values
Error
-mdbwait
Wait for the MDB to become available for editing. By default,
waits for a maximum of five minutes. You can specify
additional parameters and argument:
-maxwait
Maximum time to wait for MDB, specified in seconds.
-verbose
Display output from command.
-rpctimeout
Use the maximum wait as the RPC timeout.
-trace option
Control AF-link tracing by specified option. There are three
possible values:
on
Enable AF-link tracing. By default, the utility writes output
to the PI message log for five minutes.
off
Turn off AF link tracing.
query
Return the state of AF-link tracing.
When you enable AF-link tracing, you can specify optional
suboptions:
-log
Write output to a separate log file.
-timeout span
Write output for the number of seconds specified by span.
piartool

-al Archive list List all registered archives. Optionally, you can specify the
maximum number of archives to display. For example, the
following command will list only the primary archive and archive
1: piartool -al 2. For a description of the information output
by this command, see Output from the piartool -al command.
-ar path Archive register Register a specified archive. 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.
-as Archive statistics Monitor PI Archive Subsystem activity and statistics.
-au path Archive unregister Unregister a specified archive. You can use the wildcard
characters * and ? to unregister 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.
-aw Archive walk List details of the records in an archive file.
-backup Perform a PI Data Start a PI Data Archive server backup. The path argument
path Archive server specifies the target directory for the backup files. For a complete
backup list of arguments that modify that backup, see Launch backups
with the piartool utility.
-backup Run a backup Run a backup command. For a complete list of backup commands
command command and a list of possible arguments, see Auxiliary backup commands
for the piartool utility.
-bfs Buffered source List any PI Buffer Subsystem registered with PI Snapshot
Subsystem along with the buffered source's registration ID.
Additional options include:
-bfs ID -ptlist
List the points from a specific buffered source (ID is the
buffered source's registration ID).
-bfs ID -reset
Release the ownership locks PI Buffer Subsystem has on
points from the specified buffered source (ID is the buffered
source's registration ID).
-block Block Wait for specified subsystem to respond. By default, waits up to
subsystem 3600 seconds. Use in PI Data Archive start scripts to pause the
script until the subsystem is available.
For subsystem, you can specify two subsystems, separated by a
comma (that is, subsystem1,subsystem2), to confirm that
those subsystems can communicate.
Additional suboptions and argument:
-maxwait
Maximum wait for subsystem, in seconds.
-verbose
Display output from command.
-rpctimeout
Use the maximum wait time as the RPC timeout.

piartool

-cad Archive cache Display the events in the read and write archive cache for every
tagmask diagnostics point that matches the specified tag mask. Additional suboption:
-reset
Flush the values in the cache for the specified points.
-cas Archive cache Display a summary of the contents of the archive cache, including
summary the number of events in the read and write caches, for every point
with values in the caches. Optional argument:
tagmask
Display summary for points that match the specified tag mask.
-de path Dump event queue Dump specified event queue file. Additional suboption and
argument:
-pt tagname
Display information for specified tag.
recno
Display information for specific record in the file.
Note:
The -de option only works for event queues written by PI
Server version 3.3 or earlier.
-fs Force shift Force an archive shift.

-future Future PI points Apply the piartool command to future PI points. For PI Server
2015, you can use the -future option with the -ac, -ooo, and -
qs options.

piartool

-lic Licensing List license information. Use with one of the following arguments:
information Usage
List general license and usage information.
Def
List all licenses. Use the -select mask suboption to select
only the licenses that match the specified mask. For example,
piartool -lic def -select piarchss* lists all the
licenses that have names starting with "piarchss."
User
List all license users. Use the -select mask suboption to list
only users that match the specified mask.
Lic
List all licenses and users. Use the -select mask suboption
to list only the licenses and users that match the specified
mask.
AllowedApps [-List type,type...|-
Check app,app,...]
List the licenses of the specified application types or check
whether a specific feature is licensed. Use either -List or -
Check, but not both. The valid application types include:
PIService, PIUtility, OSIInterface, OSIMiddleWare, OSIAPIApp,
OSISDKApp, ServerApp, APIApp, SDKApp.
Note:
When PI Data Archive is not running, the piartool utility
does not work, but you can use the pilicmgr -lic usage
and thepilicmgr -lic def commands to list the license
information.
-module PI Modules lookup Look up the module path for a UID. Useful when debugging error
UID by UID messages in the PI message log that report the UID of a module,
but the not the module path.
-ooo Out-of-order snap Show tags with out-of-order events. Additional suboption and
events argument:
-r
Reset tags with out-of-order events.
n
Repeat the command every n seconds.
Note:
the piartool -ooo command.

piartool

-qs Queue statistics Monitor event queue activity and statistics. Updates every five
seconds. Additional arguments:
sec=n
Update every n seconds.
cnt=n
Display only n updates.
Note:
the piartool -qs command.
-qwait Event queue wait Wait for the event queue to empty. By default waits up to 300
time seconds. Optional argument:
maxwait
Maximum time to wait, in seconds.
-remote Remote system Run utility against a remote system. When you include this
argument as the last argument in any valid command, the utility
prompts you for remote-system login information. If successful
the utility runs against the remote system.
-sd Snapshot dump Display snapshot information for every point that matches the
tagmask specified tag mask. Additional suboption:
-bufreset
Clear PI Buffering Subsystem ownership of points that match
the specified tag mask. This will let other processes, such as
clients and API Buffer Server, post new snapshot values to the
point.
-ss Snapshot statistics Monitor PI Snapshot Subsystem activity and statistics. Updates
every five seconds. Additional arguments:
sec=n
Update every n seconds.
cnt=n
Display only n updates.

piartool

-sys System commands Manage the collective with the following suboptions:
for collective -close
management
Close the TCP/IP listeners on the Server. This will clear any
clients connected to the sever.
-drop PIServerName
Remove the specified server from the collective.
-open
Open the TCP/IP listeners on PI Data Archive. PI SDK clients
can resume connections to the server.
-promote PIServerName
Promote the specified secondary server to primary server.
-query
Return status of TCP/IP listeners on PI Data Archive.
-sync
Force the server to synchronize with the collective's primary
server.
-standalone
Enter, exit, or check stand-alone mode, depending on
suboption:
on
Place PI Data Archive in stand-alone mode.
off
Place PI Data Archive in normal mode.
query
Return current mode of PI Data Archive.
-testcfo
Clear SDK clients from PI Data Archive. Use to test SDK client
failover.
-thread Subsystem thread List the specified subsystem's threads.
subsystem list
-info
-v Version Display version and build information.
-upd Update producer Display update producer statistics. See Producers and associated
subsystem statistics subsystems. Additional sub-option:
producer -ls
List individual sign-ups.
Note:
Starting with PI Server 2015, the -aag option is no longer supported; the archive activity
grid is no longer available.

piartool
piartool command-line tool for PI Data Archive backups

You can use the piartool -backup commands to launch a VSS or non-VSS backup or to issue
other auxiliary backup commands. Typically, you do not use the piartool -backup
commands to start a backup directly. Instead, use the PI Data Archive backup scripts, which in
turn run the necessary piartool -backup commands. For on-demand backups, you can use
the Backup tool in the PI System Management Tools (PI SMT) instead of the piartool -
backup commands. For more information about backups and backup types, see the PI Data
ArchiveSystem Management Guide.

Launch backups with the piartool utility
Auxiliary backup commands for the piartool utility
Options for the piartool -backup command
Launch backups with the piartool utility

You can use the piartool -backup command to start an incremental, differential, or full
backup. The incremental, differential and full backups all result in a consistent set of database
files that can be used for disaster recovery. Typically, for your regular, nightly backups, you
should only need to do incremental backups.
Procedure
1. At a command prompt, go to the PI\adm directory.
piartool -backup path -type Type Options
where path is the full path to the backup directory. Valid entries for Type include:
INCREMENTAL
DIFFERENTIAL
FULL
Valid entries for Options include:
-wait sec
-nonvss
-arcdir
See Options for the piartool -backup command for descriptions of all the options.
Auxiliary backup commands for the piartool utility

The piartool -backup commands are typically used for troubleshooting and for monitoring
the course of a backup. The syntax is:
piartool -backup Arg1 [Arg2] [Arg3] [...]

piartool
If Arg1does not begin with a hyphen (-), then Arg1 is assumed to be the destination directory
for the backup, as described inLaunch backups with the piartool utility. If Arg1 begins with a
hyphen, then it is one of the auxiliary commands in the following table.
Note:
Italics indicate a value that must be supplied. Square brackets ([]) indicate that a value is
optional. Items separated by vertical bar (|) denote options that are mutually exclusive;
only one of the items can be used.
Auxiliary command Description

-abort Abort a current running backup. For example: piartool -backup -
abort
-history [index] [- Display backup history summary, if you specify neither an index nor the -
lastreport] lastreportflag.
Display report for the specified index, if you specify an index.
Display report for the most recent backup, if you specify the -
lastreport option.
By default, the history of the last 100 backups are stored in the backup
history. This default can be overridden by the backup_MaxHistory tuning
parameter.

piartool

-identify [-type Report the list of files that PI Data Archive will back up.
INCREMENTAL|
Use the -identifycommand to determine the files and components that
DIFFERENTIAL|FULL|
COPY] [-numarch N] [- will be included in a particular backup without actually performing the
cutoff date] [- backup. For example, to identify the files included in an incremental,
component c1 c2 differential, or full backup, use the syntax:
c3 ...] [-archive n1 piartool -backup -identify -type [INCREMENTAL|
n2 n3...] [-exclude c1 DIFFERENTIAL|FULL|COPY] [-verbose]
c2 c3...] [-verbose] To identify the files included in a backup that uses the -numarch or -
cutoff flags, use the syntax:
piartool -backup -identify [-numarch
N] [-cutoff
date] [-excluded
c0 c1 c2] [-type COPY] [-
verbose]
The -numarch and -cutoff flags have the same meaning as the
corresponding piartool -backup path command that is used to start
backups. See Launch backups with the piartool utility.
To identify the files included in a backup of specific components, use the
syntax:
piartool -backup -identify -component
c0 c1 c2... [-archive
n0 n1 n2...] [-verbose]
A component is a logical grouping of files. For example, all of the files for
PI Base Subsystem are grouped under the pibasess component.
If the -verbose flag is specified, the command reports the following
additional information:
ComponentName
The name of the component that the file belongs to. The component
name is used for the c0 c1 c2... parameters of the -component flag.
LastBackup
The time the file was last backed up. The last backup date is listed as
null if the associated file has never been backed up or if the last
backup date is not stored.
LastModified
Last time the file was modified.
SizeInBytes
File size in bytes.
ComponentDescription
Descriptive name for the component. Used only for display purposes
in third-party backup applications.
ComponentPath
The path of the component. Used only for display purposes in third-
party backup applications.
The identify command creates a file named PI\dat
\pibackupfiles.bks. This file contains the list of files identified for
backup. The number of archives in the list is restricted by the -numarch
and -cutoff parameters.
This file was used by the NTBackup.exe command for backups in PI
Server 3.4.370 as described in PI Data ArchiveSystem Management Guide.
The pibackupfiles.bks file is still created for backwards compatibility.
piartool

-query Query the current backup state and the current list of subsystems that
are registered for backup. This command is typically used to determine if
a backup is currently in progress. It can also be used to query the current
debug message trace level, where the trace level is set by the piartool
-backup -trace command or the Backup_TraceLevel tuning
parameter.
-shutdown Used in the pibackup.bat script on Windows XP to work around VSS
limitations on the Windows XP platform.
-SimulateVSS Simulate the COM+ events of a VSS backup without backing up any files.
simulate_command The -SimulateVSS commands are useful for third-party backup
applications that can take snapshots but do not communicate to the PI
Data Archive server via the VSS API. The -SimulateVSS -
PrepareBackup2Freeze command causes all events, from the
PrepareBackup event through the Freeze event, to occur. The simulated
backup is aborted if it does not end within 60 seconds. You can use the -
SimulateVSS -Thaw2PostSnapshot command in conjunction with the
-SimulateVSS -BackupShutdown command to end the simulated VSS
backup.
-trace level Control writing of debug messages to the log file.
By default, the trace level is 0, resulting in no trace messages. Higher
values of trace level result in more trace messages. Trace levels higher
than 100 result in no more messages than a trace level of 100.
Normally, tracing should be off to avoid unnecessary messages in the log
file.
If the trace level is non-zero, the trace level is displayed by the piartool
-backup -query command.
Example:
piartool -backup -trace 1
The default trace level can be overridden by specifying a non-zero value
for the Backup_TraceLevel tuning parameter.
piartool backup query command

When PI Data Archive first starts and whenever PI Backup Subsystem restarts, the output of a
piartool -backup -query command will appear as follows after all of the subsystems have
registered for backup:
Backup State
Backup in Progress: FALSE
Backup Start: Never
VSS Supported: TRUE
Subsystems Registered for Backup
Name, Registration Time, Version, Status
pibasess, 28-Jul-10 18:28:34, 3.4.385.59, [0] Success
piaflink, 28-Jul-10 18:28:57, 3.4.385.59, [0] Success
pimsgss, 28-Jul-10 18:29:02, 3.4.385.59, [0] Success
pibatch, 28-Jul-10 18:29:12, 3.4.385.59, [0] Success
piarchss, 28-Jul-10 18:29:27, 3.4.385.59, [0] Success
pisnapss, 28-Jul-10 18:29:45, 3.4.385.59, [0] Success
pilicmgr, 28-Jul-10 18:30:16, 3.4.385.59, [0] Success

piartool
From the query command, Last Backup Start will appear as Never when the backup
subsystem is restarted. To get accurate backup history information, use the piartool -
backup -history command or use the PI SMT Backup tool (Operation > Backups). The
pibatch subsystem does not appear in your list of subsystems that are registered for backup
if you are not licensed to use the old batch subsystem.
If the PI System is started normally, then subsystems should register for backup within about
30 seconds of the PI Backup Subsystem startup time. Normal startup is, for example, starting
the PI System with the pisrvstart.bat command file or letting the PI System services
automatically start after a reboot. However, if PI Backup Subsystem is shut down and restarted
by itself, it may take up to five minutes for the individual subsystems to register for backup.
If a subsystem is stopped normally (for example, without crashing), then the subsystem will
unregister for backup.
Options for the piartool -backup command

Option Description
path Full path to the backup directory. The directory path can be a UNC path.
Examples:
C:\pibackup\
\\myserver\c$\pibackup\
\\myserver\share\pibackup\
The UNC path can be a path to a shared directory on a remote computer. Mapped
network drive cannot be used in the full path.
-arcdir Back up archives and annotation files to the path\arc directory.

If this flag is not specified, archives are backed up to a directory based on their
current location. For example, if an archive is in the C:\PI\archives directory,
then it is backed up to the path\archives directory. Similarly, if an archive is in
the C:\PI\dat directory, then it is backed up to the path\dat directory.
-archive n0 n1 Back up the archive or archives specified by n0, n1, n2, and so on. The annotation
n2 ... file associated with the specified archive is also backed up.
Archive numbers begin at 0 with the primary archive. For example, the following
command backs up the primary archive and archive 2:
piartool -backup c:\pi\backup -archive 0 2
-component c0 Back up the component or components specified by c0, c1, c2, and so on. For
c1 c2 ... example:
piartool -backup c:\pi\backup -component pibasess
backs up only the files that belong to PI Base Subsystem.
The -archive and -component flags can be used in conjunction with each other.
For example, the following command backs up the pibasess, pisnapss, and piarchss
components in addition to the primary archive:
piartool -backup c:\pi\backup -component pibasess pisnapss
piarchss -archive 0
To see a full list of components, type:
piartool -backup -identify -verbose

piartool
Option Description
-cutoff date Cutoff date in PI time format.
For example, -cutoff *-10d restricts the backup to archives that contain data
between 10 days prior to current time and current time. The more restrictive of -
numarch N and -cutoff date takes precedence. The default cutoff date is 1-
Jan-1970 00:00:00, unless otherwise specified by the
Backup_ArchiveCutoffDate timeout parameter.
This flag is ignored if the -component or -archive flag is specified.
If -cutoff date is specified for an incremental or differential backup (-type
INCREMENTAL or -type DIFFERENTIAL), then all modified archives and all
archives matching the cutoff date criteria are included in the backup. The -cutoff
flag has no effect on a full backup.
-exclude c0 c1 Exclude the component or components specified by c0, c1, c2, and so on.
c2 ...
The -exclude flag is ignored for incremental, differential, or full backups.
-nonvss Perform a non-VSS backup on Windows Server 2003 or greater. This option has no
effect on Windows XP or Windows 2000 because non-VSS backups are always
performed on these platforms when a backup is started from the piartool -
backup command.
-numarch N Back up N archives.
For example, specifying -numarch 2 backs up the primary archive and archive 1,
provided that archive 1 contains data. Empty archives are never backed up. The
default number of archives for backup is 3, unless otherwise specified by the
Backup_NumArchives timeout parameter.
Specifying -numarch -1 includes all archives that contain data (and that are not
excluded with the -exclude flag) in the backup. Specifying numarch 0 excludes
all archives from the backup.
This flag is ignored if the -component or -archive flag is specified.
If -numarch N is specified for an incremental or differential backup (-type
INCREMENTAL or -type DIFFERENTIAL), the first N archives plus any other
archive that has been modified are included in the backup. The -numarch flag has
no effect on a full backup.
-type type Perform the specified type of backup: INCREMENTAL, DIFFERENTIAL, FULL, or
COPY.
For incremental and differential backups, only those archive components that
have been modified since their last backup time will be included.
For full backups, all archive components will be included, regardless of their
last modified and last backup time. The last backup time of archives are not
updated for differential or copy backups.
A full backup (-type FULL) is not appropriate for making copies of your PI
Data Archive because the last backup time of the archive files will be updated.
If the last backup time of archive files are updated outside of your nightly
backups and if you are doing incremental backups, then some archive files that
should be backed up might be missed. A full backup is appropriate for creating
a baseline for your nightly backups.
For copy backups to be performed, which prevents the last backup times of
your archives from getting updated. If the -exclude argument is specified,
then -type COPY is implied.

piartool
Option Description
-wait sec Wait up to sec seconds for the backup to complete before returning from the
piartool -backup command. The progress of the backup is reported every 15
seconds. When the backup is complete, a summary of the backup is reported.
The sec argument is optional. If you use the -wait flag without specifying the sec
argument, then the piartool -backup command waits up to one day for the
backup to complete.
If the -wait flag is not specified, then the piartool -backup command returns
immediately. In this case, the progress of the backup can be monitored with the
piartool -backup -query command.
The -wait option is used in the pibackup.bat script because it is important for
the backup to complete before the site-specific backup scripts are called.
Archive management with the piartool utility

This section contains topics that describe how you can use the piartool utility to manage
archives.
See also Archive management with the pidiag utility.
Archive creation
You can use either the piarcreate or the piartool utility to name, locate, create, and
initialize a new archive. You can create either a fix-sized archive or a dynamic archive, which
can grow up to a particular size.
Every archive has a parallel annotation file that has the extension .ann. Either utility creates
this file automatically. This file must remain in the same directory that contains its archive file
at all times.
piarcreate utility
The piarcreateutility creates an archive without registering it. You can specify the size of the
archive with the piarcreate utility, but you must complete a second step to register the
archive. Use the -d flag to create a dynamic archive. With the piarcreate utility, you can
specify the maximum number of points and maximum size of a dynamic archive. See Set
maximum file size or maximum number of points for a dynamic archive for details.
Note:
The piarcreate utility has minimal impacts on system resources. Therefore, use of this
utility is considered the most efficient way to create archives. However, you cannot
specify start and end times using the piarcreate utility.
piartool utility
You may use the piartool utility to optionally specify the following for new archives:
Start and end times for both fixed and dynamic archives
Maximum size for dynamic archives and the fixed size for fixed archives

piartool
Use option -ac to create a fixed-size archive and option-acd to create a dynamic archive. With
both the piartool -acand piartool -acd commands, the default created archive size
matches the current primary archive size, and registration is automatic.
Creation of a fixed archive with the piartool utility used interactively

C:\PI\adm\piartool -ac
This procedure will create and register a new archive. The archive path and
optional start/end times or size may be specified.
WARNING: This will reduce system responsiveness for the duration of the process.
If you do not need to initialize the archive times it is more efficient to run
'piarcreate' and then register the new archive with 'piartool -ar'.
Enter the complete path to the new archive: C:\PI\dat\piarch.113
You have entered the archive path: C:\PI\dat\piarch.113.
Is this correct (y/n/q)? y
Would you like to initialize the start and end times (y/n)? y
Times must be entered in standard PI Time Format, for example: 04-Jun-89 10:00:00
Enter the archive start time: t
You have entered the start time: 12-Nov-07 00:00:00 Is this correct (y/n)? y
Enter the archive end time ('*' for primary): 12-Nov-07 01:00:00
You have entered the end time: 12-Nov-07 01:00:00 Is this correct (y/n)? y
Would you like to set the archive size to something different than the current
primary archive (y/n)? y
You have requested to create an archive with the attributes:
File Path: C:\PI\dat\piarch.113
Start Time: 12-Nov-07 00:00:00
End Time: 12-Nov-07 01:00:00
File Size: 200MB
Is this correct (y/n)? y
Successfully scheduled the archive creation. Archive path: D:\PI\dat\piarch.113.
Check the message log for completion status.
Creation of a dynamic archive with the piartool utility used interactively

C:\PI\adm\piartool -acd
This procedure will create and register a new dynamic archive. The archive path
and optional start and end times may be specified.
WARNING: This will reduce system responsiveness for the duration of the process.
If you do not need to initialize the archive times it is more efficient to run
'piarcreate' and then register the new archive with 'piartool -ar'.
Enter the complete path to the new archive: C:\PI\dat\piarch.224
You have entered the archive path: C:\PI\dat\piarch.224.
Is this correct (y/n/q)? y

piartool
Would you like to initialize the start and end times (y/n)? y
Times must be entered in standard PI Time Format, for example: 04-Jun-89 10:00:00
Enter the archive start time: 31-Dec-06 00:00:00
You have entered the start time: 31-Dec-06 00:00:00 Is this correct (y/n)? y
Enter the archive end time ('*' for primary): 17-Jun-07 02:00:00
You have entered the end time: 17-Jun-07 02:00:00 Is this correct (y/n)? y
You have requested to create an archive with the attributes:
Start Time: 31-Dec-06 00:00:00
End Time: 17-Jun-07 02:00:00
Is this correct (y/n)? y
Successfully scheduled the archive creation. Archive path: D:\PI\dat\piarch.113.
Check the message log for completion status.
Create a new primary archive

You can create and register a primary archive with a specific start-time. The situations when
you might need to create a new primary archive include:
Backfilling archives.
After using the pidiag -ar command to recover from any corrupted archive situation.
Recovering from the Windows clock being set in the future.
If you have accidentally set your Windows clock on your PI Data Archive computer into the
future (either manually or due to a misconfigured time source) recovering can require
recreating the primary archive, after the correct time is restored.
To create a new primary archive, use the piartool -ac command and specify the start time
as required and the end time as * (now).
Note:
Registering a new primary archive fails whenever there is a current valid primary
archive registered.
A valid primary archive must have a specified start time and null end-time, which
signifies current time.
This procedure leaves you with only two registered archives.
Procedure
1. Stop the PI Data Archive server.
2. Create a new archive with the piarcreate command.
3. Register the new archive with the pidiag -ar command.
4. Start the PI Data Archive server.
5. Create a new primary archive with the piartool -ac command.

piartool
Set maximum file size or maximum number of points for a dynamic archive
You can set a limit on the file size (maxsize) or the number of points (maxpoints) of a dynamic
archive. To do this, you must use either the piarcreate or piartool commands (you cannot
do this using the PI SMT Archive Editor tool).
Use piartool to create and register a dynamic archive file and set the maxpoints and
maxsize values using the following syntax:
piartool acd <path> <maxpoints> <maxsize>
Use piarcreate to create a new archive file and set the maxpoints and maxsize values
using the following syntax:
piarcreate d <path> <maxpoints> <maxsize>
For example:
C:\PI\adm>piarcreate -d D:\PI\dat\piarch.115 2000 20000
Attempting to create a 2000 record, dynamic archive: D:\PI\dat\piarch.115 with
a maximum size of 20000 Mbytes.
Initializing archive file: D:\PI\dat\piarch.115
Archive D:\PI\dat\piarch.115 is prepared to be registered
Use piarcreate to change the maxpoints parameter:
G:\pi\adm>piarcreate -?
Usage: piarcreate -v
piarcreate -d path maxpoints maxsize(Mb)
piarcreate path size(Mb)
The following listing is for a 2048 MB archive; the maximum number of configurable points
for the archive is 1,048,576 (half the total number of records).
D:\PI\adm>piartool -al
Archive shift prediction:
Shift Time: 5-Oct-05 19:42:01
Target Archive: e:\pi\arc\piarch-2GB.1
Archive[0]: e:\pi\arc\piarch-2GB.3 (Used: 53.4%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Version: 7 Path: e:\pi\arc\piarch-2GB.3
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2097152 Add Rate/Hour: 154207.3
Offsets: Primary: 253063/1048576 Overflow: 1231270/2097152
Annotations: 1/65535 Annotation File Size: 2064
Start Time: 5-Oct-05 06:11:09
End Time: Current Time
Backup Time: Never
Last Modified: 5-Oct-05 13:26:21
Annotation files
You can annotate very value in the snapshot or the archive. An annotation can be of any data
type. An annotation file stores annotations. Each archive file has a single associated annotation
file, with an .ann extension. You can use the piconfig utility to add and edit text annotations.
Note:
Any operation on annotation translates into an actual I/O, bypassing archive caching.
Thus it is much less efficient than non-annotated events. Be aware of this when using
annotations.

piartool
The archive-listing command, piartool -al, shows annotation file statistics. The following is
output from an archive listing:
Archive[0]: c:\pi\dat\testarc.dat (256MB, Used: 0.0%)
Version: 8 Path: c:\pi\dat\testarc.dat
State: 4 Type: 0 (fixed) Write Flag: 1 Shift Flag: 1
Start Time: 27-Jul-10 17:29:30
Backup Time: 29-Jul-10 03:15:24
Last Modified: 29-Jul-10 13:28:56
In the above listing, the archive file is c:\pi\dat\testarc.dat. The corresponding

annotation file is c:\pi\dat\testarc.dat.ann. There are 5,541 annotations with space for
a total of 65,535 and the annotation file is 1,491,116 bytes (1.42 MB).
The annotation file is created if it does not exist. The archive and annotation files must remain
together, especially when restoring a backed-up archive file. PI SDK supplies a programmatic
interface for creating, accessing, and editing annotations. The PI SDK User Guide and online
help are the best source for details on valid variants for annotations.
Unregister an archive
You can unregister any archive except the primary archive (archive number 0), which stores
the current data.
Procedure
piartool -au path
where path specifies a complete, not relative, path name.
For example, the following command unregisters the archive called piarch.006 in the PI
\dat directory on the D drive:
piartool -au D:\PI\dat\piarch.006
Tip:
You can use the wildcard characters * and ? to unregister 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, the following
command unregisters 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*

piartool
Register an archive
Procedure
piartool -ar path
where path is the path to the archive file. Unlike the piartool -au command, the specified
path can be a relative path to an existing archive file.
For example, the following command registers the archive called piarch.006 in the PI
\dat directory on the D drive:
piartool -ar D:\PI\dat\piarch.006
Register archives in bulk

To register multiple archives simultaneously with the piartool -ar command, use the
wildcard characters asterisk (*) and question mark (?) in the file path to match multiple files.
The symbol * matches all possibilities with any number of characters. The symbol ? matches a
single character and may be used any number of times.
Procedure
piartool -ar path
where path is the path to the archive file. The specified path can be a relative path.
For example, entered in the PI\adm directory, the following command registers all archive
files in the PI\dat directory that begin with the piarch.0 prefix:
piartool -ar ..\dat\piarch.0*
Caution:
Try not to match non-archive files. If the contents of a matched file correspond to a
valid archive header, you can unintentionally register a file as an archive file.
List registered archives

Use the piartool -al command to return a list of registered archives.
Procedure
piartool -al

piartool
Output from the piartool -al command

Output from the piartool -al command lists archives in reverse chronological order
(archives with newer data before archives with older data). The output lists the primary
archive (that is, the archive that covers the current time) first. The output shows the dates
spanned by each archive. Archives cannot contain an overlap in dates. Unused archives have
start and end times shown as Current Time. The output displays unused archives in random
order.
The output shows the following information for every currently registered archive:
Label Description
Shift Prediction Estimated time of the next shift and the target archive. This is important for backup
planning.
Used Percentage of archive records used. This is an estimate, as the calculation only considers
empty records.
Version Identifier of the archive's internal architecture. This label allows PI Data Archive to mount
and upgrade archives from older versions of PI.
Path Full path of the archive file.
State Current condition of the archive. In piartool -al output, this will always be 4, which
means mounted and ready. All other states correspond to unregistered states, in which case
the archive is not visible in piartool -al output.
Type 0 = Fixed, 1 = Dynamic.
Write Flag 1 = Archive is currently writable, 0 otherwise.
Shift Flag 1 = Archive is potentially a target for archive shift, 0 otherwise.
Record Size Size in bytes of one record. This is always 1024.
Count Number of records in the archive file.
Add Rate Average number of overflow-records added per hour, over the archive lifetime.
Offsets: Primary Start and end record numbers for primary records. The end record number is always 1/2 of
the record count.
Offsets: Overflow Start and end record numbers for overflow records.
Annotations Number of annotations used and the maximum number available. The archive shifts when
this number is reached.
View the next predicted archive shift time

The PI SMT Archives tool (Operation > Archives) has a shift prediction column that predicts
the time for the next archive shift, based on the average number of archive records consumed
per hour, plus the rate of consumption. If the primary archive is less than 20 percent full, the
prediction is based on the previous archive rates.

piartool
Enable archives to participate in shifts

Procedure
piartool -aes path
where path is the full path to the archive.
Note:
The piartool -aes command does not enable dynamic archives to participate in
shifts.
See also
Exclude archives from shift participation
View an archive's shift-participation status

Procedure
piartool -ads path
where path is the full path to the archive.
See also


Examine output from the piartool -al command to determine whether archives are
potential targets of an archive shift.
Procedure
piartool -al
Output from the command lists archives in reverse chronological order (archives with
newer data before archives with older data). Archives with Write Flag set to 1 are
potential targets for archive shifts.

piartool
See also
Output from the piartool -al command

Estimate archive utilization

Examine output from the piartool -al command to determine the utilization of your
archives.
Procedure
piartool -al
Output from the command lists archives in reverse chronological order (archives with
newer data before archives with older data). Next to the Used label for each archive file, the
output shows the percentage of that archive that is used. For fixed sized archives, this is the
percentage of the total available records in use and is an indication of how much space is
available in the archive for data. For dynamic archives this is the percentage of primary
records in use and is an indication of how close one is to the maximum number of points
that can be created for that archive.
Monitor the flow of events to PI Archive Subsystem

You can use the piartool utility to monitor PI Archive Subsystem.
Procedure
piartool -as
Command output lists PI Archive Subsystem internal counters every five seconds.
$ piartool -as
Counters for 7-Aug-03 14:51:10
Archived Events: 1050621 1485
Out of Order Events: 0 0
Events Cascade Count: 0 0
Events Read: 5 0
Read Operations: 0 0
Cache Record Count: 0 0
Cache Records Created: 6 0
Cache Record Memory Reads: 5 0
Cache Clean Count: 0 0
Archive Record Disk Reads: 146342 219
Archive Record Disk Writes: 152737 226
Unflushed Events: 12431 -203
Unflushed Points: 3131 -48
Point Flush Count: 133491 211

piartool
Primary Archive Number: 5 0

Archive Shift Prediction (hr): 1 0
Archiving Flag: 1 0
Archive Backup Flag: 0 0
Archive Loaded Flag: 1 0
Shift or System Backup Flag: 0 0
Failed Archive Shift Flag: 0 0
Overflow Index Record Count: 0 0
Overflow Data Record Count: 5082 4
3. Review the output. Note the difference in the count in the column on the right since the
previous five seconds. The counters are reset to zero when PI Archive Subsystem starts.
4. Press Ctrl+C to stop piartool output.
Archived events counter

The Archived Events Counter is incremented for every new event written to the archive.
This count includes delete and edit events.
Out-of-order events counter

PI Archive Subsystem receives events from PI Snapshot Subsystem. If the timestamp of the
event is older than the last event in the target record, it is considered an out-of-order event
and is added to the Out-of-Order Events Counter.
Excessive out-of-order events might lead to system problems such as excess CPU consumption,
excessive disk I/O, and archives filling faster than expected.
Force an archive shift

You can use the piartool command to force an archive shift. You might force an archive shift
to test your system or to do advance archive management. However, do not force an archive
shift during normal operations.
Procedure
1. At a command prompt, go to the PI\adm directory
piartool -fs
For systems with large point counts, archive shifts might require a several minutes. Do not
shut down the PI Data Archive server until the shift has completed. To determine when this
has occurred, check the message log for message 2063 in the above output.
Events cascade counter

Out-of-order events are inserted into the target record. The insert requires moving other
events within the record. If the record is full, one or more events are forced out of the record
into the adjacent record. The Events Cascade Counter is incremented each time an
insertion forces an event out of a record. This counter indicates how out-of-order events
impact the archive.

piartool
Events read counter

The Events Read Counter indicates the number of events read by all applications. For
example, if a trending application requests an array of events over a specified time period, this
counter is incremented for each event returned.
Read operations counter

The Read Operations Counter shows the number of archive read requests. Each archive
read request increments this count by one, regardless of the number of events returned.
Archive memory cache counters

PI Archive Subsystem uses a memory cache when handling events sent to the archive disk file.
During routine operation, the write cache is automatically flushed to disk at least every 15
minutes. Abrupt system shutdowns, such as power loss, should lose no more than the last 15
minutes of data. This time range may be changed through a configurable PITimeout table
parameter.
The data archive write cache architecture provides large performance gains over reading and
writing directly to disk. The cache even provides significant performance over the operating
system file cache. As with all file cache designs, the disk image will often be slightly
inconsistent, and therefore archive backup cannot be performed without coordination with PI
Archive Subsystem.
The cache consists of archive records loaded into memory. Cache Records Created is
incremented when memory is allocated for a new record.
For example, when a user trends a point in PI ProcessBook, PI Archive Subsystem goes to the
cache to retrieve the event data. If the record is not there, PI Archive Subsystem loads the
record from disk to the cache, causing Archive Record Disk Reads to be incremented.
When writing events to the archive, they are stored first in memory. Unflushed Events
Counter indicates the total number of events not yet committed to disk. Unflushed Points
Counter indicated the number of points with any number of events not yet committed to disk.
Archive Record Disk Writes is incremented each time a record is written to disk. This
occurs during the regular cache flush every 15 minutes. It also occurs when the number of un-
flushed events for a point exceeds the configured maximum.
Cache Record Memory Reads is incremented for each read access.
Cache Clean Count indicates the number of records that were removed from the cache. The
archive cache contains a finite number of records. Old or low use records are removed from
memory to make room for most recently accessed records as needed; they are deleted when
unused for a certain length of time.
Cache Record Count is the number of records in the cache.

piartool
Primary archive number

The Primary Archive Number is an internal identifier and should be ignored. It is not to be
confused with the sequence number of the archive, as listed by piartool -al.
Archive shift prediction

The Archive Shift estimates the predicted time to the next archive shift. Use piartool
al to list the target file of the archive shift. The target archive is initialized on shift; if it
contains data, make sure it is backed up. If this data is required to remain online, a new archive
of adequate size should be created and registered.
The shift prediction in piartool -as differs slightly from the one in piartool -al. The
piartool -al figure is calculated at the time the call is made. piartool -as shows the
average shift prediction over the last 10 minutes. The latter number is available as a Windows
Performance Counter.
Archiving flag
The Archiving Flag indicates whether events may be written to the archive; a value 1
indicates events may be written, a value of 0, events may not be written. The Archiving Flag
is set to 1 when there is a mounted primary archive. A primary archive may be registered but
not mounted, for example during an archive shift. In this case, the Archiving Flag would be
set to 0. This flag is also set to 0 when in backup mode.
All registered archives may be viewed using piartool -al. The Archiving Flag is set to 0
if the primary archive becomes full and there is no other archive file available into which to
shift. Note that the primary archive will never overwrite itself.
Archive backup flag

The Archive Backup Flag will be non-zero when PI Archive Subsystem is participating in a
backup.
Archive loaded flag

The Archive Loaded Flag is 1 when a valid primary archive is mounted; 0 if the primary
archive is not mounted.
Shift or system backup flag

The Shift or System Backup Flag is 1 when the archive is in shift mode or PI Archive
Subsystem has been placed in backup mode. Shifts occur automatically or you can force a shift
with piartool -fs.

piartool
Failed archive shift flag

Failed Archive Shift Flag is set to 1 when a shift should occur but no potential archive
shift exists. Under normal conditions this flag is 0.
Overflow index record count

The Overflow Index Record Count shows the number of index records. These records
speed up access to overflow records. Index records are created when two overflow records for
a point are full and third one is being created. This counter provides a measurement of archive
file consumption.
Overflow data record count

The Overflow Data Record Count shows a number of non-primary data records. Each
archive has a primary record for each point. When this record is full, data is written to
overflow records. This counter gives a measurement of archive consumption.
Monitor the event queue with piartool -qs

Verify the proper sizing and functioning of the event queue, after you install or upgrade PI Data
Archive, or back up the server after significant changes. Use the command piartool -qs to
look at internal counters and statistics about the queue activity. For example, you can
determine if, and how fast, events are flowing through the queue.
Procedure
piartool -qs
This lists the event-queue statistics every 5 seconds.
3. Review the output.
4. Press CTRL+C to stop output from the piartool -qs command.

Queue size
Page activity
Queue capacity
Event rates
Overflow queues

piartool
Queue size
The Physical File Size shows the current size of the event queue on disk; that is, the file
pimapevq.dat or any overflow queues.
The Page Size is the portion of the file that is loaded into memory for faster access.
The event queue is a circular buffer of pages and each page is a circular buffer of events. That
is, when a page is full, PI Snapshot Subsystem tries to write into the next page and PI Archive
Subsystem reads the pages in the same order they were written.
The Total Data Pages shows the number of pages, obtained by dividing the event queue
size by the page size (minus one for the queue header).
Page activity
The Write Page Index shows the page PI Snapshot Subsystem is currently writing to.
Similarly, the Read Page Index indicates the page from which PI Archive Subsystem is
reading. Under normal conditions, these two numbers are identical. If PI Archive Subsystem is
not reading at the same pace that PI Snapshot Subsystem is writing, page shifts will occur and
the Total Page Shifts counter will increment. At any time, the Available Pages counter
shows how many free pages are left in the current queue.
Queue capacity
PI Snapshot Subsystem maintains the number of Average Events per Page based on the
average size of all events. The subsystem uses this average to derive an Estimated
Remaining Capacity in number of events. This capacity is also shown by piartool -ss.
Total Bytes Written shows the volume of data that transmitted through the event queue
since PI Snapshot Subsystem was last started.
Configure your queue to hold data from several days.
Event rates
Every time PI Snapshot Subsystem sends an event to the archive, the Total Event Writes
counter gets incremented. Similarly, when PI Archive Subsystem reads events, the Total
Event Reads is incremented. The difference between these counts equals the total events per
queue and is shown by the Current Queue Events.
Overflow queues
When the current queue is entirely full, PI Snapshot Subsystem creates additional queue files
of the same size. The Overflow Queues and Total Overflow Events counters indicate
how many queues exist and how many events they hold. These counts are the same indicated
by piartool -ss.
The Current Queue Id shows the sequence number of the primary queue. This is 0 under
normal conditions.

piartool
List buffered sources and points

Each instance of PI Buffer Subsystem that connects to PI Data Archive registers with PI
Snapshot Subsystem as a buffered source. Use the piartool -bfs command on the PI Data
Archive server to determine information about these buffered sources.
Procedure
2. Type the command appropriate for what you want to list:
To list: Type:
All buffered sources and their registration IDs piartool -bfs
Detailed information for a buffered source with a piartool -bfs ID
specific registration ID
PI points from a buffered source with a specific piartool -bfs ID -ptlist
registration ID
For information about using the -reset option to release ownership of points owned by a
specific buffered source, see Release ownership of a buffered source's points.
Release ownership of a buffered source's points

Use piartool with the -reset option to release ownership of all points owned by a buffered
source with a specified registration ID. For information on finding the registration ID for a
buffered source, see List buffered sources and points.
The -reset option may be used in rare situations to fix issues that are not addressed by other
routine solutions, for example:
If you are using a non-buffered application to write new events to buffered points, use the -
reset option to temporarily clear the PI Buffer Subsystem ownership of a point, then use
the application to write new events.
If PI Buffer Subsystem does not get point updates automatically (which only happens under
rare conditions), you may use this command to force PI Snapshot Subsystem to send point
configurations to PI Buffer Subsystem the next time that in-order events are sent.
Procedure
2. Type: piartool -bfs ID -reset
When the command completes, you will see the query status indicating whether the
command succeeded.
Note:
After this command is run, when data is written to the points again, PI Data Archive
will resend the configuration for all points to the PI Buffer Subsystem. Therefore, if the
buffered source writes to a number of points, you may see a subsequent effect on the
throughput after the command is run.

piartool
Activity grid
PI Archive Subsystem provides a tool to monitor read-access to the archive. This tool creates,
over a finite time period, a grid of activity. The grid provides an account of connections and
point activity.
Start the activity grid to temporarily identify the connections that present the greatest load on
the system and the points that are being queried most often.
This monitoring requires significant computing resources and therefore is normally turned off.
Once the load on the system is identified, OSIsoft recommends that you turn off the activity
grid.
The syntax for the activity grid is:
piartool -aag <start|stop|pause|point|cnxn> <event|access> -min n -max n
Note:
Earlier versions of PI Data Archive collected the aag statistics by PI user instead of by
connection (cnxn). The cnxn option replaces the option user, which is no longer
supported.
Set up the activity grid to view activity per point or per connection. You can query by
Event How many events were read for this point or connection.
Access How many read calls were made to this point or by this connection. For example,
one trend display call is counted as one access but can retrieve 100s of events.
To start the activity grid:
piartool -aag start
To stop it, and remove all its memory:

piartool -aag stop
To temporarily stop the accounting yet allow querying of the current statistics:
piartool -aag pause
Each query requests the number of events retrieved or the number of retrieval calls made
(<event|access>). These can be arranged by points or by connection ID (<point|cnxn>):
piartool -aag <point|cnxn> <event|access>
The following gets the number of events retrieved by point, from the time the activity grid was
started:
piartool -aag point event
It would return something that looks like this:

Count ID-Name
--------------------------------------
19 1-sinusoid
2982 4-CDM158
6 43-BaGen:bid.2
6 57-BaGen:PIBatchIndex.1
12 64-batchid-1
6 336-BaGen:proc.2
6 338-BaGen:prod.2
12 350-productid-1

piartool
40 368-piba1
13544 388-BAE9CF24-C8B3-46c0-AD5D-A64DF2174ED9
In this mode, the ID-Name column corresponds to the point ID and tag name.
The following gets the number of retrieval calls, by connection ID:
piartool -aag cnxn access
Here is an example of what would be returned:

Count ID-Name
--------------------------------------
131 7-PIBaGen.exe -
4 9-pibatch -
79 29-PIPESCHD -
3 659-snapE - ::1
18 9916-ptmoE - 10.0.0.6
34 10248-SMTHost.exe(988):remote - 10.0.0.5
120 10253-Procbook.exe(4848):remote - 10.0.0.5
52 10255-EXCEL.EXE(4296):remote - 10.0.0.5
In this mode, the ID-Name column corresponds to the ID, Name, and PeerAddress as displayed
in the PI SMT Network Manager Statistics tool (Operation > Network Manager). For local
connections, the PeerAddress is ::1 or 127.0.0.1 or blank.
The following gets the number of events for each connection:
piartool -aag cnxn event
Here is an example of what would be returned:

Count ID-Name
--------------------------------------
13875 7-PIBaGen.exe -
44 9-pibatch -
3045 29-PIPESCHD -
80 9915-ptmon.exe -
Use min/max to limit the display to only the cases of interest (abusers). For example, to display
only the connections that made more than 1,000 access calls, use the following:
piartool -aag cnxn access -min 1000
To display only the points that had more than 10,000 events read from since the activity grid
was turned on, use the following:
piartool -aag cnxn event -min 10000
Check snapshot values

Use the piartool utility to retrieve a record dump of the snapshot for a point.
Procedure
piartool -sd tagmask
where tagmask is the PI point tag name.
For example, to retrieve snapshot information for sinusoid, you would type:
piartool -sd sinusoid

piartool
Note:
You can also use the apisnap utility to check snapshot values.

piartool

piconfig
The piconfig utility is modal and interactive. It allows you to maintain and configure PI Data
Archive databases and tables, such as the PI point database and the digital state table.
With the piconfig utility, you can work interactively or you can supply text files that contain
commands and data. Use the piconfig utility to configure point information in a worksheet or
database tool, export it to a text file, then apply it to the PI point database.
You can also use the piconfig utility for troubleshooting. For example, if you suspect that you
have some tags that are not configured correctly, you can search for tags that match a certain
list of attributes.
You can use the piconfig utility only when PI Data Archive is running.
Options for the piconfig command

Option Argument Defaults Description
? Lists all commands.
?atr Lists all attributes for
current table.
?tbl Lists all tables known to
piconfig.
Case Data|Names|All All (case-insensitive) Sets case-sensitivity-
ignore mode. This
affects only timeout and
firewall tables.
Cd Directory Change directory for
input/output files.
Clear Clears Modify and
Select specifications.
Comchar NewComChar @ Changes the command
character to the
specified non-
alphanumeric character.
Comment NewCommentChar * Changes the comment
character to the
specified non-
Delimiter NewDelimiter , Changes the delimiter to
the specified non-
Echo Data|Commands |All| Data Specifies if input
Verbose|None commands and data are
echoed to the output
file.
End-repeat Marks end of repeated
field.

piconfig

Endrecord Terminates input of one
data record. Required in
keyword format. May be
used in other formats to
terminate input before
all data fields were
entered.
Endsection Marks the end of
processing section.
Error Filename Redirects error
messages to file.
Exit Exits the piconfig
utility. (Quit and Bye
work the same way.)
Help Lists all commands.
Input Filename Redirects input from
file.
Istructure Structure Specifies format of input
data.
Istype F|D|K D Selects input data
format structure type.
Line BufferSize 1024 Inputs line buffer size.
Login PI 3 node, PI username, Connects to a remote PI
password, port ID 3 home node using the
given PI user name,
password, and TCP/IP
port ID. This will not
work if explicit logins
are disabled on the
target PI Data Archive
server. piconfig
displays an error
message stating that the
authentication method
is disabled by current
server policy.
Maxerr ErrorTolerance 10 Sets the error tolerance.
piconfig will exit
when the number of
errors reaches the
specified number.
However, piconfig
exits only when in non-
interactive mode. A
Maxerr value of -1
causes piconfig to exit
upon the first error and
display the line number
of the input file.

piconfig

Mode Create|Edit, List Specifies mode of
Delete|List, operation. Create mode
Compare|Convert can be modified to edit
if the record already
exists by specifying
Create,t. Edit mode
can be modified to
create if the record
doesnt exist (Edit,t).
To check only, specify:
Edit,c or Create,c.
Modify Modification Defines field
modifications.
Ostructure Structure Specifies format of
output data. Only useful
when in list mode. A
warning is issued if this
command is used in
mode edit, create, or
delete.
Ostype F|D|K D Selects output data
format structure type:
Fixed, Delimited, or
Keyword (F,D,K).
Output Filename Redirects output to file.
If file is not specified,
the output is directed
back to standard output.
Prompt Yes|No Yes Sets prompt mode: yes
(for interactive
sessions) or no (for
batch sessions).
Ptclassname Classname Base Specifies the point class:
base or classic. PIPOINT
table only.
Quote ' | Tells piconfig to
enclose output fields
with quote character 'c'
if they contain the
delimiter character.
Recsep Yes|No Yes Tells piconfig to
separate multi-line
output records with a
comment line.
Select Selection Key=* Defines record selection
criteria.

piconfig

Sigd SignificantDigits 5 In a number display,
sets decimal digits (that
is, the number of digits
below the decimal
point) by setting it to a
number greater than or
equal to 0, or significant
digits by setting to a
negative number.
Status Reports piconfig
current configuration:
table, mode, structure
type, etc.
Structure Structure Specifies either input or
output according to
mode. Output in list and
convert modes. Input in
all other modes.
STYP Delimited|Keyword| Delimited Sets structure type.
Fixed Valid types are
Delimited, Keyword,
and Fixed.
SYST System Executes OS console
command. For example
Syst dir .
Table Table Sets the PI table to
PIPOINT, PIDS, etc.
Timformat Dig,TZ 5,F Time format. Number of
decimals on subsecond
timestamps and
whether or not to
include time-zone
indication.
Wait Seconds 0 Pause for the specified
number of seconds.
Useful in piconfig
scripts (non-
interactive).
Start the piconfig utility locally

To use the piconfig utility, PI Data Archive must be running. You can run piconfig using the
local PI Data Archive user name and password or Windows authentication.

piconfig
Note:
If the CheckUtilityLogin tuning parameter is set to 1 (on), then you cannot run the
piconfig utility with Windows authentication. When the CheckUtilityLogin tuning
parameter is on, the piconfig utility will always prompt you for a PI Data Archive user
name and password. If explicit logins are disabled on the PI Data Archive server, then the
piconfig utility displays an error message stating that the authentication method is
disabled by current server policy.
Procedure
2. Depending upon your authentication, type the appropriate command to launch the
piconfig utility:
To authenticate with a user name and password on the local PI Data Archive server, type:
piconfig
The utility prompts you to enter a valid user name and password to gain access to the
database tables.
To authenticate using Windows authentication, type:
piconfig -windows
The utility prompts you to enter the node. Enter the host name of your PI Data Archive.
The piconfig utility then attempts to start using your current Windows user name and
password.
Exit piconfig
Procedure
To end a piconfig session, type exit or Quit or Bye. It is not necessary to use the exit
command when running the piconfig utility in batch mode.
PI table selection
To perform a task with the piconfig utility, you must first select the PI Data Archive table on
which to operate. For example, to change a PI point you would select the PIPOINT table.

View PI tables
Select a table
Display table attributes
View PI tables
See PI Data Archive tables and primary keys for information about each PI Data Archive table.

piconfig
Procedure
1. Start the piconfig utility.
2. At the piconfig prompt, type: @?tbl.
Select a table
Procedure
1. Start the piconfig utility.
2. At the piconfig prompt, type @table tablename.
Display table attributes

After you select a table, type @?atr to display the attributes of that table.
Each of the table attributes can be viewed, set, or modified. Conceptually, each table in
thepiconfig utility consists of columns and rows, where the rows are table records and the
column headers are attributes. For example, each row in the PIPOINT table corresponds to a
specific tag.
The following example runs this command on the PI point database table (PIPOINT). The
output shows the attribute names and data types, the default values (D:), and the values of the
last retrieved record (C:).
(Ls - PIPOINT) PIconfig> @?atr
1 - Tag String D: !#!#!# C: SINUSOID
2 - NewTag String D: C:
3 - archiving BYTE D: 1 C: 1
4 - changedate TimeSta D: 31-Dec-69 16:00:00 C: 21-Dec-02 01:03:0
5 - changer String D: piadmin C:
6 - compdev Float32 D: 2. C: 2.
7 - Compdevpercent Float32 D: 2 C: 2.
8 - compmax Uint32 D: 28800 C: 28800
9 - compmin Uint16 D: 0 C: 0
10 - compressing BYTE D: 1 C: 1
11 - creationdate TimeSta D: 31-Dec-69 16:00:00 C: 17-Nov-02 18:39:5
12 - creator String D: piadmin C:
13 - DataAccess String D: o:rw g:r w:r C:
14 - DataGroup String D: piadmins C:
15 - DataOwner String D: piadmin C:
16 - datasecurity String D: piadmin: A(r,w) | pi C:
17 - descriptor String D: C:
18 - DigitalSet String D: system C:
19 - displaydigits BYTE D: -5 C:
20 - engunits String D: C:
21 - excdev Float32 D: 1. C:
22 - Excdevpercent Float32 D: 1 C:
23 - excmax Uint32 D: 600 C:
24 - excmin Uint16 D: 0 C:
25 - exdesc String D: C:
26 - PointID Int32 D: 0 C:
27 - pointsource String D: Lab C:
28 - pointtype String D: Float32 C:
29 - PtAccess String D: o:rw g:r w:r C:
30 - ptclassid String D: 1 C:
31 - PtClassName String D: base C:
32 - ptclassrev String D: 1 C:

piconfig
33 - PtGroup String D: piadmins C:

34 - PtOwner String D: piadmin C:
35 - ptsecurity String D: piadmin: A(r,w) | pi C:
36 - Recno Int32 D: 1 C:
37 - scan BYTE D: 1 C:
38 - shutdown BYTE D: 1 C:
39 - SourceTag String D: C:
40 - span Float32 D: 100. C:
41 - step BYTE D: 0 C:
42 - typicalvalue Float32 D: 50. C:
43 - zero Float32 D: 0. C:

Records
Primary key
Modify the primary key
Records
The piconfig utility regards a table as a collection of records. A record is a collection of fields
or attributes. One of these attributes is the primary key, which uniquely identifies the record
within the current table. This data representation is done for convenience and standardization.
It is not always an accurate image of the actual data.
Consider the following entries in the snapshot table:
Tag Value Time
CDM158 Auto 14-Jun-03 10:39:34
SINUSOID 68.973 14-Jun-03 10:00:00
SINUSOIDU 11.184 14-Jun-03 11:04:00
In this example, there is a record for each snapshot, and each record contains three attributes.
The attributes in this example are tag, value, and time.
Primary key
Every record contains one attribute that is defined as the primary key, which uniquely
identifies the record. The primary key is the first attribute listed when using the ?atr
command.
When using the select command to specify a record, the primary key must always be used. If
it is not specified piconfig assumes * (all records). Other attributes may be selected in
conjunction.
For example, the primary key for the PIPOINT table is TAG. When selecting the subset of tags
with point source F, the primary key needs to be included as follows:
@select tag=*, pointsource=F

piconfig
Modify the primary key

Most table attributes can be modified in edit mode, using modify and istructure
commands. The primary key is an exception. If you wish to change the primary key itself, you
must provide the new key value using a special attribute:
Use the newtag attribute for the PIPOINT table
Use the newset attribute for the PIDS table
For example, to rename the point sinusoid to mysinusoid, you would enter:
$ piconfig
* (Ls - ) piconfig> @table pipoint
* (Ls - PIPOINT) piconfig> @mode edit
* (Ed - PIPOINT) piconfig> @istructure tag,newtag
* (Ed - PIPOINT) piconfig> sinusoid,mysinusoid
The attribute for the new primary key is always:

newPrimary_Name
Some tables do not support renaming of records, for example PIARC and PISNAP tables. Tag is
the primary key of these tables. Because Tag is actually a point attribute, you must rename
from the PIPOINT table. Other tables have similar relationships.
PI Data Archive tables and primary keys

These are the PI Data Archive tables that you can view and edit with the piconfig utility.
Note that a table that is available on one version of a PI Data Archive server might not be
available in another. Use the ?tbl command to get the current list for the PI Data Archive you
are working with (see View PI tables).
Database Table names Primary key
Points PIPOINT TAG
Digital states PIDS SET
Digital State Strings PISTATE STATE
Users PIUSER USER
Groups PIGROUP GROUP
Snapshot PISNAP or PISNAP2 TAG
Archive PIARC TAG
Database Security DBSECURITY DBName
Batch Unit PIBAUNIT UNITNAME
Batch Alias PIBAALIAS ALIAS
Collective PICOLLECTIVE NAME
Trust Logins PITRUST TRUST
Firewall PIFIREWALL HOSTMASK
Timeout Database PITIMEOUT NAME
Attribute Sets PIATRSET SET
Point Classes PIPTCLS CLASS
Point Source PIPTSRC PTSRC

piconfig
Database Table names Primary key

PI Subsystem Information PISUBSYS, subsystem Not Applicable
PI Subsystem Statistics PISUBSYSSTATS, subsystem Not Applicable
PI Net Manager Statistics PINetMgrStats ID
Subsystem Threads PITHREAD, subsystem ID
Server PISERVER NAME
PI Identities PIIDENT Ident
PI Identity Mappings PIIDENTMAP IdentMap
Batch PIBATCH HANDLE
Attribute set table (PIATRSET)

The PIATRSET table contains sets of attributes used to build point classes. An attribute defines
a point attribute; it is comprised of a name, data type and default value. An attribute set
contains a list of attributes. Attribute sets are the building blocks of point classes. Point classes
are made up of a list of attribute sets.
Note:
Changing existing attribute sets - except for changing default values, should be done with
great care, in standalone mode.
PIATRSET attributes Description

SET Name of attribute set
ATTRIB Attribute name; a set has many of these
DEFAULT Default value of the attribute
TYPE... Data type of the attribute. For example, String,
Float32
An attribute set has many of the Attrib, Default, Type triplet. The ellipsis () following
TYPE indicates those three may be repeated.
The following piconfig session demonstrates how to list the attribute sets on the PI Data
Archive server:
* (Ls - PIATRSET) PIconfig> @table piatrset
* (Ls - PIATRSET) PIconfig> @ostr set
* (Ls - PIATRSET) PIconfig> @ends
*PIConfig Err> Wild-card specs. missing, default to '*'.
alarmparam
base
classic
sqcalm_parameters
totals
* (Ls - PIATRSET) PIconfig>
To list the entire classic and then base attribute sets use the ellipsis to repeat the output.
Users familiar with classic PI Points will recognize all these attributes. These two attribute
sets, Classic and Base, make up the classic point class.

piconfig
* (Ls - PIATRSET) PIconfig> @table piatrset

* (Ls - PIATRSET) PIconfig> @ostr attrib, default, type
* (Ls - PIATRSET) PIconfig> @ostr ...
* (Ls - PIATRSET) PIconfig> @istr set
* (Ls - PIATRSET) PIconfig> classic
*> classic
location1,0,Int32
location2,0,Int32
location3,0,Int32
location4,0,Int32
location5,0,Int32
filtercode,0,Int16
squareroot,0,Int16
totalcode,0,Int16
convers,1.,Float32
srcptid,0,Int32
instrumenttag,,String
userint1,0,Int32
userint2,0,Int32
userreal1,0.,Float32
userreal2,0.,Float32
* End Repeat...
* (Ls - PIATRSET) PIconfig> base
*> base
descriptor,,String
exdesc,,String
typicalvalue,50.,Float32
engunits,,String
zero,0.,Float32
span,100.,Float32
pointtype,12,UBYTE
pointsource,Lab,String
scan,1,BYTE
excmin,0,Uint16
excmax,600,Uint32
excdev,1.,Float32
shutdown,1,BYTE
archiving,1,BYTE
compressing,1,BYTE
step,0,BYTE
compmin,0,Uint16
compmax,28800,Uint32
compdev,2.,Float32
creationdate,31-Dec-69 16:00:00,TimeStamp
creator,0,Uint16
changedate,31-Dec-69 16:00:00,TimeStamp
changer,0,Uint16
displaydigits,-5,BYTE
* End Repeat...
Archive table (PIARC)

The PIARC table provides access to PI point data in the archives. The archives are historical
records of values for each point in the PI point database. The archives store the time-stamped
values in a set of files. You can list, add, modify, or delete events. The primary key is TAG.
PIARC Attributes Description Comment
TAG Tag name (read only)
PointID Point ID (read only)
Type Point type (float32 ) (read only)

piconfig
PIARC Attributes Description Comment

Value
TIME Event timestamp in the format
DD-MMM-YY hh:mm:ss.ssss
TimeNum Timestamp as a number in (read only)
seconds past 01-Jan-70
Status Value status (read only)
Flags (Q)uestionable (M)odifed Only Q is read/write
(A)nnotated
Annot Annotation
NewValue New value for specific
replacement
These attributes are the same as the PISNAP table attributes. In addition there are some
auxiliary attributes that affect retrieval and editing:
Attribute Description
Count Maximum number of events to retrieve in list
mode
Mode Archive editing mode
Starttime Start time for events retrieval
Endtime End time for events retrieval
Starttime and Endtime can define both a forward and a backward search.
Events can be added to the snapshot using the PIARC table. Events are placed in the snapshot if
they are more recent than the current snapshot event; otherwise, they bypass compression
and go straight to the archive according to the archiving mode specified. When a new snapshot
event is stored, the previous snapshot event is sent to the archive, compressed according to the
compression specifications.

List mode attributes for PIARC
List archive values (piarc.dif)
Edit MODE attribute for PIARC table
Change and delete events in PIARC table
Change events when there are multiple events at the same time
Use the TimeFormat command
Subsecond timestamps
Annotations
List mode attributes for PIARC

In list mode, the PIARC table mode attribute can be one of the following:

piconfig
COMP Compressed events
EVEN Interpolated events. The number of evenly spaced
events returned between starttime and endtime is
given by the Count parameter.
List archive values (piarc.dif)

The piconfig input file PI\adm\piarc.dif allows you to quickly view archive data with
piconfig:
@input piarc.dif
Next, enter data with the format:
tagname, starttime, endtime, count
For example, to view four hours of data for the tag sinusoid, with a maximum of 100 values,
type:
@input piarc.dif
sinusoid, *-4h, *, 100
@endsection
You can also use the PIARC table to view interpolated data by specifying the even mode. In this
example, five evenly spaced values will be retrieved:
* (Ls - PIARC) piconfig> @table piarc
* (Ls - PIARC) piconfig> @istru tag, starttime, endtime, count, mode
* (Ls - PIARC) piconfig> @ostr value,status,time
* (Ls - PIARC) piconfig> @ostr ...
* (Ls - PIARC) piconfig> sinusoid,*,*-4h,5,even
*> sinusoid,*,*-4h,5,even
71.32876,GOOD,20-Nov-02 17:52:51
77.07982,GOOD,20-Nov-02 16:52:51
Digital State,Shutdown,20-Nov-02 15:52:51
* End Repeat...
Edit MODE attribute for PIARC table

In edit mode, the MODE attribute can be one of the following:
noreplace Add unless event(s) exist at same time (PI 2.x).
append Add event regardless of existing events.
replace Add event, replace if event at same time.
replacex Replace existing event (fail if no event at time).
replaceSp Replace a specified value when multiple values
exist at the same time.
remove Remove existing event.
appendx As append + no compression; that is, if this is the
snapshot, force into archive.

piconfig
Note:
Do not confuse the PIARC table MODE attribute with the piconfig mode command. To
delete archive events, use the PIARC table MODE attribute =remove in piconfig edit
mode.
Change and delete events in PIARC table

The following commands can be used to add, edit, and delete events. Always backup your data
before deleting.
OSIsoft strongly recommends that you practice deleting small amounts of data on a test system
before deleting real data.
There is no way to undo a delete with any utility. Deleting large amounts of data may affect
availability of an online PI Data Archive. If this is necessary on a periodic basis, it is best to
understand the root cause and consider alternatives, such as using appropriate exception and
compression settings, increasing the available disk space, moving older archives to a second
tier storage and so on, instead of deleting data in bulk.
For detailed instructions about using piconfig to delete large amounts of data, see KB article
3065OSI8 at http://techsupport.osisoft.com/Support+Solution/7/
B849608AD89F41DC87E622ED0C244432.htm (http://techsupport.osisoft.com/Support
+Solution/7/B849608AD89F41DC87E622ED0C244432.htm).
In remove mode, both value and time must exactly match the existing event. If the timestamp
contains subseconds, it might be necessary to expand time resolution with the timf command
in order to make an exact match. See Use the TimeFormat Command for details. Similarly, the
number of decimal digits might need to be increased for floating point values using the sigd
command.
@table piarc
@mode edit,t
@istructure tag, value, time, mode
string1,some text,11:45, append
realtag,12.5,10:44, replace
inttag, 10, t, remove
When adding a new archive event with the edit modes above, you must use:
@mode edit,t
or
@mode create,t
Thepiconfig selection and modification may be used. For example one might create an input
file (input.txt) with the following command lines:
@istructure tag, starttime, endtime, count
@ostructure tag, value, status, time
@ostructure ...
@output labevents.txt
labtag,t,y,100
then redirect this input file into piconfig in order to list some events to an output file called
labevents.txt:
* (Ls - PIARC) piconfig < input.txt
Now one can change or delete all these events. For example:

piconfig
@mode edit
@istructure tag, value, status, time
@modify value*= 1.1, mode=replace
@input labevents.txt
This will increment all the previously selected events by 10%.

To delete all events for a specified time range (last 7 days in this example) for a given tag you
can place the script below in a file called delevents.dif. The script in this example will
delete up to 10000 events, but this value can be changed in the script. The default number of
events is 100.
@table piarc
@mode list
@istructure tag, starttime, endtime, count
@ostructure tag, time, value
@ostructure ...
@timf 9
@sigd 9
@output tmpdelevents.dat
%1%,%2%,%3%,10000
@output
*@exit - uncomment this to exit and review before deleting
@mode ed,t
@modify mode=remove
@istructure tag, time
@input tmpdelevents.dat
@exit
Then invoke piconfig as follows:

* (Ls - PIARC) piconfig input delevents.dif,mytag,t-7d,t
Do not include any spaces between parameters, so that the input file and its parameters are
taken as one parameter.
Change events when there are multiple events at the same time
The following commands show how to modify a specific value out of several at the same time
using replacesp mode. Note the use of NewValue attribute.
The replace mode would cause the last value at the time to be replaced.
* (Ed - PIARC) PIconfig> @input piarc.dif
* (Ls - PIARC) PIconfig> rpflt1,*,y,100
*> rpflt1,*,y,100
123.,GOOD,24-Jun-03 17:43:01
1123.,GOOD,24-Jun-03 01:00:00
112.,GOOD,24-Jun-03 01:00:00
11.,GOOD,24-Jun-03 01:00:00
1.,GOOD,24-Jun-03 01:00:00
* End Repeat...
* (Ls - PIARC) PIconfig> @mode edit,t
* (Ed - PIARC) PIconfig> @istru tag,value,newvalue,time,mode
* (Ed - PIARC) PIconfig> rpflt1,11,0.11,t+1h,replacesp
*> rpflt1,11,0.11,t+1h, replacesp
* (Ed - PIARC) PIconfig> @input piarc.dif
* (Ls - PIARC) PIconfig> rpflt1,*,y,100
*> rpflt1,*,y,100
123.,GOOD,24-Jun-03 17:43:01
1123.,GOOD,24-Jun-03 01:00:00
112.,GOOD,24-Jun-03 01:00:00
0.11,GOOD,24-Jun-03 01:00:00

piconfig
1.,GOOD,24-Jun-03 01:00:00
* End Repeat...
Use the TimeFormat command

The TimeFormat command can be used to adjust the number of subsecond digits displayed in
timestamps, and whether or not time zone information is displayed. The default number of
subsecond digits to display is 5. No time zone information is normally displayed. This
command affects the display of timestamps from the snapshot and archive only.
To set the number of subsecond digits to four and turn on time zone information display, you
would enter the command:
@timf 4,t
The time zone information displayed with every snapshot and archive timestamp is the short
label of time zone and current standard/daylight status. For example, in Pacific Standard Time,
this label would be PST. You can check the labels for your time zone with the pidiag -tz
command.
If you issue the TimeFormat command with the number of subsecond digits only, time zone
information display is turned off.
Subsecond timestamps
You can put events with subsecond timestamps in the snapshot and data archive using
piconfig. The Time attribute has the format
DD-MMM-YY hh:mm:ss.sssss
The Timenum attribute is the equivalent floating point representation of the time in number of
seconds past January 1, 1970 00:00:00.0000. The archive preserves the timestamp with
accuracy of 15.25 microseconds.
The default time accuracy of five digits might compromise a subsecond timestamp. Use the
sigd command to change the display to show six or seven digits before editing or deleting
such events.
Annotations
Since PI Server 3.3, piconfig supports annotation to archive values, in both PISnap and PIARC
tables. We recommend using piconfig only for reading annotations. Annotations should be
added using PI SDK applications that are designed for that purpose.
Batch table (PIBATCH)

The PIBATCH table is the database for the PI Batch objects such as PI Campaigns, PI Batches, PI
UnitBatches, and PI Transfer Records. This database is independent of PIBatch Subsystem and
the databases it maintains. The PI Batch table is actually part of the PI archive and is therefore
maintained by PI Archive Subsystem. PI Batch Subsystem records information about each
batch in this table, whether the batches are in progress or terminated. See the PI Data
ArchiveApplications Guide for details on how to access data in this table.
The table name is PIBATCH. The primary key is Handle. It is rarely used in batch searches.

piconfig
PIBATCH Attributes Description

UnitName Unit name to search
Handle Unique identifier for a single batch entry
BID Batch ID
ProdID Product ID
StartTime Batch start time
StartStatus Status of batch start time
StopTime Batch end time
StopStatus Status of batch end time
BIDsearch Wild card search string for batch IDs
ProdIDsearch Wild card search string for product IDs
SearchStart Time to search from
SearchStop Time to search to
Count Maximum number of batches to retrieve
NEWUnitName Changing the unit on which a batch is run by
altering attribute is not supported.
The PI Module and PI Batch database approach replaces the PI Batch Subsystem, the earlier
solution for batch data. Refer to the PI SDK Help files for details about the Module and Batch
databases.
Batch alias table (PIBAALIAS)

Aliases are defined and maintained by PI Batch Subsystem. An alias is used to define a PI tag
that corresponds to an attribute (generally, the name of some measured quantity) of a process
unit. The simple table consists of two columns: alias name and PI tag name. The alias name has
two components: a unit name and attribute name. Alias syntax is:
\\unit name\common name
For example:
\\Reactor1\temperature
The unit name must be a defined PI Batch unit, that is, an entry for it must exist in the
PIBAUNIT table. The PI tag name must also be valid.
See the PI Data Archive Applications User Guide for details on how to manage data in this table.
The table name is PIBAALIAS. The primary key is Alias.
PIBAALIAS Attributes Description
Alias Unit name and attribute. The syntax for alias
names in this table is: \\unitname\attribute.
Tag PI tag corresponding to the attribute.
NEWAlias Used to rename an existing alias.

piconfig
Batch unit table (PIBAUNIT)

PI Batch Subsystem monitors batches that run on units in a manufacturing plant. This table
contains configuration of the units. The primary key is Unitname.
See the PI Data Archive Applications User Guide for details on how to manage data in this table.
PIBAUNIT Attributes Definition
UNITNAME Defines the UNIT name. UNITNAME is the primary
index of the PIBAUNIT table. Cannot include the \
character.
NEWUnitName Used to rename an existing unit.
ActiveTag PI tag which indicates batch activity on unit.
ActiveType Interpretation of ActiveTag values. Pulse, the
default, starts batch on transition from 0 to 1 or
greater. Step, starts a new batch on any value
change.
BIDEXPR Defines an expression consisting of PI Tags and
text to generate a BATCHID when a batch begins
on a unit. The value of the evaluated expression
cannot contain a \ character.
DataAccess Security attribute, which specifies access to
batches created on the unit.
DataGroup Group membership of the batches created by the
unit.
DataOwner Owner of batches created by the unit.
Description Description of unit.
EvalDelay Specifies delay, from batch start, before evaluating
product and batch ID expressions.
MergeConsecutive If non-zero, treats short batch stop and restarts as
one contiguous batch.
PRODEXPR Defines an expression consisting of PI Tags and
text. This expression is used to generate a
PRODUCT name when the batch begins on a unit.
The value of the evaluated expression cannot
contain a \ character.
UnitAccess Security attribute, which specifies access to the
unit.
UnitGroup Unit group membership.
UnitOwner Unit owner.
Collective table (PICOLLECTIVE)

The PICOLLECTIVE table contains information about the PI Data Archive collective that the
server belongs to, including the collective's name, description, and status. Use this table along
with the PISERVER table to determine configuration and status information for each server in
a PI Data Archive collective.

piconfig
Normally, the table contains one row for the PI Data Archive collective that the server belongs
to. The Name attribute links entries in the PISERVER table to entries in the PICOLLECTIVE
table. PI Data Archive presents the CollectiveID as its server identifier to client applications
through PI SDK. This allows client applications to connect to any server in a collective without
changing displays.
The primary key is NAME.
PICOLLECTIVE Type Editable Example Description
Attribute
Name String Primary "uc-s1" Name of the
collective to which
the server belongs.
Must match
collective name
defined in
PISERVER table.
CollectiveID String Primary "08675309-0007-0 UID that uniquely
007-0007-000000 represents the PI
001001" Data Archive
collective.
Description String Primary "UC 2006 Demo Optional
Collective" description of the
collective.
LastCollectiveConfi TimeStamp No 12-Apr-06 Time stamp of last
gChangeTime 14:00:17 change to
collective
configuration.
Status Int32 No 0 Overall status of
the collective (0 =
good). Use the
pidiag -e
command to look
up the status as an
error code. If the
status is not good,
at least one
member of the
collective has a bad
CommStatus or
SyncStatus in the
PISERVER table.
NewName String Used to rename an
existing PI Data
Archive collective.
Database security table (DBSECURITY)

Database level security controls the access rights of users and groups to the various system
databases; for example, create a point. Earlier releases required user piadmin to edit a
database.

piconfig
For a detailed discussion of database security, see the PI Data ArchiveSecurity Configuration
Guide.
Database security is accessed through the DBSECURITY table. This is a general database
security table; its structure applies to all databases. The record structure looks like this:
DBSECURITY Attribute Description
DBName Database name
Description Description of the functional areas and database
tables controlled by this entry.
Access Security attribute, which specifies access to the
table
Group Group name
Owner PI user name declared to be the owner of the table.
Defaults to Piadmin.
Security Access control list which specifies access to the
table
status For internal use
The following examples show how to access and modify the DBSECURITY table.
C:\pi\adm>PIconfig table dbsecurity
* (Ls - DBSECURITY) PIconfig> @ostru dbname, owner,group,access
* (Ls - DBSECURITY) PIconfig> @ends
*PIconfig Err> Wild-card specs. missing, default to '*'.
PIARCADMIN,piadmin,piadmins,o:rw g:r w:r
PIARCDATA,piadmin,piadmins,o:rw g:r w:r
PIBatch,piadmin,piadmins,o:rw g:r w:r
PICampaign,piadmin,piadmins,o:rw g:r w:r
PIDBSEC,piadmin,piadmins,o:rw g:r w:r
PIDS,piadmin,piadmins,o:rw g:r w:r
PIHeadingSets,piadmin,piadmins,o:rw g:r w:r
PIModules,piadmin,piadmins,o:rw g:r w:r
PIPOINT,piadmin,piadmins,o:rw g:r w:r
pisnapss,piadmin,piadmins,o:rw g:r w:r
PITransferRecords,piadmin,piadmins,o:rw g:r w:r
PIUSER,piadmin,piadmins,o:rw g:r w:r
Modify the access to archive data and allow the piusers identity:
* (Ls - DBSECURITY) PIconfig> @mode edit,t
* (Ed - DBSECURITY) PIconfig> @istru dbname,owner,group,access
* (Ed - DBSECURITY) PIconfig> PIARCDATA,piadmin,piusers,o:rw g:rw w:
*> PIARCDATA,piadmin,piusers,o:rw g:rw w:
Modify the access to PI Base Subsystem auditing and thread table:

* (Ed - DBSECURITY) PIconfig> pibasess,piadmin,piusers,o:rw g:rw w:r
*> pibasess,piadmin,operators,o:rw g:rw w:r
Modify the access to the PI Update Manager thread table (there is no auditing in PI Update
Manager):
* (Ed - DBSECURITY) PIconfig> piupdmgr,piadmin,piusers,o:rw g:rw w:r
*> piupdmgr,piadmin,piusers,o:rw g:rw w:r
* (Ed - DBSECURITY) PIconfig> @mode list
* (Ls - DBSECURITY) PIconfig> @ends
*PIconfig Err> Wild-card specs. missing, default to '*'.
PIARCADMIN,piadmin,piadmins,o:rw g:r w:r
PIARCDATA,piadmin,piusers,o:rw g:rw w:
pibasess,piadmin,piusers,o:rw g:rw w:r
PIBatch,piadmin,piadmins,o:rw g:r w:r

piconfig
PICampaign,piadmin,piadmins,o:rw g:r w:r

PIDBSEC,piadmin,piadmins,o:rw g:r w:r
PIDS,piadmin,piadmins,o:rw g:r w:r
PIHeadingSets,piadmin,piadmins,o:rw g:r w:r
PIModules,piadmin,piadmins,o:rw g:r w:r
PIPOINT,piadmin,piadmins,o:rw g:r w:r
pisnapss,piadmin,piadmins,o:rw g:r w:r
PITransferRecords,piadmin,piadmins,o:rw g:r w:r
piupdmgr,piadmin,piusers,o:rw g:rw w:r
PIUSER,piadmin,piadmins,o:rw g:r w:r
* (Ls - DBSECURITY) PIconfig>
Digital state table (PIDS)

The digital state table contains the digital state sets. A state set has a name and a list of states
(digital state strings). The system is limited to 16383 sets with up to 16383 states in each set.
The default set is called SYSTEM and contains all the default system states found in a PI2.x
digital state table. The System digital state set number, SetNo, is 0 (zero).
Do not delete a digital state that has been in use. If you delete a digital state set, you cannot
view archived events associated with the set.
The table name is PIDS. The primary key is SET.
PIDS Attribute Description
SET Name of digital state set.
SETNO Digital state set number (read only).
STATE Digital state strings in the set.
OLDCODE Used to maintain offset references when editing
state sets that have empty state strings.
NEWSET Used to rename a state set.

List state sets in the digital state table
List digital states in a digital state set
Add a digital state set
Add a digital state set using multiple istructure lines
Modify a digital state set
Modify the System state set (Special considerations for blank states
Change the digital state set name
Create a digital tag
Send a digital state to the snapshot database
List state sets in the digital state table

This example shows how to use piconfig to list all state sets in the digital state table. The
defaults are list mode and delimited format.

piconfig
$ piconfig
(Ls - ) piconfig> @table pids
(Ls - PIDS) piconfig> @?atr
1 - SET (D) Setxxx
2 - SETNO (D) 0
3 - STATE (D) Statexxx
4 - OLDCODE (D) 0
5 - NEWSET (D)
(Ls - PIDS) piconfig> @ostructure set
(Ls - PIDS) piconfig> @select set=*
(Ls - PIDS) piconfig> @endsection
SYSTEM
BATCHACT
PHASES
MODES
List digital states in a digital state set

This example shows how to list all digital states included in the system digital state set.
C:Program Files\pi\adm>piconfig table pids
* (Ls - PIDS) PIconfig> @ostru set, state,...
* (Ls - PIDS) PIconfig> @sele set=system
* (Ls - PIDS) PIconfig> @ends
Add a digital state set

To add a digital state set to the digital state table, use piconfig as shown in this example:
Procedure
1. Select the digital state table.
(Ls - PIDS) piconfig> @table pids
2. Prepare to write to the table.
(Ls - PIDS) piconfig> @mode create
3. Specify an input data format of a digital state set name followed by any number of states in
the set. Follow this with a data line.
(Cr - PIDS) piconfig> @istructure set, state, ...
(Cr - PIDS) piconfig> ValveStateSet, Open, Closed
4. List the new state set in order to verify that it was properly created. Select only those sets
that start with V. Use an endsection command to force processing:
(Cr - PIDS) piconfig> @mode list
(Ls - PIDS) piconfig> @ostructure set, state, ...
(Ls - PIDS) piconfig> @select set=V*
VALVESTATESET,Open,Closed
(Ls - PIDS) piconfig>
Note:
The endsection command is not needed when creating the state set because data
lines are processed as they are entered.
Add a digital state set using multiple istructure lines

This method uses multiple istructure command lines.

piconfig
Procedure
1. Select the digital state table:
2. Prepare to write to the table:
(Ls - PIDS) piconfig> @mode create
3. Specify an input data format that consists of a digital state set name followed by any
number of states in the set:
(Cr - PIDS) piconfig> @istructure set
(Cr - PIDS) piconfig> @istructure state
(Cr - PIDS) piconfig> @istructure ...
The input lines are the set name followed by any number of states. For example:
(Cr - PIDS) piconfig> ValveStateSet
ValveStateSet
(Cr - PIDS) piconfig> Open
Open
Cr - PIDS) piconfig> Closed
Closed
Subsequent lines are treated as input until the next piconfig command is issued.
Modify a digital state set

If you want to modify an existing digital state set by adding a state, deleting a state, or
renaming a state, you must specify all of the states in the state set. Individual states cannot be
edited.
Note:
For sets with more than a few states it is advisable to use an output file, edit the file, and
then use it as the input file. The state set must be added or edited as a whole.
This procedure shows how to add another state to the ValveStateSet.
Procedure
1. Select the digital state table:
2. Prepare to write to the table:
(Ls - PIDS) piconfig> @mode edit
3. Specify an input data format that consists of a digital state set name followed by any
number of states in the set:
(Ed - PIDS) piconfig> @istructure set, state, ...
4. Input data (with no commands):
(Ed - PIDS) piconfig> ValveStateSet, Open, Closed, Stuck
5. List the new state set in order to verify that it was properly created:
(Ed - PIDS) piconfig> @mode list
(Ls - PIDS) piconfig> @ostructure set, state, ...
6. Select only those sets that start with V:
(Ls - PIDS) piconfig> @select set=V*
7. Start processing:

piconfig
Ls - PIDS) piconfig> @endsection

VALVESTATESET,Open,Closed,Stuck
(Ls - PIDS) piconfig>
Modify the System state set (Special considerations for blank states
The system digital state set is always set number 0. It cannot be deleted. Renaming it is
allowed, but not recommended. As with any other set, it must be edited in its entirety.
The system digital state set usually includes some blank states. To preserve these, make sure
that blank state are enclosed in quotes, or use the oldcode attribute. The oldcode attribute
can help maintain reference to state offsets within a set during editing. It has no other use.
@istru set
@istru oldcode,state
@istru ...
system
0,??????????
1,
2,?2
3,
4,?4
@istru set
@istru state
@istru ...
system
??????????
""
?2
""
?4
Both examples show only the first five states in the system set, and in both cases states 1 and 3
are blank.
Change the digital state set name

In the digital state table, the primary key is SET. Use the NEWSET attribute to change the value
of the primary key:
(Ls - ) piconfig> @table pids
(Ls - PIDS) piconfig> @mode list
SYSTEM
BATCHACT
PHASES
MODES
VALVESTATESET
(Ls - PIDS) piconfig> @mode edit
(Ed - PIDS) piconfig> @istru set,newset
(Ed - PIDS) piconfig> ValveStateSet,NewValveStateSet
(Ed - PIDS) piconfig> @mode list
SYSTEM
BATCHACT
PHASES
MODES
NEWVALVESTATESET

piconfig
Create a digital tag

A digital tag is defined by specifying point type Digital in the PI point database.
The default digital state set is System. To specify a different state set, enter the digital state set
name in the tag's DigitalSet attribute in the PI point database.
In this example, the tag name, the point type, and the digital state set are explicitly defined,
while all the other point attributes use the defaults.
Procedure
1. Select the PI point database table:
(Ls - ) piconfig> @table pipoint
2. Prepare it for writing:
(Ls - PIPOINT) piconfig> @mode create
3. Specify the input data format:
(Cr - PIPOINT) piconfig> @istructure tag, pointtype, digitalset
*> istructure tag, pointtype, digitalset
4. Specify the data:
(Cr - PIPOINT) piconfig> ValveStateTag, Digital, ValveStateSet
*> ValveStateTag, Digital, ValveStateSet
5. List the new tag entry in order to verify that it was properly created:
(Cr - PIPOINT) piconfig> @mode list
(Ls - PIPOINT) piconfig> @ostructure tag, pointtype, digitalset
6. Select only those tags that start with V:
(Ls - PIPOINT) piconfig> @select tag=V*
7. Force processing:
(Ls - PIPOINT) piconfig> @endsection
ValveStateTag, Digital, ValveStateSet
Send a digital state to the snapshot database

This procedure shows how to send a digital state Value to the snapshot to verify that the new
tag you have created can retrieve the value.
Procedure
1. Select the snapshot table:
(Ls - ) piconfig> @table pisnap
2. Prepare for writing:
(Ls - PISNAP) piconfig> @mode edit
3. Specify the input data format:
(Ed - PISNAP) piconfig> @istructure tag, time, value
4. Specify the data (set timestamp to *, which indicates that the current time should be used):
(Ed - PISNAP) piconfig> ValveStateTag, *, Open
5. List the snapshot entry and verify that it was properly updated:
Ed - PISNAP) piconfig> @mode list
(Ls - PISNAP) piconfig> @ostructure tag, time, value
6. Select only those tags that start with V:

piconfig
(Ls - PISNAP) piconfig> @select tag=V*

7. Start processing:
(Ls - PISNAP) piconfig> @endsection
ValveStateTag, 26-SEP-03 15:45:32, Open
Digital state strings (PISTATE)

PI maintains a list of all digital state strings in use. This means that if a given digital state string
is used in more than one digital state set, both sets refer to the same state string.
System managers need the ability to edit the digital string in the event that an error is made
when the string is first added to PI. The PISTATE table is used for this purpose. For example, to
correct the digital state string error AUto to Auto, you would issue the following piconfig
commands:
(Ls - ) piconfig> @table pistate
(Ls - PISTATE) piconfig> @mode edit
(Ed - PISTATE) piconfig> @istr state,newstate
(Ed - PISTATE) piconfig> AUto,Auto
AUto,Auto
(Ed - PISTATE) piconfig>
The only processing mode supported by the PISTATE table is edit, which means that you
cannot use this table to create, delete or list digital state strings. To modify or list digital state
sets or the strings that belong to them, use the PIDS table.
You should not use the PISTATE table to substantially change the meaning of any digital state
string. This would affect any digital state set that uses the state string.
Firewall table (PIFIREWALL)

The PI firewall is a security feature that allows PI Network Manager to control access to the PI
Data Archive server at the IP network address level. System administrators can use the PI
firewall to allow or deny specific computers to connect. Use this table to control general access
to the PI Data Archive server by network address.
After you edit the PI firewall, changes can take as long as 15 minutes to take effect. You can
also restart PI Data Archive to reload the table.
Select this table using the command:
@table pifirewall
The primary key is HOSTMASK.

PIFIREWALL Attribute Description
HostMask The name or IP address of a client computer
Value ALLOW or DISALLOW
NEWHostMask Used to rename an existing HostMask
Group table (PIGROUP)

With PI Data Archive 3.4.380, data from the PIGROUP table is moved to the PIIDENT table.
However, the PIGROUP table is preserved for backwards-compatibility purposes; it provides a

piconfig
list of PI groups, as they existed in previous releases. The PIGROUP table must still be used to
edit group memberships.
For details about how to configure and use PI groups and PI identities, see the PI Data
ArchiveSecurity Configuration Guide.
This table defines groups to which PI users may be assigned. The primary key is GROUP.
PIGROUP Attribute Description
Group Group name
Description Group description
Users List of users belonging to the group
NEWGroup Used to rename an existing group
Identity table (PIIDENT)

The PI identity table (PIIDENT) stores configuration data that defines PI identities. PI identities
represent the privileges that users obtain when they connect to the PI Data Archive server. PI
identities describe access levels to PI Data Archive secure objects, such as PI points and PI
modules. The PI identity table was added in PI Data Archive 3.4.380.
When you upgrade from a version prior to 3.4.380, data from the PI user and PI group tables
are preserved for backwards compatibility and moved to the PI identity table; the PI user and
PI group tables are merged with the PI identity table.
For details about PI identities, see the PI Data ArchiveSecurity Configuration Guide.
To create a new identity, MyNewIdentity, that can be used in a mapping or trust, type:
* (Ls - PIIDENT) PIconfig> @mode create
* (Cr - PIIDENT) PIconfig> @tabl piident
* (Cr - PIIDENT) PIconfig> @istr ident
* (Cr - PIIDENT) PIconfig> MyNewIdentity
*> MyNewIdentity
* (Cr - PIIDENT) PIconfig> @ends
* (Cr - PIIDENT) PIconfig>
Identity mappings table (PIIDENTMAP)

The PI identity mappings table (PIIDENTMAP) stores the information that associates Windows
users and groups to PI identities. When a Windows group is mapped to a PI identity, Windows
users from that group can access the PI Data Archive server based on access rights that were
given to the PI identity.
For details about how to map PI identities, including piconfig examples, and how to set
security for PI Data Archive resources, see the PI Data Archive Security Configuration Guide.
Network manager statistics table (PINETMGRSTATS)

The PI Network Manager statistics table (PINETMGRSTATS) displays information on active
connections as well as some information specific to PI Network Manager.

piconfig
The table name is PINetMgrStats. The connection ID is assigned based on order of connection.
Since connection names are not required to be unique, the ID is the primary key. This table is
read-only.
PINETMGRSTATS Attributes Description
ID Connection ID. This is the primary key.
Name Connection name.
Operating System information
OSBuild Operating system build.
OSSysName Operating system name.
OSUser Operating system user.
OSVersion Operating system version.
PID The ID of the process that made the connection.
This is applicable to all entries besides pinetmgr.
PIPath PI Data Archive root directory on the server. This
item is the same for all connections.
Network-level data
ConStatus Connection status.
ConTime Time connection was established.
BytesRecv Bytes received by the connection.
BytesSent Bytes sent by the connection.
MsgRecv Messages received by connection.
MsgSent Messages sent by connection.
PeerPort The port being used by the remote process for the
connection to PI Network Manager. This
information is especially useful when
troubleshooting firewalls and network routing.
PeerAddress IP address of connecting machine.
PeerName Host name of connecting machine.
A timeout parameter DoRDNSForMessaging needs
to be set to 1 in order for piconfig to view this
attribute. You must stop and restart PI Data
Archive for the change of DoRDNSForMessaging to
be effective.
RecvErrors Number of receive errors on the connection.

SendErrors Number of send errors on the connection.
NetType Connection network type WIN32 named pipes,
UNIX, or TCP/IP.
ElapsedTime The number of seconds that the connection was
active.
pinetmgr only
APICount The number of API connections that are connected
to the PI Data Archive server.

piconfig
PINETMGRSTATS Attributes Description

IsStandAlone 1 if the server is in standalone mode, 0 if it is not.
piconfig does not have access to this attribute.
You can view it only with the Network Manager
Statistics tool in SMT.
IsTCPListenerOpen 1 if PI Network Manager is accepting requests via

TCP, 0 if it is not.
NumConnections The number of SDK and API connections to PI

Network Manager.
SDKCount The number of SDK connections.

ServerID Internal ID of the server.
Protocol information
PI Version Version of PI Network Manager.
ConType Connection type:
PI API connection
PI API or VMS PINet node
Local connection
PI SDK or PI subsystem directly connected to
pinetmgr
Remote Router
Connection from PINS to PI Data Archive
Remote Resolver
Connection to a PINS (other end of the above
connection)
ProtocolVersion PI Protocol version of connecting application.
LastCall The timestamp for the time that the last call was
made to the PI Data Archive server by that
connection.
Licensing
RegAppID The public ID for a particular application.
RegAppName Registered application name.
RegAppType Application type: PIService, PIUtility, ServerApp,
OSIInterface, OSISDKApp.
Trust information
Trust The name of the trust that is in use by the
connection.
User The user that the connection is logged in with.

piconfig

View PI connection information
Delete connections
View PI connection information

Specifying the ID as pinetmgr accesses statistics associated with pinetmgr. Specifying ID as
* will list all connection statistics and pinetmgr statistics. ID, Name, and ProtocolVersion are
the only attributes that apply to pinetmgr. ConTime refers to startup time of pinetmgr.
The following example lists all attributes of all current connections:
* (Ls - PINETMGRSTATS) piconfig> @ostr ID, BytesRecv, BytesSent, ConStatus
* (Ls - PINETMGRSTATS) piconfig> @ostr contime, contype, msgsent, name
* (Ls - PINETMGRSTATS) piconfig> @ostr nettype, peeraddress, peername
* (Ls - PINETMGRSTATS) piconfig> @ostr protocolversion,recverrors,senderrors
* (Ls - PINETMGRSTATS) piconfig> @selec id=*
* (Ls - PINETMGRSTATS) piconfig> @ends
6,24,132447,[0] Success
4-Sep-02 17:08:05,Local connection,759,pimsgss
WIN32 Named pipe,,
3.1,0,0
*----------
7,24,108008716,[0] Success
4-Sep-02 17:08:12,Local connection,1794287,piupdmgr
WIN32 Named pipe,,
3.1,0,0
*----------
8,24,3710706,[0] Success
4-Sep-02 17:08:19,Local connection,64851,pisnapss
WIN32 Named pipe,,
3.1,0,0
*----------
9,24,1974873,[0] Success
4-Sep-02 17:08:27,Local connection,24266,piarchss
WIN32 Named pipe,,
3.1,0,0
*----------
10,24,102724,[0] Success
4-Sep-02 17:08:34,Local connection,1072,pibasess
WIN32 Named pipe,,
3.1,0,0
*----------
16,24,372707,[0] Success
4-Sep-02 17:09:13,Local connection,2059,PIPESCHD
WIN32 Named pipe,,
3.1,0,0
*----------
12,24,60055,[0] Success
4-Sep-02 17:08:49,Local connection,672,pisqlss
WIN32 Named pipe,,
3.1,0,0
*----------
13,24,9420677,[0] Success
4-Sep-02 17:08:57,Local connection,198466,pitotal
WIN32 Named pipe,,
3.1,0,0
*----------
14,24,154881,[0] Success
4-Sep-02 17:09:04,Local connection,2828,pibatch
WIN32 Named pipe,,

piconfig
3.1,0,0
*----------
15,20,12987712,[0] Success
4-Sep-02 17:09:12,Local connection,1618340,PipeE
WIN32 Named pipe,127.0.0.1,localhost
1.8,0,0
*----------
20,20,33340,[0] Success
4-Sep-02 17:43:44,Local connection,2715,RmpSE
1.8,0,0
*----------
21,20,50446,[0] Success
4-Sep-02 17:43:45,Local connection,3349,RandE
1.8,0,0
*----------
23,24,38287,[0] Success
5-Sep-02 15:01:35,Local connection,6,piconfig
WIN32 Named pipe,,
3.1,0,0
*----------
PINetMgr,720370.,3210534.,
5-Sep-02 14:52:23, ,8807.,PINetMgr
, ,
3.1,0.,0.
*----------
Delete connections
You can delete connections through piconfig with the PINETMGRSTATS table. To delete a
connection, first list the connections to get the appropriate ID. Then, in delete mode, specify
the ID.
* (Ls - ) PIconfig> @table pinetmgrstats
* (Ls - PINETMGRSTATS) PIconfig> @ostr id,name,contime
* (Ls - PINETMGRSTATS) PIconfig> @select id=*
* (Ls - PINETMGRSTATS) PIconfig> @ends
0,pigetmsg,8-Mar-05 07:55:09
1,pilicmgr,8-Mar-05 07:55:10
2,pitotal,8-Mar-05 07:55:10
3,piarchss,8-Mar-05 07:55:10
4,piupdmgr,8-Mar-05 07:55:10
5,pisqlss,8-Mar-05 07:55:10
* (Ls - PINETMGRSTATS) PIconfig> @mode delete
* (Dl - PINETMGRSTATS) PIconfig> @istr id
* (Dl - PINETMGRSTATS) PIconfig> 0
*> 0
* (Dl - PINETMGRSTATS) PIconfig>
Resulting message log message:
0 pinetmgr 8-Mar-05 14:02:06
>> Deleting connection: pigetmsg(2700), Administrator requested closing
connection pigetmsg(2700) (1121), ID: 0
Point class (PIPTCLS)

The point class database (PIPTCLS) contains all the point classes defined on a PI Data Archive
server. A point class defines the attributes of a PI point. This approach allows points to have
attributes specific to the point's role. For example, Totalizer points use a point class designed
specifically for the Totalizer needs.

piconfig
Important:
Edit point classes in stand-alone mode.
PIPTCLS Attributes Description

Class Name of the class.
SET The attribute set where attribute in the class were
defined. This attribute is only used in create mode.
It is used to specify the attribute sets which
comprise the point class.
ATTRIB Attribute name; a class has many of these.
DEFAULT Default value of the attribute.
TYPE... Data type of the attribute. For example, String,
Float32.
To list the point classes on the server:

* (Ls - PIPTCLS) PIconfig> @ostr class
* (Ls - PIPTCLS) PIconfig> @ends
*PIConfig Err> Wild-card specs. missing, default to '*'.
Alarm
base
classic
SQC_Alarm
Totalizer
This lists the classic point class; this class is built from the classic and base attribute sets:
* (Ls - PIPTCLS) PIconfig> @tabl piptcls
* (Ls - PIPTCLS) PIconfig> @mode list
* (Ls - PIPTCLS) PIconfig> @ostr attrib,default,type
* (Ls - PIPTCLS) PIconfig> @ostr ...
* (Ls - PIPTCLS) PIconfig> @istr class
* (Ls - PIPTCLS) PIconfig> classic
*> classic
descriptor,,String
exdesc,,String
typicalvalue,50.,Float32
engunits,,String
zero,0.,Float32
span,100.,Float32
pointtype,12,UBYTE
pointsource,Lab,String
scan,1,BYTE
.
.
.
datagroup,piadmins,String
dataaccess,o:rw g:rw w:r,String
datasecurity,"piadmin: A(r,w) | piadmins: A(r,w) | PIWorld: A(r)",String
pointid,0,Uint32
recno,0,Uint32
ptclassname,classic,String
ptclassid,2,Uint32
ptclassrev,1,Uint32
tag,,String
sourcetag,,String
compdevpercent,2.,Float32
excdevpercent,1.,Float32
* End Repeat...
* (Ls - PIPTCLS) PIconfig>

piconfig
Point database table (PIPOINT)

The most important configuration database is the PI point database. It contains the list of
points that are recorded in the PI Data Archive server (or mapped to points in foreign data
systems when COM Connectors are used).
The point database stores configuration information for each point as a list of point attributes.
For a complete explanation of the PI point classes and point attributes, see the PI Data
ArchiveSystem Management Guide.
The point database is tightly coupled with the Archive Table (PIARC) and the Snapshot table
(PISNAP and PISNAP2). The PI point database table name is PIPOINT. The primary key is TAG.

Access point class attributes
List attributes in the classic point class example
Modify an attribute in the point database
Modify the span point attribute example
Use operators to modify point attributes
Modify a nonexistent attribute
Add tags to the point database using Excel
Change a point type
Access point class attributes

To access the attributes of another point class, change the point class using the ptclassname
command. For example, to change to the Classic point class:
@table pipoint
@ptclass classic
@?atr
As a shortcut, you can specify the point class name while setting the PIPOINT table with a
singlepiconfig command:
@table pipoint,classic
Do not confuse the piconfig command ptclass with the attribute PtClassName.
When listing classic point attributes of non-classic points, attributes unique to classic will
appear to be blank.
List attributes in the classic point class example

When you first load the PIPOINT table, the point class defaults to Base. To see which additional
attributes are available using the Classic point class, select the Classic point class with the
ptclass command and list the attributes using the ?atr command.
(Ls - ) piconfig> @table pipoint
(Ls - PIPOINT) piconfig> @?atr
(Ls - PIPOINT) piconfig> @ptclass classic
(Ls - PIPOINT) piconfig> @?atr

piconfig
Modify an attribute in the point database

With the exception of point class and point type, the user-configurable point attributes in the
PI point database may be modified using piconfig. The syntax is:
@modify attribute=newvalue,attrib2=newvalue2,...
Modify the span point attribute example

In this example, the modify command is used to change the span for all tags starting with
MyTag:
@table pipoint
@mode edit
@modify Span=150
@select tag=MyTag*
@endsection
Use operators to modify point attributes

Values may be modified arithmetically by using the following operators:
attribute += value
attribute -= value
attribute *= value
attribute /= value
This example changes all tags with a point source of X to have a zero that is 10 units less than
its current value and increases the span to 110 percent of its current value:
@table pipoint
@mode edit
@select tag=*, pointsource=X
@modify zero-=10, span*=1.1
@endsection
modify specifications remain in effect until a table is changed. New modify specifications are
added to previous specifications until data is processed. After this, new specifications replace
previous ones.
Modify a nonexistent attribute

If you attempt to modify an attribute that a point does not have, such as a Classic attribute for a
point in the Base class, the following error message appears:
*Piconfig Error> Unknown parameter name in Modification name
Add tags to the point database using Excel

PI Tag Configurator is a Microsoft Excel add-in that you can use to configure PI points in a
spreadsheet. You can obtain PI Tag Configurator from the OSIsoft Technical Support Web site.
This section outlines a technique to develop a point configuration spreadsheet.

piconfig
The spreadsheet must contain a row for each tag and a column for each attribute, such as tag,
Pointsource, and pointtype.
Save the spreadsheet as an ASCII file with comma-separated values. Precede any non-data
lines in the file with a * comment character. That way, piconfig ignores them.
Heres an example data file, taglist.dat, generated from a spreadsheet in comma-separated
values (CSV) format:
RealTag1,Lab,float16
RealTag2,Lab,float16
Modify the following example structure file so that the attributes listed in the structure line
match the contents of the ASCII data file. Note that the tag name, as specified by the tag
attribute, is the only attribute that is required. Attributes that are not specified are given
default values.
Use create mode to create new tags; use edit mode to modify existing tags. Use create, t or edit,
t mode to create the tag if it does not exist and to modify it if it does exist.
*Example piconfig input structure file
*File name: example3.str
*
*Create or modify tags from input file taglist.dat*
@table pipoint
@mode create, t
@istructure tag, pointsource, pointtype
@input taglist.dat
@endsection
*
*List tags to verify creation or modification
*
@mode list
@ostructure tag, pointsource, pointtype
@select tag=*, pointsource=Lab, pointtype=float16
@endsection
@exit
Run piconfig using the structure file as input.

piconfig < example3.str
Change a point type

This example uses piconfig to change a point type to float 32:
@mode edit
@istru tag,pointtype
MyTag,float32
@ends
Point source table (PIPTSRC)

The point source table (PIPTSRC) provides a view into the PI point database. It provides an
option to add a description to every point source and to view how many points are in each
point source. Use the piconfig utility or PI SMT to view the point source table. The only
attribute that can be edited is the description.
The point source database is actually a view into the point source index of the point database.
It provides the ability to add a descriptor for each point source and to quickly view the number
of points per point source.

piconfig
PIPTSRC Attributes Description

Ptsrc The point source character or string
Code The internal code, used for point source update
signup
Count Number of points in this point source
Desc Free format descriptor
Snapshot table (PISNAP and PISNAP2)

The snapshot and snapshot2 tables provide access to PI Snapshot Subsystem, both for listing
or editing. The snapshot is the most recent event for a point. It can be viewed as a buffer that is
only one element deep. When a new event arrives, it becomes the new snapshot, unless it has a
timestamp older than the snapshot. The previous snapshot is evaluated according to the
compression specifications and is either sent to the event queue or discarded.
Events that have a timestamp older than the snapshot are sent to PI Archive Subsystem
through the event queue. These events are referred to as out-of-order events. Out-of-order
events are never evaluated for compression.
Event values are always stored in full precision in the snapshot. Scaling, if applicable, is applied
when the event is stored into the archive.
When the archive events for a point are listed or trended by PI ProcessBook and other tools,
the snapshot is included in the list if the requested listing covers the snapshot time.
The snapshot table resides in memory. Every 15 minutes or less, PI Snapshot Subsystem
flushes the table to disk, where it is stored in the piarcmem.dat file.
The table names are PISNAP and PISNAP2. The primary key is TAG.
PISNAP and PISNAP2 Attributes Description Comment
TAG The tag name (Read only)
PointID The point ID (Read only)
Type The point type (float32 ) (Read only)
Value
TIME Event timestamp in the format
DD-MMM-YY hh:mm:ss.ssss
TimeNum Timestamp as a number in
seconds past 01-Jan-70
Status The value status (Read only)
Flags (Q)uestionable, (M)odifed, Only Q is read/write
(A)nnotated
Annot Annotation
To read snapshot data, use list mode. To change the data, use edit mode. Other modes are not
applicable.
If a numerical snapshot value is invalid, the PI Data Archive server shows the value as Digital
State and the status attribute shows the digital state that describes the status. If a numerical
value is valid, the actual value is shown and the status attribute shows the digital state GOOD.

piconfig
To change a digital point value, you can specify either the digital state name or the numeric
offset (digital state number).
The file pisnap.dif, included with every system, is a quick way to list snapshot values.
$ piconfig input pisnap.dif
* (Ls - PISNAP) piconfig> @sele tag=c*
* (Ls - PISNAP) piconfig> @ends
CDEP158,2,GOOD,20-Nov-02 17:02:00
CDM158,Manual,GOOD,20-Nov-02 17:09:30
CDT158,53.03498,GOOD,20-Nov-02 17:10:00
The PISNAP2 table is useful for debugging classic PI API applications. It uses RVAL and ISTAT
attributes instead of Value and Status.
In PI 2.x, ISTAT for digital tags is the negative of the state number. In the PISNAP2 table, ISTAT
contains a 32-bit number that represents both set and state. The set number is in the most
significant 16 bits and the state number is in the least significant 16 bits. The system set
number is 0. Be aware that some PI API functions truncate the most significant 16 bits. String
values cannot be used in PISNAP2 table.
PISNAP2 Attributes Description
RVAL real values; or 0 for other point types
ISTAT Positive integer value for integers, status for
invalid real values, or set and state number for
digitals.

Add events to the data archive using the snapshot table
Add data using PISNAP2 table
Add events to the data archive using the snapshot table

Though interfaces normally add eventsalso known as value/time pairsto PI Data Archive,
you may want to use the snapshot table to add events to the archive for testing purposes. The
snapshot contains the most recent event for each tag. If you add an event to a tag in the
snapshot table, the previous event is archived if it passes the compression tests. Events with
timestamps earlier than the current snapshot timestamp bypass the snapshot table and are
sent directly to the archive. You can only view the most recent event in the snapshot table.
The tag name, time stamp, and value must all be specified. The time can be in any of the valid
PI time formats specified in the PI Data Archive System Management Guide.
Select the snapshot table and prepare for editing.

(Ls - ) piconfig> @table pisnap
(Ls - PISNAP) piconfig> @mode edit
Specify the format of the input data.
(Ed - PISNAP) piconfig> @istruc tag, time, value
The following lines are input data.
RealTag, 13-Aug-03 10:00, 3.81
RealTag, 13-Aug-03 10:05, 2.45
IntTag, *, 5
DigTag, T+8h, CLOSED

piconfig
Add data using PISNAP2 table

In the PISNAP2 table, use the rval and istat attributes instead of the value attribute. In this
example, a good and a bad value are added to PI:
(Ls - ) piconfig> @table pisnap2
* (Ls - PISNAP2) piconfig> @mode edit
* (Ed - PISNAP2) piconfig> @istru tag,time,rval,istat
* (Ed - PISNAP2) piconfig> sinusoid,*,50.0,0
> sinusoid,,50.0,0
* (Ed - PISNAP2) piconfig> sinusoid,*,0,-254
> sinusoid,*, 0,-254
To use the PISNAP2 table to add values to integer and digital tags requires setting the istat
attribute.
Subsystem table (PISUBSYS)

The PI subsystem table (PISUBSYS) shows subsystem-specific attributes and statistics. This
read-only table is useful for troubleshooting. To load this table, the subsystem in question
must be specified. The table name is PISUBSYS. For example, to view attributes associated with
pisnapss, type the following command:
piconfig> @table pisubsys,pisnapss
The set of attributes available varies by platform. The table has the following attributes:
PISUBSYS Attributes Description Operating System
PISubsysName Subsystem name All
IDNumber Unique ID of computer UNIX (Not all versions of UNIX
support this attribute)
Machine Hardware ID UNIX
OSNodeName TCP/IP host name UNIX
OSRelease Operating system release UNIX
OSBuild Operating system build Windows
OSSysName Operating system name All
OSVersion Operating system version All
PIStartupTime Subsystem startup time All
PIVersion Subsystem version All
View PI subsystem information

Here's an example listing attributes of the PI subsystem table.
To list the record, use the ostructure command and specify pisubsysname as *:
(Ls - PISUBSYS) piconfig> @ostr pisubsysname
(Ls - PISUBSYS) piconfig> @ostr osbuild, osversion
(Ls - PISUBSYS) piconfig> @ostr pistartuptime, piversion
(Ls - PISUBSYS) piconfig> @selec pisubsysname=*
(Ls - PISUBSYS) piconfig> @ends
pisnapss

piconfig
Service Pack 2,5.2.3790

29-Jul-10 12:00:48,PI 3.4.380.36
The operating system attribute names may vary because they are operating system dependent.
Subsystem Statistics table (PISUBSYSSTATS)

The PI Subsystem Statistics table shows detailed subsystem statistics. This read-only table also
requires subsystem specification. The table name is PISubSysStats. For example, to view
statistics for pisnapss enter the following command:
piconfig> @table pisubsysstats,pisnapss
PISubSysStats Attributes Description

PISubsysName Subsystem name.
BytesRecv Number of bytes received since startup.
BytesSent Number of bytes sent since startup.
MsgRecv Number of messages received since startup.
MsgSent Number of messages sent since startup.
RecvErrors Number of receive errors since startup.
SendErrors Number of send errors since startup.
StartTime Subsystem startup time.
The bytes and messages received and sent refer to all inter-process communications.
View PI subsystem statistics

This example lists the statistics for pisnapss. There is no primary key, so specify
PISubSysName name as *:
(Ls - PISUBSYSSTATS) piconfig> @ostr PIsubsysname
(Ls - PISUBSYSSTATS) piconfig> @ostr bytesrecv, bytessent
(Ls - PISUBSYSSTATS) piconfig> @ostr msgrecv, msgsent
(Ls - PISUBSYSSTATS) piconfig> @ostr recverrors, senderrors
(Ls - PISUBSYSSTATS) piconfig> @ostr starttime
(Ls - PISUBSYSSTATS) piconfig> @select pisubsysname=*
(Ls - PISUBSYSSTATS) piconfig> @ends
pisnapss
99626,57637
434,432
0,0
4-Sep-02 17:08:19
Some PISUBSYSSTATS tables also contain subsystem-specific data. This data is usually
presented for troubleshooting purposes. After setting a PISIBSYSSTATS table, always show the
available attributes with the @?atr command.
Server table (PISERVER)

This table contains PI Data Archive configuration and status information. If the PI Data Archive
server is part of a PI Data Archive collective, the table contains one row for each server in the
collective.

piconfig
The primary key is NAME. The value in Collective must match the value of Name in the
PICOLLECTIVE table.
This example displays the name, FQDN and server ID:
* (Ls - ) PIconfig> @mode list
* (Ls - ) PIconfig> @tabl pisys,piserver
* (Ls - PISYS,PISERVER) PIconfig> @ostr name,fqdn,serverid
* (Ls - PISYS,PISERVER) PIconfig> @sele name=*
* (Ls - PISYS,PISERVER) PIconfig> @ends
PiServer1,PiServer1.osisoft.dom,12db4fde-963d-4f47-bc43-65f9e026502c
* (Ls - PISYS,PISERVER) PIconfig>
Attribute Type Editable Example Description

Name String Primary uc-s2 Computer host
name (non-
qualified). Unique
key in the
PISERVER table.
Each server uses
this to find its own
entry in the table.
Collective String Primary uc-s1 Name of the
collective that the
server belongs to.
Must match
collective name
defined in
PICOLLECTIVE
table.
CommPeriod Int32 Primary 20 Frequency (in
seconds) that
secondary server
checks that it can
communicate with
primary server.
Default value is 5.
CommStatus Int32 no 0 Status of the last
secondary PI Data
Archive
communication
with the primary
server (0 is good).
Description String Primary UC 2006 Demo Optional
Server 2 description for the
server.
FQDN String Primary uc-s2.mycomp.com FQDN or IP
address used to
connect to
collective servers.
IsAvailable BYTE no 1 1 if available for
client access, 0
otherwise. Derived
from all other
status fields in the
table.

piconfig

IsConnectedToPri BYTE no 1 1 indicates that the
mary secondary PI Data
Archive server is
connected to the
primary PI Data
Archive server.
Always 1 on the
primary PI Data
Archive server.
IsCurrentServer BYTE no 1 1 on the
responding PI Data
Archive server, 0
for all others.
IsTCPListenerOpen BYTE no 1 1 indicates this PI
Data Archive
server TCP/IP
listener is open.
LastCommTime TimeStamp no 12-Apr-06 Last time the
14:00:17 secondary PI Data
Archive sever
communicated
status to the
primary PI Data
Archive server.
LastSyncRecordID Uint64 no 68 Number of changes
each PI Data
Archive server
applied to the
replicated tables.
LastSyncTime TimeStamp no 12-Apr-06 Last time
14:00:17 synchronization
succeeded on any
secondary PI Data
Archive server.
NumConnections Uint32 no 11 Total number of
connections on the
specific PI Data
Archive server.
PIVersion String no 3.4.375.29 Version of PI Base
Subsystem.
Port Uint32 no 5450 TCP/IP port
number for
communicating to
PI Data Archive.
Role Int32 Primary 2 0 for non-
replicated; 1 for
primary; 2 for
secondary.

piconfig

ServerID String Primary 08675309-0007-0 A UID representing
007-0007-000000 the unique PI Data
001002 Archive server
identification.
SyncFailReason String No Reason that
synchronization
did not succeed.
SyncPeriod Int32 Primary 10 Frequency (in
seconds) that
secondary server
checks for
configuration
updates from
primary server. 0
indicates no
automatic
synchronization.
SyncStatus Int32 no 0 On secondary
servers: the status
the last time that
synchronization
was attempted (0
is good)
UnavailableReason String no
NewName String Used to rename an
existing server.
Thread table (PITHREAD)

Use the PITHREAD table to view thread activity within the subsystem processes, primarily
when troubleshooting. To load this table, specify the subsystem in question. For example, to
view attributes associated with PI Snapshot Subsystem, type:
piconfig> @table pithread,pisnapss
Note:
The PITHREAD table is primarily a monitoring tool. We recommend using it only with in-
depth understanding of threads. Specifically, avoid using it for any modification or thread
creation.
PITHREAD Attributes Description

ID Operating system thread ID
Action Edit only. See the following table
ActValue Edit only. Value for the action performed
Calls Number of calls served by the thread
ConnectID pinetmgr connection ID of the last client process
serviced by this thread
CurTime Time spent processing the current RPC request; in
milliseconds

piconfig
PITHREAD Attributes Description

Handle Subsystem handle
HandleHighBits Additional subsystem handle information
LastTime Time spent processing the most recently
completed RPC request; in milliseconds
PointID ID of the point involved in the last operation
performed by this thread
PoolName Every thread belongs to a thread-pool. We are
mainly interested in the RPC thread pool, which
serves client calls to a subsystem.
Priority The thread priority
RPCName Name of the last RPC processed by the thread.
State The thread state - generally Wait or InUse
PITHREAD Actions Description Action Value

Priority Change thread priority 1 to increase -1 to decrease
Suspend Temporary suspensions of
thread execution
Resume Resume a thread previously
suspended
Terminate End this thread
For example:
* (Ls - ) PIconfig> @table pithread,piarchss
* (Ls - PITHREAD) PIconfig> @ostru id,calls,handle,poolname,priority,state
* (Ls - PITHREAD) PIconfig> @ends
1500,7,212,RPC,0,Wait
1596,9,216,RPC,0,Wait
1504,11,220,RPC,0,Wait
1116,18,224,RPC,0,InUse
2124,9,228,RPC,0,Wait
3664,8,232,RPC,0,Wait
2592,9,236,RPC,0,Wait
3812,7,240,RPC,0,Wait
1216,0,816,EVQ,0,Wait
2488,0,820,EVQ,0,Wait
2736,0,824,EVQ,0,Wait
3140,0,828,EVQ,0,Wait
3012,0,832,EVQ,0,Wait
2356,0,840,Shift,0,Wait
3336,655015,0,Main, ,
3888,166401,248,Message, ,
3016,190,260,Read, ,
Timeout table (PITIMEOUT)

The PITIMEOUT table stores PI Data Archive configuration and tuning parameters. PI Data
Archive is designed to work optimally using the default settings for these parameters. OSIsoft
recommends that you use the default values unless you are directed to do otherwise by
Technical Support, Field Service, or other OSIsoft personnel.

piconfig
@table pitimeout
The primary key is NAME. The PITIMEOUT table cannot be modified remotely.
PITIMEOUT Attributes Description
Name Tuning parameter name
Value Tuning parameter value as a string
NEWName Used to rename an existing name
This example disables the DefaultUserAccess parameter:

* (Ls - ) PIconfig> @table pitimeout
* (Ls - PITIMEOUT) PIconfig> @mode edit,t
* (Ed - PITIMEOUT) PIconfig> @istr name,value
* (Ed - PITIMEOUT) PIconfig> DefaultUserAccess,0
*> DefaultUserAccess,0
* (Ed - PITIMEOUT) PIconfig>
Trust table (PITRUST)

The PITRUST table allows a client application to connect to the PI Data Archive server as a
specific PI user without requiring that the client application enter a user name and password.
Such access is necessary for applications that run unattended, such as PI interfaces. When you
configure trusts, credential attributes such as Domain name, IP host name, IP address,
Application name, and Operating System Username are stored in the trust table.
Note:
Although you can create trusts to support single sign-on, OSIsoft recommends that you
instead use PI identities and PI mappings for this purpose.
The client and PI Data Archive obtain the client's credentials from the operating system,
domain controller, and network software. These include any of the following: domain name, IP
host name, IP address, and user name.
@table PITRUST
The primary key is TRUST.

PITRUST Attributes Description
Trust A name for this trust relationship
Domain The domain name for the client machine
IPAddr IP address of client machine
NetMask Network address mask in the format
(255.255.255.255)
IPHost Name of client machine
OSUser User name under which the client is running
AppName Application name
PIUser Associated PI user
Description Explanation of the purpose of this trust

piconfig
PITRUST Attributes Description

Flags For internal use only; controls enabling/disabling
the trust
Any field specified as NULL string (""), is ignored when incoming connection are matched
against the table.
Domain, IPHost, AppName, and OSUser must be specified exactly or not at all.
IPAddr and NetMask must be specified together. If you provide a value for one, you must also
provide the other.
PIUser must always be specified as either a currently existing PI user in the user database, a PI
group in the group database, a PI identity, or as a dollar sign ($). The dollar sign must be paired
with a $ in either or IPHost. If the trust matches incoming credentials and there is no PIUser
with the same name, an error occurs at run-time. This method of specification matches any
user or any machine that passes the domain controller validation of their login credentials.
To create a trust , type:
@table pitrust
@mode create
@istr Trust,IPHost,PIUser
YourTrustName,server.domain.int,JohnDoe@ends
Users table (PIUSER)

With PI Data Archive 3.4.380 and later, data from the PI user and PI group tables is moved to
the PI identity table. However, the PI user table is preserved for backward compatibility; it
provides a list of PI users, as they existed in previous releases.
With PI Data Archive 3.4.380, OSIsoft recommends that you use the PI identity table to create
and access all PI identities. However, the PI User table continues to function as it did in
previous releases and can be used to view and update PI Users. The PI User Table must still be
used to edit group memberships.
For details about how to use PI Identities of type PI User, see PI Data Archive Security
Configuration Guide.
This table defines PI users and records their assignment to groups. The primary key is User.
PIUSER Attributes Description
User User name
Description User description
Groups List of groups to which the user belongs
Context Reserved for future use
NEWUser Used to rename an existing user
The description attribute is used to specify any type of user information, such as address or
title. The user may be added to multiple groups.
Users are assigned to groups using the PIUSER table. Attempting to change the group
membership of users via the PIGROUP table has no effect.
This example adds a user called testuser1 to the groups piadmins and piusers:

piconfig
@table piuser
@mode create
@istr user, description, groups, ...
testuser1, Test User 1, piadmins, piusers
@ends
@exit
Enter piconfig commands

After you select a table, use piconfig commands to retrieve and possibly change the data in
the table.
Some commands change the operational mode of piconfig. For example, you can use the
mode command to change from list mode (read only) to create mode, delete mode, or edit
mode.
To see a list of piconfig commands, type:
* (Ls - PIPOINT) piconfig> @help

List information about a point
Set a tuning parameter with piconfig example
List information about a point

This example selects points that have an attribute tag starting with the letter S and the point
source R. R is the default point source for the random interface. All the tags that match these
criteria will have their tag, point source, and point type displayed.
Select the table that you want to view. In this case, select the PIPOINT table to view the PI point
database.
$ piconfig
* (Ls - ) piconfig> @tabl pipoint
* (Ls - PIPOINT) piconfig> @mode list
* (Ls - PIPOINT) piconfig> @stype delimited
* (Ls - PIPOINT) piconfig> @ostructure tag, pointsource, pointtype
* (Ls - PIPOINT) piconfig> @select tag=s*, pointsource=R
* (Ls - PIPOINT) piconfig> @endsection
SINUSOID,R,Float32
SINUSOIDU,R,Float32
SQF100,R,Float32
SQF101,R,Float32
* (Ls - PIPOINT) piconfig>
*> @exit
0 Data lines
7 Command lines
0 Records in error
4 Records Listed
Set a tuning parameter with piconfig example

On a PI Data Archive server, tuning parameters can be set using PI SMT, but on interface nodes,
they can only be set using piconfig.

piconfig
This example selects the PI timeout table and specifies create mode. The command @istr
name,value specifies that an input structure consisting of a parameter name and value will be
entered to create a new record in the PI timeout table. Next, the name and value
(MessageLog_DayLimit,60) are entered, creating the tuning parameter
MessageLog_DayLimit and setting its value to 60. The MessageLog_DayLimit tuning parameter
specifies the number of days messages will be retained in the PI message log.
c:\Program Files\PI\adm>piconfig
* (Ls - ) PIconfig> @tabl pitimeout
* (Ls - PITIMEOUT) PIconfig> @mode cr
* (Cr - PITIMEOUT) PIconfig> @istr name,value
* (Cr - PITIMEOUT) PIconfig> MessageLog_DayLimit,60
*> MessageLog_DayLimit,60
* (Cr - PITIMEOUT) PIconfig> @quit
PIconfig 1 Data lines
4 Command line
0 Records in error...
1 Records Created
Modes of the piconfig utility

The piconfig utility has the following modes:
(Ls) List mode (read only) Output formatted records from a
table to screen or file
(Cr) Create mode (add) Create new records in a table
(Ed) Edit mode (modify) Modify or rename existing
records
(Dl) Delete mode Delete records from a table
(Cv) Convert mode Convert input data from one
format into another
(Cm) Compare mode Compare file data to table data

Combine create and edit modes
Use the check-only modifier
Combine create and edit modes

Enter the character t, for true, with either create or edit mode to combine the modes.
@mode create, t
@mode edit, t
Use these combined modes to modify existing records and create non-existent records
simultaneously. The specified mode persists until the next mode command is issued.
Use the check-only modifier

Use the check-only modifier to validate points and report errors, but not make changes to the
PI point database.

piconfig
Enter the character c, for check, with either create or edit mode to combine these modes
without making changes to the PIPOINT table:
@mode create, c
@mode edit, c
Note:
The check-only modifier applies only to the PIPOINT table. For all other tables, this mode
is identical with the normal edit or create mode.
Check mode can also be specified for create or edit mode:

@mode create, t, c
@mode edit, t, c
The specified mode persists until the next mode command is issued.
Data structure types

The structure type (stype) indicates the format of the data structure used to specify input and
output.
The possible structure types are:
Delimited (default)
Fixed
Keyword
To specify an output structure type that differs from the input structure type, use theostype
and istype commands instead of the stype command.
The specified structure type persists until the next structure type command.

Structure specifications persistence
Delimited format
Fixed format
Keyword format
Convert fixed format to delimited format
Structure specifications persistence

Structure specifications for both input and output remain in effect until the table is changed.
Before any data is processed, new structure specifications are added to previous specifications.
After some data was processed, new structure specifications replace the previous ones.
You can check which structure specification is in effect as follows:
@ostructure ?
@istructure ?

piconfig
Delimited format
In delimited format, one or more lines of comma-separated attributes describe the format of
the data. One or more lines of comma-separated data values follow. These lines correspond to
the attributes. For example:
@istructure tag, pointsource,pointtype
SINUSOID,R,FLOAT32
You can change the delimiter from a comma to another non-alphanumeric character (Change
the delimiter character).
Note:
The command character @ distinguishes commands from data. Commands must be
preceded by @ or piconfig will interpret the string as data.
Fixed format
In fixed format, data structure includes one or more lines specifying the attribute, line number,
starting position on the line (counting from 1), and field width. For example:
@istructure tag, 1, 1, 12
@istructure pointsource, 1, 14, 1
@istructure pointtype, 1, 19, 7
*
*234567890123456789
SINUSOID R FLOAT32
NEXTPOINT Lab FLOAT16
The lines starting with the asterisk (*) are comment lines and are ignored. Their only purpose
is to improve readability. You can change the comment character (Change the comment
character).
The format lines come first and are all grouped together. This defines a record. If there are
more data lines than are specified in the record, piconfig interprets these as additional
records of the same format.
Fixed format is also used in the OpenVMS PI System PIDIFF utility.
Keyword format
In keyword format, every input line contains only two parts: the attribute and the value for
that attribute, separated by the delimiter character. The default delimiter character is a
comma(, ).
Theistructure command is not used with this format, as each line contains both data and its
description. For example:
tag, SINUSOID
pointsource, R
pointtype, FLOAT32
To select output attributes in keyword format, use the ostructure command. Specify a single
attribute on each line:
@ostructure tag
@ostructure pointsource
@ostructure pointtype

piconfig
To output all attributes for the current table, type:

@ostructure *
This works in both keyword and delimited formats.

Note:
The @ostructure command is meaningful only in list mode. A warning is issued if this
command is executed in create, edit or delete mode.
Convert fixed format to delimited format

The following is a simple example of converting fixed format data into delimited format. This
can be helpful in PI2 to PI3 conversions. Convert mode can be used to reorder fields in a record
or to apply modifications to data.
C:\Program Files\PI\adm>type fixed.dat
*23456789012345678901234567890
Tag1 0 100
tag2 -5 555
C:\Program Files\PI\adm>piconfig mode convert
* (Cv - ) PIconfig> @table pipoint
* (Cv - PIPOINT) PIconfig> @isty fixed
* (Cv - PIPOINT) PIconfig> @osty delim
* (Cv - PIPOINT) PIconfig> @istru tag,1,1,9
* (Cv - PIPOINT) PIconfig> @istru zero,1,10,5
* (Cv - PIPOINT) PIconfig> @istru span,1,20,5
* (Cv - PIPOINT) PIconfig> @ostru zero,span,tag
* (Cv - PIPOINT) PIconfig> @modify span+=100
* (Cv - PIPOINT) PIconfig> @echo none
* (Cv - PIPOINT) PIconfig> @input fixed.dat
0 ,200.,Tag1
-5 ,655.,tag2
Display repeating attributes

Structure specifications may contain table attributes followed by an ellipsis (). The ellipsis
indicates that the last attribute may be repeated a variable number of times within a single
record. If the ellipsis () is on a separate line, it indicates that the last (previous) structure line
may be repeated a variable number of times.
In most cases, delimited format is more suitable for repeatable attributes.
In fixed format only complete lines can be repeated. A single field cannot be repeated on the
same line in fixed format because its field length is fixed.
The ellipsis construct can be used for both input and output.
Use the ellipsis construct

List multiple states in the MODES state set in comma-separated format.
* (Ls - PIDS) piconfig> @ostructure set,state,...
* (Ls - PIDS) piconfig> @select set=modes
* (Ls - PIDS) piconfig> @endsection
MODES,Manual,Auto,Cascade,Program,Prog-Auto

piconfig
The ellipsis is useful where the same attribute can occur more than once in a single record. For
example, a state set contains variable number of states. A point class contains a variable
number of attributes and their defaults.
Select database records

Use the select command to select records of interest. Use any combination of attributes. In
list mode only, the primary key specification defaults to * (all records). In edit or delete modes,
you must include the primary key in the select specifications. To be selected, records must
match all selection criteria.
Select specifications remain in effect until the mode or table is changed. Until a command is
processed, select specifications are added to previous specifications. After that, a new select
specification replaces the previous ones.
To check the select specifications currently in effect, type:
@select ?

Comparison operators
Wildcards
Comparison operators
Use these comparison operators with the select command:
= equal
<> not equal (!= also works)
> greater than
>= greater than or equal to
< less than
<= less than or equal to
These operators can be used for date, numeric or text fields. Text comparison is based on
ASCII values.
Wildcards
Wildcards, * and ?, may be used in text fields. * matches all characters; ? matches a single
character.
Trigger record processing

The endsection command triggers the processing of selected records. It is not always
necessary to use an endsection command. An endsection is assumed when the end of file
is reached or when a command follows lines of data.
When an input structure is specified, every record is processed as data is entered.

piconfig
The following example demonstrates how processing occurs in both ways:

d:\pi\adm>piconfig table pisnap
* (Ls - PISNAP) piconfig> ostru tag,value,time
*> ostru tag,value,time
* (Ls - PISNAP) piconfig> @sele tag=sinusoid
* (Ls - PISNAP) piconfig> @ends
SINUSOID,86.71634,20-Nov-02 16:25:30
* (Ls - PISNAP) piconfig> @istru tag
* (Ls - PISNAP) piconfig> sinusoid
*> sinusoid
sinusoid,86.71634,20-Nov-02 16:25:30
Batch methods
Prepare input files
Pass an input file as a parameter
Redirect an input file
Capture output and errors in files
Pass commands as parameters
Redirect output
Reuse an output file as an input file
Prepare input files

Entering commands by hand in interactive sessions can be prone to errors. It is often easier to
enter the commands in a text file, save it, and then use that file as input to later piconfig
sessions. This is particularly useful for maintaining the point database using a spreadsheet.
Comments can be added to the text file for better readability.
For example, suppose you decided to list points with names starting in S and pointsource=R,
including tagname, pointsource and pointtype. You could specify delimited output structure.
To do all this, you could prepare and save an ASCII file named list.inp:
* list.inp *
* This piconfig script file lists the tagname, pointsource,
* and pointtype for all tags that start with "S" and
* that have point source R
*
@table pipoint
@mode list
@stype delimited
@ostructure tag, pointsource, pointtype
@select tag=s*, pointsource=R
@endsection
Start piconfig and run this input file using the input command:
$ piconfig
4 (Ls - ) piconfig> @input list.inp
The following output is generated:

piconfig
SINUSOID,Float32,R
SINUSOIDU,Float32,R
SQF100,Float32,R
SQF101,Float32,R
4 (Ls - PIPOINT) piconfig>
Pass an input file as a parameter

An alternative is to pass the input file as a parameter on the command line. The piconfig
utility takes each pair of input parameters and treats the first as a command and the second as
the command parameter:
$ piconfig input list.inp
SINUSOID,Float32,R
SINUSOIDU,Float32,R
SQF100,Float32,R
SQF101,Float32,R
4 (Ls - PIPOINT) piconfig>
Redirect an input file

Use the standard redirection from the command line:
$ piconfig < list.inp
SINUSOID,Float32,R
SINUSOIDU,Float32,R
SQF100,Float32,R
SQF101,Float32,R
piconfig 0 Data lines
6 Command lines
0 Records in error...
4 Records Listed
Input files may contain all data, all commands, or mixed commands and data. Input files may
be nested; that is, an input file can refer to other input files.
Capture output and errors in files

The piconfig utility output and errors are displayed by default on the computer screen. Use
the output and error commands to redirect this output in a file.
$ piconfig
*>@output list.out
*>@error errors.out
By default piconfig echoes the input commands and input data in the file, as well as the
output data. If you wish to see only the output data in the file, use the echo command with the
data option:
*> @echo data
Pass commands as parameters

You can pass the commands on the piconfig command line. takes each pair of input
parameters and treats the first as a command and the second as the command parameter:
$ piconfig output list.out input list.inp

piconfig
Redirect output
Use standard redirection from the command line:
$ piconfig < list.inp > list.out
Reuse an output file as an input file

Redirecting the output to a file is very useful because you can reuse the output file as an input
file with other piconfig commands. For example, suppose you want to create a tag that is
similar to another tag that already exists on the PI Data Archive server. For example, the
tagname and the hardware address are the only differences; the descriptor, zero, span,
pointtype, pointsource, and engineering units are the same.
To reuse an output file as an input file, list all of the point attributes of the existing tag to a file.
Then use a text editor to modify the tag name and hardware address. Use the file as input to
piconfig to create the new tag.
Security for a piconfig session

Users of the piconfig utility can be required to log on to the PI database by specifying a user
name and a password. This option is turned on by setting the PI Data Archive server tuning
parameter CheckUtilityLogin to 1.
By default this option is off.
Helpful hints
Abbreviations
All piconfig commands can be abbreviated to four characters.
Case sensitivity
Windows program and file names are case-preserving, but not case-sensitive.
The piconfig commands, attribute names and table names are not case-sensitive, but the
data are case-sensitive. The case-sensitivity on the timeout, firewall, and trust tables may be
changed for both of these parameters by using the case command.
Command input files

The piconfig commands and data can be placed in any number of files and executed using
theinput command.
If the input file contains many lines, all of which have the same command, a command input
file may be useful:

piconfig
@command @command_file
In a command file, the command specified is prepended to every line in the command file. This
is useful, for example, when a file with input structure lines have been generated from another
program, such as PIDIFF, or when the same complex structure is used for both input and
output. For example, if the file cmds.txt contains the following lines:
tag,pointtype,pointsource
ptowner,ptgroup,ptaccess
ptsecurity
dataowner,datagroup,dataaccess
datasecurity
You can execute these commands by entering the following at the piconfig prompt:
@istructure @cmds.txt
The commands in the file are executed as follows:

@istructure tag,pointtype,pointsource
@istructure ptowner,ptgroup,ptaccess
@istructure ptsecurity
@istructure dataowner,datagroup,dataaccess
@istructure datasecurity
This technique works for both piconfig scripts and for interactive sessions.
Input line length

By default, piconfig reads from its input up to 1024 characters. This is sufficient in almost
all cases.
If the input contains lines longer than 1024 characters, reset the input buffer using the line
command, for example:
@line 4000
Quoted strings
There are two reasons to use quotes (single or double) with piconfig data:
The data contains an embedded delimiter character that will confuse correct parsing either
on input or on output that is used in the future by piconfig itself or by other applications
(such as Microsoft Excel).
The specific table requires certain data to be enclosed in quotes (single or double) for its
own further processing. Examples include the PI Batch tables and the Performance
Equation expressions configured in the extended-descriptor of a point.
piconfig attempts to parse incoming data into fields using the delimiter character. If a field
starts with a quote (either single or double), piconfig ignores any delimiter until a matching
quote is found.
When an already quoted string must contain embedded quotes, there are two options:
Enclose strings containing double quotes in single quotes and vice versa
Escape the embedded quotes with a backslash (\)
A field containing the delimiter character must be quoted. A field that starts with a quote
should be quoted using the other type of quote. A field that starts with one type of quote and
contains the other type as well should be quoted, and the embedded quotes must be escaped.

piconfig
For example, a field containing:

unit,function
should be specified as
"unit,function"
or
'unit,function'
The expression
'sinusoid' > 'tag33'
"'sinusoid' > 'tag33'"
or
('sinusoid' > 'tag33')
The expression
'sinusoid' + "t-1d" + "ABC"
"'sinusoid' + \"t-1d\" + \"ABC\""
When the output from piconfig is used in another session or by another program such as
Excel, make sure that fields containing the delimiter character are quoted (on output). Using
the quote command does this:
@quote "
or
@quote '
Sending values as strings

piconfig sends all table values as strings. When sent to the snapshot (archive values go via
the snapshot), it is interpreted as follows:
For a string tag
Use the incoming string without change.
For a digital tag:
Look for a state in the tag's state set.
Look for a state in the System digital set.
Interpret the string as a numeric offset and check if within range of the tag's set.
For all other tag types:
Look for a state in the System digital set.
Convert the string to a value of the tag's type.
Boolean values
When a field in any table is a Boolean flag, for example the step flag in the PIPOINT table, the
input data can be specified as:

piconfig
1 / 0
Yes / No
True / False
piconfig always sends the data to the table as a string as explained above.
The table owner, in this example PI Base Subsystem, interprets the incoming string as a
Boolean value 1 / 0.
This can cause some confusion in the digital states table when states are defined as the strings
1, 2, 3, and so on. We recommend that you configure digital states like this: "One, Two, " or
"State1, State2, "
Similarly, to define the states "true", "false", make a set with "false" in the first position
followed by "true" to correspond to 0 and 1. Alternatively, modify the names slightly; such as
"S-true", "S-false".
Configuration persistence
Table specifications remain in effect until the next table command. Mode specifications
remain in effect until the next mode command.
For all structure formats, the structure specifications remain in effect until a table is changed.
New structure specifications are added to previous specifications until they are used to
process data. After this, new specifications overwrite previous ones. Select and modify
specifications behave similarly. These two commands are also cleared on mode and table
changes.
Command line parameters

The piconfig commands may be specified as command-line parameters when invoking
piconfig. Each pair of parameters is assumed to be a command. These commands are
executed before the first prompt is issued. Some examples are:
$ piconfig comchar ?
$ piconfig table pipoint stype fixed
$ piconfig help
Special characters in piconfig

piconfig uses special characters that include:
command character (ComChar)
comment character (comment)
delimiter character (delimiter)
quote character (quote)
Note:
Specifying a quote character causes any field containing the delimiter character (comma
by default), to be enclosed with the specified quote character. See Quoted strings.

piconfig

Change the command character
Change the delimiter character
Change the comment character
Change the command character

The default command character is the at symbol (@). You can change the command character
to any single, visible character that is not a number or a letter.
Procedure
1. Run piconfig.
2. At the piconfig prompt, type:
@Comchar NewCommandCharacter
For example., to change the comment character to an exclamation point (!) you would type
@Comchar !
Change the delimiter character

The default delimiter character is a comma ( , ). You can change the delimiter character to any
single, visible character that is not a number or a letter.
Note:
The same delimiter character is used between piconfig attributes, between elements of a
piconfig command, and between both input and output data fields.
Procedure
1. Run piconfig.
2. At the piconfig prompt, type the delimiter command, followed by the new character.
For example, to change the delimiter character to a backslash ( \ ) you would type:
@delimiter \
Change the comment character

The default comment character is the asterisk (*). You can the comment character to any
single, visible character that is not a number or a letter.
Procedure
1. Run piconfig.
2. At the piconfig prompt, type the comment command, followed by the new character.
For example, to change the comment character to an exclamation point (!) you would type:
@comment !

piconfig
Display current settings with status command

To display the currently assigned characters, mode, and table, use the status command.
* (Ls - ) PIconfig> @table pipoint
* (Ls - PIPOINT) PIconfig> @status
---- PIconfig Status at 30-Jul-10 11:52:32 ----
Mode: List
Decimal digits displayed: -7
Characters: Command: <@> Delimiter: <,> Comment: <*> Quot: <"> Var: <%>
Struc. Type IN: <Delim.> OUT: <Delim.>
Error count: 0 Max: 10 Last Error: Abort
Current table: <PIPOINT> Cur. Prim.: <#####> Def. Prim: < >
Nesting level : 0
Node: <127.0.0.1,piadmin>
Hexadecimal and octal numbers

By default, piconfig uses decimal notation (base 10). To specify numbers in octal, precede
them with 0. To specify numbers in hexadecimal, precede them with 0x. For example, the
numbers 10, 012, and 0xA specify the same number.
Use the login command to change to another server

If you already have a piconfig session in progress, you can switch to a different PI Data
Archive server using the login command. The login command takes four parameters:
Remote PI Data Archive host name, or IP address
Remote PI Data Archive user name
Remote PI Data Archive password
Remote PI Data Archive port ID (usually 5450)
See also Remote operation of PI Data Archive utilities.
Procedure
For example, at the piconfig command prompt, type:
@login figaro, piadmin, myadminpassword, 5450
Once the login command is issued, all subsequent commands are executed on the remote PI
Data Archive server.
Turn piconfig prompting on or off

When run interactively piconfig issues a prompt after each command.
To turn prompting on or off:
@prompt yes
@prompt no
When turned on, the prompt indicates the piconfig mode and the current table name in
parentheses. The table name in the prompt is set when you issue the @table command:
* (Ls - ) piconfig> @table pipoint
* (Ls - PIPOINT) piconfig> @help

pidiag
Use the pidiag utility to diagnose, retrieve information about, and perform simple repairs of,
PI Systems.
Caution:
Never use open files with tools that perform operations on files, such as compact and
repair options. In general, use such tools only when the system is in an inactive state. If
you are unsure about how to use these tools, consult OSIsoft Technical Support before
using them. Make a backup copy of the data file before you attempt any operations.
Run the pidiag utility from the ..\PI\adm directory.

To invoke pidiag, type:
pidiag -xxx
where xxx identifies a command line option. Depending on the specific option, you might
include additional arguments.

Options for the pidiag command
Display pidiag version number
Interpret error codes
Archive management with the pidiag utility
Event queue files management
Licensing management
Miscellaneous commands
Options for the pidiag command

Italics indicate a value that must be supplied. Square brackets ([]) indicate that a value is
optional. Items separated by vertical bar (|) denote options that are mutually exclusive; only
one of the items can be used.
Option Description
-ad [path] Lists archive files known to PI Data Archive.
-ahd Lists information about unregistered archive files.
-ar [path] Creates a new archive manager data file.
-ara Recovers the archive manager data file.
-archk path [complete] Generates a report on an archive file.
-cpc [-fix] Checks performance counters, reports any problems found, and
optionally fixes certain problems.
-crash Simulates a process crash.

pidiag
Option Description
-did Dumps the server ID file; used for troubleshooting PI collectives.
This command works only when the server is not running. When
the server is running, use Collective Manager or piconfig with
the pisysdump.dif file.
-e code Displays the message associated with an error code.
-ecert [path] Exports the server certificate to a file.
-gap path [-time=secs] [- Estimates gaps in data for an archive. By default it samples the
sample=percent] [- most active 10 percent of tags where the archive gap is at least
matching=percent] 300 seconds long and is uniform across 90 percent of the sampled
tags.
-host Displays host information as used for trust login.
-host -file filename Produces machine signature file (for licensing).
-host -lictocsf licfile csffile Extracts the cluster signature from a license file and stores in a
cluster signature file
-host -lictomsf licfile msffile Extracts the machine signature from a license file and stores in a
machine signature file.
-icert [path] Imports the certificate file to the certificate store.
-qd [HeaderOnly Header| RecNo=n | Dumps header or all/filtered events from the event-queue file.
PointId=ID] path
-qs path Displays statistics of an offline event-queue file.
-tz [ -if path | -ifrule [path] ] [-of Customizes Standard and Daylight Saving Time changes.
path]
-tz [time[TZ]] [ -check | -dump [- Shows time-zone information.
brief] |-full]
-udf path Resets the piadmin (userid #1) password to blank.
-v Shows version information.
Display pidiag version number

Procedure
pidiag -v
Interpret error codes

Use the pidiag utility to interpret any error codes included in the message logs.
To display the error message, enter:
pidiag -e errorcode
where errorcode is the error number displayed in the message log. Error code values may be
positive or negative.

pidiag
For example, if the error code is -10722, enter:

pidiag -e -10722
[-10722] PINET: Timeout on PI RPC or System Call
You can also use the pidiag utility to translate operating system error codes, which are
always positive numbers.
Archive management with the pidiag utility

This section contains topics that describe how you can use the pidiag utility to manage
archives.
Dump the archive manager data file

The archive manager data file contains the list of archive files currently known to the PI Data
Archive server. When the server is shut down, use this to determine which archives will be
available at startup.
Procedure
pidiag -ad path
If you omit the path specification, the command displays the content of the file at the default
location, PI\dat\piarstat.dat.
C:\PI\adm>pidiag -ad
Archive manager data file version is 1
Archive primary archive code is 1
Archive manager data file dump follows:
PInt [$Workfile: pinttmpl.cxx $ $Revision: 13 $]::
Table contains 3 entries, with 3 total slots allocated.
Extend size is 2 slots and the next iCode is 4.
1. C:\PI\dat\piarch.001
Alphabetical index:
C:\PI\dat\piarch.001
PIobject:
End of Dump
You can use the pidiag-ad command in a procedure to repair the archive manager data
file. For details, see Repair the archive manager data file.
When PI Archive Subsystem is running, use the piartool -al command to get this
information.
Create a new archive manager data file

This command is useful when moving a PI Data Archive server to another machine, or when
running the same point configuration with different sets of archives.

pidiag
If the archive manager data file is corrupted, first try the pidiag -ara command. If that does
not help, use the pidiag-ar command. For more details, see Repair the archive manager data
file.
Procedure
1. Shut down PI Data Archive.
pidiag -ar path
The optional path argument is the full path of the primary archive file that you want to use.
If you do not provide this argument, the command will prompt you for it. When you restart
PI Data Archive, the file is the only archive registered.
Automatically recover the archive manager data file

Use the pidiag -ara command to repair an archive manager data file with a corrupted index.
Procedure
1. Shut down PI Data Archive.
2. At a command prompt, go the PI\adm directory.
pidiag -ara
The pidiag -ara command attempts an automatic recovery of the archive manager data
file, PI\dat\piarstat.dat, using the existing data in the file.
Display unregistered archive information

You can only use this command if the archive file is not registered, or if PI Data Archive is
down. If you use it with a registered archive file, the pidiag -ahd command returns an access
error.
For examples on using the pidiag -ahd command, see the PI Data Archive System
Management Guide.
Procedure
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:

pidiag
D:\PI\adm>pidiag -ahd d:\pi\dat\piarch.001

Version: 8 Path: D:\PI\dat\piarch.001
State: 3 Type: 0 (fixed) Write Flag: 1 Shift Flag: 1
Start Time: 16-Aug-09 23:08:12
Backup Time: 25-Aug-09 14:26:11
Last Modified: 24-Sep-09 14:31:27
Verify the integrity of the archive files

Run this command on unregistered archive files or when the server is inactive.
Procedure
2. Type the command: pidiag -archk path
Where path is the full path to the archive.
Note:
You can specify the optional complete parameter, as in: pidiag -archk path
complete, to include details about each record in the report, including the start time,
number of events, and fill ratio of the data record.
The command generates a report that displays:

List of points sorted by record number (RecNo)
Number of index records (indices)
Number of data records
Count of events in all records and the average fill ratio (fr)
Output from the pidiag -archk command

D:\PI\adm\pidiag -archk D:\PI\dat\piarch.001
Analyzing archive: D:\PI\dat\piarch.001
-----------------------------------------------------------------
recno: 1 id: 1 indices: 1 records: 5 events: 636 fr: 89.4%
recno: 3 id: 3 indices: 2 records: 278 events:54437 fr: 99.5%
recno: 4 id: 4 indices: 7 records: 866 events:428465 fr:99.6%
recno: 11 id: 17 indices: 6 records:1092 events:86402 fr: 48.0%

pidiag

----------------------------------------------------------------
0 errors detected
23 total index records
2399 total data records
593701 total events
247.5 events per record
10800 total annotations
Consistency check status: [0] Success
Points receiving events in order with no edits or remove events typically have a fill ratio close
to 100%.
Note:
Since the last record in a chain is rarely full, the fill ratio is almost never exactly at 100%.
In this example, points 4 and 17 (recno 4 and 11, respectively) have an excessive number of
index records.
Find and report errors in archive files

Review archive statistics to find problems in archive files. On average, points should not have
more than one or two index records. If this is not the case for many points, you should review
compression parameters for these points or make the archive files smaller.
Use the archive check command to detect and report any errors in the archive file. Errors are
summarized at the end of the report but when running the command, they are sent to the
standard error (stderr) stream. As a result, when redirecting the output to a file, the
following syntax should be used so that errors are inserted into the output file report.txt:
pidiag -archk "archive_file" > report.txt 2>&1
Alternatively, the following construct can be used to redirect the output to two different files:
pidiag -archk "archive_file" 1> report.txt 2> errors.txt
The archive errors or corruptions could be the result of failures (crash, unexpected
termination, power failure, and so on) or software bugs. If this occurs, use the offline archive
utility to reprocess the corrupted archive file, recover the data and fix all issues..
The -archk command can also be run with the optional argument complete, in order to
extract detailed information about the archive file structure. This extra information is similar
to what is provided by the archive walk command (see piartool -aw). It notably includes
point types and statistics (start time, event count, fill ratio) for every index or data record and
for each point in the archive file. The archive header information is also included at the
beginning of the report.
Here is an example of the detailed mode:
D:\PI\adm>pidiag -archk D:\PI\dat\piarch.001 complete
--------------------------------------------------------------------------
Version: 7 Path: D:\PI\dat\piarch.001
State: 3 Type: 0 Write Flag: 1 Shift Flag: 1
Start Time: 19-Oct-05 12:39:10
Backup Time: Never

pidiag
Last Modified: 19-Dec-05 18:09:15

recno: 1, id: 1, events: 636, annotations: 0, fr: 89.4% - (Float32)
index array size: 1
0: idxrec id: 1, record pointers: 5, total events: 636
record array size: 5
0: record id: 130516, start: 19-Oct-05 12:39:10, events: 142, fr: 99.4%
1: record id: 130811, start: 30-Oct-05 15:33:27, events: 142, fr: 99.7%
2: record id: 130515, start: 12-Nov-05 09:29:36, events: 142, fr: 99.9%
3: record id: 130210, start: 22-Nov-05 04:44:08, events: 142, fr: 99.9%
4: record id: 128814, start: 15-Dec-05 13:31:42, events: 68, fr: 47.9%
[...]
Check data gaps in an archive

Use the pidiag utility to check for data gaps in an archive.
Procedure
pidiag -gap path [-time=secs][-sample=percent][-matching=percent]
The command checks for data gaps by sampling the most active tags and searching for gaps
in their archived data. By default, the command samples the most active 10 percent of tags.
The command reports any gaps that are at least 300 seconds long and that are uniform
across 90 percent of the sampled tags. You can specify the percentage of tags to sample, the
gap length, and the percentage of tags having the same gap.
For example:
D:\PI\adm>pidiag -gap d:\pi\dat\piarch.001
------------------------------------------------------------------
Archive start time: 16-Aug-09 23:08:12
Archive end time: 18-Jan-38 19:14:07
Number of points to sample: 183
Minimum gap time: 300 seconds
164 out of 183 points must have aligned gaps
------------------------------------------------------------------
----------- RESULTING GAPS -----------
Duration: 417 st: 16-Aug-09 23:08:54 et: 16-Aug-09 23:15:51

Repair the archive manager data file

The archive manager data file, piarstat.dat, contains the list of archive files known
(registered) to PI Data Archive. If this file is corrupted, you can use the pidiag utility to
rebuild it.
pidiag option Description
-ad Dumps the current piarstat.dat file. This is
used to review the data in the file.

pidiag
pidiag option Description

-ar Provides an interactive recovery utility for
renaming the old piarstat.dat to piarstat.old and
generating a new one with a single entry the
primary archive provided by the user.
-ara Provides an automated recovery utility that
renames the old piarstat.dat to piarstat.old
and generates a new one with all of the entries
found in the original file. Any errors will cause the
automated version to abort, and the user should
resort to the interactive version.
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 archives. If the interactive version was used, all other archives must
be registered.
Check performance counters

Procedure
1. At a command prompt, go to PI\adm directory.
pidiag cpc [-fix]
When you specify the -fix option, the utility attempts to fix the problems. If there are
problems it cannot fix, it makes suggestions on how to repair the issues manually.
Event queue files management

Topics in this section describe pidiag commands you can use to obtain troubleshooting
information from the event queue files.

View event queue file contents
View event queue file statistics

pidiag
View event queue file contents

Use the pidiag utility to view header and events from an offline event queue file. An offline
event queue file is an event queue file that is not currently loaded by PI Snapshot Subsystem or
PI Archive Subsystem
Procedure
pidiag -qd [HeaderOnly | RecNo=n |PointId=ID] path
where path is the full path of the event queue file. If you specify the HeaderOnly option, the
command only returns the file header and page headers.
View event queue file statistics

Use the pidiag -qs command to view the statistics information contained within the event-
queue statistics file. When troubleshooting a PI Data Archive issue, the Technical Support
Engineer may request this information. You many run this command only when PI Snapshot
Subsystem and the PI Archive Subsystem are offline.
Procedure
pidiag -qs path
Licensing management
PI Data Archive requires a PI license file to run. The license file may be machine or cluster
specific, which means it can be used only on a particular computer or the members of a
particular cluster. PI License Manager determines whether a machine- or cluster-specific
license file can be used on a computer or a cluster based on hardware, network, and operating
system information. The signature of a machine or a cluster contains this information. You can
use several pidiag commands to gather and check machine and cluster signatures.

Generate a signature file
Compare signatures
Extracting the signature from a license file
Generate a signature file

Use the pidiag utility to gather the hardware, network, and operating system information of
the local computer or cluster, and store the information in the output file called a machine
signature file or a cluster signature file. You need a signature file to generate the PI license file
for a computer or cluster.

pidiag
Procedure
pidiag -host -file filename
where filename is the file name of the machine signature file. OSIsoft recommends that you
use the extension .msf for a machine signature file and .csf for a cluster signature file.
For example:
D:\PI\adm>pidiag -host -file D:\vmtest-xp2.msf
Compare signatures
Use the pidiag utility to compare a signature file to another signature file or to local or cluster
configuration.
Procedure
pidiag -host -compare filename [, filename]
This command compares signatures. When your provide only one signature file, the
command compares the information stored in the file with the configuration of the local
computer or cluster. When you provide a second signature file, the command compares the
two signature files.
Signature comparison examples

Matching signatures example:
D:\PI\adm>pidiag -host -compare D:\vmtest-xp2.msf
Percent Match: 100
Not matching signatures example:

D:\PI\adm>pidiag -host -compare D:\vmtest-xp4.msf
OS String : Service Pack 3 - Service Pack 2
CPU Level : 6 - 15
CPU Rev : 3851 - 1032
CPU count : 4 - 0
Logical CPU count : 4 - 1
Memory : 2048 - 512
Fixed Disk Count : 1 - 0
Total Disk Space (MB) : 476817 - 10227
Multi-Thread : 0 - 7
MAC Address : 4-005056c00008 - 0-000c290b1612
MAC Address 2 : 3-005056c00001 -
ComputerName : VMTEST-XP2 - VMTEST-XP4
IPaddr : 192.168.5.182 - 192.168.4.132
OSProductID : 55274-640-7804556-23379 - 76487-640-7804556-23915
Percent Match: 0

pidiag
Extracting the signature from a license file

A machine specific license file contains the signature of the machine or cluster that it was
generated for. This information can be extracted by:
pidiag -host -lictomsf licfile msffile
If the license file is for a cluster, the command is:

pidiag -host -lictocsf licfile csffile
The licfile parameter is the full path of the license file. The msffile parameter is the output
machine signature file that will contain the extracted machine signature. The csffile parameter
is the output cluster signature file that will contain the extracted cluster signature.
Example:
D:\PI\adm>pidiag -host -lictomsf D:\pilicense.dat D:\test.msf
These commands are useful when you have a machine specific license file but do not know
which computer or cluster it is for. Once you extract the signature, you can use the pidiag -
host -compare command to check it against your machine or cluster.
Miscellaneous commands
Topics in this section describe pidiag commands for various administrative tasks.

Test for crash dump capability
Reset password to blank
Display network definitions
Export and import certificates
Test for crash dump capability

You can raise operating system exception (crash) to test the crash dump capability of the
installed just-in-time debugger.
Procedure
1. Navigate to the PI\adm directory.
2. Type:
pidiag -crash
3. Debuggers, including Dr. Watson, rely on debug symbols to translate code addresses to line
numbers and meaningful text. The PI System installs these symbols in %SystemRoot%
\Symbols\exe directory where SystemRoot is typically C:\Windows. The system
environment variable, _NT_SYMBOLS_PATH, must include this full path. On a crash, if this
path is not included in _NT_SYMBOLS_PATH the crash symbols will not be correctly
interpreted.

pidiag
Reset password to blank

Note:
PI Base Subsystem must be shut down for this command to succeed. Also note the path
argument requires a trailing \ character.
The administrative account is piadmin. To reset the piadmin (userid #1) password to blank:
Procedure
2. Type:
pidiag -udf path
This command is useful when the piadmin password is lost. For example:
e:\PI\adm>pidiag -udf e:\pi\dat\
The administrative password has been successfully reset.
After you finish

Following this operation, the piadmin password can be set to any given string using the
pisetpass utility.
Display network definitions

To display the network definitions of a computer:
Procedure
2. Type:
pidiag -host
This may be used on nodes running client applications and interfaces, to help the definition
of trust login records. For example:
D:\pi\adm>pidiag -host
Domain <MyComp>
Machine <PISRV3>
User <user1>
IP Addr <10.0.0.3>
FQDN <PISRV3.MyComp.com>
Primary Domain Controller: <\\controller03.MyComp.com
IPV6 Compatible host address resolution:
Reverse name lookup setting: 1
Name: PISRV3.MyComp.com
Address: fe80::ad49:68df:30ff:fc6d12
Family: PF_INET6
Name: PISRV3.MyComp.com
Address: 10.0.0.3
Family: PF_INET
Reverse name lookup setting: 0

pidiag
Name: fe80::ad49:68df:30ff:fc6d12
Address: fe80::ad49:68df:30ff:fc6d12
Family: PF_INET6
Name: 10.0.0.3
Address: 10.0.0.3
Family: PF_INET
This command also tests the availability of the domain controller. The command should
complete in a fraction of a second; if it hangs or takes more than a few seconds to return it
indicates the domain controller access may not be fast or consistent. Failure to have prompt
access to the domain controller results in poor PI System performance.
Export and import certificates

Authentication among the members of a PI collective relies on certificates stored in the
Windows certificate store. If a member of a collective is a Microsoft Cluster, each node of the
cluster must have the certificate. During PI Data Archive installation or upgrade, you need to
export the certificate from the first node and import it to each other node. For details, please
refer to the document PI High Availability on Microsoft Cluster Services.
The command to export the certificate from a cluster node to a file is:
pidiag ecert [path]
The optional path is the name of the file to store the certificate. If it is not provided, the
certificate is stored in PI\adm\piserver.cer.
The command to import the certificate file to a cluster node is:
pidiag icert [path]
The optional path is the name of the certificate file. If it is not provided, PI\adm
\piserver.cer is used.

pidiag

pigetmsg
Use pigetmsg to view messages in the PI message log. Run the pigetmsg utility from the ..
\PI\adm directory.
If you include all necessary parameters on the command line when you run pigetmsg, then
pigetmsg simply returns the results and exits. This is called non-interactive mode. If you do
not enter all the necessary parameters, then pigetmsg prompts you to enter them. This is
called interactive mode.
To run in non-interactive mode, specify at least two of the following:
Start time (st)
End time (et)
Max count (mc)
If you specify the -i option, pigetmsg goes into interactive mode after the results are
returned, even if you entered all necessary parameters for non-interactive mode.
If you specify the -i option, pigetmsg goes into interactive mode after the results are
returned, even if you entered all necessary parameters for non-interactive mode.
If you specify the f option, pigetmsg goes into continuous mode after the results are
returned.

pigetmsg command line options
Filtering pigetmsg output
Search and sort messages
Display message summary
Save messages to a file
Read messages from a message log file
Display a message definition
pigetmsg command line options

This section lists options for pigetmsg by type of option. For connection options, see Remote
operation of PI Data Archive utilities.
Mode options
Mode Option Description
-f Update continuously (refreshing every two
seconds).

pigetmsg
Mode Option Description

-i Interactive mode (the default mode). Combine
with -f for prompts through each page of
messages.
Input options
Input Option Description
-if file_name Read messages in the specified message log file.
pigetmsg filter options valid for group counts with the sum and top options
Filter options
Filter Option (Field) Description
-id msg_id Retrieve messages with the specified message
identification number. (Specify 0 for free-format
messages.)
-mc num_msg Retrieve no more than the specified number of
messages.
-msg text Retrieve messages with the specified text. Text
must match exactly. To retrieve messages with
additional text, include wildcard characters (*).
For example, specify -msg Consumer* to retrieve
messages that start "Consumer" and contain any
subsequent text. Specify -msg "*timed out*" to
retrieve messages that contain "timed out" any
place in the message text.
-ohost name Retrieve messages written by processes acting on
behalf of users from the specified host name.
Without a specified host name, retrieves messages
without an originating host, such as those written
locally or those written by older clients.
-oosuser name Retrieve messages written by processes acting on
behalf of the specified user name.
-opiuser identity Retrieve messages written by processes acting on
behalf of users with the specified PI identity.
-phost name Retrieve messages written by processes running
on the specified host name. With no specified host
name, retrieve messages written by processes
running on localhost.
-pid number Retrieve messages written by programs with the
specified process ID number.
-posuser name Retrieve messages written by processes running
under the specified user account name.
-ppiuser identity Retrieve messages written by processing running
under user accounts with the specified PI identity.
-pr name Retrieve messages written by specified program
name, such as pinetmgr.

pigetmsg
Filter Option (Field) Description

-src name Retrieve messages written by specified program
name, such as pinetmgr, or that contain specified
value in src1, src2, or src3 fields. With no program
specified, retrieve messages written by any
program.
-src1 name Retrieve messages with specified value in the src1
field. Values contained in this field vary by the
program writing the message.
Filter options for pigetmsg that are not valid to group counts with the sum and top options
Filter options not valid
Filter Option Description
-cat type Retrieve messages that belong to the specified
category.
-et time Retrieve messages up to the specified end time,
entered in PI time format. Beginning with PI Data
Archive 3.4.385, if you specify just -st, then
pigetmsg assumes the end time is the current
time.
-pri number Retrieve messages marked with the specified
priority (1-10).
-si Retrieve information, warning, error, and critical
messages.
-sw Retrieve warning, error, and critical messages.
-se Retrieve error and critical messages.
-sc Retrieve critical messages only.
-st time Retrieve messages beginning at the specified start
time, entered in PI time format.
-t Retrieve last message in the specified time range.
Without an end-time specification, retrieve most-
recent message.
Prompting options
Prompting Option Description
-qb Run pigetmsg interactively, prompting for basic
options only (start time/end time).

pigetmsg
Prompting Option Description

-qa Run pigetmsg interactively, prompting for all
options.
Formatting options
Formatting Option Description
-fb Generate binary message-log output.
-fc Generate CSV-format output.
-ft Generate two-line output (two lines per message).
-fw Generate wide-format output (one message per
line).
-fx Generate XML-format output.
Output options
Output Option Description
-m msg_id Display the message definition for the specified
message ID.
Note:
Cannot combine with other options.
-oa Output all message fields (by default, only shows

the most common fields).
-of filename Output results to the specified file (if no file name
specified, use a default). By default, writes to a
binary (message log) format.
-sd num_digits Display specified number of digits in subsecond
timestamps (for example, 5 for 17-Jul-09
10:23:13.03518). By default, shows no
subseconds.
-sum spec Display a count of messages.
Optionally, include spec to group message counts
by a filter option or a time interval:
Filter option
Group message counts by unique values for the
specified option. The command can group by
select pigetmsg filter options (listed in the
"Filter options for pigetmsg valid to group
counts in the -sum and -top options" table). For
example, specify sumpr to see a count of
messages produced by each program name.
Time interval
Group messages produced during the specified
time interval. For example, specify: sum 1h to
show a count of messages written during each
one-hour time interval.

pigetmsg
Output Option Description

-top field Display a count of messages grouped by specified
filter option and sorted by number of occurrences.
The command can group by select pigetmsg filter
options (listed in the "Filter options for pigetmsg
valid to group counts in the -sum and -top options"
table). For example, specify -top id to see a
count of messages with unique message IDs,
sorted by most frequently occurring message ID.
-tz spec Override the local time zone settings and display in
the zone defined by spec. For example, -tz -5h
displays messages in U.S. Eastern Standard Time.

Continuous mode option
Interactive mode option
Continuous mode option

Continuous mode (-f) continually flushes the message log and gets the last messages every 2
seconds. You can stop the program by pressing CTRL+C. If you also specify the interactive (-i)
option, then pressing CTRL+C prompts you on what to do next.
Continuous mode affects the operation of other options:
If you also specify a start time (with the -st option), pigetmsg initially displays messages
beginning at the specified start time up to current time.
If you also specify the tail option (-t), then pigetmsg initially displays the last (n)
messages.
If you also specify the -i option, and pigetmsg prompts after displaying each page of
messages.
Interactive mode option

In interactive mode, there is a default start time and end time. The default start time is *-15m,
that is, 15 minutes prior to the current time. The end time is* which indicates current time.
There is no default limit on the maximum number of messages, or max count. That is, if you
do not enter a value for max count, you will retrieve all messages based on the start and end
times entered.
To select the default, press Enter at the prompt.
Filtering pigetmsg output

Use these guidelines to filter pigetmsg output:
To review messages for a specific time span, enter starttime and endtime.
To review a specific number of messages that begin at a specific start time, enter maxcount
and starttime.

pigetmsg
To review a specific number of messages that end at a specific end time, enter endtime and
maxcount.
To review messages that span from a specific start time through either a specific number of
messages or a specific end time, starttime, endtime, and maxcount.
Search and sort messages

You can use pigetmsg to search for and sort messages:
To see today's error messages, one screen at a time, enter:

pigetmsg -st t -se -i
To show the last ten messages reported by the piaflink process, and then update
continuously to show new messages, enter:
pigetmsg t 10 -f pr piaflink
To show messages for the past hour, filtering out debug messages, enter:
pigetmsg si -st *-1h
Display message summary

You can display a summary view with pigetmsg to sort through a large number of messages.
Use the -sum option to summarize results by a field or by a time interval, and use the -top
option to summarize results sorted by top occurrences for a specified field. For example:
Display the number of critical, error, warning, informational, and debug messages since
midnight.
pigetmsg -st T -sum sl
MessageSeverity, Count
Error,52
Warning,1
Information,17068
Debug,20923
Display the type of error messages reported, sorted to show the top occurrences first. (The
message is shown in a canonical form that ignores the message parameters.)
pigetmsg -st T -se -top msg
MessageID, Count, Message
6088,37,"Connection to pinetmgr lost."
6019,14,"Rpcservertablelist registration failure: %1"
6023,1,"PIsessionmgr::disconnect %1 Status: %2"
Display the occurrences of a particular message broken down over a given interval.
pigetmsg -st T -id 6088 -sum 1h
13-Jan-10 00:00:00,0
13-Jan-10 01:00:00,0
13-Jan-10 02:00:00,0
13-Jan-10 03:00:00,0
13-Jan-10 04:00:00,0
13-Jan-10 05:00:00,0
13-Jan-10 06:00:00,0
13-Jan-10 07:00:00,0
13-Jan-10 08:00:00,4
13-Jan-10 09:00:00,31
13-Jan-10 10:00:00,2
13-Jan-10 11:00:00,0
13-Jan-10 12:00:00,0
13-Jan-10 13:00:00,0

pigetmsg
13-Jan-10 14:00:00,0
13-Jan-10 15:00:00,0
13-Jan-10 16:00:00,0
13-Jan-10 17:00:00,0
13-Jan-10 18:00:00,0
13-Jan-10 19:00:00,0
13-Jan-10 20:00:00,0
13-Jan-10 21:00:00,0
13-Jan-10 22:00:00,0
13-Jan-10 23:00:00,0
Save messages to a file

Use the -of option with pigetmsg to write messages to a file. For example, the following
command writes messages from the last seven days to a log file:
pigetmsg -st *-7d -of
By default, the utility automatically names the file based on the search start and end time, the
name of the server, and any filtering options you specify. You can specify a file name:
pigetmsg -st * -1d -of mylog.dat
By default, the utility writes message in log-file format, which you can search and filter with PI
SMT or pigetmsg. You can specify alternative formats, including CSV, XML, wide (one message
per line), and two line (two lines per message).
Read messages from a message log file

Procedure
1. In a command line window, change to the PI\adm directory.
2. Type: pigetmsg -if filename
Note:
Beginning with PI Server 2010, the -if option replaces the pimsgss offline utility,
which read messages directly from a message log file.
Display a message definition

Procedure
1. In a command line window, change to the PI\adm directory.
2. Type:
pigetmsg -m messageID
where messageID is the message ID.

For example, to display the message definition for the message with ID 6023, type:
pigetmsg -m 6023
This would produce output like:

PIsessionmgr::disconnect %1 Status: %2
Parameters

pigetmsg
SessionID : Int32
Status : Status
Severity : Error
Message ID : 6023

pilistupd
Use the pilistupd utility to monitor PI Update Manager. Run pilistupd from the ..\PI
\adm directory. PI Data Archive must be running to use pilistupd.
Note:
PI Data Archive exposes PI Update Manager counters as Windows performance counters.
You can view these counters with Windows Performance Monitor, and you can store
these counters as PI points using the PI Performance Monitor Interface.
At the PI\adm directory, type:

pilistupd -ss
You will see a summary of the current state of update signups:
Producer
This is the source of update notifications. For example: PI Snapshot Subsystem produces
snapshot events; PI Base Subsystem produces PI point database and Module Database
changes; PI Archive Subsystem produces archive changes; and PI Batch Subsystem
produces Batch Database changes.
ConsumerA
pplication currently signed up as a consumer. For example, a PI ProcessBook display is a
consumer.
Qual
The qualifier. If the producer is snapshots or archive, the qualifier contains a point ID. If the
producer is PIUnitBatchOnUnitUpdates, the qualifier contains a unit batch storage point ID.
Not used for other producers.
Flags
If the producer is archive, contains archive event modes. Not used for other producers.
Pending
Number of events available for the consumer to retrieve. The value goes up and down as
events come in and the consumer pulls them out. Values that increase continuously might
indicate that the consumer is not working properly or disconnected.
Note:
The Pending column display is not accurate above 65,536 events.

pilistupd command line options
pilistupd modifiers
pilistupd examples
Producers and associated subsystems

pilistupd
pilistupd command line options

The pilistupd utility resides in the PI\adm subdirectory. To invoke pilistupd:
pilistupd [options] [modifiers]
Option Description
-cs Summary of consumer statistics.
-g A list of producers and consumers with their
status. This option is supported for backward
compatibility. The -ps and -qs options provide
more information.
-ps Summary of producer statistics.
-qs consumer Statistics for the specified consumer's event queue.
-sp Summary of signup statistics, sorted by producer.
-ss Summary of signup statistics, sorted by consumer.
-us Summary of PI Update Manager statistics.
-v Show version.
pilistupd modifiers
Modifier Description
-c consumer Select a specific consumer. Use * and ? as wildcard
characters. Enclose the consumer name in quotes if the
name contains Microsoft Windows escape characters. For
example:
pilistupd -c "pialarm|2"
-p producer Select producer. Use * and ? as wildcard characters.
-m min Show only signups with pending >= min
-r [S] [C] Repeat C times every S sec. Default for S is 5 seconds.
pilistupd examples
Limit output to point updates example
Run pilistupd with PI ProcessBook display example
Determine if client updates occur example
Limit output to point updates example

The following command limits output to the producer ptupdates:
e:\pi\adm>pilistupd -p ptupdates
Producer Consumer Qual. Flags Pending

pilistupd
ptupdates Pibatch|1 0 0 0
ptupdates Pitotal|2 0 0 0
ptupdates PipeE|14|3 0 0 0
ptupdates RandE|16|4 0 0 0
ptupdates RmpSE|17|5 0 0 0
The results show signups for all registered consumers for the producer ptupdates.
Run pilistupd with PI ProcessBook display example

The following output display was generated by running pilistupd with an open PI
ProcessBook version 3.x display, trending two points.
c:\pi\adm>pilistupd
Signup Statistics for 7-Mar-07 14:24:41

Producer Consumer Qual Flag Pending
-------- -------- ---- ---- -------
ptupdates pitotal|1 0 0 0
snapshots pialarm|2 1 0 0
ptupdates pialarm|2 0 0 0
ptupdates RmpSE|36|3 0 0 0
ptupdates RandE|37|4 0 0 0
ptupdates PipeE|254|9 0 0 0
ptupdates Procbook:zheng2:376:1|89 0 0 0
snapshots Procbook:zheng2:376:2|90 1 0 0
snapshots Procbook:zheng2:376:2|90 4 0 0
The last three lines of results are all the same display. For PI SDK applications, the consumer
attributes include:
Application name Procbook
Client hostname zheng2
Process ID 376
Event pipe ID 1 and 2
Consumer ID assigned by PI Update Manager 89 and 90
The qualifier attribute shows the point IDs being trended. There are no Pending events.
Determine if client updates occur example

Run pilistupd several times to reveal changes in the pending numbers. You can do this with
command-line switches. In the example below, the -m option requests only producers with at
least one pending event. The -r requests that the command be run 100 times. Results appear
for four runs before the Ctrl+C (^C) command stops the output. For three of the runs, none of
the producers has any pending updates, as indicated by the No Matching entries output.
e:\pi\adm>pilistupd -p snapshots -m 1 -r 100
No Matching entries
No Matching entries
Producer Consumer Qual. Flags Pending
--------- --------- ------ ------ --------
snapshots piadE|15|5 4 0 1

pilistupd
No Matching entries
^C
Producers and associated subsystems

Producer Description Subsystem
Snapshots Snapshot Snapshot
Archive Archive Archive
PtUpdates Point updates Base
MDBUpdates Module database Base
PIChangeRecordUpdates Changes for replication Base
DigitalSets Digital sets Base
BDBUpdates Batch database updates Archive
PIBatchUpdates Batch updates Archive
PIUnitBatchUpdates Unit batches Archive
PIUnitBatchOnUnitUpdates Unit batch updates for a specific Archive
unit
PICampaignUpdates Campaigns Archive
PITransferRecordUpdates Transfer records Archive

pipetest
Use the pipetest utility to check the syntax of a performance equation. Run the pipetest
utility from the ..\PI\adm directory. The utility can operate interactively, take its input from
a file, or check the extended descriptor of a point.
To start pipetest, open a command window, change to the ..\PI\adm directory, and type a
pipetest command. For a complete list of pipetest commands, type:
pipetest -?
The pipetest utility is limited to equations that are 4,095 characters or less, and you cannot
use the utility to test dynamic response functions.
To run the pipetest utility interactively from a command prompt window, open a command
window, change to the ..\PI\adm directory and type:
pipetest
At the pipetest equation prompt, type in the equation you want to test. If the equation syntax
is not valid, pipetest displays a syntax error. If the syntax is valid, pipetest displays the
result of the equation.
You can also put one or more performance equations in a simple text file, and pass the entire
file to pipetest using the -f switch. In the text file, you put each equation on a single line. You
can include comment lines by beginning the line with an exclamation mark (!).
Here is the text from an example pipetest file, called peTestEquations.txt:
! test calculation for point A
if BadVal('sinusoid') then 0 else ('sinusoid')/25
! test calculation for point B
TimeLT('sinusoid', 'y' , 't', TagVal('sinusoid', '*'))
To test the equations in the file, type:

pipetest -f peTestEquations.txt
Each input line in turn is echoed and the evaluated result is displayed.

pipetest

pisetpass
Use the pisetpass utility to change the password for a PI user. Run the pisetpass utility
from the ..\PI\adm directory.
If you have lost the piadmin password, first use pidiag udf to reset the piadmin password
to blank. Next, use the pisetpass command to set the piadmin password any given string.
PI Base Subsystem must be running for the pisetpass command to succeed.

pisetpass

pisqlss
This section outlines the PI SQL Subsystem (pisqlss) settings that can be altered using
command line arguments. The mechanism for specifying command-line arguments differs
between supported platforms. This section outlines the techniques.
pisqlss command line options

In general, you specify a command line option by using an argument token, one or more
spaces, and then the argument value. The argument token always begins with a leading dash
( - ). For example:
pisqlss -t 60 -ts 7200 -o trace,aggrtimestart
In this example, SQL query timeout is set to 60 seconds, the default time step (for queries
against the piinterp table) is set to 7200 seconds (that is, 2 hours) and the trace
andaggrtimestart options have been set.
PI SQL Subsystem (pisqlss) supports the following command-line arguments:
Argument Description
-o Options (letter "o", not zero). The options are
specified in a comma-separated list of tokens. The
interpretation of the tokens is not case-sensitive.
See the following table for the list of supported
options.
-t SQL query timeout, in seconds. If this time expires,
PI SQL Subsystem will cause the query to return
either a timeout error, or a subset of the actual
results, if the SUBSET option is set. See the table of
options below.
-ts Default value of the timestep column in the
PIINTERP table. This value can be overridden for
any query by specifying a timestep constraint in
your SELECT statement.
The -o argument is followed by a comma-separated list of option tokens with no space

between the tokens. The supported options are:
Option Token Description
AGGRTIMESTART Causes all queries of the aggregate tables to use
the time at which the interval starts to identify the
aggregate; the default is to use the time at which
the aggregate period ends.
EXECSAFE If set, the query does not execute if the PI SQL
determines that a query is too unspecific and
would take too long to execute.

pisqlss
Option Token Description

LOG Writes a summary of every operation by pisqlss on
a statement handle to the file sqltrace.log in
your pi\log directory. See also the TRACE option.
This file is generated in all PI Data Archive
configurations, except while not running as a
service on Windows. In this case, output is
directed to standard output, which is the
command window.
QEP Causes the gateway to dump a query execution
plan to a file called pisql_n.qep in the pi\log
directory on the PI Data Archive computer, where
n is the handle number.
SUBSET If a query times out while this option is in effect, PI
SQL Subsystem returns a subset of the actual
results with no error. If this option is in effect, the
results returned do not represent the actual final
results of the query. When query development is
complete, remove this option.
TRACE Writes a summary of every Prepare, that is, query
parsing, and Execute operation by PI SQL
Subsystem to the file sqltrace.log in your pi
\log directory. See also the LOG option.
Start pisqlss as a Windows service

You can start subsystems by running Services in Control Panel, or by using the
pisrvstart.bat file in your PI\adm directory.
To pass command-line arguments to PI SQL Subsystem running as a Windows service: in
Control Panel open Administrative Tools. Open Services, select PI SQL Subsystem, right-click
and choose Properties. Stop the service, and enter the arguments into the Start parameters
dialog box. Click the Start button to restart PI SQL Subsystem.
This example shows a system manager about to restart PI SQL Subsystem while setting the
default timestep to 7200 seconds and turning on TRACE mode.
Note:
This works one time only. If you close the Services, then reopen and reselect your
service, you will not see your command-line arguments from the last run. This method
cannot be used to provide command-line parameters to services started automatically
when your Windows system boots.
Start pisqlss in a command window

Command-line arguments can be provided to a Windows program by listing them after the
program name. You can edit the file pistart.bat to include command-line arguments when
starting subsystems.
Starting this way results in a command window for every subsystem. You cannot log off
Windows in this configuration and leave the system running.

pisqlss
Use caution when editing pistart.bat. This file is overwritten at every PI Data Archive
upgrade.

pisqlss

piversion
Use the piversion utility to find the PI Data Archive version and build numbers. Run the
piversion utility from the ..\PI\adm directory.
To find the PI Data Archive version and build numbers, change to the PI\adm directory, and
type:
piversion -v
If you have applied a patch to your PI Data Archive, the version numbers of the executables
affected are different from that shown by piversion -v. To see the version of each
executable and the version of the executable running in memory, use piversion.bat, also in
the PI\adm directory:
piversion.bat
When you use the -v option to run an executable, it does not start; instead, the version number
appears. For example, if you type piarchss.exe -v from the PI\bin directory, you would
see something like this:
Version: PI 3.4.380.36
Program: piarchss.exe

piversion

PI Data Archive database files
The PI Data Archive includes several databases and files that store configuration information
and time-series data. The main PI Data Archive databases are the PI point database and the
time-series database, which provides access to the PI archive files. Other parts of the system,
including the PI Batch Database and the PI Module Database, support these components. The
security database contains settings about client authentication and high-level database access.
The PI Data Archive data files are located in the PI\dat directory. Archives are likely to be in a
separate directory.
List of Database Files

This table provides a list of database files for your reference. The files are organized by the
subsystem to which they belong:
Files that comprise: Description
Point Database (PI Base Subsystem)
pipoints.dat Point definitions. This binary file stores the point
database.
piptattr.dat Attribute set definitions.
piptclss.dat Point class definitions.
pidigst.dat This binary file stores the digital sets; it references names
stored in pidignam.dat.
pidignam.dat This binary file stores each unique digital state name.
piptsrcind.dat Point source index (allows for quick lookup by point
source). Automatically rebuilt if it does not exist.
piptcomind.dat Index of COM connector points. Automatically rebuilt if it
does not exist.
Module Database (PI Base Subsystem)
PIModuleDb.dat PI Module Database.
PIModuleUnitDb.dat Batch process unit indexan index of all modules with
the IsPIUnit flag set to true. Automatically rebuilt if it does
not exist. Note: Delete this file before a backup
restoration.
Security (PI Base Subsystem)
piidentity.dat PI identity definitions; upgraded PI Data Archive servers
contain piusr.dat and piusrgrp.dat
piidmapping.dat PI user contexts, a very simplistic mechanism to tag PI
users; this is deprecated but the PI SDK has a public
interface for it.
piidentmapping.dat PI mapping definitions.
piacl.dat Access control list (ACL) definitions for all PI Data Archive
secure objects (points, modules and database security
databases).
pidbsec.dat PI database security definitions.
pitrstrl.dat PI trusts definitions.


pifirewall.tbl PI firewall table.
Time-Series Database (PI Snapshot Subsystem and PI
Archive Subsystem)
piarcmem.dat Snapshot table. This binary file is used by PI Snapshot
Subsystem. It contains the most recent values that have
been sent to the PI Data Archive server. PI Snapshot
Subsystem periodically writes the latest snapshot values
to this file.
pimapevq.dat (or pimq####.dat) These are the memory-mapped event queue files. Most
systems use the default single file pimapevq.dat. Certain
situations require multiple event queues; in this case the
files take the naming convention of pimaNNNN.dat where
NNNN is an integer.
The memory-mapped event queue serves two purposes.
First, it used for moving events from PI Snapshot
Subsystem to PI Archive Subsystem. PI Snapshot
Subsystem places events which pass compression into
this queue. PI Archive Subsystem takes these events and
writes them to the archive. Second, this file provides
storage of events when PI Archive Subsystem cannot
process events such as during archive shifts or when the
archive process is shut down.
This file, as the name implies is a memory-mapped file.
Memory mapped files allow for high speed in-memory
access with the security of being safely backed up to disk.
piarstat.dat List of registered archive files. This binary file, called the
archive manager data file, keeps track of registered
archives. PI Archive Subsystem requires this file. If you
are having trouble with archive file registration, do not
delete this file. Instead, repair the archive manager data
file.
PI Data Archive Messages (PI Message Subsystem)
pimsgtxt.dat Message text resource. This binary file stores formatted
message strings used by the pigetmsg utility.
pimdf.dat Message definitions; new on PI Data Archive versions
3.4.380 and later.
pimsg_yymmdd.dat Message logs, where yymmdd represents date covered by
file.
Batch Database (PI Batch Subsystem)
piptunit.dat Legacy Batch Units (deprecated)
piptalia.dat Legacy Batch Aliases (deprecated)
Miscellaneous
shutdown.dat This text file contains directives that tell the PI Shutdown
Interface which points should receive shutdown events.


pilastsnap.dat Used to determine the PI Data Archive shutdown time.
This binary file stores the timestamp of the last
completed snapshot flush to disk. On PI Data Archive
startup, this timestamp is assumed to be the shutdown
time and is used as the timestamp for shutdown events.
On orderly shutdown, this file will contain the true
shutdown time. With a system crash such as a power
failure, the snapshot may be as old as the snapshot flush
cycle time period. The snapshot flush cycle is controlled
by the SnapFlushCycle timeout parameter, which is 15
minutes by default.
pitimeout.tbl Tuning parameter definitions.
piarcmem
This binary file is used by PI Snapshot Subsystem. It contains the most recent values that have
been sent to the PI Data Archive server. PI Snapshot Subsystem periodically writes the latest
snapshot values to this file. Contact OSIsoft Technical Support if you need to diagnose and
repair this file.
piarstat.dat
This binary file, called the archive manager data file, keeps track of registered archives. PI
Archive Subsystem requires this file. If you are having trouble with archive file registration, do
not delete this file. Instead, see Repair the archive manager data file.
pidignam
This binary file stores each unique digital state name. Contact OSIsoft Technical Support if you
need to diagnose or repair this database file.
pidigst
This binary file stores the digital sets; it references names stored in the above file. Contact
OSIsoft Technical Support if you need to diagnose or repair this database file.
pilastsnap
This binary file stores the timestamp of the last completed snapshot flush to disk. On PI Data
Archive startup, this timestamp is assumed to be the shutdown time and is used as the
timestamp for shutdown events. On orderly shutdown, this file will contain the true shutdown
time. With a system crash such as a power failure, the snapshot may be as old as the snapshot
flush cycle time period. The snapshot flush cycle is controlled by the SnapFlushCycle timeout
parameter, which is 15 minutes by default.

pimapevq.dat and pimaNNNN

These are the memory-mapped event queues. Most systems use the default single file
pimapevq.dat. Certain situations require multiple event queues; in this case the files take the
naming convention of pimaNNNN.dat where NNNN is an integer.
The memory-mapped event queue serves two purposes. First, it used for moving events from
PI Snapshot Subsystem to PI Archive Subsystem. PI Snapshot Subsystem places events which
pass compression into this queue. PI Archive Subsystem takes these events and writes them to
the archive. Second, this file provides storage of events when PI Archive Subsystem cannot
process events such as during archive shifts or when the archive process is shut down.
This file, as the name implies is a memory-mapped file. Memory mapped files allow for high
speed in-memory access with the security of being safely backed up to disk.
pimsgtxt
This binary file stores formatted message strings used by the pigetmsg utility. Contact OSIsoft
Technical Support if you need to diagnose or repair this database file.
pipoints
This binary file stores the point database. Contact OSIsoft Technical Support if you need to
diagnose or repair this database file.
piptalia
This binary file contains alias information. Contact OSIsoft Technical Support if you need to
piptattr
This binary file stores the point attributes. Contact OSIsoft Technical Support if you need to
piptclss
This binary file stores the point classes. Contact OSIsoft Technical Support if you need to
piptunit
This binary file stores the PI point units. Contact OSIsoft Technical Support if you need to

piusr
This file stores the PI user database. Contact OSIsoft Technical Support if you need to diagnose
or repair this database file.
piusrctx
This file stores the context database. Contact OSIsoft Technical Support if you need to diagnose
piusrgrp
This file stores the group database. Contact OSIsoft Technical Support if you need to diagnose
shutdown
This text file contains directives that tell the PI Shutdown Interface which points should
receive shutdown events.


PI Performance Counters
The tables in this section list the PI Data Archive performance counter statistics that you can
view with Windows Performance Monitor.
PI archive subsystem statistics

Annotation Average Size Average size of annotations stored.
Annotation Largest Size Largest annotation stored.
Annotations Created/sec Rate at which annotations are created.
Annotations Deleted/sec Rate at which annotations are deleted.
Annotations Edited/sec Rate at which annotations are edited.
Annotations Read/sec Rate at which annotations are read.
Archive Header Flushes/sec Rate at which archive headers are written to disk.
Archive Record Allocations/sec Rate at which archive records are allocated.
ArcEvent Calls/sec Rate of single archive event calls.
Archive Backup Flag Bitmask value indicating backup state. Bit values
are: 0x01 - Backup in progress; 0x02 - Legacy
backup in progress; 0x10 - Archive shifts are
prevented until backup completes.
Archive Count Number of registered archives.
Archive Cycles/Sec Number of subsystem cycles per second.
Archive Point Cache Loaded Flag Indicates if the point cache has been successfully
loaded.
Archived Events/sec Rate of successful event addition to the archive.
Archiving Flag Indicates if data is being archived.
Cache Clean Operations/sec Rate at which archive cache records are removed
from memory.
Cache Flush Operations/sec Rate at which points are flushed to disk.
Cache Record Count Archive cache records in memory.
Cache Record Disk Reads/sec Rate of archive cache disk reads.
Cache Record Memory Reads/sec Rate of archive cache memory hits.
Cache Records Created/sec Rate at which archive cache records are created.
Cache Records Deleted/sec Rate at which archive cache records are deleted.
CompEvents Calls/sec Rate of compressed events calls.
Config. Max Unflushed Events/pt Maximum number of unflushed events per point.
Configured Cache Record Pool Maximum number of cache records in the read-
only pool.
Connector Event Read Exec Time Time elapsed in milliseconds for one event read
for a COM connector point.

Connector Events Read Exec Time Time elapsed in milliseconds for one Events Read
for a COM Connector point.
Connector Events Read/sec Rate of events read for mapped points through
COM Connectors. This rate is NOT included in the
Events Read/sec counter.
Connector Read Operations/sec Rate of calls to read events for mapped points
through COM Connectors. This rate is NOT
included in the Read Operations/sec counter.
Connector Summaries Exec Time Time elapsed in milliseconds for one summaries
call for a COM Connector point.
Connector Summaries/sec Rate of summaries for mapped points through
COM Connectors. This rate is NOT included in the
Events Read/sec counter.
Current Cache Record Pool Current maximum number of cache records, this
may be lower that the configured value due to low
memory resources.
Current Max Unflushed Events/pt Current maximum number of unflushed events per
point, this may be lower that the configured value
due to low memory resources.
Empty Archive Count Number of empty, shiftable archives.
Event Queue Chunk Size Number of events read per event queue read
operation.
Event Queue Reader Delay Amount of time (in milliseconds) the event queue
reader thread is being throttled.
Events Cascade/sec Rate of out-of-order events causing record shifts.
Events Read/sec Rate of archive events read.
Failed Archive Shift Flag Indicates if the most recent archive shift failed.
Failed Events/sec Number of events which failed to be added to
memory or archive files.
File Management Operations/sec Rate at which archive file management operations
are performed.
File Management Queue Size Number of pending archive file management
operations in memory queue.
Flushed Events/sec Number of events successfully flushed to archive.
Flush Queue Size Number of pending flush operations in memory
queue.
Full Write Cache Flushes/sec Number of full write caches that were flushed.
GetSnapshot Calls/sec Rate of internal calls to PI Snapshot Subsystem.
High Priority Flush Queue Entries/sec Rate at which flush requests are added to the high
priority flush queue.
High Priority Flush Queue Size Number of flush requests in the high priority flush
queue.
InterpEvents Calls/sec Rate of interpolated events calls.
Out of Order Events/sec Out of order events posted in the archive.
Overflow Data Record/sec Rate at which data archive records are created.
Overflow Index Record/sec Rate at which index archive records are created.

PIBatches Created/sec Rate of PI Batch creation.
PIBatches Deleted /sec Rate of PI Batch deletion.
PIBatches Edited/sec Rate of PI Batch edits.
PIBatches Read /sec Rate of PI Batch access.
PICampaigns Created/sec Rate of PI Campaign creation.
PICampaigns Deleted /sec Rate of PI Campaign deletion.
PICampaigns Edited/sec Rate of PI Campaign edits.
PICampaigns Read /sec Rate of PI Campaign access.
PITransferRecords Created/sec Rate of PI Transfer Record creation.
PITransferRecords Deleted /sec Rate of PI Transfer Record deletion.
PITransferRecords Edited/sec Rate of PI Transfer Record edits.
PITransferRecords Read/sec Rate of PI Transfer Record access.
PIUnitBatches Created/sec Rate of PI Unit Batch creation.
PIUnitBatches Deleted /sec Rate of PI Unit Batch deletion.
PIUnitBatches Edited/sec Rate of PI Unit Batch edits.
PIUnitBatches Read /sec Rate of PI Unit Batch access.
PlotEvents Calls/sec Rate of plotted (trended) event calls.
Point Flushes Last Cycle Number of points flushed to disk during last cycle.
Busy points might get flushed several times per
cycle.
Preemptive Flushes/sec Rate of preemptive flushes performed.
Primary Archive % Used Percent of used records in primary archive file.
Primary Archive Average Events/record Average number of events per record in the
primary archive.
Primary Archive Flushed Events/sec Rate of events being flushed to the primary
archive.
Primary Archive Index Records Number of index records in the primary archive.
Primary Archive Record Allocations/sec Rate at which archive records are allocated in the
primary archive
Primary Archive Records Fill/sec Fill rate of records in primary archive.
Primary Archive Total Events Number of events in the primary archive.
Primary Archive Number Internal index number of archive current assigned
to primary position.
Read Operations/sec Rate of archive read calls. Each call can return
multiple events. The rate of event retrieval is
Events Read/sec.
Record Disk Reads/sec Rate of archive disk reads (includes Cache Record
Disk Reads/sec).
Record Disk Writes/sec Rate of archive disk writes.
Record Load Time Average BASE Denominator for Record Load Time Average.
Record Load Time Average Average time (in microseconds) required to load a
record from an archive.
Record Write Time Average BASE Denominator for Record Write Time Average.

Record Write Time Average Average time (in microseconds) required to write
a record to an archive.
Shift or System Backup Flag Indicates if an archive shift or system backup is in
process.
Skipped Flushes/sec Rate of flushes skipped due to point being
previously flushed.
Summary Calls/sec Rate of summary/filter expression calls.
Time to Archive Shift Number of seconds until the archive is projected to
shift. This time is not calculated if the archive is
less than 20% full.
Total Unflushed Events Total number of unflushed events.
Unflushed Points Number of points that have at least one unflushed
event.
Write Cache Flush Size Average BASE Denominator for Write Cache Flush Size Average.
Write Cache Flush Size Average Average size of write caches when flushed.
Write Contention Points Number of points in write contention last cycle.
Write Contentions/sec Rate of write lock contentions.
PI authentication statistics
Performance Counter Description
Delegation Failures/sec Rate of failed delegation attempts made to PI
Network Manager.
Delegation Successes/sec Rate of successful delegations made to PI Network
Manager.
Explicit Login Failures/sec Rate of failed explicit login authentication attempts
made to PI Network Manager.
Explicit Login Successes/sec Rate of successful explicit login authentications
HA Authentication Failures/sec Rate of failed HA authentication attempts made to
PI Network Manager.
HA Authentication Successes/sec Rate of successful HA authentications made to PI
Network Manager.
Session Authentication Failures/sec Rate of failed authentication attempts made to PI
Network Manager.
Session Authentication Successes/sec Rate of successful authentications made to PI
Network Manager.
Trust Failures/sec Rate of failed trust authentication attempts made
to PI Network Manager.
Trust Successes/sec Rate of successful trust authentications made to PI
Network Manager.
Windows Authentication Failures/sec Rate of failed Windows authentication attempts

Performance Counter Description

Windows Authentication Successes/sec Rate of successful Windows authentications made
to PI Network Manager.
PI backup subsystem statistics

Aborted Backups Total number of times backups have been aborted.
Backup In Progress If a backup is in progress, this counter is set to 1.
Otherwise, this counter is set to 0.
Backups Started Total number of backups that have been started.
Backups Started non-Component Total number of VSS, non-component mode
backups that have been started. For example, a
backup with NtBackup.exe will cause this counter
to be incremented.
Backups Started non-VSS Total number of non-VSS backups that have been
started.
Failed Backups Total number of backups that have failed.
Last Backup Copy Failures Number of file copy failures from the last backup.
This counter is not incremented for a non-
component mode backup.
Last Backup Duration Time in seconds of last backup.
Last Backup Failed If the last backup failed or if the last backup was
aborted or if the last backup's verification check
failed, this counter will be 1. Otherwise, this
counter is set to 0.
Last Backup Files Copied Number of files copied in last backup. This counter
is not incremented for a non-component mode
backup.
Last Backup Files Skipped Number of files not copied in last backup because a
file of the same last modified date and size already
exists in the destination. File copies can be skipped
for incremental, differential, and full backups. This
counter is not incremented for a non-component
mode backup.
Last Backup Init Duration Initialization duration. The number of seconds
required to start backup after the backup was
requested. This should typically be 0 for non-VSS
backups and about 5 seconds or less for VSS
backups.
Last Backup Megabytes Copied Number of megabytes copied in last backup. This
counter is not incremented for a non-component
mode backup.
Last Backup PrepareBackup To Freeze Duration Number of seconds between PrepareBackup and
Freeze events. This can be a long time for a non-
VSS backup if the backup is waiting for an archive
shift to complete.

Last Backup Total File Count Total files identified for last backup. Should be
equal to copied + skipped + failed unless the
backup is non-component mode.
Last VSS Freeze Duration Time in milliseconds between start of the freeze
event and the end of the thaw event for the last
VSS backup.
Last VSS Freeze Transition Time in milliseconds to acquire exclusive write
locks in all subsystems participating in backup.
Verification Failures Total number of verification failures.
PI base subsystem statistics

Counter Description
Connector Point Count Count of defined points that are mapped points.
These are points that interact with points on a
foreign data historian using a COM Connector.
Digital State Translations/sec Rate at which digital state strings are translated to
offsets.
Heading Accesses/sec Rate at which heading information is accessed, not
including module edits.
Heading Count The total number of headings in the module
database.
Heading Create or Edit/sec Rate at which headings are created or edited.
Heading Set Accesses/sec Rate at which heading set information is accessed,
not including module edits.
Heading Set Count The total number of heading sets in the module
database.
Heading Set Create or Edit/sec Rate at which heading sets are created or edited.
MDB-AF Communication Failures Count Number of communication failures among PI Base
Subsystem, PI AF Link Subsystem, AF Server, and
SQL Server since startup of PI Base Subsystem.
MDB-AF Health MDB-AF Health
Module Accesses/sec Rate at which module information is accessed, not
including module edits.
Module Count The total number of modules in the module
database.
Module Create or Edit/sec Rate at which modules are created or edited.
Module Database Accesses/sec Rate at which module database information is
accessed, not including module edits.
Module Database Create or Edit/sec Rate at which MDB records are created or edited.
Module Database Creates or Edits through AF Module Database creates or edits through AF since
startup.
Module Database Creates or Edits through PI SDK Module Database creates or edits through PI SDK
since startup.

Counter Description
Module Database Record Count The total number of records in the module
database.
Point Accesses/sec Rate at which point information is accessed, not
including point edits. This will include translations
of tag to point id.
Point Count Total number of defined points. This number
includes the Connector Point Count.
Point Create or Edit/sec Rate at which points are created or edited.
Points Loaded in Memory Indicates the number of points that have all point
attributes loaded in memory. It is updated as the
Base Subsystem is starting and loading the point
database. The Base Subsystem reports progress
messages once a minute while it is loading the
point database. A final message is reported when
loading the point database is complete. This
counter can be compared with PI Base Subsystem
\Point Count to determine the percentage of
points loaded.
Security Descriptor Mismatches Indicator Indicates if there are known security mismatches
between a PI Module security descriptor and its
corresponding AF Element security descriptor
since the last security report was generated. Value
of 1 means there are known errors.
Wild Card Searches/sec Rate of wildcard point searches. This counter
represents the rate at which new searches are
started, not the number of points found.
PI Buffer Subsystem statistics

These global counters record PI Buffer Subsystem's overall status, which includes all buffering
from a given client or interface computer. They include counters that are not specific to any
one server, and counters that represent aggregated values of all servers receiving buffered
data.
Buffer Sessions Active Number of active buffer sessions1 for physical
servers to which PI Buffer Subsystem is connected
and sending data.
Buffer Sessions Offline Number of inactive buffer sessions1 for physical
servers for which PI Buffer Subsystem is unable
queue and/or send data.
Buffer Sessions Total Total number of active and offline buffer sessions1.
Compressed Events/sec Rate of events marked for archiving (does not
include Out-Of-Order events).

Events In Error Number of events not processed locally by the
Buffer Subsystem, including:
1. events with invalid mode, data type, or value
2. events that can't be coerced to the point's data
type
3. events with a digital set that does not match
the point's configuration
These events are still sent to the PI Data Archive
servers.
Events Received/sec Rate of events received.

Events Rejected Number of events rejected by the Buffer
Subsystem, including:
1. events with unsupported API source type
(uncommon)
2. the target server is version 3.4.375 and PI
Buffer Subsystem does not have write access to
the point
These events are not sent to the PI Data Archive
servers.
Health Overall health (0 = OK, 1 = Warning, 2 = Error,

3=Critical)
Out-Of-Order Events/sec Rate of out-of-order events received.
Point Count Numbers of local points with cached configuration
(on disk).
Point Edits/sec Rate of new points and point edits received from
all servers.
Points With Post Error Total number of points that received errors when
posting, for all servers.
Queue> Capacity The estimated time (in seconds) that PI Buffer
Subsystem can buffer data for this logical server if
the connection to all servers is lost.
Queue> File Count Total number of queue files for all servers.
Queue> Write Errors Number of events that failed to be written to the
buffer queue for all servers.
Total API Buffered Events Number of events in all API buffers (including
APIBUF*.DAT files).
Total Events Sent/sec Rate of events sent to all servers.
Total Queue Writes Exclusive/sec Rate of events written to a buffer queue but not
other queues in the same collective (no fanning
mode).
Total Queue Writes/sec Rate of events written to all buffer queues.
Total Queued Events Total buffered events.
Total Snapshot Posts/sec Rate of data posts to all PI sessions.
Unresolved Cache Points Numbers of local points with unknown
configuration.

1 When PI Buffer Subsystem establishes buffering to a physical server, it creates a buffer
session. The session persists as long as PI Buffer Subsystem is buffering to this server.
PI collective statistics
Current Server The index of the current server of the collective
Is Running Normally Is the status normal for all members of the
collective?
Last Config Change Time Last time the configuration of the collective was
modified
Number of Servers The number of member servers in the collective
PI license entry statistics

Amount drawn Amount drawn from this license
Amount left Amount left in this license
PI license manager statistics

License count Total active licenses
License requests Requests for license per second
License returned Return license calls per second
User count Total active users
PI license user statistics

Failed requests Total number of failed license calls
Successful requests Total number of successful license calls
PI message subsystem statistics

Inserted Messages/sec The number of messages that were inserted into PI
Message Subsystem from the application event log
per second.

Sent Messages/sec The number of messages sent to PI Message
Subsystem per second.
Retrieved Messages/sec The number of messages retrieved by PI Message
Subsystem per second.
PI network manager statistics

API Asynch Call Delay Delay in milliseconds between when an API call
was scheduled and when it was executed
API Protocol Connections The number of connections to PI Network
Manager using the API protocol.
Bytes Received/sec The number of bytes received by the PI Network
Manager.
Bytes Sent/sec The number of bytes sent to the PI Network
Manager.
Connections The number of connections to the PI Network
Manager. Applies to _Total only.
Inbound PInet3 Connections The number of network connections to this PI
Network Manager.
Licensing Failures The number of times an application was rejected
due to licensing concerns
Licensing Warnings The number of times an application was warned of
licensing concerns
Local PInet3 Connections The number of connections made to this PI
Network Manager over the named pipe.
Messages Received/sec The number of messages received by the PI
Network Manager.
Messages Sent/sec The number of messages sent to the PI Network
Manager.
Outbound PInet3 Connections The number of connections to remote PI Data
Archive servers using the PInet3 protocol.
Overflow/sec The number of times an overflow message is
required by the PI Network Manager.
PI API Connections The number of PI API applications connected.
PINet3 Asynch Call Delay Delay in milliseconds between when a PINet call
was scheduled and when it was executed
PI SDK Connections The number of PI SDK applications connected.
Queued Connection Deletions The number of connections currently being
processed for deletion
Queued Connections The number of connections currently being
processed
Receive Errors The number of times an error occurs during a
receive of a message to the PI Network Manager.

Scheduled Task Delay Delay in milliseconds between when the currently
running task was scheduled and when it was
executed.
Send Errors The number of times an error occurs during a send
of a message to the PI Network Manager.
PI performance equation scheduler statistics

AlarmFuncCalls/sec Rate of calls made to alarm functions.
ArcFindCalls/sec Rate of calls made to PI Archive Subsystem for
finding values.
ArcSummaryCalls/sec Rate of calls made to PI Archive Subsystem for
summarized values.
ArcValueCalls/sec Rate of calls made to PI Archive Subsystem for
compressed events.
FailedEvaluations/sec Rate of PE evaluations that return the digital state
Calc Failed.
NumberOfPEs Number of Performance Equations.
SnapshotCalls/sec Rate of calls made to PI Snapshot Subsystem to
obtain snapshot event(s).
SnapshotEvents/sec Rate of snapshot event retrieval.
SteamFuncCalls/sec Rate of calls made to steam functions.
TotalEvaluations/sec Rate of PE evaluations.
Statistics for PI Performance Equation Scheduler also include UniInt-specific statistics. See
"UniInt Performance Counters" in the UniInt Interface User Manual for details.
PI Data Archive localhost statistics

Thepiperfmon.dif file contains examples of some basic performance counters useful in
monitoring PI Data Archive. These points contain performance information about the PI Data
Archive server as well as the machine that runs it. The performance counters for the machine
are useful in determining resource problems of the machine that runs PI Data Archive. The
performance counters for the PI Data Archive server are useful in determining how well the PI
Data Archive server is performing.
Tag Description
PERF.LOCALHOST.Logical Disk(_Total).Free Free Megabytes displays the unallocated space on
Megabytes the disk drive in MB. One MB = 1,048,576 bytes.

Tag Description
PERF.LOCALHOST.Memory.% Committed Bytes In % Committed Bytes In Use is the ratio of Memory:
Use Committed Bytes to Memory: Commit Limit.
(Committed memory is physical memory in use for
which space has been reserved in the paging file
should it need to be written to disk. The commit
limit is determined by the size of the paging file. If
the paging file is enlarged, the commit limit
increases, and the ratio is reduced). This counter
displays the current percentage value only; it is
not an average.
PERF.LOCALHOST.Memory.Page Faults/sec Page Faults/sec is the overall rate that faulted
pages are handled by the processor. It is measured
in numbers of pages faulted per second. A page
fault occurs when a process requires code or data
that is not in its working set (its space in physical
memory). This counter includes both hard faults
(those that require disk access) and soft faults
(where the faulted page is found elsewhere in
physical memory). Most processors can handle
large numbers of soft faults without consequence.
However, hard faults can cause significant delays.
This counter displays the difference between the
values observed in the last two samples, divided
by the duration of the sample interval.
PERF.LOCALHOST.Processor(0).% Processor Time % Processor Time is the percentage of time that
the processor is executing a non-Idle thread. This
counter was designed as a primary indicator of
processor activity. It is calculated by measuring
the time that the processor spends executing the
thread of the Idle process in each sample interval,
and subtracting that value from 100%. (Each
processor has an Idle thread, which consumes
cycles when no other threads are ready to run). It
can be viewed as the percentage of the sample
interval spent doing useful work. This counter
displays the average percentage of busy time
observed during the sample interval. It is
calculated by monitoring the time the service was
inactive, and then subtracting that value from
100%.
PERF.LOCALHOST.TCP.Segments Segments Retransmitted/sec is the rate at which
Retransmitted/sec segments are retransmitted, that is, segments
transmitted containing one or more previously
transmitted bytes.
PERF.LOCALHOST.TCP.Segments Sent/sec Segments Sent/sec is the rate at which segments
are sent, including those on current connections,
but excluding those containing only retransmitted
bytes.

Tag Description
PERF.LOCALHOST.Process(piarchss).% Processor % Processor Time is the percentage of elapsed
Time PERF.LOCALHOST.Process(pibasess).% time that all of the threads of this process used the
Processor Time processor to execute instructions. An instruction is
PERF.LOCALHOST.Process(pinetmgr).% Processor the basic unit of execution in a computer, a thread
Time PERF.LOCALHOST.Process(pisnapss).% is the object that executes instructions, and a
Processor Time process is the object created when a program is
run. Code executed to handle some hardware
interrupts and trap conditions are included in this
count. On Multi-processor machines the maximum
value of the counter is 100 % times the number of
processors.
PERF.LOCALHOST.PI Archive.Read Events Rate of archive events read.
operations/sec
PERF.LOCALHOST.PI Archive.Cache Record Disk Archive cache disk reads.
Reads/sec
PERF.LOCALHOST.PI Archive.Cache Record Archive cache memory hits.
Memory Reads/sec
PERF.LOCALHOST.PI Base Subsystem.Point Count Total number of defined points. This number
includes the Connector Point Count.
PERF.LOCALHOST.PI Network The number of connections to PI Network
Manager(_Total).Connections Manager. This counter only applies to instance
_Total.
PERF.LOCALHOST.PI Network The number of messages sent to PI Network
Manager(_Total).Messages Sent/sec Manager.
PERF.LOCALHOST.PI Network
Manager(piarchss).Messages Sent/sec
Manager(pibasess).Messages Sent/sec
Manager(pisnapss).Messages Sent/sec
PERF.LOCALHOST.PI Out of order events sent to the snapshot.
Snapshot.OutOfOrderSnapshots/sec
PERF.LOCALHOST.PI Snapshot.Queued Events/sec Events sent to the event queue.
PERF.LOCALHOST.PI Snapshot.Snapshots/sec Events sent to the snapshot.
PERF.LOCALHOST.PI Update-Manager.Pending Total Events pending in the PIUpdate Manager
events database.
PERF.LOCALHOST.CALCULATED.PI Compression PI Compression Ratio is a performance equation
Ratio that calculates amount of data that is compressed.
PERF.LOCALHOST.CALCULATED.PI Archive.Cache PI Archive.Cache Hit Rate is a performance
Hit Rate equation that measures the rate at which data is
accessed from memory as opposed to disk.
PI Data Archive statistics

Communication Period The frequency the server is configured to
communicate with the collective
Is Available Is the server available?

Is Communicating Is the server communicating to the other members
of the collective?
Is Current Server Is the server the member of the collective sending
this information?
Is In Sync Is the server in sync with the other members of the
collective?
Last Communication Time Last time the server communicated with the
collective
Last Sync Record ID Last sync record processed
Last Sync Time Last time the server synchronized with the
collective
Role The role this server plays in a collective
Server Index The index of the server in the list of members of
the collective
Sync Period The frequency this server is configured to sync
with the collective
Sync Records/sec Sync records processed/sec
PI session statistics
Bytes Received/sec The number of bytes received by the PI session.
Bytes Sent/sec The number of bytes sent by the PI session.
Messages Received/sec The number of messages received by the PI
session.
Messages Sent/sec The number of messages sent by the PI session.
Receive Errors The number of times an error occurs during a
receive a message by the PI session.
Send Errors The number of times an error occurs during a send
of a message by the PI session.
PI snapshot subsystem statistics

Connector GetSnapshots/sec Rate at which events are read from mapped points
included in the GetSnapshots/sec counter.
Connector Snapshot Put Elapsed Time Time elapsed in milliseconds for Snapshot Put for
COM Connector a point.
Connector Snapshot Read Elapsed Time Time elapsed in milliseconds for Snapshot Read
for a COM Connector point.

Connector Snapshots/sec Rate at which events are sent to mapped points
included in the Snapshots/sec counter.
Connector Updates Elapsed Time Time elapsed in milliseconds for Updates for COM
Connector points.
Connector Updates/sec Update events received from COM Connectors.
This rate is NOT included in the Connector
GetSnapshots/sec counter.
Digital State Translations/sec Rate of digital strings translated into offsets.
Estimated Remaining Capacity Estimated maximum number of events with
current queue file.
Event Queue Page Shifts/sec Rate of data page shifts in primary queue file.
Event Queue Total Pages Number of data pages in primary queue file.
Event Queue Used Pages Number of full data pages in primary queue file.
Events in Overflow Queues Total of events in the overflow queue files.
Events in Primary Queue Number of events in the primary queue file.
GetSnapshot Calls/sec Rate of individual snapshot value calls.
GetSnapshots Calls/sec Rate of multiple snapshot values calls.
GetSnapshots/sec Rate at which events are read from the snapshot.
Number of Overflow Queues Number of overflow queue files (0 if only the
primary queue is active).
OutOfOrderSnapshots/sec Rate at which out-of-order events are sent to the
snapshot.
Primary Event Queue Id Identification number of primary queue (0 to
65,535).
Queued Events/sec Rate at which events are sent to the event queue.
Remove Snapshots/sec Rate of snapshot values being deleted.
Snapshots/sec Rate at which events are sent to the snapshot.
PI SQL subsystem statistics

ArcValueCalls/sec Rate of RPC calls made to PI Archive Subsystem to
obtain a single archived value.
ArcValueCompCalls/sec Rate of RPC calls made to PI Archive Subsystem for
compressed events.
ArcValueCompEvents/sec Rate at which compressed data events are
returned by PI Archive Subsystem.
ArcValueTimedCalls/sec Rate of RPC calls made to PI Archive Subsystem for
interpolated or timed events.
ArcValueTimedEvents/sec Rate at which interpolated or timed data events
are returned by PI Archive Subsystem.
Callbacks/sec Rate of calls to PI-SQL execution callback routine.

Dot Variable Evaluations/sec Rate of "dot" variable evaluations made within the
PI SQL Library. A dot variable in SQL is a table alias
and column name, such as "picomp.tag. This rate
is a measure of PI SQL Subsystem processing not
related to obtaining data from other subsystems.
Handles Number of PI SQL handles currently allocated in PI
SQL Subsystem. This is an indication of how many
clients are actively processing SQL statements.
Next Point With Source Calls/sec Rate at which points are returned by PI Base
Subsystem in searches for points with a specific
PointSource attribute.
PostCalls/sec Rate of RPC calls made to PI Snapshot Subsystem
to post events from execution of SQL INSERT or
UPDATE statements.
PostEvents/sec Rate at which data events are posted to PI
Snapshot Subsystem from execution of SQL
INSERT or UPDATE statements.
SnapshotCalls/sec Rate of RPC calls made to PI Snapshot Subsystem
to obtain a single snapshot value.
SummaryArcValueCalls/sec Rate of RPC calls made to PI Archive Subsystem for
summarized values (such as average, total, and
standard deviation).
WHERE Clause Evaluations/sec Rate of full evaluations of the WHERE clause of a
SELECT statement.
WildcardPoints/sec Rate at which points are returned when
performing wildcard searches of the PI point
database.
WildcardSearches/sec Rate at which new wildcard searches are initiated
in the PI point database.
PI subsystem statistics
Actual Pending Transactions Only for internal debugging purpose. You should
use it only under the suggestion of OSIsoft
Technical Support.
Avg. Message Execution Time This generic PI Subsystem counter applies to all
subsystems (one counter per instance). It reports
the average execution time, in milliseconds, of
incoming messages (RPC). This counter is the
average equivalent of the existing PI Subsystem
Statistics(INSTANCE)\Message Execution Time
counter. The existing counter tends to over or
under report the actual value because it is simply
the last value reported and suffers from sampling
problems. The average counter should more
accurately report the true message execution time.

Avg. RPC Requests in Queue This generic PI Subsystem counter applies to all
subsystems (one counter per instance). It reports
the average number of RPCs in queue waiting to be
executed. A consistent and significant number of
RPC requests in queue indicate the subsystem is
saturated processing RPCs.
This counter is the average equivalent of the

existing PI Subsystem Statistics(INSTANCE)\RPC
Requests in Queue counter. The existing counter
tends to over or under report the actual value
because it is simply the last value reported and
suffers from sampling problems. The average
counter should more accurately report the true
number of RPC requests in queue.
Backup Freeze Avg Duration Average milliseconds that subsystem is frozen for
backups.
Backup Freeze Failures Number of failed freeze operations.
Backup Freeze In Progress If the subsystem is frozen, this counter is set to 1.
Otherwise, it is set to 0.
Backup Freeze Last Count Number of freeze operations for the last backup.
Multiple freeze operations may be required for
non-VSS backups.
Backup Freeze Last Duration Number of milliseconds subsystem was frozen for
the last backup.
Backup Freeze Last Transition Number of milliseconds required to put the
subsystem into a frozen state for the last backup
Backup Freeze Max Duration Maximum milliseconds that subsystem has been
frozen for a backup.
Backups Aborted Number of backup abort operations.
Backups Completed Number of backup complete operations.
Backups Started Number of backup start operations.
Callback Execution Rate Number of callbacks executed per second.
Callback Execution Time Execution time of transaction callback.
File Close Number of time File base Close called.
File Compress Number of time File base Compress operations.
File Create Number of time File base Create called.
File Delete/Sec Rate of File base Delete.
File Grow Number of time File Directory grow operations.
File Open Number of time File base Open called.
File Read/Sec Rate of File base Read.
File Write/Sec Rate of File base Write.
Lock Acquisitions/sec Number of successful lock acquisitions per second.
Lock Contentions/sec Number of lock conflicts (threads waiting for the
same lock).
Lock Timeouts/sec Number of lock timeouts (failed locks) per second.

Message Complete Time Total message handling time (including results
sending).
Message Execution Time Execution time of incoming message (RPC). See
also Avg. Message Execution Time.
Message Pickup Time Latency of incoming messages (time in message
queue).
Message Queue Length Number of incoming messages in queue.
Pending Transactions Number of pending transactions.
RPC Requests in Queue Number of pending RPCs in queue. See also AVg.
RPC Requests in Queue.
RPC Threads Active Number of RPC worker threads processing a
query.
RPC Threads Total Total number of RPC worker threads (query
processing).
Transaction Avg Time Average execution time of outgoing transactions.
Transaction Canceled/sec Number of transactions canceled per second.
Transaction Completed/sec Number of transactions completed per second.
Transaction Max Time Maximum execution time of outgoing transactions.
PI totalizer subsystem statistics

EventExpr/sec Rate of EventExpr evaluations.
Filter Changes/sec Rate of Filter state changes
FilterExpr/sec Rate of FilterExpr evaluations
Period End/sec Rate of Totalization period completions
Source Tag Values/sec Rate of Totalizer input events.
Total Point Count The total number of active PI Totalizer Subsystem
points.
Update status The status of the PI Update Manager as perceived
by the PI Totalizer. If non-zero, this is the absolute
value of the most recently received error code. If
zero, all is well.
Updates/sec Rate of snapshot values to Totalizer points
PI update consumer statistics

Get Events calls/sec Get-event calls rate.
Lost events/sec Events lost due to the PI Update Manager database
being full.
New events/sec Event rate for this consumer.

Pending events Total Events pending for this consumer.
Update sign-ups Queued sign-ups for this consumer.
PI update manager statistics

Consumer count Total number of registered consumers.
Get Events calls/sec Total consumers Get-event calls rate.
Lost events/sec Events lost due to the PI Update Manager database
being full.
Max pending events Maximum pending events reached in the PI Update
Manager database.
New events/sec Events sent to the PI Update Manager.
New registration/sec Consumer and Producer registration rate.
Pending events Total Events pending in the PI Update Manager
database.
Update signups Queued signups in the PI Update Manager.
PI update producer statistics

New events/sec Event rate for this producer.
Pending events Total events pending for this producer.
Update calls/sec Rate of incoming update calls.
Update sign-ups Queued sign-ups for this producer.


PI Message Subsystem example messages
The PI Message Subsystem writes the messages that PI Data Archive generates during normal
operation to the PI message log. Use the pigetmsg utility in the PI\adm directory to retrieve
messages.

Client connection messages
Subsystem connection messages
Disconnect messages
RPC resolver messages
Dead process timed out
Client connection messages

PI Network Manager (pinetmgr) writes messages to the PI message log that track
communications between PI clients and the PI Data Archive server.
The following message from pinetmgr indicates that a client is attempting to connect to the PI
Data Archive server. Note that a connection ID (cnxn ID) is assigned.
D 22-Sep-09 21:41:33 pinetmgr (7004)
>> PInet accepted TCP/IP connection, cnxn ID 31 Hostname: , 195.10.22.187: 1269
A PI SDK-based client will first publish its name. In this example the client name is AboutPI-
SDK.exe.
I 22-Sep-09 21:41:33 pinetmgr (7039)
>> Connection accepted: Process name: AboutPI-SDK.exe(4372):remote(4372)
ID: 31
The PI Data Archive server will then attempt to authenticate the client. That is, the client will
pass in certain credentials and the PI Data Archive server will accept or reject these
credentials. In this example the client successfully connects via Windows authentication:
I 22-Sep-09 21:41:33 pinetmgr (7082)
>> Successful login ID: 31. Address: 195.10.22.187. Name: AboutPI-
SDK.exe(4372):remote. Identity List: piadmins | PIWorld. Environment Username :
FABRIKAM\testuser. Method: Windows Login (SSPI,Kerberos)
If the client is unable to connect via one method, it may try another. Here it fails to connect via
Windows authentication but is able to connect via trust.
I 22-Sep-09 22:38:27 pinetmgr (7138)
>> Unsuccessful login ID: 35. Address: 195.10.22.187. Name: AboutPI-SDK.exe(43
72):remote. Credentials used: FABRIKAM\testuser. Method: Windows Login
(SSPI,Kerbero
s). Error: [-10433] No identity mapping for this request
I 22-Sep-09 22:38:27 pinetmgr (7076)
>> Successful login ID: 35. Address: 195.10.22.187. Host: . Name: AboutPI-SDK.e
xe(4372):remote. User: piadmin. OSUser: . Trust: addertrust
The server administrator has the option to disable certain authentication methods. In this
example explicit logins have been disabled. The message will look like this:
I 23-Sep-09 12:52:35 pinetmgr (7138)
>> Unsuccessful login ID: 44. Address: 195.10.22.187. Name: AboutPI-SDK.exe(50

48):remote. Credentials used: piadmin. Method: Explicit Login. Error: [-10431]

Authentication method is disabled by current server policy
If the server is unable to authenticate a PI SDK-based client, it will be
forceably disconnected.
I 22-Sep-09 22:25:03 pinetmgr (7096)
>> Deleting connection: AboutPI-SDK.exe(4372):remote(4372), Shutdown request
received from AboutPI-SDK.exe(4372):remote(4372), ID: 31 195.10.22.187:1269
PI API-based applications have a different set of connection establishment messages. All PI

API-based client connection messages begin with "New Pinet 1 connection". First the Pinet 1
protocol is printed:
D 22-Sep-09 21:04:01 pinetmgr (7051)
>> New Pinet 1 connection: RandE Protocol: 00010008
The PI Data Archive server then attempts to use the credentials of the incoming connection to
locate a record in the PI trust database. If a match is found, the following message is written
(For PI API-based clients the published application name is truncated. The name is a five-
character name: four characters plus a capital "E". In this example, the client name is RandE):
I 22-Sep-09 21:04:01 pinetmgr (7053)
>> New Pinet 1 connection: RandE Successful Trust-Relation login:
adder2k3_32_1.osisoft.int|127.0.0.1|RandE piadmin.
If a match is not found, the messages are:
I 22-Sep-09 21:53:40 pinetmgr (7054)
>> New Pinet 1 connection: RandE No Trust established for: adder.osisoft.int|19
2.168.5.137|RandE. Explicit login is required for access.
I 22-Sep-09 21:53:42 pinetmgr (7077)
>> Access Denied: [-10413] No trust relation for this request ID: 32. Address
: 195.10.22.187. Host: . Name: RandE. User: . OSUser: . Trust:
Subsystem connection messages

pinetmgr writes messages to the PI message log that track communications between utilities
and the subsystems.
New connections requested by one of the PI subsystems are assigned a connection ID:
0 pinetmgr 27-Oct-05 16:23:25
>> Connection accepted: Process name: piupdmgr(3184) ID: 5
The subsystem begins its own initialization.

0 piupdmgr 27-Oct-05 16:23:25
>> Starting PI process piupdmgr.
0 piupdmgr 27-Oct-05 16:23:27
>> PI subsystem piupdmgr is now running, version: PI 3.4.370.52
The above messages may be following by subsystem-specific initialization messages. When

initialization is complete, the subsystem tells pinetmgr which remote procedure calls (RPCs)
it supports. This is indicated in the following message:
0 pinetmgr 27-Oct-05 16:23:26
>> Servertablelist received from: piupdmgr(3184). 4 entries: piupdmgr|1
piupdmgr|2 piupdmgr_subsysquery|1 piupdmgr_dbsecurity|1
When pinetmgr receives notification of new RPCs, it updates the master list, and then sends
the updated list to all PIsubsystems. When a subsystem receives this updated master RPC list,
it writes the following message. At this point, the subsystem is ready to process remote
procedure calls:
0 piupdmgr 27-Oct-05 16:23:27
>> Rpcservertablelist successfully registered to pinetmgr.

If pinetmgr is unable to send the updated list to the new subsystem, it writes a message as
follows:
0 pinetmgr 27-Oct-05 16:32:22
>> Error sending client table(2) to: piupdmgr
A successfully connected subsystem may write messages indicating its initialization progress.
In general, there is no message written when initialization is complete and the subsystem is
ready to process RPC calls.
Disconnect messages
pinetmgr writes messages to the PI message log that track communications between PI
clients and the PI Data Archive server.
The following example show messages from pinetmgr indicating a PI-SDK application
(AboutPI-SDK.exe) is disconnecting from the PI Data Archive server:
I 03-Aug-10 06:47:21 pinetmgr (7096)
>> Deleting connection: AboutPI-SDK.exe(7196), Shutdown request received from
AboutPI-SDK.exe(7196), ID: 39 :0
D 03-Aug-10 06:47:21 pinetmgr:Connection Statistics (7133)

>> ID: 39; Duration: 0.2833333 min.; kbytes sent: 49.07129; kbytes recv:
1.081055; app: AboutPI-SDK; user: piadmin; osuser: ; trust: !Proxy_127!; ip
address: ; ip host:
D 03-Aug-10 06:47:21 pinetmgr:Connection Information (7079)

>> Connection ID: 39 ; Process name: AboutPI-SDK.exe ; User: piadmin ; OS
User: ; IP: ; AppID: 0 ; AppName: AboutPI-SDK (disconnecting)
The following example show messages from pinetmgr indicating a PI-API application
(Random Interface) is disconnecting from the PI Data Archive server:
I 03-Aug-10 10:26:25 pinetmgr (7113)
>> Deleting connection: RandE, A request to abort a connection was received.
Check previous messages for more details. [-10721] PINET: Client Aborted
Connection., ID: 30 ::1:54920
D 03-Aug-10 10:26:25 pinetmgr:Connection Information (7079)

>> Connection ID: 30 ; Process name: RandE ; User: piadmin ; OS User: ; IP: ::
1 ; AppID: 0 ; AppName: PI-IN-UNIINT (disconnecting)
D 03-Aug-10 10:26:25 pinetmgr:Connection Statistics (7133)

>> ID: 30; Duration: 1078.8 min.; kbytes sent: 46.49512; kbytes recv: 151.2598;
app: PI-IN-UNIINT; user: piadmin; osuser: ; trust: !Proxy_127!; ip address: ::1;
ip host:
Sometimes when applications exit without properly terminating their connection to the PI
Data Archive server, pinetmgr can report the following:
I 03-Aug-10 10:25:23 pinetmgr (7121)
>> Deleting connection: RandE, Asynch read failed. [64] The specified network
name is no longer available., ID: 43 ::1:53559
FABRIKAM\FABRIKAM

RPC resolver messages

Every few minutes, the pinetmgr sends a health-check message to each of the PI subsystems.
If one doesn't respond within a given amount of time, pinetmgr will report the following
message and the subsystem (RPC resolver) is marked offline.
>> Deleting connection: pisnapss, Subsystem Healthcheck failed.
If an RPC is made to a subsystem that is marked off-line, the following message is generated.
[-10733] PINET: RPC Resolver is Off-Line
The following message indicates that the first part of a message was retrieved. This contains
the message length. The pinetmgr attempted to retrieve the rest of the message but a timeout
occurred.
>> Deleting connection: pisnapss, Connection lost(1),
[-10731] PINET: incomplete message
Dead process timed out

pinetmgr keeps track of processes that have signed up for updates. It is possible for a process
which has signed up for updates to go away without properly unregistering for updates. If
pinetmgr detects this case, it will remove the dead process from its table and report the
following message:
0 piupdmgr 19-Feb-97 17:31:15
>> Consumer <UNKNE|8> timed out! removed...

Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Tech Support Contact Us page (https://techsupport.osisoft.com/Contact-Us/). The
website offers additional contact options for customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:
Product name, version, and build numbers
Details about your computer platform (CPU type, operating system, and version number)
Time that the difficulty started
Log files at that time
Details of any environment changes prior to the start of the issue
Summary of the issue, including any relevant log files during the time the issue occurred
To ask questions of others who use OSIsoft software, join the OSIsoft user community,
PI Square (https://pisquare.osisoft.com). Members of the community can request advice and
share ideas about the PI System. The PI Developers Club space within PI Square offers
resources to help you with the programming and integration of OSIsoft products.

Technical support and other resources

Index
134

Index

PI Data Archive 2015 Reference Guide en

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

PI Data Archive 2015 Reference Guide en

Hochgeladen von

Copyright:

Verfügbare Formate

PI Data Archive 2015

PI Data Archive 2015 Reference Guide

About this document................................................................................................. 1

PI Data Archive command-line utilities........................................................................ 3

PI Data Archive 2015 Reference Guide iii

View the next predicted archive shift time................................................................................................. 40

iv PI Data Archive 2015 Reference Guide

Identity table (PIIDENT)............................................................................................................................. 78

PI Data Archive 2015 Reference Guide v

Hexadecimal and octal numbers.............................................................................................................. 110

vi PI Data Archive 2015 Reference Guide

PI Data Archive database files................................................................................. 147

PI Performance Counters........................................................................................ 153

PI Data Archive 2015 Reference Guide vii

PI Message Subsystem example messages............................................................... 173

Technical support and other resources..................................................................... 177

viii PI Data Archive 2015 Reference Guide

PI Data Archive 2015 Reference Guide 1

2 PI Data Archive 2015 Reference Guide

Executable Location Purpose

Remote operation of PI Data Archive utilities

PI Data Archive 2015 Reference Guide 3

-node Argument or Description

4 PI Data Archive 2015 Reference Guide

PI Data Archive 2015 Reference Guide 5

6 PI Data Archive 2015 Reference Guide

To exit the ipisql utility, type: exit;

Topics in this section

Options for the ipisql command

PI Data Archive 2015 Reference Guide 7

ipisql option Description

If the file myquery.txt contains the statement:

You can use as many lines as you like.

8 PI Data Archive 2015 Reference Guide

Topics in this section

Options for the offline archive utility

PI Data Archive 2015 Reference Guide 9

Option Name Description

Offline archive utility processing

10 PI Data Archive 2015 Reference Guide

On the first pass, the utility:

Run the offline archive utility

Topics in this section

PI Data Archive 2015 Reference Guide 11

Tips for using the offline archive utility

Specify a start time for the output file

Where option is one of the following:

12 PI Data Archive 2015 Reference Guide

Specify an end time for the output file

where option is one of the following:

Specify an ID conversion file

PI Data Archive 2015 Reference Guide 13

ID Conversion input file format

Offline archive utility exit codes

14 PI Data Archive 2015 Reference Guide

Event queue files and offline archives

Topics in this section

Move event queue files

PI Data Archive 2015 Reference Guide 15

Load event queue into an offline archive

Correcting event timestamps (-tfix -tfixend)

Topics in this section

Time conversion file format