Inspecting program data for COBOL

Code Debug TSO lets you view the contents of variables defined in your program and the data that is passed to the working storage and the linkage. The data is formatted by the data type defined in your program.

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

When you have Code Debug Db2 Extension and File-AID for Db2 installed, you can also browse and edit Db2 table data during a Code Debug TSO session. See Using-Code-Debug-Db2-Extension for more information.

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 the 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 the variable.

The KEEP command is used when you want to continuously display the contents of a variable. When the KEEP command is entered, Code Debug TSO continuously displays and updates the data values in the Keep window until you delete the keep. Code Debug inserts a K in column 9 of the Keep window to differentiate between the explicitly kept items and the automatically kept items.

The PEEK command is used when you want to temporarily display the contents of a variable. When the PEEK command is entered, Code Debug TSO scrolls to the DATA DIVISION statement, displays the data values in a window on the right side of the screen, and inserts a P in column 9 of the source. Some of the statement will be overlaid. When you resume execution, the window is removed from the screen. Examples of the Keep and Peek windows are shown in the following figure.

Keep and Peek Windows

Automatic Keep, Keep, and Peek windows display data in the same format: the statement number where the variable is declared, the level number, the data name, the current value, and the data type.

The level number appears only if the variable is declared in the source as a structure with level numbers. Data values are displayed according to scaling and precision attributes. Alphabetic items are displayed as characters, and numeric items are displayed as DECIMAL, PACKED decimal (COMP-3), HALFWORD (COMP), FULLWORD (COMP), INDEX, or FLOAT (COMP-1, COMP-2), depending on the internal representation. Tables are shown by rows and columns, rather than in a linear fashion.

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 vertical 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 and Peek windows 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.

The contents of variables displayed in a window can be changed by using the MOVE command or by typing over them (implicit MOVE).

If the OCCURS field is not associated with an index or subscript, it can also be typed over to display a different table entry. An occurrence modifier can also be appended to increment or decrement through the table entries. Erasing the occurrence indicator (S= or I=) will disassociate that position with its underlying variable. See the KEEP command Usage Notes section in the Command-and-syntax-reference for more information about keeping tables and/or arrays and using the OCCURS field.

Using the KEEP Command

The KEEP command lets you continuously view the contents of program variables in a window opened at the top of the source display. You can enter the KEEP primary command with the name of the variable or you can enter the K line command either in the Procedure Division (where the variable is referenced) or in the Data Division (where the variable is defined). If the data exceeds 30 bytes, the field becomes scrollable, and it is indicated by the MORE-> sign in the statement number area.Tables are formatted by each dimension when the KEEP command is entered at the elementary level. If the OCCURS field is not associated with an index or subscript, it can be typed over to browse through the table by each entry. Also, a relative subscript can be appended to increment or decrement the occurrences. If the data displayed is a character data type, a column template is displayed to show the length. The length of a numeric item, however, is a function of the internal format.The alphabetic items are displayed as characters and the numeric items are displayed as DECIMAL, PACKED decimal (COMP-3), HALFWORD (COMP), FULLWORD (COMP), INDEX, or FLOAT (COMP-1, COMP-2), depending on the internal representation. Tables will be shown by row and column, rather than in a linear fashion.

The KEEP command has the following format:

KEEP (K line command)

Keeps the value of a variable.

KEEPE (KE line command)

Keeps the values of the elementary items that are part of a group item.

KEEPH (KH line command)

Keeps the hexadecimal values of a variable.

Use the DELETE command (DELETE KEEP or D line command) to remove the display resulting from the KEEP commands.

Examples for using the KEEP command are given as follows. Note that an AFTER 53 breakpoint was entered in the TRIMAIN program before execution was resumed.

The following figure shows the result of entering the KEEP command for the variables WORK-REC and N-N-C. For this example, the automatic Keep window was moved to the bottom of the display with the SET AUTOKEEP 5 command so that all of the explicitly kept items will show in the Keep window without scrolling.

Result of Entering the KEEP Command for WORK-REC and N-N-C

When a table element is displayed, Code Debug TSO inserts an OCCURS field. Above data shows data name N-N-C in the Keep window. N-N-C has an OCCURS field with a value of 1. The KEEP command for N-N-C did not specify an occurrence, so the default of 1 was used. The Autokeep window displays data name N-CNTR with an OCCURS field showing a value of I=4.

The I=4 indicates that the current N-CNTR element being displayed is associated with an index which currently points to the fourth element. The statement that encountered the after breakpoint contained N-CNTR(TX), which generated this information.

If you want to display the currently referenced data in a table as the subscript or index changes, enter the KEEP command using a data item qualified with the occurrence variable.

For instance, a KEEP on N-CNTR displays the data value in the window defaulting to the first occurrence (See the following figure), whereas a KEEP on N-CNTR(TX) displays the currently referenced data (Result of Entering the KEEP Command on a Table Element N-CNTR(TX)).

Result of Entering the KEEP Command on a Table Element N-CNTR

Result of Entering the KEEP Command on a Table Element N-CNTR(TX)

The value in the OCCURS field (I=3) can be typed over with a numeric index value to display a different table entry. Also, an occurrence modifier can be appended to the disassociated occurrence field in order to browse through the table elements each time Enter is pressed.

As shown in the following figure, add a signed integer (for example, +1, -2) to increment or decrement the index by a specified interval.

Browsing Through the Table Elements

The subscript and index boundaries are automatically checked when you are browsing through the table. The boundary limit can be displayed by entering the SHOW INDEX command. The following figure shows the boundary limits for N-N-C.

Result of the SHOW INDEX Command

Using the PEEK Command

You can enter the PEEK primary command with the name of the variable or you can enter the P line command either in the Procedure Division (where the variable is referenced) or in the Data Division (where the variable is defined).

There are three forms of the PEEK command, each corresponding to a data display format. The three forms are:

PEEK (P line command)

Displays the value of a variable.

PEEKE (PE line command)

Displays the values of the elementary items that are part of a group item.

PEEKH (PH line command)

Displays the hexadecimal values of a variable.

Examples of the commands and the resulting formats are described as follows

Use the DELETE primary command or line commands to remove the display resulting from the PEEK commands.

When the PEEK command is issued, the value of the variable is displayed in character or numeric format. Tables are formatted by each dimension when the PEEK command is entered at the elementary level. If the data displayed is a character data type, a column template is displayed to show the length. The length of a numeric item, however, is a function of the internal format.

The following figure shows the result of entering the PEEK command on WORK-REC in the TRIMAIN program.

Result of Entering PEEK WORK-REC

The following figure shows the result of entering the PEEK command on N-N-C-TABLE in the TRIMAIN program. Note the MORE-> sign in the statement number area and the column template.

Result of Entering PEEK N-N-C-TABLE (Shows MORE>Sign and Column Template)

The following figure shows the result of entering the PEEK command on N-N-C in the TRIMAIN program. Note the appearance of the OCCURS field. Because the OCCURS field is disassociated, it can be increased or decreased by simply overtyping the value.

Result of Entering PEEK N-N-C (Shows OCCURS Field and Column Template)

The following figure shows the result of entering the PEEK command on CHECK-SUM in a program that contains counters and sums. Note that the numeric value is shown in PACKED decimal format.

Result of Entering PEEK CHECK-SUM (Shows PACKED Decimal Format)

The following figure shows the result of entering the PEEK command on CHAR-PTR in a program that contains halfwords. Note that the numeric value is shown in HALFWORD format.

Result of Entering PEEK CHAR-PTR (Shows HALFWORD Format)

When the PEEKE command is entered for a group level data name containing elementary data items, the values for each elementary item are displayed, as shown in the following figure, where PEEKE was entered on WORK-REC in the TRIMAIN program.

Result of Entering PEEKE Command on the Group Level Data Item WORK-REC

Description:(Shows DECIMAL Format)

The PEEKH command displays the value of the variable in the hexadecimal format. The following figure shows the result of entering the PEEKH command on the 05 data item SIDE-A for the 01 data item WORK-REC in the TRIMAIN program.

Result of Entering PEEKH Command on the Group Data Item SIDE-A

Description:(Shows HEXADECIMAL Format)

The Session Log Entries for PEEK, KEEP, and Automatic KEEP

Every time a PEEK or KEEP command is entered, or an Automatic Keep displays data in the Keep window, the command and the value of the data name are entered in the session log. The format of the session log entry for both the PEEK and KEEP commands is similar.

To reduce the size of the session log, you can turn off the session log entries of the KEEP and PEEK commands and Automatic Keeps by using the SET LOG KEEP OFF, SET LOG PEEK OFF, and SET LOG AUTOKEEP OFF commands.

Since a displayed field is not scrollable in the session log, large alphanumeric items wrap around to the next line. The number of characters of data per line for an alphanumeric display is determined by the value specified on the SET LOGSIZE command. The record length for the session log file can be set to either 80 or 133. If the LOGSIZE is 80, an alphanumeric display wraps around after 30 characters per line. If the LOGSIZE is 133, the display wraps around after 80 characters per line.

The following figure shows a session log entry for the PEEK command entered for a table. The LOGSIZE is set to 80. In this example, the values in the displayed table wrap around every 30 bytes until the entire table of 100 bytes is displayed.

The Session Log Entry Following Execution of a PEEK Command

Unless SET HEXMODE is specified as ON, the session log entry of a displayed field containing nonrepresentable characters includes the symbol used to represent them—either periods or the character designated by the SET NONDISP command.

When the SET HEXMODE command is on, nonrepresentable characters are displayed in hexadecimal format in the session log. SET HEXMODE ON ensures that sufficient information is provided for a variable containing unprintable characters. All invalid numeric data (e.g., uninitialized packed data) is represented by question marks (?).

When an after, before, onetime, trace, when, or GO 1 breakpoint is encountered and the value of one or more of the kept variables changes, all kept variables are entered in the session log. The variables whose values have changed are listed first, followed by the data names that have not changed. If none of the values of the kept variables change, a session log entry is not made.

Using the MOVE Command

You can change the contents of program variables at any time using the MOVE command. MOVE lets you move either a data name or a literal into another data name.

There are three ways to enter the MOVE command:

1. By typing over a displayed or kept field with a new value, causing an implicit move.
2. Directly as a primary command.
3. In conjunction with the INSERT command.

The session log entry for all three MOVE command formats is the same.

The following figures show examples of entering the MOVE command in different ways to produce the same result. The examples will use the following figure in which the variable WORK-REC is displayed.

Displaying Variable WORK-REC Prior to Typing Over Value

Example 1 — Typing Over Value in Variable Field to Cause an Implicit Move:

In the following figure, the displayed value (345) for the variable WORK-REC is typed over with the new value (999), causing an implicit move.

Typing Over Value for Variable WORK-REC

Example 2 — Entering MOVE as a Primary Command:

If you enter MOVE '345’ TO WORK-REC in the primary command line, the result is an explicit move. As shown in the following figure, the literal value (345) is moved to the data field for WORK-REC and the value of WORK-REC is changed from 999 to 345.

An Example of MOVE Entered as a Primary Command

Example 3 — Using the MOVE Command in Conjunction With the INSERT Command:

In the following figure, the I (Insert) line command was entered on line 49 to open up a line on which to insert the MOVE command. A before breakpoint is also being entered on line 50, following the inserted MOVE command.

Inserting MOVE Command

When you press Enter, a before breakpoint is indicated for line 50, as shown in the following figure.

Before Breakpoint Set on Line 50

Then, when you press PF12 (GO), execution is paused following the inserted MOVE command as shown in the following figure.

Source Display After GO is Entered

Enter KEEP for WORK-REC. The value indicated on the inserted MOVE command is displayed in the Keep window as shown in the following figure.

Result of an Inserted MOVE Command

Displaying and Modifying Memory and Registers

Storage areas and general-purpose registers can be accessed if you wish to debug at the hexadecimal level. The MEMORY command lets you view and modify the storage area starting from a specified location. A full screen memory display is shown in the dump format, and any unprotected areas can be typed over to alter the storage content. The GPREGS command lets you view and modify the registers. A register window is displayed at the bottom of the screen, and you can type over the hexadecimal values to modify the registers. The TOGGLE command permits you to switch back and forth between the storage screen (generated from the MEMORY command) and the listing screen (general-purpose registers opened by using the GPREGS command).

Using the MEMORY Command

The MEMORY command entered without any arguments displays the storage area, starting from the beginning of the currently displayed program. For example, entering the following command from the primary command line of the TRIMAIN program displays the Memory Display screen shown in following figure:

   MEMORY

The fourth line on the Memory Display screen contains the base address and a column template that starts with zero and continues to hexadecimal F. The offsets below the base address list the displacement from the start of the storage area.

Press PF3 (END) to return to the Source display screen.

Result of Entering the MEMORY Command

The MEMORY command can be entered with indirect register addressing to specify a location. For example, the following command displays memory starting from the location pointed to by the 24-bit mode address in register 13, as seen in the following figure:

Result of Entering MEMORY R13%

Also, you can use arithmetic expressions such as the following to access storage, as shown in the following figure.

MEMORY R9%+4

Result of Entering MEMORY R9%+4

Using the GPREGS Command

The GPREGS command opens a window and displays the 16 general-purpose registers at the bottom of the screen. The following figure shows the result of entering the GPREGS command for the TRIMAIN program. The displayed hexadecimal values can be typed over to change the register contents.

Result of Entering the GPREGS Command

The register window can be removed from display by entering the following command:

Using the TOGGLE Command

The TOGGLE command lets you switch from one panel display to another. For COBOL, you may move back and forth between the Listing screen and the Storage screen. It may be beneficial for you to define a specific PF KEY to efficiently utilize the toggle functionality.