Temporary Licenses

You have the ability to move a floating license from an RLM Cloud license server and create a temporary nodelocked license which operates without an internet connection. Temporary licenses are always nodelocked, either uncounted or single. Temporary licenses are preferred over roaming licenses if they solve your use case.

This temporary license is much like a roaming license, but with a few important distinctions:

There is no need for a separate enabling license, as is the case with the rlm_roam license for roaming
There are no environment variables involved, rather, there are 2 new API calls to create and revoke the temporary license.
The temporary license can be automatically refreshed when the computer is connected to the internet, without any user (or software) interaction.
The temporary license is a standard RLM license, locked to a special dynamically created rehostable hostid, rather than to an encrypted roam file. This is because, for roaming, you have no control over the license server’s environment, but for temporary licenses, the server is under your control.

In order to create the temporary license, you call the rlm_create_temp_license() API call. To return it early (before expiration), call rlm_return_temp_license() If any temporary license expires, the next call to rlm_create_temp_license() removes them. These calls are described in the Temporary license functions section.

Characteristics of a temporary license

As noted above, the temporary license is a normal RLM license, nodelocked to a dynamically created rehostable hostid. This license utilizes the RLM keywords:

exptime=hh:mm
auto_refresh=refresh parameters (used by RLM only, not visible in the normal client API)

The temporary license is stored in the RLM temporary directory, along with many other RLM files. RLM searches this directory for licenses before it searches any “normal” license files.

A temporary license has the standard RLM expiration date, but in addition, it has an expiration time on that date as well. It also has the auto_refresh parameters which specify how to refresh the license.

Note

The auto_refresh keyword is reserved for RLM use only, and this data will not appear in any normal client-side calls such as rlm_products(), or rlm_license_xxx(). This keyword is not, and will not, be described in the license file section above.

Finally, temporary licenses cannot be created from a token-based license, only from regular base licenses.

ISV control over temporary license creation

Unlike roaming, no external license is required to enable temporary licenses, since you make an explicit call to set up or return the temporary license.

Also, unlike roaming, there is no issue of servers locked to transient hostids, since the server is always an RLM Cloud server. However, you cannot create a temporary license from a failover server, only from a primary server. If you attempt to create a temporary license from a failover server, you will get the RLM_EH_NOTEMP_FAILOVER error.

You should never create more than one temporary license for a product on a system – only one will be usable. In particular, 2 “single” licenses will not allow 2 separate checkouts of the license, so there is no point in creating more than 1 temporary license on a system.

If you attempt to create a temporary license from a checked-out license that did not come from an RLM Cloud server, you will receive the RLM_EH_TEMPFROMCLOUD error - “Temporary licenses come from RLM Cloud servers only” (-187). This will happen, for example, if you check out an already-existing temporary license and then call rlm_create_temp_license() on the checked-out license handle.

If you want to extend the period of the temporary license

You can do this either manually, by calling rlm_remove_temp_license() then rlm_create_temp_license() or let RLM do it automatically for you by setting the auto refresh parameters. If you set auto refresh, then a checkout of the license within the number of minutes before expiration will attempt to refresh the license for the number of minutes to new expiration (from the current time – not an extension of the original expiration).

If you want to return the temporary license early

You do this by calling rlm_checkout() followed by rlm_return_temp_license(). As long as the license is available for checkout, and the software can still access the original server, the return will succeed.

Some additional notes

You cannot create a license which expires later than the license on the license server itself.
The license created will inherit several of the attributes from the floating license on the server:
- version
- options
- contract
- customer
- issuer
- akey
Any other options in the original license are not preserved in the temporary license.
Unlike a roamed license, the license server will attempt to associate this license with any license of the same name, version, and license options string. This means you can replace the license on your RLM Cloud server, and the temporary license will continue to be “checked out” on the server and returnable, as long as the product, version, and options strings are the same. If no license on the server has the same name, version, and options string, the automatic refresh of the license will no longer be successful. You will be able to return it, however this will only remove the license locally, since the server no longer knew about this temporary license.

Tutorial on Temporary Licenses

The code you write to create and revoke temporary licenses is more straightforward than roaming. To create a temporary license, you will check out a license, specify several parameters of the temporary license, and then call rlm_create_temp_license().

Check out the license as you would do normally. The license handle is passed to rlm_create_temp_license() in the RLM_TEMP_HANDLE. In the following example, we create a temporary “single” license valid for 3 days, which will be refreshed on checkout any time after 2 days before expiration. Note that the new license will expire 3 days from the time of refresh, not 3 additional days from the first expiration.

#define HOUR (60)
#define DAY (HOUR * 24)
char *prod = “product_name”;
char *ver = “1.0”;
RLM_HANDLE rh; /* You called rlm_init() earlier */

int
create_temp(RLM_HANDLE rh, char *prod, char *ver)
{
        RLM_LICENSE lic;

        RLM_HANDLE rh;

        int status = 0;

                rh = rlm_init(....);

                if (!rh) return(ERROR);

                lic = rlm_checkout(rh, prod, ver, ...);

                if (!lic) return(ERROR2);

                if (rlm_license_single(lic) || rlm_license_uncounted(lic))

                        return(GOT_NODELOCKED_LICENSE_NO_TEMP_CREATED);

                temp_handle = rlm_temp_new_handle(rh);

                if (!temp_handle) return(ERROR3);

                rlm_temp_set_handle(temp_handle, RLM_TEMP_HANDLE_DURATION, (void
                *) 3*DAY);

                rlm_temp_set_handle(temp_handle, RLM_TEMP_HANDLE_WINDOW,
                (void *) 2*DAY);

                rlm_temp_set_handle(temp_handle, RLM_TEMP_HANDLE_NEW_DURATION,
                (void *) 3*DAY);

                rlm_temp_set_handle(temp_handle, RLM_TEMP_HANDLE_LICENSE, (void *)
                lic);

                status = rlm_create_temp_license(rh, temp_handle);

                rlm_temp_destroy_handle(temp_handle);

                return(status);
}

This license can be returned any time it can be checked out. In other words, it cannot be returned after it expires, but this happens automatically, anyway. This example returns the license created in the earlier example:

lic = rlm_checkout(rh, prod, ver, ...);

status = rlm_remove_temp_license(rh, lic)

In this example, if the temporary license has expired and your checkout is granted a license from the server, the rlm_remove_temp_license() call will return RLM_EH_NOTTEMP (-76).