PEEK
COBOL | PL/I | Assembler | C Language |
Description
Use the PEEK command to view the contents of program variables. PEEK scrolls to the data area, displays the data values next to the variable, and inserts a P in column 9 of the source. You can alter the variable content by typing over the displayed value. The PEEK display is temporary and is deleted when execution resumes.
A PEEK is valid on any line with a variable name.
The results of PEEK commands are recorded in the session log unless suppressed by the SET LOG PEEK OFF command.
Input
PEEK Line Command Syntax
P* - Display all variables on a line
Pn - Display the nth variable on a line
PP - Display the variables on a block of lines
PE - Display the elementary items for the variable on a line
PEn - Display the elementary items of the nth variable on a line
E - Display the elementary items for the variable on a line
En - Display the elementary items of the nth variable on a line
EE - Display the elementary items on a block of lines
PH - Display the variable on the line in hexadecimal format
PHn - Display the nth variable on the line in hexadecimal format
H - Display the variable on the line in hexadecimal format
Hn - Display the nth variable on the line in hexadecimal format
HH - Display the variables on a block of lines in hexadecimal format
> - Display the variable on the line as a full character string
C - Display the variable on the line as a full character string
< - Display the character variable on the line as an array
A - Display the character variable on the line as an array
The following are the parameter descriptions for the PEEK command:
data
A data-name, variable, data-label, or register (Rn).
LINKAGE (COBOL)
The linkage section of the active source program.
LOCAL-STORAGE (COBOL)
The local-storage section of the active source program.
WORKING-STORAGE (COBOL)
The working-storage section of the active source program.
CSR
Displays the data area indicated by the cursor position. The CSR keyword is not valid in an unattended batch test. The PEEK CSR command is usually assigned to PF2.
PSW (Assembler)
The program status word.
Usage Notes
ALL Languages |
Usage notes related to tables and/or arrays can be found under Understanding the OCCURS Field, Understanding the Index, Keeping Tables, and Keeping Arrays. These sections are under the KEEP command, but are equally applicable to the PEEK command.
COBOL |
When the PEEK command is entered on a 01 level data item (see Source for PEEK Examples), Code Debug TSO shows the value of the group item unexpanded, as shown in Result of Entering PEEK on a GROUP-ITEM. Use PEEK to exhibit the values of elementary items subordinate to the group item without showing the group item itself, as seen in Example of Entering PEEKE on a GROUP-ITEM. For an elementary item, the result of a PEEK and PEEKE is the same, as seen in Result of Entering PEEK ELEMENT-2 or PEEKE ELEMENT-2.
Source for PEEK Examples000061 01 GROUP-ITEM.
000062 05 ELEMENT-1 PIC X(3).
000063 05 ELEMENT-2 PIC X(17)Result of Entering PEEK on a GROUP-ITEM
----+----1----+----2
000061 P 01 GROUP-ITEM. > 123ABCDEFGHIJKLMNOPQExample of Entering PEEKE on a GROUP-ITEM
000061 01 GROUP-ITEM.
---
000062 P 05 ELEMENT-1 > 123
----+----1----+--
000063 P 05 ELEMENT-2 > ABCDEFGHIJKLMNOPQResult of Entering PEEK ELEMENT-2 or PEEKE ELEMENT-2
----+----1----+--
000063 P 05 ELEMENT-2 > ABCDEFGHIJKLMNOPQA column template is displayed above the nonnumeric data item. The length of the column template corresponds to the variable length defined in the picture clause.
Numeric items are displayed without a column template. The length of a numeric field in bytes is a function of the field’s internal representation. Code Debug TSO converts all numeric items to display format. The usage (BINARY, PACKED, HALFWORD, etc.) is displayed to the right of each numeric field. Numeric Items Displayed After an E Line Command on NUM-REC uses the following source as an example:
Source for E Line Command Example000081 01 NUM-REC.
000082 P 05 UNSIGNED-FLD PIC 9(3)V99.
000083 P 05 BINARY-FLD PIC S9(3) COMP.
000084 P 05 FULLW-FLD PIC S9(8) COMP.
000085 P 05 FLOAT1-FLD COMP-1.
000086 P 05 FLOAT2-FLD COMP-2.
000087 P 05 PACKED-FLD PIC S9(5)V99 COMP-3Numeric Items Displayed After an E Line Command on NUM-REC
000081 01 NUM-REC
000082 P 05 UNSIGNED-FLD > 453.22 DECIMAL
000083 P 05 BINARY-FLD > +10223 HALFWORD
000084 P 05 FULLW-FLD > +00000001 FULLWORD
000085 P 05 FLOAT1-FLD > +5.632E04 FLOAT1
000086 P 05 FLOAT2-FLD > -.29999999999999999E+03 FLOAT2
000087 P 05 PACKED-FLD > +17.88 PACKEDUse the T and DT line commands, respectively, to add and delete a template for any displayed data.
If the variable’s length exceeds the screen width, the field becomes scrollable. Scrollable fields are identifiable by the highlighted MORE-> in the line command area. If the scrollable data to the right is the same as the last visible character on the screen (all spaces or binary zeros, for instance), then MORE-> is replaced by SAME-> in the line command area.
When you scroll the data left or right using the DLEFT (PF22) or DRIGHT (PF23) command, only the scrollable values and their associated column templates actually move. All other fields remain stationary. Once a scrollable field is displayed to its rightmost position (that is, you have reached the end of the field), you can no longer scroll in that direction. See Source Before Horizontal Scrolling of a Displayed Item for a before example and Result After Pressing PF23 Key for Horizontal Scrolling of a Displayed Item for an after example of scrolling a long data element. Notice that only the value field and its column template scroll.
Source Before Horizontal Scrolling of a Displayed Item000022 05 FILLER PIC 9(04).
----+----1----+----2----+----3
MORE-> P 01 N-N-C-TABLE > EQUILATERAL TRIANGLES0000ISOSC
000024 05 N-N-C OCCURS 4 TIMESResult After Pressing PF23 Key for Horizontal Scrolling of a Displayed Item
000022 05 FILLER PIC 9(04).
----+----4----+----5----+----6
MORE-> P 01 N-N-C-TABLE > ELES TRIANGLES 0003 SCALENE TR
000024 05 N-N-C OCCURS 4 TIMESNonrepresentable characters are displayed as periods (.) and invalid numeric values are displayed as question marks (?). Code Debug TSO displays lowercase data as is. If your terminal cannot display lowercase characters, you can have Code Debug TSO display lowercase characters as nonrepresentable characters by entering the following command:
SET LOWCASE CONVERT
To restore the default of displaying lowercase characters as is, enter the following command:
SET LOWCASE ASISYou can display variables in hexadecimal format by using the PEEKH command or H line command. See the following figure for an example of entering the H line command on the source line containing ID-NUMBER.
Result of Entering an H Line Command on ID-NUMBER----+----1-
000085 P 01 ID-NUMBER > 345-23-8976
> FFF6FF6FFFF
> 34502308976- You can type over either the hexadecimal digits or the displayed value. If you type over both fields, the hexadecimal digits take precedence.
You cannot type over the hexadecimal digits unless the variable value line and the two lines for the hexadecimal value are shown on the screen. If the display occurs at the bottom of the screen and vertical truncation occurs (that is, lines are lost at the bottom of the screen), typing over is not permitted. A variable contains invalid data if it is an elementary numeric item and the contents of the variable do not conform to its defined usage.
Code Debug TSO displays a numeric field containing invalid data as question marks (?). A message indicating the invalid data type is displayed to the right of each numeric field as shown in the following figure.
Invalid Numeric Display000029 01 NUM-REC.
000030 P 05 UNSIGNED-FLD > ????? INVALID DECIMAL
000031 P 05 FLOAT1-FLD > ???? INVALID FLOAT1
000032 P 05 FLOAT2-FLD > ???????? INVALID FLOAT2
000033 P 05 PACKED-FLD > ???? INVALID PACKED
000034 B PROCEDURE DIVISION.
000040 MAIN-PARA.- Use the CSR command to direct Code Debug TSO to display the variable indicated by the cursor position. If the cursor is not on a line containing a valid variable name, an error message is displayed. This command is most effective when the command PEEK CSR is set to a specific PF key. Then, placing the cursor on a variable name in Working-Storage or in the Procedure Division and pressing the PF key displays the variable.
CSR is not valid in an unattended batch test. - A displayed item can be scrolled. It will continue to display its value until execution resumes. The DELETE primary command or D line command can be used to remove a displayed item and redisplay the original source code.
- The Pn, PEn, En, PHn, and Hn line commands are valid only on data lines.
- The nth variable of the P line command is determined as follows: P or P1 displays the first variable on a line, P2 displays the second variable, P3 the third variable, and so forth. P* is used to display all the variables on the line.
Use the PEEK command to view the contents of COBOL tables. Code Debug TSO can display the entire table or any occurrence of a group or elementary item at any level of the table.
An entire table is displayed by specifying the group level variable name as shown in the following figure. The remainder of the table is viewed by scrolling to the right.
Displaying a COBOL Table000133 *
P 0134 01 SIMPLE-TABLE.
000135 05 S-ELEMENT OCCURS 5 TIMES
000136 INDEXED BY SX.
000137 10 S-NAME PIC X(10).
000138 10 S-CNTR PIC 9(04).
000139 *
P 0140 01 COMPOUND-TABLE.
000141 05 C-ROW OCCURS 3 TIMES INDEXED BY ROW-INDEX.
000142 10 C-COL OCCURS 2 TIMES INDEXED BY COL-INDEX.
000143 15 C-L1 PIC X(2).
000144 15 C-L2 PIC S9(3) USAGE COMP.
000145You can display only one occurrence of any subordinate group or elementary item at a time. However, a second occurrence of the same item can be displayed simultaneously in the Keep window.
If a display request is entered for an indexed or subscripted data name and the specific occurrence number is not specified, then the first occurrence of that item is displayed. When any table sub-element is displayed, Code Debug TSO inserts an occurrence field above the element as shown in the following figure.
Displaying a COBOL Table Occurrence000023 01 N-N-C-TABLE REDEFINES NAME-N-CNTR-TABLE.
000024 05 N-N-C OCCURS 4 TIMES
000025 INDEXED BY TX.
3 OCCURS
----+----1----+----2-
000026 P 10 N-NAME > EQUILATERAL TRIANGLES
000027 P 10 N-CNTR > 0007 DECIMAL
000028 01 OUT-OF-RECS PIC X.
000029 01 TRIANGLE-TYPE PIC 9.
000030 01 WORK-REC.
000031 05 SIDE-A PIC 9(01)- Since a PEEK command physically scrolls your source to the Data Division section, use LOCATE * to return to your current point of execution.
Assembler |
- The PEEK primary command lets you display data areas in EBCDIC format if defined as character (C); in decimal format if defined as decimal (P,Z,F,H); and in hexadecimal format if defined as hexadecimal (X), binary (B), or address (Y,A,S,V,Q).
- The PEEK command is not valid on an instruction line.
- The P line commands cannot be used on lines of inserted code in Assembler.
- The PEEKH primary command lets you display data areas in hexadecimal format.
- Data items for which addressability has not been established are not displayed.
- Data areas defined as graphic (G) are supported by the PEEK command.
- A column template is displayed above the data areas that are defined as character (C). The column template corresponds to the length of the data area. Data areas defined as hexadecimal (X), address (A,Y,S,V,Q), binary (B), fixed-point (H,F), floating-point (E,D,L), or decimal (P,Z) are displayed without a column template. The length of a numeric field is a function of its internal representation.
- The display field becomes scrollable if the data area length exceeds 30 bytes. The MORE-> in the line command area identifies the scrollable fields. You can use PF22 and PF23 to scroll left and right, respectively. MORE-> is replaced by SAME-> when the scrollable data to the right is the same as the last visible data on the screen.
- A data area is said to contain invalid data if its contents do not conform to its defined usage and it displays nonrepresentable characters. The default character for invalid numeric values is the question mark (?).
- Code Debug TSO cannot determine whether the terminal or printer you are using can display or print lowercase characters. For that reason, Code Debug TSO displays lowercase characters as nonrepresentable characters (.) or (?) for invalid numeric values. If your terminal or printer can display lowercase characters, enter:
SET LOWCASE ASIS
which displays lowercase as is, without converting to nonrepresentable characters.
If CAPS is set to ON (default), Code Debug TSO converts lowercase characters to uppercase when you press Enter. SET CAPS OFF should be used in conjunction with SET LOWCASE ASIS. - You can reference any data area that is not in protected storage and alter its contents by typing over the displayed data (an implicit move) or by using the MOVE command.
- You cannot type over the hexadecimal digits unless all four lines (column template, EBCDIC display, and hexadecimal display) are shown on the screen. Typing over is not permitted if the display occurs at the bottom of the screen and vertical truncation occurs.
- If a character field defined with duplication factor is displayed, the first occurrence field is shown. Each occurrence field can be referenced individually by specifying the entry.
- Relative addressing (+/- calculation factor) is not supported with the PEEK command. Use the MEMORY command (displays memory) instead. See MEMORY for a description of the MEMORY command.
- If a line contains more than one data area, the value of the first data area on the line is displayed when a P line command is entered. The Pn line command displays the nth data area. Use the P* line command to display all the data areas on the line. The P line commands cannot be used on lines of inserted code in Assembler.
- Block PP line commands are recorded in the session log as individual PEEK commands on each data area.
- The DELETE command is used to turn off a PEEK command.
PL/I |
When the PEEK command is entered on a 01 level data item, Code Debug TSO shows the value of the group item unexpanded, as shown in the following figure. Use PEEKE to show the values of elementary items subordinate to the group item without showing the group item itself, as seen in Result of Entering PEEKE on NAMES_N_CNTRS. For an elementary item, the result of a PEEK and PEEKE is the same.
Result of Entering PEEK on NAMES_N_CNTRS----+----1----+----2----+----3
MORE-> P DCL 1 NAMES_N_CNTRS > EQUILATERAL TRIANGLES...ISOSCE
------ 2 N_N_C(4),
------ 3 N_NAME CHAR (21) ,
------ 3 N_CNTR FIXED(4);Result of Entering PEEKE on NAMES_N_CNTRS
000007 DCL 1 NAMES_N_CNTRS,
------ 2 N_N_C(4),
1 OCCURS
----+----1----+----2-
------ P 3 N_NAME CHAR ( > EQUILATERAL TRIANGLES
------ P 3 N_CNTR > +0002 PACKEDA column template is displayed above the nonnumeric data item. The length of the column template corresponds to the variable length defined. The SET TEMPLATE OFF command prevents the display of this automatic template, except for variables with the VARYING attribute.
Numeric items are displayed without a column template. The length of a numeric field in bytes is a function of the field’s internal representation. Code Debug TSO converts all numeric items to display format. The usage (PACKED, BINARY, HALFWORD, POINTER, etc.) is displayed to the right of each numeric field.
Numeric Items Displayed After an E Line Command on NUM_REC000081 DCL 1 NUM_REC,
------ P 5 UNSIGNED_FLD, > 453.22 ZONED
------ P 5 BINARY_FLD, > +10223 HALFWORD
------ P 5 FULLW_FLD, > +00000001 FULLWORD
------ P 5 FLOAT1_FLD, > +5.632E04 FLOAT1
------ P 5 FLOAT2_FLD, > -.29999999999999999E+03 FLOAT2
------ P 5 PACKED_FLD; > +17.88 PACKEDUse the T and DT line commands, respectively, to add and delete a template for any displayed data.
If the variable’s length exceeds the screen width, the field becomes scrollable. Scrollable fields are identifiable by MORE-> in the line command area. If the scrollable data to the right is the same as the last visible character on the screen (all spaces or binary zeros, for instance), then MORE-> is replaced by SAME-> in the line command area.
When you scroll the data left or right using the DLEFT (PF22) or DRIGHT (PF23) command, only the scrollable values and their associated column templates actually move. All other fields remain stationary. Once a scrollable field is displayed to its rightmost position (that is, you have reached the end of the field), you can no longer scroll in that direction. See Source Before Horizontal Scrolling of a Displayed Item for a before example and Result After Pressing PF23 Key for Horizontal Scrolling of a Displayed Item for an after example of scrolling a long data element. Notice that only the value field and its column template scroll.
Source Before Horizontal Scrolling of a Displayed Item000006 DCL TBL(04) STATIC CHAR(21)
------ INIT('EQUILATERAL TRIANGLES','ISOSCELES TRIANGLES',
------ 'SCALENE TRIANGLES', 'INVALID TRIANGLES');
------
----+----1----+----2----+----3
MORE-> P DCL 1 NAMES_N_CNTRS, > EQUILATERAL TRIANGLES...ISOSCE
------ 2 N_N_C(4),
------ 3 N_NAME CHAR (21) ,
------ 3 N_CNTR FIXED(4)Result After Pressing PF23 Key for Horizontal Scrolling of a Displayed Item
000006 DCL TBL(04) STATIC CHAR(21)
------ INIT('EQUILATERAL TRIANGLES','ISOSCELES TRIANGLES',
------ 'SCALENE TRIANGLES', 'INVALID TRIANGLES');
------
----+----4----+----5----+----6
MORE-> P DCL 1 NAMES_N_CNTRS, > LES TRIANGLES ...SCALENE TRIA
------ 2 N_N_C(4),
------ 3 N_NAME CHAR (21) ,
------ 3 N_CNTR FIXED(4);Nonrepresentable characters are displayed as periods (.) and invalid numeric values are displayed as question marks (?). Code Debug TSO displays lowercase data as is. If your terminal cannot display lowercase characters, you can have Code Debug TSO display lowercase characters as nonrepresentable characters by entering the command:
SET LOWCASE CONVERT
To restore the default of displaying lowercase characters as is, enter the command:
SET LOWCASE ASISUse the PEEKH primary command or the H line command to display variables in hexadecimal format. See the following figure for an example of entering the H line command on the source line containing IN_REC.
Result of Entering an H Line Command on IN_REC000002 DCL INFILE INPUT RECORD;
000003 DCL MORE_RECORDS BIT (1);
------
----+----1----+----2----+----3
SAME-> P DCL 1 IN_REC, > 789
FFF444444444444444444444444444
789000000000000000000000000000
------ 2 SIDES,
------ 3 SIDE_A PIC’9’,
------ 3 SIDE_B PIC’9’,
------ 3 SIDE_C PIC’9’,
------ 2 UNUSED CHAR (77);- You can type over either the hexadecimal digits or the displayed value. If you type over both fields, the hexadecimal digits take precedence.
You cannot type over the hexadecimal digits unless the variable value line and the two lines for the hexadecimal value are shown on the screen. If the display occurs at the bottom of the screen and vertical truncation occurs (that is, lines are lost at the bottom of the screen), typing over is not permitted. - You cannot request a hexadecimal display on a bit string data type. Use the MEMORY command to see the hexadecimal values.
A variable contains invalid data if it is an elementary numeric item and the contents of the variable do not conform to its defined usage.
Code Debug TSO displays a numeric field containing invalid data as question marks (?). A message indicating the invalid data type is displayed to the right of each numeric field as shown in the following figure.
Invalid Numeric Display000004 DCL 1 IN_REC,
------ 2 SIDES,
------ P 3 SIDE_A PIC'9', > ?? INVALID DECIMAL
------ P 3 SIDE_B PIC'9', > ?? INVALID DECIMAL
------ P 3 SIDE_C PIC'9', > ?? INVALID DECIMAL
----+----1----+----2----+----3
SAME-> P 2 UNUSED CHAR (7 > ..............................
------
000005 DCL 1 WORK_REC ,
------ P 2 (SIDE_A, SIDE_B, SID > ?? INVALID PACKED
'''''' P 02 SIDE_B > ?? INVALID PACKED
'''''' P 02 SIDE_C > ?? INVALID PACKED
------- Use the CSR command to direct Code Debug TSO to display the variable indicated by the cursor position. If the cursor is not on a line containing a valid variable name, an error message is displayed. This command is most effective when the command PEEK CSR is set to a specific PF key. Then, placing the cursor on a valid variable name and pressing the PF key displays the variable.
- A displayed item can be scrolled. It will continue to display its value until execution resumes. The DELETE primary command or D line command can be used to remove a displayed item.
- The Pn, PEn, En, PHn, and Hn line commands are valid only on data lines.
The nth variable of the P line command is determined as follows: P or P1 displays the first variable on a line, P2 displays the second variable, P3 the third variable, and so forth. P* is used to display all the variables on the line.
- Use the PEEK command to view the contents of arrays. Code Debug TSO can display the entire array, or any occurrence of an element of the array, at any dimension.
You can display only one element of any subordinate group or elementary item at a time. However, any portion of the array can be scrolled through by altering the occurrence values once they have been disassociated from the underlying variables.
If a display request is entered to keep an indexed or subscripted data name, and the specific element number is not specified, then the first element of that group is kept.
When any array element is displayed, Code Debug TSO inserts an occurrence field above the element as shown in the following figure.
Displaying an Array Occurrence000005 DCL 1 WORK_REC ,
------ 2 (SIDE_A, SIDE_B, SIDE_C) FIXED DEC(1);
------
2 OCCURS
----+----1----+----2-
000006 P DCL TBL(04) STATIC CHAR(21) > ISOSCELES TRIANGLES
------ INIT('EQUILATERAL TRIANGLES','ISOSCELES TRIANGLES',
------ 'SCALENE TRIANGLES','INVALID TRIANGLES');
------
000007 DCL 1 NAMES_N_CNTRS,
------ 2 N_N_C(4),
2 OCCURS
----+----1----+----2-
------ P 3 N_NAME CHAR ( > ISOSCELES TRIANGLES
------ P 3 N_CNTR FIXED( > +0001 PACKED- If the variable is not the first one declared on the line, PEEK scrolls to the source where the variable is declared and inserts a line to show the data value.
- PEEK set at a variable that is implicitly declared converts the PEEK to KEEP.
Examples
Assembler |
- To display a packed data area name PACKED in a decimal format, enter:
PEEK PACKED To display a fullword data area named FULLW in a hexadecimal format, enter an H line command on the FULLW line area. See the following figure for an example of displaying data areas.
Displaying Data Areas************************************************************
0810D2 P BIN DC B'000 0004B6 > 10
----+----1----+-
0810D3 P CHAR DC C'CHARACTER STRING' > CHARACTER STRING
0810E3 P HEX DC X'FF0 0003C7 > FF00FF
0810E7 P ZONED DC Z'12345' > +12345 ZONED
0810EC P PACKED DC P'12345' > +12345 PACKED
0810F0 P FULLW DC F'12345' > 12345 FULLWORD
0810F4 P HALFW DC H'12345' > 12345 HALFWORD
0810F8 P FLOATE DC E'1.2345 > +1.2344999E+00 FLOAT1
081100 P FLOATD DC D'12345 > +1.2345000000000000E+04 FLOAT2To display the contents of register 2 as shown in the following figure, enter:
PEEK R2
Displaying Register Contents--------------------------- CODE DEBUG TSO - SOURCE ----------------------------
COMMAND ===> SCROLL ===> CSR
R2 0007E97B
------ ------------------------------------------ Before TRIRPTA:96/AMODE 24 <>
000090 PRINT PUT OUTDCB,PRINTLN PRINT PRINTLN
=====> LA R2,2(,R2) BUMP POINTER TO NEXT TYPE
000097 LA R3,33(,R3) BUMP POINTER TO NEXT TITLE
000098 MVC NUMBER,=XL2'F0' ZERO OUT FIELD
000099 GOBACK BCT R5,BLDLINE DO IT AGAIN- To display the Program Status Word (PSW), enter:
PEEK PSW
The current PSW is then displayed in the message area.
CURRENT PSW = 078D0000 0007C88A - If you enter:
PEEK 'THIS IS NOT DATA'
THIS IS NOT DATA is displayed in the message area and written to the session log.