VLSupdateExt2

Syntax

LS_STATUS_CODE VLSupdateExt2 (LS_HANDLE           lshandle,
                              unsigned long       ulGraceSwitchToNetworkTm,
                              unsigned int        *new_units_reqd,
                              unsigned char       *log_comment,
                              LS_CHALLENGE        *challenge
                              VLSserverInfo       *serverInfo); 	 	 
Argument Data Type Direction Description
lshandle LS_HANDLE IN

The handle previously returned by the corresponding request call.

ulGraceSwitchToNetworkTm unsigned long IN

Unused till version 8.3.x.

Since version 8.4.0, this parameter allows switching from a grace license to a network license . Accordingly, the parameter can have the following values:

>A numeric value between 1 to 54,000, which is the time in seconds. After this time interval, the application looks for a license token on network.

>VLS_GRACE_REMAIN_ON_NONET: When you do not want to allow switching from a grace license to network license (functionality so far and also the default setting).

>LS_DEFAULT_UNITS: Sets the value of ulGraceSwitchToNetwork to 10 minutes.

new_units_reqd unsigned int IN/OUT

Unused till version 9.1.x.

Since v9.2.0, it represents the number of license units that can be obtained from the License Manager while renewing the license.

>From RMS v9.5 onwards, up to 4,294,967,294 licenses units are supported. This is applicable for license version 20 and above.

>If the License Manager has sufficient units to renew as per the refresh call, it will reclaim/release initial requested units and grant new units. In this case, two implicit entries for release and request are created in the usage log.

>If the number of license units available with the License Manager is less than the required number, the LSUpdate call renews the existing number of units only (if any set using the LSRequest call). The value of new_units_reqd is updated with actual tokens requested/granted. Also, the last_status (a field of the lshandle structure) is updated to reflect the reason for failure. Use the VLSgetLastErrorStatusFromHandle API to view the view the last error status.

log_comment unsigned char IN

>If vendor usage data attribute consists of multiple words, each will be anonymized individually, only if they are separated using a space. In general, avoid specifying the same entry (or word) twice in the vendor usage data attribute as the "uniquely" anonymized data will be repeated.

>The spaces in the vendor usage data attribute are replaced with underscores (_). Also, the keyword <an> itself is not anonymized and is replaced by an underscore (_) in the resulting usage log line record.

>To complete the vendor usage data attribute anonymization process, the system administrator must have also allowed anonymity of user information (either by setting the LS_LOG_ANONYMITY environment variable or using the -log-anonymity License Manager start-up option).

challenge LS_CHALLENGE IN/OUT

The challenge structure.

serverInfo VLSserverInfo IN/OUT This information is passed to the License Manager for use in License Manager hook functions. An IN\OUT parameter.

Description

An advanced variant of VLSupdateExt.

This API has been introduced (RMS v9.5) to support license hard limit up to 4,294,967,294 (applicable for license version 20 and above). Further, this high value is applicable only when the hard limit is used as a quantity.

Returns

The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes:

Error Code Description

VLS_CALLING_ERROR

>lshandle is a queued handle. Cannot use VLSupdateExt2 to update a queued handle.

>challenge argument is non-NULL, but cannot be understood.

>The log comment value has exceeded the maximum allowed buffer size. Up to 100 characters are allowed (excluding the null character). If you plan to have only a part of data as anonymized, then use the following formula to calculate the maximum allowed data: 100 bytes = 17x + y, where "x" is the number of words to be anonymized and "y" is the length of the unanonymized data. If you plan to have only anonymized characters in the usage log file, then after the anonymization tag <an>, up to 6 words separated by a space can be included.

>The log comment probably consists of the hash (#) sign in the beginning or end of the string. Also, it should not contain consecutive hash signs.

VLS_NO_LICENSE_GIVEN

Generic error indicating that license was not updated.

LS_LICENSETERMINATED

Default error. Cannot update license because the key lifetime has expired and re-request of the license has failed.

VLS_NO_SUCH_FEATURE

License Manager does not have license that matches requested feature, version and capacity.

LS_NOLICENSESAVAILABLE

All licenses in use.

LS_LICENSE_EXPIRED

License has expired.

VLS_TRIAL_LIC_ EXHAUSTED

Trial license expired or trial license usage exhausted.

VLS_FINGERPRINT_ MISMATCH

Client-locked; locking criteria does not match.

VLS_APP_NODE_LOCKED

Feature is node locked, but the update request was issued from an unauthorized machine.

VLS_CLK_TAMP_FOUND

License Manager has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

VLS_VENDORIDMISMATCH

This error can occur under the following scenarios:

>The vendor of the requesting application does not match with the License vendor.

>The License addition failed due to mismatch among the vendor of the license and vendor of the isolated License Manager.

VLS_INVALID_DOMAIN

The domain of the License Manager is different from that of client.

VLS_NO_SERVER_ RUNNING

License Manager on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with License Manager has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_BAD_SERVER_ MESSAGE

Message returned by License Manager could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_RESOURCE_LOCK_FAILURE Failed to fetch the API resource lock. On receiving this error, retry calling this API.
LS_BADHANDLE The system is low on memory or is in unstable state.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

See Also

>VLS_UPDATE

>VLSbatchUpdate