LIST expression command

Displays values of expressions.

Read syntax diagramSkip visual syntax diagramLISTTITLEDUNTITLEDexpression'expression'GROUP1reference(,expression'expression'GROUP1reference)TITLED*FSWSSLSLOS;
Notes:
  • 1 Only for COBOL.
TITLED
Displays each expression in the list with its value. For PL/I, this is the default. For C and C++, this is the default for expressions that are lvalues. For COBOL, this is the default except for expressions consisting of only a single constant. For assembler, disassembly, and LangX COBOL, this is the default for expressions that are valid as receivers of a z/OS® Debugger assembler assignment statement.

If you specify TITLED with no keyword, all variables in the currently qualified block are listed. If you specify TITLED with an asterisk (*) and you are debugging a C, C++, or COBOL program, all variables in the currently qualified compile unit are listed.

If you are debugging a COBOL program, the following additional options are available with TITLED:

FS
Lists all variables defined in the COBOL File Section in the currently qualified compile unit.
WSS
Lists all variables defined in the COBOL Working-Storage Section in the currently qualified compile unit.
LS
Lists all variables defined in the COBOL Linkage Section in the currently qualified compile unit.
LOS
List all variables defined in the COBOL Local-Storage Section in the currently qualified compile unit.
* (C, C++, and COBOL)
Lists all variables in the currently qualified compile unit.
UNTITLED
Lists expression values without displaying the expressions themselves. For C and C++, this is the default for expressions that are not lvalues. For COBOL, this is the default for expressions consisting of only a single constant. For assembler, disassembly, and LangX COBOL, this is the default for expressions that are not valid as receivers of a z/OS Debugger assembler assignment statement. For the LIST command, an expression also includes character strings enclosed in either quotation marks (") or apostrophes ('), depending on the current programming language.

In C and COBOL, expressions containing parentheses () must be enclosed in another set of parentheses when used with the LIST command as in example LIST ((x + y) ⁄ z);.

GROUP (COBOL)
Displays a reference as an EBCDIC character string. If you specify GROUP on an elementary item, it has no effect. The operand following the GROUP keyword must be a reference; for example, LIST TITLED GROUP y;. You cannot specify expressions.
expression
An expression valid in the current programming language other than LangX COBOL.
'expression'
A valid LangX COBOL expression enclosed in apostrophes (').

Usage notes

  • For Enterprise COBOL for z/OS Version 5, this command has the following usage notes:
    • When you use the LIST command to display a record or group, the levels of the record or group are shown as they are declared in the program.
    • When you use the LIST command on an array (table), the output shows the value of each array element, one per line. The output changes in the following ways:
      • The subscripts for each array element are shown in parentheses after the name of the array. This matches how array subscripts are specified in COBOL. Previously, each line of the output had the word "SUB" at the beginning, and the subscripts were shown in parentheses after this word.
      • If the array has subordinate data items, which means the elements are groups but not scalars, the value of each subordinate data item is displayed for an array element before the values of the next array element are displayed. In other words, array element n is displayed before array element n+1. The output better reflects how the array is organized in memory.
    • When you use the LIST command to list a single member of an array, the output is the same as a variable of the given type.

      Examples:

      Given these arrays:

      5 ARR1 OCCURS 2 TIMES INDEXED BY IX1.                   
  10 X PIC 99 USAGE BINARY.                             
  10 Y PIC 99 USAGE BINARY.
5 ARR2 PIC 9 USAGE BINARY OCCURS 2 TIMES INDEXED BY IX2.

      The output is as follows:

      LIST ARR1 ( 1 ) ;      
10 X of 05 ARR1 = 00001 
10 Y of 05 ARR1 = 00002

LIST ARR2 ( 1 ) ; 
ARR2 ( 1 ) = 00000
    • The output of LIST %EPA when inside a declarative section shows the internal entry point of the declarative but not the entry point of the program.
    • When you use the LIST TITLED * command, only those variables for active blocks are shown.
    • When you use the LIST expression command to display the value of an element of an array and you do not specify an array subscript or index, the value of the first element is displayed. That is, it defaults to Index = 1.
    • You cannot use index data items as an index name when you reference an array element. For example, if you have the following declaration in your program, 77 IXDI1 USAGE IS INDEX, you cannot use IXDI1 as index in LIST ARR(IXDI1).
    • The number of digits that are displayed after you use the LIST command for a numerical value is consistent with what is specified in the Enterprise COBOL for z/OS Version 5 Programming Guide.
    • The result of displaying an expression with the LIST command shows the sign if either operand is signed. In the following example, LIST SIGNED_ONE + TWO = +0003, the first operand is signed.
    • When you use the LIST command to display a variable of National type, the output shows the N prefix. Example: NAT= N'abcde'.
    • You cannot display the values of variables in a Nested Program (block) if they are declared in the Local or Linkage Section and the Nested Program (block) is not active.
    • When you use the LIST TITLED command, the output that displays the value of a variable that has unprintable character is shown as dots. It shows HEX values only if you use %HEX.
    • For an object-oriented program, if a variable name is a part of both the Object name and the Method name, and you use the LIST command with this variable, you can get an error message to indicate that it is ambiguous.
    • The DBCS string is prefixed with a G, for example, V_-DBCS = G'DBCS string'.
  • For COBOL programs, if you want to use the LIST TITLED command with a variable that is named FS, WSS, LS, or LOS, you must enclose the name of the variable in parenthesis. For example, the command LIST TITLED (FS) lists the variable FS; the command LIST TITLED FS lists the variables in the File Section.
  • z/OS Debugger allows you to abbreviate many commands. This might result in unexpected results when you use the LIST command with a single-letter expression. For example, LIST A can be interpreted as the LIST AT command, which lists all breakpoints. However, if you wanted to display the value of a variable labeled A in your program, you need to use parenthesis: LIST (A).
  • If LIST TITLED * is specified and your compile unit is large, slow performance might result.
  • For COBOL, if LIST TITLED * is specified and your compile unit is large, you might receive an out of storage error message.
  • For COBOL, the LIST command can reference a condition name, a file name, or an expression.
  • For optimized COBOL programs, the LIST command cannot reference a variable that was discarded by the optimizer.
  • When using LIST TITLED with no parameters within the PL/I compile unit, only the first element of any array will be listed. If the entire array needs to be listed, use LIST and specify the array name (i.e., LIST array where array is the name of an array).
  • If a character variable contains character data that cannot be displayed in its declared data type, z/OS Debugger displays the data with a special character. The topic "How z/OS Debugger handles characters that can't be displayed in their declared data type" in the IBM® z/OS Debugger User's Guide describes what z/OS Debugger does in this situation. If you display the data in hexadecimal, it will require twice as many bytes. The maximum number of bytes that can be displayed is 65,535.
  • If the DATA option of the PLAYBACK ENABLE command is in effect for the current compile unit, the LIST expression command can be used while you replay recorded statements by using the PLAYBACK commands.
  • If you are trying to display a scalar item, the maximum length that LIST can display is 65,535 bytes.
  • You can enter the L prefix command by using the Source window prefix area to display the value of the variables on that line. For the list of supported compile units, see L prefix command (full-screen mode).
  • For Enterprise PL/I programs, to change the display format so that z/OS Debugger displays arrays and elements as they are stored in memory, enter the SET LIST BY SUBSCRIPT ON command.
  • If the Log window is not visible, z/OS Debugger displays the result of the LIST expression command in the List pop-up window.

Examples

  • Display the values for variables size and r and the expression c + r, with their respective names. 
    LIST TITLED (size, r, c + r);
  • Display the COBOL references as if they were elementary items. The current programming language setting is COBOL. 
    LIST (GROUP x OF z(1,2), GROUP a, w);
  • Display the value of the z/OS Debugger variable %ADDRESS. 
    LIST %ADDRESS;
  • In the disassembly view, display the value of register 1 (R1), which is the value of z/OS Debugger variable %R1. 
    LIST R1 ;
  • In COBOL, display the names and values of variables defined in the File Section. 
    LIST TITLED FS;

Refer to the following topics for more information related to the material discussed in this topic.