List Program Temporary Fixes (QpzListPTF) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Product information | Input | Char(50) |
| 3 | Format name | Input | Char(8) |
| 4 | Error code | I/O | Char(*) |
Service Program: QPZLSTFX
Default Public Authority: *EXCLUDE
Threadsafe: No
The List Program Temporary Fixes (QpzListPTF) API returns a list of PTFs for the specified product, option, load, and release. The product must be supported or installed before the list of PTFs is returned.
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
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.
- Product information
- INPUT; CHAR(50)
The attributes of the product for which information is being requested. For more information on this parameter, see Format of Product Information.
- Format name
- INPUT; CHAR(8)
The content and format of the information that is returned for each PTF. The possible format names are:
PTFL0100 List of PTFs for product, option, load, and release. For more information, see PTFL0100 Format List Section.
- 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 Product Information
For the detailed descriptions of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | Product ID |
| 7 | 7 | CHAR(6) | Release level |
| 13 | D | CHAR(4) | Option |
| 17 | 11 | CHAR(10) | Load ID |
| 27 | 1B | CHAR(1) | Include superseded PTFs |
| 28 | 1C | CHAR(1) | Include permanently removed PTFs |
| 29 | 1D | CHAR(21) | Reserved |
Field Descriptions
Include permanently removed PTFs. Whether to include PTFs that have a status of permanently removed in the list. A PTF that has been permanently removed and also requires a server IPL, is on order, or has a save file or cover letter will be included in the list regardless of the value specified. Valid values follow:
| 0 | Do not include permanently removed PTFs in the list. |
| 1 | Include permanently removed PTFs in the list. |
Include superseded PTFs. Whether to include superseded PTFs in the list. Valid values follow:
| 0 | Do not include superseded PTFs in the list. |
| 1 | Include superseded PTFs in the list. |
Load ID. The load ID for which PTFs are being requested. Load IDs are 10 characters in length. For example, 2924 is the load ID for an English national language version (NLV). You can use the following special value for the load ID:
| *ALL | The list of PTFs contains PTFs for all loads for the product specified. |
Option. The option number for which PTFs are being requested. Use 0000 for the base option. Valid values are 0000 through 0099, where each character is a digit. You can use this special value for the option:
| *ALL | The list of PTFs contains PTFs for all options of the specified product. |
Product ID. The product ID for which PTFs are being requested.
Release level. The release of the product for which PTFs are requested. The release can be passed as one of the following formats:
| VxRyMz | Valid values for version x and release y are 0 through 9. Valid values for modification z are 0 through 9 or A through Z. |
| vvrrmm | Valid values for version vv and release rr are 00 through 35. Valid values for modification mm are 00 through 09 or 0A through 0Z. The leading zeros are required. This format must be used if the version or release of the product is greater than 9. |
| *ALL | The generated list of PTFs contains PTFs for all releases of the specified product. |
Reserved. This field must contain hexadecimal zeros.
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:
- PTFL0100 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(50) | Product information |
| 70 | 46 | CHAR(8) | Format name |
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(1) | Current IPL source |
| 21 | 15 | CHAR(1) | Current server IPL source |
| 22 | 16 | CHAR(1) | Server firmware status |
PTFL0100 Format List Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | PTF ID |
| 7 | 7 | CHAR(6) | Release level of the PTF |
| 13 | D | CHAR(4) | Product option of the PTF |
| 17 | 11 | CHAR(4) | Product load of the PTF |
| 21 | 15 | CHAR(1) | Loaded status |
| 22 | 16 | CHAR(1) | Save file status |
| 23 | 17 | CHAR(1) | Cover letter status |
| 24 | 18 | CHAR(1) | On-order status |
| 25 | 19 | CHAR(1) | IPL action |
| 26 | 1A | CHAR(1) | Action pending |
| 27 | 1B | CHAR(1) | Action required |
| 28 | 1C | CHAR(1) | IPL required |
| 29 | 1D | CHAR(1) | PTF is released |
| 30 | 1E | CHAR(2) | Minimum level |
| 32 | 20 | CHAR(2) | Maximum level |
| 34 | 22 | CHAR(13) | Status date and time |
| 47 | 2F | CHAR(7) | Superseded by PTF ID |
| 54 | 36 | CHAR(1) | Server IPL required |
| 55 | 37 | CHAR(13) | Creation date and time |
 68 |
44 | CHAR(1) | Technology refresh PTF
|
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.
| 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. |
Creation date and time. The date and time that the PTF was created. This value will be blanks when the creation date and time cannot be determined. The date and time field is in the CYYMMDDHHMMSS format:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
Current IPL source. The copy of Licensed Internal Code that the system is currently operating from. The previous IPL of the system used this copy of Licensed Internal Code.
| A | The system is currently operating on the A IPL source. |
| B | The system is currently operating on the B IPL source. |
| Blank | The current IPL source could not be determined. |
Current server IPL source. The copy of the server firmware that was used on the previous server IPL.
| 0 | There is no server IPL source because the system is not operating as a service partition. |
| 1 | The server is currently operating on the T server IPL source. |
| 2 | The server is currently operating on the P server IPL source. |
Server firmware status. The status of the server firmware that is currently active.
| 0 | There is no server firmware status information because the system is not operating as a service partition. |
| 1 | The server firmware that is currently active is at the same level as the server firmware that is installed on the system. |
| 2 | A server IPL is required to activate PTFs that have been applied for the server firmware. |
| 3 | A server IPL is required to activate a new level of the server firmware portion of the Licensed Internal Code that has been installed on the system. Note that this value is obsolete as of V6R1M0. |
| 4 | The server firmware that is currently active is at a later level than the server firmware that is installed on the system. This can occur when PTFs for the server firmware have been permanently removed, but are still currently active. When a server IPL occurs, a lower level of the server firmware will be activated. |
| 5 | The server firmware that is currently active is at a different level than the server firmware that is installed on the system. The service partition is currently configured to not allow the system to make changes to the server firmware. |
| 6 | The server firmware that is currently active is at a later level than the server firmware PTFs installed on the system. The installed server firmware PTFs are not compatible with the server firmware. When a server IPL occurs, the lower level of the server firmware will not be activated. |
| 7 |
The server firmware that is currently active is at a different level than the server firmware PTF installed on the system. However, the date of the firmware PTF is later than the
firmware entitlement date. The server firmware will not be
activated until a valid firmware entitlement date is detected. |
IPL action. The action to be taken on this PTF during the next unattended 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. |
IPL required. An IPL is required to apply this PTF. The following values are valid:
| 0 | The PTF is delayed. The PTF must be applied during an IPL. |
| 1 | The PTF is immediate. No IPL is needed to apply the PTF. |
| Blank | The type of the PTF is not known. |
Loaded status. The current loaded status of the PTF. A PTF can have any of the following statuses:
| 0 | The PTF has never been loaded. |
| 1 | The PTF has been loaded. |
| 2 | The PTF has been applied. |
| 3 | The PTF has been applied permanently. |
| 4 | The PTF has been 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:
|
Note: These fields are returned as numbers instead of text because statuses are translatable text instead of special values. The text message that contains these values is CPX3501.
Maximum level. The indicator of the highest level of the product to which this PTF can be applied. The level can be AA to 99. This field will be blank if the product does not have a level.
Minimum level. The indicator or the lowest level of the product to which this PTF can be applied. The level can be AA to 99. This field will be blank if the product does not have a level.
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. |
Product load of the PTF. The load ID of the product load for the PTF.
Product option of the PTF. The option of the product to which the PTF applies.
PTF ID. The identifier of the PTF.
PTF is released. Whether the PTF save file is available for distribution to another system. This is set to 1 only when the System Manager for IBM® i licensed program is on the system and the product is supported. The user needs to check the PTF save file status before using this field. Possible values follow:
| 0 | The PTF save file cannot be distributed. |
| 1 | The PTF save file is released and can be distributed to another system. |
Release level of the PTF. The release of the PTF. 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. |
Save file status. Whether a save file exists for the PTF. This field should always be checked to determine if a save file exists. The following values are valid.
| 0 | The PTF has no save file. |
| 1 | The PTF has a save file. |
Server IPL required. Indicates whether or not a server IPL must be performed in order to activate the changes for the PTF. Note that this field is obsolete as of V6R1M0 and will be set to 0. The possible values are:
| 0 | No server IPL is required to activate the changes for the PTF. |
| 1 | A server IPL must be performed using the T server IPL source in order to activate the changes for the PTF. |
| 2 | A server IPL must be performed using the P server IPL source in order to activate the changes for the PTF. |
Status date and time. The date and time that the PTF status was last changed. This value will be blank when the status date and time is not available. The date and time field is in the CYYMMDDHHMMSS format:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
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.
Technology refresh PTF. Whether the PTF is a technology refresh PTF. A technology refresh PTF is used to deliver a significant amount of new function between major releases. The following values are valid:
| 0 | The PTF is not a technology refresh PTF. |
| 1 | The PTF is a technology refresh PTF. |
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 |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C4A E | Value not valid for field &1. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF35BE E | Product &1 &4 not supported or installed. |
| CPF358A E | Release not valid. |
| CPF6601 E | No PTF activity exists for product &1. |
| 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 library &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: V4R1