VLSqueuedRequest

int	 	       VLSqueuedRequest(
unsigned char	 	*license_system,
unsigned char	 	*publisher_name,
unsigned char	 	*product_name,
unsigned char)	 	*version,
unsigned long	 	*units_reqd,
unsigned char	 	*log_comment,
LS_CHALLENGE	 	*challenge,
LS_HANDLE	 	*lshandle,
VLSqueuePreference	*qPreference,
int	 		*requestFlag);

Argument	Description
license_system	A license requested in the system. Pointer to the string which uniquely identifies a particular license system.
publisher_name	Refers to the name of the publisher (manufacturer) of the product. Cannot be NULL and must be unique. It is recommended that a company name and trademark be used.
product_name	Feature name. The name of the product requesting licensing resources. Cannot be NULL and must be unique.
version	Version for which licenses are requested. Must be unique for the associated feature
units_reqd	>Number of units requested to run the license. The license system verifies that the requested number of units exists and it is possible to reserve those units, but no units are actually consumed at this time. The default is 1, and this value is used if a NULL value is passed. >From RMS v9.5 onwards, up to 4,294,967,294 licenses units are 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).
challenge	Pointer to a challenge structure. The challenge-response will also be returned.
lshandle	Handle to the license which the user has requested. If the user has successfully received the license, the status of the handle is VLS_ACTIVE_HANDLE. Otherwise, the client is put in the queue and the status of the handle is VLS_QUEUED_HANDLE.
qPreference	Pointer to the VLSqueuePreference structure, which is used to specify the client’s preference for how it wishes to be placed in the queue. After the call is made, the structure contains the values assigned by the License Manager when it has placed the client in the queue.
requestFlag	Valid values are: >VLS_REQ_GET - specifies a non-queuing request (without queuing the client). If license is not available, client will not be queued. >VLS_REQ_QUEUE - specifies to queue the client (without returning with the license). Even if license is available, client will be queued. If both are specified, the client requests the License Manager to issue the license, if available, otherwise to queue the client. Upon return from this API, this parameter will be set to either VLS_REQ_GET (specifying the license has been granted) or, VLS_REQ_QUEUE (specifying that the client has been queued).

Description

The call provides a mechanism to the calling application to ask the License Manager to grant a license if available. If no license is available, the client will be queued. The client can call VLSupdateQueuedClient to inquire if a license is available. Once a license is available, the client can call VLSgetQueuedLicense to obtain the license.

In response, the License Manager will either issue the license token when (and if) the license is available, put the client in the queue when the license is not available, or issue an appropriate error message, which describes the cause for not being able to service the request.

The client will pass the following information to the License Manager:

>Time in seconds for the client to wait in the queue for the license.

>Time in seconds for the License Manager to hold the license once it becomes available.

>Priority relative to other clients.

>The maximum position within the queue before which the client can be queued.

>The maximum position within the group queue, before which the client can be queued.

Notice that the LS_MAX_QLEN environment variable can override the qPreference structure. The end-user can put a limit on the maximum size of the queue by defining the LS_MAX_QLEN environment variable. This variable depends upon the availability of memory resources. The different values of LS_MAX_QLEN are:

>LS_MAX_QLEN not set. Client preference is applied.

>LS_MAX_QLEN = -1. Client preference is ignored and the client is always queued.

>LS_MAX_QLEN = 0. Queue is disabled and no clients will be put in the queue.

>LS_MAX_QLEN > 0. Overrides the client’s preference.

Similarly variable LS_MAX_GRP_QLEN will override the setting of the max group wait time in the qPreference structure.

Variables LS_MAX_WAIT_SEC and LS_MAX_HOLD_SEC override the max wait time and max hold time elements of the qPreference structure.

Returns

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

Error Code	Description
VLS_CALLING_ERROR	>request_flag specifies queuing but qPreference is NULL. >lshandle is NULL. >challenge argument is non-NULL, but cannot be understood. >publisherName is NULL >The log comment value has exceeded the maximum allowed buffer size. >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. >The log comment value has exceeded the maximum allowed buffer size. Up to 50 characters are allowed (excluding the null character). If you plan to have only anonymized characters in the usage log file, then after the anonymization tag <an>, up to 3 words separated by a space can be included. If you plan to have only a part of data as anonymized, then use the following formula to calculate the maximum allowed data: 50 bytes = 17x + y, where "x" is the number of words to be anonymized and "y" is the length of the unanonymized data. >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_APP_UNNAMED	>product_name is NULL >version is NULL
VLS_NO_LICENSE_GIVEN	>units_reqd is zero. >Invalid handle specified. >Generic error indicating that the license is not granted.
LS_NOLICENSESAVAILABLE	All licenses in use.
LS_INSUFFICIENTUNITS	License Manager does not currently have sufficient licensing units for the requested feature to grant a license.
VLS_NO_SUCH_FEATURE	License Manager does not have a license that matches requested feature, version and capacity.
LS_LICENSE_EXPIRED	License has expired.
VLS_NOMORE_QUEUE_RESOURCES	Queue is full.
VLS_APP_NODE_LOCKED	Requested feature is node locked, but request was issued from an unauthorized machine.
VLS_USER_EXCLUDED	User or machine excluded from accessing requested feature.
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	The vendor identification of the requesting application does not match the vendor identification of the feature for which the License Manager has the license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.
VLS_TRIAL_LIC_EXHAUSTED	Trial license has expired.
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 is specified.
VLS_NO_SERVER_FILE	The License Manager has not been set and is unable to determine which License Manager to use.
VLS_BAD_SERVER_MESSAGE	Message returned by the License Manager could not be understood.
LS_NO_NETWORK	Generic error indicating that the network is unavailable for servicing the license operation.
VLS_NON_REDUNDANT_ SRVR	License Manager is non-redundant and therefore cannot support this redundancy-related operation.
VLS_SERVER_SYNC_IN_ PROGRESS	License Manager synchronization in process.
VLS_FEATURE_INACTIVE	Feature is inactive on specified License Manager.
VLS_MAJORITY_RULE_ FAILURE	Majority rule failure prevents token from being issued.
LS_NORESOURCES	An error occurred in attempting to allocate memory needed by this function.

For the complete list of the error codes, refer to Licensing Library Error and Result Codes.