Retrieve License Information (QLZARTV) API

Required Parameter Group:

1	Receiver variable	Output	Char(*)
2	Length of receiver variable	Input	Binary(4)
3	Format name for receiver variable	Input	Char(8)
4	Product identification	Input	Char(*)
5	Product identification format name	Input	Char(8)
6	Error code	I/O	Char(*)

Default Public Authority: *USE

Threadsafe: No

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

The following table describes the format name supported for the format for product identification parameter. The format identifies the product or feature whose license information is to be retrieved. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(7)	Product ID
7	7	CHAR(6)	Release level
13	D	CHAR(4)	Feature

LICR0100 Format

The following describes the format of the license information returned in the receiver variable parameter. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Usage limit
4	4	BINARY(4)	Usage count
8	8	CHAR(2)	Usage type
10	A	CHAR(2)	Compliance type
12	C	CHAR(6)	License term
18	12	CHAR(6)	Release level

LICR0200 Format

The following describes the format of the license information returned in the receiver variable parameter. This format contains additional fields that LICR0100 does not have. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Usage limit
12	C	BINARY(4)	Usage count
16	10	CHAR(2)	Usage type
18	12	CHAR(2)	Compliance type
20	14	CHAR(6)	License term
26	1A	CHAR(6)	Release level
32	20	BINARY(4)	Threshold value
36	24	BINARY(4)	Grace period
40	28	CHAR(7)	Date grace period expires
47	2F	CHAR(3)	Processor group
50	32	CHAR(2)	Reserved
52	34	BINARY(4)	Peak usage
56	38	CHAR(7)	Expiration date
63	3F	CHAR(8)	Vendor data
71	47	CHAR(16)	Product license information handle
87	57	CHAR(1)	Reserved
88	58	BINARY(4)	Offset to message queue list
92	5C	BINARY(4)	Number of message queues
96	60	BINARY(4)	Offset to current license user list
100	64	BINARY(4)	Number of current license users
104	68	BINARY(4)	Length of each current license user record
108	6C	BINARY(4)	Processor usage count
112	70	BINARY(4)	Processor peak usage count
116	74	CHAR(13)	Last peak date and time
129	81	CHAR(13)	Last update date and time
142	8E	CHAR(*)	Reserved
Note: Offsets vary depending on the number of message queues in the list.
		CHAR(10)	Message queue name
		CHAR(10)	Message queue library name
Note: Offsets vary depending on the number of current license users and the length of each current license user record.
		CHAR(*)	List of current license users

LICR0300 Format

The following describes the format of the license information returned in the receiver variable parameter. This format contains additional fields about license users that LICR0200 does not have. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Usage limit
12	C	BINARY(4)	Usage count
16	10	CHAR(2)	Usage type
18	12	CHAR(2)	Compliance type
20	14	CHAR(6)	License term
26	1A	CHAR(6)	Release level
32	20	BINARY(4)	Threshold value
36	24	BINARY(4)	Grace period
40	28	CHAR(7)	Date grace period expires
47	2F	CHAR(3)	Processor group
50	32	CHAR(2)	Reserved
52	34	BINARY(4)	Peak usage
56	38	CHAR(7)	Expiration date
63	3F	CHAR(8)	Vendor data
71	47	CHAR(16)	Product license information handle
87	57	CHAR(1)	Reserved
88	58	BINARY(4)	Offset to message queue list
92	5C	BINARY(4)	Number of message queues
96	60	BINARY(4)	Offset to current license user list
100	64	BINARY(4)	Number of current license users
104	68	BINARY(4)	Length of each current license user record
108	6C	BINARY(4)	Length of each license user
112	70	BINARY(4)	Processor usage count
116	74	BINARY(4)	Processor peak usage count
120	78	CHAR(13)	Last peak date and time
133	85	CHAR(13)	Last update date and time
146	92	CHAR(*)	Reserved
Note: Offsets vary depending on the number of message queues in the list.
		CHAR(10)	Message queue name
		CHAR(10)	Message queue library name
Note: Offsets vary depending on the number of current license users and the length of each current license user record.
		BINARY(4)	Number of uses held
		CHAR(*)	License user
		CHAR(*)	Reserved

Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

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.

Date grace period expires. The date that the grace period expires. Once a user has exceeded the usage limit, the date the grace period expires is set using the grace period and the current date. 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.

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.

Expiration date. The date the license will expire. The valid values are:

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.

Feature. The feature of the product. Valid values for the feature are 5001 through 9999.

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.

Last peak date and time. The date and time when the peak usage of the product or feature last occurred since the peak usage was reset to zero. In the CYYMMDDHHmmSS format as follows:

C	Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY	Year
MM	Month
DD	Day
HH	Hour
mm	Minute
SS	Second

Last update date and time. The date and time when the usage limit was last updated. In the CYYMMDDHHmmSS format as follows:

C	Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY	Year
MM	Month
DD	Day
HH	Hour
mm	Minute
SS	Second

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.

Possible values are:

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.
	Where the x and y can be a number from 0 through 9. Z can be a number 0 through 9 or a letter A through Z.

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. If the product is using processor usage type, the peak usage value will be rounded up to the next whole number. For instance, an actual peak usage of 2.15 would round up to 3. See the processor peak usage count field for the processor peak usage count in hundreths of a processor.

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

Processor usage count. The processor usage count is the number of hundreths of processors in the logical partition configured at the time the product was used. This field is set to 0 for products that do not have a processor usage type.

Processor peak usage count. The maximum processor usage count in hundreths of processors. The processor peak usage may be reset using option 10 of the Work License Information (WRKLICINF) command. This field is set to 0 for products that do not have a processor usage type.

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 count. The usage count for the product or feature at the time of the retrieve operation. Valid values are 0 through 999999. If the product is using processor usage type, the usage count value will be rounded up to the next whole number. For instance, an actual usage count of 2.15 would round up to 3. See the processor usage count field for the processor usage count in hundreths of a processor.

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.

Usage type. The usage type associated with this license.

The valid values are:

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.
03	The license usage is by processors. Counts the number of processors that are assigned to the logical partition.

Vendor data. Information the vendor defined at Generate License Key time.

Error Messages

Message ID	Error Message Text
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.

API introduced: V2R3

[ Back to top | Software Product APIs | APIs by category ]