Retrieve Debugged Threads (QteRetrieveDebuggedThreads) API

The Retrieve Debugged Threads (QteRetrieveDebuggedThreads) API retrieves information for threads being debugged. (3) 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 on 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 on 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

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.