Professional Documents
Culture Documents
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, IT
Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI
ProfileView, 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.
Published: 11/10/2009
Table of Contents
Command-Line Utility Reference .................................................................................................. 1
Use PI Server Utilities Remotely ........................................................................................ 2
apisnap and pisnap.bat ...................................................................................................... 3
ipisql ................................................................................................................................... 3
piarchss (the Offline Archive Utility) Reference ................................................................. 5
piartool Reference ............................................................................................................ 11
piconfig Reference ........................................................................................................... 35
pidiag Reference .............................................................................................................. 93
pigetmsg Reference ....................................................................................................... 114
pilistupd Reference......................................................................................................... 118
pipetest ........................................................................................................................... 122
pisetpass ........................................................................................................................ 122
piversion ......................................................................................................................... 123
iv
About this Document
The PI Server Reference Guide provides a reference to the PI Server command-line utilities.
It also lists PI Server error codes, messages, performance counters, and database files.
This guide assumes that you have a basic knowledge of the PI Server and how to perform
typical system administration tasks. See the Introduction to PI System Management guide for
this information. For more in-depth information about managing the PI Server, see the PI
Server System Management Guide. For information on configuring security (authentication
and access permissions) on a PI Server, see Configuring PI Server Security.
piartool.exe PI\adm PI Archive Tool; Use to mount Archive files, and monitor,
inspect, or modify the state of a running PI Server.
pidiag.exe PI\adm Use for diagnostics and offline repair of the PI Server.
See the Help menus in PI SMT, PI Tag Configurator, and Collective Manager, for more
information about these administrative tools.
Use the -? argument to view details about any PI Server command-line utility. For example:
pilistupd -?
Note: If you authenticate with an explicit login, enter –username PI_username and
-password password.
• Utility argument
For example, to use Windows authentication:
piartool -node pi380tst -Windows –al
To authenticate with an explicit login:
piartool –node pi380tst –explicit –username piuser –password march380
-al
You can also use the option -remote to run utilities remotely. For example:
pilistupd -remote
Enter these connection parameters when prompted:
ο PI Server home node host name or IP address
ο Port ID (defaults to 5450)
ο PI User account name
ο PI User account password
To enter the connection parameters when you start the utility:
piconfig -remote pi380tst -port 5450 -username piuser -password
march380
2
apisnap and pisnap.bat
Note: There is also a script in the PI\adm directory called pisnap.bat. This script runs
the apisnap utility and connects to PI Server on the same computer.
ipisql
This utility is an interactive program that executes SQL statements directed at the PI Server.
It uses the PI API to connect to the PI Server.
The ipisql utility is in the PI\adm\ directory. To start the utility, enter its name at a
command prompt. The utility connects to the default PI 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 ipisql, enter exit followed by a semicolon. The error code from the processing of
the last SQL statement is the return code of the ipisql utility. This allows error detection if
ipisql is used in a script.
ipisql Options
The ipisql utility supports several options that can be specified on the command line.
Most of the options are exactly the same as the command-line options for the PI SQL
Subsystem itself, specifically timeout (-t), timestep (-ts) and options (-o). ipisql supports the
option tokens AGGRTIMESTART, EXECSAFE, QEP, SUBSET, and ANSISQLVAL.
The options argument supports the same option tokens as pisqlss, except LOG and TRACE.
In addition, ipisql supports the option token ANSISQLVAL, which is not supported as a
command-line option for pisqlss. When the option ANSISQLVAL is set, the values for the
integer points are returned in the VALUE column. If this option is not set, the values for the
integer points are returned in the STATUS column.
-csv Write results to standard output in comma-separated variable format suitable for
importing into a spreadsheet. The query text, column headings, row count and
error information are written to standard error, also in comma-separated variable
format. No command prompts are displayed.
-f Identifies a query file. If this argument is used, ipisql executes the query in the
specified file and exits. A command prompt is not displayed.
-node Identifies the PI Server node to connect to. The name to use is the PI Server
computer's network name. If the PI server 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.
For example, to execute query in the file myquery.txt against the PI 3.4 System larry
with port number 5450 using a default timestep of two minutes, enter:
ipisql -ts 120 -f myquery.txt -node larry:5450
If the file myquery.txt contains the statement:
select * from picomp where tag = ? and time >= ?
you might avoid the prompt for SQL parameter values by entering:
ipisql -f myquery.txt -p0 sinusoid -p1 "today"
4
piarchss (the Offline Archive Utility) Reference
Submitting Queries
SQL statements can be typed at the prompt and terminated with a semicolon ( ; ). This
causes the query to be sent to PI. The query can Span multiple lines. The prompt for
subsequent lines looks like:
_PISQL>
You can use as many lines as you like.
You can also process queries stored in a text file using the FILE command:
PISQL>file myquery.txt;
A query in a file need not be terminated with a semi-colon; the query 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.
Note: The archives that are created by the Offline Archive Utility may be either fixed or
dynamic. Their format is not different from any other archives created by piartool
-ac.
About piarchss
During processing, piarchss makes two passes through the input archive file. On the first
pass, the utility checks all records in the input archive file. Every record that contains valid
data, and is within the specified time range, is added to a list. The list is sorted by time and
point ID to assure data is loaded in chronological order. The point ID of the input record is
verified. Any required point ID conversion is performed using the specified conversion table.
For example, conversion is required when you migrate archives from a PI2 or from another
PI3 System to your PI Server. An error message is issued for every record for which a point
could not be found in the local PI Server. These messages can be suppressed if desired.
Statistics are displayed approximately every five seconds, at the end of the first pass, and at
the end of the second pass.
During the second pass, records from the sorted list are written to the output file. The input
data is optionally filtered or modified. If the output archive file does not exist, it is created.
The archive header is initialized based on command-line specifications. If the output file
already exists, the input data is added. If a primary record does not exist for a given point ID,
the data for that point ID is discarded.
The input data is converted to the output point type, if different from the input point type. All
auxiliary data, such as index records and record links, are recreated during the load. Only
actual data are read from the input, and thus, any errors in the input file auxiliary data are
repaired.
The Offline Archive Utility is actually the same Archive subsystem executable, piarchss that
is a part of a running PI system. To use the archive utility functions of piarchss, you run it in
console mode using special command-line arguments. The offline archive utility can be used
even while PI is running.
You typically use the piarchss utility to work with archive files outside the context of a
running PI Server. This enables you to continue archiving current data on your PI Server,
while manipulating other archives offline. Typical applications of the offline tool include:
• 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
Note: The archives that are created by the Offline Archive Utility may be either fixed or
dynamic. Their format is not different from any other archives created by piartool
-ac.
Running piarchss
When you run piarchss as the offline archive utility, indicate an input archive file and an
output archive file, along with relevant command parameters. The basic format is:
piarchss -if inputPath -of outputPath
where inputPath is the full path and file name of the input archive file and outputPath is the
full path and file name of output archive file.
6
piarchss (the Offline Archive Utility) Reference
The piarchss utility takes the input file, processes it according to the command parameters,
and then outputs the processed file to whatever location you specified. The piarchss utility
does not modify the input file under any circumstances.
• 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 piartool -fs or temporarily shut down the 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.
• By default, the piarchss offline archive utility creates dynamic archives. Use the -f
argument to specify a fixed archive.
• You can run the piarchss offline archive utility while the PI System, including piarchss
itself, is running. At a minimum, the pinetmgr, pibasess, and pisnapss
subsystems must be running, because the utility needs to access the Point Database
during off-line operations.
-id pathname Specify ID Specify the ID conversion binary path and filename.
conversion file See Specifying an ID Conversion File (-id) (page 33).
-if pathname Input archive Required. The full path, including drive letter is
file required. This is true for all file arguments passed.
-oet option Output file end Options: Input, Event, time, NFE, Primary, NoChange.
time See Specifying an End Time for the Output File (-oet)
(page 8).
-of pathname Output Archive Required.
File
-ost option Output file Options: Input, Event, time, NFE. See Specifying a
start time Start Time for the Output File (-ost) (page 8).
-silent Silent mode Suppress warning messages.
-tfix Time fix Apply a specified time transformation to input data. See
Transforming Event Timestamps (-tfix).
-tzf pathname Time zone Use when input is different from standard DST.
specification
file
-vah Validate Apply a validation algorithm. Multiple events
annotation referencing a single annotation are detected and fixed.
handles Batch Database annotations are checked for
consistency.
8
piarchss (the Offline Archive Utility) Reference
Later, the renamed Event Queue file can be loaded into an offline archive. The input file is
the saved Event Queue data file. The argument -evq indicates the input file is an Event
Queue. The resulting output archive might have dates that overlap existing archives. Offline
processing, as discussed above, is required to combine these archives. Here is an example
command line using piarchss to recover an Event Queue:
piarchss -if D:\pi\dat\pimapevq.save -of D:\pi\dat\piarch099.dat
-evq
Note: In most cases the Event Queue is the above file. But, it is possible to have
multiple Event Queues. The utility piartool -qs indicates if your system uses
multiple queues. If multiple queues are used, the queue naming convention is
pimapNNNN.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.
Also, the memory mapped file approach introduced in version 3.4 and other enhancements
allows PI to handle out-of-order data much more efficiently. Thus, in most cases, offline
processing of the Event Queue is not necessary.
Note: The Offline Archive Utility will not work in descending or random time order.
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.
This example demonstrates how to combine archives:
piarchss -if D:\pi\dat\oldest.dat -of D:\pi\dat\bigfile.dat
10
piartool Reference
In this example, january.dat and february.dat do not exist prior to the operation.
They are created as dynamic archives by default. After they are created, they may be
registered using piartool -ar, and then events may be added to the archive files in the usual
way. Both output archives are not shiftable because they were created by the Offline Archive
Utility as dynamic archives.
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 (page 8) and Specify an End Time for the Output File (page
8).
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 it again.
piartool Reference
This table lists the command-line options you will use to manage archives with the piartool
utility.
Note: PI Server must be running when you use piartool. For details about the offline
archive utility, see Manage Archives of Offline PI Server (page 6).
-aag Archive Activity Enable/Disable the archive activity grid, and list the
Grid Archive access information.
12
piartool Reference
-lic [Options listed Licensing Usage List general license and usage information
under Action] Information Def [-select "mask"] List all licenses. The
-select option lets you do a wildcard selection
instead of displaying the entire list of licenses. For
example, piartool –lic def –select
piarchss* shows all the licenses whose names
start with "piarchss".
User [-select "mask"] List all license users.
The -select option lets you list only the users
matching the wildcard mask.
Lic [-select "mask"] List all licenses and
users. The -select option allows you to list only the
licenses and users matching the wildcard mask.
AllowedApps [-List type,type...|-Check
app,app,...]
List the licenses of the specified application types or
check whether a specific feature is licensed. The
valid application types include: PIService, PIUtility,
OSIInterface, OSIMiddleWare, OSIAPIApp,
OSISDKApp, ServerApp, APIApp, SDKApp.
Note: When a PI server is not running, piartool
does not work but you can use pilicmgr -lic
usage and pilicmgr -lic def to list the license
information.
-mpt {0|1} Message protocol Log all communication coming to and from the
[For troubleshooting trace server.
only] To enable tracing run with -mpt 1. Call a second time
with -mpt 0 to stop tracing.
The resulting output file appears in the \pi\temp
directory with the .mpt extension.
The file can be read with the mptconsolveview utility,
which OSISoft provides on request, e.g.:
Mptconsolveview .\24-Aug-05_12-10-06.mpt
-msg "message" Message Sends a series of test messages to the PI message
[-pro "procname"] Subsystem Test log. Can emulate sending messages from any
process. nrep sets how many messages are sent,
[-nrep m]
nbuf sets how many messages are sent at a time,
[-nbuf l] nmps attempts to throttle how many messages are
[-nmps n] sent per second.
[For troubleshooting
only]
14
piartool Reference
You can use the piartool –backup commands to launch a VSS or non-VSS backup or to
issue other auxiliary backup commands. For more information about backups and backup
types, see the PI Server System Management Guide.
Argument 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 depending
upon their current location. For example, if an archive is in the
C:\PI\archives directory, then it is backed up to path\archives.
Similarly, if an archive is in the C:\PI\dat directory, then it is backed up to
path\dat.
-archive N Back up only the specified archive number N and its associated annotation
file.
Archive numbers begin at 0 for the primary archive. This flag is ignored if
the -component flag is specified.
The -archiving flag takes precedence over the -numarch and -cutoff flags.
-component comp Back up only the component specified by comp. For example:
piartool -backup c:\pi\backup -component pibasess
backs up only the files that belong to the PI Base Subsystem. As a second
example, the command:
piartool -backup c:\pi\backup -component
piarchss
backs up only the piarchss component. Notice that the full path name of the
piarchss component, PI Archive Subsystem\piarchss, is not used when
specifying the component name. See Backup Components of the PI Server.
To see a full list of the components, enter:
piartool –backup –identify –verbose
The -component flag takes precedence over the -numarch and -cutoff flags,
which are used only to restrict the number of archive components that are
backed up. If the -component flag is not specified, all components are backed
up except for the archive components that are restricted from backup by the
-numarch and -cutoff flags.
The -component flag also takes precedence over the -archive flag.
Argument 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.
-incremental Files are not backed up if a file in path has the same name, last modified date
and file size as in the source directory. If path does not exist or if there are no
files in path, then the –incremental flag has no effect.
-nonvss Perform a non-VSS backup on Windows Server 2003 or greater. This option
has no effect on Windows XP or Windows 2000.
-numarch N Back up N archives.
For example, specifying -numarch 2 backs up the primary archive and
archive 1, provided that the primary archive and archive 1 contain data. Empty
archives are not identified for backup. The default number of archives for
backup is 3, unless otherwise specified by the Backup_NumArchives
timeout parameter.
This flag is ignored if the -component or -archive flag is specified.
-wait [sec] Wait up to sec seconds for the non-VSS backup to complete before returning
from the piartool -backup command. The progress of the backup is reported
every 15 seconds and when the backup is complete, the status of the backup
is reported via piartool -backup -query.
If the -wait flag is used without specifying the optional sec parameter, then the
piartool -backup command waits up to 1 day for the backup to complete.
If the -wait flag is not specified, then piartool -backup 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.
16
piartool Reference
Argument Description
-identify Reports the list of files that PI will back up. If the -verbose flag is
[-numarch number] specified, the command reports a list of files and components.
[-cutoff date] A component is a logical grouping of files. For example, all of the files
[-verbose] for the base subsystem are grouped under the pibasess component.
The purpose of a component is to identify a group of files for backup.
The -numarch and -cutoff flags have the same meaning as the
corresponding piartool -backup path command that is used to start
backups. See Launching Backups with piartool (page 15).
The identify command creates a \pi\dat\pibackupfiles.bks file.
This file contains the list of files that need to be backed up for the PI
Server. The number of archives in the list is restricted by the -numarch
and -cutoff parameters.
This file was used by NTBackup.exe for backups in 3.4.370 as
described in Upgrade Considerations. The pibackupfiles.bks file is still
created for backwards compatibility.
Example:
piartool -backup -identify -verbose
-SimulateVSS Simulates the COM+ events of a VSS backup without backing up any
simulate_command files. See Lifetime of a VSS Backup for a complete description of the
COM+ events. The -SimulateVSS commands are useful for third-party
backup applications that can take snapshots but do not communicate to
the PI Server via the VSS API.
-SimulateVSS -PrepareBackup2Freeze 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 -SimulateVSS -Thaw2PostSnapshot in conjunction with
-SimulateVSS -BackupShutdown ends the simulated VSS backup.
-test –freeze component Freezes the specified component. For example, piartool -backup -test
-freeze -pibasess prevents any modification to the PI Point Database,
Module Database, Digital State table, and so on.
For a complete list of components, enter the piartool -backup
–identify -verbose command.
The other subsystems either do not have files that need to be backed up or they do not need to
be running for a backup to succeed.
18
piartool Reference
-cutoff parameters or, if these parameters are not specified, the Backup_ArchiveCutoffDate
and Backup_NumArchives timeout parameters. The output has the format:
e:\pi\adm>piartool -backup -identify
FileName_1
FileName_2
FileName_3
...
Whenever the backup identify command is run, a backup selection file,
PI\dat\pibackup.bks, is created. This file was used by NTBackup.exe for backups in
3.4.370 as described in Upgrade Considerations, and is still created for backwards
compatibility.
The piartool -backup -identify -verbose command lists detailed information about the
components and files that are backed up by the PI Backup Subsystem. The components and
files that are listed should correspond to the components and files described in Backup
Components of the PI Server.
The piartool -backup -identify -verbose command includes the following file information:
Name File Information
ComponentName The component that the file belong to.
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.
The last backup date is not stored for any files belonging to the
SettingsAndTimeoutParameters component and for all PI message logs,
except for the PI message log that is currently in memory.
LastModified Last modified time of the file.
SizeInBytes Size of the file in bytes.
Create Archives
These utilities allow you to name the new archive, specify its location, create it, and initialize
it:
• piarcreate
• piartool -ac
• piartool -acd
The piarcreate utility creates an archive without registering it. You can specify the size of
the archive with piarcreate, but you must complete a second step to register the archive. Use
the -d flag to create a dynamic archive. With piarcreate, you can specify the maximum
number of points and maximum size of a dynamic Archive. See Set the Maximum Archive
Size for details.
Note: With piarcreate, the impacts to system resources are minimal. Therefore, use of
this utility is considered the most efficient way to create archives. However, you
cannot specify start and end times using piarcreate.
You may use the piartool utility to optionally specify the following for new archives: the
start and end times for both fixed and dynamic archives, the maximum size for dynamic
archives and the fixed size for fixed archives. Use option -ac to create a fixed-size archive
and option -acd to create a dynamic archive. With both piartool -ac and piartool -acd, the
default created archive size matches the current Primary Archive size, and registration is
automatic.
Every archive has a parallel annotation file that has the extension .ann. The file is created
automatically by either utility. It must remain in the same directory that contains its archive
file at all times.
This procedure will create and register a new archive. The archive
path and optional start/end times or size may be specified.
Would you like to initialize the start and end times (y/n)? y
20
piartool Reference
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
Note: To review the message log for the archive created in this example, enter
pigetmsg - st t -et * -pn piarchss. See Search for and Sort Messages
with pigetmsg for details.
This procedure will create and register a new dynamic archive. The
archive path and optional start and end times may be specified.
Would you like to initialize the start and end times (y/n)? y
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
Note: To review the message log for the archive created in this example, enter
pigetmsg - st t -et * -pn piarchss. See Search for and Sort Messages
with pigetmsg for details.
22
piartool Reference
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.
Annotation file statistics are shown with the Archive listing utility piartool -al. The
following is output from an Archive listing:
Archive[0]: D:\PI\dat\piarch.033 (Used: 1.8%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: $]::
Version: 7 Path: D:\PI\dat\piarch.001
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 1.7
Offsets: Primary: 20/65536 Overflow: 128673/131072
Annotations: 10826/65535 Annotation File Size: 434144
Start Time: 19-Oct-05 12:39:10
End Time: Current Time
Backup Time: Never
Last Modified: 19-Dec-05 13:10:32
In the above listing, the Archive file is d:PI\arc\piarch.033. The corresponding
Annotation file is d:PI\arc\piarch.033.ann. There are 10,826 annotations; with
room for a total of 65,535 and the Annotation file is 434,144 bytes (424 KB).
The Annotation file is created if it does not exist. It is important the Archive and Annotation
files remain together, especially when a backed up Archive file is restored.
Note: The PI SDK supplies a programmatic interface for creating, accessing, and editing
annotations. The PI SDK User Guide and online help are the best source for
details on valid variants for annotations.
Unregister an Archive
Any archive may be unregistered except the Primary Archive (archive number 0), which
stores the current data. Use this command to drop an archive from the list of registered
archives:
piartool -au path
where path specifies a complete, not relative, pathname. 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
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*
Register an Archive
To register archives, you use the piartool -ar command. The syntax is:
piartool -ar path
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
The specified path must be a complete, not relative, path of an existing archive file. You can
use the wildcard characters * and ? to register archives in bulk. The symbol * matches all
possibilities with any number of characters. The symbol ? matches a single character and may
be used any number of times.
For example, the following command registers all archive files in the PI\dat directory that
begin with the piarch.0 prefix:
piartool -ar D:\PI\dat\piarch.0*
Note: piartool -aes does not re-enable dynamic archives for shifting.
24
piartool Reference
For systems with large point counts, archive shifts may require a several minutes. As soon as
the shift starts, messages are written to the PI message log, such as:
0 piarcmgr 2-Apr-03 14:32:39
>> Forced archive shift requested.
0 piarcmgr 2-Apr-03 14:32:39
>> Beginning Archive Shift. Current Primary Archive:
d:\pi\dat\piarch.001
0 piarcmgr 2-Apr-03 14:32:39
>> Target Archive for Shift: d:\pi\dat\piarch.003
0 piarsrv 2-Apr-03 14:32:39
>> Clear and Initialize archive file: d:\pi\dat\piarch.003
0 piarsrv 2-Apr-03 14:32:48
>> Archive clear progress: 51200 records cleared.
0 piarsrv 2-Apr-03 14:32:58
>> Archive clear progress: 102400 records cleared.
0 piarsrv 2-Apr-03 14:33:08
>> Archive clear progress: 153600 records cleared.
0 piarsrv 2-Apr-03 14:33:19
>> Archive clear progress: 204800 records cleared.
0 piarsrv 2-Apr-03 14:33:28
>> Archive successfully cleared 256000 records
0 piarsrv 2-Apr-03 14:33:28
>> Archive successfully initialized 16285 points.
0 piarsrv 2-Apr-03 14:33:28
>> Archive file Clear and Initialize completion status[0] Success
0 piarcmgr 2-Apr-03 14:33:28
>> Completing Archive Shift. Current Primary Archive:
d:\pi\dat\piarch.001
0 piarcmgr 2-Apr-03 14:33:28
>> Archive d:\pi\dat\piarch.001 shifted successfully. New Primary
Archive is d:\pi\dat\piarch.003
Do not shut down the PI Server until the shift has completed. To determine when this has
occurred, check the message log for a message like:
0 piarcmgr 2-Apr-03 14:33:28
>> Archive d:\pi\dat\piarch.001 shifted successfully. New Primary
Archive is d:\pi\dat\piarch.003
Backfilling Data
At times it may be useful to make data available in PI that was collected prior to the PI
installation. Several applications can be used for this procedure, known as backfilling. You
may use a PI API or PI SDK application, piconfig, or the batch file interface. Your choice
depends mainly on how the data that will be entered into PI is currently stored.
connections at the server. To do this, start piconfig without starting PI. Disregard
messages about failure to connect and enter:
@table pifirewall
@mode edit,t
@istr hostmask,value
"*.*.*.*",DISALLOW
Note: Entries that allow access to specific names or addresses override the
DISALLOW. Edit all other entries to DISALLOW. Local connections are not
affected by PIFirewall table entries; verify that applications that may write
data are not running.
3. Start PI with the -base parameter. This ensures that PI starts up with only the minimum
required subsystems. Enter the command:
pisrvstart.bat -base
4. Use piartool -ac or -acd to create and register archive files for the backfilling period.
5. Use piconfig or other tools to insert one event for every point at the earliest time on-line.
6. Delete all the PointCreated events from the snapshot. This will bring into the
snapshot the old events. This can be done with a PI API or PI SDK program or with the
piconfig utility. Verify that the old event is in the snapshot.
7. Backfill the archives by reading in the data in Time Sequential Order. This way the data
is compressed.
Caution: The Archive Subsystem assumes the snapshot time is the most recent
time stamp written to any point. To enable compression, it is important to keep
all current data sources from writing to the PI Server. This is why Random,
Ramp Soak, Performance Equations, PI Total, PI Alarm, or any other
interfaces cannot be running.
8. If you used the technique of modifying the PIFirewall table in Step 2 above, run piconfig
to either change the hostmask value to Allow or delete the above hostmask altogether.
9. Start the interfaces using pisrvsitestart.bat.
Note: You can backfill data using an archive created with a start time prior to point
creation time, provided the point data exists when that archive is created.
Reprocessing an old archive with the offline utility adds to that archive all
existing points, while preserving all the old data.
26
piartool Reference
2. Use piartool -ac to create and initialize back fill archives. The start and end times must
be specified. The start time should be the timestamp of the oldest data to be backfilled;
the end time should be just prior to the oldest archive time specified using piartool -al.
3. Backfill the data. The data that you backfill is not compressed, since it is prior to the
snapshot time.
4. If the backfill archive is filled before all of the backfill data is entered, you must delete
the backfill archive, and create two backfill archives. Next, divide the target time range
between the two, or create a single larger archive, and then retry the data backfilling.
Note: The default archives are sized at the time of installation when the installer answers
prompts from the installation wizard.
Note: The piartool utility can run remotely by specifying some additional parameters
on the command line. For details, see Using the piartool Utility (page 11).
28
piartool Reference
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 the
Archive Subsystem. The utility piartool –bs places the archive in a safe consistent state for
backups; piartool –be returns the archive to normal operation.
The cache consists of archive records loaded into memory. Cache Records Created is
incremented when memory is allocated for a new record.
When archive data is requested, as for example, when a user is trying to trend a point in PI
ProcessBook, the Archive Subsystem goes to the cache to retrieve the event data. If the
record is not there, the Archive Subsystem loads the record from disk to the cache; Archive
Record Disk Reads is 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.
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.
30
piartool Reference
You should verify the proper sizing and functioning of the Event Queue, after you install or
upgrade PI Server, or backup the server after significant changes. The command piartool –qs
allows you 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.
1. Enter piartool –qs to list the Event Queue statistics every 5 seconds.
2. Review the output.
3. Compare the difference in the count in the column at the right margin to the count from
the previous 5 seconds. The counters are reset to 0 when the Archive Subsystem is
started.
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, the Snapshot Subsystem tries to write into the next page and the
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 the Snapshot Subsystem is currently writing to.
Similarly, the Read Page Index indicates the page from which the Archive Subsystem is
reading. Under normal conditions, these two numbers are identical. If the Archive Subsystem
is not reading at the same pace the Snapshot 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
The 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
the Snapshot Subsystem was last started.
Event Rates
Every time the Snapshot sends an event to the archive, the Total Event Writes counter gets
incremented. Similarly, when events are read by the Archive Subsystem, 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, the 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 always 0
under normal conditions.
Activity Grid
The Archive Subsystem provides a tool to monitor the rate of 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.
32
piartool Reference
Note: 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.
Use the -id option to specify an ID conversion file when you reprocess archives. For
example, when you move a PI archive to a different PI Server. The ID conversion file is a
binary file that maps the source archive point ID into the target system point ID. When the ID
conversion file is used, only points included in this file are converted.
This is always necessary when data is brought from another PI3 system.
The binary file is created from an input text using the piartool utility.
piartool -idci ID_conversion_input_file -idco
ID_conversion_binary_file
The ID_conversion_input_file is the full path and file name for the input text file.
The ID_conversion_binary_file is the full path and name for the binary file to be created.
piartool reports any point in the input file that does not exist in the target system.
Note: The piartool -idci input file does not allow for comment characters. The comment
character (*) generated by piconfig must be removed.
To get a record dump of the Snapshot for a point, you use piartool -sd tagmask. For example,
to get the Snapshot information for sinusoid, you would type:
piartool -sd sinusoid
You would get back something that looks like this:
*** Point RecNo: 1, Tag: SINUSOID (1 / 1)
* Dump of Snapshot Record, Point ID: 1
-- Configuration:
type: Float32 (12), zero: 0, span: 100
archiving: 1, compressing 1, step: 0, filter code: 0
compression min: 0, max: 28800, deviation: 2
-- Security:
ACL ID: 2 [ 1:A(r,w)|5:A(r,w)|2:A(r) ]
-- Snapshot Event:
time: 16-Oct-09 17:04:48 (utc: 1255737888)
type: 12, value: S,O,A,S,Q [0,0,0,0,0]: 73.1651, 73.1651
-- Compressed Event:
time: 16-Oct-09 16:40:48 (utc: 1255736448)
type: 12, value: S,O,A,S,Q [0,0,0,0,0]: 81.8715, 81.8715
-- Compression State:
out-of-order: 1, compression slopes: -0.00743496, -0.00465718
updates: 0, 3ph: 0, buffered: 0
dirty: 1, bits: 0x8070c, delete pending snap/comp: 0/0
* End of Dump
*** 1 points successfully listed in 0.157 sec.
Note: You can also use the apisnap utility to check Snapshot values.
34
piconfig Reference
You can use the piconfig utility to maintain and configure PI Server databases such as the
Point Database and the Digital State table.
The piconfig command-line application runs on the PI Home node. You can work
interactively with piconfig or you may supply text files that contain commands and data. You
may use piconfig to configure point information in a spreadsheet or database tool, export it to
a text file, then apply it to the Point Database.
The piconfig utility can also be used 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.
localuser user name None Allows you to specify local user name when
CheckUtilityLogin Tuning Parameter is set to 1
(On).
localpass password None Allows you to specify local password when
CheckUtilityLogin Tuning Parameter is set to 1
(On).
Maxerr N 10 Sets the error tolerance. piconfig will exit when the
number of errors reaches n. 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.
Mode Flag List Specifies mode of operation: Create, Edit, Delete,
List, Compare, Convert, Create, and Edit mode can
be modified to include both. Specify the mode flag
as Edit,t or Create,t.
For check only specify Edit,c or Create,c.
Modify Modification None Defines field modifications.
Ostructure Structure None 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 Flag D Selects output data format structure type: Fixed,
Delimited, or Keyword. (F,D,K)
Output File None Redirects output to file. If file is not specified, the
output is directed back to standard output.
Prompt Flag No Sets prompt mode: yes (for interactive sessions) or
no (for batch sessions)
Ptclassnam Classname Base Specifies the point class: base or classic. Pipoint
e Table only.
Quote C None Tells piconfig to enclose output fields with quote
Must be ' or “ character 'c' if they contain the delimiter character
36
piconfig Reference
Select PI Tables
Whether you use an interactive session or a script file, to update a table with piconfig you
must:
1. Select the PI table of interest.
2. View the current setting of the table.
3. Display table attributes.
Select a Table
Use the table command to select a table. The currently selected table is indicated by the
prompt.
No table is selected until the first table command is issued. The table remains selected until
the next table command.
* (Ls - ) piconfig> @table pipoint
38
piconfig Reference
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:
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:
Each of the table attributes can be viewed, set, or modified. Conceptually, each table in the
piconfig utility has several columns, where the column headers are the attributes. Each row is
a table record. For the PIPOINT table, each row corresponds to a particular tag.
RECORDS
piconfig views its tables 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:
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
40
piconfig Reference
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 PI Point 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
Note: Some tables do not support renaming of records, for example PIARC and PISNAP
tables. Tag is the primary key of these tables. Since Tag is actually a point
attribute, the rename must be down from the PIPOINT table. Other tables have
similar relationships.
42
piconfig Reference
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.
Use this mode to validate points and report errors, but not make changes to the Point
Database.
Check mode can also be specified for create/edit.
@mode create, t, c
@mode edit, t, c
The specified mode persists until the next mode command is issued.
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
44
piconfig Reference
Note: The same delimiter character is used between piconfig attributes, between
elements of a piconfig command and between both input and output data fields.
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
Note: The lines starting with the asterisk (*) are comment lines and are ignored.
Their only purpose is to improve readability.
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.
Note: 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 ( , ).
The istructure 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. A single
attribute is specified on each line, as shown below:
@ostructure tag
@ostructure pointsource
@ostructure pointtype
To output all attributes for the current table, enter:
@ostructure *
This works in both keyword and delimited formats.
Note: The command @ostructure is meaningful only in list mode. A warning is issued if
this command is executed in create, edit or delete mode.
Operators
Use following comparison operators for 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.
46
piconfig Reference
Exit
Exit is the command that terminates the piconfig session. It is not necessary to use this
command when running piconfig in batch mode because the end of file causes piconfig to
execute the current commands and then exit. Quit and Bye have the same effect.
Batch Methods
48
piconfig Reference
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.
Redirect Output
An alternative is to use standard redirection from the command line:
$ piconfig < list.inp > list.out
Note: If you authenticate with an explicit login, enter –username PIUser account
name and -password password.
• Utility argument
For example, to use Windows authentication:
piconfig -node pi380tst -Windows
To authenticate with an explicit login:
50
piconfig Reference
Note: You may specify the parameters -port, -username and -password in any order,
after -remote.
If you are passing any piconfig arguments on the command line, enter them before the
-remote option. For example:
piconfig input piarc.dif -remote -node figaro -port 5450 -username
piadmin -password myadminpassword
PI Server Tables
These are the PI tables that can be viewed and edited with piconfig:
Database Table Names Primary Key
Points PIPOINT TAG
Note: As of release 3.3, the Proxy Database is no longer in use. During upgrade, its
contents are converted to PI Trust Database records.
52
piconfig Reference
These attributes are the same as the PISNAP 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 (page 54)
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.
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.
54
piconfig Reference
The piconfig 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:
@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.
@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
It is important that no spaces be included between parameters, so that the input file and it's
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
Note: The default time accuracy of 5 digits might compromise a sub-second time-stamp.
Expand to 6 or 7 digits before editing or deleting such events.
56
piconfig Reference
Use 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.
Note: Changing existing attribute sets - except for changing default values, should be
done with great care, in standalone mode.
Note: 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 listing the attribute sets on the PI 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>
Now listing the entire classic then base attribute sets; note use of the ellipsis to repeat the
output:
* (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...
Users familiar with classic PI Points will recognize all these attributes. These two attribute
sets, Classic and Base, make up the classic point class.
58
piconfig Reference
terminated. See the PI Server Applications 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.
The following attributes are defined:
Attribute 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.
Note: The PI Batch Subsystem refers to the older PI Server Batch support. The PI
Module and PI Batch Database approach is replacing the PI Batch Subsystem.
Refer the PI SDK Help files for details about the Module and Batch Databases.
Attribute 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.
60
piconfig Reference
Collective Tables store configuration information about the Collective, as well as status
information for each member of the Collective.
The PI Collective Table has information about the name of the Collective, the CollectiveID,
the description of the Collective, and the status of the Collective. Since a server can belong to
only one Collective at a time, only one entry is normally found in this table.
If the status of the Collective is good, this indicates that the status of every member of the
Collective is good. If the status is bad, this generally indicates that at least one member of
the Collective has a bad CommStatus or SyncStatus.
The collective name is used to link the entries in the PIServer table to the PICollective table.
Every PI Server presents the Collective ID as the Server ID to each application using the PI
SDK to connect to a server in the collective. This allows all displays and applications that
depend on the Sever ID to connect to any PI Server in the collective without change. For
information on how to configure the PIServer and PI Collective tables, see High Availability
and PI Server Replication.
Attribute Description
Name The name of the collective that the server belongs to; must
match collective name defined in the PIServer table
CollectiveID A UID representing the unique PI Collective identification
Description Optional description for the collective
LastCollectiveConfigChangeTime Last time stamp for change in collective configuration
Status The status of the collective (0 is good)
NewName Used to rename an existing collective
Attribute Description
DBName Database name
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
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
62
piconfig Reference
Attribute Description
SET name of digital state set
SETNO digital state set number (read only)
STATE… digital state strings in the 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).
Once created, a digital state set cannot be deleted.
Note: The endsection command is not needed when creating the state set because
data lines are processed as they are entered.
64
piconfig Reference
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. Next, 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
(Ls - PIDS) piconfig> @endsection
VALVESTATESET,Open,Closed,Stuck
(Ls - PIDS) piconfig>
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 input file. As mentioned above, the state must be added or
edited as a whole. See Modify the System State Set (page 65).
66
piconfig Reference
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.
68
piconfig Reference
used to describe access level to PI Server secure objects, such as PI points and PI modules.
The PI Identity Table was added in PI Server 3.4.380.
When you upgrade from a version prior to 3.4.380, data from the PI User and PI Group
databases is 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 Configuring PI Server Security.
Attribute 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 Server 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
NumConnections2 The number of SDK and API connections to the Network Manager
70
piconfig Reference
1
A timeout parameter DoRDNSForMessaging needs to be set to 1 in order for piconfig to
view this attribute. Note that you need to stop and restart PI server for the change of
DoRDNSForMessaging to be effective.
2
pconfig does not have access to this attribute; this means you can view it only with the
Network Manager Statistics tool in SMT.
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. The following piconfig session demonstrates this feature:
* (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
72
piconfig Reference
Note: Use great care when editing existing Point Classes, and edit them in standalone
mode.
The following piconfig session lists 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
Now listing 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
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
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 - PIPTCLS) PIconfig>
74
piconfig Reference
@select tag=MyTag*
@endsection
76
piconfig Reference
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
Attribute Description
Desc… Free format descriptor
The following piconfig session lists the point sources on the server:
* (Ls - PIPTSRC) PIconfig> @ostru ptsrc,code,count,desc
* (Ls - PIPTSRC) PIconfig> @ends
*PIconfig Err> Wild-card specs. missing, default to '*'.
#,15,26,
*,13,1,
1,7,5589,
9,2,11,
?,14,1,
@,10,4,
C,4,22,
G,9,18,
L,3,15,
Lab,5,4056,
PIBatch-InternalUse-1,11,2,
PICampaign-InternalUse-1,19,1,
PITest,16,1,
PIUnitBatch-InternalUse-1,8,109,
R,1,9865,
T,6,15,Totalizer Points
U,12,2,
78
piconfig Reference
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 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.”
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 is included with every system. It 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
CDF144,Digital State,No Data,20-Nov-02 17:11:42
CDM158,Manual,GOOD,20-Nov-02 17:09:30
CDT158,53.03498,GOOD,20-Nov-02 17:10:00
A second table named PISNAP2 is useful for debugging classic PI API applications. It uses
the PI 2.x concepts rval and istat instead of Value and Status:
Attribute 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.
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.
Note: This table has no real primary key since there is only one record.
80
piconfig Reference
The set of attributes available on this table varies with the platform type. The table attributes
are listed in the following table.
Attribute 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
Attribute Description
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.
82
piconfig Reference
Attribute Description
Name The computer hostname (non-qualified); unique key in the PI Server
table; each server uses this to find its own entry in the table
Collective The name of the collective that the server belongs to; must match
collective name defined in the PICollective table
CommPeriod Period for secondary PI Server to send status to primary, receive status
of collective members, and retrieve configuration changes
CommStatus Status of the last secondary PI Server communication with the primary
server (0 is good)
Description Optional description for the server
FQDN FQDN or IP address used to connect to collective servers
IsAvailable 1 if available for client access, 0 otherwise; derived from all other status
fields in the table
IsConnectedToPrimary 1 indicates that the secondary PI Server is connected to the primary PI
Server; always 1 on a primary PI Server
IsCurrentServer 1 on the responding PI Server, 0 for all others
IsTCPListenerOpen 1 indicates this PI Server TCP listener is open
LastCommTime Last time the secondary PI Server communicated status to the primary
PI Server
LastSyncRecordID Number of changes each PI Server applied to the replicated tables
LastSyncTime Last time synchronization succeeded on secondary PI Servers
NumConnections Total number of connections on the specific PI Server
PIVersion Version of PI Base Subsystem
Port The TCP/IP port number for communicating to the PI Server
Role 0 for non-replicated; 1 for primary; 2 for secondary
ServerID A UID representing the unique PI Server identification
SyncFailReason Reason that synchronization did not succeed
SyncPeriod Synchronization period in seconds; 0 means synchronize on demand
only; set on primary PI Server to affect behavior of secondary PI Server
SyncStatus On secondary servers; the status the last time synchronization was
attempted (0 is good)
Unavailable Reason
NewName Used to rename an existing server
Attribute Description
ID Operating system thread ID
Action Edit only. See the following table
ActValue Edit only. Value for the action performed
Attribute Description
Calls Number of calls served by the thread
Handle Subsystem handle
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
State The thread state - generally “Wait” or “InUse”
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.
84
piconfig Reference
The PI Server 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.
Note: Tuning Parameter values are preserved during PI Server upgrades. When you
upgrade the PI Server, review any values that you changed from the default.
This table contains the PI Server timing parameters as well as many other configurable
parameters. Adjustment of these parameters should be done by the PI Server Administrator.
Select this table using the command:
@table pitimeout
The primary key is NAME. The attributes are listed in the following table.
Attribute Description
Name Timing attribute name
Value Timing value as a string
NEWName Used to rename an existing name
Note: Although you can create trusts to support single sign-on, OSIsoft recommends
that you instead use PI Identities and PI Identity mappings for this purpose.
The client and PI Server 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 username.
Select this table using the command:
@table PITRUST
The primary key is TRUST. The table attributes are:
Attribute 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)
Attribute Description
IPHost Name of client machine
OSUser User name under which the client is running
AppName Application name
PIUser Associated PI user
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 or as a dollar sign ($). The dollar sign must be paired with a $ in either OSUser
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.
Note: With PI Server 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 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 Configuring PI Server Security.
This table defines PI users and records their assignment to groups. The table name is
PIUSER. The primary key is User. The table attributes are:
Attribute 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.
Note: Users are assigned to groups using the PIUSER table. Attempting to change the
group membership of users via the PIGROUP table has no effect.
86
piconfig Reference
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 Timeout, Firewall, and Trust tables may be
changed for both of these parameters by using the case command.
piconfig attempts to parse incoming data into fields using the delimited 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 (\)
Note: 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.
88
piconfig Reference
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:
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 the 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 ?
90
piconfig Reference
Caution: You should never use open files with tools that perform operations on files,
such as compact and repair options. In general, you should only use such tools
when the system is down. If you are unsure about how to use these tools, consult
OSIsoft Technical Support before using them. You should make a backup copy of
the data file before you attempt any operations.
To invoke pidiag:
pidiag -xxx
where xxx identifies an option. Depending on the specific tool, additional parameters may be
included to invoke various options. These optional parameters are summarized here and in
the piadiag utility help.
Note: Italics means the actual value must be supplied. Square brackets ([]) mean
optional. Items separated by vertical bar (|) are mutually exclusive of each other,
only one of the items can be used.
Option Description
Option Description
-did Dump Server ID file; only works when the server is not
running. When the server is running use PI Collective
Manager or piconfig with the pisysdump.dif.
-dow Echo the day of the week (0-6). 0=Sunday, 1=Monday,
and so on.
-e code Translate error code
-ecert [path] Export the server certificate to a file.
-fb path [-header] [-dv] Display file base file header, index, or version. -dv lists
only the disk version of the file without any upgrades.
-header suppresses the listing of the index and shows
only the header. The input file is opened read only.
-fbc path [-header] Compact a file base file. -header suppresses the listing of
the index and shows only the header.
-fbf inpath outpath [alignment] Recover (fix) file base data file index by copying
[-compress] [-header] recoverable records to an output file. -fbf requires an
output file and the input file is opened read only.
-gap path [-time=secs] Estimate gaps in data for an archive. By default it
[-sample=percent] samples the most active 10 percent of tags where the gap
is at least 300 seconds long and is uniform across 90
[-matching=percent] percent of the sampled tags.
-rgs [-?] [-u] path Register or unregister COM component by running .rgs
[ReplaceableParameter= script in path
"<Value>"]
-t time [U] Convert timestamp to string.
94
pidiag Reference
Option Description
-tz [ -if path | -ifrule [path] ] Specify special DST settings
[-of path]
-tz [time [TZ]] [ -check | -dump Show time zone information
[-brief] |-full]
-udf path Reset the piadmin (userid #1) password to blank
-qd [HeaderOnly Header| Dump header or all/filtered events from Event Queue file
RecNo=n | PointId=ID] path
-qs path Get offline queue file statistics
-ulcks Reset the piadmin (userid #1) password to blank
Use the pidiag utility to interpret any error codes that are 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.
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.
Most of the PI System internal databases are stored in files that have a common internal
structure. Data is stored in records and the records are indexed. We call this structure file
based. This section discusses the tools for diagnostics and repair of such database files.
96
pidiag Reference
The header and index of the compressed file is displayed after the compression. The -header
option can be used to suppress the listing of the index.
Archive Management
When the Archive Subsystem is running, use piartool -al to get this information.
Caution: Use this command only when the PI Server is shut down.
The optional path argument is the full path of the primary archive file that you want to use.
When it is not s not provided, you will be prompted for it. Upon restarting PI, the file is the
only archive registered.
If the archive manager file is corrupted, first try pidiag-ara. If that does not help, use
pidiag-ar. For more details on using pidiag -ar and pidiag -ara, see Repairing the Archive
Registry (page 102).
98
pidiag Reference
Note: This command can only be used if the archive file is not registered, or if the PI
Server is down. If you use it with a registered Archive file, pidiag returns an
access error.
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 (RecNos 4 and 11, respectively) clearly have an excessive
number of index records. See Maximize PI Server Performance (page 100).
100
pidiag Reference
Note: pidiag -adg accepts wildcard characters in the path argument (for example,
D:\PI\dat\piarch.*). This allows performing easy downgrade of many
archive files in a single command.
Archive file versions are displayed in the archive header information. For details, see
Information about Unregistered Archives (page 98). The archive file versions of the most
recently released PI Servers are:
PI Server Version Archive Version
3.3 5
3.4.363 and 6
3.4.364
3.4.370 and 7
3.4.375
3.4.380 8
102
pidiag Reference
Dump of page #5
PImapfilepage[$Workfile: pimmq.cxx $ $Revision: 36 $]::
pagesize: 1048576, eventcount: 43104, version: 1
full: 1, readoffset: 178414, writeoffset: 178405
datasize: 1048548, wrapoffset: 1048542
...
When a record number or a point ID is specified, the events of the record or the point are also
displayed:
D:\PI\adm>pidiag -qd RecNo=1 d:\pi\dat\pimapevq.dat
PImapfilequeue[$Workfile: pimmq.cxx $ $Revision: 36 $]::
filepath: d:\pi\dat\pimapevq.dat
headersize: 65536, pagesize: 1048576, state: 0x62
Dump of page #5
PImapfilepage[$Workfile: pimmq.cxx $ $Revision: 36 $]::
pagesize: 1048576, eventcount: 43104, version: 1
full: 1, readoffset: 178414, writeoffset: 178405
datasize: 1048548, wrapoffset: 1048542
---------------------------------------------
pointid,recno,mode,timestamp,type,bits: value
1,1,append,25-Sep-2009 16:56:06,12,S,O,A,S,Q [0,0,0,0,0]: 76.4593,
76.4593
1,1,append,25-Sep-2009 19:31:15,12,S,O,A,S,Q [0,0,0,0,0]: 14.2614,
14.2614
...
104
pidiag Reference
PI Server ID Utilities
Prior to PI server version 3.4.375 (the PR1 release), the server ID is stored in the file
PI\dat\PISysID.dat and can be viewed via the pdiag -cid command.
In version 3.4.375 and later, the file no longer exists. The Server ID is stored in the PIServer
table and must be viewd with the Collective Manager or piconfig when the PI Server is
running. When the server is not running, it can be viewed by pidiag -did. For details, see the
High Availability and PI Server Replication Guide.
If you are to downgrade the PI Server to a version earlier than 3.4.375, use the pidiag -rcsid
command to recreate the PISysID.dat file.
Notes: These object names are case sensitive. pidiag returns a system error 2
when mistyped.
These objects are all defined in the global namespace of Windows. As a result,
their names must always be prefixed by the string Global\ (case-sensitive).
Example:
C:\PI\adm>pidiag -gmmf Global\pibasess_Counters
Performance counters for MMF Global\pibasess_Counters
Point Count: 200558
Connector Point Count: 0
Point Create or Edit/sec: 0
Digital State Translations/sec: 165
Wild Card Searches/sec: 200
Point Accesses/sec: 200710
Module Count: 20
Heading Set Count: 0
Heading Count: 0
Module Database Record Count: 24
Module Create or Edit/sec: 0
Heading Set Create or Edit/sec: 0
Heading Create or Edit/sec: 0
Module Database Create or Edit/sec: 0
Module Accesses/sec: 94
Heading Set Accesses/sec: 0
Heading Accesses/sec: 0
Module Database Accesses/sec: 94
106
pidiag Reference
checks performance counters and reports problems found. When the option -fix is specified, it
attempts to fix the problems. If there are problems it cannot fix, it makes suggestions on how
to repair the issues manually.
Licensing Utilities
PI Server 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 operationg system
information. We call such information the signature of a machine or a cluster. Several pidiag
commands are provided for gathering and checking machine and cluster signatures.
Comparing Signatures
pidiag -host -compare filename [, filename]
This command compares signatures. When only one signature file is provided, it compares
the information stored in the file with the configuration of the local machine or cluster. When
a second signature file is provided, this command compares the two signature files.
Matching signatures example:
D:\PI\adm>pidiag -host -compare D:\vmtest-xp2.msf
Miscellaneous
108
pidiag Reference
Note: The PI Base Subsystem must be shut down for this command to succeed. Also
note the path argument requires a trailing \ character.
Name: Test755.osisoft.int
Address: 192.168.5.182
Family: PF_INET
Name: Test755.osisoft.int
Address: 192.168.5.182
Family: PF_INET
Name: Test755.osisoft.int
Address: 192.168.5.182
Family: PF_INET
Name: 192.168.5.182
Address: 192.168.5.182
Family: PF_INET
Name: 192.168.5.182
Address: 192.168.5.182
Family: PF_INET
Name: 192.168.5.182
Address: 192.168.5.182
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.
110
pidiag Reference
On 32-bit Windows, this command displays the PIPC home directory. On 64-bit Windows, it
displays the PIPC home directories for both 32-bit applications and 64-bit applications.
Example 1, on 32-bit Windows:
C:\Program Files\PIPC\adm>pidiag -getpipcpath
PIPC home directory: C:\Program Files\PIPC\
Example 2, on 64-bit Windows:
C:\Program Files\PIPC\adm>pidiag -getpipcpath
32-bit PIPC home directory: C:\Program Files (x86)\PIPC
64-bit PIPC home directory: C:\Program Files\PIPC\
Generate GUID
pidiag -uuid [count]
This generates GUIDs. Count is the number of GUIDs to generate. If it is not specified, one
GUID is generated.
pidiag -uuid
88E75570-14AA-4512-879D-A20B85771402
112
pidiag Reference
pigetmsg Reference
The pigetmsg utility is located in 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. The
necessary parameters to run in non-interactive mode are a minimum of two of the following:
• start time (–st)
• end time (–et)
• maxcount (–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 –f option, pigetmsg goes into continuous mode after the results are
returned. See Use pigetmsg in Continuous Mode (page 116) for more information.
Use this command to open Help files for the pigetmsg utility:
pigetmsg /?
114
pigetmsg Reference
Option Description
Mode
-f Update continuously (refreshing every 2 seconds)
-i Interactive mode (the default, can be combined with -f to prompt users through each page of
messages)
Filter Options
-st Start time. This should be entered in PI time format.
-et End time. This should be entered in PI time format.
-t Tail. Output the last messages within the time range (default is 1) If no end time is specified,
search starts from current time
-id This is an integer that represents the specific message identification number: 0 for the
free-format messages. The default is all messages.
-msg A string mask selection for the message text. The default is * (show everything).
-mc total number of messages to return
-pr This is the specific program name (pinetmgr)
-src Source of the message (matching the process name, Source 1, 2 or 3)
-src1 -src1 Source 1
-src2 -src2 Source 2
-src3 -src3 Source 3
-pid Process ID, This is the process ID of the program.
-phost Process hostname. This is the hostname where the program is running. Blank means this
came from localhost.
-posuser The Name of the user account (Principal) the process was running under.
-ppiuser The PI Identity(s) of the user account the process was running under.
-ohost Hostname of the user this process was acting on behalf of.
-oosuser The Name of the user (Principal) this process was acting on behalf of.
-opiuser The PI Identity(s) of the user this process was acting on behalf of.
-si minimum severity level-- choose the appropriate option for the minimum severity level you
-sw want to see
-se -si = information
-sc -sw = warning
-se = error
-sc = critical
-cat Category. Messages may optionally belong to a particular category.
-pri Priority. Messages may optionally be marked with a particular priority (1-10).
Prompting options
-qb basic prompts only (start time/end time)
-qa prompt for all message fields
Formatting options
-fw Wide format output (one message per line)
-fx XML format output
Connection Options
-Node <nodename>
-Windows
-Trust
-Explicit
Note: The -dc option is not available in PI Server versions 3.4.380 and later. Interactive
mode (-i) will show one page of messages at a time.
Continuous mode (-f) continually flushes the message log and gets the last messages every 2
seconds. If StartTime is specified, pigetmsg initially displays messages beginning at the start
time up to current time. If the Tail option (-t) is specified, then pigetmsg initially displays the
last (n) messages. If EndTime is specified (should be a timestamp relative to current time, i.e.
*-5s), introduces a delay between the time a message is generated and the time pigetmsg
displays it. This can ensure messages that arrive late or out of order are not missed. The
program may be stopped with a Ctrl-C.
Specify the -i option, and pigetmsg prompts after displaying each page of messages.
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
116
pigetmsg Reference
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, click Enter after a prompt.
For example, to begin an interactive session as the user, piadmin, with the password,
buddy on a remote NT host named Samson, use:
pigetmsg –remote –node Samson –username piadmin –port 5450 –password
buddy
To use pigetmsg to list all messages received today from a specific subsystem such as the PI
Base Subsystem:
pigetmsg –st t –et "*" –pn pibasess
To list the last 100 messages that have the word error as part of the message and then
display these messages 10 at a time:
pigetmsg –st t –et "*" –mc 100 –msg "*error*" –dc 10
To send pigetmsg results to a file, use the standard output redirection operator (>):
pigetmsg –st "*–1h" –et "*" > myfile.txt
Run the pigetmsg utility to test pimsgss. If pimsgss is not working correctly, you will
see:
D:\PI\adm>pigetmsg
Message ID [A], (0-n) (A)ll (T)ail (F)lush (Q)uit (?):
Message Source [*], (?):
Start time in PI format [*-15m], s(K)ip (?):
End time in PI format [*], s(K)ip (?):
Maximum count [], (0-n) (?):
Text mask [*], (?):
Display count [], (0-n) (?):
[-10733] PINET: RPC Resolver is Off-Line.
pilistupd Reference
The pilistupd utility shows the size of the queues of events maintained by the Update
Manager. The utility requires that PI Server be running.
118
pilistupd Reference
• Qual: This is the qualifier. The qualifier is a producer-specific integer. For example,
Snapshots update stores the requested point ID in the qualifier.
• Flags: A producer-specific field.
• 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 number shows a maximum of 50000 events, even if more events are
in the queue. You can configure this limit with the MAXUPDATEQUEUE Tuning
Parameter. The Update Manager might limit individual consumers from
accumulating too many pending events. This is a display limitation and does not
imply data loss.
The following table lists the possible producers and what subsystem they belong to.
Producer Description Subsystem
120
pilistupd Reference
The next table was generated by running pilistupd with an open PI ProcessBook version 3.x
display, trending two points.
c:\pi\adm>pilistupd
Running pilistupd several times should reveal changes in the pending numbers. This can be
done easily by using command-line switches. The -m option, requests a minimum pending
value of 1. The -r requests that the command be run 100 times. In the example below, the
command is issued and then results appear for four runs before the command is stopped with
Ctrl+C. For three of the runs, none of the producers have 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
snapshots piadE|15|5 12 0 1
snapshots piadE|15|5 18 0 1
snapshots piadE|15|5 19 0 1
snapshots piadE|15|5 20 0 1
No Matching entries
^C
In a normal system, you would anticipate that the pending number would reach 1
occasionally as the pilistupd command was run before the consumer retrieved the update. If
the pending number never increases above 0, it may be that data is not arriving from the
source. If the pending number increases continually and does not shrink, the consumer is
probably not retrieving the updates.
pipetest
The pipetest utility checks the syntax of a Performance Equation. It can operate interactively,
take its input from a file or check the extended descriptor of a point. The pipetest utility is
located in the pi\adm directory. 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 4095 characters or less and you can not
use it 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 enter:
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's 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.
pisetpass
The pisetpass command is useful when the piadmin password is lost. Following this
operation, the piadmin password can be set to any given string using the pisetpass utility. For
example:
e:\PI\adm>pidiag -udf e:\pi\dat\
The administrative password has been successfully reset.
The administrative account is piadmin.
122
piversion
Note: The PI Base Subsystem must be shut down for this command to succeed. Also
note the path argument requires a trailing \ character.
piversion
To get the PI Server version and build numbers, enter the following from the PI\adm
directory:
piversion -v
If you have applied a patch to your PI Server, 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
Miscellaneous
126
piarcmem.dat
piarcmem.dat
This binary file is used by the PI Snapshot Subsystem. It contains the most recent values that
have been sent to the PI Server. The PI Snapshot Subsystem periodically writes the latest
Snapshot values to this file. Use pidiag -fb and pidiag -fbf to verify the validity of this
PIFileBase-type database.
piarstat.dat
This binary file keeps track of registered archives. It is required by piarchss. If you are
having trouble with archive file registration, do not delete this file. Instead, see Repairing the
Archive Registry (page 102).
pidignam.dat
This binary file stores each unique digital state name. Use pidiag -fb and pidiag -fbf to
validate and restore this PIFileBase-type database.
pidigst.dat
This binary file stores the digital sets; it references names stored in the above file. Use
pidiag -fb and pidiag -fbf to validate and restore this PIFileBase-type database.
pilastsnap.dat
This binary file stores the timestamp of the last completed Snapshot flush to disk. On PI
System 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.
pimsgtxt.dat
This binary file stores formatted message strings used by the pigetmsg utility. Use pidiag -fb
and pidiag -fbf to check and restore the validity of this PIFileBase-type database.
pipoints.dat
This binary file stores the Point database. Use pidiag -fb and pidiag -fbf to check and restore
the validity of this PIFileBase-type database.
piptalia.dat
This binary file contains alias information. Use pidiag -fb and pidiag -fbf to check and
restore the validity of this PIFileBase-type database.
piptattr.dat
This binary file stores the point attributes. Use pidiag -fb and pidiag -fbf to check and restore
the validity of this PIFileBase-type database.
piptclss.dat
This binary file stores the point classes. Use pidiag -fb and pidiag -fbf to check and restore
the validity of this PIFileBase-type database.
128
piptunit.dat
piptunit.dat
This binary file stores the PI Point units. Use pidiag -fb and pidiag -fbf to check and restore
the validity of this PIFileBase-type database.
piusr.dat
This file stores the PIUser database. Use pidiag -fb and pidiag -fbf to check and restore the
validity of this PIFileBase-type database.
piusrctx.dat
This file stores the context database. Use pidiag -fb and pidiag -fbf to check and restore the
validity of this PIFileBase-type database.
piusrgrp.dat
This file stores the group database. Use pidiag -fb and pidiag -fbf to check and restore the
validity of this PIFileBase-type database.
shutdown.dat
This text file contains directives that tell the PI Shutdown Interface which points should
receive shutdown events.
PI Performance Counters
PI Server has a number of performance counter statistics that can be viewed using Microsoft's
performance Monitor utility (System Monitor in Windows 2000).
The following tables list the statistics that may be viewed.
Attribute Description
Connector Read Rate of calls to read events for mapped points through COM
Operations/sec Connectors. This rate is NOT included in the Read Operations/sec
counter.
Connector Events Rate of events read for mapped points through COM Connectors.
Read/sec This rate is NOT included in the Events Read/sec counter.
Connector Summaries/sec Rate of summaries for mapped points through COM Connectors. This
rate is NOT included in the Events Read/sec counter.
Connector Events Read Time elapsed in milliseconds for one Events Read for a COM
Exec Time Connector point.
Connector Event Read Time elapsed in milliseconds for one Event Read for a COM
Exec Time Connector point.
Connector Summaries Time elapsed in milliseconds for one summaries call for a COM
Exec Time Connector point.
Point Flushes Last Cycle Number of points flushed to disk during last cycle. Busy points might
get flushed several times per cycle.
Unflushed Points Number of points that have at least one unflushed event.
Archive Cycles/Sec Number of Subsystem cycles per second.
Total Unflushed Events Total number of unflushed events.
Configured Cache Record Maximum number of cache records in the read-only pool.
Pool
Current Cache Record Current maximum number of cache records, this may be lower that
Pool the configured value due to low memory resources.
Config. Max Unflushed Maximum number of unflushed events per point.
Events/pt
Current Max Unflushed Current maximum number of unflushed events per point, this may be
Events/pt lower that the configured value due to low memory resources.
Primary Archive % Used Percent of used records in Primary Archive File.
Event Queue Chunk Size Number of events read per Event Queue read operation.
Flush Queue Size Number of pending flush operations in memory queue.
Write Contentions/sec Rate of write lock contentions (EVQ threads).
Write Contention Points Number of points in write contention last cycle.
GetSnapshot Calls/sec Rate of internal calls to the Snapshot Subsystem.
ArcEvent Calls/sec Rate of single archive event calls.
CompEvents Calls/sec Rate of compressed events calls.
InterpEvents Calls/sec Rate of interpolated events calls.
PlotEvents Calls/sec Rate of plotted (trended) event calls
Summary Calls/sec Rate of summary/filter expression calls.
PICampaigns Created/sec Rate of PI Campaign creation.
PIBatches Created/sec Rate of PI Batch creation.
PIUnitBatches Created/sec Rate of PI Unit Batch creation.
PITransferRecords Rate of PI Transfer Record creation.
Created/sec
132
PI Base Subsystem Statistics
Attribute Description
PICampaigns Edited/sec Rate of PI Campaign edits
PIBatches Edited/sec Rate of PI Batch edits
PIUnitBatches Edited/sec Rate of PI Unit Batch edits
PITransferRecords Rate of PI Transfer Record edits.
Edited/sec
PICampaigns Read /sec Rate of PI Campaign access.
PIBatches Read /sec Rate of PI Batch access.
PIUnitBatches Read /sec Rate of PI Unit Batch access.
PITransferRecords Rate of PI Transfer Record access.
Read/sec
PICampaigns Deleted /sec Rate of PI Campaign deletion.
PIBatches Deleted /sec Rate of PI Batch deletion.
PIUnitBatches Deleted /sec Rate of PI Unit Batch deletion.
PITransferRecords Deleted Rate of PI Transfer Record deletion.
/sec
Attribute Description
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 Number of megabytes copied in last backup. This counter is not
Copied incremented for a non-component mode backup.
Last Backup PrepareBackup Number of seconds between PrepareBackup and Freeze events.
To Freeze Duration 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 Total files identified for last backup. Should be equal to copied +
Count 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.
134
PI Buffer Subsystem Statistics
Attribute Description
Module Accesses/sec Rate at which module information is accessed, not including module
edits.
Heading Set Accesses/sec Rate at which heading set information is accessed, not including
module edits.
Heading Accesses/sec Rate at which heading information is accessed, not including module
edits.
Module Database Rate at which module database information is accessed, not
Accesses/sec including module edits.
PI Collective Statistics
Attribute Description
Is Running Normally Is the status normal for all members of the collective?
Last Config Change Last time the configuration of the collective was modified
Time
Current Server The index of the current server of the collective
Number of Servers The number of member servers in the collective
136
PI Performance Equations Statistics
Attribute Description
Bytes Received/sec The number of bytes received by the PI Network Manager.
Overflow/sec The number of times an overflow message is required by the PI Network
Manager.
Receive Errors The number of times an error occurs during a receive of a message to the
PI Network Manager.
Send Errors The number of times an error occurs during a send of a message to the PI
Network Manager.
PI API Connections The number of PI API applications connected.
PI SDK Connections The number of PI SDK applications connected.
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
Queued Connections The number of connections currently being processed
Queued Connection The number of connections currently being processed for deletion
Deletions
PINet3 Asynch Call Delay in milliseconds between when a PINet call was scheduled and
Delay when it was executed
API Asynch Call Delay Delay in milliseconds between when an API call was scheduled and when
it was executed
Scheduled Task Delay Delay in milliseconds between when the currently running task was
scheduled and when it was executed
PI Performance Counters
138
PI Server LocalHost Statistics
PI Server Statistics
Attribute Description
Is Communicting Is the server communicating to the other members of the collective?
Is In Sync Is the server in sync with the other members of the collective?
Is Available Is the server available?
Is Current Server Is the server the member of the collective sending this information?
Last Sync Record ID Last sync record processed
Role The role this server plays in a collective
Sync Records/sec Sync records processed/sec
Communication The frequency the server is configured to communicate with the collective
Period
Sync Period The frequency this server is configured to sync with the collective
Last Communication Last time the server communicated with the collective
Time
Last Sync Time Last time the server synchronized with the collective
Server Index The index of the server in the list of members of the collective
PI Session Statistics
Attribute Description
Messages Sent/sec The number of messages sent by the PI session.
Messages Received/sec The number of messages received by the PI session.
Bytes Sent/sec The number of bytes sent by the PI session.
Bytes Received/sec The number of bytes received 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.
140
PI Snapshot Subsystem Statistics
Number of Overflow Number of overflow queue files (0 if only the primary queue is active).
Queues
Events in Overflow Queues Total of events in the overflow queue files.
Estimated Remaining Estimated maximum number of events with current queue file.
Capacity
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.
Event Queue Page Rate of data page shifts in primary queue file.
Shifts/sec
Primary Event Queue Id Identification number of primary queue (0 to 65,535).
Attribute Description
ArcValueCompCalls/sec Rate of RPC calls made to the PI Archive Subsystem for compressed
events.
ArcValueCompEvents/sec Rate at which compressed data events are returned by the PI Archive
Subsystem.
WildcardSearches/sec Rate at which new wildcard searches are initiated in the PI Point
Database.
WildcardPoints/sec Rate at which points are returned when performing wildcard searches
of the PI Point Database.
ArcValueCalls/sec Rate of RPC calls made to the PI Archive Subsystem to obtain a
single archived value.
SnapshotCalls/sec Rate of RPC calls made to the PI Snapshot Subsystem to obtain a
single snapshot value.
WHERE Clause Rate of full evaluations of the WHERE clause of a SELECT
Evaluations/sec statement.
ArcValueTimedCalls/sec Rate of RPC calls made to the PI Archive Subsystem for interpolated
or timed events.
ArcValueTimedEvents/sec Rate at which interpolated or timed data events are returned by the PI
Archive Subsystem.
SummaryArcValueCalls/se Rate of RPC calls made to the PI Archive Subsystem for summarized
c values (such as average, total, and standard deviation).
Dot Variable Rate of "dot" variable evaluations made within the PI SQL Library. A
Evaluations/sec 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.
Next Point With Source Rate at which points are returned by the PI Base Subsystem in
Calls/sec searches for points with a specific PointSource attribute.
PostCalls/sec Rate of RPC calls made to the PI Snapshot Subsystem to post
events from execution of SQL INSERT or UPDATE statements.
PostEvents/sec Rate at which data events are posted to the PI Snapshot Subsystem
from execution of SQL INSERT or UPDATE statements.
Handles Number of PI SQL handles currently allocated in the PI SQL
Subsystem. This is an indication of how many clients are actively
processing SQL statements.
PI Subsystem Statistics
Attribute Description
Message Queue Length Number of incoming messages in queue.
Pending Transactions Number of pending transactions.
Actual Pending Only for internal debugging purpose. You should use it only under the
Transactions suggestion of OSIsoft Technical Support.
Message Pickup Time Latency of incoming messages (time in message queue).
Message Execution Execution time of incoming message (RPC).
Time
142
PI Subsystem Statistics
Attribute Description
Message Complete Time Total message handling time (including results sending).
Callback Execution Time Execution time of transaction callback.
Transaction Number of transactions completed per second.
Completed/sec
Transaction Number of transactions cancelled per second.
Cancelled/sec
Transaction Avg Time Average execution time of outgoing transactions.
Transaction Max Time Maximum execution time of outgoing transactions.
Lock Acquisitions/sec Number of successful lock acquisitions per second
Lock Timeouts/sec Number of lock timeouts (failed locks) per second.
Lock Contentions/sec Number of lock conflicts (threads waiting for the same lock).
RPC Threads Total Total number of RPC worker threads (query processing).
RPC Threads Active Number of RPC worker threads processing a query.
File Open Number of time File base Open called.
File Close Number of time File base Close called.
File Read/Sec Rate of File base Read.
File Write/Sec Rate of File base Write.
File Delete/Sec Rate of File base Delete.
File Create Number of time File base Create called.
File Compress Number of time File base Compress operations.
File Grow Number of time File Directory grow operations.
Backups Started Number of backup start operations
Backups Completed Number of backup complete operations
Backups Aborted Number of backup abort operations
Backup Freeze Last Number of milliseconds subsystem was frozen for the last backup
Duration
Backup Freeze Last Number of milliseconds required to put the subsystem into a frozen
Transition state for the last backup
Backup Freeze Last Number of freeze operations for the last backup. Multiple freeze
Count operations may be required for non-VSS backups
Backup Freeze Failures Number of failed freeze operations
Backup Freeze In If the subsystem is frozen, this counter is set to 1. Otherwise, it is set to
Progress 0.
Backup Freeze Max Maximum milliseconds that subsystem has been frozen for a backup
Duration
Backup Freeze Avg Average milliseconds that subsystem is frozen for backups
Duration
144
PI Update Producer Statistics
148
Normal Startup Messages
150
Normal Startup Messages
152
Normal Startup Messages
154
Normal Startup Messages
156
Client Connection Messages
158
Disconnect Messages
The subsystem begins its own initialization. On Windows, part of this process involves
updating the subsystem's own working set size limits:
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 PI subsystems. 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 System message log that track communications
between PI clients and the PI Server.
The following message from pinetmgr indicates that a client is attempting to connect to PI
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: ,
192.168.5.137: 1269
A PI SDK-based client will first publish it's 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 server will then attempt to authenticate the client. That is, the client will pass in
certain credentials and the PI server will accept or reject these credentials. In this example the
client successfully connects via Windows authentication:
160
RPC Resolver Messages
-13 PI_ATT_BADDSCODERANGE Digital State Code Out of Range For This Tag
-19 PI_ATT_PTATTZERO Point Attribute Zero Error or Disk Error for Point
Database
-20 PI_ATT_BADZEROSPAN Bad Zero or Span For Integer Point
-22 PI_ATT_BADTYPVALUE Typical Value Not Between Zero and Top of Range
164
Error Codes 1-99, With Messages
-60 PI_ATT_NOPIDAVAIL No more pid slots for retrieving point update lists
166
Error Codes 300-399, With Messages
168
Error Codes 900-999, With Messages
170
Error Codes 10000-10999, With Messages
172
Error Codes 10000-10999, With Messages
174
Error Codes 10000-10999, With Messages
176
Error Codes 10000-10999, With Messages
178
Error Codes 11000-11999, With Messages
180
Error Codes 11000-11999, With Messages
182
Error Codes 11000-11999, With Messages
184
Error Codes 12000-12999, With Messages
186
Error Codes 12000-12999, With Messages
188
Error Codes 13000-13999, With Messages
190
Error Codes 15000-15999, With Messages
192
Error Codes 16000-16999, With Messages
194
Error Codes 16000-16999, With Messages
196
Error Codes 16000-16999, With Messages
198
Error Codes 17000-17999, With Messages
200
Error Codes 18000-18999, With Messages
202
Error Codes 30000-30999, With Messages
You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table
below to find the most appropriate number for your area. Dialing any of these numbers will
route your call into our global support queue to be answered by engineers stationed around
the world.
Office Location Access Number Local Language Options
San Leandro, CA, USA 1 510 297 5828 English
Philadelphia, PA, USA 1 215 606 0705 English
Johnson City, TN, USA 1 423 610 3800 English
Montreal, QC, Canada 1 514 493 0663 English, French
Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese
Altenstadt, Germany 49 6047 9890 English, German
Manama, Bahrain 973 1758 4429 English, Arabic
Singapore 65 6391 1811 English, Mandarin
86 021 2327 8686 Mandarin
Perth, WA, Australia 61 8 9282 9220 English
Support may be provided in languages other than English in certain centers (listed above)
based on availability of attendants. If you select a local language option, we will make best
efforts to connect you with an available Technical Support Engineer (TSE) with that language
skill. If no local language TSE is available to assist you, you will be routed to the first
available attendant.
If all available TSEs are busy assisting other customers when you call, you will be prompted
to remain on the line to wait for the next available TSE or else leave a voicemail message. If
you choose to leave a message, you will not lose your place in the queue. Your voicemail
will be treated as a regular phone call and will be directed to the first TSE who becomes
available.
If you are calling about an ongoing case, be sure to reference your case number when you call
so we can connect you to the engineer currently assigned to your case. If that engineer is not
available, another engineer will attempt to assist you.
Search Support
From the OSIsoft Technical Support Web site, click Search Support.
Quickly and easily search the OSIsoft Technical Support Web site's Support Solutions,
Documentation, and Support Bulletins using the advanced MS SharePoint search engine.
techsupport@osisoft.com
When contacting OSIsoft Technical Support by email, it is helpful to send the following
information:
• Description of issue: Short description of issue, symptoms, informational or error
messages, history of issue
• Message logs: See documentation for your PI System for information on obtaining
message logs pertinent to the situation.
From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.
Using OSIsoft's Online Technical Support, you can:
• Enter a new call directly into OSIsoft's database (monitored 24 hours a day)
• View or edit existing OSIsoft calls that you entered
• View any of the calls entered by your organization or site, if enabled
• See your licensed software and dates of your Service Reliance Program agreements
206
Remote Access
From the OSIsoft Technical Support Web site, click Contact Us > Remote Support
Options.
OSIsoft Support Engineers may remotely access your server in order to provide hands-on
troubleshooting and assistance. See the Remote Access page for details on the various
methods you can use.
On-site service
From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service
Visit.
OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more
information.
Knowledge Center
From the OSIsoft Technical Support Web site, click Knowledge Center.
The Knowledge Center provides a searchable library of documentation and technical data, as
well as a special collection of resources for system managers. For these options, click
Knowledge Center on the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support Pages,
Known Issues, Enhancements, and Documentation (including user manuals, release
notes, and white papers).
• System Manager Resources include tools and instructions that help you manage: Archive
sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server
security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.
Upgrades
From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.
You are eligible to download or order any available version of a product for which you have
an active Service Reliance Program (SRP), formerly known as Tech Support Agreement
(TSA). To verify or change your SRP status, contact your Sales Representative or Technical
Support (http://techsupport.osisoft.com/) for assistance.