Each version of the COBOL compiler provides enhancements that you can use to develop COBOL programs. These enhancements can create different levels of debugging capabilities. The topics below describe how to use these enhancements when you debug your COBOL programs.
To test COBOL programs, you can write debugging commands that resemble COBOL statements. Debug Tool provides an interpretive subset of COBOL statements that closely resembles or duplicates the syntax and action of the appropriate COBOL statements. You can therefore work with familiar commands and insert into your source code program patches that you developed during your debug session.
The table below shows the interpretive subset of COBOL statements recognized by Debug Tool.
| Command | Description |
|---|---|
| CALL | Subroutine call |
| COMPUTE | Computational assignment (including expressions) |
| Declarations | Declaration of session variables |
| EVALUATE | Multiway switch |
| IF | Conditional execution |
| MOVE | Noncomputational assignment |
| PERFORM | Iterative looping |
| SET | INDEX and POINTER assignment |
This subset of commands is valid only when the current programming language is COBOL.
When you are entering commands directly at your terminal or workstation, the format is free-form, because you can begin your commands in column 1 and continue long commands using the appropriate method. You can continue on the next line during your Debug Tool session by using an SBCS hyphen (-) as a continuation character.
However, when you use a file as the source of command input, the format for your commands is similar to the source format for the COBOL compiler. The first six positions are ignored, and an SBCS hyphen in column 7 indicates continuation from the previous line. You must start the command text in column 8 or later, and end it in column 72.
The continuation line (with a hyphen in column 7) optionally has one or more blanks following the hyphen, followed by the continuing characters. In the case of the continuation of a literal string, an additional quotation mark is required. When the token being continued is not a literal string, blanks following the last nonblank character on the previous line are ignored, as are blanks following the hyphen.
When Debug Tool copies commands to the log file, they are formatted according to the rules above so that you can use the log file during subsequent Debug Tool sessions.
Continuation is not allowed within a DBCS name or literal string. This restriction applies to both interactive and commands file input.
Refer to the following topics for more information related to the material discussed in this topic.
While Debug Tool allows you to use many commands that are either similar or equivalent to COBOL commands, Debug Tool does not necessarily interpret these commands according to the compiler options you chose when compiling your program. This is due to the fact that, in the Debug Tool environment, the following settings are in effect:
In addition to the subset of COBOL commands you can use while in Debug Tool, there are reserved keywords used and recognized by COBOL that cannot be abbreviated, used as a variable name, or used as any other type of identifier.
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool can process all variable types valid in the COBOL language.
In addition to being allowed to assign values to variables and display the values of variables during your session, you can declare session variables to suit your testing needs.
Example: assigning values to COBOL variables
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool obtains information about a program variable by name, using information that is contained in the symbol table built by the compiler. You make the symbol table available to Debug Tool by compiling with the TEST compiler option.
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool provides three COBOL-like commands to use when assigning values to variables: COMPUTE, MOVE, and SET. Debug Tool assigns values according to COBOL rules. See Debug Tool Reference and Messages for tables that describe the allowable values for the source and receiver of the COMPUTE, MOVE, and SET commands.
The examples for the COMPUTE, MOVE, and SET commands use the declarations defined in the following COBOL program segment.
01 GRP.
02 ITM-1 OCCURS 3 TIMES INDEXED BY INX1.
03 ITM-2 PIC 9(3) OCCURS 3 TIMES INDEXED BY INX2.
01 B.
02 A PIC 9(10).
01 D.
02 C PIC 9(10).
01 F.
02 E PIC 9(10) OCCURS 5 TIMES.
77 AA PIC X(5) VALUE 'ABCDE'.
77 BB PIC X(5).
88 BB-GOOD-VALUE VALUE 'BBBBB'.
77 XX PIC 9(9) COMP.
77 ONE PIC 99 VALUE 1.
77 TWO PIC 99 VALUE 2.
77 PTR POINTER.
Assign the value of TRUE to BB-GOOD-VALUE. Only the TRUE value is valid for level-88 receivers. For example:
SET BB-GOOD-VALUE TO TRUE;
Assign to variable xx the result of the expression (a + e(1))/c * 2.
COMPUTE xx =(a + e(1))/c * 2;
You can also use table elements in such assignments as shown in the following example:
COMPUTE itm-2(1,2)=(a + 1)/e(2);
The value assigned to a variable is always assigned to the storage for that variable. In an optimized program, a variable might be temporarily assigned to a register, and a new value assigned to that variable might not alter the value used by the program.
Assign to the program variable c , found in structure d , the value of the program variable a , found in structure b:
MOVE a OF b TO c OF d;
Note the qualification used in this example.
Assign the value of 123 to the first table element of itm-2:
MOVE 123 TO itm-2(1,1);
You can also use reference modification to assign values to variables as shown in the following two examples:
MOVE aa(2:3)TO bb; MOVE aa TO bb(1:4);
Assign the value 3 to inx1, the index to itm-1:
SET inx1 TO 3;
Assign the value of inx1 to inx2:
SET inx2 TO inx1;
Assign the value of an invalid address (nonnumeric 0) to ptr:
SET ptr TO NULL;
Assign the address of XX to ptr:
SET ptr TO ADDRESS OF XX;
Assigns the hexadecimal value of X'20000' to the pointer ptr:
SET ptr TO H'20000';
To display the values of variables, issue the LIST command. The LIST command causes Debug Tool to log and display the current values (and names, if requested) of variables. For example, if you want to display the variables aa, bb, one, and their respective values at statement 52 of your program, issue the following command:
AT 52 LIST TITLED (aa, bb, one); GO;
Debug Tool sets a breakpoint at statement 52 (AT), begins execution of the program (GO), stops at statement 52, and displays the variable names (TITLED) and their values.
Put commas between the variables when listing more than one. If you do not want to display the variable names when issuing the LIST command, issue LIST UNTITLED instead of LIST TITLED.
The value displayed for a variable is always the value that was saved in storage for that variable. In an optimized program, a variable can be temporarily assigned to a register, and the value shown for that variable might differ from the value being used by the program.
If you use the LIST command to display a National variable, Debug Tool converts the Unicode data to EBCDIC before displaying it. If the conversion results in characters that cannot be displayed, enter the LIST %HEX() command to display the unconverted Unicode data in hexadecimal format.
Programs you run with Debug Tool can contain variables and character strings written using the double-byte character set (DBCS). Debug Tool also allows you to issue commands containing DBCS variables and strings. For example, you can display the value of a DBCS variable (LIST), assign it a new value, monitor it in the Monitor window (MONITOR), or search for it in a window (FIND).
To use DBCS with Debug Tool, enter:
SET DBCS ON;
If you are debugging in full-screen mode and your terminal is not DBCS capable, the SET DBCS ON is not available.
The DBCS default for COBOL is OFF.
The DBCS syntax and continuation rules you must follow to use DBCS variables in Debug Tool commands are the same as those for the COBOL language.
For COBOL you must type a DBCS literal, such as G, in front of a DBCS value in a Monitor or Data pop-up window if you want to update the value.
Refer to the following topics for more information related to the material discussed in this topic.
The table below shows the possible values for the Debug Tool variable %PATHCODE when the current programming language is COBOL.
| -1 | Debug Tool is not in control as the result of a path or attention situation. |
| 0 | Attention function (not ATTENTION condition). |
| 1 | A block has been entered. |
| 2 | A block is about to be exited. |
| 3 | Control has reached a label coded in the program (a paragraph name or section name). |
| 4 | Control is being transferred as a result of a CALL or INVOKE. The invoked routine’s parameters, if any, have been prepared. |
| 5 | Control is returning from a CALL or INVOKE. If GPR 15 contains a return code, it has already been stored. |
| 6 | Some logic contained by an inline PERFORM is about to be executed. (Out-of-line PERFORM ranges must start with a paragraph or section name, and are identified by %PATHCODE = 3.) |
| 7 | The logic following an IF...THEN is about to be executed. |
| 8 | The logic following an ELSE is about to be executed. |
| 9 | The logic following a WHEN within an EVALUATE is about to be executed. |
| 10 | The logic following a WHEN OTHER within an EVALUATE is about to be executed. |
| 11 | The logic following a WHEN within a SEARCH is about to be executed. |
| 12 | The logic following an AT END within a SEARCH is about to be executed. |
| 13 | The logic following the end of one
of the following structures is about to be executed:
|
| 14 | Control is about to return from a declarative procedure such as USE AFTER ERROR. (Declarative procedures must start with section names, and are identified by %PATHCODE = 3.) |
| 15 | The logic associated with one of the
following phrases is about to be run:
|
| 16 | The logic following the end of a statement
containing one of the following phrases is about to be run:
|
Refer to the following topics for more information related to the material discussed in this topic.
You might want to declare session variables during your Debug Tool session. The relevant variable assignment commands are similar to their counterparts in the COBOL language. The rules used for forming variable names in COBOL also apply to the declaration of session variables during a Debug Tool session.
The following declarations are for a string variable, a decimal variable, a pointer variable, and a floating-point variable. To declare a string named description, enter:
77 description PIC X(25)
To declare a variable named numbers, enter:
77 numbers PIC 9(4) COMP
To declare a pointer variable named pinkie, enter:
77 pinkie POINTER
To declare a floating-point variable named shortfp, enter:
77 shortfp COMP-1
Session variables remain in effect for the entire debug session.
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool interprets COBOL expressions according to COBOL rules. Some restrictions do apply. For example, the following restrictions apply when arithmetic expressions are specified:
When arithmetic expressions are used in relation conditions, both comparand attributes are considered. Relation conditions follow the IF rules rather than the EVALUATE rules.
Only simple relation conditions are supported. Sign conditions, class conditions, condition-name conditions, switch-status conditions, complex conditions, and abbreviated conditions are not supported. When either of the comparands in a relation condition is stated in the form of an arithmetic expression (using operators such as plus and minus), the restriction concerning floating-point operands applies to both comparands. See Debug Tool Reference and Messages for a table that describes the allowable comparisons for the IF command. See the Enterprise COBOL for z/OS Programming Guide for a description of the COBOL rules of comparison.
Windowed date fields are not supported in relation conditions.
Refer to the following topics for more information related to the material discussed in this topic.
Use the LIST command to display the results of your expressions. For example, to evaluate the expression and displays the result in the Log window, enter:
LIST a + (a - 10) + one;
You can also use structure elements in expressions. If e is an array, the following two examples are valid:
LIST a + e(1) / c * two;
LIST xx / e(two + 3);
Conditions for expression evaluation are the same ones that exist for program statements.
Refer to the following topics for more information related to the material discussed in this topic.
During your Debug Tool session you can use expressions that use string constants as one operand, as well as expressions that include variable names or number constants as single operands. All COBOL string constant types discussed in the Enterprise COBOL for z/OS Language Reference are valid in Debug Tool, with the following restrictions:
Additionally, Debug Tool allows the use of a hexadecimal constant that represents an address. This H-constant is a fullword value that can be specified in hex using numeric-hex-literal format (hexadecimal characters only, delimited by either quotation marks (") or apostrophes (') and preceded by H). The value is right-justified and padded on the left with zeros. The following example:
LIST STORAGE (H'20cd0');
displays the contents at a given address in hexadecimal format. You can use this type of constant with the SET command. The following example:
SET ptr TO H'124bf';
assigns a hexadecimal value of 124bf to the variable ptr.
Debug Tool provides certain functions you can use to find out more information about program variables and storage.
You can use the %HEX function with the LIST command to display the hexadecimal value of an operand. For example, to display the external representation of the packed decimal pvar3, defined as PIC 9(9), from 1234 as its hexadecimal (or internal) equivalent, enter:
LIST %HEX (pvar3);
The Log window displays the hexadecimal string X'000001234'.
This Debug Tool function allows you to reference storage by address and length. By using the %STORAGE function as the reference when setting a CHANGE breakpoint, you can watch specific areas of storage for changes. For example, to monitor eight bytes of storage at the hex address 22222 for changes, enter:
AT CHANGE %STORAGE (H'00022222', 8) LIST 'Storage has changed at Hex address 22222'
Qualification is a method of specifying an object through the use of qualifiers, and changing the point of view from one block to another so you can manipulate data not known to the currently executing block. For example, the assignment MOVE 5 TO x; does not appear to be difficult for Debug Tool to process. However, you might have more than one variable named x. You must tell Debug Tool which variable x to assign the value of five.
You can use qualification to specify to what compile unit or block a particular variable belongs. When Debug Tool is invoked, there is a default qualification established for the currently executing block; it is implicitly qualified. Thus, you must explicitly qualify your references to all statement numbers and variable names in any other block. It is necessary to do this when you are testing a compile unit that calls one or more blocks or compile units. You might need to specify what block contains a particular statement number or variable name when issuing commands.
Qualifiers are combinations of load modules, compile units, blocks, section names, or paragraph names punctuated by a combination of greater-than signs (>), colons, and the COBOL data qualification notation, OF or IN, that precede referenced statement numbers or variable names.
When qualifying objects on a block level, use only the COBOL form of data qualification. If data names are unique, or defined as GLOBAL, they do not need to be qualified to the block level.
The following is a fully qualified object:
load_name::>cu_name:>block_name:>object;
If required, load_name is the name of the load module. It is required only when the program consists of multiple load modules and you want to change the qualification to other than the current load module. load_name can also be the Debug Tool variable %LOAD.
If required, cu_name is the name of the compile unit. The cu_name must be the fully qualified compile unit name. It is required only when you want to change the qualification to other than the currently qualified compile unit. It can be the Debug Tool variable %CU.
If required, block_name is the name of the block. The block_name is required only when you want to change the qualification to other than the currently qualified block. It can be the Debug Tool variable %BLOCK. If block_name is case sensitive, enclose the block name in quotation marks (") or apostrophes ('). If the name is not inside quotation marks or apostrophes, Debug Tool converts the name to upper case.
Below are two similar COBOL programs (blocks).
MAIN
·
·
·
01 VAR1. 02 VAR2. O3 VAR3 PIC XX. 01 VAR4 PIC 99.. ****************MOVE commands entered here****************
SUBPROG
·
·
·
01 VAR1. 02 VAR2. O3 VAR3 PIC XX. 01 VAR4 PIC 99. 01 VAR5 PIC 99. ****************LIST commands entered here****************
You can distinguish between the main and subprog blocks using qualification. If you enter the following MOVE commands when main is the currently executing block:
MOVE 8 TO var4; MOVE 9 TO subprog:>var4; MOVE 'A' TO var3 OF var2 OF var1; MOVE 'B' TO subprog:>var3 OF var2 OF var1;
and the following LIST commands when subprog is the currently executing block:
LIST TITLED var4; LIST TITLED main:>var4; LIST TITLED var3 OF var2 OF var1; LIST TITLED main:>var3 OF var2 OF var1;
each LIST command results in the following output (without the commentary) in your Log window:
VAR4 = 9; /* var4 with no qualification refers to a variable */
/* in the currently executing block (subprog). */
/* Therefore, the LIST command displays the value of 9.*/
MAIN:>VAR4 = 8 /* var4 is qualified to main. */
/* Therefore, the LIST command displays 8, */
/* the value of the variable declared in main. */
VAR3 OF VAR2 OF VAR1 = 'B';
/* In this example, although the data qualification */
/* of var3 is OF var2 OF var1, the */
/* program qualification defaults to the currently */
/* executing block and the LIST command displays */
/* 'B', the value declared in subprog. */
VAR3 OF VAR2 OF VAR1 = 'A'
/* var3 is again qualified to var2 OF var1 */
/* but further qualified to main. */
/* Therefore, the LIST command displays */
/* 'A', the value declared in main. */
The above method of qualifying variables is necessary for commands files.
The point of view is usually the currently executing block. You can also get to inaccessible data by changing the point of view using the SET QUALIFY command. The SET keyword is optional. For example, if the point of view (current execution) is in main and you want to issue several commands using variables declared in subprog, you can change the point of view by issuing the following:
QUALIFY BLOCK subprog;
You can then issue commands using the variables declared in subprog without using qualifiers. Debug Tool does not see the variables declared in procedure main. For example, the following assignment commands are valid with the subprog point of view:
MOVE 10 TO var5;
However, if you want to display the value of a variable in main while the point of view is still in subprog, you must use a qualifier, as shown in the following example:
LIST (main:>var-name);
The above method of changing the point of view is necessary for command files.
The block structure of a COBOL class created with Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 or later, is different from the block structure of a COBOL program. The block structure of a COBOL class has the following differences:
A method belongs to either the FACTORY block or the OBJECT block. A fully qualified block name for a method in the FACTORY paragraph is:
class-name:>FACTORY:>method-name
A fully qualified block name for a method in the OBJECT paragraph is:
class-name:>OBJECT:>method-name
When you are at a breakpoint in a method, the currently qualified block is the method. If you enter the LIST TITLED command with no parameters, Debug Tool lists all of the data items associated with the method. To list all of the data items in a FACTORY or OBJECT, do the following steps:
For example, to list all of the object instance data items for a class called ACCOUNT, enter the following command:
QUALIFY BLOCK ACCOUNT:>OBJECT; LIST TITLED;
There are limitations to debugging VS COBOL II programs compiled with the TEST compiler option and linked with the Language Environment library. Language Environment callable services, including CEETEST, are not available. However, you must use the Language Environment run time.
Debug Tool does not get control of the program at breakpoints that you set by the following commands:
However, if you set the breakpoint with an AT CALL command that calls a non-VS COBOL II program, Debug Tool does get control of the program. Use the AT ENTRY *, AT EXIT *, AT GLOBAL ENTRY, and AT GLOBAL EXIT commands to set breakpoints that Debug Tool can use to get control of the program.
Breakpoints that you set at entry points and exit statements have no statement associated with them. Therefore, they are triggered only at the compile unit level. When they are triggered, the current view of the listing moves to the top and no statement is highlighted. Breakpoints that you set at entry points and exit statements are ignored by the STEP command.
If you are debugging your VS COBOL II program in remote debug mode, use the same TEST run-time options as for any COBOL program.
The VS COBOL II compiler does not place the name of the listing data set in the object (load module). Debug Tool tries to find the listing data set in the following location: userid.CUName.LIST. If the listing is in a PDS, direct Debug Tool to the location of the PDS in one of the following ways:
For additional information about how you can debug VS COBOL II programs, see Using CODE/370 with VS COBOL II and OS PL/I, SC09-1862.