Licensing
This section explains the licensing for Pervasive PSQL Vx Server and contains the following topics:
•
License Model
•
Status Codes Affected
•
Utilities Affected
•
Message Logging
•
Access Methods Affected
•
Application Changes Required
•
Key Validation
License Model
Pervasive PSQL Vx Server is designed to support highly virtualized environments. For instance, Vx Server includes support for Cloud computing (private, community, and hybrid), as well as for full virtualization, partial virtualization, and paravirtualization. Pervasive PSQL Vx Server has no restrictions on hosting, connection pooling, Internet or intranet use. No additional license is required for use with hypervisor features such as live migration, failover, fault tolerance (FT), high availability (HA), and disaster recovery.
The technological and operational differences that come with virtualized environments require a license model optimized for such environments. The user count license model used for Pervasive PSQL Server and Workgroup does not suffice. That model works well for traditional client/server applications in which many users or devices constantly add, update, and delete records from distinct individual desktops.
Instead, Pervasive PSQL Vx Server uses a license model that shifts the emphasis from how many users to how much work the database server processes. The model is based on capacity to accommodate license enforcement in virtualized environments. For example, each instance of Pervasive PSQL Vx Server has capacity limits on both the number of sessions in use and the data in use. (Also, each instance is identified by a virtual hostname and all virtual MAC addresses.)
Number of Sessions In Use (Session Count)
A “session” is defined as a client ID used by the transactional engine interface or a connection to the relational engine interface. “Client ID” is defined as a 16-byte structure that combines elements provided by the application, by the client platform, and by the database engine to uniquely identify a database transaction context.
The number of sessions in use is a count of the concurrent sessions. For brevity, “number of sessions in use” is also referred to “session count.” “Session count limit” is the maximum permitted number of concurrent sessions as granted by a license agreement.
Messages pertaining to session count are logged to the various Pervasive PSQL logging repositories. See Message Logging.
The database engine uses various sessions for its own internal processes, such as for accessing Pervasive PSQL system files, metadata files, dbnames.cfg, and default system databases. These internal sessions do not consume any session counts.
Data In Use
“Data in use” is defined as the total size of all concurrently open data files. (A data file is a file created by an application to provide the data processed by that application.) “Data in use limit” is the maximum permitted amount of all concurrently open data files as granted by a license agreement.
The value for data in use increases when a data file is first opened. Subsequent opens to an already open data file do not add to the total. Data in use also increases if an open file increases in size. Operations on an already open file continue to be permitted even if the size of the open file increases beyond the data in use limit.
The value for data in use decreases when a data file is closed by the final user to have the file open. Since more than one user can access the same data file, all opens must be closed before data in use decreases.
Messages pertaining to data in use are logged to the various Pervasive PSQL logging repositories. See Message Logging.
The database engine uses various files for its own internal processes, such as Pervasive PSQL system files, metadata files, dbnames.cfg, and default databases. Files used for internal processes do not increase the value for data in use.
Estimating Session Count and Data In Use
Before you move from PSQL Server to PSQL Vx Server, you need to determine what size license you need for your business. To make that determination, you need information about your session count and data usage. Pervasive Software provides Capacity Usage Viewer to provide that information.
Capacity Usage Viewer is a utility that records peak daily session use and peak daily data use. It renders those figures into two graphs that display your use over time. Capacity Usage Viewer enables you to select time periods ranging from All to Last week. You can also zoom in to view the data for a customized time period.
To estimate your capacity requirements, select a time period that includes maximum and minimum licensing requirements. For example, if your business has quarterly cycles, include at least 90 days worth of data. By reviewing data usage and concurrent session usage over time, you can ensure that PSQL Vx license capacity meets or exceeds your peak usage requirements.
Refer to Capacity Usage Viewer in Pervasive PSQL User's Guide for detailed information about how to access and use Capacity Usage Viewer.
*Note: Monitor can also help you estimate session count and data in use. See Monitoring Database Resources in Advanced Operations Guide and Monitor in Pervasive PSQL User's Guide.
Behaviors When Limits Are Reached
The following table summarizes the expected behaviors and suggested corrective actions when the limits are reached for session count and data in use.
Table 2
Expected Behaviors When Limits Are Reached for Session Count and Data In Use
Limit Reached
Behavior
Corrective Action
Session Count
The database engine denies requests for new sessions and returns status code 161 to the application.
Sessions established before the session count limit was reached continue to work and are not interrupted or disconnected.
Messages pertaining to session count are logged to the various Pervasive PSQL logging repositories.
Authorize an increase key for session count. An increase key can be authorized at any time and does not require that you close sessions or stop the database engine. The increase is immediately available.
You may try closing some of the current sessions. However, this action requires that you know which sessions are safe to close without resulting in incorrect data, incomplete records or aborted transactions.
Data In Use
The database engine denies requests for new file opens and returns status code 161 to the application.1
Subsequent opens to an already open data file are permitted. That is, if a file is already open and data in use reaches or exceeds its limit, other users can still access the open file.
Note that data in use also increases if an open file increases in size. Operations on an already open file continue to be permitted even if the size of the open file increases beyond the data in use limit.
The value for data in use decreases when a data file is closed by the final user to have the file open. Since more than one user can access the same data file, all opens must be closed before data in use decreases.
Messages pertaining to data in use are logged to the various Pervasive PSQL logging repositories. For example, a message first alerts you when data in use reaches 90% of the data in use limit.
Authorize an increase key for data in use. An increase key can be authorized at any time and does not require that you close data files or stop the database engine. The increase is immediately available.
You may try closing some of the currently open data files. However, this action requires that you know which data files are safe to close without resulting in incorrect data, incomplete records or aborted transactions.
1 Status code 161 is returned if the file to be opened exceeds 110% of the data in use limit. A slight buffer above 100% is provided because an increase in data in use can also result from the growth of currently open data files.
Product Key and Increase Key
Because Pervasive PSQL Vx Server uses a capacity-based license model, it requires its own product key. You cannot authorize Pervasive PSQL Vx Server with a key for Pervasive PSQL Server or Pervasive PSQL Workgroup. Each instance of Pervasive PSQL Vx Server requires a key.
Session count and data in use are defined in the Pervasive PSQL Vx Server key issued by Pervasive Software or by an application vendor. Keys are available in various combinations of values for session count limit and data in use limit. See www.pervasivedb.com for details.
Increasing the Value for Session Count or Data In Use
Pervasive Software or an application vendor offers a key to increase session count limit, data in use limit, or both. (Conceptually, the key is the same as a user count increase (UCI) key for Pervasive PSQL Server or Pervasive PSQL Workgroup.)
You immediately increase the value for session count limit, data in use limit, or both when you authorize the key. A restart of the database engine is not required. A permanent key must be present to authorize an increase key. An increase key cannot be authorized onto a temporary key.
If you deauthorize the permanent key, all increase keys associated with that key are also deauthorized.
Note that the database engine logs a message to the Pervasive PSQL logging repositories when the limit increases for session count or data in use. The message contains the current limit and usage. See also Message Logging. You can monitor the current, peak, and maximum values for session count and data in use with the Monitor utilities. See Monitoring Database Resources in Advanced Operations Guide.
Status Codes Affected
The wording, description, or both for the following status codes have changed to better address both license models (user count and capacity based).
•
161: A key has reached a maximum limit for user count, session count, or data in use, or has changed state to expired or disabled
•
7064: No license obtained for the product
•
7065: A product has not been obtained
•
7102: Illegal license type is defined
•
7110: Only temporary licenses are installed on the system and all of them have expired
•
7124: An increase key for user count, session count, or data in use must have a vendor ID that matches the vendor ID of an authorized permanent key
•
7125: An active permanent license already exists
•
7126: Cannot increase the value beyond the maximum limit for user count, session count, or data in use
•
7475: Invalid value for user count, session count, or data in use
•
-4838: A key has reached a maximum limit for user count, session count, or data in use, or has changed state to expired or disabled.
Utilities Affected
The following utilities have changed to accommodate a capacity-based license model.
License Administrator (GUI and CLI)
License Administrator displays the session count limit and data in use limit for a given key. You may also authorize a key to increase the value for session count limit or data in use limit. A single increase key can increase both values depending on the key. See License Administration in Pervasive PSQL User's Guide for details.
Monitor
Monitor has the following changes pertaining to session count and data in use. The changes are summarized for the graphical user interface. The command line interface (bmon) contains similar changes where applicable. See Monitoring Database Resources in Advanced Operations Guide for details.
The changes to Monitor make it easier to estimate license requirements for session count and data in use. For example, Monitor displays the peak values for session count and data in use, and informs you how long the database engine has been running. Duration plus peak usage allows you to establish a more accurate baseline for estimating. When you estimate capacity, include the values determined from your peak conditions.
•
The “Active Users” menu command and “MicroKernel Active Users” dialog have been renamed to “Active Sessions” and “MicroKernel Active Sessions,” respectively. The dialog has been modified to reflect session information.
•
The “MicroKernel Resource Usage” dialog show the current, peak, and maximum values for user count, session count, and data in use. “Licenses in Use” has been removed.
•
The “MicroKernel Active Files” dialog lists the physical file size in kilobytes (KB) for a given file.
•
The amount of time in weeks, days, hours, and minutes that the database engine has been running (referred to as “MicroKernel Uptime”) is shown on the “MicroKernel Communications Statistics” dialog and on the “MicroKernel Resource Usage” dialog.
Message Logging
Messages pertaining to the capacity-based license model are logged to all of the logging repositories: Notification Viewer, PVSW.LOG, and the operating system event log. Any message logged to Notification Viewer is also logged to the operating system event log and to PVSW.LOG. Any message logged to the operating system event log is also logged to PVSW.LOG. If a message also includes a list of open files, the list is logged only to PVSW.LOG. See also Pervasive PSQL Message Logging in Pervasive PSQL User's Guide. .
The database engine logs a message when the capacity increases or decreases for session count or data in use. The message contains the current capacity and usage. You can monitor the current, peak, and maximum values for session count and data in use with the Monitor utility. See Monitoring Database Resources in Advanced Operations Guide.
Session Count
All messages pertaining to session count are informational. Session count messages inform you when session count reaches its limit, when session count returns to an acceptable range after a period of time, and when session count capacity changes.
If the total number of active concurrent sessions equals the session count limit, the database engine denies requests for new sessions and returns status code 161 to the application. Established sessions continue to work and are not interrupted or disconnected.
When a session closes all of its file handles, session count is decremented. No Reset operation is required to decrement the session count. Note, however, that unless a session is reset, it remains visible in the list of active sessions in Monitor even though the session does not increase session count. See Viewing Session Information in Advanced Operations Guide.
Data In Use
Messages for data in use can be informational, warning, or error. When applicable, the messages advise you on corrective actions.
A message first alerts you when data in use reaches 90% of the data in use limit. This brings to your attention that data in use is approaching its limit and corrective action may soon be required. Additional messages—with escalating frequency—occur when the data in use limit reaches 100% or slightly exceeds 100%. (A buffer above 100% is provided because an increase in data in use can also result from the growth of currently open data files.)
For all of the message occurrences just discussed, the operation on the file is permitted. The messages are logged whether the file is first opened or already open and its size increases.
If the file to be opened exceeds 110% of the data in use limit, the database engine denies the open request and returns status code 161 to the application. The error message logged to PVSW.LOG and to the operating system event log lists the name of the file, its size, and the data in use limit. Files already open continue to be available and access to them is not interrupted or disconnected.
Access Methods Affected
The following SDK access methods have changed to accommodate a capacity-based license model.
DTI
•
The XML string that PvGetProductsInfo returns includes additional elements for session count, session count limit, data in use, and data in use limit. If the product is Pervasive PSQL Vx Server, the elements returned for user count and maximum user count are always zero. If the product is Pervasive PSQL Server or Workgroup, the elements returned for session count, session count limit, data in use, and data in use limit are always zero. See PvGetProductsInfo() in Distributed Tuning Interface Guide.
•
The PVMKDEUSAGEEX structure in monitor.h has been modified to include the following:
•
The current, peak, and maximum values for sessions and for data in use.
•
The duration, in seconds, that the database engine has been running (referred to as “engine uptime”).
The PVMKDEUSAGEEX structure is used by PvGetMkdeUsageEx. See PvGetMkdeUsageEx() in Distributed Tuning Interface Guide.
•
The PVFILEINFO structure in monitor.h has been modified to include the physical size in kilobytes of a file. This structure is used by PvGetFileInfo. See PvGetFileInfo() in Distributed Tuning Interface Guide.
•
The pserverClientType argument for PvGetEngineInformation returns two additional types: VXWIN_SERVER(6) and VXLINUX_SERVER(7). See PvGetEngineInformation() in Distributed Tuning Interface Guide.
DTO
All of the changes to DTO apply only to DTO2. See DTO2 in Distributed Tuning Objects Guide.
•
The DtoMonitor object contains the following additional properties. See DtoMonitor Object in Distributed Tuning Objects Guide.
CurLicDataInUseMB
Returns the current value in megabytes (MB) of data in use.
CurSessionCountInUse
Returns the current number of sessions in use (the current session count).
EngineUpTimeSecs
Returns how long in seconds the database engine has been running.
MaxLicDataMB
Returns the maximum allowed size in megabytes (MB) for data in use (the data in use limit). The hex value 0xFFFFFFFF means unlimited.
MaxSessionCount
Returns the maximum number of sessions allowed by a license (the session count limit). The hex value 0xFFFFFFFF means unlimited.
PeakLicDataInUseMB
Returns the peak value in megabytes (MB) of concurrent data in use.
PeakSessionCountInUse
Returns the peak number of concurrent sessions in use.
 
•
The DtoOpenFile object contains the following additional property. See DtoOpenFile Object in Distributed Tuning Objects Guide.
PhysFileSizeKB
Returns the physical size of the file in kilobytes (KB).
 
•
The DtoEngineInformation object contains the following additional values for the ServerClientType property:
•
6 = VXWIN_SERVER
•
7 = VXLINUX_SERVER
See DtoEngineInformation Object in Distributed Tuning Objects Guide.
Application Changes Required
Typically, no application changes are required. If your application already works with Pervasive PSQL Server or Workgroup, it will also work with Pervasive PSQL Vx Server.
You need to revise your application if it uses DTI or DTO and you want to use the additional functionality for a capacity-based license model. See Access Methods Affected.
Key Validation
Pervasive PSQL Vx Server periodically verifies that the key for the database engine is still valid. The validation requires Internet connectivity.
If the periodic validation determines that a key is invalid, the key changes state from “active” to “failed validation.” The database engine functions normally for 30 days so that you have ample time to correct the failures.
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 through various logging repositories used by Pervasive PSQL Vx Server. See Pervasive PSQL Message Logging in Pervasive PSQL User's Guide.
If you do not correct the causes of the failed validation before the allowed period ends, the key changes state again to “disabled.” The key is no longer valid and the database engine cannot access data files.
For example, if the network loses Internet connection, you have 30 days to restore connectivity and re-validate Pervasive PSQL Vx Server. Pervasive PSQL Vx Server logs messages to various message repositories to inform you that Internet connectivity has been lost. If Internet connectivity is not restored within the allowed period, the Pervasive PSQL Vx Server key becomes disabled.