Viewing a Program in Storage

One function you will need when executing under TEST is to view the contents of your data items and registers.

The LIST subcommand (abbreviated "L") provides this facility, and it requires just one operand — the register(s) or address(es) of storage you want to view.

When using TEST, you specify what you want to work with via an address. There are several forms of addresses: registers, symbolic, relative, absolute, and indirect, as you will see in the following examples.

This section of the tutorial shows you the LIST subcommand of TEST and uses LIST to demonstrate the various forms of the addresses you can use on the TEST subcommands.

You will need to view the source code for SAMPLE1 while performing the following exercise; a listing of it appears in Example programs for the TEST tutorial.

(1) test sample1

     TEST

(2) list 0r

     0R  0001AD0C
     TEST

(3) list 5r:8r

     5R  FFFFFFFF   6R  FFFFFFFF   7R  FFFFFFFF   8R  FFFFFFFF
     TEST

(4) list 14r:3r

     14R  0000B82C  15R  0001CF68   0R  0001AD0C   1R  0001BFB0
      2R  FFFFFFFF   3R  FFFFFFFF
     TEST

(5) list (3r 9r 11r)

     3R  FFFFFFFF
     9R  FFFFFFFF
     11R  FFFFFFFF
     TEST

(6) go

     IKJ57023I PROGRAM UNDER TEST HAS TERMINATED NORMALLY+
     TEST

(7) list 0r:15r

     0R  0001AD0C   1R  0001BFB0   2R  FFFFFFFF   3R  FFFFFFFF
     4R  FFFFFFFF   5R  FFFFFFFF   6R  FFFFFFFF   7R  FFFFFFFF
     8R  FFFFFFFF   9R  FFFFFFFF  10R  FFFFFFFF  11R  FFFFFFFF
    12R  FFFFFFFF  13R  0001BFB8  14R  0000B82C  15R  0001CF68
    TEST

Test your program again, stopping at the start of your program.
To see the contents of a register, use the LIST subcommand, specifying the register number followed by the letter "R", meaning "register".
Hint: Be careful not to get confused with a common programming convention of naming the registers "R0", "R1", and so on. Under TEST, such names would designate a main storage location, as you will see later.
At times you may wish to view a consecutive range of registers. The notation for this is a colon separating the two registers of the range.
This subcommand requests registers 5 through 8.
Note that registers can wrap around, so you may specify a higher register number first.
You may wish to view the contents of a list of registers. In this case, you must enclose the list in parentheses and separate each register in the list with a comma or a blank.
This subcommand requests the contents of registers 3, 9, and 11.
Now execute the program.
This subcommand displays all of the registers, after the program has terminated.
Note that TEST initializes registers 2 through 12 with X'FFFFFFFF' to allow you to see which registers are changed by the tested program.
The above examples of registers show the three standard forms in which addresses can be specified on the TEST subcommands:
- A single address
- A range of addresses (separated by a colon)
- A list of addresses (enclosed in parentheses and separated by blanks or commas)
This is true whether the addresses are registers or main storage locations.
```
(8) list charcon

     CHARCON  TEST EXAMP
     TEST

(9) list fullcon

     FULLCON  -1
     TEST

    list halfcon

     HALFCON  +32
     TEST

(10) list adcon

      ADCON  118676
      TEST

     list hexcon

      HEXCON  0000001F
      TEST

     list packcon

      PACKCON  +25
      TEST

     list bincon

      BINCON  10101100
      TEST

(11) list charcon:bincon

      CHARCON  TEST EXAMP...*.
      TEST

(12) list (adcon packcon 5r)

      ADCON  118676
      PACKCON  +25
       5R  FFFFFFFF
      TEST
```
Viewing the contents of main storage locations is just as easy as viewing registers. All you need to specify is the address or addresses of the locations you want to view.

Because you assembled and link-edited your program with the TEST option, you will be able to view the contents of your program by using the symbolic names on your data items and instructions.
This causes TEST to display the contents of CHARCON in character form. TEST chooses character because you defined the item in your assembler code as CL10.
Listing a fullword or halfword item causes TEST to convert the value to a signed decimal number, which is easier to read than binary.
Here are the other data items in the program, listed with the default characteristics implied by their definition.
Again, you may use the range and list forms of the LIST subcommand. This subcommand displays all of the storage between CHARCON and BINCON. TEST uses the first data type to determine how to display the storage.
Note: A dot indicates an unprintable character.

Here is a list of addresses, in parentheses. You can mix registers and storage locations in the list.

(13) list save

      SAVE
            +0  +0
            +4  +114616
            +8  +0
            +C  +0
           +10  +0
           +14  +0
           +18  +0
           +1C  +0
           +20  +0
           +24  +0
           +28  +0
           +2C  +0
           +30  +0
           +34  +0
           +38  +0
           +3C  +0
           +40  +0
           +44  +0
      TEST

(14) list fullcon:bincon

      FULLCON
            +0  -1
            +4  +31
            +8  +2155461
            +C  -488423227
           +10  -406727465
           +14  +604
           +18  -1409285540
      TEST

Notice that displaying an item defined with a duplication factor causes TEST to recognize this in its format.

Sometimes LIST's default data type is not very helpful; here all the storage after FULLCON is treated as fullwords.

Note: The default is the type specified in the program for the first item in the range.

(15) list bitcon

(16)  IKJ57280I ADDRESS BITCON NOT FOUND+
      IKJ56703A REENTER THIS OPERAND -

(17) ?

      IKJ57280I BITCON NOT IN INTERNAL SYMBOL TABLE FOR TEMPNAME . SAMP1

(18) |

      TEST

(19) list stop1

      STOP1
           +0    LH    R3,122(,R12)
      TEST

     list stop2

      STOP2
           +0    A     R3,114(,R12)
      TEST

     list stop3

      STOP3
           +0    ST    R3,118(,R12)
      TEST

(20) list stop1:stop3

      STOP1
           +0    LH    R3,122(,R12)
           +4    A     R3,114(,R12)
           +8    ST    R3,118(,R12)
      TEST

(21) list (stop1 stop3)

      STOP1
           +0    LH    R3,122(,R12)
      STOP3
           +0    ST    R3,118(,R12)
      TEST

This is a sample of an error, because the symbol BITCON does not exist in the program.
TEST asks you to reenter the incorrect address.
A "+" sign at the end of a message means that more information is available.
You can obtain this extra information by typing "?" with nothing else on the line.
To cancel the erroneous subcommand and return to the TEST mode, press the attention key. This produces the "|" symbol on the screen.
TEST also allows you to display instructions. You see the explicit assembler form.
This subcommand shows a range of instructions.

This subcommand shows a list of instructions.

(22) list charcon x

      CHARCON
           +0  E3C5E2E3 40C5E7C1 D4D7
      TEST

(23) list fullcon x

      FULLCON  FFFFFFFF
      TEST

(24) list fullcon:bincon x

      FULLCON
           +0  FFFFFFFF 0000001F 0020E3C5 E2E340C5
               E7C1D4D7 0000025C AC
      TEST

(25) list charcon x length(5)

      CHARCON  E3C5E2E3 40
      TEST

(26) list save x multiple(5)

      SAVE
           +0  00000000
           +4  0001BFB8
           +8  00000000
           +C  00000000
          +10  00000000
      TEST

     list charcon length(2) multiple(5)

      CHARCON
           +0  TE
           +2  ST
           +4   E
           +6  XA
           +8  MP
      TEST

(27) list save:bincon print(sample1)

      TEST

Now, for some other operands of LIST. You may wish to read the syntax of the LIST subcommand of TEST in z/OS TSO/E Command Reference at this time.

After the address on LIST, you can specify a data type that TEST should use to display storage. This overrides the defined data type of the symbol.
This requests TEST to display CHARCON in hexadecimal.
Here is FULLCON displayed in hexadecimal.
Here is a range of storage, also in hexadecimal.
The length operand specifies the number of bytes you want to have displayed. This overrides the defined length of the symbol.
The multiple operand allows you to specify a multiplicity factor for the item. You can use this to display a table, or to format a long area for readability.
The print operand allows you to specify a data set, rather than the terminal, to which the list should be directed. You may later print the data set to read the information easily.
The name of the data set that will contain the list consists of the name you specify, preceded by your prefix and followed by TESTLIST as the descriptive qualifier. Therefore, in this example, the information will be placed in ‘prefix.SAMPLE1.TESTLIST’.
```
(28) where charcon

(29) 1CFEA. LOCATED AT +82 IN TEMPNAME.SAMP1 UNDER TCB LOCATED AT 7C2560.
     TEST

(30) list 1cfea.

      0001CFEA.  E3C5E2E3
      TEST

(31) list 1cfea. c length(5)

      0001CFEA.  TEST
      TEST

(32) list +82 length(8)

          +82  E3C5E2E3 40C5E7C1
      TEST

(33) list save+20

      0001CFB4.  00000000
      TEST

(34) list save+32n

      0001CFB4.  00000000
      TEST

(35) list save-10

      0001CF84.  5030C076
      TEST

(36) where save-10

 1CF84.  LOCATED AT +1C IN TEMPNAME.SAMP1 UNDER TCB LOCATED AT 7C2560.
TEST

(37) list +1c

          +1C  5030C076
      TEST
```
So far, you have seen the various operands of the LIST subcommand of TEST. All addresses were specified as symbolic addresses. Normally, your symbolic names cannot be referenced at execution time, but using the TEST operand on the ASM and LINK commands caused your symbols to be available at execution time.

Other forms of addresses besides symbolic are absolute, relative, indirect, and address expressions, as shown below.
To obtain the absolute address of data or an instruction, use the WHERE subcommand.
This example is requesting the location of CHARCON.
TEST gives the absolute address and the address relative to the CSECT.
To use an absolute address in a LIST command, follow the address with a period. The period is a signal that you have entered an absolute address and not a register number or a symbolic address.
Because TEST does not know the data type of this address, it displays the data in hexadecimal, for the default length of four.
Using the data type and length operands lets you control how much storage is displayed, and in what format.
A relative address is indicated by a plus sign followed by a hexadecimal number. It represents the displacement of something from the beginning of the CSECT. (Later you will be able to change this "base" address.)
This is an address expression, meaning a symbolic, absolute, or relative address followed by a plus or a minus sign, followed by a hexadecimal number (modifying value).
If you prefer to express the modifying value in decimal, you must follow the number with the letter "n".
"+32n" is the same as "+20".
Here is a negative modifying value.
Just to check the address involved, WHERE tells you the absolute and relative addresses of SAVE-10.

This displays the same storage location as SAVE-10.

(38) list 1r

       1R  0001BFB0
      TEST

(39) list 1bfb0.

      0001BFB0.  8001BFB4
      TEST

(40) list 1r%

      0001BFB0.  8001BFB4
      TEST

(41) list 1r%%

      8001BFB4.  00000000
      TEST

     end

      READY

(42) listcat

      IN CATALOG:USERCAT
      USER01.SAMPLE1.ASM
      USER01.SAMPLE1.LOAD
      USER01.SAMPLE1.OBJ
      USER01.SAMPLE1.TESTLIST
      READY

Now to look at indirect addresses.

Viewing the contents of a register, as you have already seen.
Here is the data at the address specified in register 1.
Specifying a "%" or a "?" after a register says you want to view, not the register, but the data to which the register points.
This subcommand produces the same result as the previous two subcommands.

When you use "%", the effective address is treated as a 24-bit address. When you use "?", the effective address is treated as a 31-bit address.
You can stack "%" and "?" signs to indicate multiple levels of indirect addressing.
This means go to the address to which register 1 points, and then use that as an address, and view the data there.
After ending TEST, a LISTCAT command displays the data sets involved so far. Notice that the SAMPLE1.TESTLIST data set was created from your LIST subcommand with the PRINT operand.

In this section of the tutorial, you have seen several examples of the LIST subcommand to view registers and storage. You have also seen the three general forms of address operands on TEST subcommands:

Single address
Range of addresses
List of addresses.

Finally, you have seen the various types of addresses:

Symbolic
Absolute
Relative
Indirect
Expressions
Registers