Program-Stop Handler Exit Program
Required Parameter Group:
| 1 | Qualified program name | Input | Char(20) or Char(*) |
| 2 | Program type | Input | Char(10) |
| 3 | Module name | Input | Char(10) |
| 4 | Stop reason | Input | Char(10) |
| 5 | Receiver variable | Input | Char(*) |
| 6 | Number of entries | Input | Binary(4) |
| 7 | Message data | Input | Char(*) |
QSYSINC Member Name: ETEPGMST
Threadsafe: No
The Program-Stop Handler exit program is a user-written program that handles program-stop conditions.
This program must be identified to the Source Debugger support with the Start Source Debug (QteStartSourceDebug) API.
Breakpoint- and step-program stop conditions are reported using stop reasons 2, 3, and 4. The location at which the program-stop condition occurred is specified in the receiver variable parameter and is in terms of the statement view. The user-supplied program may use the Map View Position (QteMapViewPosition) API to determine the location to which this program maps any other registered view.
Watch-program stop conditions are reported using stop reasons 5 and 6. For watch-program stop conditions, the program stopped might not have debug data. In this case, the machine interface (MI) number is reported for OPM programs and the statement number is reported for ILE programs and Java™ class files. If the program can be debugged, the line number in the statement view is reported for OPM programs, ILE programs, and Java class files. Other information is also included in the receiver variable to identify the program that caused the watch condition to be satisfied.
Unmonitored-exception-program stop conditions are represented through stop reason 1. Unmonitored exceptions are reported through this exit program only when the program and module identified have been created with debug data. Without debugging data, the message that is the cause of the unmonitored exception is issued, and the Program-Stop Handler exit program is not called.
When a job being debugged by a servicing job is stopped by the QteStopDebuggedJob API, reason code 7 is reported. When this reason code is reported, none of the other input parameters are used and can be ignored.
Debugging of threaded jobs is enabled by the thread ID field that is contained in the parameters passed to the stop handler. Threads debugging is supported if a service job is used to debug a job that was spawned by native threads support. For nonthreaded applications, the thread ID passed will always be that of the initial job thread.
Authorities and Locks
None.
Required Parameter Group
- Qualified program name
- INPUT; CHAR(20) or CHAR(*)
The format of this parameter is dependent on the program type parameter. If the program type is *PGM or *SRVPGM, the format of this parameter is as follows:
The name of the program that is stopped as a result of a breakpoint, program step, or unmonitored exception. This parameter may also be the name of the program that is stopped because a watch condition has been satisfied.
The first 10 characters contain the name of the program. The second 10 characters contain the name of the library where the program is located. Each name is left-justified.
If the program type is *CLASS, the format of this parameter is as follows:
The null-terminated class file name of the JAVA class.
- Program type
- INPUT; CHAR(10)
The object type of the program that is stopped. The possible values are:
*PGM Bound program or OPM program *SRVPGM Service program *CLASS JAVA class file
- Module name
- INPUT; CHAR(10)
The name of the module (left-justified) that is stopped. The value of this field is blank for OPM programs and JAVA class files.
- Stop reason
- INPUT; CHAR(10)
The reason the program was called. Each character of this parameter has a specific meaning. The characters and their meanings are:
1 This reason is set when an unmonitored exception is received by the program being serviced by the source debugger support. 0 No unmonitored exception 1 Unmonitored exception 2 The program stopped because an unconditional or conditional breakpoint was satisfied. 0 No break condition 1 Break condition 3 The program stopped because a step condition was reached. 0 No step condition 1 Step condition 4 The program stopped because a conditional breakpoint was set and there was a failure in running the condition. The program is stopped at the break position specified. 0 No break condition failure 1 Break condition failure 5 The program stopped because a watch condition set with the watch debug statement was satisfied. 0 No watch condition 1 Watch condition 6 The program stopped because there was a failure in processing the watch condition. 0 No watch condition failure 1 Watch condition failure 7 The debugged job being serviced was stopped by the QteStopDebuggedJob API. 0 Debugged job not stopped 1 Debugged job stopped 8-10 Reserved. These characters are set to 0.
- Receiver variable
- INPUT; CHAR(*)
Stop Reasons 1, 2, 3, 4:
If only stop reason 1, 2, 3, or 4 is present, the following receiver variable format is passed:
A list of locations within the statement view where the program stop condition occurred. This list contains the number of entries where each number is defined as follows:
Stopped locations Array of BINARY(4)
The line number in the statement view where the program is stopped.Thread ID CHAR(8)
The thread identification of the thread where the program is stopped. This value immediately follows the last stopped location.Stop Reasons 5, 6:
Whenever stop reason 5 or 6 is present (other stop reasons can be present also), the following receiver variable format is passed:
Information about the watch stop condition, including the program stopped and the program that caused the watch condition to be satisfied. See Format of Watch-Program Stop Reason for Receiver Variable.
Stop Reason 7:
For stop reason 7, the receiver variable parameter is not used and can be ignored.
- Number of entries
- INPUT; BINARY(4)
The number of positions stored in the receiver variable parameter. In some cases, it is not known exactly where a program is stopped; therefore, multiple positions are given. Each entry specifies one position in the statement view. This number is not less than one nor greater than three. At least one stopped position will be identified; if stopped at more than one position, no more than the first three positions are made available.
This parameter is valid when stop reason 1, 2, 3, or 4 is the only reason present (stop reason 5 or 6 cannot be present). If stop reason 5 or 6 is present, the receiver variable contains the equivalent number of stopped locations parameter.
- Message data
- INPUT; CHAR(*)
Information about the message. The information in this parameter is valid only when the stop reason specified is an unmonitored exception. For a detailed description of the format, see Format of Message Data.
Format of Watch-Program Stop Reason for Receiver Variable
The following table shows the information supplied in the receiver variable parameter when a stop reason of 5 or 6 is present. For more information on the fields, see Field Descriptions.
Watch Receiver Variable Header
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Watch number |
| 4 | 4 | BINARY(4) | Offset to stopped program information |
| 8 | 8 | BINARY(4) | Offset to watch interrupt information |
Watch Stopped Program Information
The following table shows the stopped program information that is supplied in the receiver variable parameter. This data structure is accessible by adding the offset to stopped program information field in the receiver variable header to the address of the receiver variable.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to stopped procedure name |
| 4 | 4 | BINARY(4) | Length of stopped procedure name |
| 8 | 8 | BINARY(4) | Offset to stopped locations |
| 12 | C | BINARY(4) | Number of stopped locations |
| 16 | 10 | CHAR(1) | Stopped locations flag |
| 17 | 11 | CHAR(3) | Reserved |
| 20 | 14 | CHAR(8) | Thread ID |
| CHAR(*) | Reserved | ||
| Array of BINARY(4) | Stopped locations | ||
| CHAR(*) | Stopped procedure name | ||
Watch Interrupt Information
The following table shows the watch-interrupt information that is supplied in the receiver variable parameter. This data structure is accessible by adding the offset to watch interrupt information field in the receiver variable header to the address of the receiver variable.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(26) | Qualified interrupt job name |
| 26 | 1A | CHAR(20) | Qualified interrupt program name |
| 46 | 2E | CHAR(10) | Interrupt program type |
| 56 | 38 | CHAR(10) | Interrupt module name |
| 66 | 42 | CHAR(1) | Interrupt locations flag |
| 67 | 43 | CHAR(1) | Reserved |
| 68 | 44 | BINARY(4) | Offset to interrupt procedure name |
| 72 | 48 | BINARY(4) | Length of interrupt procedure name |
| 76 | 4C | BINARY(4) | Offset to interrupt locations |
| 80 | 50 | BINARY(4) | Number of interrupt locations |
| 84 | 54 | CHAR(8) | Thread ID |
| 92 | 5C | BINARY(4) | Offset to interrupt class file name |
| 96 | 60 | BINARY(4) | Length of interrupt class file name |
| CHAR(*) | Reserved | ||
| Array of BINARY(4) | Interrupt locations | ||
| CHAR(*) | Interrupt procedure name | ||
| CHAR(*) | Interrupt class file name | ||
Field Descriptions
Interrupt class file name. The Java class file name of the Java class containing the locations that caused the watch condition to be satisfied. For OPM and ILE programs, the Java class file name is not returned.
Interrupt locations. A list of locations, of the type described by the interrupt locations flag, that caused the watch condition to be satisfied.
Interrupt locations flag. The type of the locations in the interrupt locations field. All locations are of the same type.
| 1 | Line number in statement view |
| 2 | Statement number |
| 3 | MI number |
Interrupt module name. The name of the module (left-justified) in the program that caused the watch condition to be satisfied. The value of this field is blank for OPM programs and JAVA class files.
Interrupt procedure name. The procedure name of the procedure that contains the program locations that caused the watch condition to be satisfied. For OPM programs the procedure name is not returned.
Interrupt program type. The object type of the program that caused the watch condition to be satisfied. The possible values follow:
| *PGM | Bound program or OPM program |
| *SRVPGM | Service program |
| *CLASS | JAVA class file |
Length of interrupt class file name. The length of the interrupt class file name. This field is zero if there is no interrupt class file name available (for example, OPM and ILE programs).
Length of interrupt procedure name. The length of the interrupt procedure name. This field is zero if there is no interrupt procedure name available (for example, OPM programs).
Length of stopped procedure name. The length of the stopped procedure name. This field is zero if there is no stopped procedure name available (for example, OPM programs).
Number of interrupt locations. The number of locations in the program that caused the watch condition to be satisfied. At most, three locations are returned.
Number of stopped locations. The number of stopped program locations. At most, three stop locations are returned.
Offset to interrupt class file name. The offset from the start of the receiver variable to the name of the Java class file containing the location that caused the watch condition to be satisfied. The field is zero if there is no interrupt class file name available (for example, OPM and ILE programs).
Offset to interrupt locations. The offset from the start of the receiver variable to the list of locations in the program that caused the watch condition to be satisfied.
Offset to interrupt procedure name. The offset from the start of the receiver variable to the name of the procedure that contains the program location that caused the watch condition to be satisfied. This field is zero if there is no interrupt procedure name available (for example, OPM programs).
Offset to stopped locations. The offset from the start of the receiver variable to the stopped program location entries.
Offset to stopped procedure name. The offset from the start of the receiver variable to the name of the procedure that contains the stopped program location. This field is zero if there is no stopped procedure name available (for example, OPM programs).
Offset to stopped program information. The offset from the start of the receiver variable to the stop information for the program that is stopped as a result of the watch condition being satisfied.
Offset to watch interrupt information. The offset from the start of the receiver variable to the watch interrupt information. This data structure describes the program that caused the interruption.
Qualified interrupt job name. The name of the job that caused the watch condition to be satisfied. The first 10 characters contain the job name. The second 10 characters contain the user profile name. The next 6 characters contain the job number. Each name is left-justified.
Note: This field is the same as the name of the job being debugged. Watch program interruptions in other jobs are ignored.
Qualified interrupt program name. The name of the program that caused the watch condition to be satisfied. The first 10 characters contain the name of the program. The second 10 characters contain the name of the library where the program is located. Each name is left-justified. The value of this field is blank for Java class files.
Reserved. An ignored field.
Stopped locations. A list of locations, of the type described by the stop location flag, where the program stop condition occurred.
Stopped locations flag. The type of the locations in the stop locations field. All stop locations are of the same type.
| 1 | Line number in the statement view |
| 2 | Statement number |
| 3 | MI number |
Stopped procedure name. The name of the procedure that contains the stopped locations. For OPM programs the procedure name is not returned.
Thread ID. This is an 8-byte thread identification that is assigned by the system. It identifies the thread associated with the stopped or interrupt locations fields.
Watch number. The watch number identifier of the watch condition being satisfied. This is the same number that is returned by the Submit Debug Command API when the watch condition was set.
Format of Message Data
The following table shows the information supplied in the message data parameter. For more information on the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of message data |
| 4 | 4 | CHAR(7) | Message ID |
| 11 | B | CHAR(20) | Message file |
| 31 | 1F | CHAR(1) | Reserved |
| 32 | 20 | CHAR(512) | Message data |
Field Descriptions
Length of message data. The length of the data available in the message data parameter, in bytes. This field contains the length of the available message data for the predefined message indicated in the message ID field.
Message data. The values for substitution variables in the predefined message specified in the message ID field and located in the message file field.
Message file. The name of the message file that contains the message identified in the message ID field.
The first 10 characters contain the message file name. The second 10 characters contain the name of the library where the file can be located. Both entries are left-justified.
Message ID. The identifying code of the message.
Reserved. An ignored field.
Exit program introduced: V2R3
[ Back to top | Debugger APIs | APIs by category ]