List PTF Groups (QpzListPtfGroups) API
Required Parameter Group:
| 1 | Qualified user space name | Input | CHAR(20) |
| 2 | Format name | Input | CHAR(8) |
| 3 | CCSID | Input | BINARY(4) |
| 4 | Error code | I/O | CHAR(*) |
Service Program Name: QPZGROUP
Default Public Authority: *USE
Threadsafe: No
The List PTF Groups (QpzListPtfGroups) API returns a list of all levels of all PTF groups that are known to the system. You can then use the QpzListPtfGroupDetails API to return detailed information for a specific PTF group.
Authorities and Locks
- Work with PTF Groups (WRKPTFGRP) command
- *USE
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
Lock conflicts may occur if this API is called while another PTF or PTF group operation is in progress.
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that is to receive the generated list. The first 10 characters contain the user space name. The second 10 characters contain the name of the library where the user space is located. You can use these special values for the library name:
*CURLIB The job's current library. *LIBL The library list.
- Format name
- INPUT; CHAR(8)
The content and format of the information that is returned. The possible format names are:
LSTG0100 List of PTF group names, levels, descriptions, and status. For details, see LSTG0100 Format List Section.
- CCSID
- INPUT; BINARY(4)
The coded character set ID in which to return the PTF group names and descriptions. Valid values are 0 through 65533. If a value of 0 is specified, the names and descriptions will be returned in the CCSID of the job.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of the Generated Lists
The user space will contain:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section:
- LSTG0100 format
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the generated list returned, see Field Descriptions.
When you retrieve the list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see Examples: APIs and exit programs.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1A | BINARY(4) | CCSID |
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space library name used |
| 10 | A | CHAR(10) | User space name used |
LSTG0100 Format List Section
The following information is repeated for each PTF group.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(60) | PTF group name |
| 60 | 3C | CHAR(100) | PTF group description |
| 160 | A0 | BINARY(4) | PTF group level |
| 164 | A4 | BINARY(4) | PTF group status |
| 168 | A8 | CHAR(6) | Target release |
| 174 | AE | CHAR(2) | Reserved |
Field Descriptions
CCSID. The coded character set ID of the returned PTF group names and descriptions that was requested.
Format name. The format of the returned information that was requested.
PTF group description. The text description of the PTF group.
PTF group level. The current level of the PTF group.
PTF group name. The name of the PTF group.
PTF group status. The overall status of the PTF group on this system. The status is determined using the status of all PTFs defined in the PTF group, as well as all PTFs defined in all related PTF groups. The level of the related PTF groups used to resolve the status of the PTF group is the highest level of the related PTF group that has a status of Installed or Apply at next IPL. If no levels of the related PTF group have a status of Installed or Apply at next IPL, the highest level of the related PTF group that exists on the system will be used. The following values are valid:
| 0 | Unknown. The PTF group status cannot be resolved because a related PTF group is either not found on the system or is in error. |
| 1 | Not applicable. All PTFs in the PTF group and related PTF groups are for products that are not installed or supported on this system. |
| 2 | Supported only. There are no PTFs in the PTF group or related PTF groups that are for installed products on this system. There is at least one PTF that is for a product, release, option, and load identifier that is supported on this system. |
| 3 | Not installed. There is at least one PTF that is for an installed product on this system, and not all of the PTFs or their superseding PTFs are temporarily or permanently applied. |
| 4 | Installed. All PTFs for products that are installed on this system are temporarily or permanently applied. If a PTF is superseded, a superseding PTF is either temporarily or permanently applied. |
| 5 | Error. The PTF group information is in error. Either delete the PTF group or replace the PTF group information that is currently on the system. |
| 7 | Apply at next IPL. All PTFs for the installed products on the system are either set to be applied at the next IPL or are already temporarily or permanently applied. |
| 8 | Related group. The PTF group does not have any PTFs for products installed or supported on the system. However, it is identified in another PTF group as a related PTF group. Deleting a PTF group in this status will cause the other PTF group to have a status of Unknown. |
| 9 | On order. There is at least one PTF in the group that is on order and has not yet been installed on the system. It will be delivered on either physical or virtual media. |
Target release. The release of the operating system on which the PTF group is to be used. PTF groups that have a target release lower than the currently installed operating system release and also do not contain any PTFs for installed or supported products are automatically deleted by the system. When this PTF group is not associated with an operating system release, this field will contain blanks.
User space library name specified. The name specified for the library that contains the user space to receive the generated list.
User space library name used. The actual name of the library that is used to contain the user space that received the list.
User space name specified. The name specified for the user space that is to receive the generated list.
User space name used. The actual name of the user space that received the list.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0CEE E | Unable to convert data to CCSID &1. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF36AF E | PTF group function already in progress. |
| CPF3BC7 E | CCSID &1 outside of valid range. |
| CPF3CAA E | List is too large for user space &1. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in libary &3. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R2