Add Product License Information (QLZADDLI) API

The Add Product License Information (QLZADDLI) API adds license information to a product or a feature of a product. License information can be added at two times:

• After the product definition object (*PRDDFN) has been created using the Create Product Definition (CRTPRDDFN) command or the Create Product Definition (QSZCRTPD) API.
• Either before or after the product options have been packaged using the Package Product Option (PKGPRDOPT) command or the Package Product Option (QSZPKGPO) API.

License information must be added before the product is installed.

Authorities and Locks

API QLZADDLI Authority

QPGMR(*USE)
QSRV(*USE)
QSRVBAS(*USE)
QSYSOPR(*USE)

Product Availability Lock

*SHRRD. The product availability object is in the QUSRSYS library.

Public Authority

*EXCLUDE

Required Parameter Group

Product identification

INPUT; CHAR(*)

Information that uniquely identifies the product or feature to which license information will be added. The structure of this information is determined by the name of the format. For more information, see LICP0100 Format and LICP0200 Format.

Product identification format name

INPUT; CHAR(8)

The name of the format containing the information to identify the product.

The format names are:

LICP0100	Basic product information used as input to the API. For details, see the LICP0100 Format.
LICP0200	Basic product information plus the product feature message ID are used as input to the API. For details, see the LICP0200 Format.

License information

INPUT; CHAR(*)

Information that is used to license the product or feature. The structure of this information is determined by the name of the format. For more information, see LICI0100 Format and LICI0200 Format.

License information format name

INPUT; CHAR(8)

The name of the format containing the license information.

The format names are:

LICI0100	Basic license information used as input to the API. For details, see LICI0100 Format.
LICI0200	Basic license information plus count usage across logical partitions used as input to the API. For details, see LICI0200 Format.

Error code

I/O; CHAR(*)

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

Optional Parameter Group

Product license information handle

OUTPUT; CHAR(16)

A handle based on the product license information. This handle can be used by the software vendor to help ensure asset protection. Specifically, it makes sure that no unauthorized changes were made to the license information. This handle can be used in conjunction with the Retrieve License Information (QLZARTV) API. The information retrieved by the QLZARTV API includes the product license information handle of the product and license information currently installed on the system. If this handle does not match the one returned by this command or API, then the product has been tampered with. It is suggested that this handle be retrieved and checked before doing a request or release when using keyed compliance. This handle is only returned if the product has keyed compliance.

LICP0100 Format

The following information uniquely describes the product or feature for which the license information is to be added. For detailed descriptions of the fields, see Field Descriptions.

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

LICP0200 Format

The following information uniquely describes the product or feature for which the license information is to be added. It also includes the message identifier of the specified feature. For detailed descriptions of the fields, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	BIN(4)	Size of structure
4	4	CHAR(7)	Product ID
11	B	CHAR(6)	Release level
17	11	CHAR(4)	Feature
21	15	CHAR(7)	Feature message ID

LICI0100 Format

The following specifies the format for the license information that is being added to the product or feature. The allow default usage grace period, vendor password, and grace period fields must be specified if the compliance type is 03. For a compliance type of 01 or 02, these fields do not have to be specified. For detailed descriptions of the fields, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	CHAR(2)	Usage type
2	2	CHAR(2)	Compliance
4	4	BINARY(4)	Default usage limit
8	8	CHAR(1)	License term
9	9	CHAR(1)	Allow a license to be released
10	A	CHAR(10)	Vendor password
20	14	BINARY(4)	Grace period
24	18	CHAR(1)	Allow default usage limit grace period

LICI0200 Format

The following specifies the format for the license information that is being added to the product or feature. The allow default usage grace period, vendor password, grace period, and count across logical partitions fields must be specified if the compliance type is 03. For a compliance type of 01 or 02, these fields do not have to be specified. For detailed descriptions of the fields, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Size of structure
4	4	CHAR(2)	Usage type
6	6	CHAR(2)	Compliance
8	8	BINARY(4)	Default usage limit
12	C	CHAR(1)	License term
13	D	CHAR(1)	Allow a license to be released
14	E	CHAR(10)	Vendor password
24	18	BINARY(4)	Grace period
28	1C	CHAR(1)	Allow default usage limit grace period
29	1D	CHAR(1)	Count usage across logical partitions

Field Descriptions

Allow default usage limit grace period. Whether a grace period should be allowed on the default usage limit. If allowed, the default usage limit could be exceeded for the number of days in the grace period for the product or feature. The default usage limit is the number of users that are able to use the product or feature before the license key is installed. Thus, an unlimited number of users can use the product or feature for the number of days in the grace period without having a key.

0	There is no grace period for the default usage limit.
1	There is a grace period for the default usage limit.

Allow a license to be released. Whether a use of the license that was previously requested can be released using the Work with License Information (WRKLICINF) command. When a use of the license is released, the usage count is decremented. This value can only be specified for a usage type of registered.

The valid values are:

0	A use of the license cannot be released with the WRKLICINF command.
1	A use of the license can be released with the WRKLICINF command.

Compliance. The action taken when the usage limit is exceeded.

The valid values are:

01	The usage limit cannot be exceeded. After the usage limit for a product or feature is reached, it cannot be accessed again until the usage limit for it is increased. A message indicating an attempt was made to exceed the usage limit is sent to: 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 that the usage limit has been exceeded is sent to: The QSYSOPR message queue. The message queues specified on the 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 provider. A user who attempts to use the product or feature after the usage limit has been reached is allowed access for the number of days contained in the product's grace period. Once the grace period expires, 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 vendor. The numbers of users falls below the usage limit.
	A warning message, indicating the usage limit is exceeded, is sent to the QSYSOPR message queue and the message queues specified on the CHGLICINF command.

Count usage across logical partitions. Whether usage is counted across logical partitions.

0	Usage is not counted across logical partitions.
1	Usage is counted across logical partitions.

Default usage limit. The usage limit in effect when the product or feature is initially installed.

The valid values are:

0-999999	The number of users allowed to access the product or feature.
-1	Any number of users are allowed to access the product or feature.

Note: For keyed compliance, this is the number of users that will be able to use the product or feature before the license key is installed using the Add License Key command (ADDLICKEY) or API (QLZAADDK). Therefore, to prevent any access to the product or feature without a key, the default usage limit must be set to 0. Also, 0 must be specified for the allow default usage limit grace period.

Feature. The feature of the product to which the license information is being added. Valid values for the feature are 5001 through 9999.

Feature message ID. The message identifier for the message that describes the specified product or feature. If a message ID is not specified, the message identifier used to describe the base product option is used.

Grace period. The number of days after a product first exceeds its usage limit that a user has to obtain a new license key. If a new license key is not obtained from the software provider by the time the grace period is expired, no users over the usage limit are allowed to access the product or feature. When the usage limit is first exceeded, the date the grace period expires is calculated by adding the number of days in the grace period to the current date. Valid values for the grace period are 0 through 999.

During the grace period, the number of users able to use the product or feature is restricted to 50% greater than the current usage limit.

License term. The length of time the authorized usage limit for a product lasts.

The valid values are:

1	The authorized usage limit is valid for the entire version of the product or feature. Each time a new version is installed, the authorized usage limit must be set by using one of the following: The Work with License Information (WRKLICINF) command. The Change License Information (CHGLICINF) command.
	In the case of keyed compliance (type 03), a new license key must also be obtained from the software provider. However, products with keyed compliance (type 03) must set the usage limit by using the ADDLICKEY command. This command also requires that a license key be obtained from the software provider to allow use of the product.
2	The authorized usage limit is valid for the entire release of the product or feature. Each time a new release is installed, the authorized usage limit must be set by using the WRKLICINF command or the CHGLICINF command. In the case of keyed compliance (type 03), a new license key must also be obtained from the software provider. However, products with keyed compliance (type 03) must set the usage limit by using the ADDLICKEY command. This command also requires that a license key be obtained from the software provider to allow use of the product.
3	The authorized usage limit is valid only for a modification of the product. Each time a new modification is installed, the authorized usage limit must be set by using the WRKLICINF command or the CHGLICINF command. However, products with keyed compliance (type 03) must set the usage limit by using the ADDLICKEY command. This command also requires that a license key be obtained from the software provider to allow use of the product.

Product ID. The product ID of the product or feature to which the license information is being added.

Release level. The version, release, and modification level of the product.

The Release level can be passed as one of the following two formats:

VxRyMz

Where x is any numeric character 0 through 9, y is any numeric character 0 through 9, and z is any numeric character 0 through 9 or uppercase letter A through Z. For example, V7R2M0 is version 7, release 2, modification 0.

vvrrmm

Where vv are any numeric characters 00 through 35 representing the version of the product, rr are any numeric characters 00 through 35 representing the release of the product, and mm can be 00 through 09 or 0A through 0Z representing the modification of the product. For example, 110300 is version 11, release 3, modification 0. This format must be used if the version or release of the product is greater than 9.

Size of structure. The size of the entire data passed in on this structure.

Usage type. The type of license usage.

The valid values are:

01	The usage type is concurrent. It is for the number of unique jobs accessing the product or feature at one time.
02	The usage type is registered. It is for the number of unique users registered by the product or feature.
03	The license usage is by processors. Counts the number of processors that are assigned to the logical partition.

Vendor password. The software vendor's password. This password is encrypted, stored with the product, and is used in validating Add License Key (ADDLICKEY) requests. It must be the same password that is used to generate keys for this product and feature on the Generate License Key command or API. The password must begin with an alphabetic character (A through Z, $, #, or @) followed by no more than 9 alphameric characters (A through Z, 0 through 9, $, #, @, or _).

Error Messages

Message ID	Error Message Text
CPF0CB2 E	Product identifier &1 not valid.
CPF0C4B E	Product availability object &2/&1 recovery required.
CPF0C4C E	Cannot allocate object &1 in library &2.
CPF0C4D E	Error occurred while processing object &1 in library &2.
CPF0C54 E	Data in product record not correct.
CPF24B4 E	Severe error while addressing parameter list.
CPF3CF1 E	Error code parameter not valid.
CPF3C21 E	Format name &1 is not valid.
CPF3C90 E	Literal value cannot be changed.
CPF358A E	Release not valid.
CPF8191 E	Product definition &4 in &9 damaged.
CPF8193 E	Product load object &4 in &9 damaged.
CPF9E0A E	Allow license release not valid.
CPF9E0B E	Allow grace period value of &1 not valid.
CPF9E0C E	Allow license release &1 not valid.
CPF9E0D E	Grace period &1 not valid.
CPF9E0E E	Feature message identifier &1 not valid.
CPF9E0F E	Vendor password &1 not valid.
CPF9E02 E	Cannot add license information.
CPF9E03 E	License information already exists.
CPF9E04 E	Product definition for product &1 &2 feature &3 cannot be found.
CPF9E05 E	Feature &3 not valid.
CPF9E06 E	Usage type &1 not valid.
CPF9E07 E	Compliance &1 not valid.
CPF9E08 E	Default usage limit &1 not valid.
CPF9E09 E	License term &1 not valid.
CPF9E1A E	License information conflict found.
CPF9E15 E	Error in license management function.
CPF9801 E	Object &2 in library &3 not found.
CPF9803 E	Cannot allocate object &2 in library &3.
CPF9810 E	Library &1 not found.
CPF9838 E	User profile storage limit exceeded.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
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 ]