Pervasive PSQL Message Logging
Pervasive PSQL provides various logging repositories for messages to assist you with troubleshooting. The logging falls into two broad categories:
•
All messages. These messages include status, error, warning, and information messages. They can originate from any Pervasive PSQL component, including the license administration components.
•
Licensing messages. These messages alert you about licensing issues and provide troubleshooting information. They originate from license administration components.
The following table summarizes the repositories.
Table 21
Pervasive PSQL Message Logging Repositories
Repository
Written To By
Pervasive Notification Viewer
License administration components
Operating System Event Log
License administration components (Windows)
All Pervasive PSQL components (Linux)
Pervasive PSQL Event Log
All Pervasive PSQL components (Windows)
Licensing Messages
Several of the logging repositories emphasize licensing messages. The reason is that the Pervasive PSQL licensing components periodically verify that the key for the database engine is still valid. If a key is determined to be invalid, the key changes state from “active” to “failed validation.” The database engine functions normally for a certain number of days so that you have ample time to correct the validation failure(s).
If you do not correct the failures before the number of days ends, the key changes state again to “disabled.” The key is no longer valid and the database engine cannot access data files.
Because you need to attend to a failed validation in a timely manner, the state change of the key is brought to your attention as soon as possible. For example, a message is logged to all of the message repositories. The most evident of these is Pervasive Notification Viewer. (License Administrator also displays the state of keys, which you can re-check at any time by initiating a validation action. See License Administration in Pervasive PSQL User's Guide.)
Change in State of Key
The following table explains the type of message returned based on the change in state of the key.
Table 22
Message Type Based on Change in State of Key
Message Type
Change in State of Key
Scenario
 
From
To
 
Warning
Active
Failed Validation
A validation action detects that the key has failed validation. For example, the machine signature cannot be determined, no longer matches the key, or one or more licensing components cannot be loaded.
The database engine functions normally for a certain number of days so that you have ample time to correct the validation failure(s).
Warning
Disabled
Failed Validation
Only some of the conditions that resulted in a disabled key have been corrected, but at least one condition still needs to be addressed.
Because the key has changed state to failed validation, the database engine functions normally for a certain number of days so that you can correct the remaining validation failure(s).
Error
Failed Validation
Disabled
The number of days provided to correct the failed validation have expired. The conditions causing the failed validation were not corrected before the expiration. The key is no longer valid and the database engine cannot access data files.
Information
Failed Validation
Active
The condition(s) that caused the failed validation is corrected. The key is valid and the database engine has all functionality.
Information
Disabled
Active
The condition(s) that disabled the key is corrected. The key is valid and the database engine has all functionality.
Note that no messages are logged for keys with a state of “expired” (which applies only to temporary keys), or “inactive” (which applies to keys still registered on the machine from previous versions of Pervasive PSQL).
Logging Frequency
The following table lists the frequency with which licensing messages are logged for particular actions.
Table 23
Logging Frequency of Messages By Initiating Action
Initiating Action
Logging Frequency
Logging Repository1
Key changes state as described in Table 22
Immediately
•
Pervasive Notification Viewer
•
Operating System Event Log
•
Pervasive PSQL Event Log
Key remains in failed validation state
Once a day reminder
•
Pervasive Notification Viewer
•
Operating System Event Log
•
Pervasive PSQL Event Log
A validation action invoked programmatically through API call
See To Display Remaining Authorizations in Pervasive PSQL User's Guide, PvValidateLicenses() in Distributed Tuning Interface Guide, and ValidateLicenses in Distributed Tuning Objects Guide.
Immediately
•
Operating System Event Log
•
Pervasive PSQL Event Log
Warning or error messages originating from the Pervasive PSQL licensing server
Immediately
•
Operating System Event Log
•
Pervasive PSQL Event Log
1Message logging follows a one-way hierarchy: any licensing message logged to Pervasive Notification Viewer is also logged to the Operating System Event Log and to the Pervasive PSQL Event Log. Similarly, any licensing message logged to the Operating System Event Log is also logged to the Pervasive PSQL Event Log.
Pervasive Notification Viewer
The Pervasive Notification Viewer (hereafter, just “Notification Viewer”) is an application utility for displaying messages logged by the licensing components. The purpose of the utility is to inform you of noteworthy licensing messages (see Table 23) in a noticeable but unobtrusive manner.
By default, Notification Viewer is installed with Pervasive PSQL Server, 32-bit and 64-bit, on Windows and Linux, and with Pervasive PSQL Workgroup. Also by default on Windows platforms, Notification Viewer restarts when you restart Windows.
On Windows platforms, the executable is named notifyviewer.exe. The utility provides a single running instance for a user. An attempt to start Notification Viewer when it is already running brings the GUI to the front of the application displays.
On Linux distributions, the utility is a shell script named notifyviewer. Each time the shell script executes it starts another instance of Notification Viewer. If you restart Linux, you must restart Notification Viewer. The shell script is not automatically executed when Linux is restarted.
Command Line Options
You can specify how you want the utility to start with the following command line options.
Option
Meaning
(no option)
If you start the utility without specifying an option, the GUI displays and a tray icon appears if the operating system supports a system tray.
-tray
Starts the utility with the GUI hidden and displays a tray icon. If the operating system does not support a system tray, the GUI displays (is not hidden).
Notification Viewer provides two interfaces: system tray icons and a graphical user interface (GUI).
System Tray Icons Interface
By default on Windows, Notification Viewer starts with the GUI hidden and displays its system tray icon. (On Linux, Notification Viewer starts as a GUI and displays its system tray icon if the Linux distribution supports a system tray.) After starting, the utility begins monitoring licensing messages.
If Notification Viewer detects unread messages, the tray icon visibly changes to indicate unread messages. See Tray Icons.
Notification Viewer also displays two types of tooltips. The mouse-over tooltip displays the number of important unread messages (if any), the total number of unread messages, or the name of the utility if all messages have been read. A balloon tooltip displays when Notification Viewer detects messages that need to be brought to your attention. On Windows, the balloon tooltip remains visible until you dismiss it directly or perform a keyboard or mouse operation. On Linux, you must click on the balloon tooltip to dismiss it.
Popup Menu
The popup menu for the tray icon contains two menu items: “Open” which opens the GUI, and “Exit” which will terminate the utility. You right-click on the tray icon to display the popup menu.
Tray Icons
The following table explains the meaning of the tray icons.
Icon
Meaning
Notification Viewer is running and monitoring licensing messages. This icon indicates a “normal” condition in which all messages have been read.
Notification Viewer contains unread messages.
This icon remains visible until all unread messages are read. See Left panel.
Graphical User Interface
You can open Notification Viewer GUI by double-clicking the tray icon or by right-clicking on the tray icon then clicking “Open.” By default on Linux, Notification Viewer starts as a GUI and displays its system tray icon. (If you want to change the startup behavior on Linux, pass the -tray option to the notifyviewer shell script. If the Linux distribution does not support a system tray, Notification Viewer displays the GUI but no system tray icon. In that case, start Notification Viewer by running the shell script.)
When the GUI is visible, unread messages are immediately added to the GUI. (In addition, the tray icon tooltip is shown and the icon changes to indicate unread messages.)
Pervasive PSQL tracks which records in the notification file are read or unread for each user. That is, each user displaying the GUI sees all of the messages, but whether a particular message is read or unread varies by user.
If a system tray is not supported by an operating system, the “close” command for Notification Viewer terminates the utility. If a system tray is supported, then “close” hides the GUI and the tray icon becomes the only visual representation that the utility is still running.
Toolbar and Panels
The Notification Viewer GUI provides a toolbar and two main panels as shown in Figure 31.
Figure 31 Notification Viewer GUI
 
GUI Element
Description
Toolbar
Provides two options:
•
Show only unread messages (toggle on, toggle off)
•
Mark all messages as read
Left panel
Contains a scrollable list of messages. They are sorted with the latest messages on top and arranged in three groups: “Today,” “Previous 7 days,” and “Older.” You can expand and collapse each group.
Each message shows an image for the type of information, a caption string, the message date and a brief description. All text is in a bold typeface if the message is unread.
To “read” a message: click on (select) the message. Once selected, the typeface for the message changes to a regular typeface.
Right panel
Shows the message details, which provide a full description of the message, and when applicable, suggestions to resolve any issues.
Operating System Event Log
The Pervasive PSQL license administration components write messages to the operating system event log on Windows platforms. All Pervasive PSQL components write messages to the operating system event log on Linux distributions.
Windows Platforms Event Logs
Windows operating systems provide a method to log events categorized as “Application,” “Security,” or “System.” Pervasive PSQL logs licensing messages only to the Windows Application Event Log. The messages are a subset of the licensing messages written to PVSW.LOG.
Any licensing message categorized as an “error” or “warning” is logged. This includes messages that result from a change in the state of a key as well as other warning and error messages (see Table 23). In addition, certain information messages are logged, such as those listed in Table 22.
Viewing Event Logs
Windows operating systems provide a graphical user interface utility called Event Viewer to view and manipulate event logs. The utility can be accessed through the Windows Control Panel or by executing the command eventvwr.msc from a command interface. Note that the Event Viewer interface for Windows XP and Windows Server 2003 differs from the one for Windows Vista and later.
Regardless which Event Viewer is used, Pervasive PSQL displays the following for an event.
•
Date and Time – date and time the event occurred
•
Source – Pervasive SQL
•
Category – Product Keys
•
Type/Level – level of the event: Information, Warning, or Error
•
Event ID – 1000
•
User – N/A
•
Computer – name of the computer
In addition, on Windows Vista and later, the Keyword column displays “Classic” and the Log column displays “Application.” Event Viewer allows you to display additional columns, but Pervasive PSQL provides no data for them.
Linux Distributions Event Logs
On Linux distributions, all Pervasive PSQL components write messages to the standard Linux logging system, syslog. By default, syslog writes to the /var/log/messages directory. Optionally, for SQL Connection Manager only, you can also log messages to the event.log file.
Event.log File and Bti.ini
Bti.ini is a Pervasive PSQL configuration file used on Linux distributions. By default, the file is located in the /usr/local/psql/etc directory.
The file lets you configure settings for the SQL Connection Manager (the “SQLManager” section in the INI file). One of the settings, LogEvent, determines the type of event messages logged to the event.log file. By default, event.log is located in the /usr/local/psql/bin directory.
Bti.ini Parameters for SQLManager Section
Description
MgrPort
Sets the port number used by the SQL Connection Manager. The default is 1583.
MgrUseTransport
Sets the type of protocol used by the SQL Connection Manager. This must be set to TCP.
LogEvent=msg_type
Specifies one of the following values for msg_type to indicate the type of messages logged to event.log (the default is 1):
•
0 – no logging
•
1 – errors only
•
2 – errors plus warnings
•
3 – errors plus warnings plus information messages
•
4 – errors plus warnings plus information messages plus connect.log
InstallDirectory=/usr/local/psql
Activates the connection log: /usr/local/psql/connect.log
Pervasive PSQL Event Log
On Windows platforms, all Pervasive PSQL components write status, error, warning, and information messages to the Pervasive PSQL event log. (On Linux distributions, Pervasive PSQL does not use an exclusive event log. Instead, all Pervasive PSQL components write messages to the standard Linux logging system, syslog. See Linux Distributions Event Logs.)
The Pervasive PSQL event log is called PVSW.LOG and, by default, is located in the application_data_directory\PSQL\logs directory. All Pervasive PSQL components on Windows platforms write to this log file. If two or more Pervasive-based applications are running on the same machine, they share PVSW.LOG.
PVSW.LOG Fields
PVSW.LOG consists of text messages in a format described in Table 24.
Table 24
PVSW.LOG Fields 
Field
Contents
Date
Automatic date-stamp in mm/dd/yyyy format.
Time
Automatic time-stamp in hh:mm:ss format. Also indicates AM or PM.
Component
File name of component returning the error (prefix only, no extension).
Process
Instance ID of the component, which is the process ID of the component.
Process Name
Path and name of the component, truncated to the last 15 characters.
Computer Name
Name assigned to the machine hosting the process, truncated to the first 15 characters.
Type
A single character: I for Information, W for Warning, or E for Error.
Message
The message text which may be either a string retrieved from a resource associated with the calling component or a text string passed directly from the calling component.
Some message text may contain numeric values, which may be in decimal or hexadecimal format. The characters “0x” precede any hexadecimal values to distinguish them from decimal values.
Some message text may also contain information specific to an OEM application, such as a link to a vendor’s Web site and troubleshooting information.
An entry may be followed by binary data in standard hexadecimal format. There is no limit to the length of the binary data.
PVSW.LOG Example Entry
The following shows an example of the type of data contained in PVSW.LOG.
Date
Time
Component
Process
Process Name
5/10/2011
9:53:06 AM
LicenseMgr
9048
NTDBSMGR.EXE
Computer Name
Type Category
Message
USRegion2Svr
W
License failed validation. Remaining Days: 14