| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified program name | Input | Char(20) or Char(*) |
| 5 | Program type | Input | Char(10) |
| 6 | Module name | Input | Char(10) or Binary(4) |
| 7 | Returned library name | Output | Char(10) or Char(*) |
| 8 | Error code | I/O | Char(*) |
The Retrieve Module Views (QteRetrieveModuleViews) API is used to return a list of modules and views associated with a specified program to the caller of the API. The list includes all of the following:
If you specify a module name, a list of views for that module is returned. If you specify *ALL for the module name, the list includes all modules for a given program.
The module name parameter must be specified as either *ALL or blanks for OPM programs. The statement view and a source view (or the statement view and a listing view) are always returned. The module name field is returned as blanks.
This API also supports JAVA class file debug views. In this case the program type parameter must be *CLASS and the qualified program name parameter must be a null-terminated JAVA class file name. The class path name of the file that contains the JAVA class file is returned in the returned library name parameter. For JAVA, the module name parameter must be specified as a binary field that contains the number of bytes provided in the returned library name field for JAVA class path name information.
Information returned by the Retrieve Module Views API is used by the calling program as input parameters to the Register Debug View API. Every module returned has at least one view associated with it. This is the statement view. It can be assumed that any additional views returned have text associated with them, and source debug can be done on these modules.
The authorities required are dependent on the program type parameter. If the program type is *PGM or *SRVPGM, the authorities are as follows:
If the program type is *CLASS, the authorities are as follows:
A variable that is to receive the information requested. You can specify the size of this area to be smaller than that needed to hold the information. In this case, only part of the information is returned. However, the number of bytes that the API needs to return all of the information is still returned.
The length of the receiver variable. The minimum length is 8 bytes.
It is suggested that a length of 8 be passed to the API, which fills in the first two fields of the receiver variable. One of the fields, bytes available, indicates how much space must be provided. This space can then be obtained, and a second call to the API can be made.
The content and format of the module view information that is returned. The only valid value for this parameter is:
| VEWL0100 | Module view information. For more information, see VEWL0100 Format. |
The format of this parameter is dependent on the program type parameter. If the program type is *PGM or *SRVPGM, the format of this parameter is as follows:
The following special values may be used for the library name:
| *CURLIB | The job's current library. |
| *LIBL | The library list. |
If the program type is *CLASS, the format of this parameter is as follows:
The null-terminated class file name of the JAVA class.
The type of program for which a view is to be registered. This is the object type of the program object. The allowable values are:
| *PGM | ILE or OPM program |
| *SRVPGM | ILE service program |
| *CLASS | JAVA class file name |
The format of this parameter is dependent on the program type parameter.If the program type is *PGM or *SRVPGM, the format of this parameter is as follows:
If the program type is *CLASS, the format of this parameter is as follows:
The format of this parameter is dependent on the program type parameter.If the program type is *PGM or *SRVPGM, the format of this parameter is OUTPUT CHAR(10) as follows:
If the program type is *CLASS, the format of this parameter is OUTPUT CHAR(*) as follows:
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table shows the format of the receiver variable for the VEWL0100 format.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 elements |
| Note: The following fields repeat once for each element. | |||
| CHAR(10) | Module name | ||
| CHAR(10) | View type | ||
| CHAR(20) | Compiler ID | ||
| CHAR(10) | Main indicator | ||
| CHAR(13) | View timestamp | ||
| CHAR(50) | View description | ||
| CHAR(3) | Reserved | ||
| BINARY(4) | View number | ||
| BINARY(4) | Number of views | ||
All views for a module are listed together in the receiver variable. The number of views field contains the total number of views for the module. The views are contiguous.
Bytes available. The number of bytes of data available to be returned to the user.
Bytes returned. The number of bytes of data returned to the user.
Compiler ID. The ID of the compiler that generated this view. For unique identification the first 4 bytes are used as follows:
| x'00050000' | ILE C |
| x'00050001' | CSET C++ cooperative compiler |
| x'00060000' | ILE CL |
| x'00060001' | OPM CL |
| x'00070000' | OPM COBOL |
| x'00070001' | ILE COBOL |
| x'00170001' | OPM RPG |
| x'00170002' | ILE RPG |
| x'001D0000' | JAVA |
Main indicator. Whether the module is a main module (entry point) for the program. The main indicator field can have one of the following values:
| *MAIN | Module is a main module |
| *NOMAIN | Module is not a main module |
There is at most one main module per program. Service programs contain no main entry point. *MAIN is always returned for OPM programs. For JAVA class files *MAIN is returned if the class file has a main procedure. Otherwise, *NOMAIN is returned for JAVA.
Module name. The name of the module for this list entry. For OPM programs and JAVA class files, the module name is returned as blanks.
Number of elements. The number of elements returned in the receiver variable. Each element has the same format, and it is repeated in the receiver variable. If the number of elements is zero and the receiver variable has room for at least one element, the program has no views in the module requested. If the module requested is *ALL, zero elements indicate the program cannot be debugged. For OPM programs, a CPF9584 error code is returned, instead of a zero number of elements value, if the program cannot be debugged. For class files, a CPF9599 error code is returned, instead of a zero number of elements value, if the program cannot be debugged.
Number of views. The number of views in this module listed in the receiver variable
Reserved. An ignored field.
View description. A character string that describes the view.
View number. A number that identifies a view within a module. Each view has a unique view number, which is used when you specify a specific view to register using the Register Debug View API.
View timestamp. The timestamp indicating when the view was created. It has the format of the American National Standard timestamp.
View type. The type of view. The view type can be one of the following values:
| *TEXT | This is a view where text comes from files or text supplied by the processor. |
| *LISTING | This is a view where text comes entirely from text supplied by the processor. |
| *STATEMENT | This is a view consisting of statement identifiers. All modules have a statement view. |
When the program type parameter is *CLASS, class path name information is returned in the returned library name parameter. The following table shows the format of the returned library name parameter when the JAVA class file view information is retrieved. 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) | Offset to class path name |
| C | C | BINARY(4) | Length of class path name |
| CHAR(*) | Class path name | ||
Bytes available. The number of bytes available to be returned in the returned library name parameter. If the bytes available value is larger than the bytes provided value passed in the module name parameter, the API should be called again with a value that is at least as large as the bytes available. If the space provided is not large enough, the string space is filled with as many characters of the class path name as will fit.
Bytes returned. The number of bytes returned in the returned library name parameter.
Class path name. The path name of the file that contains the class file that was retrieved.
Length of class path name. The length of the class path name returned.
Offset to class path name. The offset from the start of the returned library name parameter to the class path name.
| Message ID | Error Message Text |
|---|---|
| CPF3C21 E | Format name &1 is not valid. |
| 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. |
| CPF9549 E | Error addressing API parameter. |
| CPF954F E | Module &1 not found. |
| CPF955F E | Program &1 not a bound program. |
| CPF9584 E | OPM program &1 cannot be added to ILE debug environment. |
| CPF9585 E | Program &1 already active in OPM debug environment. |
| CPF9587 E | Module name value &1 not valid. |
| CPF9591 E | Value specified in module name parameter is not valid. |
| CPF9592 E | Class file not found. |
| CPF9593 E | Not authorized to class file. |
| CPF9594 E | JAVA class file not available. |
| CPF9599 E | Class file cannot be debugged. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9809 E | Library &1 cannot be accessed. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
[ Back to top | Debugger APIs | APIs by category ]