Create Program Temporary Fix (QPZCRTFX) API

This API should only be used by organizations to create program temporary fixes (PTFs) for products that they develop.

The Create Program Temporary Fix (QPZCRTFX) API creates a PTF save file and optionally creates cover letters in the general purpose library (QGPL). The save file contains a PTF control object and any number of fix objects. The save file name is the PTF identifier preceded by the letter Q. If a file with the same name already exists in QGPL, a unique name is generated by the system. This name is a timestamp preceded by the letter Q. After creating the PTF, you can use the Display PTF (DSPPTF) command to view the PTF attributes.

PTFs can only be created for products that are installed.

PTFs must be created by a profile that is known to exist on all systems. This allows a PTF to be loaded on any system that has the product installed.

Authorities and Locks

API Public Authority

*EXCLUDE

Create library (CRTLIB) command

*USE authority to the command and all authorities required by the command.

Create save file (CRTSAVF) command

*USE authority to the command and all authorities required by the command.

The following authorities are required when specifying the indicated input parameter:

Cover Letter Parameter

*USE authority to input cover letter file

*EXECUTE authority to input cover letter library

*OBJOPR, *OBJMGR, *ADD, *DLT authority to the QAPZCOVER file in library QGPL

Object Parameter

*CHANGE authority to the object

*EXECUTE authority to the development library

Exit program parameter

*CHANGE authority to the exit program

*EXECUTE authority to the exit program library

Document parameter

*USE authority to the SAVDLO command and all authorities required by the command.

Directory information parameter

*USE authority to the SAV command and all authorities required by the command.

*USE authority to the CPY command and all authorities required by the command.

*USE authority to the CRTDIR command and all authorities required by the command.

Required Parameter Group

PTF information

INPUT; CHAR(50)

Attributes of the PTF to be created. See PTF Information Format for more information about this field.

Development library name

INPUT; CHAR(10)

The library in which the fix is located. This can be any library.

Objects

INPUT; ARRAY(*) of CHAR(20)

The name and type of each object to be included in the PTF. The first 10 characters contain the name, and the second 10 characters contain the external type of the object.

Object name	The name of the object.
Object type	The external type of the object. This must be preceded by an asterisk (*). For more information, refer to the System Manager Use book.

Number of objects

INPUT; BINARY(4)

The number of objects listed in the objects parameter. This number must be in the range of 0 through 300.

Documents

INPUT; ARRAY(*) of CHAR(73)

The name of the documents that are to be included in the PTF.

The create PTF function copies the document from a subfolder using the name specified, followed by /QP. For example, if a PTF is being created for a product folder called PRODUCT, the fix objects must be developed in a subfolder named PRODUCT/QP. The document is installed into the product folder PRODUCT during the apply PTF operation. The QP subfolder allows you to develop a PTF without changing the product.

Document name

The name of the document including the path name.

Number of documents

INPUT; BINARY(4)

The number of documents listed in the documents parameter. This number must be in the range of 0 through 300.

Requisite PTFs

INPUT; ARRAY(*) of CHAR(24)

The list of requisite PTFs. A requisite relationship exists when one PTF requires that another PTF also be applied. It is a prerequisite relationship if the other PTF does not require the first. It is a corequisite relationship if the other PTF does require the first. Prerequisite PTFs must exist within the same product. A prerequisite PTF must already exist on the system or the create operation will fail. Corequisite PTFs must exist within the same product, option, load id, and release.

For more information on this structure, see Requisite PTF Format.

Number of requisite PTFs

INPUT; BINARY(4)

The number of PTFs listed in the requisite PTFs parameter. This number must be in the range of 0 through 300.

Exit programs

INPUT; ARRAY(*) of CHAR(84)

The PTF exit programs called when a PTF is temporarily applied, permanently applied, temporarily removed, or permanently removed. Exit programs eliminate the need for you to manually carry out special instructions to install the PTF. The run option field of this parameter determines when the exit program is called.

Shipping the same exit program in two PTFs causes one PTF to supersede the other.

For more information on this structure, see Exit Programs Format and Program Temporary Fix Exit Program.

Number of exit programs

INPUT; BINARY(4)

The number of exit programs listed in the exit programs parameter. This number must be in the range of 0 through 50.

Problem IDs

INPUT; ARRAY(*) of CHAR(10)

A list of the problem IDs for problems that this PTF fixes. By listing the problem IDs, the symptom strings associated with those problems will be included in the PTFs.

Number of problem IDs

INPUT; BINARY(4)

The number of problem IDs listed in the problem IDs parameter. This number must be in the range of 0 through 300.

Cover letters

INPUT; ARRAY(*) of CHAR(44)

A cover letter can be created for each of the national language versions (NLV) that IBM supports. A member that contains source for each PTF cover letter must be supplied as input to the API. The cover letter file can be a source file with a maximum record length of 92 or a physical file with record length of 80. The cover letter must be in the file before this API is called. Only one cover letter per NLV is allowed.

For more information on this structure see Cover Letter Format.

Number of cover letters

INPUT; BINARY(4)

The number of cover letters listed in the cover letter parameter. This number must be in the range of 0 through 50.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Optional Parameter Group 1

Directory information

INPUT; Array(*) of CHAR(*)

Identifies the information for directory objects that are included in the PTF. See Directory Information Format for more information about this field.

Number of directories

INPUT; BINARY(4)

The number of directories listed in the directory information parameter. This number must be in the range of 0 through 30.

Optional Parameter Group 2

Additional parameter information

INPUT; CHAR(*)

The additional information to use when creating this PTF.

Additional parameter information format name

INPUT; CHAR(8)

The format of the data specified in the additional parameter information. The possible format name is:

PTFC0100

The format contains information to create a PTF that contains job preconditions and object preconditions. For details, see PTFC0100 Format.

PTF Information Format

For detailed descriptions of each field, see Field Descriptions.

Requisite PTF Format

Each entry in the array for the requisite PTFs parameter has the following format. For detailed descriptions of each field, see Field Descriptions.

Exit Programs Format

Each entry in the array for the exit programs parameter has the following format. For detailed descriptions of each field, see Field Descriptions.

Cover Letter Format

Each entry in the array for the cover letter parameter has the following format. The information must be presented in the order listed below. The exact offsets for each entry are not given. For detailed descriptions of each field, see Field Descriptions.

Directory Information Format

Each record in the array for the directory information parameter has the following format. The information must be presented in the order listed below. The exact offsets for each entry are not given. For detailed descriptions of each field, see Field Descriptions.

The following restrictions exist when you are assigning directory names:

• You cannot specify /QSYS.LIB or /QDLS directories.
• You must specify unique path names.
• Do not begin or end the path name with a forward slash.
• Do not use a blank in the directory path name.
• Do not use any of the character combinations of "." or ".." in the directory path name.

Directory Object Information Record Format

Each record in the array for the directory object information parameter has the following format. The information must be presented in the order listed below. The exact offsets for each entry are not given. For detailed descriptions of each field, see Field Descriptions.

PTFC0100 Format

This information defines the format for the additional parameter information when the additional parameter information format name is PTFC0100. For detailed descriptions of each field, see Field Descriptions.

Job Precondition Record

An array containing the names of the jobs or subsystems that must not be active when the PTF is being immediately applied or removed temporarily. When this PTF is applied or removed and this job or subsystem is active, the PTF will not be allowed to be processed.

Note: PTF processing will not prevent the job or subsystem from becoming active after this check is made, but before the PTF is actually processed.

Each record in the job preconditions array has the following format. The information must be presented in the order listed below. The exact offsets for each entry are not given. For detailed descriptions of each field, see Field Descriptions.

Object Precondition Record

An array containing the names of the objects that must not be allocated when the PTF is being immediately applied or removed temporarily. When this PTF is applied or removed and this object has active or waiting locks, the PTF will not be allowed to be processed.

Note: PTF processing will not prevent the object from being allocated after this check is made, but before the PTF is actually processed.

Each entry in the object preconditions array has the following format. The information must be presented in the order listed below. The exact offsets for each entry are not given. For detailed descriptions of each field, see Field Descriptions.

Field Descriptions

Cover letter file name. The name of the file where the cover letter can be located.

Cover letter library name. The name of the library where the cover letter file can be located.

Cover letter member name. The member name that contains the cover letter.

Development directory name. The name of the directory where the directory objects that will be in the PTF reside. The possible special value is:

Directory information record. The information about each directory for this PTF.

Directory object information record. The information about the objects for this directory.

Directory object name. The name of the directory object to include in the PTF.

Exit program library name. The library where the exit program can be found. If the exit program is part of the PTF, this is the library in which it exists currently. If the exit program is part of the product, this is the primary library where the exit program exists.

Exit program name. The name of the exit program.

Exit program type. Whether the exit program is to be included in this PTF. The possible values are:

Length of each job precondition record. The length of the job precondition record. The length must be set to 11.

Length of each object precondition record. The length of the object precondition record. The length must be set to 30.

Length of the development directory name. The length of the development directory name. The length of a development directory cannot exceed 240 characters.

Length of the directory object name. The length of the directory object name. The length of a directory object exceed 255 characters.

Length of the product directory name. The length of the product directory name. The length of a product directory cannot exceed 240 characters.

Load ID. The load ID of the product load for the PTF. This will be a language load if the PTF is for textual data, or it will be the code load.

Number of directory objects. The number of objects that exist in the array of directory object information records. This number must be in the range of 1 through 100.

Number of job precondition records. The number of job preconditions that exist. This number must be in the range of 0 through 300.

Number of object precondition records. The number of object preconditions that exist. This number must be in the range of 0 through 300.

NLV. The NLV of the cover letter. This must be a valid system NLV.

Offset to the development directory name. The byte offset from the beginning of the directory information parameter to the beginning of the name of the development directory.

Offset to the first directory object information record. The byte offset from the beginning of the directory information parameter to the first directory object information record.

Offset to the first job precondition record. The byte offset from the beginning of the additional information parameter to the beginning of the first job precondition record.

Offset to the first object precondition record. The byte offset from the beginning of the additional information parameter to the beginning of the first object precondition record.

Offset to the next directory information record. The byte offset from the beginning of the directory information parameter to the beginning of the next directory information record.

Offset to the product directory name. The byte offset from the beginning of the directory information parameter to the beginning of the name of the product directory.

Precondition library name. The name of the library where the object specified in the precondition object name field resides.

Precondition name. The name of the job or subsystem that must not be active when this PTF is temporarily applied or removed immediately. A specific name or a generic name can be specified. This field must be blanks when the precondition type is 3 or 4.

Precondition object name. The name of the object that must not be allocated when this PTF is applied temporarily or removed immediately. A specific name or a generic name may be specified.

Precondition object type. The type of the object specified in the precondition object name field.

Precondition type. The type of the precondition specified in the precondition name. The possible values are:

Primary object library name. The library in which the objects are to be placed when the PTF is applied. If necessary, the PTF apply operation maps the primary library that is specified when the PTF was created in the actual installed library. Two cases where this is important are:

• The product load has been installed into a secondary language library.
• Dynamic library renaming was used when the product was installed.

Product directory name. The name of the directory defined by the product that is the default directory where the objects will reside when the PTF is applied. The length of a product directory cannot exceed 240 characters.

Product ID. The product for which the PTF is being created. This product must be installed on the system.

Product option. The option of the product for which the PTF is being created. All objects in the PTF must be for the same option and the same library within the option.

PTF ID. The ID by which the PTF is to be known. The identifier must be 7 characters. The first character must be numeric. The second and third characters must be alphabetic. The same identifier can be used only once for each product and release level.

Release level. The version, release, and modification level of the product in the format VxRyMz. Valid values for x and y are 0 through 9, and valid values for z are 0 through 9 or A through Z.

Requisite type. The type of requisite relationship. If this is blank, a prerequisite relationship is assumed. The possible values are:

Reserved. An error will be signaled if this field does not contain blanks.

Run option. When the exit program is to be run. The possible values are:

Target release. The earliest release of the operating system on which you intend to load and apply the PTF. This must be left-justified. If this is blank, the current release is assumed. The possible special values follow:

User data. Any data you want to pass to the exit program.

Error Messages