piartool command-line options

Option

Name

Description

-ac -hist|-future|-arcset

Archive create

Create and register an archive of fixed size. You can specify -hist for historical records, -future for future records, or -arcset N, where 0 is historical and 1 is future.

-acd

Dynamic archive create

Create a PI archive that grows dynamically in size. The maximum size is 2 TB. To create a dynamic archive with a maximum size less than 2 TB, use piarcreate instead.

Note: Using the ‑acd option can negatively affect performance. We recommend creating a fixed-size archive using the ‑ac option instead.

-ads path

Archive disable shift

Remove the specified archive from shift participation.

-aes path

Archive enable shift

Add the specified archive to shift participation.

-afl -dump

AF link: dump

Monitor the link between a PI AF server and Data Archive, and return the state of the link between Data Archive and PI AF server. Optionally, to list all information related to the configuration and status of the link available from PI Base Subsystem in addition to PI AF Link Subsystem, include the ‑verbose parameter.

-afl -mdbstat

AF link: MDB state

Monitor the link between a PI AF server and Data Archive, and return the state of the MDB. Possible returned values are:

• 0

  OK

• 1

  Starting up

• Other values

  An error occurred

-afl -mdbwait

AF link: MDB wait

Monitor the link between a PI AF server and Data Archive, and wait for the MDB to become available for editing. By default, the wait time is five minutes. You can specify these additional parameters:

• -maxwait

  Maximum time to wait for MDB, specified in seconds.

• -verbose

  Display output from command.

• -rpctimeout

  Use the maximum wait as the RPC timeout.

-afl -trace

AF link: trace

Monitor the link between a PI AF server and Data Archive, and specify AF-link tracing behavior. Additional parameters are:

• on

  Enable AF-link tracing. By default, the utility writes output to the PI message log for five minutes. Optionally, you can specify these parameters:

• -log

  Writes the output to a log file.

• -timeout sec

  Writes the output for the specified number of seconds.

• off

  Turn off AF link tracing.

• query

  Return the state of AF-link tracing.

-al

Archive list

List all registered archives. Additional parameters and argument are:

• -future|-hist|-arcset N

  Apply the command to a specified set of archives. See Archive set parameters for piartool.

• N

  The maximum number (N) of archives to display. For example, to list only the primary archive and archive 1:

  piartool -al 2

  For a description of the piartool -al output, see Output from the piartool -al command.

-ar path

Archive register

Register a specified archive. To register archives in bulk, use the wildcard characters * and ?. To match all possibilities with any number of characters, use *. To match a single character, use ? any number of times.

Note: There is no need to specify the archive set. The PI Archive Subsystem registers the given archive to the appropriate archive set.

-as -hist|-future|-arcset

Archive statistics

Monitor PI Archive Subsystem activity and statistics. You can specify -hist for historical records, -future for future records, or -arcset N, where 0 is historical and 1 is future.

For more information about output from this option, see Output from piartool -as.

-au -hist|-future|-arcset path

Archive unregister

Unregister a specified archive.

To unregister archives in bulk, use the wildcard characters * and ?. To match all possibilities with any number of characters, use *. To match a single character, use ? any number of times.

You can specify -hist for historical records, -future for future records, or -arcset N, where 0 is historical and 1 is future.

-aw -hist|-future|-arcset N

Archive walk

List details of the records in an archive. You can specify -hist for historical records, -future for future records, or -arcset N, where 0 is historical and 1 is future.

-backup path

Perform a Data Archive server backup

Start a Data Archive server backup. The path argument specifies the target directory for the backup files. For a complete list of arguments that modify that backup, see Launch backups with the piartool utility.

-backup command

Run a backup command

Run a backup command. For a complete list of backup commands and a list of possible arguments, see Auxiliary backup commands for the piartool utility.

-bfs

Buffered source statistics

List any PI Buffer Subsystem registered with PI Snapshot Subsystem along with the buffered source's registration ID. Additional options include:

• -bfs ID -ptlist

  List the points from a buffered source, where ID is the buffered source's registration ID.

• -bfs ID -reset

  Release the ownership locks PI Buffer Subsystem has on points from a buffered source, where ID is the buffered source's registration ID.

-block subsystem

Block

Wait for specified subsystem to respond. By default, waits up to 3,600 seconds. Use in Data Archive start scripts to pause the script until the subsystem is available.

For subsystem, you can specify two subsystems, separated by a comma (that is, subsystem1, subsystem2), to confirm that those subsystems can communicate.

Additional parameters and argument:

• -maxwait

  Maximum wait for subsystem, in seconds.

• -verbose

  Display output from command.

• -rpctimeout

  Use the maximum wait time as the RPC timeout.

-cad tagmask

Archive cache diagnostics

Display the events in the read and write archive cache for every point that matches the specified tag mask. Additional parameters:

• -reset

  Flush the values in the cache for the specified points.

• -future|-hist|-arcset N

  Apply the command to a specified set of archives. See Archive set parameters for piartool.

-cas

Archive cache summary

Display a summary of the contents of the archive cache, including the number of events in the read and write caches, for every point with values in the caches. Additional parameter and argument:

• -future|-hist|-arcset N

  Apply the command to a specified set of archives. See Archive set parameters for piartool.

• tagmask

  Display summary for points that match the specified tag mask.

-de path

Dump event queue

Dump specified event queue file. Additional parameter and argument:

• -pt tagname

  Display information for specified tag.

• recno

  Display information for specific record in the file.

  Note: The -de option only works for event queues written by PI Server version 3.3 or earlier.

-flush

Flush

Flush all values in the read and write cache.

-fs

Force shift

Force an archive shift in the historical set.

-idci

ID conversion

This option is no longer supported. To create ID conversion files, use piarchss -idci.

-lic

Licensing information

List license information. Use with one of the following arguments:

• usage

  List general license and usage information.

• def

  List all licenses. Use the -select mask parameter to select only the licenses that match the specified mask. For example, to list all licenses that have names starting with "piarchss", type:

  piartool -lic def -select piarchss*

• user

  List all license users. Use the -select mask parameter to list only users that match the specified mask.

• lic

  List all licenses and users. Use the -select mask parameter to list only the licenses and users that match the specified mask.

• AllowedApps [-List type, type...|-Check app, app,...]

  List the licenses of the specified application types or check whether a specific feature is licensed. The valid application types include: PIService, PIUtility, OSIInterface, OSIMiddleWare, OSIAPIApp, OSISDKApp, ServerApp, APIApp, SDKApp.

  Note: When Data Archive is not running, the piartool utility does not work. To list license information, enter one of the following:

  pilicmgr -lic usage

  pilicmgr -lic def

-module UID

PI Modules lookup by UID

Look up the module path for a UID. This option is useful when debugging error messages in the PI message log that report the UID of a module, but the not the module path.

-msg message

Send message

Send the specified message to the message log.

-ooo

Out-of-order snap events

Show tags with out-of-order events. Additional parameters and argument:

• -future|-hist|-arcset N

  Apply the command to a specified set of archives. See Archive set parameters for piartool.

• -r

  Resets the list of tags with out-of-order events since startup.

• N

  Repeat the command every N seconds.

-qs

Queue statistics

Monitor event queue activity and statistics. Updates every five seconds. Additional parameter and arguments:

• -future|-hist|-arcset N

  Apply the command to a specified set of archives. See Archive set parameters for piartool.

• sec=n

  Update every n seconds.

• cnt=n

  Display only n updates.

-qwait

Event queue wait time

Wait for the event queue to empty. By default waits up to 300 seconds. Optional argument:

• maxwait

  Maximum time to wait, in seconds.

-registerhacert

Register HA certificate

Register or check certificates used for a Data Archive collective. You must specify one of the following parameters:

• --updatePublicCertOnPrimary or -u

  Register the certificates between the secondary and the primary server in a collective. Run this command on all members of the collective.

• --reportInfoOnTarget server-name or -r server-name

  Reports the name and signature for the public certificate of the specified machine. Use this to troubleshoot certificate-related issues on any member.

  Note: A single dash denotes the short syntax while double dashes denote the long syntax.

-remote

Remote system

Run utility against a remote system. When you include this argument as the last argument in any valid command, the utility prompts you for remote-system login information. If successful the utility runs against the remote system.

-rsso

Redundant single -on (RSSO)

When using OIDC authentication configured against an AIM server, the output displays the following RSSO-related information:

• A list of available RSSOs

• The URI of the Single Management Server (SMS)

• The Client ID registered with the AIM server

• The Redirect URI(s)

-sd tagmask

Snapshot dump

Display snapshot information for every point that matches the specified tag mask. Additional parameter:

• -bufreset

  Clear PI Buffering Subsystem ownership of points that match the specified tag mask. This will let other processes, such as clients and API Buffer Server, post new snapshot values to the point.

-ss

Snapshot statistics

Monitor PI Snapshot Subsystem activity and statistics. Updates every five seconds. Additional parameter and arguments:

• -future|-hist|-arcset N

  Apply the command to a specified set of archives. See Archive set parameters for piartool.

• sec=n

  Update every n seconds.

• cnt=n

  Display only n updates.

-sys

System commands for collective management

Manage the collective with the following parameters:

• -close

  Close the TCP/IP listeners on the server and clear any clients connected to the sever.

• -drop PIServerName

  Remove the specified server from the collective.

• -open

  Open the TCP/IP listeners on Data Archive. PI SDK clients can resume connections to the server.

• -promote PIServerName

  Promote the specified secondary server to primary server.

• -query

  Return status of TCP/IP listeners on Data Archive.

• -sync

  Force the specified server to synchronize with the collective's primary server.

• -standalone on|off|query

  Enter, exit, or check stand-alone mode, depending on parameter:

• on

  Place Data Archive in stand-alone mode.

• off

  Place Data Archive in normal mode.

• query

  Return current mode of Data Archive.

• -testcfo

  Clear SDK clients from Data Archive. Use to test SDK client failover.

-systembackup

System backup

Subsystem offline mode for audit file access.

-thread subsystem -info|-history

Subsystem thread list

When -info is used, list the specified subsystem's threads. When -history is used, list the last 100 RPCs that have run or are currently running for the specified subsystem. Use the -history parameter to track the amount of time it takes for an RPC to run.

-v

Version

Display version and build information.

-upd subsystem producer

Update producer statistics

Display update producer statistics. See Producers and associated subsystems. Additional parameter:

• -ls

  List individual sign-ups.