Control PTF Order (QESCPTFO) API

The Control PTF Order (QESCPTFO) API allows you to prepare an order for:

• Individual PTFs
• Cumulative PTF package
• PTF Group
• Summary information for available PTFs
• Preventive Service Planning (PSP) information

This API is restricted to be used for PTFs for V5R3M0 and above.

Authorities and Locks

Data Queue Authority

*OBJOPR and *ADD

Data Queue Library Authority

*EXECUTE

Directory Authority

Authority to the path and file are determined by the open() API. For details, see the Authorities section of the open()--Open File API for files opened with an access mode of O_WRONLY and O_TRUNC.

Required Parameter Group

PTF order information

INPUT; CHAR(*)

The information of the PTF order. The format of this information depends on the specified Format of PTF order information.

Length of PTF order information

INPUT; BINARY(4)

The size of the PTF order information variable

Format of PTF order information

INPUT; CHAR(8)

The format of the PTF order information specified. You must use one of the following format names:

PTFO0100	Process PTF order. The information of the PTF order is described by PTFO0100 Format.
PTFO0200	Resume PTF order. The information of the PTF order is described by PTFO0200 Format.
PTFO0300	Cancel PTF order. The information of the PTF order is described by PTFO0300 Format.

Contact information

INPUT; CHAR(*)

The contact information to be used by your service representative to contact you or send you service information. The format of this information depends on the specified Format of contact information.

Length of contact information

INPUT; BINARY(4)

The size of the contact information variable. If zero is specified, the existing contact information in the system is passed to the service provider. Zero can only be specified when CNTC0000 is specified for the format of contact information.

Format of contact information

INPUT; CHAR(8)

The format of the contact information specified. You must use one of the following format names:

CNTC0000	No contact information is provided. The existing contact information in the system is passed to the service provider. Length of contact information parameter should be set to zero.
CNTC0100	The contact information is described by CNTC0100 Format.

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the actual list of PTFs delivered. The format of this information depends on the specified Format of receiver variable.

Length of receiver variable

INPUT; BINARY(4)

The size of the receiver variable. If the receiver variable is not large enough to hold the complete list of PTFs delivered, the returned list is truncated.

Format of receiver variable

INPUT; CHAR(8)

The format of the returned information. You must use one of the following format names:

PTFD0100

The information returned is described by PTFD0100 Format.

Error code

I/O; CHAR(*)

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

PTFO0100 Format

The following information is to be passed on PTF order information parameter to process a new PTF order. For a detailed description of each field, see Field Descriptions.

PTFO0200 Format

The following information is to be passed on PTF order information parameter when resuming a PTF order. For a detailed description of each field, see Field Descriptions.

PTFO0300 Format

The following information is to be passed on PTF order information parameter when cancelling a PTF order. For a detailed description of each field, see Field Descriptions.

CNTC0100 Format

Use this format to include contact information on the PTF order. For detailed descriptions of the fields in this table, see Field Descriptions

PTFD0100 Format

The following information is to be returned in the receiver variable on a process order request or on a resume order request. For a detailed description of each field, see Field Descriptions.

Field Descriptions

Alternative electronic mail address. The electronic mail (e-mail) address for the contact person, if the primary electronic mail address is not available.

Alternative Fax number. The complete telephone number where information for the contact can be faxed, if the primary fax number is not available. This number should include the area code, exchange numbers, and the extension.

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Check. Indicates whether checking is performed on the service requester system to determine if PTFs are ordered based on whether or not the PTF product is installed or supported. Possible values are:

Note: *NO must be specified when *CVRLTR is specified for PTF parts to order.

City or locality. The city or locality name for the location to which you want your service provider to send parts or assistance.

Company name. The name of the organization that owns or is responsible for this system. The name should appear in this field as it appears on a mailing label.

Contact name. The name of the person in your organization who is responsible for repairs and maintenance on the system. This person may be called by the service provider with information or assistance for a system problem. Also, parts or PTFs may be sent to this person.

Country or region. The country or region where the company is located to which the service provider should send parts or assistance.

Delivery format. Specifies the format the PTFs are stored. Possible values are:

Delivery method. Specifies how the PTFs are delivered. Possible values are:

Delivery mode. Specifies how the PTFs were delivered. Possible values are:

Help desk or pager number. The complete Help desk or pager number. This number should include the area code, exchange numbers, and the extension.

Image directory. The path name of the directory where optical image files will be saved. For more information on specifying path names, refer to "Object naming rules" in "CL concepts and reference" in the CL reference information in the iSeries Information Center at http://www.iseries.ibm.com/infocenter. The following special value is accepted:

Image prefix. The prefix for the optical image file names. If multiple images are received under one order, the files will be uniquely identified by a numerical suffix on the image name. This field must be set to blanks if *IMAGE is not specified for delivery format. The following special value is accepted:

Length of alternative electronic mail address. The length of the alternative electronic mail address.

Length of fixed size order information. The length of the fixed portion of the structure passed with the order information.

Length of image directory. The length of the image directory, in bytes. This field must be set to zero if *IMAGE is not specified for delivery format.

Length of primary electronic mail address. The length of the primary electronic mail address.

Length of PTFs being delivered entry. The length of the information for each PTF being delivered.

Length of PTFs ordered entry. The length of the information required for each PTF ordered.

Library of status data queue. The library where the status data queue is located. This field must be set to blanks if the name of status data queue field is set to blanks.

Maximum order size. The maximum size in megabytes of the order to be delivered electronically. If the order size exceeds the specified value, the action to be taken depends on the value specified in the delivery method field. A value of 100 MB (MB equals approximately 1 000 000 bytes) is used if a lower value is specified. If -1 is specified for this parameter, orders of any size can be delivered electronically.

Media for mailing PTFs. The media currently used for mailing program temporary fixes (PTFs). The media options available are:

Name of status data queue. The name of a FIFO (first-in first-out) data queue where the download status is sent. This field must be set to blanks if no status is necessary. See Usage Notes for information about the status data queue.

National language version. The national language version code currently being used for PTF cover letters. If the cover letter you ordered has not been translated into this language the cover letter will be sent in U.S. English.

Number of PTFs being delivered. The total number of PTFs being delivered.

Number of PTFs ordered. The total number of PTFs in the order. At least one PTF must be ordered.

Offset to alternative electronic mail address. The offset to the alternative electronic mail address.

Offset to image directory. The offset to the image directory of the directory where optical images will be saved. This field must be set to zero if *IMAGE is not specified for delivery format.

Offset to primary electronic mail address. The offset to the primary electronic mail address.

Offset to PTFs being delivered. The offset to the information of the first PTF being delivered.

Offset to PTFs ordered. The offset to the information of the first PTF to be ordered.

Order identifier. The unique identifier of the order. This identifier is the same as the problem ID of the problem created when the order was requested.

Order preparation time. The time in minutes that the service provider will take to prepare the order before it is available to be downloaded.

Order status. Specifies the order status. Possible values are:

Postal code. The Postal code for the location to which the service provider should send parts or assistance.

Primary electronic mail addresses. The electronic mail (e-mail) address for the contact person.

Primary fax number. The complete telephone number where information for the contact can be faxed. This number should include the area code, exchange numbers, and the extension.

Primary telephone number. The complete telephone number where the person named for the Contact may be reached most often. This number should include the area code, exchange numbers, and the extension.

Product. The 7-character product identifier of the product that the PTF is associated with. If the PTF identifier is associated with more than one product, the PTF order is limited to the product specified. The following special value is accepted if this is an input field:

PTF identifier ordered. The PTF identifier. Some PTFs must be ordered individually or within a list of PTFs with the same prefix and not as part of a general list.

A cumulative PTF package (CUM) is specified using the format SF99vrm and the Preventive Service Planning (PSP) format is SF98vrm, where vrm is version-release-modification.

The following special values are accepted if this is an input field:

PTF identifier sent. The PTF identifier.

PTF parts to order. Indicates whether PTFs or cover letters are being ordered. Possible values are:

Release. The 6-character release level in VxRyMz format where Vx is the version number, Ry is the release number, and Mz is the modification level. The variables x and y can be a number from 0 through 9, and the variable z can be a number from 0 through 9 or a letter from A through Z. The following special value is accepted if this is an input field:

Reorder. Indicates whether a PTF that is currently loaded, applied, or on order should be ordered again. Possible values are:

Note: A PTF is not reordered if the *SAVF delivery format is specified and a save file is available on the system.

Requisites. The level of fixes that are being requested. Possible values are:

Reserved. A reserved field. Should be set to null (x'00').

State or province. The state or province names for the location to which you want your service provider to send parts or assistance.

Street address lines 1, 2 and 3. The postal number and street name of the location to which you want your service provider to send parts or assistance for the problem. This should not be a post office box.

Update interval. The time in seconds that indicates how often download status is updated in the data queue when PTFs are being downloaded. This field must be set to zero if the name of status data queue field is set to blanks. See Usage Notes for information about the status data queue.

Wait time for order completion. The time in minutes that the connection with the service provider should remain active while the order is being prepared for download. If this value is greater than or equal to the order preparation time field, the connection will remain active and the download process will be started automatically when the order is ready. Otherwise, the connection with the service provider will be closed and a request to resume the order should be submitted at a later time. If -1 is specified, the connection will remain active as much time as necessary while the order is being prepared.

Usage Notes

1. Only one job on the system can invoke QESCPTFO API at a time.
2. When processing a PTF order, and the delivery format is *SAVF, the API will return control to the caller when all PTF save files are delivered. When the delivery format is *IMAGE, the API will return control to the caller depending on the order preparation time and the wait time for order completion fields. If the order preparation time is greater than the wait time for order completion, the order is set to *WAIT status, the API will return control to the caller and a request to resume the order should be submitted after the time indicated by order preparation time field. Otherwise, the API will return control to the caller when the optical image files are delivered.
3. Information about the download status is sent to the status data queue specified and updated at intervals specified in the update interval field. The download progress can be checked by monitoring the status data queue in a different thread or process. The following table shows the format for the status data. For a detailed description of each field, see Field Descriptions.

   Offset		Type	Field
   Dec	Hex
   0	0	CHAR(10)	Message identifier
   10	A	CHAR(2)	Message format
   12	C	CHAR(*)	Message status data

Field Descriptions

Message identifier. The identifier of the message sent to the queue. Possible values are:

Message format. The format of the message data in the queue. Possible values are:

Message status data. The information of the data sent to the queue. This information depends on the message format field. If the message status data exceeds the maximum entry length of the data queue, the information is truncated.

If the message format field is '01', then the message status data has the following format:

If the message format field is '02', then the message status data has the following format:

Bytes downloaded. The number of bytes that has been already downloaded.

Order size. The number of bytes to be delivered for the order.

Order identifier. The unique identifier of the order this message is associated with. This identifier is the same as the problem ID of the problem created when the order was requested.

Receiver format name. The format specified for the format of receiver variable parameter.

Receiver variable structure. The actual list of PTFs delivered as specified by the format of receiver variable.

Error Messages

The following messages may be sent from this function: