Dump Module Variables (QteDumpModuleVariables) API

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.

Authorities

Authority Required

• *SERVICE special authority and *USE authority to the input program, or
• *USE authority to the input program when the input program is the caller of the API, or
• *CHANGE authority to the input program

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the list of program variables and current values for the specified module.

Receiver variable length

INPUT; BINARY(4)

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.

Format name

INPUT; CHAR(8)

The format of the information returned for the module. The possible format name is:

DMPV0100

Dump module variables.

Qualified program name

INPUT; CHAR(20)

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.

Program type

INPUT; CHAR(10)

The object type of the program. The possible values are:

*PGM	ILE program
*SRVPGM	ILE service program

This API cannot be used to dump variable information for an OPM program.

Module name

INPUT; CHAR(10)

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.

Data option

INPUT; BINARY(4)

The content of the information returned for the module. The possible values are:

0	Variable names only.
1	Variable names and current values in default character format (the type associated with the variable will be used in determining the format of the value returned).
2	Variable names, the current values in default character format, and the current values in hex format.

Continuation handle

INPUT; CHAR(16)

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 continuation handle is not blank on the first request for a given set of input parameters.
  
  
• The continuation handle is not the same as provided in the receiver variable header section on the previous call to this API.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of the Receiver Variable

The receiver variable area consists of:

• A receiver variable header section.
  
  
• A module variable header section for each variable returned by the Dump Module Variables API. The module variable header section consists of:
  
  
  • A fixed-length header section
    
    
  • A variable-length section containing the information requested for the module variable.

Receiver Variable Header Section

Table 1. Receiver Variable Header Section

Module Variable Header Section

This table describes the common header area to each subsequently defined module variable section.

Table 2. Module Variable Header Section

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.

Module Variable Section (Scalar Variable Entry Type)

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

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.

Module Variable Section (Array Definition Entry Type)

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

Module Variable Section (Block Definition Entry Type)

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

Field Descriptions

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:

Error Messages