Persistence Data Initialization and Cleaning—Using Legacy API and Utilities

Setting Up Persistence Data on a System

For Standalone Scenarios

For standalone scenarios, you can set up the system using either of the following options:

>On Windows, UNIX, and Linux ARM: Integrate the sntlInitStandaloneSystem API function in your application installer or create a custom utility that calls this function. The system initialization functions are included in the lsinit client library.

NOTE   On non-Windows, to perform any operation in standalone mode persistence data must be initialized. This is done by calling the sntlInitStandaloneSystem API. This is a one-time activity and administrator rights are needed for initializing the persistence data.

>On Windows: Allow your customers to run the lsinit.exe, a command-line utility for Windows. You need to generate this utility using lsgeninit.exe

>On Android: Integrate the sntlInitStandaloneSystem API in your application. The system initialization functions are included in the lsinit client library.

>There is a difference in the way the two methods show the error codes. While the API function shows specific error codes (documented in the Sentinel RMS API Reference Guide), the utility maps multiple error codes to a single generic error. See the table below for details:

Error as Shown by lsinit.exe	Corresponding sntlInitStandaloneSystem error
#1 ERR_LSINIT_CORRUPT_EXE (if lsinit.exe is corrupt. Since the input to the API function is via parameters and not through any file, no corresponding error exists in the API function.)	--
#2 (ERR_LSINIT_INFO_EXISTS)	0x00000008 (ERR_INIT_INFO_EXISTS)
#3 (ERR_LSINIT_INIT_FAIL)	0x00000010 (If sntlInitStandaloneSystem returns any error code except ERR_INIT_INFO_EXISTS)

There can be a scenario when you want to set up persistence data for multiple licenses at one time. If you use lsinit.exe to do this, then remember that the status returned is always of the last operation only. So if lsinit.exe returns success, it only means that the persistence data for the last license has been set up successfully. The set up operations for licenses other than the last one may have succeeded or failed. Therefore, in this scenario, use of the API function is recommended to show the status for each license.

For Network Scenarios

For network scenarios, the sntlInitNetworkSystem API function is provided to set up the License Manager for persistence information. However, if you use the Sentinel RMS License Manager installer or MSI on the host machine, there is no need to call this function through any other means.

NOTE   The sntIInitNetworkSystem API has been deprecated. It has also been removed from the public header lsinit.h.

Important Notes

>As a part of system initialization, some persistence data files are created. However, these do not interfere with the restricted files, folders or registry on Windows, as Sentinel RMS is ready for Windows Logo Compliance. Instruct your customers to not delete the files created at run-time.

>The system initialization options are only available for the applications licensed using Sentinel RMS version 8.x.x or later. If you are planning an upgrade for any previous version-based customers, do allow system initialization using any of the means mentioned above. However, the latest versions of the client library and system initialization library must be used.

>The following persistence databases are maintained separately for each software vendor’s applications:

•Trial license persistence data in all scenarios (on a standalone system, and License Manager)

•Commuter license persistence data on the License Manager

•Volume transaction license persistence data in all scenarios

•Standalone revocation persistence data on a standalone system

•Network revocation persistence data on the License Manager (as per license revocation method 1)

•Standalone Lease and Network Lease on the License Manager.

System Initialization (lsinit) Libraries

See Platforms, Libraries, and Compilers for the list of system initialization libraries on various supported operating systems.

For details about the API functions, refer to the Sentinel RMS SDK API Reference Guide.

Using the lsgeninit Utility (Windows Only)

NOTE   Administrator privileges are required to run this utility.

Alternatively, lsgeninit.exe, a command-line utility for Windows (only), is used for generating the lsinit.exe utility, which in turn is used for setting up system for standalone licensing.

This utility requires a configuration file containing the GUID, feature name, and version as command-line parameters. The configuration file can list up to 100 records, one record in a line, in the following format:

<GUID> <FeatureName> <Version> # comments

Specify GUID, feature name, and version. Specify version if it was included in the license; this initializes the persistence for a specific feature-version combination. If no version was included in the license itself, it can be skipped here too. Each feature-version combination should be listed only once. You may also specify the RandomGUID keyword in the configuration file to have a GUID automatically generated for any feature. For example,

RandomGUID <FeatureName> <Version>

This utility also requires a stub binary, lsinitstub.exe, to be present at the same location from where lsgeninit utility is executed. On successful execution of lsgeninit, lsinit.exe will be generated. This installer file should be executed on the target system. If executed with the "-debug" option, it returns the initialization status for each record.

After successful execution, the lsgeninit utility needs user input to return to the command prompt. This command-line utility asks the user to press the enter key to continue. Use the "-np" (No pause) option while executing the lsgeninit.exe utility to eliminate the user input requirement.

Recovering from Persistence Data Corruption (Persistence Cleanup)

See Cleaning Persistence Data Using lsclean.