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.
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.
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.
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.
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
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
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.
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.
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.
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 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:
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 &3 contains
common objects.
CPF3507 E
Corequisite PTF &1-&2 &3 not
specified.
CPF3509 E
Specified corequisite PTF &1-&2 &3
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 &3 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 &3 not created.
CPF9872 E
Program or service program &1 in library
&2 ended. Reason code &3.
manual.
5