LM_LOGIN

Log in and return a unique token and configuration information

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX

 

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

Arguments

app_stat

Returned with the log‑in status. The most common ones are listed below; see the Licensing Toolkit Error Codes table for additional codes that could be returned. (n)

0 = Product has been configured or a license is available.

1 = Product has not been configured.

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)

application

The code that you created to refer to the application. 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 was configured with License Manager: (a)

lm_applic   ,a6     ;Application code
lm_usrmax   ,d4     ;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 configured. 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:

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

1 = Check whether the license is available.

2 = Check whether the license is configured.

3 = Log in the license if it is configured.

Passing anything other than 0, 1, 2, or 3 is the same as passing 1. An available license indicates either that the license is configured or that the 14‑day evaluation period is in effect. When check is 1 or 2, License Manager only checks on the license; it does not request a log‑in slot and so the concurrent number of users is not incremented. See the Discussion for details. (n)

seat

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

Discussion

The LM_LOGIN subroutine requests a log‑in “slot” from License Manager for the specified application or performs a license check, and then returns configuration information about the log‑in.

Tip

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), the call to LM_LOGIN returns a token if the license is configured and a slot is available. If the license is not configured, but the 14‑day evaluation period is in effect, the call returns success (0) and a token of 0. In this case, no license is consumed, and so a log‑out is not required. If the 14‑day evaluation period has expired (and the license has not been configured), the call returns failure (1).

When check is 1, if the license is configured or if the 14‑day evaluation period is in effect, the call to LM_LOGIN returns success (0) and a token of 0. If the 14‑day evaluation period has expired, the call returns failure (1).

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

When check is 3, the call to LM_LOGIN returns a token if the license is configured and a slot is available, but if the 14‑day evaluation period is in effect, the call 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, as 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:

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.