License monitoring details

The responsibility for ensuring that a site does not use more seats than they have purchased falls to the end-user.

To assist in this effort, a mechanism within PV-WAVE logs user sessions for later analysis. PV-WAVE implements this via a set of environment variables, PV-WAVE kernel support, and a standard library routine used to analyze the log file(s).

There are two environment variables to control license monitoring (LM) logging: PVWAVE_LOG_LM and PVWAVE_LM_LOGFILE.

How it works

The LM logger records information about the PV-WAVE session in memory and appends that information to the log file at session exit. The record for each PV-WAVE session contains the start time, stop time, the features invoked during the session and the number of tokens used. The record size is 18 bytes.

The log file to be written is obtained from the operating system at the time that the session exits, so you can programmatically set or change the PVWAVE_LM_LOGFILE environment variable from within your PV-WAVE session using the PUTENV command should you wish different sessions or users to use different log files. The PVWAVE_LOG_LM environment variable, which enables/disables logging, must not be changed during the session.

The LM logger uses a file named .RW_lock in the LM logging directory to avoid multiple sessions trying to write to the log file simultaneously. If a session is not able to get a lock in a reasonable length of time, it writes its session information to a file in the log directory with the same name as the log file but with the session process ID appended. You should pass all of these files along with the main log file to the analyzer or concatenate them together and pass them as a single file.

If you see these extra files, it is likely you are running many, short PV-WAVE processes at the same time, usually in an automated batch job. If you think you are getting too many of them, check to make sure that a process didn’t terminate abnormally and leave the .RW_lock file behind. If no sessions are running and the file exists, delete it.

Seats vs. Tokens

For historical reasons, PV-WAVE sessions are licensed using tokens instead of seats. The number of tokens available is a function of the purchased platform, the product level and the license type. The log file analyzer reports use in terms of tokens

The number of tokens available is found in the header of the license.pvwave file provided to you by Rogue Wave. Compare the maximum number of tokens used in the output from the log file analyzer (WAVEUSAGE) to the numbers found in this file.

Ensuring an accurate count

System dates/times need to match

PV-WAVE license monitoring is based on product use. If you purchase three ADVANTAGE seats for Linux, and thus have three tokens available, this means that you may run up to three PV-WAVE ADVANTAGE Linux sessions at any given moment. There is no limit to the number of users who are allowed to use PV-WAVE, only the number of concurrent sessions running. The time stamps in the log file are used to determine concurrency.

Each machine running PV-WAVE is responsible for generating its own log file entry. To properly count concurrent sessions, it is important that the machines running PV-WAVE have accurate date/time settings. They don’t have to match exactly, but they should be as close as possible. If one or more machines are out of sync, your counts will not be accurate.

PV-WAVE needs to close properly

Since each log entry is written at session exit, it is important that each PV-WAVE session be terminated in a manner that allows the entry to be written to the log file. There are two ways that a PV-WAVE session might terminate without generating a log entry. The first is in the unlikely event that PV-WAVE crashes. In this case no entry will be written. The only other way that we have found so far is if the user kills the shell in which PV-WAVE is running. This is less likely on Unix platforms, but potentially common on Windows where people are accustomed to closing applications using the ‘X’ on the corner of the window. If you use the ‘X’ to close the PV-WAVE console window while a session is running, no log entry is made. This is not an issue when closing dialog boxes created and controlled by PV-WAVE, such as GUI-based PV-WAVE applications. It is only an issue when running PV-WAVE in the Windows console window, which is owned and controlled by the Windows system and does not inform PV-WAVE when it is killed.

Write permissions

The log file and its directory must be accessible and writable to any potential PV-WAVE user. If no log file is present, the user of the first PV-WAVE session creates the file and their default permissions will apply, possibly preventing other users from writing to it. For this reason, Rogue Wave recommends that before you begin logging you create an empty log file and set its permissions for broad, general populous access. On Unix, you can use the ‘touch’ command to create the empty file.

License monitoring environment variables

PV-WAVE includes several environment variables that allow you to configure how you interact with license management. The responsibility for ensuring that a site does not use more seats than they have purchased falls to the user. These environment variables and license logging provide you with the mechanisms needed to monitor PV-WAVE product use.

PVWAVE_LOG_LM

This environment variable turns license logging on and off. This provides the ability to examine product use over time. When set to 1, logging is enabled. When set to 0, logging is disabled. Logging is disabled by default. When logging is enabled, PV-WAVE appends a short (18 bytes), binary record to the log file when the session exits.

PVWAVE_LM_LOGFILE

This environment variable designates the location and name of the log file. On Unix platforms, the default name and location is <RW_DIR>/license/license.pvwave.log, where <RW_DIR> is the PV-WAVE installation directory On Windows platforms, the default location is %APPDATA%\pv-wave\license.pvwave.log, where %APPDATA% is the Windows system variable designating where applications are safely allowed to write data for each individual user.

The three environment variables previously referenced are defined to their default values on Unix platforms when wvsetup is sourced and may be changed by editing the wvsetup file in your installation. On Windows platforms they must be set in the environment of each individual machine and may be created/changed via the Control Panel->System->Advanced->Environment Variables dialog. Note that changes to the Windows environment affects all PV-WAVE sessions run on that machine.

A typical scenario is to enable logging periodically to collect a representative sample of your PV-WAVE usage, assemble all of your log files and pass them to the PV-WAVE standard library routine WAVEUSAGE. This routine reads the supplied file(s), analyzes their contents and issues a report about your PV-WAVE usage for the time period covered by the log file(s).

To learn more about WAVEUSAGE, see its documentation in the (Undefined variable: pvwave.waveur).