LM_LOGIN

xcall lm_login(app_stat, producer, app_code, token, lm_record, slot_num, [check] 
&     [, seat])

Arguments

app_stat

Returned with the log-in status. The most common values are listed below; see Licensing Toolkit error messages for additional values that can be returned. (n)

0 = Operation was successful.

1 = Product is not licensed.

2 = Concurrent user maximum reached.

7 = Product demo has expired.

producer

The producer code for your company. (This code was assigned to your company by Synergex when you requested the License Key Generator.) (a)

app_code

The code that you created to refer to the application or application component. It can be up to six characters long. (a)

token

Returned with the log-in token, which is a key that is maintained in License Manager. (i4)

lm_record

(optional in traditional Synergy and on UNIX) Returned with the information that was specified when the application code was installed by License Manager: (a)

lm_applic   ,a6     ;Application code
lm_usrmax   ,d5     ;Maximum number of concurrent users
lm_expdat   ,d8     ;Time-out date (YYYYMMDD)
lm_insdat   ,d8     ;Installation date (YYYYMMDD) 
lm_custom   ,a100   ;Developer-defined information

slot_num

(optional in traditional Synergy and on UNIX) Returned with the slot number, which ranges from 1 to the number of users for which the product is licensed. Slots are used as they become available; consequently, the slot number will not necessarily tell you the current number of users. (n)

check

(optional) One of the following options: (n)

0 = Log in the license if it is available. (default)

1 = Check whether the license is available.

2 = Check whether the license is installed.

3 = Log in the license if it is installed.

Passing anything other than 0, 1, 2, or 3 is the same as passing 1.

An available license indicates either that the license is installed or that the 14-day grace period is in effect. When check is 1 or 2, License Manager only checks on the license; it does not request a license log-in, and so a slot is not taken and the concurrent number of users is not incremented. See the Discussion for details.

seat

(optional) A 32-bit integer set to 0 (zero) or the value designated to represent the seat. (i)

Discussion

LM_LOGIN requests that License Manager either log in a license “slot” for the specified application code or perform a license “check.” If the license is installed, information about it is returned in lm_record.

For security reasons, we recommend that you encode the strings for producer code and application code in your routines.

When check is 0 (or not passed), if the license is installed and a slot is available, LM_LOGIN returns a token. If the license is not installed, but the 14-day grace period is in effect, LM_LOGIN returns success (0) and a token of 0. In this case, no license slot is consumed, and so a log-out is not required. If the 14-day grace period has expired (and the license has not been installed), LM_LOGIN returns failure (1).

When check is 1, if the license is installed or the 14-day grace period is in effect, LM_LOGIN returns success (0) and a token of 0. If the 14-day grace period has expired (and the license has not been installed), LM_LOGIN returns failure (1).

When check is 2, if the license is installed, LM_LOGIN returns success (0) and a token of 0. Any other condition returns failure (1).

When check is 3, if the license is installed and a slot is available, LM_LOGIN returns success (0) and a token. If the 14-day grace period is in effect, LM_LOGIN returns failure (1).

The token returned by LM_LOGIN should be saved by your application and used in the call to LM_LOGOUT. License Manager will only recognize log-outs with a matching token. You need to retain the token only while the license is logged in because a token has meaning only for the log-in for which it was obtained.

When using the seat argument, the value you should pass depends on the type of application:

For a stand-alone application, where the user is running the application interactively from the same workstation that the user is logged in to, pass 0 for seat or just don’t pass seat at all. (All licenses logged in and out are based on the workstation being the seat.)
In a server environment, where there are multiple processes running on the same machine (such as an xfNetLink – xfServerPlus application), you will need to decide how a “seat” should be represented within your application. Seat can be any 32-bit integer. The seat should be unique among seats, but the same for each instance of a particular seat. For example, you may want to use the client’s IP address. Each license taken by the same seat for the same application code will be shared. In a server environment, you must include the seat to log out the correct license.

The status value returned by LM_LOGIN in app_stat is for checking success or providing application-related license error messages. This value has no effect on your application; you must write code to handle the returned status. For example, if LM_LOGIN returns 2 (concurrent user maximum reached), you could deny the user access to your application and present an error message stating the problem. You can access system error codes with %SYSERR, which may assist in troubleshooting.

Examples

See lm_auth.dbl in Licensing_TK_Examples.zip, available from Synergy CodeExchange in the Resource Center on the Synergex website.