List PTF Group Details(QpzListPtfGroupDetails) API
Required Parameter Group:
| 1 | Qualified user space name | Input | CHAR(20) |
| 2 | PTF group information | Input | CHAR(*) |
| 3 | Format name | Input | CHAR(8) |
| 4 | CCSID for returned information | Input | BINARY(4) |
| 5 | Error code | I/O | CHAR(*) |
Service Program Name: QPZGROUP
Default Public Authority: *USE
Threadsafe: No
The List PTF Group Details (QpzListPtfGroupDetails) API lists information for a specific level of a PTF group on the system. The information returned is determined by the format specified.
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.
- PTF group information
- INPUT; CHAR(*)
The attributes of the PTF group for which information is being requested. For more information on this parameter, see Format of PTF Group Information.
- Format name
- INPUT; CHAR(8)
The content and format of the information returned for this PTF group. The possible format names are:
GRPR0100 Return basic information about the PTF group. All information is returned in the user space Header Section, no list information is returned for this format. For details, see Header Section. GRPR0200 Return basic information about the PTF group including the list of PTFs named within the PTF group. For details, see GRPR0200 Format List Section. GRPR0300 Return basic information about the PTF group including the list of PTFs named within the PTF group and their detailed information. For details, see GRPR0300 Format List Section. GRPR0400 Return the same information as in GRPR0300 format, but for any PTFs that are superseded by a later PTF, return detailed information about the superseded by PTF ID in place of the superseded PTF. For details, see GRPR0300 Format List Section. GRPR0500 Return the list of related PTF groups. For details, see GRPR0500 Format List Section.
- CCSID for returned information
- INPUT; BINARY(4)
The coded character set ID in which to return the PTF group name, description, and related PTF group names. 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 PTF Group Information
For the detailed descriptions of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of PTF group information |
| 4 | 4 | CHAR(60) | PTF group name |
| 64 | 40 | BINARY(4) | CCSID of PTF group name |
| 68 | 44 | CHAR(1) | Include related PTF groups |
| 69 | 45 | CHAR(3) | Reserved |
| 72 | 48 | BINARY(4) | Level |
Field Descriptions
Length of PTF group information. The length of the data in the PTF group information parameter, including this field. The valid values for this field are 69 or 76.
PTF group name. The name of the PTF group for which information is being requested. The name is limited to a maximum of 30 characters.
CCSID of PTF group name. The coded character set ID for the PTF group name specified in the PTF group information parameter. Valid values are 0 through 65533. If a value of 0 is specified, the name is assumed to be in the CCSID of the job.
Include related PTF groups. Whether to include information from all related PTF groups in the returned list information. The following values are valid:
| 0 | Do not include information from related PTF
groups.
For formats GRPR0200, GRPR0300, and GRPR0400, only the information for the PTFs named within this PTF group is returned. For format GRPR0500, only the related PTF groups named within this PTF group that have a status of Installed or Apply at next IPL are returned. If no levels of the related PTF group have a status of Installed or Apply at next IPL, the latest level of the related PTF group is returned. |
| 1 | Include all information from all related PTF
groups. The latest level of the related PTF groups with a status of Installed or
Apply at next IPL will be used. If no levels of the related PTF group have
a status of Installed or Apply at next IPL, the latest level of the related
PTF group on the system is used.
For formats GRPR0200, GRPR0300, and GRPR0400, the information for all PTFs named within this PTF group and all related PTF groups is returned. For format GRPR0500, the related PTF groups in all related PTF groups are returned. |
| 2 | Include information from the latest level of all related PTF groups. This value is only valid for format GRPR0500. An error will occur if this value is used with any other format. |
| 3 | Include all levels of all related PTF groups. This value is only valid for format GRPR0500. An error will occur if this value is used with any other format. |
Level. The level of the PTF group for which information is being requested. If the Length of PTF group information field is set to 69, this field will default to a value of 0. The following values may be used:
| 1-99999 | Return information for the specified level of the PTF group. If the level does not exist, an error will be returned. |
| 0 | Return information for the highest level of the PTF group that has a status of Installed or Apply at next IPL. If no levels of the PTF group have a status of Installed or Apply at next IPL, the highest level of the PTF group that exists on the system is returned. |
| -1 | Return information for the highest level of the PTF group that exists on the system. |
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:
- GRPR0200 format
- GRPR0300 format
- GRPR0400 format
- GRPR0500 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(60) | PTF group name |
| 80 | 50 | CHAR(8) | Format name |
| 88 | 58 | BINARY(4) | CCSID of PTF group name |
| 92 | 5C | BINARY(4) | CCSID for returned information |
| 96 | 60 | CHAR(1) | Include related PTF groups |
| 97 | 61 | CHAR(3) | Reserved |
| 100 | 64 | BINARY(4) | Level |
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name used |
| 10 | A | CHAR(10) | User space library name used |
| 20 | 14 | CHAR(60) | PTF group name |
| 80 | 50 | CHAR(100) | PTF group description |
| 180 | B4 | BINARY(4) | PTF group level |
| 184 | B8 | BINARY(4) | PTF group status |
| 188 | BC | CHAR(8) | Date of special handling PTFs |
| 196 | C4 | CHAR(6) | Target release |
GRPR0200 Format List Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | PTF ID |
| 7 | 7 | CHAR(7) | Product ID |
| 14 | E | CHAR(6) | Release |
| 20 | 14 | CHAR(4) | Product option |
| 24 | 18 | CHAR(4) | Product load ID |
| 28 | 1C | CHAR(2) | Minimum level |
| 30 | 1E | CHAR(2) | Maximum level |
GRPR0300 Format List Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | PTF ID |
| 7 | 7 | CHAR(7) | Product ID |
| 14 | E | CHAR(6) | Release |
| 20 | 14 | CHAR(4) | Product option |
| 24 | 18 | CHAR(4) | Product load ID |
| 28 | 1C | CHAR(2) | Minimum level |
| 30 | 1E | CHAR(2) | Maximum level |
| 32 | 20 | CHAR(1) | Loaded status |
| 33 | 21 | CHAR(1) | IPL action |
| 34 | 22 | CHAR(1) | Action pending |
| 35 | 23 | CHAR(1) | Action required |
| 36 | 24 | CHAR(1) | Cover letter status |
| 37 | 25 | CHAR(1) | On-order status |
| 38 | 26 | CHAR(1) | Save file status |
| 39 | 27 | CHAR(10) | Save file name |
| 49 | 31 | CHAR(10) | Save file library name |
| 59 | 3B | CHAR(7) | Superseded by PTF ID |
| 66 | 42 | CHAR(7) | Latest superseding PTF ID |
| 73 | 49 | CHAR(1) | Product status |
| 74 | 4A | CHAR(1) | Omit status |
| 75 | 4B | CHAR(1) | Pre-apply status |
GRPR0500 Format List Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(60) | Related PTF group name |
| 60 | 3C | CHAR(100) | PTF group description |
| 160 | A0 | BINARY(4) | PTF group level |
| 164 | A4 | BINARY(4) | PTF group status |
Field Descriptions
Action pending. Indicates whether a required action has yet to be performed to make this PTF active. This field reflects the current status of any required actions. The following values are valid:
| 0 | No required actions are pending for this PTF. |
| 1 | A required action needs to occur for this PTF to
be active. Check the Activation Instructions section of the cover letter to
determine what the action is.
If the action required field is 2 and you have performed the activation instructions, then the PTF is active. However, this field will not be updated until the next IPL. |
Action required. An action is required to make this PTF active when it is applied. See the cover letter to determine what action needs to be taken. The following values are valid:
| 0 | No activation instructions are needed for this PTF. |
| 1 | This PTF was shipped with activation instructions in the cover letter. This value is returned for all PTFs that have an exit program to update the status of the PTF after the activation instructions have been performed. |
| 2 | This PTF was shipped with activation instructions in the cover letter. No exit program exists to verify the activation instructions were performed. |
Cover letter status. Whether a cover letter exists for the PTF. The following values are valid.
| 0 | The PTF has no cover letter. |
| 1 | The PTF has a cover letter. |
Date of special handling PTFs. The date the PTF group was last created with special handling PTFs. The date is specified in format yyyymmdd. The following special value is valid:
| *NONE | No date provided. |
IPL action. The action to be taken on this PTF during the next IPL. The following values are valid:
| 0 | No action occurs at the next IPL. |
| 1 | The PTF is temporarily applied at the next IPL. |
| 2 | The PTF is temporarily removed at the next IPL. |
| 3 | The PTF is permanently applied at the next IPL. |
| 4 | The PTF is permanently removed at the next IPL. |
Latest superseding PTF ID. The identifier of the most recent supersede of this PTF that exists on the system. This field will be blank when the PTF does not have a superseding PTF.
Loaded status. The current loaded status of the PTF. The following values are valid:
| 0 | The PTF has never been loaded. |
| 1 | The PTF is loaded. |
| 2 | The PTF is applied temporarily. |
| 3 | The PTF is applied permanently. |
| 4 | The PTF is permanently removed. |
| 5 | The PTF is damaged. An error occurred while applying the PTF. It needs to be reloaded and applied. |
| 6 | The PTF is superseded. A PTF will have a status
of superseded when one of the following situations occurs:
|
Library name. The name of the library where the user space can be located. You can use these special values for the library name:
| *CURLIB | The job's current library. |
| *LIBL | The library list. |
Maximum level. The indicator of the highest level of the product on which this PTF can be installed. If the minimum and maximum levels are the same, then this PTF can only be installed on one level of the product. The level can be AA to 99. This field will be blank if the product has no level.
Minimum level. The indicator of the lowest level of the product on which this PTF can be installed. If the minimum and maximum levels are the same, then this PTF can only be installed on one level of the product. The level can be AA to 99. This field will be blank if the product has no level.
Omit status. Whether the PTF should be omitted when installing the PTF group. The following values are valid:
| 0 | The PTF should not be omitted. |
| 1 | The PTF was defined to be omitted when the PTF group was created. |
| 2 | The PTF was specified to be omitted by the user when the PTF group was installed. |
On-order status. Whether the PTF has been ordered. The following values are valid:
| 0 | The PTF has not been ordered or has already been received. |
| 1 | The PTF has been ordered. |
Pre-apply status. Whether the PTF should be applied before the other PTFs when installing the PTF group. The following values are valid:
| 0 | The PTF should not be pre-applied. |
| 1 | The PTF should be applied temporarily before the other PTFs when installing the PTF group. |
| 2 | The PTF should be applied permanently before the other PTFs when installing the PTF group. |
Product ID. The product identifier of the PTF.
Product load ID. The load ID of the product load for the PTF. A value of "CODE" indicates this PTF is for the code load of the product.
Product option. The option of the product for the PTF.
Product status. The current status of the product. The following values are valid:
| 0 | The PTF is for a product, version, option, load identifier, and level that is not installed or supported on the system. |
| 1 | The PTF is for a product, version, option, load identifier, and level that is installed on the system. The product may or may not be supported. |
| 2 | The PTF is for a product, version, option, and load identifier, that is only supported on the system, it is not installed. |
PTF group description. The text description of the PTF group.
PTF group level. The level of the PTF group. A value of 0 indicates the PTF group level cannot be determined.
PTF group name. The name of the PTF group for which information is being requested.
PTF group status. The overall status of the PTF group on this system. The PTF group status is obtained using the status of all the PTFs listed within the PTF group as well as all PTFs listed in all related PTF groups. The level of the related PTF groups used 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 latest 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. |
| 6 | Not found. The PTF group is not found on the system. This status will only be returned for the status of a related PTF group when using format GRPR0500. |
| 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. |
PTF ID. The identifier of the PTF in the PTF group.
Related PTF group name. The name of the related PTF group.
Release. The version, release, and modification of the product. The release will be returned in one of the following 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. This format will be returned when the version and release of the product 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. This format will be returned if the version or release of the product is greater than 9. |
Reserved. An error will be signaled if this field does not contain hexadecimal zeros.
Save file library name. The name of the library where the save file for the PTF is located. If no save file name has been reserved, this field will be blank.
Save file name. The name of the file where the save file for the PTF is located. You should use the save file status field to determine if a save file exists for this PTF. If no save file name have been reserved, this field will be blank.
Save file status. Whether a save file exists on the system for the PTF. The following values are valid.
| 0 | The PTF has no save file. |
| 1 | The PTF has a save file. |
Superseded by PTF ID. The identifier of the PTF that has replaced this PTF. This field will be blank when the PTF is not superseded or when the superseding PTF has not been loaded on the system.
Target release. The release of the operating system on which
the PTF group is to be used.
The release level is
specified in the format VxRyMz, where Vx is
the version, Ry is the release, and Mz is the modification
level.
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. |
| CPF36A2 E | Length of PTF group name or text too long. |
| CPF36A4 E | PTF group &1 not found. |
| CPF36A5 E | Information for PTF group &1 not complete. |
| CPF36AF E | PTF group function already in progress. |
| CPF36B1 E | Value for parameter &1 not valid. |
| CPF3BC7 E | CCSID &1 outside of valid range. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C39 E | Value for reserved field is not valid. |
| CPF3C4C E | Value not valid for field. |
| 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. |
| 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