| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | View ID | Input | Binary(4) |
| 4 | Error code | I/O | Char(*) |
The Retrieve Stopped Position (QteRetrieveStoppedPosition) API is used to determine if a module in a program is on the call stack. It indicates the position in the view at which the program stopped if the program is on the stack. The caller must specify a registered view ID. The most recently called procedure in the specified module is the one whose line is returned. If a program is on the stack, the stack is searched from the most recent call backward until a procedure in the module is found. The location in that procedure is returned.
If no procedure in the identified module is on the stack, a zero is returned.
None.
The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested if you specify the length of receiver variable parameter correctly. As a result, the API returns only the data that the area can hold. For more information, see Format of Receiver Variable.
The length of the receiver variable. The minimum length is 8 bytes.
It is suggested that a receiver variable length be given that is large enough to hold one position element. Because this normally is the number of elements that are returned, a single call to this API is usually sufficient. Also, this allows the number of stopped positions field to be used to determine whether the program is stopped. If zero elements are returned, the program is not stopped in the specified view.
The identifier of a previously registered view obtained using the Register Debug View API.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table shows the information supplied in the receiver variable parameter. 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 | BINARY(4) | Number of stopped positions |
| Note: The following fields are repeated for each stopped position. | |||
| BINARY(4) | Line number | ||
| BINARY(4) | Column number | ||
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Column number. The column number within the line number specified where the program is stopped in the view ID. Column numbers can be 1 through 255.
Line number. The line number within the view ID where the program is stopped. This number represents the line number within the view that corresponds to text retrieved using the Retrieve View Text API.
Number of stopped positions. A stopped position consists of the line number and column number fields and are repeated this number of times, once for each position available. If the view is not on the stack, this number is zero. If there is no room in the receiver variable to hold any stopped positions, this number is also zero. Therefore, there should be enough room in the receiver variable to hold at least one stopped position.
Because of program optimization, it is possible for the API not to know exactly where the view is stopped. For this reason, more than one position may be returned.
| Message ID | Error Message Text |
|---|---|
| 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. |
| CPF9542 E | View not found. |
| CPF9548 E | Map not available. |
| CPF9549 E | Error addressing API parameter. |
[ Back to top | Debugger APIs | APIs by category ]