VLScreateUsageLogBackupFile

Syntax

LS_STATUS_CODE 	VLScreateUsageLogBackupFile  (
char	 	*hostName,
int	 	*backUpCreationStatus );

Argument	Type	Direction	Description
hostName	char	IN	The host name or IP address of the computer hosting the License Manager that is using the log file.
backUpCreationStatus	int	OUT	Indicates the Usage Log Backup (ULB) creation status on the License Manager host. It can be any of the following: >ULB_INITIATED - For internal use only. >ULB_IN_PROGRESS – The backup file creation process is in progress. >ULB_COMPLETE – The backup file creation process has been completed. >ULB_RECENTLY_CREATED - The backup creation process has completed recently and all clients are trying to create/query the backup file. The status code will be issued within the 15 minutes of the completion of this task. >ULB_ERROR - An error is encountered in the backup file creation process. The return code of the API would provide exact reason for the error to the user.

Argument

Type

Direction

Description

hostName

char

The host name or IP address of the computer hosting the License Manager that is using the log file.

backUpCreationStatus

int

OUT

Indicates the Usage Log Backup (ULB) creation status on the License Manager host. It can be any of the following:

>ULB_INITIATED - For internal use only.

>ULB_IN_PROGRESS – The backup file creation process is in progress.

>ULB_COMPLETE – The backup file creation process has been completed.

>ULB_RECENTLY_CREATED - The backup creation process has completed recently and all clients are trying to create/query the backup file. The status code will be issued within the 15 minutes of the completion of this task.

>ULB_ERROR - An error is encountered in the backup file creation process. The return code of the API would provide exact reason for the error to the user.

Description

Creates a backup file of the usage log file currently being written at the hostname specified. This change can be done while the file is being used.

As of now, the system administrator controls the size of the usage log file (using the -z command-line option). Once the maximum size is reached, the contents of the current log file will be saved into a backup file unless the no-backup -x option has been explicitly used. By calling this API, you can create the backup of the usage log file currently being written regardless of the file size value given in the –z option. For example, if the API is called when the License Manager has the following usage log files: usage.log.00, usage.log.01. In this case, the backup file will be created with the name usage.log.02. This back up file will have dummy “release” entries for all the active licenses/clients (if any). Similarly, the next usage.log will have dummy “request” entries for all the active licenses.

API Usage Notes

>The API is available with network and integrated RMS licensing libraries only. It is not available with the standalone (no-net) libraries and will return error VLS_NOT_SUPPORTED_IN_NONET_LIBRARY, if called.

>In order to check the progress of the backup file creation, call this API again until status ULB_COMPLETED or ULB_ERROR is received. However, to initiate the backup file creation again, a gap of at least 15 minutes (after status ‘ULB_COMPLETED’ is received from the License Manager) must be maintained between two consecutive API calls.

>In the case status is ULB_ERROR, return code of the API should be diagnosed to check the cause of error occurred on the License Manager side.

Returns

The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure.

Error Code	Description
VLS_NOT_SUPPORTED_IN_NONET_LIBRARY	The API is called from standalone (no-net) library or the hostname is set to “no-net”.
VLS_NOT_SUPPORTED	The API call is directed to the License Manager having version earlier than 8.5.3.x (Windows) or 8.6.0.x (UNIX).
VLS_BAD_SERVER_MESSAGE	Message from License Manager could not be understood.
VLS_NO_SERVER_ RUNNING	License Manager on specified host is not available for processing the license operation requests. However, when the API returns error code 5 ( VLS_NO_SERVER_RUNNING) and backUpCreationStatus as ULB_IN_PROGRESS, then this error code should be ignored. This can happen when client requests the status (via a successive API call ) but the License Manager is busy creating backup (probably because it has many active/open client handles). As a result, the client request may have timed out and status ULB_IN_PROGRESS is reported. Furthermore, if this behavior is observed for more than 15 minutes, then client starts receiving ULB_ERROR (possibly when the client has lost communication with the Licenses Manager, after the latter successfully catered to the 1st API call).
VLS_NO_SERVER_ RESPONSE	Communication with License Manager has timed out.
LS_NO_NETWORK	Generic error indicating that the network is unavailable for servicing the license operation.
VLS_HOST_UNKNOWN	Invalid hostName is specified.
LS_NORESOURCES	An error occurred in attempting to allocate memory needed by function.
VLS_FILE_OPEN_ERROR	The License Manager fails to open/rename the log file.
VLS_USAGE_LOG_BACKUP_DISABLED	-x command-line option is used to disable usage log backup when the maximum size is reached.

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