ECLiPSe Runtime Subset and Licensing Issues

Scope: This note applies to ECLiPSe 5.2, Build #35 and later.
Author: Joachim Schimpf, IC-Parc
Date: 2001-10-28
Caution: inconsistent spelling of license/licence in different contexts!

Packaging Scheme

ECLiPSe is being distributed as a set of gzipped tar files. The supported architectures are currently:
 
sun4 SunOS 4 (being phased out)
sparc_sunos5 SunOS 5 (tested on 5.5 and 5.7)
i386_linux Intel x86 Linux
i386_nt Windows 95,98,2000,NT4
alpha_linux 64-bit Alpha Linux

Fore each of the architectures, there is the following set of packages (except that not all CPLEX/XPRESS interfaces are available on allarchitectures):
 
eclipse_basic.tgz alternative ECLiPSe development system (flexlm-related predicates are dummy and fail always)
eclipse_rt.tgz alternative ECLiPSe runtime subset (a subset of eclipse_basic) plus flexlm functionality
eclipse_misc.tgz optional Public domain libraries, probably not relevant for PT
eclipse_doc_online.tgz optional Documentation in html format
eclipse_doc_print.tgz optional Documentation in pdf format (does not include Reference Manual)
if_cplex65.tgz optional Interface to CPLEX 6.5 with CPLEX statically linked (requires development license)
if_cplex71.tgz optional Interface to CPLEX 7.1 with CPLEX statically linked (requires runtime or development license)
if_xpress12.tgz optional Interface to XPRESS 12.20 (requires development license)
if_xpress1250.tgz optional Interface to XPRESS 12.50 (requires development license)
if_xpress12parcrisk.tgz optional Interface to XPRESS 12.20 (requires intialisation with 'parcrisk' runtime key or development license)

Installing a development system:

  1. Unpack eclipse_basic
  2. Only if you need the FlexLM functionality to be operational, unpack eclipse_rt as well
  3. Unpack eclipse_doc_online and eclipse_doc_print
  4. Unpack the if_xxx interfaces that you want to use for your development (if you install more than one, you will have to resolve ambiguities later, see below)
  5. Execute the RUNME script (on Unix) or the ecl_inst.tcl script (on Windows) as explained in the README file.
Installing a deployment system:
  1. Unpack eclipse_rt
  2. Unpack one of the if_xxx interfaces, e.g. if_xpress12parcrisk for Riskwise
  3. If eclipse is used in embedded form, no further installation should be needed. Otherwise some registry entries and/or environment variables may need to be set, see README and Embedding Manual.

Runtime Subset

The ECLiPSe runtime subset is contained in the package eclipse_rt.tgz. This subset does not contain: This means that you cannot get an "Eclipse prompt" with this subset. It can only be used

FlexLM licensing

The ECLiPSe-API for the FlexLM licensing functionality is described in Reference Manual/Non-public libraries/flexlm. It consists of the four predicates:
 
licence_checkin(?Feature)
Check in a FlexLM licence
licence_checkout(+Feature, ++Policy, +Version, +Path, -Message, -Status)
Check out a licenced feature from FlexLM
licence_heartbeat(+Feature, +Minutes, -Reconnects, -FailedReconnects)
Refresh a checked out FlexLM licence
licence_held(+Feature)
Check whether we already have a licence for a particular feature

This functionality is only operational in the runtime subset. An ECLiPSe development system by default contains only a dummy implementation of this API, which behaves as if there were no licenses available at all, i.e. licence_checkout/6 returns with Status=error and Message="ECLiPSe licence check failed", licence_checkin/1 always succeeds, and licence_heartbeat/4 and licence_held/1 always fail.

To create a development environment with operational FlexLM licensing functionality, simply unpack both packages eclipse_basic.tgz and eclipse_rt.tgz into the same location.

Eplex Library (interface to CPLEX and XPRESS-MP)

The ECLiPSe library eplex is an interface between ECLiPSe and a third-party LP/MIP solver (currently supported are CPLEX and XPRESS-MP in various versions). The interface hides the differences between those solvers from the ECLiPSe programmer. However, the interface needs to be ported or at least rebuilt for every new release of the third-party solver. That's why the distribution contains several variants of if_xpress and if_cplex packages. They all implement the same functionality on the ECLiPSe side, but contain different versions of the solver. In addition, these solvers usually require a license to run.

Loading the library

Within ECLiPSe code, the use of the eplex library should normally be specified in generic form as 
:- lib(eplex).
If only one variant of the library is installed (i.e. only a single if_cplex or if_xpress package has been unpacked), then this one gets loaded by ECLiPSe. This should normally be the case for a runtime installation of ECLiPSe.

Selecting a particular library variant (development systems mainly)

If an ECLiPSe installation has several variants of eplex installed, the ambiguity must be resolved. This can be done by specifically requesting a CPLEX or an XPRESS-MP variant by using either of the following: 
:- lib(eplex_xpress).
:- lib(eplex_cplex).
If this is still ambiguous (e.g. different versions installed), ECLiPSe will pick an arbitrary one.

A further way to select a particular solver is to make an entry in the eplex_lic_info.ecl file, which is located in the lib subdirectory of the ECLiPSe installation. This method is only recommended for development installations. The file contains entries of the form: 

    licence(Hostname, Solver, Version, LicStr, LicNum).
e.g. 
    licence('breeze.icparc.ic.ac.uk', cplex, '65', '', 0).
which specifies that on the given machine the if_cplex65 version of the interface should be used (the last two arguments will be passed to lp_get_license/2 when ECLiPSe tries to obtain a license for the solver, see below). A default entry is written by giving an ECLiPSe variable in place of the machine name, e.g. 
    licence(_Default, xpress, '12', default, 0).
This line will match any machine and select if_xpress12 and expect XPRESS licensing information in a default location. Whenever an eplex_lic_info.ecl file is present, ECLiPSe will load the solver variant that corresponds to the first matching line in that file.

After loading the eplex library, it tries to obtain a license immediately by implicitly calling lp_get_license/0. lp_get_license/0 calls lp_get_license/2 with the arguments being the last two arguments of the matching line in eplex_lic_info.ecl. Failure to obtain a license is not fatal (a warning may be printed), a license can always be obtained subsequently using lp_get_license/2.

Obtaining a development license for CPLEX >= 7.1

CPLEX 7 uses the ILOG license manager (ilm). You need to have a license file either in the default location /ilog/ilm/access.ilm, or in another location, in which case you need to set the environment variable ILOG_LICENSE_FILE to the absolute pathname of that file. For TOKEN type licenses, you also need to have a license demon (ilmd) running. With this setup, ECLiPSe needs no further information, and you can get a license by simply calling 
    :- lp_get_license('', 0).
or by making an entry in the eplex_lic_info.ecl file (see above) with the last two arguments being '' and 0, i.e. 
    licence(..., ..., ..., '', 0).
The license will then be automatically obtained when the library gets loaded or when you call lp_get_license/0.

Obtaining a development license for XPRESS-MP

XPRESS-MP uses a license file called xpress.pwd and possibly a dongle on Windows machines. There is a default xpress.pwd file which is included in the if_xpress package. This default file allows to use a restricted "student version" of  XPRESS-MP, and it is also sufficient if you have a dongle plugged into your Windows machine. Otherwise, the location of the proper xpress.pwd file must be specified explicitly as an argument, or it can be given in the XPRESS environment variable.

For using the student version, or if you have a dongle, use 

    :- lp_get_license(default, 0).
For using an xpress.pwd file in the directory /my/pwd/location, use 
    :- lp_get_license('/my/pwd/location', 0).
If you want the value of the XPRESS environment variable to be used instead, give an empty string, i.e. 
    :- lp_get_license('', 0).
In all three cases, you can alternatively make an entry in the eplex_lic_info.ecl file with the last two arguments corresponding to the arguments of lp_get_license_info/2. The license will then be automatically obtained when the library gets loaded or when you call lp_get_license/0.

Obtaining a runtime license for CPLEX >= 7.1

This should work as follows, but it is an untested example since we don't have such a RUNTIME license yet: 
:- lib(eplex).

:-  ( lp_get_license("LICENSE parctechnologies-london\nRUNTIME CPLEX ...", 9999999) ->
        true                            % got a runtime license
    ; lp_get_license ->
        true                            % got a development license
    ;
        writeln(error, "No license"),   % got nothing
        abort
    ).
lp_get_license/2 gets called with a license string and a number which is the signature for the string.

Obtaining the Riskwise VAR license for XPRESS-MP

XPRESS-MP uses a challenge-response scheme for its VAR (value added reseller) licenses. The VAR version for XPRESS-MP generates a random number, the ECLiPSe code has to apply a magic formula to it and pass the result back. For Riskwise, the ECLiPSe code should look as follows: 
:- lib(eplex).

:-  (
        ( lp_get_license_challenge(N) ->
            Response is 90057741 - (N*N)//19,
            lp_get_license("", Response)        % get runtime license
        ;
            lp_get_license                      % try development license
        )
    ->
        true                                    % got it
    ;
        writeln(error, "No license"),
        abort
    ).
Note that lp_get_license_challenge/1 will succeed for VAR versions of XPRESS-MP (e.g. if_xpress12parcrisk) and fail for non-VAR versions (e.g. if_xpress12). You can therefore write the code such that it works for both.

Completely generic code

Unfortunately the differences in licensing between CPLEX and XPRESS-MP cannot be completely hidden by the eplex library. But you can use lp_get/2 to write completely generic code as follows: 
:- lib(eplex).

:-  ( lp_get(optimizer, xpress) ->
        ... code to get XPRESS-MP license ...
    ; lp_get(optimizer, cplex) ->
        ... code to get CPLEX license ...
    ;
        abort    % should not occur
    ).