Add View File (QteAddViewFile) API
Required Parameter Group:
| 1 | File descriptor buffer | Input | Char(*) |
| 2 | Number of entries | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | View number | Input | Binary(4) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Service Program: QTECRTVS
Threadsafe: No
The Add View File (QteAddViewFile) API provides a list of files that can be used when describing text for a previously added view. If a file is read more than once (such as a multiple included file), it should be added multiple times. When this file needs to be identified to other APIs, its file index is given, which is an index into the list of files supplied. The first file supplied has an index of zero.
The first file added to a view must be the root file for that view. For example, if a processor produces a source view, where a root file includes other files, the root file must be specified as the first file for the view. This is true even if the file is not the first file to produce view text (which would happen if an include statement is on the first line of the file).
All files for a view must be added at one time, with one call to this API.
Authorities and Locks
None.
Required Parameter Group
- File descriptor buffer
- INPUT; CHAR(*)
The input variable containing the list of files that make up the specified view text.
The source debugger support does not validate the existence of this file. This validation is done when text from the file is retrieved.
- Number of entries
- INPUT; BINARY(4)
The number of files that are provided in the file descriptor buffer parameter.
Many files may be described in a single file descriptor buffer. However, each entry must represent a single file, and this parameter must be a count of the number of files provided.
For format FILA0200, the number specifies the number of format entries, each containing seven fields, that are present before the external file names buffer.
- Format name
- INPUT; CHAR(8)
The content and format of the information supplied by the calling program in the file descriptor buffer. The valid values for format name are:
FILA0100 IBM® i file FILA0200 External file (workstation file not on a System i™ platform) or IBM i integrated file system file For more information, see FILA0100 Format or FILA0200 Format.
- View number
- INPUT; BINARY(4)
The number assigned by the debug support as an output parameter on the Add View Description API, which must be called prior to this API. If a file is used for more than one view, it must be supplied once for each view in which it is used.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
FILA0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | IBM i file name |
| 10 | A | CHAR(10) | IBM i file library |
| 20 | 14 | CHAR(10) | IBM i member name |
FILA0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| Note: The first seven fields repeat the number of times specified in the number of entries parameter. | |||
| BINARY(4) | Offset of file name | ||
| BINARY(4) | Length of file name | ||
| BINARY(4) | File flag | ||
| BINARY(4) | CCSID of file name | ||
| CHAR(2) | Country or region ID of file name | ||
| CHAR(3) | Language ID of file name | ||
| CHAR(3) | Reserved | ||
| Note: The following field occurs after the preceding header fields. | |||
| CHAR(*) | File names buffer | ||
Field Descriptions
IBM i file library. The name of the library that contains the file being listed. It is an IBM i object name, left-justified, and padded with blanks.
IBM i file name. The name of the IBM i file being listed. It is an IBM i object name, left-justified, and padded with blanks.
IBM i member name. The name of the member in the file being listed. It is an IBM i object name, left-justified, and padded with blanks.
CCSID of file name. The CCSID the file name is in. A value of zero indicates to use the CCSID value of the job. A value of 65 535 causes an error message to be sent and the request to be ended.
Country or region ID of file name. The country or region ID of the file name. A value of blanks indicates that the country or region ID of job should be used.
File flag. Whether the file is an IBM i integrated file system file or an external file (a workstation file not on a System i platform).
| 0 | External file |
| 1 | IBM i integrated file system file |
File names buffer. The names of external files or IBM i integrated file system files being listed. The file names are laid out one after another in this buffer. There is a pair of offset and length fields for each file name in this buffer.
Language ID of file name. The language ID of the file name. A value of blanks indicates to use the language ID value of the job.
Length of file name. This is the length in bytes of the external file name in the external file names buffer.
Offset of file name. This offset from the start of the file descriptor buffer specifies the start of an external file name.
Reserved. Reserved for future use.
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. |
| CPF9549 E | Error addressing API parameter. |
| CPF9556 E | API not valid at this time. |
| CPF9558 E | View already contains file descriptors. |
| CPF955B E | Number of entries not valid. |
| CPF955D E | View data overflow. All debug data lost. |
| CPF956B E | File name length not valid. |
| CPF956C E | File name offset not valid. |
| CPF9575 E | File flag not valid. |
| CPF9581 E | CCSID of file name parameter not valid. |
API introduced: V3R1
[ Back to top | Debugger APIs | APIs by category ]