Required Parameter Group:
Service Program: QTEDMPV
|
The Dump Module Variables (QteDumpModuleVariables) API is used to get a list of all the variable names and current values of those variables. Variable values may only be requested if an active call stack entry for the module specified exists in the job in which this API is called. Values existing in program static or automatic storage are not accessible by this API unless the program has a current call stack entry. All variables that were defined by the compiler and stored in the module HLL symbol table will be returned. This API supports the ILE CL, ILE COBOL, and ILE RPG compilers.
The module for which variable information is being requested must contain debug data. See the debug view (DBGVIEW) parameter of the Create RPG Module (CRTRPGMOD), Create COBOL Module (CRTCBLMOD), or Create CL Module (CRTCLMOD) command. It is not necessary that the job in which the program is running be in debug mode to use this API.
Variable names and, optionally, their values will be provided within the block in which they were declared. This API does not guarantee that those variables are returned in any particular order within the block.
The variable that is to receive the list of program variables and current values for the specified module.
The length of the receiver variable that is provided in the previous parameter. This value must be at least 48 to provide space for the receiver variable header section. The bytes available field tells the caller what size is required to receive the entire results of the request.
The format of the information returned for the module. The possible format name is:
The name of the program for which the variables and values will be provided.
The first 10 characters contain the name of the program. The second 10 characters contain the name of the library where the program is located. Each name will be left-justified. The special values of *LIBL and *CURLIB may be specified.
The object type of the program. The possible values are:
This API cannot be used to dump variable information for an OPM program.
The name of the module (left-justified) within the program. The module must be written in one of the supported ILE languages or an error is reported.
The content of the information returned for the module. The possible values are:
The handle used to continue from a previous call to this API that resulted in partially complete information. You can determine if a previous call resulted in partially complete information by checking the continuation handle variable in the receiver variable header section following the API call.
If the API is not attempting to continue from a previous call, this parameter must be set to blanks. Otherwise, a valid continuation value must be supplied. When continuing, the first entry in the returned receiver variable parameter is the entry that immediately follows the last entry returned in the previous call.
An error will occur under the following conditions:
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
The receiver variable area consists of:
Table 1. Receiver Variable Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of variable sections |
| 12 | C | CHAR(10) | Returned library |
| 22 | 16 | CHAR(10) | Reserved |
| 32 | 20 | CHAR(16) | Continuation handle |
| Note: The following information is repeated as many times as the value specified in the number of variable sections field. | |||
|
|
|
| Module variable header section |
|
|
|
| Module variable section |
This table describes the common header area to each
subsequently defined module variable section.
Table 2. Module Variable Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of module variable section |
| 4 | 4 | BINARY(4) | Offset to next variable |
| 8 | 8 | BINARY(4) | Variable entry type |
This portion of the module variable section will always start in the next available 4-word boundary to ensure proper alignment of the BINARY(4) fields within each section. The caller must use the offset to next variable field to find the start of the next module variable section and use the length of module variable section to determine the length of the current section.
The following table is used when the variable entry being
returned is scalar.
This section could occur
by itself or following an array definition.
Table 3. Scalar Variable Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Variable type |
| 4 | 4 | BINARY(4) | Total digits |
| 8 | 8 | BINARY(4) | Precision |
| 12 | C | BINARY(4) | Scaling factor |
| 16 | 10 | BINARY(4) | Offset to variable name |
| 20 | 14 | BINARY(4) | Length of variable name |
| 24 | 18 | BINARY(4) | Length of default value |
| 28 | 1C | BINARY(4) | Length of hexadecimal value |
| 32 | 20 | BINARY(4) | String content descriptor |
| 36 | 24 | BINARY(4) | Length of string prefix |
|
|
| CHAR(*) | Variable name |
|
|
| CHAR(*) | Default value |
|
|
| CHAR(*) | Hexadecimal value |
All variable values will be returned in displayable character format. For example, if the internal representation of a 2-byte unsigned integer is X'0345' the data returned through this API in the default value area will be '837 ' (X'F8F3F7404040'), and in the hex value area will be '0345' (X'F0F3F4F5').
When the scalar values of an array are being retrieved, the values will be returned in row major order, with no separating characters. The data option parameter will be used to determine if any values are displayed and in what form.
The following table is used when the variable entry being
returned is an array.
This section will define the array and will be followed by
one or more scalar variable sections.
Table 4. Array Definition Variable Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of scalar fields |
| 4 | 4 | BINARY(4) | Offset to first variable |
| 8 | 8 | BINARY(4) | Offset to dimensions |
| 12 | C | BINARY(4) | Offset to array name |
| 16 | 10 | BINARY(4) | Number of array dimensions |
| 20 | 14 | BINARY(4) | Length of array name |
|
|
| BINARY(4) | Dimension lower bound |
|
|
| BINARY(4) | Dimension upper bound |
|
|
| CHAR(*) | Array name |
The following table is used when the variable entry being
returned is a block definition. One of these sections will exist for
each block defined in the program. A block definition entry will
precede all other variable entry sections for variables defined
within the specified block.
Table 5. Block Definition Variable Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Block number |
| 4 | 4 | BINARY(4) | Offset to block name |
| 8 | 8 | BINARY(4) | Length of block name |
|
|
| CHAR(*) | Block name |
Array name. The field containing the name of the array.
Block name. The field containing the name of the block.
Block number. The number of the block.
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Continuation handle. When not all the requested data can be returned on a single call to this API, a value will be supplied in this field which may be used to continue on the next call to this API.
Default value. The value of the variable represented in the default format for the variable type.
Dimension lower bound. The lower bound of an array dimension.
Dimension upper bound. The upper bound of an array dimension.
Hexadecimal value. The value of the variable represented in hexadecimal format as it is stored in the machine.
Length of array name. The length of the array name field.
Length of block name. The length of the block name field (may be zero if no name is associated with the block).
Length of default value. The length of the data in the default value field. This will be zero if the data option parameter is 0.
Length of hexadecimal value. The length of the data in the hexadecimal value field. This will be zero if the data option parameter is 0 or 1.
Length of module variable section. The module variable entry section length, including the length of the module variable section header.
Length of string prefix. The length of the string prefix (may be 0 if no prefix is associated with the string).
Length of variable name. The length of the variable name field.
Number of array dimensions. The number of dimensions in the array. The dimension upper and lower bound fields are repeated for each array dimension.
Number of scalar fields. Number of scalar fields in each array element. There will be one module variable section for each scalar following an array definition header.
Number of variable sections. The number of variable entries returned by the API. These include block variable entries, scalar variable entries, and array variable entries.
Offset to array name. Offset to the start of the array name field.
Offset to block name. Offset to the start of the block name field.
Offset to dimensions. Offset to the start of the first dimension lower bound field.
Offset to first variable. Offset to the start of the module variable header section for the first scalar variable.
Offset to next module variable header section. Offset to the start of the next module variable header section.
Offset to variable name. Offset to the start of the variable name field.
Precision. The precision associated with a decimal type (packed, zoned, or binary decimal).
Reserved. An ignored field.
Returned library. The library where the program was found. This is useful when *LIBL or *CURLIB is specified for the program library portion of the program name parameter.
Scaling factor. The scaling factor associated with a decimal type (packed, zoned, or binary decimal).
String content descriptor. The type of the string variable. It may be one of the following values:
Total digits. The total number of digits associated with a decimal type (packed, zoned, or binary decimal).
Variable entry type. The type of variable section that follows the module variable header section. It may be one of the following values:
Variable name. The field containing the name of the variable.
Variable type. The data type of the variable. It may be one of the following values:
|
Top
| Debugger APIs
| Source Debugger APIs Source Debugger APIs and Exit Programs | Create View APIs | APIs by category |
| [Information Center Home Page | Feedback ] | [Legal | AS/400 Glossary] |