Monitoring PV‑WAVE use

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 is 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_LIC_FILE

The environment variable PVWAVE_LIC_FILE allows you to specify a license file for PV‑WAVE that is other than the default. By default, PV‑WAVE uses the file: <RW_DIR>/license/license.pvwave. If you wish to specify an alternative file or location, set PVWAVE_LIC_FILE to be the full path to and file name of the license file you wish to use. Only one file may be specified.

PVWAVE_LM_WHITELIST

The environment variable PVWAVE_LM_WHITELIST allows you to restrict the use of PV‑WAVE to a specified list of users. Set PVWAVE_LM_WHITELIST to the full path to and file name of the text file containing the list of users allowed to use PV‑WAVE. PV‑WAVE compares the user name of the account currently using PV‑WAVE to this list of users. If the user name does not appear in the list, PV‑WAVE displays the following message and exits:

Unauthorized user: username; please see your local PV-WAVE site administrator

The file containing the list of users must conform to the following format restrictions:

  • Must be a plain text file.

  • Each name must be on a separate line.

  • Lines beginning with the comment character (#) are ignored. Comment characters that do not begin a line are considered part of the user name.

  • Does not include leading or trailing spaces which are not part of the user name.

  • Does not include domain names.

    • Note:
    If PVWAVE_LM_WHITELIST is defined and PV‑WAVE cannot find or open the file, it prints an error and exits.

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 use for the time period covered by the log file(s).

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