VLSgetCommuterCode

Obtains a commuter authorization from the License Manager to be passed on to a remote client that does not have network access to the License Manager. This call checks out a commuter authorization for another machine. It requires a commuter locking code string from the VLSgetMachineIDString call used on the remote computer. After successful completion of the call, the authorization code string should be passed on to the remote computer which will use VLSinstallCommuterCode to install the authorization.

If the machine that requires the commuter authorization has network access to the License Manager, then you should not use this call. Instead, check out the license using VLSgetAndInstallCommuterCode, VLSgetAndInstallCommuterCodeExt API. Once a commuter authorization is checked out for a remote computer, it cannot be checked back in until the commuter authorization expires.

Syntax

LS_STATUS_CODE VLSgetCommuterCode (	 	 
unsigned char	 	*feature_name,
unsigned char	 	*feature_version,
unsigned long	 	*units_rqd,
unsigned long	 	*duration,
unsigned long	 	*lock_mask,
unsigned char	 	*log_comment,
unsigned char	 	*machineIDString,
unsigned char	 	*commuter_code,
LS_CHALLENGE	 	*challenge,
VLSserverInfo	 	*requestInfo,
VLSserverInfo	 	*commuterInfo,
unsigned long	 	*extension_in_duration );

Argument	Description
feature_name	The feature name of the license to check out from the License Manager.
feature_version	The feature version of the license to check out from the License Manager.
units_reqd	Number of units required for 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.
duration	Number of days the commuter authorization will last. This value may be superseded by the maximum limit allowed by the license.
lock_mask	The desired locking criteria for the client machine. The value here should be equal to or a subset of the value used by the VLSgetMachineIDString call. This value will return the actual locking criteria used to lock the commuter authorization.
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.
machineIDString	Machine ID string generated by the remote computer desiring the commuter authorization.
commuter_code(OUT)	The actual commuter authorization code. This string should be passed on to the remote computer desiring the commuter authorization for installation.
challenge(IN/OUT)	A challenge and response for the given license on the License Manager. Set to NULL if you are not using this feature.
requestInfo(IN/OUT)	Reserved. Use NULL for this value.
commuterInfo(IN/OUT)	To be used in future for hooks.
extension_in_duration	The additional number of days to extend the duration of an existing remotely checked out commuter license (can be termed as "commuting a remote extension token"). However, pass this as NULL under the following scenarios: >If you are checking out a remote commuter license for first time for a feature. > If the checked out remote commuter license is lost. Similarly, when an extension token is being commuted, non-applicable parameters (like, units required, duration, and so on) will be ignored.

Returns

The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for the failure. Possible error codes that can be returned by this call include VLS_INVALID_MACHINEID_STRING and VLS_OPERATION_NOT_ALLOWED_AFTER_DEFERRED_REVOCATION.

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