Viewing System Messages

During normal operation, the PI Message Subsystem maintains a central log file for messages from all PI subsystems. PI creates a new log every day, on universal time coordinate (UTC) time. PI puts the log files in the PI\log directory and names each log according to the date. The file names are of the form, pimsg_YYMMDD.dat, where:

‰ YYY is years since 1900 (for example,if the year is 2000, YY is 100)

‰ MM is the month (for example, if the month is January, MM is 01)

‰ DD is the day (for example, if it is the fifth of the month, DD is 05) For example, the log file for January 5, 2000 is named pimsg_1000105.dat.

PI Message log files are binary files that you can view using the pigetmsg utility.The pigetmsg utility lets you view messages according to time, subsystem, or sender’s identity. The pigetmsg utility requires PI to be running.

2.2.1 Available Log History

The number of files left on the system determines the amount of log history available. PI creates a new log file every day. PI keeps log files for 35 days, at which point it automatically purges them from the system. If you want to keep the log files longer than 35 days, you can back them up before PI deletes them. If necessary, you can restore the backed up files at a later date for investigation.

Note: The message log can be written (but not read) using function calls in the PI

API. It can be both read and written using the function calls in the PI SDK.

You can also view the log files from PI SMT.

2.2.2 Viewing System Messages with pigetmsg

In general, the message source is a PI subsystem, but it can be a facility within a subsystem, such as pipoint if a point database error is recorded. You can run pigetmsg in interactive or non-interactive mode.

The pigetmsg utility is located in the PI/adm directory. To get help on usage of the pigetmsg utility, type:

pigetmsg /?

Using pigetmsg in Non-Interactive Mode

When you use pigetmsg in non-interactive mode, you specify all necessary parameters on the command line when you call pigetmsg. In this mode, There are no defaults for the start time (-st), end time (-et), or maxcount (-mc) options because the utility requires that at least two of these three parameters (start time, end time, max count) be defined.

‰ If start time and end time are specified, the utility returns messages from the start time to the end time.

2.2 - Viewing System Messages

‰ If start time and max count are specified, the utility returns the number of messages specified by the max count beginning from the start time.

‰ If end time and max count are specified, the utility returns the number of messages specified by the max count up to and including the end time.

‰ If start time, end time, and max count are all specified, the utility returns messages beginning at the start time and finishing when either the number of messages specified in the max count or the end time is reached.

All the command line options for pigetmsg are listed in the following table. Argument Description

-st Start time. This should be entered in PI time format. -et End time. This should be entered in PI time format.

-mc Max count. This is an integer the total number of messages to return. -id This is an integer that represents the specific message identification number

from the text-file: 0 for the free-format messages. The default is all messages. -pn This is the message source, either a specific program name (pinetmgr) or a wild-

card mask (* for all programs, *arc* for all archive related sources, etc.). The default is all programs.

-msg A string mask selection for the message text. The default is * (show everything). -dc Number of message to display at one time. The default is to display all

messages.

Using pigetmsg in Interactive Mode

When you run pigetmsg without specifying at least two of the required parameters (-st, -et, and -mc), the pigetmsg utility goes into interactive mode. In the interactive mode, you are prompted to enter these parameters. The standard defaults for the parameters are obtained by entering a carriage return, <Enter>, after each prompt.

In the interactive mode, there is a default for the start time, end time, and max count. The default for the start time is *-15m, which is 15 minutes prior to the current time. The end time is * which is the current time and the max count default is no limit.

Searching and Sorting the Messages

To list all messages received from a specific subsystem such as the Totalizer for today, use:

pigetmsg -st t -et "*" -pn pitotal

On UNIX systems, * on the command line is expanded to perform a directory search. Thus for pigetmsg it must be specified either as \* or *. The same is true for any mask containing *.

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, use:

pigetmsg -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

Using pigetmsg Remotely

The pigetmsg utility also supports remote logins to other PI Server systems. An interactive remote pigetmsg session is initiated with the -remote argument:

pigetmsg -remote

pigetmsg prompts the user for the required connection details: node name, TCP/IP port, user name, and password. The term “node” refers to the TCP/IP host name or TCP/IP Address of the PI Server.

Alternatively, you can initiate a remote passing all arguments on the command line. Parameter Description

-username Remote PI Server username -port TCP/IP port number

-node Remote PI Server node name -password Remote PI Server password

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

2.2.3 Viewing Messages When the Message Subsystem Goes Down

If the Message Subsystem is not available, messages are written to the Windows error log (or to standard output on UNIX). On Windows, use the Event Viewer to see messages when PI is running as Services, or check the command windows if running interactively. The PI Server messages that went to the event log messages are stored back to the PI Message Log on system startup and on regular time intervals – every 3 minutes.

On UNIX, you will find a log file for each subsystem in the PI/log directory. On both platform types, some startup messages may be written to these locations before the PI Message Subsystem is active.

2.2.4 Viewing Message Log Files Generated on other Servers

There are times when it is useful to read message log files that were generated on a different PI Server. The PI Message Subsystem executable can be run in an offline mode for this purpose.

Running the PI Message Subsystem in offline mode is very similar to pigetmsg; the significant difference is that the log file must be specified. Message log files are created

2.2 - Viewing System Messages

daily; each file covers one day. The file naming convention contains the year month and date. The log files are created in the PI\log directory.

Even though all messages will be read from the log file, pinetmgr must be running.

The PI Message Subsystem executable, pimsgss, is located in the PI\bin directory. Here is an example of running pimsgss offline to view messages from February 27, 2003:

D:\PI\bin>pimsgss -file ..\log\pimsg_1030227.dat Message ID [A], (0-n) (A)ll (H)ead (T)ail (Q)uit (?):

Once the log file is specified, the behavior is identical to pigetmsg. Only messages in the time period covered by the specified file can be viewed.

Offline use also allows specifying all arguments on the command line, just like pigetmsg. Messages that match the command line arguments are immediately displayed. Here is an example:

D:\PI\bin>pimsgss -file ..\log\pimsg_1030227.dat -st "27-feb-03 12:00" - et "27-feb-03 15:00"

0 pinetmgr 27-Feb-03 12:07:16

>> Connection accepted: Process name: piconfig(1696) ID: 88 0 pinetmgr 27-Feb-03 12:11:54

>> Deleting connection: Piconfig(1696), Shutdown request received from piconfig(1696) (8), ID: 88

0 pinetmgr 27-Feb-03 12:35:20

>> Connection accepted: Process name: Piconfig(1484) ID: 89 0 pinetmgr 27-Feb-03 12:38:08

>> Deleting connection: Piconfig(1484), GetQueuedCompletionStatus error: Broken Pipe [109] The pipe has been ended.

Connection: Piconfig(1484) (14, 109), ID: 89 0 pinetmgr 27-Feb-03 13:24:08

>> PInet accepted TCP/IP connection, cnxn ID 90 Hostname: olive.osisoft.com, 208.243.230.129

2.2.5 Interpreting Error Messages (pidiag)

Sometimes the message log includes error messages. Use the pidiag utility to interpret error codes:

pidiag -e errorcode

This will display the associated error message. For example, if the error code is 10722, you would type:

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. Note that the error code translation takes place on the operating system running pidiag. For example, on Windows, you could issue the command:

pidiag -e 2

Avoid reading error codes from the PI Server message log on one operating system and translating them with pidiag -e on another.

2.2.6 Subsystem Healthchecks (RPC Resolver Error Messages)

Every few minutes, the pinetmgr sends a healthcheck message to each of the PI subsystems. If one doesn’t respond within a given amount of time, pinetmgr will report the following message and the subsystem (RPC resolver) is marked off-line.

>> Deleting connection: pisnapss, Subsystem Healthcheck failed.

If an RPC is made to a subsystem that is marked off-line, the following message is generated.

[-10733] PINET: RPC Resolver is Off-Line

The following message indicates that the first part of a message was retrieved. This contains the message length. The pinetmgr attempted to retrieve the rest of the message but a timeout occurred.

>> Deleting connection: pisnapss, Connection lost(1), [-10731] PINET: incomplete message