The Display Program Variable (DSPPGMVAR) command shows the current value of one or more program variables in a program that is being debugged. The variables can be specified either by their variable names or by their machine-instruction object-definition-table-vector (MI ODV) numbers. A maximum of 10 variables can be specified.

Restrictions:

• You can use this command only in debug mode. To start debug mode, refer to the Start Debug (STRDBG) command.
• You cannot use this command if you are servicing another job, and that job is on a job queue, or is being held, suspended, or ended.

• You cannot use this command to display variables in a bound program.
• You cannot use this command to display variables within the system domain unless the user has *SERVICE special authority.

Parameters

Keyword	Description	Choices	Notes
PGMVAR	Program variables	Values (up to 10 repetitions): Element list	Required, Positional 1
	Element 1: Program variable	Character value, *CHAR
	Element 2: Basing pointer variable	Values (up to 5 repetitions): Character value
OUTFMT	Output format	*CHAR, *HEX	Optional
OUTPUT	Output	*, *PRINT	Optional
PGM	Program	Name, *DFTPGM	Optional
START	Char output start position	Integer, 1	Optional, Positional 2
LEN	Characters to display	Integer, *DCL	Optional
RCRLVL	Recursion level	Integer, *LAST	Optional

Top

Program variables (PGMVAR)

Specifies up to ten program variables whose values are to be shown. The variables can be in a high-level language (HLL) or machine instruction (MI) program.

This is a required parameter.

Element 1: Program variable

*CHAR

This special value can be specified instead of a variable name if a basing pointer is specified. This shows a character view of a pointer to be shown without the use of a based variable.

character-value

Specify the name of the program variable to be shown. The name must be enclosed in apostrophes if it contains special characters.

If the program variable is an array, the subscripts representing the elements in the array can be specified. If an array name is specified without any subscripts, all of the array elements are recorded. A single-dimensional cross-section can also be specified. Up to 132 characters may be specified for this program variable entry. This includes any qualifiers, subscripts, blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, machine-interface object-definition-table-vector (MI ODV) number, asterisk (single-dimensional cross-section), or a numeric variable name can be specified for a subscript.

Element 2: Basing pointer variable

character-value

Specify the name of a basing pointer variable. In some languages, the program variable may be based on a pointer variable. This set of values allows you to explicitly specify the basing pointers for the variable to be recorded. Each basing pointer name must be enclosed in apostrophes if it contains special characters.

If the basing pointer is an array, the subscripts representing an element in the array must be specified. Up to 132 characters can be specified for a basing pointer name. This includes any qualifiers, subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, MI ODV number, or a numeric variable name can be specified for a subscript.

Output format (OUTFMT)

Specifies the format in which the values of the program variables are shown. Additional descriptive information for some variable types is also shown with the variable values in a format predefined by the system.

*CHAR

The program variables are shown in character form.

*HEX

The program variables are shown in hexadecimal form.

Output (OUTPUT)

Specifies whether the output from the command is displayed at the requesting work station or printed with the job's spooled output.

*

The output is displayed (if requested by an interactive job) or printed with the job's spooled output (if requested by a batch job).

*PRINT

The output is printed with the job's spooled output.

Program (PGM)

Specifies the name of the program that contains the program variables shown.

*DFTPGM

The program previously specified as the default program has its variables shown.

name

Specify the name of the program whose program variables are shown.

Char output start position (START)

Specifies, for string variables only, the starting position in the string from which the value of the variable is to be shown. If more than one string variable is specified for the Program variables (PGMVAR) parameter, the same starting position value is used for each one. For a bit string, the value specifies the starting bit position; for a character string, the value specifies the starting character position.

1

The variable is shown from the first position on through the length specified for the Characters to display (LEN) parameter.

integer

Specify the first position in the string to be shown. The value supplied for the Char output start position (START) parameter must not be larger than the maximum string length for any variable specified, except that a value of 1 for the START parameter is allowed if the maximum length for a string is zero. The value supplied for the LEN parameter plus the value supplied for the START parameter minus one must not be greater than the maximum string length. These checks are made for each string variable specified for the PGMVAR parameter.

Characters to display (LEN)

Specifies, for string variables only, the length of the string shown when the breakpoint is reached, starting at the position specified by the Char output start position (START) parameter. If more than one string variable is specified for the Program variables (PGMVAR) parameter, the same value is used for each one. For a bit string, the value specifies the number of bits shown, and for a character string, the value specifies the number of characters shown.

*DCL

The string variable is shown to the end of the string or for a value of 200 bytes, whichever is less. If the string variable has a maximum length of zero, the only allowable value for the LEN parameter is *DCL.

integer

Specify the length of the data shown. The length (as well as the combination of values supplied for the START parameter and the LEN parameter must be no greater than the length of the shortest string specified by the PGMVAR parameter.

Recursion level (RCRLVL)

Specifies which recursion level of the program contains the variable whose value is to be displayed. Recursion level 1 is the first (or earliest) call of the program, recursion level 2 is the second call of the program, and so on to the last (most recent) recursion level in the stack. For example, if program A calls program B, then program B calls program A, a new recursion level of program A is formed. If the first call of program A contains the variable to be displayed, a value of 1 for the Recursion level (RCRLVL) parameter must be specified. Some high-level languages also allow recursive procedures.

*LAST

The value of the specified variable in the last (most recent) call of the specified program is displayed.

integer

Specify the recursion level of the program that contains the variable whose value is to be displayed.

Examples

Example 1: Displaying Program Variables

DSPPGMVAR   PGMVAR('&QUANT')  PGM(MYPROG)

Assuming that the program MYPROG is in debug mode, this command shows the name and current value of the CL variable called &QUANT its type and length are also shown.

Example 2: Displaying Program Variables

DSPPGMVAR   PGMVAR(TOTSALES  MANHRS)  PGM(REGION)  RCRLVL(1)

This command shows the program variables TOTSALES and MANHRS of the first call of the program REGION.

Error messages

*ESCAPE Messages

CPF1999

Errors occurred on command.