Retrieve License Information (QLZARTV) API

The Retrieve License Information (QLZARTV) API returns license information about a software product. The license information returned depends on the format specified.

• The LICR0100 format retrieves basic license information.
• The LICR0200 format retrieves basic license information, detailed license information, and the list of current license users.
• The LICR0300 format retrieves basic license information, detailed license information, the list of current license users, and additional information about the license users.

Authorities and Locks

Public API Authority

*USE

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable to receive the requested license information.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.

Format name for receiver variable

INPUT; CHAR(8)

The name of the format that identifies the type of license information to be retrieved. The supported formats are:

LICR0100

Basic license information is retrieved. For more information, see LICR0100 Format.

LICR0200

Basic license information is retrieved along with detailed license information and license user information. For more information, see LICR0200 Format.

LICR0300

Basic license information is retrieved along with detailed license information and multiple-use license user information. For more information, see LICR0300 Format.

Product identification

INPUT; CHAR(*)

Information that uniquely identifies the product or feature whose license information will be retrieved. The structure of this information is determined by the name of the format.

Product identification format name

INPUT; CHAR(8)

The name of the format that describes the product identification. The only format name supported is:

LICP0100

See LICP0100 Format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

LICP0100 Format

LICR0100 Format

LICR0200 Format

LICR0300 Format

Field Descriptions

Bytes returned. The number of bytes of data returned.

Compliance type. The compliance type associated with this license. The compliance type determines the action taken when the value of the usage limit field is exceeded. The valid values are:

01

The usage limit cannot be exceeded. The user who attempts to use the product or feature after the usage limit has been reached is prevented from accessing it. The product or feature cannot be accessed until the appropriate action is taken to increase the usage limit of it. A message indicating an attempt was made to exceed the usage limit is sent to each of the following:

• The QSYSOPR message queue
• The message queues specified on the Change License Information (CHGLICINF) command.

02

The user who attempts to use the product or feature after the usage limit has been reached is allowed access. A warning message indicating the usage limit is exceeded is sent to QSYSOPR and to the message queues specified on the Change License Information (CHGLICINF) command.

03

To use a product or feature with keyed compliance, the license must be installed using one of the following:

• A valid license key through the Add License Key Information (ADDLICKEY) command.
• The Add License Key Information (QLZAADDK) API.

This license key is provided by the software provider. The key ties the usage limit to the particular product or feature and to a particular system serial number. To change the usage limit, a user must get a new key from the software vendor. A user can use the product or feature after the usage limit is reached. However, the user is allowed access to the product or feature for only the number of days contained in the product's grace period. Once the grace period has expired, no users over the usage limit are able to use the product or feature until one of the following happens:

• A new license key is received from the software provider.
• The number of users fall below the usage limit.

A warning message indicating that the usage limit has been exceeded is sent to each of the following:

• The QSYSOPR message queue.
• The message queues specified on the CHGLICINF command.

9999999

This value indicates no grace period or that the grace period has expired.

CYYMMDD

The date the grace period expires. C is the century, YY is the year, MM is the month, and DD is the day. The date must be numeric as follows:

• Century, where 0 indicates years 19xx and 1 indicates years 20xx.
• Month may not be greater than 12.
• Day may not be greater than 31.

CYYMMDD

C is the century, YY is the year, MM is the month, and DD is the day. The date must be numeric as follows:

• Century, where 0 indicates years 19xx and 1 indicates years 20xx.
• Month may not be greater than 12.
• Day may not be greater than 31.

9999999

The license does not have an expiration date.

Grace period. The number of days after a product first exceeds its usage limit that a user has to obtain a new license key. Before the grace period expires, a new license key needs to be obtained from the software vendor. If this is not done, users exceeding the usage limit are not allowed access to the product or feature. The date the grace period expires is calculated by adding the number of days in the grace period to the current date.

Length of each current license user record. The length of each current license user record. This is the length of the license user plus the length of any additional license user information.

Length of each license user. The length of each license user. This is the same value that is used during the request and release of this product. This may be a value of 1 through 80.

License term. The extent of time the authorized usage limit for a product lasts. Each time a new license term is installed for a product, the authorized usage limit must be set by doing each of the following:

• Obtaining a new license key.
• Using the Add License Key Information (ADDLICKEY) command.

Vx

The authorized usage limit is valid only for the entire version of the product or feature.

VxRy

The authorized usage limit is valid only for the entire release of the product or feature.

VxRyMz

The authorized usage limit is valid only for the modification level of the product.

License user. A user that currently holds one or more uses of the product or feature.

List of current license users. A list of all the current users of the product.

Message queue library name. The library where the message queue resides.

Message queue name. The name of message queue.

Number of current license users. The number of current license users in the list.

Number of message queues. The number of message queues in the list.

Number of uses held. The number of license uses held by this license user.

Offset to current license user list. The offset from the beginning of the receiver variable to the start of the first current license user. This offset is 0 if there are no license users or if the size of the receiver variable is not large enough to hold any license users.

Offset to message queue list. The offset from the beginning of the receiver variable to the start of the first message queue name and library. This offset is 0 if there are no message queues or if the size of the receiver variable is not large enough to hold any message queues.

Peak usage. The maximum number of license users that have accessed the product or feature at one time. The peak usage may be reset using option 10 of the Work License Information (WRKLICINF) command.

Processor group. The processor group of this system. A processor group is the grouping of system model numbers by relative processor size.

Product ID. The product ID of the product or feature whose license information is to be retrieved.

Product license information handle. The product information handle is passed back. It may be used within the application to verify that the product attributes are the same as the original license information created by the software provider. This handle will not be stored and will be generated each time license information is retrieved.

Release level. The version, release, and modification level of the product whose license information was requested. This is returned in the receiver variable parameter. If you specified *ONLY in the release field of the LICP0100 format, the actual release level is returned here.

Reserved. If this field is input, character fields must be set to blanks and binary fields must be set to hexadecimal zeros.

Threshold value. The threshold for this product or feature.

The threshold indicates you want a message sent to the system operator message queue stating that a product or feature is reaching the usage limit.

-1

The threshold value is *NOMAX.

0-999999

The threshold value.

Usage limit. The usage limit for this license.

-1

Any number of users are allowed to access the product or feature.

0-999999

The number of users allowed to access the product.

01

The usage type is concurrent. It is for the number of unique jobs accessing the product at one time.

02

The usage type is registered. It is for the number of unique license users registered by the product.

Error Messages

CPF0C1C E

Release level &1 not valid.

CPF0C1E E

Error occurred during running of &1 API.

CPF2206 E

User needs authority to do requested function on object.

CPF2207 E

Not authorized to use object &1 in library &3 type *&2.

CPF24B4 E

Severe error while addressing parameter list.

CPF3CF1 E

Error code parameter not valid.

CPF3C21 E

Format name &1 is not valid.

CPF3C24 E

Length of the receiver variable is not valid.

CPF3C90 E

Literal value cannot be changed.

CPF9E11 E

License information not retrieved.

CPF9E13 E

More than one release found.

CPF9E15 E

Error in license management function.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.