Create Problem Log Entry (QsxCreateProblemLogEntry) API

Required Parameter Group:

1	Handle	Input	Binary(4)
2	Problem log ID	Output	Char(40)
3	Key structures	Input	Array of Pointers
4	Number of keys	Input	Binary(4)
5	Error Code	I/O	Char(*)

  Service Program Name: QSXSRVPL

  Default Public Authority: *USE

  Threadsafe: No

The Create Problem Log Entry (QsxCreateProblemLogEntry) API creates a problem log entry and adds the information provided to the problem log files using keys. Key 1 (problem log ID) is returned to the user that is required for other API operations.

The API allows a problem to be created with a status of OPENED, READY, or PREPARED. The difference to the user is that the amount of data increases as the problem goes from OPENED to PREPARED.

The types of problems that may be created are:

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

The keys provided to create a problem are checked for validity and applicability to the problem log entry in two ways:

Applicability of the type
Applicability of the field

The fields are checked to verify that they are not null. Some keys allow the user to control them (key control). Keys without "key control" support require all fields to be filled. Fields not flagged are ignored.(The existence of the data is verified; NOT whether or not the data is valid. The problem log APIs do not check the validity of the data.) Operations that are unsupported or not valid, such as creating a problem in SENT status or not providing all dependent keys, result in a diagnostic message for each infraction found and an exception or an error notification defining it.

The key fields are checked before the problem log entry is created and an error is signalled if any required key fields are null.

If the maximum number of problem log entries has been reached for this particular date (99999), CPF392F E is signaled.

Authorities and Locks

API Public Authority: *USE

Required Parameter Group

Handle: INPUT; BINARY(4)
An identifier that associates the problem log services started by the Start Problem Log Services API.
Key 1 (problem log ID): OUTPUT: CHAR(40)
This parameter contains the problem log identifier after the problem is created. If this parameter is omitted, no problem log ID is returned.
Key structures: INPUT; ARRAY of POINTERS
An array of pointers that has the address of each key that contains data to be written into the problem log. The number of pointers passed in the array must equal the value passed by parameter 4, Number of keys.
Number of keys: INPUT; BINARY(4)
Defines the number of keys that are being 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

See Key Groups for Problem Log APIs for a description of the keys.

Rules for Key Usage

To create a problem log entry, specific data is required. The amount of data varies depending on the status of the problem log. This section defines the data required for each problem type for statuses OPENED and READY. Problems in OPENED or READY status may be amplified with the status of PREPARED. The supplemental data required for this is defined once and is applicable to either OPENED or READY.

General Keys For Problem Log Entry Data

The minimum key data for all problems types is:

Key 1 (problem log ID)
This key must contain one of the following:
- Problem log identifier if the problem was created on another system
- The value "*LOCAL" to indicate that the problem is a local one.
Key 2 (problem type)
This defines the type of problem log entry being created.
Key 3 (problem status)
Defines the status to which the entry will be set. Three values are allowed:
- OPENED. Create a problem in OPENED status.
- READY. Create a problem in READY status.
- PREPARED. Create a problem in READY or OPENED status and add supplemental data required for PREPARED status.
Key 5 (problem origin system)
- Required if key 1 (problem log ID) is not *LOCAL.
- Prohibited if key 1 (problem log ID) is *LOCAL.
Key 6 (operational data)
- If key 1 (problem log ID) is *LOCAL, the Received from system field is prohibited. If it is not *LOCAL, the Received from system field is required.
- If key 3 (problem status) indicates the problem is to be in PREPARED status the Prepared for system field is required otherwise it is prohibited.
- The Date and time added field is automatically added by the API.
- The Date and time closed field is automatically added when the problem is closed.
Key 1002 (problem description message) or key 3001 (text entry), type 1.
Either or both are acceptable. Key 3001 is used if both are supplied. When both key 1002 and key 3001 are added, only key 3001 is available through the command interface, but both key 1002 and key 3001 can be retrieved through APIs. When the problem type is machine detected, key 1002 is required.
Key 5001 (contact information)
Required if key 1 (problem log ID) is not *LOCAL. Used to enter contact data for the remote system.
Key 6001 (history information)
This information defines the type of create action. One or more history entries are allowed. At least one event is required.

In addition, the following information is needed based on the problem type.

Keys for Creating Problem Type 1

Machine detected problems (problem type 1) use the following keys:

Data for OPENED status are:

Key 1002 (problem description message)
Required.
Key 1003 (problem creation data)
Required.
Key 1005 (failing device)
Required to define the device and/or code that is failing.
Keys 2001-2009 (FRU entries)
At least one key of the range 2001 to 2009 is required. The keys may be provided in any order but will be stored in probability of fix order, with the highest probability FRU record being stored first and the least probability FRU record being stored last.
Keys 4001 and 4002 (supporting data)
Optional. Used to define the supporting data that will be associated with the problem. Multiple entries are allowed.

Data for READY status are:

Post analysis data must be added to a machine detected problem to achieve READY status. This data is in addition to the data added to achieve OPENED status. Data for READY status are:

Key 1004 (reporting device)
Defines the machine that will be reported to a service provider as the failing machine.
Key 1005 (failing device) This provides a description of the resource that caused the problem.
Key 1006 (reporting code)
Defines the program/product that is failing. This is required if the highest probability FRU is key 2002 (code FRU type).
Key 1007 (problem analysis data)
Required
Key 1010 (symptom string)
Required
Keys 2001-2009 (FRU entries)
At least one key of the range 2001 to 2009 is required. The keys may be provided in any order but will be stored in probability of fix order, with the highest probability FRU record being stored first and the least probability FRU record being stored last.

Keys for Creating Problem Type 2

User-perceived hardware or software problems (problem type 2) can be created in READY and READY - PREPARED status only. These problems require data similar to machine-detected problems (problem type 1) with the following exceptions:

Key group 2000 (FRU records) is prohibited.
Key group 3000 (problem type 1) is required if 1002 is not used.

Keys for Creating Problem Type 3

PTF orders (problem type 3) are created in READY and READY - PREPARED status only and use the following:

Key group 1000 (problem description entries), except key 1002 (problem description message), is prohibited.
Key group 2000 (FRU records) is prohibited.
Key group 4000 (supported data records) is prohibited.
Key 1011 is optional.
Key group 7001 is required.

Keys for Creating Problem Type 4

User-perceived remote hardware or software problems (problem type 4) can be created in READY and READY - PREPARED status only. These problems require data similar to machine-detected problems (problem type 1) with the following exceptions:

Key group 2000 (FRU records) is prohibited.
Key group 4000 (supported data records) is prohibited.

Keys for Creating Problem Type 5

Application detected problems (problem type 5) are used to enter problems automatically detected during the execution of a program. They can be created in READY and PREPARED status only. These problems require data similar to machine-detected problems (problem type 1) with the following exceptions:

Key group 2000 (FRU records) is optional.
If key group 2000 (FRU records) is specified only key 2002 (code FRU type) is permitted.
Key group 4000 (supported data records) is optional.
Key group 4000 (supported data records) may be used to identify APAR data that is associated with the problem.

Keys for Creating Problem Types 6 and 7

Client machine-detected (problem type 6) and user-created (problem type 7) problems are used to create problem log entries for an attached client. These problems are generated in the READY status. The data requirements are:

Key 1012 is required and must be LOGONLY on the Add Problem Log Entry API.
Key 1013 is required.
Key 1003 (problem creation data)
Key 1010
Keys 1001, 1002, 1003
Keys 4001 and 4002 are optional
Key 3001 (text entry) is optional
Key 6001 (history information) is optional

Keys for Creating Problem Type 8

User-created general problems (problem type 8) are used to add data of a general nature, that is not applicable to the types already defined. The entry can be created in READY and READY - PREPARED status only. The data requirements are:

Key group 1000 (problem description entries) is prohibited.
Key 1002 (problem description message) can be used to create text for the problem description of the message.
Key 3001 (text entry) type 2 is required to provide a detailed description of the problem.
Key group 4000 (supported data records) can be used to identify data that is associated with the problem.

Data for PREPARED Status

The supplemental data needed to move a problem from OPENED or READY status to PREPARED status are:

Key 6 (operational data)
Key control
Prepared for system
Required to define the system that this problem will be sent to.
Key 1001 (problem severity)
Optional. Default is none.
Ignored for PTF Order (problem type 3).
Key 1011 (PTF media selection)
Optional. Default is the contact data base. 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.

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

Top | Problem Management API list
APIs by category