Start View Creation (QteStartViewCreation) API
Required Parameter Group:
| 1 | Input file descriptor buffer | Input | Char(*) |
| 2 | Output file descriptor buffer | Input | Char(*) |
| 3 | Format name | Input | Char(8) |
| 4 | Discard previous views | Input | Char(10) |
| 5 | Processor ID | Input | Char(20) |
| 6 | View CCSID | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Service Program: QTECRTVS
Threadsafe: No
The calling program uses the Start View Creation (QteStartViewCreation) API to initialize the debug view creation environment. This API should be the first one of the view creation APIs to be called.
This calling program is usually a text preprocessor or a compiler. In this document, the term processor will be used to specify any program that reads input text and produces view data for the debugger.
The processor that calls the Start View Creation API must provide the names of the input file read and the output file created (if any). The input and output files may be IBM® i library files or IBM i integrated file system files.
The input file name is the name of the root source file read by the processor. If the input file is an IBM i library file created by a previously run processor, then view information is stored with the file. If the input file is an IBM i integrated file system file, the view information is stored in a debug view integrated file system file that was created by the End View Creation API. The name of the debug view integrated file system file is the same as the input integrated file system file with the extension of ".dbgvwinfo" appended at the end. The input file view information is combined with the view information previously produced by the processor and stored in the output source file specified by the processor. If the input file is an IBM i integrated file system file, the debug view integrated file system file with extension ".dbgvwinfo" is deleted after reading the view information it contains.
If an input file is specified and there is no view information associated with the file, it is assumed that this file is the root source from which the program is created. It is also assumed that the processor that specifies this file is the first processor in the chain of processors that produces the program.
The processor creating the view supplies the CCSID in which all supplied text is stored. Thus, when view text is extracted, all supplied text is translated from this CCSID to the CCSID of the job. When view text (such as macro expansion text) is supplied, it must be supplied in the same CCSID. Text that comes from other files may be in any CCSID, as it will automatically be translated into the job's CCSID when the text is retrieved.
If no input file is specified, it is assumed that a previous processor created view information in a temporary space, instead of storing it with the file. This is the case when a compiler runs and produces view information. Since the compiler does not produce an output file to be read by another processor, the view information is stored in a temporary location associated with the process, and no output file is specified.
Each processor creates view information that is combined with information produced by previous processors. The final, and complete, view information is stored by the binder in the module and program object associated space.
After the view information is complete, the End View Creation API should be called.
The input file must exist and be available at the time this API is issued. The output file must exist and be available at the time the QteEndViewCreation API is issued.
Authorities
- Authority Required
- The authorities required are dependent on the format name parameter.
If the format name is FILA0100:
- *USE authority to the input file
- *EXECUTE authority to the input file library
If the format name is FILA0200:
- *R authority to the input file
- *X authority to each directory in the input file path
- *R and *OBJEXIST authority to the debug view file, if it exists
- *WX authority to the parent directory of the debug view file, if it exists
Required Parameter Group
- Input file descriptor buffer
- INPUT; CHAR(*)
The name of the file read by the processor creating debug data. This file may have been created by the customer, or it may be the output of a previously run preprocessor. The special value of *NONE is used when input from the processor does not come from a source file. In general, the only processor which would indicate *NONE is the back end of the compiler. The *NONE special value must be specified in the IBM i file name field of the FILA0100 format or in the file name field of the FILA0200 format.
This file may contain view information if it is created by a previously run preprocessor.
The structure of this parameter is specified by the format name parameter.
- Output file descriptor buffer
- INPUT; CHAR(*)
The file written by the processor creating debug data. A special value of *NONE for the output file indicates that the view information created will remain with the job and will be passed to the next compilation step without being associated with a specific file. Generally, only the compiler uses this special value, as it does not create a source file to be read by another processor. The *NONE special value must be specified in the IBM i file name field of the FILA0100 format or in the file name field of the FILA0200 format.
The associated space of this file will contain view information created by this processor in addition to view information created by any previous preprocessor steps. It is the responsibility of the processor to create this file and make it available before the QteEndViewCreation API is called.
The structure of this parameter is specified by the format name parameter.
- Format name
- INPUT; CHAR(8)
The content and format of the information supplied by the calling program in the input file descriptor buffer and the output file descriptor buffer. The valid values for format name are:
FILA0100 IBM i file FILA0200 IBM i integrated file system file
- Discard previous views
- INPUT; CHAR(10)
Whether the program creating debug view information wants the source debugger support to throw away any previously created view information. This allows a processor to force the view information created to be the only debug data available. In general, processors would specify *NO to allow any previous processor's view information to be included in the final program object.
*YES The source debugger support does not use any previously built view information but rather starts with the information provided by the processor creating debug data. *NO The source debugger support uses any previously built and existing view information and adds to it the view information created during this compiler step.
- Processor ID
- INPUT; CHAR(20)
The processor that creates view information.
- View CCSID
- INPUT; BINARY(4)
The CCSID of any text supplied to the view creation APIs.
- 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 | ||
| 0 | 0 | BINARY(4) | Offset of file name |
| 4 | 4 | BINARY(4) | Length of file name |
| 8 | 8 | BINARY(4) | File flag |
| 12 | C | BINARY(4) | CCSID of file name |
| 16 | 10 | CHAR(2) | Country or region ID of file name |
| 18 | 12 | CHAR(3) | Language ID of file name |
| 21 | 15 | CHAR(3) | Reserved |
| Note: The following field occurs after the preceding header fields. | |||
| 24 | 18 | CHAR(*) | File name |
Field Descriptions
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. The file flag specifies that the file is an IBM i integrated file system file. The only valid value is:
| 1 | IBM i integrated file system file |
File name. The name of the IBM i integrated file system file. A special value of *NONE for an input file indicates that input from the processor does not come from a source file. A special value of *NONE for an output file indicates that the view information created will remain with the job and will be passed to the next compilation step without being associated with a specific file.
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 IBM i integrated file system file name in the file name buffer.
Offset of file name. This offset from the start of the file descriptor buffer specifies the start of the file name.
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 file being listed. It is an IBM i object name, left-justified, and padded with blanks. A special value of *NONE for an input file indicates that input from the processor does not come from a source file. A special value of *NONE for an output file indicates that the view information created will remain with the job and will be passed to the next compilation step without being associated with a specific file.
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.
Reserved. Reserved for future use. This field must be initialized to hexadecimal zeros.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9549 E | Error addressing API parameter. |
| CPF9554 E | Discard Previous Views parameter 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. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9809 E | Library &1 cannot be accessed. |
| CPF9810 E | Library &1 not found. |
| CPF9815 E | Member &5 file &2 in library &3 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9822 E | Not authorized to file &1 in library &2. |
| CPFA0D4 E | File system error occurred. Error number &1. |
API introduced: V3R1
[ Back to top | Debugger APIs | APIs by category ]