Retrieve Workload Groups Information (QLZRTVWC) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Workload groups information format name | Input | Char(8) |
| 4 | Workload groups query value | Input | Char(*) |
| 5 | Workload groups query format name | Input | Char(8) |
| 6 | Error code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: No
The Retrieve Workload Groups Information (QLZRTVWC) API retrieves information for the specified workload group. This information includes the configured processor core limit for the workload group and the licensed programs (software products) associated with the workload group.
The API can also be used to retrieve a list of all the workload groups defined on the partition.
The QSYS2.WORKLOAD_GROUP_INFO view can be used as an alternative to this API. See WORKLOAD_GROUP_INFO view for more information.
Authorities and Locks
- Public API Authority
- *EXCLUDE
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable to receive the requested information. The structure of this information is determined by the workload groups information format name.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable in bytes. 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.
- Workload groups information format name
- INPUT; CHAR(8)
The name of the format that describes the workload groups information to be retrieved.
The supported formats are:
WLCR0100 Capacity and software product information for a given workload group is retrieved. For more information, see WLCR0100 Format. WLCR0200 The list of all workload groups on the partition which match the query value is retrieved. For more information, see WLCR0200 Format.
- Workload group query value
- INPUT; CHAR(*)
The value identifying the workload group to retrieve information about. The structure of this information is determined by the workload group query value format name. This value can represent one of the following:
- The product information for a given licensed program
- A fully qualified product directory path name packaged with a licensed program
- A specific workload group name
- Product identification format name
- INPUT; CHAR(8)
The name of the format that describes the workload groups query value.
The supported formats are:
WLCQ0100 The workload groups query value is the product information for a given licensed program. For more information, see WLCQ0100 Format. WLCQ0200 The workload group query value is a fully qualified product directory path name. For more information, see WLCQ0200 Format. WLCQ0300 The workload groups query value is a specific workload group name or is special value *ALL. For more information, see WLCQ0300 Format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
WLCR0100 Format
The following information describes the workload groups information to be retrieved. The information includes the list of licensed programs associated with the workload group. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Workload group name |
| 18 | 12 | CHAR(2) | Reserved |
| 20 | 14 | BINARY(4) | Workload group processor capacity |
| 24 | 18 | BINARY(4) | Offset to workload group product list |
| 28 | 1C | BINARY(4) | Number of products in workload group |
| 32 | 20 | BINARY(4) | Length of each product record |
| Note: Offsets vary depending on the number of products in the list. | |||
| CHAR(7) | Product ID | ||
| CHAR(6) | License term | ||
| CHAR(4) | Feature | ||
WLCR0200 Format
The following information describes the workload groups information to be retrieved. The information includes a list of all workload groups defined on the partition which match the query value. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to workload groups list |
| 12 | C | BINARY(4) | Number of workload groups |
| 16 | 10 | BINARY(4) | Length of each workload groups record |
| Note: Offsets vary depending on the number of workload groups in the list. | |||
| CHAR(10) | Workload group name | ||
| BINARY(4) | Workload group maximum processor core limit | ||
WLCQ0100 Format
The following information describes the workload groups query value for a given licensed program. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | Product ID |
| 7 | 7 | CHAR(6) | License term |
| 13 | D | CHAR(4) | Feature |
| 17 | 11 | CHAR(4) | Option |
WLCQ0200 Format
The following information describes the workload groups query value for a fully qualified product directory path name. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Product directory path name length |
| 4 | 4 | BINARY(4) | CCSID of product directory path name |
| 8 | 8 | CHAR(*) | Product directory path name |
WLCQ0300 Format
The following information describes the workload groups query value for a specific workload group name. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Workload group name |
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.
CCSID of product directory path name. The CCSID of the product directory path name for format WLCQ0200. A value of 0 indicates the name is in the job default CCSID.
Feature. The feature of the product. Valid values for the feature are 5001 through 9999.
Length of each product record. The length of each product record associated with the workload group.
Length of each workload group record. The length of each workload group record.
License term. The extent of time the authorized usage limit for a product lasts. The license term can cover an entire version or an entire release or an entire modification level of a given product.
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. |
Number of products in workload group. The number of software products for a given workload group.
Number of workload groups. The number of workload groups on the partition.
Offset to workload group list. The offset from the beginning of the receiver variable to the start of the list of workload groups. This offset is 0 if there are no workload groups or if the size of the receiver variable is not large enough to hold any workload groups.
Offset to workload group product list. The offset from the beginning of the receiver variable to the start of the list of products for a given workload group. This offset is 0 if there are no products in this workload group or if the size of the receiver variable is not large enough to hold any product information.
Option. The four character product option for a given licensed product. Valid values for the option are 0000 through 0099. 0000 represents the *BASE option.
Product directory path name. The product directory path name. A path name has a maximum length of 1024 characters. If the given path name is not packaged with a licensed product, then no information will be returned.
Product directory path name length. The length of the product directory path name.
Product ID. The 7 character product ID of the product whose workload group information is to be retrieved.
Release level. The 6 character version, release, and modification level of the product whose workload group information was requested. The release level must be in the format VxRyMz. Valid values for x and y are 0 through 9. Valid values for z are 0 through 9 and A through Z.
Reserved. If this field is input, character fields must be set to blanks and binary fields must be set to hexadecimal zeros.
Workload group name. The name of a workload group.
The valid special value when using WLCQ0300 is:
| *ALL | All workload groups on the partition. |
Workload group maximum processor core limit. The maximum processor core capacity associated with the workload group.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0CB3 E | Value for reserved field not valid. |
| CPF0C1C E | Release level &1 not valid. |
| CPF0C1F E | Product information not found. |
| CPF0C1E E | Error occurred during running of &1 API. |
| CPF2206 E | User needs authority to do requested function on object. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF247E E | CCSID &1 is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| 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. |
| CPF9E15 E | Error in license management function. |
| CPF9E6D E | Feature &3 not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: IBM® i 7.1