Add View Text (QteAddViewText) API
Required Parameter Group:
| 1 | View number | Input | Binary(4) |
| 2 | Text descriptor buffer | Input | Char(*) |
| 3 | Number of entries | Input | Binary(4) |
| 4 | Format name | Input | Char(8) |
| 5 | Supplied text buffer | Input | Char(*) |
| 6 | Length of text buffer | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Service Program: QTECRTVS
Threadsafe: No
The Add View Text (QteAddViewText) API is used to describe a piece of text of a previously added view. As a processor reads its input source, it creates at least one view. This API is issued to add the directions for re-creating the text of these views. For the debugger to show the text that makes up a view, the location of the pieces of text that make up the view must be specified.
When the view is reconstructed by the debugger, the pieces of text will be retrieved and concatenated into a single piece of text, following the directions given when this API is called. Thus, when it is mentioned that text is copied, it is referring to a later time, when the view is reconstructed.
All the text for a view must be added at once, with one call to this API. For this reason, the text must be built up in a buffer as the processor produces its output. At the end of view creation, all text is then supplied to this API.
If any text comes from files, the file descriptors must have been previously added to the view with the Add View File (QteAddViewFile) API.
See documentation on Set Encryption Key (QteSetEncryptionKey) and Set Decryption Key (QteSetDecryptionKey) APIs for information on encrypting debug view data.
Authorities and Locks
None.
Required Parameter Group
- View number
- INPUT; BINARY(4)
The number of the view to which a piece of text is being added. This number must be the same as the number previously returned by the Add View Description API.
- Text descriptor buffer
- INPUT;CHAR(*)
The input variable containing the text descriptors. Text descriptors define the location of text used to build the view specified in the view name parameter.
- Number of entries
- INPUT;BINARY(4)
The number of text descriptors that are provided in the text descriptor buffer parameter.
Many pieces of text may be described in a single text descriptor buffer. However, each entry must represent a single piece of contiguous text, and this parameter must be a count of the number of entries provided.
Each entry must contain all fields indicated, but, depending on the type of text being described by the entry, certain fields will not be used by the API.
If any text is supplied by the calling program, it is identified by a text descriptor, but the text itself is contained in the supplied text buffer.
- Format name
- INPUT; CHAR(8)
The content and format of the information supplied by the calling program in the text descriptor buffer. The valid values for format name are:
TXTA0100 Used when the text being added to this view can come from any of the following: - Blanks
- Stored in a file
- Copied from the previous view
- Supplied by the calling program within the supplied text buffer parameter
This is the case for a *TEXT view.
TXTA0101 Used when the entire text for this view is supplied text. This is the case for a *LISTING view. TXTA0102 Used when statement information for a *STATEMENT view is to be supplied. TXTA0103 Used when the entire text for this view is supplied text. This is the case for a *LISTING view. Note that this format is identical to TXTA0101; however, when the TXTA0103 format is specified, the listing view that is created will be compressed. When it is reconstructed, it will be decompressed at that time. TXTA0104 Used to support fully free-form RPG. It is an extension of the format TXTA0100 by adding an array of the range formats. TXTA0105 Used to support fully free-form RPG. It is an extension of the format TXTA0101 by adding an array of the range formats. TXTA0106 Used to support fully free-form RPG. It is an extension of the format TXTA0103 by adding an array of the range formats. 
- Blanks
- Supplied text buffer
- INPUT; CHAR(*)
The input variable that is to be passed to the API, containing the text that is supplied when a text descriptor in the text descriptor buffer parameter indicates that text is supplied. Text descriptors within the text descriptor buffer refer to text locations within this buffer by the offset from the beginning of the buffer. The piece of text is ended by a NULL (hex 00) character. To conserve storage, delete the trailing blanks in lines of supplied text, and end the text with a null character.
Note: A line of supplied text must not be more than 255 characters in length, not counting the NULL character.
- Length of text buffer
- INPUT; BINARY(4)
The length of the supplied text buffer.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
TXTA0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Text location |
| 10 | A | CHAR(2) | Reserved |
| 12 | C | BINARY(4) | File index |
| 16 | 10 | BINARY(4) | Starting offset |
| 20 | 14 | BINARY(4) | Number of lines |
| 24 | 18 | BINARY(4) | From line |
TXTA0101 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Starting offset |
TXTA0102 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Procedure dictionary ID |
| 4 | 4 | BINARY(4) | Statement number |
| 8 | 8 | CHAR(1) | Statement type |
TXTA0103 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Starting offset |
TXTA0104 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Text location |
| 10 | A | CHAR(2) | Reserved |
| 12 | C | BINARY(4) | File Index |
| 16 | 10 | BINARY(4) | Starting Offset |
| 20 | 14 | BINARY(4) | Number Of Lines |
| 24 | 18 | BINARY(4) | From Line |
| 28 | 1C | BINARY(4) | Number of range array elements |
| Note: The following fields describe the elements in the range array and are repeated the number of times specified in the "number of range array elements" field. | |||
| BINARY(4) | Starting line of the range | ||
| BINARY(4) | Ending line of the range | ||
| BINARY(4) | Source line format | ||
| BINARY(4) | Continuation flag | ||
TXTA0105 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Starting offset |
| 4 | 4 | BINARY(4) | Number of range array elements |
| Note: The following fields describe the elements in the range array and are repeated the number of times specified in the "number of range array elements" field. | |||
| BINARY(4) | Starting line of the range | ||
| BINARY(4) | Ending line of the range | ||
| BINARY(4) | Source line format | ||
| BINARY(4) | Continuation flag | ||
TXTA0106 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Starting offset |
| 4 | 4 | BINARY(4) | Number of range array elements |
| Note: The following fields describe the elements in the range array and are repeated the number of times specified in the "number of range array elements" field. | |||
| BINARY(4) | Starting line of the range | ||
| BINARY(4) | Ending line of the range | ||
| BINARY(4) | Source line format | ||
| BINARY(4) | Continuation flag | ||
Field Descriptions
Continuation flag. The flag defined to indicate whether this line is a continuation of previous line. Possible values are:
| 0 | Continuation property not provided |
| 1 | This line is a continuation of previous line |
| 2 | This line is a new line, not a continuation |
Ending line of the range. The number of the line where the range ends.
File index. A file member added by the Add View File API. This field is required if the text location is set to *FILE; otherwise, it is ignored. The first file added for the specified view is file 0, the second is file 1, and so forth.
When the view has a previous view, file 0 should not be specified. File 0 is assumed to mean a line in the previous view because the first file specified in the file descriptor must be the root source file used to construct this view. This root source file is the same as the previous view. Instead, *PREVIOUS should be specified in the text location field. If file 0 is specified instead of the previous view and the previous view was created by another preprocessor that created a temporary file as its output, that file may not exist at run time. In that case, text for the view could not be retrieved. However, if *PREVIOUS is specified, the View Retrieval API can use the text descriptors of the output view created by the preprocessor to reconstruct the text.
Note: The source debugger support does not validate the existence of this file. It merely uses the name in the view information to refer to the location of debug data. When the text of the view is reconstructed, text will be retrieved from the file named in this parameter (and the member name parameter), and the file name will be validated at that time.
From line. The line number where text is located. If the text location is a file, this is the line number in that file. If the text location is a previous view, this is the line position within that view. This can be thought of as the start line position. This field is required if the text location is set to *FILE or *PREVIOUS.
Number of lines. The number of lines of text being described. It is intended that views be created in order, where each piece of text comes directly after the previous text added. This field is required when text location is set to *FILE or *PREVIOUS.
Number of range array elements. The number of elements in the range array.
Procedure dictionary ID. The dictionary number of the procedure where the statement is located.
Reserved. Reserved for future use.
Source line format. The format type of the source line. Possible values are:
| 0 | Format type not provided |
| 1 | Fixed RPG |
| 2 | Extended RPG |
| 3 | Free-form RPG |
| 4 | Fully free-form RPG |
Starting line of the range. The number of the line where the range begins.
Starting offset. The location within the supplied text buffer of the start of the supplied text. This is an offset from the beginning of the buffer to the start of the text. This field is required if the text location is set to *SUPPLIED in the TXTA0100 format.
Statement number. The HLL statement number of the statement.
Statement type. The type of the statement being added. Possible values are:
| X'01' | INIT CODE |
| X'02' | PROC ENTRY |
| X'03' | PROC EXIT |
| X'04' | ALLOC |
| X'05' | STMT |
| X'06' | ENTRY |
| X'07' | EXIT |
| X'08' | MULTIEXIT |
| X'09' | PATH LABEL |
| X'10' | PATH CALL BGN |
| X'11' | PATH CALL RET |
| X'12' | PATH DO BGN |
| X'13' | PATH TRUEIF |
| X'14' | PATH FALSEIF |
| X'15' | PATH WHEN BGN |
| X'16' | PATH OTHERW |
| X'17' | GOTO |
| X'18' | POST COMPOUND |
Text location. The location of the text being referred to. This field is required for all entries.
| *FILE | The text is stored in a file. |
| *PREVIOUS | The text is a copy of the previous view text. The previous view is specified when the view is created. |
| *SUPPLIED | The text is supplied by the API user within the supplied text buffer parameter. The text that is supplied by the using program must be in the suppled text buffer parameter and referred to by a text descriptor within the text descriptor buffer parameter. |
| *BLANK | The text consists of blank lines. The number of blank lines inserted is specified by the number of lines field. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3C21 E | Format name &1 is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9542 E | View not found. |
| CPF9545 E | No previous view. |
| CPF9549 E | Error addressing API parameter. |
| CPF954E E | Text location is not valid. |
| CPF9551 E | File not found. |
| CPF9552 E | Cannot map between views. |
| CPF9556 E | API not valid at this time. |
| CPF9557 E | View already contains text descriptors. |
| CPF955B E | Number of entries not valid. |
| CPF955C E | Supplied Text Length parameter not valid. |
| CPF955D E | View data overflow. All debug data lost. |
| CPF9569 E | Missing supplied text. |
| CPF956A E | No such text in previous view. |
API introduced: V4R2
[ Back to top | Debugger APIs | APIs by category ]