DSPPGMVAR (Display Program Variable) Command Description

DSPPGMVAR Command syntax diagram

Purpose

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-interface object-definition-table-vector (MI ODV) numbers. Up to 10 variables can be specified.

Restrictions:

  1. This command is valid only in debug mode. To start debug mode, refer to the STRDBG (Start Debug) command.

  2. This command cannot be used if the user is servicing another job, and that job is on a job queue, or is being held, suspended, or ended.

  3. This command cannot be used to display variables in a bound program.

  4. This command cannot be used to display variables within the system domain unless the user has *SERVICE special authority.

Required Parameter

PGMVAR
Specifies the names of from 1 through 10 program variables whose values are shown. The variables can be in a high-level language (HLL) or machine-interface (MI) program.

Element 1: Program Variables

*CHAR: This special value is specified instead of a variable name if a basing pointer is also specified. This special value displays a character view of a pointer being shown without the use of a based variable.

'program-variable': Specify the names of from 1 through 10 program variables 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 an element 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, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, MI ODV number, asterisk (single-dimensional cross-section), or a numeric variable name can be specified for a subscript. For more information on the program-variable value, refer to parameter values used for testing and debugging in the Information Center.

Some examples are: 

PGMVAR(A)
PGMVAR('A(2,B)')
PGMVAR('B(I1,*,I3)')
PGMVAR('VAR1 OF A(I,J IN B)')

Element 2: Basing Pointers

'basing-pointer': Specify up to five basing pointers for the each program variable being displayed. In some languages, the program variable may be based on a pointer variable. This set of values allows the user to specify the basing pointers for the variable to be displayed. 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. For more information on the basing pointer value, refer to parameter values used for testing and debugging in the Information Center.

Some examples are: 

PGMVAR(('VAR1(B,5)' 'PTR2(C,P2)'))
PGMVAR((VAR2 (BASEPTRA BASEPTRB)))

Optional Parameters

START
Specifies, for string variables only, the starting position in the string from which its value is being displayed. If more than one string variable is specified in the 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 scope of the open data path (ODP) is the job in which the Program variables occurs. If the job is multi-threaded, only those opens from the same thread can share this ODP.

starting-position: Specify the first position in the string being displayed. The START value specified must not be larger than the maximum string length for any variable specified, except that START(1) is allowed if the maximum length for a string is zero. The LEN value, plus the START position minus one, must not be greater than the maximum string length. These checks are made for each string variable specified in the PGMVAR parameter.

LEN
Specifies, for string variables only, the length of the string shown when the breakpoint is reached, starting at the position specified by the START parameter. If more than one string variable is specified in the PGMVAR parameter, the same value is used for each one. For a bit string, the value specifies the number of bits shown; 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, only LEN(*DCL) is allowed.

displayed-length: Specify the length of the data shown. The length (as well as the combination of START and LEN) must be no greater than the length of the shortest string specified in the PGMVAR parameter.

OUTFMT
Specifies the format in which the objects are shown.

*CHAR: The program variables are shown in character form.

*HEX: Program variables are shown in both character format and hexadecimal format.

OUTPUT
Specifies whether the output from the command is shown at the requesting display station or printed with the job's spooled output. More information on this parameter is in commonly used parameters.

*: Output requested by an interactive job is shown on the display. Output requested by a batch job is printed with the job's spooled output.

*PRINT: The output is printed with the job's spooled output.

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

*DFTPGM: The program currently specified as the default program has its variables shown.

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

RCRLVL
Specifies which recursion level of the program contains the variables being shown. 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, and then program B calls program A, a new recursion level of program A is formed. Some high-level languages also allow recursive procedures. For these programs, refer to the appropriate high-level language manual for more information.

*LAST: The last (most recent) call of the program contains the pointer being shown.

recursion-level-number: Specify the number of the recursion level of the program containing the pointer being shown.

Examples for DSPPGMVAR

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 for DSPPGMVAR

*ESCAPE Messages

CPF1999
Errors occurred on command.