| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | View ID | Input | Binary(4) |
| 4 | Start line number | Input | Binary(4) |
| 5 | Number of lines | Input | Binary(4) |
| 6 | Line length | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
The Retrieve View Text (QteRetrieveViewText) API is used to retrieve source text from a specified view. This text may be formatted and displayed by the user of this API. The caller must specify the following:
All text retrieved, whether it comes from files or as text supplied by a processor, is in the CCSID of the job.
If source files have changed since the view was created, diagnostic messages CPF9561 (for IBM® i files) and CPF9596 (for IBM i integrated file system files) are sent to the calling program's message queue for each file. Error messages CPF9566 (for IBM i files) and CPF9597 (for IBM i integrated file system files) also are issued, and all of the text available is retrieved. The calling program should warn the user that the view text may be incorrect.
If a source file cannot be accessed because it is deleted or the user is not authorized, error messages CPF9565 (for IBM i files) and CPF9598 (for IBM i integrated file system files) are issued. No more text is retrieved. Text up to that file is retrieved and this is indicated in the fields of the receiver variable. If the calling program attempts to read text in the view following the file, the starting line number can be set to a line after the file. The number of lines in the file that should have been read is returned in the exception data. This allows the calling program to skip over this file if desired.
It is suggested that the calling program buffer the retrieved text to minimize use of this API. Source files accessed by this API do not remain open across API calls. Performance degradation occurs for every use of the API that results in file access because of opening and closing files.
See documentation on Set Encryption Key (QteSetEncryptionKey) and Set Decryption Key (QteSetDecryptionKey) APIs for information on encrypting debug view data.
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 parameter. The minimum length is 8 bytes.
The identifier of a previously registered view obtained by using the Register Debug View API.
The number of the first line to be retrieved.
The number of lines of source text to be retrieved. This number includes the line specified in the start line number parameter. Fewer than the number of lines may be placed in the receiver variable if fewer lines than requested are available. No more than the number of lines specified is placed in the receiver variable.
The following special value is supported for this parameter:
| 0 | All of the text associated with this view should be retrieved. |
The length of each line of text to be retrieved. Each line takes exactly this many characters. If the actual line of text is shorter, it is padded to the right with blanks. If the line is longer than this length, it is truncated to fit. The line length must be a number from 1 through 255.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following tables show the information supplied in the receiver variable parameter. The information returned depends on the type of view being used. For more information about each field, see Field Descriptions. For the listing view:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of lines returned |
| 12 | C | BINARY(4) | Line length |
| Note: The following field is repeated for each line returned. The number of characters is equal to the line length. | |||
| CHAR(*) | Listing view source line | ||
For the statement view:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of lines returned |
| 12 | C | BINARY(4) | Line length |
| Note: The following fields are repeated for each line returned. The total number of characters in each line is equal to the line length (10 + 10 + 10 + * = line length). | |||
| CHAR(10) | Procedure dictionary number | ||
| CHAR(10) | Statement number | ||
| CHAR(10) | Statement type number | ||
| CHAR(*) | Procedure name | ||
For the text view:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of lines returned |
| 12 | C | BINARY(4) | Line length |
| Note: The following fields are repeated for each line returned. | |||
| CHAR(12) | Sequence number | ||
| CHAR(*) | Text view source line | ||
Bytes available. The number of bytes of data available to be returned.
Bytes returned. The number of bytes of data returned.
Line length. The length of each line of text in the receiver variable parameter.
Listing view source line. The text associated with each line retrieved. The number of characters in each line is equal to the line length.
Number of lines returned. The number of lines of source text retrieved by this API and available in the receiver variable. This may be less than the number of lines requested or available, if the receiver variable is not large enough to hold the text requested.
Procedure dictionary number. The number that uniquely identifies the procedure in this module. The number is left-justified and padded on the right with blanks. For OPM programs the procedure dictionary number is set to a value of 0.
Procedure name. The name of the procedure. The name is left-justified and padded on the right with blanks. For OPM programs the procedure name is blanks.
Sequence number. If the text is from a source physical file, these 12 bytes contain the sequence number and source date for that line. If the text is from an IBM i integrated file system file, these 12 bytes are blank. If the text is supplied by the compiler, these 12 bytes are blank.
Statement number. The number that uniquely identifies the statement in the procedure. The number is left-justified and padded on the right with blanks. This number is shown on the compiler listing. For OPM programs the statement number is the same as the machine interface (MI) number.
Statement type number. The type of statement produced by the compiler. The number is left-justified and padded on the right with blanks. Possible values are:
| 1 | INIT CODE |
| 2 | PROC ENTRY |
| 3 | PROC EXIT |
| 4 | ALLOC |
| 5 | STMT |
| 6 | ENTRY |
| 7 | EXIT |
| 8 | MULTIEXIT |
| 9 | PATH LABEL |
| 10 | PATH CALL BGN |
| 11 | PATH CALL RET |
| 12 | PATH DO BGN |
| 13 | PATH TRUEIF |
| 14 | PATH FALSEIF |
| 15 | PATH WHEN BGN |
| 16 | PATH OTHERW |
| 17 | GOTO |
| 18 | POST COMPOUND |
Text view source line. The text associated with each line retrieved. The number of characters in each line equals the line length minus 12 bytes (the sequence number).
| 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. |
| CPF9549 E | Error addressing API parameter. |
| CPF954A E | No source text available. |
| CPF954C E | Cannot retrieve text from file. |
| CPF9560 E | Line length not valid. |
| CPF9561 E | Source file has changed. |
| CPF9563 E | Number of lines not valid. |
| CPF9564 E | Starting line number not valid. |
| CPF9565 E | Source cannot be accessed. |
| CPF9566 E | One or more source files have changed. |
| CPF9596 E | Source file has changed. |
| CPF9597 E | One or more source files have changed. |
| CPF9598 E | Source file cannot be accessed. |
| CPF959A E | Source file type not valid. |
| CPF957E E | Decryption error occurred. |
[ Back to top | Debugger APIs | APIs by category ]