Retrieve Debugged Threads (QteRetrieveDebuggedThreads) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Thread array | Input | Array of Char(8) |
| 5 | Number of threads | Input | Binary(4) |
| 6 | Error code | I/O | Char(*) |
Service Program: QTETHRD
Threadsafe: No
The Retrieve Debugged Threads (QteRetrieveDebuggedThreads) API retrieves information for threads being debugged.
Note: A job may have several threads, each of which is debugged if the job is debugged. By default, the current thread is the initial thread of the debugged job or the thread at a debug stop.
Information about the requested threads is returned in the receiver variable. This allows the writer of a debugger to maintain and control a list of threads that are being debugged. If this API is processed when threads are active, the information returned by the API may no longer be accurate. Check the job status flag to see what state the job was in when the API was processed.
Threads debugging is supported if a service job is used to debug a job that was spawned by native threads support. If this is not the debug environment present when this API is called, a CPF958B error is returned.
Authorities and Locks
None.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of this area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data the area can hold. For more information, see Format of Receiver Variable. Entries are only returned in their entirety. The API never returns anything less. If there is not enough space for the entire entry, that entry is not returned and bytes available and bytes returned are not equal.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable in the user program, the results are not predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The content and format of the information returned in the receiver variable. The possible format names are:
THDL0100 Basic thread debug information. THDL0200 Extended thread debug information.
- Thread array
- INPUT; ARRAY OF CHAR(8)
The thread identifiers (IDs) for which debug information is returned. In the thread array parameter, thread IDs are specified and debug information about the requested threads is returned in the receiver variable. Each thread identifier in the thread array is 8 bytes long. The number of thread identifiers is specified in the number of threads parameter.
If the number of threads parameter is minus one, the first thread array parameter must be a special value. In this case, all other thread array parameters are ignored. Valid special values are:
*ALL Thread debug information for all threads is returned. *CURRENT Thread debug information for the current thread is returned. *INITIAL Thread debug information for the initial thread is returned. *ENABLE Thread debug information for all enabled threads is returned. *DISABLE Thread debug information for all disabled threads is returned.
- Number of threads
- INPUT; BINARY(4)
The number of thread identifiers provided in the thread array parameter. The number of threads parameter must be greater than zero or minus one. If it has a value of minus one, the first and only thread array parameter must be a special value. If it is greater than zero, the number specified is the number of thread array parameters that must be provided.
- 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 Receiver Variable
The following receiver variable formats are returned based on the format name parameter:
THDL0100 Format
The following table shows the format of the receiver variable for the THDL0100 format. For more information about the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(1) | Job status flag |
| 9 | 9 | CHAR(3) | Reserved |
| 12 | C | BINARY(4) | Offset to thread records |
| 16 | 10 | BINARY(4) | Number of thread records |
| 20 | 14 | BINARY(4) | Size of thread record |
| CHAR(*) | Reserved | ||
| Note: The following fields repeat the number of times specified in the number of thread records field. | |||
| CHAR(8) | Thread ID | ||
| CHAR(1) | Current thread flag | ||
| CHAR(1) | Initial thread flag | ||
| CHAR(1) | Thread run state | ||
| CHAR(1) | Thread debug status | ||
THDL0200 Format
The following table shows the format of the receiver variable for the THDL0200 format. For more information about the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(1) | Job status flag |
| 9 | 9 | CHAR(3) | Reserved |
| 12 | C | BINARY(4) | Offset to thread records |
| 16 | 10 | BINARY(4) | Number of thread records |
| 20 | 14 | BINARY(4) | Size of thread record |
| CHAR(*) | Reserved | ||
| Note: The following fields repeat the number of times specified in the number of thread records field. | |||
| CHAR(8) | Thread ID | ||
| CHAR(1) | Current thread flag | ||
| CHAR(1) | Initial thread flag | ||
| CHAR(1) | Thread run state | ||
| CHAR(1) | Thread debug status | ||
| CHAR(3) | Reserved | ||
| CHAR(1) | top of stack flag | ||
| BINARY(4) | Statement view ID stopped in | ||
| BINARY(4) | Line in statement view stopped in | ||
Field Descriptions
Bytes available. The number of bytes of data available to be returned to the user.
Bytes returned. The number of bytes of data returned to the user.
Current thread flag. Whether the thread is the current thread or not. Possible values are:
| 0 | The thread is not the current thread. |
| 1 | The thread is the current thread. |
Initial thread flag. Whether the thread is the initial thread or not. Possible values are:
| 0 | The thread is not the initial thread. |
| 1 | The thread is the initial thread. |
Job status flag. The status of the job when the API was processed.
| 0 | The job is stopped by debug. The information returned by this API is accurate. |
| 1 | The job is running and has not been stopped by debug (for example, breakpoint, step, watch, or unmonitored exception). If threads are running it is not possible for debug to present a stable debugging environment. The information returned by this API may no longer be accurate. |
Line in statement view stopped in. If the thread is stopped in a module that has been registered under debug, this is the line number in the module's statement view where the thread is stopped. See the statement view ID stopped in field for more information. This field is only applicable for the current thread. If the thread being returned is not the current thread then this field will contain a -1.
Number of thread records. The number of thread records that are returned in the receiver variable. Each record has the same format, and is repeated in the receiver variable.
Offset to thread records. The offset in bytes from the start of the receiver variable to the first requested thread information record.
Reserved. An ignored field.
Size of thread record. The number of bytes occupied by each thread record.
Statement view ID stopped in. The view ID of a previously registered debug statement view. It is the statement view ID of the highest module found on the call stack that has been registered under debug. If no statement views on the stack are registered, the thread is not stopped by debug, or if the thread is not the current thread a value of -1 is returned.
Thread debug status. The debug status of the thread.
| 0 | The thread is disabled. |
| 1 | The thread is enabled. |
Thread ID. This is an 8-byte thread handle assigned by the system.
Thread run state. The debug run status of the thread.
| 0 | The thread is running. |
| 1 | The thread is currently stopped at a breakpoint, step, watch or unmonitored exception. When this happens all other threads are halted. |
| 2 | This is a thread that was halted by debug because of a debug stop that occurred in one of the debugged job's threads. The reason for stopping or halting all threads is to provide a static debugging environment. |
Top of stack flag. Whether the stopped view ID is at the top of the call stack or not. Possible values are:
| blank | This is not the current thread. This field is only applicable for the current thread. |
| 0 | The view ID is not at the top of the call stack. |
| 1 | The view ID is at the top of the call stack. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9541 E | Not in debug mode. |
| CPF9549 E | Error addressing API parameter. |
| CPF958A E | Thread &1 not found. |
| CPF958B E | Threads debugging not supported. |
| CPF958C E | Number of threads not valid. |
| CPF958E E | Thread array special value not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V4R2
[ Back to top | Debugger APIs | APIs by category ]