VLSgetAndInstallCommuterCodeExt

Syntax

int VLSgetAndInstallCommuterCodeExt (	 	 
unsigned char	 	*feature_name,
unsigned char	 	*feature_version,
unsigned int	 	*units_reqd,
unsigned int	 	*duration,
unsigned int	 	*lock_mask,
unsigned char	 	*log_comment,
LS_CHALLENGE	 	*challenge );

Argument	Description
feature_name	Name of the feature.
feature_version	Version of the feature.
units_reqd	Number of units required to run the license. The license system verifies that the requested number of units exist and may reserve those units. The available number of units is returned. If the number of licenses available with the License Manager is less than the requested number, the number of available licenses will be returned using unitsReqd. If unitsReqd is NULL, VLS_CALLING_ERROR will be returned. From RMS v9.5 onwards, license hard limit up to 4,294,967,294 is supported. This is applicable for license version 20 and above.
duration(IN/OUT)	Displays the number of days for which the license has to be checked out. Specify zero (0) for unlimited check-out. If the remaining number of days available is less than the requested days, then the duration parameter will be ignored and the License Manager will issue the commuter authorization for the remaining number of days. The License Manager will never issue the commuter authorization beyond the birth and death date of the license. The start date of the commuter authorization is based on the client system’s time and not that of the License Manager. From RMS v9.5 onwards, license hard limit up to 4,294,967,294 is supported. This is applicable for license version 20 and above.
lock_mask(IN/OUT)	Mask defining which fields are to be used for locking. On entry, lock_mask specifies the locking criteria that should be used for looking the commuter code. If a zero is given, the API will lock the code to disk ID (Windows), otherwise it will lock to host name. Notice, the API will replace the zero with lock_mask for Disk ID or host name before sending this value to the License Manager. From RMS v9.5 onwards, license hard limit up to 4,294,967,294 is supported. This is applicable for license version 20 and above.
log_comment	>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). The API truncates the log comment in the following case: >The log comment value, when the <an> tag is not used, has exceeded the maximum allowed buffer size. Up to 100 characters are allowed (excluding the null character). In the following cases, VLS_CALLING_ERROR is returned: >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. >The log comment value, when the <an> tag is used, has exceeded the maximum allowed buffer size obtained using the following guidelines. 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.
challenge(IN/OUT)	The challenge-response for this operation. Pointer to a challenge structure. The challenge-response will also be returned in this structure.

Description

Obtains the commuter code from the License Manager and installs the standalone commuter authorization at the client.

Before calling VLSgetAndInstallCommuterCodeExt API, the VLSgetMachineID function must be called in order to obtain the supported lock masks, which are passed in the lock_mask parameter.

VLSgetAndInstallCommuterCodeExt can also be used for the explicit check-out of a repository license.

NOTE 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 VLS_SUCCESS is returned if successful. Otherwise, it will return the following error codes:

Error Code	Description
VLS_CALLING_ERROR	>duration is NULL >lock_mask is NULL >unitsReqd is NULL >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_UNABLE_TO_INSTALL_COMMUTER_CODE	Could not install the checked out commuter license code on the target computer.
VLS_OPERATION_NOT_ALLOWED_AFTER_DEFERRED_REVOCATION	Commuter token check out and repository license request are not allowed after the deferred revocation operation has already been performed for the given feature-version. This cannot be done for the feature-version until all its licenses scheduled for revocation are revoked.

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