Change Problem Log Entry (QsxChangeProblemLogEntry) API

Required Parameter Group:

1	Handle	Input	Binary(4)
2	Key structures	Input	Array of Pointers
3	Number of keys	Input	Binary(4)
4	Error code	I/O	Char(*)

  Default Public Authority: *EXCLUDE

  Service Program: QSXSRVPL

  Threadsafe: No

The Change Problem Log Entry (QsxChangeProblemLogEntry) API updates an existing problem entry by changing the information. Key 1 (problem log ID) identifies the problem to be changed. Some data in the problem log entry can be changed on a field by field basis while other data can only be changed as a group and some data cannot be changed.

Authorities and Locks

API Public Authority: *USE

Required Parameter Group

Handle: INPUT; BINARY(4)
An identifier that associates the problem log services started with the QsxStartProblemLogServices API.
Key structures: INPUT; ARRAY of POINTERS
An array of pointers to the key structures being passed to the API.
Number of keys: INPUT; BINARY(4)
Number of keys passed to the API.
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 the Keys

The number of keys used varies depending on the type of problem log entry being changed. You must select the keys applicable to the problem type with which you are working. If the keys provided to the API do not match the requirements for the problem log entry type you are changing, you are notified by the error handling procedures.

For details about the keys that can be used, see Key Groups for Problem Log APIs.

Rules for Key Usage

You can change the problem log data, the status, or both. The problems are categorized into the following types:

1	Machine-detected problem
2	User-perceived hardware or software problem
3	PTF orders
4	User-perceived remote problem
5	Application-detected problem
6	Client machine-detected problem
7	Client user-detected problem
8	User-created general problem

Changing General Data

General data is data that can be changed for any problem type without affecting the status of the problem. Data of this class are:

Key 4 (user assigned). The validity of this data is not checked.
Key 3001 (text entry) problem types 1, 2, and 4 can be changed.
Key 6001 (history information). Use the Add Problem Log Entry (QsxAddProblemLogEntry) API.

Changing Problem Status

To change the problem status, specific data is required. The amount of data depends on the current or requested problem log status. Data that requires a status change cannot be added unless key 3 (problem status) is provided. An error is signaled if this occurs.

A problem can be changed to the following statuses:

OPENED
The beginning status of a problem.
OPENED-PREPARED
Problem is staged for transmission to a service provider.
READY
Problem entry has been analyzed and data is provided by keys that reflects the analysis results.
READY-PREPARED
Problem is staged for transmission to a service provider.
SENT
Problem has been sent to a service provider and a solution was not available.
SENT-PREPARED
Problem is staged for transmission to a service provider.
ANSWERED
Problem has been sent to a service provider and a solution was available.
ANSWERED-PREPARED
Problem is staged for transmission to a service provider.
VERIFIED
User has applied and tested the solution provided. The results of the testing are satisfactory. Once a problem is moved to VERIFIED status, it cannot be returned to OPENED or READY status.
VERIFIED-PREPARED
Problem is staged for transmission to a service provider.
CLOSED
Problem is resolved and there is no longer a need for the problem entry. Once this status is set, it cannot be returned to any other status. The problem can only be retrieved.

PREPARED, while displayed as a specific status, is actually an amplifier to the previous status of the problem: OPENED, READY, SENT, ANSWERED or VERIFIED.

The supplemental data needed to move a problem to PREPARED status are:

Key 6 (operational data)
- Prepared for system
  Required to define the system that this problem will be sent to.
Key 1001 (problem severity)
- Optional. If not provided, the API defaults it to None.
- Prohibited for PTF orders (problem type 3).
Key 1011 (PTF media selection)
Optional. Defines the media on which a program fix can be delivered. If not provided, the contact data is used as a default. Typically this is the tape device type and model or a description of the media type on which PTFs are delivered if the distribution size exceeds a predefined transmit size limit.
Key 5001 (contact information)
Optional. Used to override local service contact information.

A problem can be set to PREPARED status by providing the required data keys (if not already provided) and a key 3 (problem status) code of 5.

Keys for Changing Problem Type 1 to Another Status

Problem type 1 (machine-detected problems) requires data from two additional key groups, 1000 and 2000.

Note: When changing status and FRU entries are required, use the Add Problem Log Entry API. To change status in general, you do not need the key group 2000 data.

Data for OPENED status
A problem in OPENED status, with the exception of general data that does not affect a status change, can only be changed to READY status. A problem may be changed from the OPENED status to the PREPARED status if the problem is to be sent to a system that has System Manager installed.
Data for READY status
A problem can be changed from OPENED to READY status by including the following data items:
- Key 3 (problem status) indicates READY status.
- Key 1004 (reporting device) is always required to identify the product with a maintenance contract, regardless of the problem.
- Key 1006 (reporting code) is required for problems that were, on analysis, determined to be caused by software.
- Key 1010 (symptom string).
- Key 1007 (problem analysis data).
Data for SENT and ANSWERED status at the service requester
A problem can be changed to SENT or ANSWERED status by including the following data items:
- Key 3 (problem status) indicates SENT or ANSWERED status.
- Key 8 (answer codes).
  At the service requester the answer code assigned field should be updated with the answer received from a service provider that is not *IBMSRV.
  
  If *IBMSRV was the service provider, the Problem number field should be updated to reflect the problem management number that *IBMSRV has associated with the problem.
- Key 7001 (PTF ID) is used to change the Sent and Status fields.
Once the problem is in SENT or ANSWERED status, text can be added that defines the problem status. This is data that is added as a response to a query of the problem status or as an answer the service provider sends to the problem. This is done with key 3001 (text entry), type 3. Key 6001 (history information) is required to indicate the action has taken place.

If the local system is acting as a service provider, the problem log entry for the service requester can be updated to reflect the following conditions:
- A response was sent
- PTFs were sent
- An answer was added to the problem log
These actions do not require a status change. Add a history event to define the action taken.
Data for ANSWERED status at the service provider
When a service provider answers a problem, the status is changed from READY status to ANSWERED status by including the following data items:
- Key 3 (problem status) indicates ANSWERED status.
- Key 6001 (history information) can add a number of events depending on the status change.
- Key 7001 (PTF ID) is used to change the Sent and Status fields of the PTF entry.
Once the problem is in ANSWERED status, text can be added that defines the problem status. This is data that is added as a response to a query of the problem status or as an answer the service provider wants to add to the problem. This is done with key 3001 (text entry), type 3. Key 6001 (history information) is required to indicate the action has taken place.

When a response is sent to the service requester, key 6 (operational data) is used to indicate that a response was sent. The following data items are required:
- Key 8 (answer codes) is updated to indicate the answer that was sent to the service requester.
- Key 6001 (history information) can add a number of events depending on the status change.
- Key 7001 (PTF ID) is used to change the Sent and Status fields.
If PTFs were sent or an answer was added to the problem log, these actions do not require a status change. Add a history event to define the action taken.
Data for VERIFIED status
A problem can be changed to VERIFIED status from READY, SENT or ANSWERED status by including the following data items:
- Key 3 (problem status) indicates VERIFIED status.
- Key 1008 (fix verification status) where the Status field and PDP field must be provided.
- Key 6001 (history information) can add a number of events depending on the status change. The Remote verification ran field is required based on the origin system location.
- FRUs (key group 2000) are added for machine-detected problems and are added with the Add Problem Log Entry API.
Data for recovery
Recovery data can be added from OPENED or READY by including the following data items, and the status is not changed:
- Key 3 (problem status) is not permitted. The status does not change as a result of running recovery procedures.
- Key 1009 (fix recovery status) and problem determination procedures (PDP) fields must be provided.
- Key 6001 (history information) can add a number of events depending on the status change. Remote recovery ran is required based on the origin system location.
Data for CLOSED status
A problem can be changed to CLOSED status from any other status by including the following data items:
- Key 3 (problem status) indicates that CLOSED status is the only key allowed.
- Key 6 (operational data) is updated by the API when the problem is closed.

Keys for Changing Problem Types 2, 4, 5, and 8

Problem types 2 (User-perceived), 4 (User-perceived remote), 5 (Application-detected), and 8 (User-created general) require the following data to achieve the following status:

Data for OPENED status
This does not apply because these problem types are created in READY status.
Data for READY status
This does not apply because these problems are created in READY status.
Data for SENT and ANSWERED status at the service requester
A problem can be changed to SENT or ANSWERED status by including the following data items:
- Key 3 (problem status) indicates SENT or ANSWERED status.
- Key 8 (answer codes).
  At the service requester, the Answer code assigned field should be updated with the answer received from a service provider that is not *IBMSRV.
  
  If *IBMSRV was the service provider, the problem management number (PMR) number field should be updated to reflect the problem management number that *IBMSRV has associated with the problem.
- Key 6001 (history information) can add a number of events depending on the status change.
- Key 7001 (PTF ID) is used to change the Sent and Status fields.
Once the problem is in SENT or ANSWERED status, text can be added that defines the problem status. This is data that is added as a response to a query of the problem status or as an answer the service provider sends to the problem. This is done with key 3001 (text entry), type 3. Key 6001 (history information) is required to indicate the action has taken place.

If the local system is acting as a service provider, the problem log entry for the service requester can be updated to reflect that a response was sent, PTFs were sent, or that an answer is added to the problem log. These actions do not require a status change. Add a history event to define the action taken.
Data for ANSWERED status at the service provider
When a service provider answers a problem, the status is changed from READY status to ANSWERED status by including the following data items:
- Key 3 (problem status) indicates ANSWERED status.
- Key 6001 (history information) can add a number of entries depending on the status change.
- Key 7001 (PTF ID) is used to change the Sent and Status fields.
Once the problem is in ANSWERED status, text can be added that defines the problem status. This is data that is added as a response to a query of the problem status or as an answer the service provider wants to add to the problem. This is done with key 3001 (text entry), type 3. Key 6001 (history information) is required to indicate the action has taken place.

When a response is sent to the service requester, the problem log entry is updated to reflect that a response was sent. The following data items are required:
- Key 8 (answer codes) is updated to indicate the answer that was sent to the service requester.
- Key 6001 (history information) can add a number of events depending on the status change.
- Key 7001 (PTF ID) is used to change the Sent and Status fields.
If PTFs were sent or an answer was added to the problem log, these actions do not require a status change. Add a history event to define the action taken.
Data for CLOSED status
A problem can be changed to CLOSED status from any other status by including the following data items:
- Key 3 (problem status) indicates that CLOSED status is the only key allowed.
- Key 6 (operational data) is updated by the API when the problem is closed.

Keys for Changing Problem Type 3

Problem type 3 (PTF order) requires the following data to achieve the following status:

Data for OPENED status
This does not apply to PTF orders (problem type 3).
Data for READY status
This does not apply to PTF orders (problem type 3) because they are created in READY status.
Data for SENT and ANSWERED status at the service requester
A problem can be changed to SENT or ANSWERED status by including the following data items:
- Key 3 (problem status) indicates SENT or ANSWERED status.
- Key 8 (answer codes).
  At the service requester the Answer code assigned field should be updated with the answer received from a service provider that is not *IBMSRV.
  
  If *IBMSRV was the service provider, the Problem number field should be updated to reflect the problem management number that *IBMSRV has associated with the problem.
- Key 6001 (history information) can add a number of events depending on the status change.
- Key 7001 (PTF ID) is used to change the Sent and Status fields. This key is also used to update the product and VRM fields of the PTFs, especially if the default product, *ONLYPRD, and version, *ONLY, were used during the creation of the problem or if the SNDPTFORD command used the defaults.
Once the problem is in SENT or ANSWERED status, text can be added that defines the problem status. This is data that is added as a response to a query of the problem status or as an answer the service provider sends to the problem. This is done with key 3001 (text entry), type 3. Key 6001 (history information) is required to indicate the action has taken place.

If the local system is acting as a service provider, the problem log entry for the service requester can be updated to reflect that a response was sent, PTFs were sent, or that an answer is added to the problem log. These actions do not require a status change. Add a history event to define the action taken.
Data for ANSWERED status at the service provider
When a service provider answers a problem, the status is changed from READY status to ANSWERED status by including the following data items:
- Key 3 (problem status) indicates ANSWERED status.
- Key 6001 (history information) can add a number of events depending on the status change.
- Key 7001 (PTF ID) is used to change the Sent and Status fields.
Once the problem is in ANSWERED status, text can be added that defines the problem status. This is data that is added as a response to a query of the problem status or as an answer the service provider wants to add to the problem. This is done with key 3001 (text entry), type 3. Key 6001 (history information) is required to indicate the action has taken place.

When a response is sent to the service requester, the problem log entry is updated to reflect that a response was sent. The following data items are required:
- Key 8 (answer codes) is updated to indicate the answer that was sent to the service requester.
- Key 6001 (history information) can add a number of events depending on the status change.
- Key 7001 (PTF ID) is used to change the Sent and Status fields.
If PTFs were sent or an answer was added to the problem log, these actions do not require a status change. Add a history event to define the action taken.
Data for CLOSED status
A problem can be changed to CLOSED status from any other status by including the following data items:
- Key 3 (problem status) indicates that CLOSED status is the only key allowed.
- Key 6 (operational data) is updated by the API when the problem is closed.

Keys for Changing Problem Types 6 and 7

Problem type 6 (client machine-detected) and problem type 7 (client user-detected) require the Problem category field in key 1012 be set to 0 (Report) to move to PREPARED status.

Error Messages

Message ID	Error Message Text
CPF3C1E E	Required parameter &1 omitted.
CPF3C90 E	Literal value cannot be changed.
CPF3CF1 E	Error code parameter not valid.
CPF3CF2 E	Error(s) occurred during running of &1 API.
CPF7AAB E	Problem &1 not found.
CPF3C4D D	Length &1 for key &2 not valid.
CPF3C82 D	Key &1 not valid for API &2.
CPF3C86 D	Required key &1 not specified.
CPD7A82 D	Value not valid for key &1. (char string)
CPD7A83 D	Value not valid for key &1. (integer)
CPD7A87 D	Key &1 may be added only once.
CPD7A88 D	Incorrect DBCS field format found.
CPD7A8A D	Key value &1 is not valid.
CPD7A8B D	Length of data not valid.
CPF7A89 E	Incorrect handle for this activation.
CPF7A8A E	Problem log services not started.
CPF7AA7 E	Problem &1 not found.
CPF9821 E	Not authorized to program &1 in library &2.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFA320 E	Pointer parameter is null.

API introduced: V3R1

[ Back to top | Problem Management APIs | APIs by category ]