Inspecting program data with Assembler

You can find out if your program is executing as it should by displaying program data, registers, and loaded memory. With Code Debug TSO commands, you can view and modify the contents of variables defined in your program and the data that is passed in parameter lists. The data is formatted in the display by the data type defined in your program. All of the data displays can be modified by typing over the values.

Described in this section are the Automatic Keep function and the Code Debug TSO commands KEEP, PEEK, MEMORY, and GPREGS.

Displaying and Modifying Program Variables

Code Debug TSO automatically displays the values of data items referenced by the current execution statement whenever execution halts. These values are displayed in a Keep window at the top of the source display as shown in following figure.  Each time the program halts, a new set of variables and their values are displayed.

Keep Window Displaying Automatic Keeps

If a variable of interest is not automatically kept, you can use an explicit KEEP command or the PEEK command to temporarily display the contents of a variable.

The KEEP command is used when you want to continuously display the data values in a window at the top of the Source screen as shown in following figure. Code Debug TSO inserts a K in column 9 of the window to differentiate between the explicitly kept items and the automatically kept items. In this example, OUTDCB is an automatically kept data item.

Displaying Program Data Values in the Keep Window

The data values in the Keep window are updated at each breakpoint as the program is executed. You can remove data items in the Keep window by entering a D (Delete) in the line command area next to the data item to be removed.

The Keep window is both scrollable and adjustable in size. The window becomes scrollable when the data exceeds the size of the window. Scrolling is cursor sensitive; that is, the cursor must be in the Keep window for scrolling to take place. Move the cursor to the window and use the PF7 (UP) and PF8 (DOWN) keys to scroll the data vertically. Use the PF22 (DRIGHT) and PF23 (DLEFT) keys to scroll the Keep window horizontally. To ensure that the cursor remains in the Keep window while scrolling, put the cursor on the segmented execution status line before using your scroll keys. You can do this either with the up and down arrow keys or with the Tab key.

You can set the size of the Source, the Keep window, and the Automatic Keep window. The automatically kept items can, by default, be displayed in the Keep window at the top of the screen or in a separate Automatic Keep window at the bottom of the screen. See the SET command in the Command-and-syntax-reference for additional information.

If you do not want to continuously display a data item, use the PEEK command to temporarily display the item. The PEEK command shows data values in the same format as the KEEP command, but the values are displayed on the source line where the item is defined as shown in following figure. The PEEK command scrolls to the specified data item and shows the current value. However, the displayed value disappears as soon as you continue executing your code.

Use the PF22 (DRIGHT) and PF23 (DLEFT) keys to scroll the Peek window horizontally.

Displaying Program Data Values With the PEEK Command

The KEEP and PEEK commands show data in three different default formats, depending on the data type.

Character data types are displayed in EBCDIC format with a template on top to indicate the length of the string.

Decimal (zoned and packed), fullword, and halfword data types are displayed in the decimal format. The doubleword data type is displayed in the floating point format. Other data types (hexadecimal, binary, address) are displayed in the verify format, which displays values up to 16 bytes horizontally in the hexadecimal format. If the data type is X (hexadecimal), you can display the value beyond 16 bytes by scrolling to the right.

See the following figure for an example of various data types displayed.

Displaying Various Data Types With the PEEK Command

Both the KEEP and PEEK commands have hexadecimal versions KEEPH and PEEKH for viewing the data contents in hexadecimal format regardless of the data type. The hexadecimal values are displayed vertically, and scrolling is allowed if there is data beyond 30 bytes.

The VERIFY command displays data contents horizontally in the hexadecimal format regardless of the data type; however, only 16 bytes are displayed. See the Displaying and Modifying Object Code for more information on the VERIFY command.

You can enter the KEEP, KEEPH, PEEK, or PEEKH command either from the line command area or from the primary command area. To inspect data, scroll to the source line that contains the data area and place the letter K (Keep), KH (KeepH), P (Peek), or PH (PeekH) in the line command area. Code Debug TSO displays the data contents in the appropriate format. Enter these commands in the line command area on a source line that references a data area label. For example, if you type over statement 71 in following figure with the letter P, the contents of INDCB are displayed.

If there is more than one data label on a single source line, Code Debug TSO defaults to displaying contents of the first data label. You can display the second data label INREC rather than the first data label INDCB on statement number 71 by typing P2 over the line command area. Type P* or K* to display the contents of all the data areas on a line.

Entering the PEEK Command

If you know the label name of a data area that you wish to display, you can also type the command from the primary command line. When you enter PEEK INREC, Code Debug TSO scrolls down to INREC in the source display and shows the data contents as illustrated in following fiugre.

Result of Entering the PEEK Command

Modifying Program Variables

There are two ways to modify program data. One is to type over the displayed field and press Enter. Typing over a displayed or kept item invokes an implicit MOVE. Another is to use the MOVE command from the primary command line. In order to modify a character or a zoned field using the MOVE command, you must enclose the data to be moved in single quotes to indicate literal data. An example is,

MOVE ’MOVE DATA’ TO CHAR

The target field is either padded with blanks (X'40') or truncated at the right side. If you wish to move a hexadecimal value, couple the data with the letter X followed by the data enclosed in single quotes. For example,

MOVE X’128’ TO HALFW

To modify a packed field, do not enclose the data to be moved in single quotes to indicate a decimal value. For example,

MOVE 789 TO PACKED

The target field is padded with binary zeros (X'00') or truncated at the left side.

Inspecting Tables

If a table is composed of character data or you display it using KEEPH or PEEKH, the value is shown in a translate table (CHARTABL DS 256C) as in following figure. For instance, entering KEEPH CHARTABL on the primary command line displays the occurrence field and the hexadecimal data field. The occurrence field defaults to 1 and remains 1 throughout your program. By typing over the occurrence field to an index other than 1 and pressing Enter, you can update the display to the corresponding element in the table. Code Debug TSO issues a warning message when the index exceeds the limit.

Displaying a Table in the Keep Window

Add a table entry modifier, such as +1 or -3, to the occurrence field and toggle through the table by pressing Enter. The index is automatically increased or decreased by the amount of the modifier each time Enter is pressed. See the following figure.

Toggling Through a Table for Each Entry

Displaying and Modifying Object Code

The VERIFY command without any keywords shows the object code for each statement embedded in the Source screen. See the following figure. Code Debug TSO displays the mnemonic, offset, object code, and effective addresses per source line. Enter DELETE VERIFY on the primary command line to remove the object code format from the screen. You can display and reset the object code format at the individual-instruction or data-area level by entering VERIFY on the command line and specifying a location as a keyword.

Result of Entering the VERIFY Command

Code Debug TSO displays up to 16 bytes of the data contents in the verify format. If you wish to display a long data area, enter MEMORY and examine the data contents at the raw memory level. See the Displaying Memory for more information on how to use the MEMORY command.

PEEK and KEEP commands on hexadecimal and packed items with a length greater than 12 default to the verify format. If you want to continuously display a data area in the verify format, enter the KV line command to display it in a Keep window.

You can type over any displayed field, press Enter, and modify your program as long as the area is not protected. In fact, entering VERIFY and typing over the displayed fields has the same effect as applying a dynamic zap to your program.

Displaying General-Purpose Registers

Code Debug TSO provides several ways to check general-purpose register values. The SHOW ACTIVE command displays comprehensive diagnostic information including register values (See the Show ACTIVE Screen). The PEEK and KEEP commands let you display a specific register content while you are in the source. The GPREGS command opens the GPREGS window at the bottom of the screen and displays the sixteen (16) general-purpose register contents. You can remove the GPREGS window by entering GPREGS OFF.

SHOW ACTIVE Screen

The register values displayed by the PEEK, KEEP, or GPREGS command can be altered by typing over the values and pressing Enter.

Displaying Memory

If you want to examine and modify blocks of memory as hexadecimal data bytes, enter the MEMORY command or the M line command to show the Memory screen. The VERIFY command shows the object code intermixed with the source code, but the MEMORY command shows the current state of storage in the unformatted dump format. You can access the program at any location in memory as long as it is not fetch-protected. You can follow pointers by using indirect specification of locations and scroll through memory beyond module boundaries. Since the MEMORY command is not bound to a particular view of the program, it operates without a source listing. If data on the Memory screen is not protected, it can be changed by typing over the values.

If you enter the MEMORY command without any keywords, memory is shown from the beginning of the active program. The name of the active program is displayed on the right-hand side of the fourth header line. If you place the letter M in the line command area and press Enter, memory is shown starting at that location. The Memory screen default for the line command area is the offset format and the base address is displayed on the first line. You can toggle between address (24-bit or 31-bit mode) and offset format using the LINE command. For example, typing LINE 24 on the primary command line shows the storage location in 24-bit addresses.

You can specify a location using expressions mixing register, absolute addresses, and offsets. For example, entering MEMORY R1%+3e displays the storage starting from the location +3E of the 24-bit address contained in register 1. You can chain pointers by adding the % (24-bit mode), ? (31-bit mode), or ! (64-bit mode) indirect addressing symbol. You must enter the SET MODE 64 command before using an exclamation point for indirect addressing. An example of indirect addressing is MEMORY R1%% which displays storage starting from the 24-bit address pointed to by the 24-bit address contained in register 1.

Following Pointers—Result of Entering GPREGS and MEMORY R1%%

While you are in the Memory screen, you can use PF2 (PEEK CSR) to follow pointers and display memory starting from the address pointed to by the cursor position. This is preferable to entering the absolute address or entering multiple indirect address signs (%, ?, and !) from the primary command line. For example, place the cursor at C1A158 (address 5E421) in above figure and press PF2 to display memory starting from C1A158, as long as it is not a fetch-protected address.

Code Debug TSO commands that are allowed on the Memory screen are FIND, EXCLUDE, and scrolling commands. You cannot set breakpoints or open a data display window from this screen. Press PF3 (END) or PF6 (LOCATE *) to continue your source listing debugging at the source level.

DSECT Processing

This section shows how an established DSECT can be reassigned, tested, and used at another location as a valid template.

Following figure shows the source display of program TRITSTA at the point where the DSECT TSTREC established addressability using register 2. The Keep window shows the contents of register 1 and register 2, as well as the data contained in the DSECT and the automatically kept data. (The Keep window has been expanded to show all the data items by entering the SET KEEP 12 command.) Although the base address 7C081 is set for TSTREC, the line command area for the DSECT continues to show the displacement instead of the absolute address even if the LINE command is set to 24 or 31. The LINE command controls the line command area format, displayed as statement numbers, offsets, or addresses (24-bit or 31-bit).

Program TRITSTA

Once your program establishes addressability to a DSECT, you can temporarily reassign the DSECT address through Code Debug TSO and test if the same DSECT can be used at another location as a valid template. The original DSECT address established by executing your program can be restored at any time.

To reassign DSECT addressability and access data from another location, it is necessary to allocate a work area for the data to be retrieved. Code Debug TSO provides the GETMAIN command to allocate virtual storage and return the starting address of the memory acquired. Since DSECT TSTREC requires 4 bytes of storage, type GETMAIN 4 on the primary command line and press Enter to allocate four bytes of memory to be used for DSECT processing. The starting address of the storage acquired by the GETMAIN command is returned in register 1 and the condition code is returned in register 15. See the following figure. The USING command can be used to reassign register 1 to the DSECT TSTREC. When returning to the original register, use the DROP command.

Result of Entering the GETMAIN Command

The following examples illustrate the use of the GETMAIN keywords. See the Command-and-syntax-reference for definitions of all the GETMAIN keywords.

1. To acquire 128 bytes of storage:
   GETMAIN 128 or GETMAIN LV=128
2. To acquire 4096 bytes of storage and return the starting address in register 2 rather than register 1:
   GETMAIN 1K A=2 or GETMAIN 4096 A=2
3. To acquire storage using the length contained in register 5, starting on a page boundary rather than a doubleword boundary:
   GETMAIN LA=5 BNDRY=PAGE
4. To acquire 256 bytes of storage and initialize with ones (1) rather than zeros (0):
   GETMAIN 256 INIT=1
5. To acquire storage above the 16 MB line rather than below the 16 MB line:
   GETMAIN 8 LOC=ABOVE
6. To acquire 256 bytes of storage using subpool 2 rather than subpool 0:
   GETMAIN 256 SP=2

Above figure shows that the return address in register 1 is 5D5B0. Typing MEMORY R1% shows the Memory screen starting from address 5D5B0. See the following figure. Since four bytes of storage starting from 5D5B0 are available and are initialized with zeros, type over either the character fields or the hexadecimal fields with any arbitrary data, such as 1567 or X’F1F5F6F7’, and press Enter. Return to the Source screen by pressing PF3 (END).

Modifying Memory at Address 05D5B0

The DSECT TSTREC in the Keep window still shows the values 0 for TYPE and 3, 4, 5 for sides A, B, and C. In order to access value 1 for TYPE and 5, 6, 7 for sides A, B, and C, temporarily reassign the DSECT address to register 1 instead of register 2 for testing purposes. Type USING TSTREC R1 on the primary command line and press Enter. The Keep window is updated to show the data values stored at starting address 5D5B0 using the TSTREC template. See the following figure.

Result of Entering the USING Command

The USING command, however, does not modify the base address for DSECT TSTREC in your program. Your program continues to execute using register 2 as the base address for TSTREC instead of register 1. Following figure shows the result of entering the VERIFY command on the label PACKIT (PACK TSTA,SIDEA). The effective address of SIDEA shows the address contained in register 2 instead of the reassigned address contained in register 1. You must modify all references to DSECT TSTREC in your program by typing over the verified fields in order to test your program using the new base address.

Verifying a PACK Instruction

In order to restore the original DSECT address using register 2, type DROP R1 on the primary command line and press Enter. You again see 3, 4, 5 for sides A, B, and C. The address in register 2 could have been typed over with the address in register 1, thus making instruction modification unnecessary.

In High Level Assembler, you can keep variables using the High Level Assembler qualification syntax. The variables are made addressable by the labeled dependent USING instructions in the program. Following figure shows an example:

Keeping Labeled Dependent USINGs