Report Software Error (QpdReportSoftwareError) API

Use the Report Software Error (QpdReportSoftwareError) API whenever your ILE program detects a software problem that must be fixed.

The API logs the problem in the system problem log, which lets you track the problem, as well as send it to a service provider. See the System Manager for iSeries product for more information about service providers and service requesters.

The API also lets you specify the symptoms that identify the problem. The operating system and the service provider use those symptoms to find a PTF that may fix the problem.

The API also lets you specify data to dump to spooled files. If neither the operating system nor the service provider can find a PTF, you may be able to find the cause of the problem using the data the program dumped.

Authorities and Locks

Object Authority

*USE for objects in libraries

*R for objects in directories

Object Library Authority

*EXECUTE

Object Directory Authority

*RX

Locks

None

Required Parameter Group

Problem description records

INPUT; ARRAY of POINTERS

This is a list of pointers to problem symptom and data description records. See Problem Description Records Format for the format of the records.

Number of Problem description records

INPUT; BINARY(4)

The number of problem description records your program is passing 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. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Problem Description Records Format

Field Descriptions

Key Identifies a particular problem symptom or data. See Keys for a list of the possible keys.

Problem record description This describes a particular symptom of the problem, or specifies data to collect. See Formats of Specific Problem Description Records for the various problem record description formats.

Keys

The following table lists the valid keys of the key field area of the software problem record.

Formats of Specific Problem Description Records

Key 100-Call Stack Counter

This key specifies which invocation on the program stack is suspected of causing the error being reported. If this key is used, you must not use keys 101, 102, 103, or 104. If neither key 100, 101, nor 102 are specified, the API assumes that the program or service program that called the API is the one that has the problem.

Key 101-Suspected Program

This key is used to identify which program is suspected of causing the error being reported. If this key is used, you must not use key 100 or 102, but should use keys 103 and 104 if applicable. If neither key 100, 101, nor 102 are specified, the API assumes that the program or service program that called the API is the one that has the problem.

Note: The program must exist on the system at the time the API is called.

Key 102-Suspected Service Program

This key is used to identify which service program is suspected of causing the error being reported. If this key is used, you must not use key 100 or 101, but should use keys 103 and 104 if applicable. If neither key 100, 101, nor 102 are specified, the API assumes that the program or service program that called the API is the one that has the problem.

Note: The service program must exist on the system at the time the API is called.

Key 103-Suspected Module

This key is used to identify which module is suspected of causing the error being reported. If this key is used, you must not use key 100, but should use keys 101 or 102.

Note: The module must exist on the system at the time the API is called.

Key 104-Suspected Procedure

This key is used to identify which procedure is suspected of causing the error being reported. If this key is used, you must not use key 100, but should use key 103 and either 101 or 102.

Key 105-Detecting Program

This key identifies the program that detected the problem. If this key is used, you must not use key 106. If neither key 105 nor 106 is specified, the API assumes that the program or service program that called the API is the one that detected the problem.

Note: The program must exist on the system at the time the API is called.

Key 106-Detecting Service Program

This key identifies the service program that detected the problem. If this key is used, you must not use key 105. If neither key 105 nor 106 is specified, the API assumes that the program or service program that called the API is the one that detected the problem.

Note: The service program must exist on the system at the time the API is called.

Key 200-Symptom

This key identifies the symptoms associated with the problem. Together, the symptoms form a symptom string. i5/OS searches for a PTF that has a solution string that matches this symptom string.

Key 201-Instruction Number

This key identifies the instruction number where the problem occurred.

Key 300-System Object

This key identifies system objects associated with the problem. The system objects will be dumped to spooled files. The spooled files will be kept on an output queue in the APAR library associated with the problem log entry. You can display the spooled files using the WRKPRB command. The combination of this key and the other keys related to objects may be specified up to 32 times.

Key 301-Data

This key identifies data associated with the problem. The data is dumped to spooled files. This key may be specified up to 32 times. The spooled files are kept on an output queue in the APAR library associated with the problem log entry. You can display the spooled files using the WRKPRB command. The first one thousand bytes from the list of data items are also sent to the service provider if the problem is reported and if the "send data packet" flag in the service attributes is on. That data resides in a file named QAPDFCDP in the APAR library associated with the problem log entry on the service provider.

Key 302-Named System Object

This key names system objects associated with the problem. The system objects will be dumped to spooled files. The spooled files will be kept on an output queue in the APAR library associated with the problem log entry. You can display the spooled files using the WRKPRB command. The combination of this key and the other keys related to objects may be specified up to 32 times.

Note: The object must exist on the system at the time the API is called.

Key 303-Spooled File

This key identifies spooled files associated with the problem. The job that created the spooled files must be the current job. This key may be specified up to 32 times. The spooled files are kept on an output queue in the APAR library associated with the problem log entry.

Key 304-Named Integrated File System Object

This key names integrated file system objects associated with the problem. The integrated file system objects will be dumped to spooled files. The spooled files will be kept on an output queue in the APAR library associated with the problem log entry. You can display the spooled files using the WRKPRB command. The combination of this key and the other keys related to objects may be specified up to 32 times.

Notes:

1. The object must exist on the system at the time the API is called.
2. Both absolute and relative path names are allowed. The patterns ? and * are not allowed. The home directory of the user is not resolved, thus a tilde (~) in the first character position is not treated as the home directory. The NLS-enabled path name structure (defined in the QLG header file) can be filled in to specify the coded character set identifier (CCSID) the path name is in.

Key 400-Service Identifier

This key identifies where in a particular program or service program the problem was reported. The default service identifier is 9000.

Field Descriptions

Call stack counter. The number of invocations in the program stack to count from the invocation of the program or service program that called the API, to the invocation of the program or service program that is suspected of having the problem. Use 1, for instance, to specify the program or service program that called the program or service program that called the API. If the call stack counter value exceeds the number of invocations currently on the program stack, the API uses the invocation of the program or service program that called the API.

Data ID. This number is used to identify the data that is dumped.

Data length. The length of the data that is dumped.

Instruction number. Specifies exactly where the problem occurred within the specified program or service program.

Key. Identifies the problem description record.

Length of library name. The length of the library name. The value ranges from 1 to 10.

Length of module name. The length of the module name. The value ranges from 1 to 10.

Length of procedure name. The length of the procedure name. The value ranges from 1 to 256.

Length of program name. The length of the program name. The value ranges from 1 to 10.

Length of service program name. The length of the service program name. The value ranges from 1 to 10.

Length of symptom data. This indicates how many bytes the stored data occupies. The valid range is 1 to 15. The length of the symptom data plus the length of the symptom keyword must not exceed 15.

Length of symptom keyword. The length of the symptom keyword. The valid range is 1 to 15. The length of the symptom data plus the length of the symptom keyword must not exceed 15.

Library name. A pointer to the name of the library which contains the program, service program, or module in which the error has occurred.

Module name. A pointer to the name of the module in which the error has occurred.

NLS-enabled path name structure. For more information on this structure, see Path Name Format.

Object library. The library in which the object resides.

Valid values for the library name are:

Object name. The name of the object to be dumped.

Object type. The type of object. For complete list of the available object types, see the Control Language (CL) information in the iSeries Information Center.

Pointer to data. A space pointer to the data.

Pointer to object. A system pointer to a system object.

Pointer to symptom data. A pointer to the symptom data. The symptom data is a symptom of the problem. It is concatenated to the symptom keyword. The sum of the symptom keyword length and the symptom data length must not be longer than 15 characters.

Pointer to symptom keyword. A pointer to the system keyword. The symptom keyword is concatenated to the symptom data. The sum of the symptom keyword length and the symptom data length must not be longer than 15 characters. There are a limited number of keywords that can be used. The valid keywords are:

Table 1. Symptom string keywords

Procedure name. A space pointer to the name of the procedure in which the error has occurred.

Program name. A pointer to the name of the program in which the error is suspected. The suspected program name is included in the symptom string (as F/name) created when this API is called. If neither the 100, 101, nor the 102 keys are used, then the program name in the symptom string defaults to the caller of this API.

Reserved. Null.

Service identifier. Identifiers where in a program or service program the problem was reported. The valid range is 1 to 8999.

Service program name. A pointer to the name of the service program in which the error is suspected. The suspected service program name is included in the symptom string (as F/name) created when this API is called. If the 100, 101, or the 102 keys are not used, then the service program name in the symptom string defaults to the caller of this API.

Spooled file name. The name of a spooled file associated with the problem.

Spooled file number. The unique number of a spooled file associated with the problem. The valid range is 1 through 9999.

The following special values are supported for this parameter:

Type of symptom data. This indicates how the data is stored.

The possible values are:

Usage Notes

When this API runs within a threaded job, no problem log entry is created. When the API is called, the following occurs:

• Any error data that is provided is spooled to one or more spooled files.
• A symptom string is created.
• A message is sent to the job log and to the QSYSOPR message queue, which indicates that a software error has been detected.

Error data can be provided on the call to the API by using the data item offset and length parameters. (No object dumping support is available).

Also, dump job output is provided to help with problem determination.

Also, the following keys are ignored:

Error Messages