Retrieve Program Temporary Fix Information (QPZRTVFX) API

The Retrieve Program Temporary Fix Information (QPZRTVFX) API returns information about a specific program temporary fix (PTF). The information returned is determined by the format specified.

You can use the QPZRTVFX API to:

• Retrieve basic information about a PTF.
• Retrieve the cover letter information for a PTF.
• Retrieve the requisites for a PTF.
• Retrieve the list of objects for a PTF.
• Retrieve the dependents for a PTF.
• Retrieve the list of APARs for a PTF.
• Retrieve the list of symptom strings for a PTF.
• Retrieve the list of exit programs for a PTF.
• Retrieve the preconditions for a PTF.
• Retrieve the superseded PTF IDs for a PTF.

Authorities and Locks

None.

Lock conflicts may occur if this API is called while another PTF operation is in progress.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that is to receive the information requested. The length of this area must be passed in the length of receiver variable parameter. The API returns only the data the area can hold.

Length of receiver variable

INPUT; Binary(4)

The length of the receiver variable. You can specify a smaller area than the format requested as long as you specify the length of receiver variable parameter correctly. If the length specified is larger than the size of the receiver variable, the results are not predictable. This value must be greater than or equal to 8.

PTF information

INPUT; CHAR(50)

The attributes of the PTF for which information is being requested. For more information on this parameter see Format of PTF Information.

Format name

INPUT; CHAR(8)

The content and format of the information returned for the PTF. The possible format names are:

PTFR0100	Basic information; for details, see PTFR0100 Format.
PTFR0200	This format contains the basic information as well as an array of cover letters in the format given. If the receiver variable does not have enough space for all the cover letters to be returned, only the cover letters that fit in the space provided are returned. For details, see PTFR0200 Format.
PTFR0300	This contains the basic information plus an array that contains information about the requisite PTFs. If the receiver variable does not have enough space to return all requisite information, only the information that fits in the space provided is returned. For details, see PTFR0300 Format.
PTFR0400	This contains the basic information plus an array that contains a list of the PTF objects and their alternative names. If the receiver variable does not have enough space to return all of the PTF object information, only the information that fits in the space provided is returned. For details, see PTFR0400 Format.
PTFR0500	This contains the basic information plus an array that contains information about the dependent PTFs. If the receiver variable does not have enough space to return all dependent information, only the information that fits in the space provided is returned. For details, see PTFR0500 Format.
PTFR0600	This contains the basic information plus an array that contains information about the APAR numbers. If the receiver variable does not have enough space to return all APAR information, only the information that fits in the space provided is returned. For details, see PTFR0600 Format.
PTFR0700	This contains the basic information plus an array that contains information about the symptom strings. If the receiver variable does not have enough space to return all symptom string information, only the information that fits in the space provided is returned. For details, see PTFR0700 Format.
PTFR0800	This contains the basic information plus an array that contains the exit program information. If the receiver variable does not have enough space to return all exit program information, only the information that fits in the space provided is returned. For details, see PTFR0800 Format.
PTFR0900	This contains the basic information plus an array that contains the information about the preconditions. If the receiver variable does not have enough space to return the precondition information, only the information that fits in the space provided is returned. For details, see PTFR0900 Format.
PTFR1000	This contains the basic information plus an array that contains the information about the superseded PTFs. If the receiver variable does not have enough space to return the superseded PTF information, only the information that fits in the space provided is returned. For details, see PTFR1000 Format.

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 Information

For detailed descriptions of each field, see Field Descriptions.

Field Descriptions

CCSID for returned directory names. The CCSID in which the directory names should be returned. If this field is blank, the CCSID is the job default CCSID. This value is used only for returned directory names.

Close PTF database files. Whether the PTF database files should remain open after returning from the API call. This field allows for improved performance when this API is called numerous times during processing. Do not leave the PTF database files open for long periods of time because other PTF operations cannot be performed while these files are open. If a blank is specified in this field, it will be treated as a 0.

Product ID. The product ID for the PTF for which information is requested. The possible values are:

PTF ID. The identifier of the PTF for which information is requested.

Release level. The release of the PTF for which information is requested. This field is ignored if *ONLY is specified in the product ID field. The format is:

Reserved. This field must contain blanks.

PTFR0100 Format

This format returns basic information about the PTF. For detailed descriptions of each field, see Field Descriptions.

PTFR0200 Format

The fields that follow the cover letter records field define an entry in that array. That group of fields is repeated by the number of different NLVs available for the cover letter field. For detailed descriptions of each field, see Field Descriptions.

PTFR0300 Format

The fields following the requisite record field define an entry in that array. That group of fields is repeated by the number of requisites. For detailed descriptions of each field, seeField Descriptions.

PTFR0400 Format

The fields following the PTF object record field define an entry in that array. That group of fields is repeated by the number of PTF objects. If a PTF contains subobjects, an offset to an array of subobjects is provided. The subobject fields are repeated by the number of PTF subobjects. For detailed descriptions of each field, see Field Descriptions.

PTFR0500 Format

The fields following the dependent record field define an entry in that array. That group of fields is repeated by the number of dependents. For detailed descriptions of each field, see Field Descriptions.

PTFR0600 Format

The fields following the APAR record field define an entry in that array. That group of fields is repeated by the number of APAR records. For detailed descriptions of each field, see Field Descriptions.

PTFR0700 Format

The fields following the symptom string record field define an entry in that array. That group of fields is repeated by the number of symptom string records. For detailed descriptions of each field, see Field Descriptions.

PTFR0800 Format

The fields following the exit program record field define an entry in that array. That group of fields is repeated by the number of exit programs. For detailed descriptions of each field, see Field Descriptions.

PTFR0900 Format

The fields following the precondition record field define an entry in that array. That group of fields is repeated by the number of precondition records. For detailed descriptions of each field, see Field Descriptions.

PTFR1000 Format

The fields following the superseded PTF record field define an entry in that array. That group of fields is repeated by the number of superseded PTF records. For detailed descriptions of each field, see Field Descriptions.

Field Descriptions

APAR number. The number of the APAR that is fixed when you install this PTF.

APAR record. The information about the APAR. The record is an array that contains the fields in format PTFR0600.

Action pending. 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:

Action required. Whether 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.

Alternative object name. The alternative name of the object when the PTF is temporarily applied or temporarily removed. PTFs that have been temporarily applied have alternative object names in the format of QPZAnnnnnn; PTFs that are temporarily removed have alternative object names in the format of QPZRnnnnnn, where nnnnnn is some number. This field is blank for the following reasons:

• the PTF is not temporarily applied or is temporarily removed.
• the object is a temporary object on the system; that is, an object name that starts with QPZ1 or QPZ2.
• the object was bypassed when the PTF was loaded.

Bytes available. The number of bytes of data available to be returned to the user.

Bytes returned. The number of bytes that were returned to the user. This is the lesser of the number of bytes available to be returned or the length of the receiver variable.

CCSID of returned directories. The value of the CCSID in which the directories were returned. This will be the requested CCSID if the value of the CCSID conversion indicator is 0. This field is used only for subobject attributes of DIR (directory) and SOM (system object model).

Cover letter file name. The file containing the cover letter member.

Cover letter library name. The library containing the cover letter file.

Cover letter member name. The member containing the cover letter.

Cover letter national language version (NLV). The NLV corresponds to a code that indicates the language in which the cover letter was written. For more information on NLVs, see the Globalization topic in the iSeries Information Center.

Cover letter records. The record containing the cover letter information.

Cover letter status. Whether a cover letter exists for the PTF. The following values are valid.

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:

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.

Current server IPL source. The copy of the server firmware that was used on the previous server IPL.

Dependent load ID. The load ID of the dependent PTF. This value is blank when the load ID of the dependent PTF cannot be determined.

Dependent maximum level. The indicator of the highest level of the product for which this PTF can be installed. This field will be blank if the product has no level.

Dependent minimum level. The indicator of the lowest level of the product for which this PTF can be installed. This field will be blank if the product has no level.

Dependent option. The product option of the dependent PTF. This value is blank when the option of the dependent PTF cannot be determined.

Dependent product ID. The product ID of the dependent PTF.

Dependent PTF ID. The PTF ID of the dependent PTF.

Dependent PTF record. The information about the dependent PTF. The record is an array that contains the fields in format PTFR0500.

Error indicator about CCSID conversion. Whether the CCSID conversion to the requested CCSID was successful. If the requested CCSID conversion fails, the CCSID in which the directories are returned is identified in the CCSID of returned directories field. This field is used only for subobject attributes of DIR (directory) and SOM (system object model). Possible values follow:

Exit program library. The name of the library containing the exit program.

Exit program name. The name of a program that will be run at certain stages of the PTF process.

Exit program record. The information about the exit program. The record is an array that contains the fields in format PTFR0800.

Exit program run option.

The stage of the PTF process in which the exit program will be run. Possible values follow:

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.

File name. The name of the file where the save file for the PTF is located. If no save file name has been reserved, this field will be blank.

Format information available. When you request information using formats PTFR0300, PTFR0400, PTFR0600, PTFR0700, PTFR0800, PTFR0900, or PTFR1000 this field indicates whether the system has the information available to return for the PTF. The system may not be able to return the requested information if the PTF is permanently applied or superseded and does not have a save file. The possible values are:

IPL action. The action to be taken on this PTF during the next IPL. The following values are valid:

Length of APAR record. The length of each APAR record.

Length of cover letter record. The length of each cover letter record.

Length of dependent PTF record. The length of each dependent PTF record.

Length of exit program record. The length of each exit program record.

Length of precondition record. The length of each precondition record.

Length of PTF object record. The length of one array element in the PTF object record.

Length of requisite record. The length of each requisite record.

Length of subobject name. The length of the subobject name.

Length of subobject record. The length of one array element in the subobject record.

Length of superseded PTF record. The length of each superseded PTF record.

Length of symptom string data. The length of the returned symptom string.

Length of symptom string record. The length of each symptom string record.

Length of exit program user data. The length of the returned exit program user data string.

Licensed Internal Code Group. The name of the Licensed Internal Code Group for this PTF. If the name of the group is not available or if the PTF is not a Licensed Internal Code fix, this field will be blank.

Loaded status. The current loaded status of the PTF. A PTF can have any of the following statuses:

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.

This field may be blank.

Load ID. The load ID of the product load for the PTF.

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.

Number of APAR records. The number of returned APAR records.

Check the format information available field returned in PTFR0100 before using this value. The number of APARs will be zero when the system cannot determine if this PTF has APARs.

Number of dependent PTFs. The number of dependent PTFs available. The receiver variable may not have been large enough to hold all the dependent PTF records. If so, the number of dependents returned may be less than this value.

Number of different NLVs available for the cover letter. Cover letter member names are returned in an array. This number indicates how many NLVs were available for the cover letter. However, the length of the receiver may not have been large enough to hold all the cover letter NLVs available. If so, the number of cover letter member names returned may be less than this value.

Number of exit program records. The number of exit program records. The receiver variable may not have been large enough to hold all the exit program records. If so, the number of exit programs returned may be less than this value.

Check the format information available field returned in PTFR0100 before using this value. The number of exit programs will be zero when the system cannot determine if this PTF has any exit programs.

Number of precondition records. The number of returned precondition records.

Check the format information available field returned in PTFR0100 before using this value. The number of precondition records will be zero when the system cannot determine if this PTF has preconditions.

Number of PTF objects. The number of PTF objects available. The receiver variable may not have been large enough to hold all the PTF object records. If so, the number of PTF objects returned may be less than this value.

Check the format information available field returned in PTFR0100 before using this value. The number of objects will be zero when the system cannot determine the number of objects contained in this PTF.

Number of PTF subobjects. The number of PTF subobjects associated with this PTF object. The receiver variable may not have been large enough to hold all the PTF subobject records. If so, the number of PTF subobjects returned may be less than this value.

Number of requisites. The number of requisite PTFs available. The receiver variable may not have been large enough to hold all the requisite PTF records. If so, the number of requisites returned may be less than this value.

Check the format information available field returned in PTFR0100 before using this value. The number of requisites will be zero when the system cannot determine if this PTF has requisite PTFs.

Number of superseded PTF records. The number of superseded PTF records. The receiver variable may not have been large enough to hold all the superseded PTF records. If so, the number of superseded PTFs returned may be less than this value.

Check the format information available field returned in PTFR0100 before using this value. The number of superseded PTF records will be zero when the system cannot determine if this PTF has any superseded PTFs.

Number of symptom string records. The number of returned symptom string records.

Check the format information available field returned in PTFR0100 before using this value. The number of symptom strings will be zero when the system cannot determine if this PTF has symptom strings.

Object library. The primary library where PTF objects will be placed for this product. If the product was installed in the primary library, this is the library where the PTF objects will reside.

Note: If the product was installed in a library other than the primary library, the API user might need to determine the installed library that corresponds to this primary library by using format PRDR0200 of the Retrieve Product Information (QSZRTVPR) API.

Object name. The name of the object that is contained in the PTF.

Object type. The symbolic type of the object that is contained in the PTF.

Offset to additional information. The offset from the beginning of the receiver variable to the start of either the cover letter information or the requisite information. This is to allow expansion of the basic information.

Offset to exit program user data. The offset from the beginning of the receiver variable to the start of the exit program user data.

Offset to first APAR record. The offset from the beginning of the receiver variable to the start of the APAR record.

Offset to first cover letter record from the beginning. The offset from the beginning of the receiver variable to the first cover letter record.

Offset to first dependent PTF record. The offset from the beginning of the receiver variable to the start of the first dependent PTF record.

Offset to first exit program record The offset from the beginning of the receiver variable to the start of the first exit program record.

Offset to first precondition record. The offset from the beginning of the receiver variable to the first precondition record.

Offset to first PTF object record. The offset from the beginning of the receiver variable to the start of the PTF object record.

Offset to first requisite record. The offset from the beginning of the receiver variable to the start of the first requisite record.

Offset to first superseded PTF record The offset from the beginning of the receiver variable to the start of the first superseded PTF record.

Offset to first symptom string record. The offset from the beginning of the receiver variable to the start of the first symptom string record.

Offset to subobject name. The offset from the beginning of the receiver variable to the start of the subobject name.

Offset to symptom string data. The offset from the beginning of the receiver variable to the start of the symptom string data.

Offset to this PTF object's first subobject record. The offset from the beginning of the receiver variable to the start of the first PTF subobject record.

On-order status. Whether the PTF has been ordered. The following values are valid:

Post-apply or post-remove considerations. Whether the cover letter contains special instructions that should be followed after applying or removing the PTF.

Pre-apply or pre-remove considerations. Whether the cover letter contains special instructions that should be followed prior to applying or removing the PTF.

Precondition library name. The name of the library for the precondition object. This field contains blanks when the precondition type is *JOB, *SBS, *RSTD, or *JVM.

Precondition name. The name of the object, job, or subsystem for which the precondition exists. The name can be either a specific name or a generic name. A generic name is a character string that contains one or more characters followed by an asterisk(*). The field contains blanks when the precondition type is *RSTD or *JVM.

Precondition record. The information about the precondition. Precondition records identify objects, jobs, or subsystems that cannot be active when this PTF is temporarily applied or removed immediately. The record is an array that contains the fields in format PTFR0900.

Precondition type. The type of the object indicated in the precondition name. Possible values are:

Product ID. The PTF is for this product. The product must be installed or supported.

Product option. The PTF is for this option of the product.

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 licensed product 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 are:

PTF object record. The information about the PTF objects. The record is an array that contains the fields described in format PTFR0400.

This information is available only if the PTF is loaded, temporarily applied, or has a save file.

PTF subobject record. The information about the PTF subobjects. The record is an array that contains the fields described in format PTFR0400.

PTF type. The type of PTF. The possible values are:

Release level. The release of the PTF. It must be in the format of VxRyMz. Valid entries for x and y are any number between 0 and 9. Valid entries for z is any number between 0 and 9 or a character between A and Z.

Release of dependent PTF. The release of the dependent PTF.

Release of requisite. The release of the requisite PTF.

Requisite is conditional. Whether the requisite relationship is conditional. Users should check this field to determine whether it is necessary to check a remote system for the presence of the software that is described in the product ID, release, option, and load ID.

Requisite is required. Whether a requisite PTF is required on this system. The possible values are:

Requisite load ID. The load ID of the requisite PTF. This value may be blank when the load ID of the requisite PTF cannot be determined.

Requisite option. The product option of the requisite PTF. This value may be blank when the option of the requisite cannot be determined.

Requisite maximum level. The indicator of the highest level of the product on which this PTF can be installed. This field will be blank if the product has no level.

Requisite minimum level. The indicator of the lowest level of the product on which this PTF can be installed. This field will be blank if the product has no level.

Requisite product ID. The product ID of the requisite PTF.

Requisite PTF ID. The PTF ID of the requisite PTF.

Requisite record. The information about the requisite. The record is an array that contains the fields in format PTFR0300.

Reserved. This field is ignored.

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:

Server IPL required. Indicates whether or not a server IPL must be performed in order to activate the changes for the PTF. The possible values are:

Status date and time. The date and time the PTF status was last changed. This field will be blank when the status date and time is not available. The date and time field is in the CYYMMDDHHMMSS format:

Subobject attribute. The type of subobject contained in the PTF. The possible values follow:

Subobject name. The name of the subobject. This is a name of an object that is not limited to 10 characters.

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.

Superseded PTF ID. The identifier of a PTF that is superseded by this PTF.

Superseded PTF record. The information about the superseded PTFs. The record is an array that contains the fields in format PTFR1000.

Superseding PTF. 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.

Symptom string data. The symptom string for the problems fixed by this PTF.

Symptom string record. The information about the symptom string. The record is an array that contains the fields in format PTFR0700.

Target release. The earliest release of the operating system on which you can load and apply the PTF. The release level is specified in the format VxRyMz, where Vx is the version, Ry is the release, and Mz is the modification level.

Type of dependent PTF. The type of dependent relationship. The possible values are:

Type of requisite. The type of requisite relationship. The possible values are:

Error Messages