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 | ||
| 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 | ||
| 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 | ||
| 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 | ||
| 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:
|
| 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:
|
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 warning message indicating that the usage limit
has been exceeded is sent to each of the following:
|
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:
|
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:
|
| 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 or vv | The authorized usage limit is valid for the entire version of the product or feature. |
| VxRy or vvrr | 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. |
| vvrrmm | The authorized usage limit is valid only for the modification level of the product. This format will be returned when the product is licensed at the modification level and the version or release of the product is greater than 9. |
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.
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.
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.
The Release Level can be in two possible formats:
| VxRyMz | Where x is the version of the product, y is the release of the product, and z is the modification of the product. For example, V7R2M0 is version 7, release 2, modification 0. For output, this format will always be returned when the version and release are both less than or equal to 9. |
| vvrrmm | Where vv is the version of the product, rr is the release of the product, and mm is the modification of the product. For example, 110300 is version 11, release 3, modification 0. For input, This format must be used if the version or release of the product is greater than 9. For output, this format will be returned if the version or release of the product is greater than 9. |
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