Integrating RLM Into Your Product

If you would like to integrate RLM into your own product, you will need to configure the RLM libraries and add calls to the RLM functions in your software.

If your application is written in Java, you should read this chapter to familiarize yourself with the basic RLM concepts. There are some Java-specific installation and integration instructions in the Using RLM with Java. If you have a .NET application, you will find instructions for integrating RLM in Using RLM with .NET section.

Reprise Software recommends that you take a look at the rlmclient.c sample program in the examples directory of the RLM kit. This example shows the use of the first 7 of the 8 functions in the RLM core API.

These first 7 functions are the basic functions you will use in your application. When you are ready to learn more about these or other RLM functions, consult the RLM Reference Manual.

The Game Plan

As an ISV you integrate RLM by adding calls from the RLM client library into your application. Only if you plan to ship concurrent-use (floating) licenses will you also configure and build a license server. You then ship your product plus a few additional components of the RLM license system, as required. You can accomplish the engineering portions of these tasks in less than a day – the hardest work is deciding what to license, and what license rights to grant to your customers. Once you integrate RLM, the additional components you ship are:

A license file to describe your customer’s rights to the product (custom-generated by you for each of your customers).
The RLM utilities (rlmutil – a standard part of the RLM kit).

If you provide Concurrent-use (floating) licenses to your customers you will also need to ship the license servers:

The RLM (generic) license server (a standard part of the RLM kit).
Your custom license server (Built from components from the RLM kit).

Note

The servers are required only if you are shipping floating licenses.

Except for the license file, the components are the same for every one of your customers. The actual license file, which describes your customer’s rights to the product, will (in almost all cases) be different for every one of your customers.

When deployed to support floating (concurrent-use) licenses, RLM is a client-server system, with license requests transmitted over TCP/IP from the client (your application) to the license server that controls license usage rights. When deployed to support nodelocked licensing, no network connection nor license server processes are needed.

Given that background, now we are ready to start.

Integrating RLM into your application – the 3 steps

To integrate RLM into your software, there are three steps:

Download and install the kit from the Reprise website
Configure your RLM libraries
Add RLM API calls to your application

Step 1: Download and install the kit

If you ran the demo in the second chapter, you have already done this. If not, follow the instructions in the previous chapter.

Step 2: configure your RLM libraries

Windows:

Extract the kit directories (src and x86_w3 or x86_w4 for 32-bit or x64_w3 or x64_w4 for 64- bit).

You have 2 options for configuring the libraries on Windows – you can either use a Visual Studio or Visual C++ Project, or a Command Window. Each method has the same outputs; choose the method you’re more comfortable with.

Configuring RLM with Visual Studio

The platform directories (x86_w*, and x64_w*) contain Microsoft Visual Studio or Visual C++ project and workspace files. Double-click on the appropriate .vcproj file to launch Visual Studio/Visual C++.

Click on “Rebuild All” in the Build menu in Visual C++, or “Build Solution” in Visual Studio. The build will complete after a few seconds and the output window will indicate 0 errors and 0 warnings.

You may be prompted to allow it to convert the project to a later version. Allow it to do so, then proceed.

Configuring RLM with a Command Window

To launch a Command Window with the development environment already set up, launch x64 Native Tools or x86 Native Tools from the Microsoft Visual Studio folder in your Start menu. The options differ with the specific version and edition of Visual Studio, but choose the one that does native development for the platform you’re on. In other words, if you’re on a 32-bit system, choose the option that does 32-bit development, and if you’re on a 64-bit system, choose the options that does 64-bit development. This correct choice may not always be clear from the names of the options, but the command window that’s launched will display a message at the top saying something like:

“Setting environment for using Microsoft Visual Studio 20xx x64 tools.”

or

“[vcvarsall.bat] Environment initialized for: ‘x64’”

You can also open a command window and run the vcvarsall.bat batch file provided by Microsoft to set up your command window for the next step. This batch file is located in the Visual Studio Program Files folder.

Next, do the following:

C:> cd to the place where you extracted the kit.
C:\your_kit> cd x86_w4 (or x86_w3, x64_w3, or x64_w4)
C:\your_kit\x86_w4> nmake

Unix or Mac:

Note

You have already performed these steps when you did the demo earlier.

% gunzip platform.tar.gz
% tar xvf platform.tar
% ./INSTALL
% cd platform
% make

All platforms:

RLM kits are pre-built for ISV “demo”, with licenses that expire in 30-60 days after the RLM kit release date. If your demo license has expired, you will need to put the new license you received from Reprise Software into the file license_to_run.h in the src directory. If you have purchased RLM, you will need to edit license_to_run.h to replace the license there with your permanent license, and you will also need to edit the makefile in the binary directory (x86_w* or x64_w*) to change your ISV name.

If you are using Java, there are a few additional steps required. These are described in the RLM Reference Manual.

Step 3: Add RLM API calls to your application

Using the example rlmclient.c as a guide, add the RLM API calls to your application. You will need rlm_init() and rlm_checkout() calls at a bare minimum, however it is good practice to call rlm_checkin() when you are finished with the license, and rlm_close() if your program makes no further licensing calls.

Once you have done this, compile your application using the RLM include files in the directory <kit_dir/src>, and link with the RLM client library.

You’re done!

Now that your application has been built with the RLM calls included, copy the example license file and edit it with your product names, etc. Use the rlmsign utility to sign the license file, and experiment with some node-locked and floating licenses. Don’t forget to read the note on your public-private key pair below.

Important note on your public-private key pair

Step 2, above, created a public-private key pair for you as part of the make (or nmake) command, or build in Visual Studio. Before you use RLM in your product, you need to create a public-private key pair that you will use for all your licenses, and you should do this only one time. The key pair will affect the licenses you create, and you want to be able to process older license keys with newer versions of your software. Note that you should do this once, not once per platform you install.

You can safely ignore the remainder of this note for now, but you should return to this and understand the implications before you begin your RLM production implementation.

To create your key pair, run the rlmgenkeys utility. rlmgenkeys creates a pair of files:

rlmpubkey.c - your public key - this gets built into your application and your ISV server.
rlmprivkey.c - your private key - this gets built into rlmsign to create your license keys.

To run rlmgenkeys:

% cd kit-dir
% cd src
% ../platform-dir/rlmgenkeys

Where:

kit-dir is the directory where the RLM kit resides, and
platform-dir is the RLM binary directory for the machine on which you are running.

If you do not share src directories on your various platforms, run rlmgenkeys once and copy the resulting files to all the other *src directories you use. Once you have created your key pair and installed it in the src directories in all your RLM kits, do a “make” in each kit to update the rlm.a library.

You should be very careful with these two files. DO NOT LOSE THEM. Do not allow your private key file (or rlmsign) outside your company. If your private key file (or rlmsign) becomes compromised, others will be able to make licenses for your products. Once you generate these files, you should copy them to a safe place where they will not be lost, and where they will be secure.

When you upgrade to a newer version of RLM, you will be asked for the location of these two files, so that the new version will generate compatible keys with your older versions.