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 manual.

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.

Offset		Type	Field
Dec	Hex
0	0	CHAR(7)	PTF ID
7	7	CHAR(7)	Product ID
14	E	CHAR(6)	Release level
20	14	CHAR(4)	Product option
24	18	CHAR(10)	Primary object library name
34	22	CHAR(4)	Load ID
38	26	CHAR(6)	Target release
44	2C	CHAR(6)	Reserved

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.

Offset		Type	Field
Dec	Hex
0	0	CHAR(7)	PTF ID
7	7	CHAR(16)	Reserved
23	17	CHAR(1)	Requisite type

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.

Offset		Type	Field
Dec	Hex
		CHAR(10)	Exit program name
		CHAR(10)	Exit program library name
		CHAR(7)	Run option
		CHAR(7)	Exit program type
		CHAR(50)	User data

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.

Offset		Type	Field
Dec	Hex
		CHAR(10)	Cover letter file name
		CHAR(10)	Cover letter library name
		CHAR(10)	Cover letter member name
		CHAR(4)	NLV
		CHAR(10)	Reserved

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.
• Do not use any of the character combinations of "." or ".." in the directory path name.

Offset		Type	Field
Dec	Hex
		Array of CHAR(*)	Directory information record
		BINARY(4)	Offset to the next directory information record
		BINARY(4)	Offset to the development directory name
		BINARY(4)	Length of the development directory name
		BINARY(4)	Offset to the product directory name
		BINARY(4)	Length of the product directory name
		BINARY(4)	Offset to the first directory object information record
		BINARY(4)	Number of directory objects
		CHAR(*)	Development directory name
		CHAR(*)	Product directory 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.

Offset		Type	Field
Dec	Hex
		Array of CHAR(*)	Directory object information record
		BINARY(4)	Length of directory object name
		BINARY(4)	Displacement to next directory object information record
		CHAR(*)	Directory object name

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Offset to first job precondition record
4	4	BINARY(4)	Number of job precondition records
8	8	BINARY(4)	Length of each job precondition record
12	C	BINARY(4)	Offset to first object precondition record
16	10	BINARY(4)	Number of object precondition records
20	14	BINARY(4)	Length of each object precondition record

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.

Offset		Type	Field
Dec	Hex
		CHAR(1)	Precondition type
		CHAR(10)	Precondition name
		CHAR(*)	Reserved

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.

Offset		Type	Field
Dec	Hex
		CHAR(10)	Precondition object name
		CHAR(10)	Precondition library name
		CHAR(10)	Precondition object type
		CHAR(*)	Reserved

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:

*PRDDIR

The development directory name is the same as the product directory name.

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.

Displacement to next directory object information record. The displacement, in bytes, from the beginning of the current directory object information record to the next directory object information record.

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:

*PTF	The exit program is to be included in the PTF. The exit program must exist in the library specified in the exit program library field.
*OBJLST	The exit program is part of the product and should not be included in the PTF. The exit program must exist in one of the following: The object list for the product, option, and load of the PTF being created. The principal library for the base option (*BASE) of the product.

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 1024 characters.

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

Length of the product directory name. The length of the product directory name. The length of a product directory cannot exceed 1024 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:

1	The precondition name indicates a job.
2	The precondition name indicates a subsystem.
3	The system must be in restricted state for this PTF to be immediately applied or removed. The precondition name field must be blanks when this value is specified.
4	No Java™ virtual machines can be active on the system in order to temporarily apply or temporarily remove this PTF immediately. Any new Java virtual machines will be prevented from being started during the apply or remove processing. The precondition name field must be blanks when this value is specified.
5	No integrated Web application server (IAS) can be active on the system in order to temporarily apply or temporarily remove this PTF immediately.

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.

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 of the product. 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.

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

1	The requisite PTF is a prerequisite of this PTF. The requisite PTF is required by this PTF, but it does not require this PTF. It cannot specify this PTF as a prerequisite. It must be applied before or with this PTF. If it is applied with this PTF, the system applies it first.
2	The requisite PTF is a corequisite of this PTF; it is required by this PTF, and it requires this PTF. It must specify this PTF as a corequisite. Corequisite PTFs must be applied together. When they are applied together, the system may apply either of them first.
(blank)	A value of 1 is assumed. The requisite PTF is a prerequisite of this PTF. The requisite PTF is required by this PTF, but it does not require this PTF.

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:

*BOTH	The exit program will be run at the end of apply and remove processing.
*APPLY	The exit program will be run at the end of apply processing.
*REMOVE	The exit program will be run at the end of remove processing.
*PREAPY	The exit program will be run before the PTF is applied and at the end of apply processing.
*PRERMV	The exit program will be run before the PTF is removed and at the end of remove processing.
*PREBTH	The exit program will be run before the PTF is removed and at the end of remove processing. It is also run before the PTF is applied and at the end of apply processing.

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:

*CUR	The PTF is to be loaded, applied to, and used on the release of the operating system currently running on your system. The PTF also can be applied on a system with any later release of the operating system installed.
*PRV	The PTF is to be loaded, applied to, and used on the previous release with modification level 0 of the operating system. The PTF also can be applied on a system with any later release of the operating system installed.
Target release	The release of the operating system on which you intend to 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. Valid values depend on the current version, release, and modification level, and they change with each new release. Note: This PTF can be loaded and applied on any release after the specified target release.

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

Error Messages

Message ID	Error Message Text
CPF24B4 E	Severe error while addressing parameter list.
CPF3CF1 E	Error code parameter not valid.
CPF3C29 E	Object name &1 is not valid.
CPF3C31 E	Object type &1 is not valid.
CPF3C90 E	Literal value cannot be changed.
CPF35BC E	Object type &1 not supported.
CPF35CC E	Library required for building PTFs already exists.
CPF35DA E	Folder &1 not valid.
CPF35DB E	Duplicate documents specified.
CPF35DC E	Primary library not found.
CPF35DD E	Problem &1 does not exist.
CPF35DF E	Value for target release not valid.
CPF35D3 E	Cover letter not copied.
CPF35D4 E	Cover letter file record length too long.
CPF35D5 E	Cover letter NLV not valid.
CPF35D6 E	Duplicate exit programs specified.
CPF35D8 E	Exit program &1 not valid.
CPF35D9 E	Duplicate objects specified.
CPF3505 E	Corequisite PTF &1-&2 &5 contains common objects.
CPF3507 E	Corequisite PTF &1-&2 &8 not specified.
CPF3509 E	Specified corequisite PTF &1-&2 &7 not valid.
CPF357A E	Parameter value not valid.
CPF357B E	Product not found.
CPF357D E	Document or folder name not correct.
CPF3570 E	No PTF IDs available in range.
CPF3571 E	PTF ID &1 not within valid range.
CPF3572 E	PTF &2-&1 &4 already exists.
CPF3573 E	Resources required for product &1 are not available.
CPF3574 E	PTF ID not valid.
CPF358A E	Release not valid.
CPF358B E	PTF not created.
CPF358C E	Create PTF not allowed for product &1.
CPF358D E	Run option not valid.
CPF358E E	Exit program type not valid.
CPF359C E	Requisite type not valid.
CPF35EC E	Duplicate requisites specified.
CPF3901 E	PTF &1-&2 &4 not created.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

---

API introduced: V2R3

---

[ Back to top | Software Product APIs | APIs by category ]