Fujitsu COBOL Debugging Guide: Microsoft Windows Microsoft Windows 95 Microsoft Windows NT

Microsoft Windows Microsoft Windows 95 Microsoft Windows NT
Fujitsu COBOL Debugging Guide
Second Edition: March 1997 The contents of this manual may be revised without prior notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Fujitsu Limited. 1996, 1997 Fujitsu Limited. All Rights Reserved.
Preface
Fujitsu COBOL allows you to create, execute, and debug COBOL programs with Microsoft Windows 3.1, Windows 95, and Windows NT. This manual describes the debugging functions available.
Audience
This manual is for people who develop COBOL programs using Fujitsu COBOL. It assumes users possess basic knowledge of COBOL and are familiar with the appropriate Windows platform.
iii
How this Manual is Organized

This manual consists of the following chapters and appendix:
Chapter Contents
Chapter 1. Introduction to Debugging with Fujitsu COBOL. Chapter 2. Debugging in Windows 95 and Windows NT Chapter 3. Debugging in Windows 3.1 Chapter 4. Debugging Mixed COBOL85 and PowerCOBOL Chapter 5. Debugging Visual Basic calling COBOL Chapter 6. COBOL Trace and Check Functions Appendix A. Debugger Command Lists
An overview of the various debugging functions.. Details of the debugger for the 32 bit Windows environments. Details of the debugger for the 16 bit Windows environments. Details of debugging mixed COBOL85 and PowerCOBOL applications. Details of debugging mixed Visual Basic and COBOL applications. Details of using the TRACE and CHECK compile time, and associated run-time options. Lists of the commands supported in the different environments that can be entered into the command-line windows.
iv
How to Use This Manual

Check the features listed in the introduction and determine which debugging features you wish to use. Select the chapter that details those features. If you are debugging mixed Visual Basic and COBOL applications you may first want to familiarize yourself with the COBOL debugger by reading Chapter 2. Then follow the guidelines in Chapter 4 for debugging the mixed language application.
Conventions Used in this Manual

This manual uses the following typographic conventions.
Example of Convention setup Program-name Description Characters you enter appear in bold. Underlined text indicates a place holder for information you supply. Small capital letters are used for the name of keys and key sequences such as ENTER and CTRL+R. A plus sign (+) indicates a combination of keys. Ellipses indicate the item immediately preceding can be specified repeatedly. Names of pulldown menus and options appear with the initial letter capitalized. Indicates that the enclosed item may be omitted. Indicates that one of the enclosed items delimited by | is to be selected. Commands, statements, clauses, and options you enter or select appear in uppercase. Program section names, and some proper names also appear in uppercase. Defaults are underlined. This font is used for examples of program code.
ENTER
Edit, Literal [def] {ABC|DEF} CHECK WITH PASCAL LINKAGE ALL PARAGRAPH-ID COBOL ALL
PROCEDURE DIVISION : ADD 1 TO POW-FONTSIZE OF LABEL1. IF POW-FONTSIZE OF LABEL1 > 70 THEN MOVE 1 TOW POW-FONTSIZE OF LABEL1. END-IF.
The sheet acts as an application creation form. COBOL85 Users Guide See Debug Program Types in Chapter 2.
Italics are occasionally used for emphasis. References to other publications or sections within publications are in quotation marks.
vi
Fujitsu COBOL supports the following operating systems: Windows Operating System 3.1 Windows 95 Operating System Windows NT Workstation Operating System 3.51 Windows NT Server Network Operating System 3.51 Windows NT Workstation Operating System 4.0 Windows NT Server Network Operating System 4.0
vii
Related Manuals
Other manuals for Fujitsu COBOL and related products:
Manual Title COBOL85 Reference Manual COBOL85 Users Guide Getting Started with Fujitsu COBOL Migration Guide MF to Fujitsu COBOL Contents Detailed explanation of COBOL85 syntax (open system) Detailed information about COBOL Usage Introduction to using Fujitsu COBOL Detailed explanation about migration and migration tools provided in the Fujitsu COBOL product.
The following products are not supported in the Englishlanguage version of this product: SequeLink MeFt/NET MeFt/NET-SV BS*NET RDB/7000 Server for Windows NT RDB II RDB II Esql-COBOL PowerAIM
viii
Trademarks
Microsoft, MS-DOS, Visual Basic, Windows, are registered trademarks and Visual C++, Windows 95, and Windows NT are trademarks of Microsoft Corporation. Other product names are trademarks or registered trademarks of each company. Trademark indications are omitted for some system and product names described in this manual.
ix
Acknowledgment
The language specifications of COBOL are based on the original specifications developed by the work of the Conference on Data Systems Languages (CODASYL). The specifications described in this manual are also derived from the original. The following passages are quoted at the request of CODASYL. COBOL is an industry language and is not the property of any company or group of companies, or of any organization or group of organizations. No warranty, expressed or implied, is made by the COBOL Committee as to the accuracy and functioning of the programming system and language. Moreover, no responsibility is assumed by the committee, in connection therewith. The authors of the following copyrighted material have authorized the use of this material in part in the COBOL specifications. Such authorization extends to the use of the original specifications in other COBOL specifications: FLOW-MATIC (Trademark of Sperry Rand Corporation), Processing for the UNIVAC I and II, Data Automation Systems, copyrighted 1958, 1959, by Sperry Rand Corporation. IBM Commercial Translator, Form No. F28-8013, copyrighted 1959 by International Business Machines Corporation. FACT, DSI 27A5260-2760, copyrighted 1960 by MinneapolisHoneywell.
All Rights Reserved, Copyright, FUJITSU LIMITED 1996-1997. All Rights Reserved, Copyright, Microsoft Corporation, 19831997.
Contents
Chapter 1. Introduction to Debugging with Fujitsu COBOL. ...................................1 Debugging with Fujitsu COBOL...................................................................................2 Features of the Debugger for Windows 95 and NT.....................................................3 Features of the Debugger for Windows 3.x .................................................................5 Features of the COBOL Debugging Functions.............................................................7 Chapter 2. Debugging in Windows 95 and Windows NT..........................................9 Overview of the Debugger ..........................................................................................10 Preparing Programs for Debugging............................................................................11 Starting the Debugger ..................................................................................................14 Overview of the Debugger Windows.........................................................................21 Using the Debugger .....................................................................................................28 Chapter 3. Debugging in Windows 3.1.......................................................................43 Overview of the Debugger ..........................................................................................44 Preparing Programs for Debugging............................................................................46 Starting the Debugger ..................................................................................................49 Overview of the Debugger Windows.........................................................................58 Debugger Functions .....................................................................................................63
xi
Subcommand Functions .............................................................................................. 77 Notes............................................................................................................................. 90 Chapter 4. Debugging Mixed COBOL85 and PowerCOBOL .................................. 93 Overview ...................................................................................................................... 94 Preparing Programs for Mixed COBOL Debugging................................................. 95 Starting Debugging Mixed COBOL Applications..................................................... 97 Tips for Debugging Mixed COBOL Applications..................................................... 98 Chapter 5. Debugging Visual Basic calling COBOL .............................................. 105 Overview .................................................................................................................... 106 Preparing Programs for Debugging with Visual Basic........................................... 107 Starting Debugging with COBOL and Visual Basic................................................ 110 Stopping Debugging with COBOL and Visual Basic.............................................. 120 Dos and Donts in the Dual Debugging Environment........................................... 121 Chapter 6. COBOL Trace and Check Functions...................................................... 123 Outline of the Debugging Function.......................................................................... 124 Using the TRACE Function....................................................................................... 126 Using the CHECK Function...................................................................................... 131 Appendix A. Debugger Command Lists.................................................................. 137 Index .............................................................................................................................. 139
xii
xiii
Chapter 1. Introduction to Debugging with Fujitsu COBOL.

The introduction gives you an overview of the debugging options available with Fujitsu COBOL.
Debugging with Fujitsu COBOL

Fujitsu COBOL provides three debugging aids: COBOL Debugger for Windows 95 and Windows NT (32 bit applications) COBOL Debugger for Windows 3.1 (16 bit applications) COBOL Debug Functions
The debuggers are full feature, interactive debuggers that provide a rich set of functions to help you locate bugs and analyze the behavior of your programs. They work on the executable code, either in EXE or DLL form, so you are seeing the same code execute that will be run when the applications are used in production. Working with the executable code also means that mixed language debugging can be straightforward. Both debuggers come from the same family of Fujitsu products so support many common interface features such as the ability to record and play back sequences of debugging operations and a command-line interface for those who like to drive the keyboard hard! The COBOL debug functions provide tracing of executed statements and checking of subscripts and modifiers going out of range. With these functions you can ascertain the exact points at which abnormal termination occurs and prevent errors of programs corrupting memory outside their allotted range. (Currently the COBOL debug functions are not supported in the Windows 95 product.)
Features of the Debugger for Windows 95 and NT

The debugger for Windows 95 and NT provides the following features: Displays the original program source. Colors code to indicate comments, verbs, data-names and other syntax features. Clearly indicates the current execution point, breakpoint settings, pass count settings and execution route trace point. Gives convenient access to all functions through menus, a toolbar, a pop-up menu, accelerator keys and a commandline window. Records and displays the CALL stack status. Lists all programs loaded in memory and allows you to switch easily between them. Supports storage of different file types in multiple directories or in a single directory. Provides navigation around the program source through Find and Jump to line number functions. Provides different levels of code execution control including stepping line by line, automated line by line execution while you watch, and full speed execution to the next breakpoint. Code can be executed up to the point indicated by the cursor, up to the next program and up to a long list of specific execution conditions such as particular verbs being executed,
particular files being accessed and entry to or exit from the program. The current execution point can be set to any statement in the program. Breakpoints can be set on any statement. The breakpoint can be set to occur only if a particular condition is true or after the line has been executed a particular number of times. Passage counts can be set on any statement so you can check the number of times particular lines are being executed. The values of data items can be inspected, changed and monitored throughout execution. Unassigned linkage items can be assigned storage space so that debugging can continue. Execution path can be recorded for later tracing so you can confirm how a particular point in the code was arrived at. Debugging operations, and their results, can be recorded in a log file for later inspection or for later replay of either the whole debugging session or repeated sequences of operations. Useful lists of breakpoints, pass counts, monitored data items, active programs and other information are provided to help you control your debugging session.
With this full set of features bugs are quickly tracked down and eradicated.
Features of the Debugger for Windows 3.x

The debugger for Windows 3.x has an older style interface, but still provides a rich set of features including: Displays the original program source. Clearly indicates the current execution point, breakpoint settings, and execution route trace point. Gives convenient access to all functions through menus, push buttons, accelerator keys and a command-line window. Records and displays the CALL stack status. Lists all programs loaded in memory and allows you to switch easily between them. Supports storage of different file types in multiple directories or in a single directory. Provides navigation around the program source through Search and Line Search functions. Provides different levels of code execution control including stepping line by line, executing the next n lines, and full speed execution to the next breakpoint. Code can be executed up to the point indicated by the current selection, up to a specified program and up to a long list of specific execution conditions such as particular verbs being executed, and particular files being accessed. The current execution point can be set to any statement in the program. Breakpoints can be set on any statement. The breakpoint can be set to occur only if a particular condition is true or after the
line has been executed a particular number of times. Doubleclicking on a statement sets and unsets a simple breakpoint. Execution can be interrupted when a particular data item changes value. Passage counts can be set on any statement so you can check the number of times particular lines are being executed. The values of data items can be inspected, changed and monitored throughout execution. Unassigned linkage items can be assigned storage space so that debugging can continue. Execution path can be recorded for later tracing so you can confirm how a particular point in the code was arrived at. Debugging operations, and their results, can be recorded in a log file for later inspection or for later replay of either the whole debugging session or repeated sequences of operations. Useful lists of breakpoints, pass counts, monitored data items, active programs and other information are provided to help you control your debugging session.
Checking out your 16 bit code is no problem with this set of features.
Features of the COBOL Debugging Functions

There are two COBOL debugging functions TRACE and CHECK. These functions can be very useful in trapping difficult to reproduce problems in production situations.
TRACE
TRACE records the following information at program execution time: Results of executed statements Line number and position within line of statement causing abnormal termination. Program name being executed. Messages output during execution.
TRACE lets you check where abnormal termination is happening and the path taken to reach that point. TRACE is enabled by specifying an option at compile time and providing specific details in environment variables at run time.
CHECK
CHECK is also a compile time option. When set the COBOL run time checks for subscripts, indexes or reference modifiers going out of range. A message is output when one of these items goes out of range.
A count can be specified so that the message is only displayed after a certain number of occurrences.
Chapter 2. Debugging in Windows 95 and Windows NT

This chapter explains how to use the interactive debugger to debug programs running under Windows 95 or Windows NT. It takes you through the steps to: Prepare programs for debugging Start the debugging session Perform the most common debugging operations.
It also describes the debugger windows in detail and special functions such as automatic debugging.
10
Overview of the Debugger

The COBOL85 debugger is a full function, interactive source code debugger. It lets you debug executable programs by watching and controlling execution of the actual source code. The debugger provides functions for: Controlling code execution Watching and changing data values Setting breakpoints at specific locations Setting breakpoints on specific conditions Counting the number of times lines are executed Retracing execution paths Recording and replaying debugging commands Operating the debugger automatically Navigating around the source code Configuring the colors of different source code items Viewing the program CALL sequence
Access is provided to these functions in several ways, allowing you to choose the access method that works best for you. The toolbar contains the most frequently used functions and there are accelerator keys for most immediate actions. All the functions are available from the drop down menus. A pop-up menu provides functions best invoked by mouse-only actions. A command line interface provides compatibility with earlier versions of Fujitsu debuggers and supports automated debugging.
11
Preparing Programs for Debugging

This section explains how to prepare COBOL programs for use with the debugger. The figure below gives an overview of the debugging procedure.
Figure 1: Overview of the debugging procedure
12
Debug Program Types

The debugger can debug executable programs (EXE) and dynamic link libraries (DLL) called from executable programs. This chapter refers to these executable programs and dynamic link libraries as debug target programs. Usually, a debug target program consists of multiple COBOL source programs. For the debugger to recognize one of these programs for debugging, you need to create a debugging information file by compiling with the TEST option.
Figure 2: Debugging programs with and without TEST
Compiling for Debugging

To prepare a program for debugging, specify the compiler option TEST when compiling the COBOL source program. This causes the compiler to create a debugging information file and place information used by the debugger in the object file.
13
The file name used for the debugging information file is the name of the COBOL source program with the extension SVD added. The debugger can execute programs compiled without the TEST option, and programs written in other languages, but you cannot view or debug their source code.
Linking for Debugging

To link an object file for debugging, specify the linkage options /DEBUG and /DEBUGTYPE. When you specify these options, the linker processes the debug information that the compiler writes to the object file. The debugger uses this information to link the source code to the executable program file or dynamic link library. The formats of the options /DEBUG and /DEBUGTYPE are:
/DEBUG /DEBUGTYPE: {COFF|BOTH}
When linking COBOL programs to be debugged specify /DEBUG /DEBUGTYPE:COFF in the linker options. When linking with Microsoft Visual C++ development system, specify /DEBUG /DEBUGTYPE:BOTH in the linker options. For other language products refer to the manuals for those products. If you do not want to view certain programs in the debugger, omit the /DEBUG and /DEBUGTYPE options.
14
Starting the Debugger

This section explains how to start the debugger and provide the information required for debugging.
Invoking the Debugger

To start the debugger, do one of the following: Select "WINSVD[Debug]..." from the Tools menu of the PROGRAMMING-STAFF window. Select COBOL85 Debugger from the Start, Programs, Fujitsu COBOL group. Execute WINSVD.EXE
When the debugger starts, it displays its main window. The next step is to enter options to the Start Debugging dialog box. Alternatively you can specify the options in a command line to the debugger. See Specifying Options on the Command Line for details of the command line format.
15
Starting to Debug a Program

To start debugging a program, select File, Start Debugging. This brings up the Start Debugging dialog box.
Figure 3: The Start Debugging Dialog Box
The Start Debugging dialog box lets you input all the information the debugger requires to execute your program. You only need to enter the information that applies to your program. The information requested on each tab is as follows:
16
Table 1: Start Debugging Dialog Box Parameters Parameter Application Application: Execution-time-option: Start program: Description Name of the EXE file to be loaded. This is the only mandatory parameter. Default: Extension of EXE. Any options expected on the command line of the program. Name of the first program to be debugged (must be a program prepared for debugging). Default: the first program for debugging executed in the EXE or a DLL called by it. Directories containing the source of the programs to be debugged. Default: the directory containing the EXE file. Directories containing copy libraries used by the debug target programs. Default: the directory containing the EXE file. Directories containing subschemas used by the debug target programs. Default: the directory containing the EXE file. Directories and extension of form descriptors used by the debug target programs. Default: the directory containing the EXE file, extension PMD. Directories and extension of file descriptors used by the debug target programs. Default: the directory containing the EXE file, extension FFD. Directories containing debugging file information (.SVD files) Default: the directory containing the EXE file. File to drive the debugging session. Default extension: LOG File to save actions and results from the debugging session. Default extension: LOG
Source Source file storage folders: Copy library storage folders: Subschema descriptor file storage folders: Descriptor Screen and form descriptor:
File descriptor:
Debugging Information Debugging information file storage folders Batch Debugging Command file History file
17
Details of the Start Debugging Dialog Box Options

Relative file names When you use relative path names, the debugger adds the directory that was current when the debugger started to the path name. Multiple directory names For fields that accept multiple directories, separate the directory names by semicolons ;. The debugger searches the directories in the order specified. Command and history files Do not specify the same file in both the Command file and History file parameters. If the file specified for the History file already exists it is overwritten. See "Automatic Debugging Operation" for details of batch debugging and command files.
18
Specifying Options on the Command Line

To start the debugger from the command line use the WINSVD command with the following format:
winsvd [start-parameter] [application-name] [execution-timeoption]
You must specify the parameters in the order shown above. If you only enter winsvd, you need to provide the application information in the Start Debugging dialog box. You must specify application-name if you want to enter any other information after winsvd. When you start the debugger with information on the command line, it comes up with the Start Debugging dialog box opened and the command line information entered in the appropriate fields. To start debugging, enter any further information in the Start Debugging dialog box, and click the OK button. See the list below for the supported start parameters.
19
Table2. Start-Parameters Specification Format /G start- program-name /S source-file-storagedirectory-name /C copy-library-storagedirectory-name /A subschema-description-filestorage-directory-name /M screen-and formdescriptors-storage-directoryname /E screen-and formdescriptors-extension /H file-descriptors-storagedirectory-name /O file-descriptors-extension /D debugging-informationfile-storage-directory-name /B command-file-name /L history- file-name /N Field in Start Debugging dialog box Start program Source file storage folders Copy library storage folders Subschema description file storage folders Screen and form descriptor folders Screen and form descriptor extension File descriptor folders File descriptor extension Debugging information file storage folders Command file History file Starts debugging without opening the Start Debugging dialog box.
"-" (hyphen) can be used instead of "/ " (slash) as the first character of a start parameter. The start parameter letter can be upper case or lower case. There should be no spaces between the start parameter letter and the following character string. To specify multiple start parameters, provide one or more blanks between start parameters.
20
For example, to enter a command with the following parameters and options: application name: source file storage directory name: E:\EXE\SAMPLE1.EXE D:\SOURCE
debugging information file storage directory name: E:\SVD execution-time option: PARAM1
the command line would be:

winsvd /sd:\source /de:\svd e:\exe\sample1.exe param1
21
Overview of the Debugger Windows

Main Window
The main window of the debugger contains the Source File window, the Program List window, the Data Watch windows, and the Line Command window. The status bar at the bottom of the window displays program status information and an expanded explanation about the item under the mouse pointer. The figure below shows an example of the main window.
Figure 4: Debugger Main Window
22
You can invoke debugging operations in five ways: 1. Using menu commands: Refer to Help for details of each command. 2. Using accelerator keys: The drop down menus show the accelerator keys beside the functions they invoke. 3. Using tool bar buttons: Refer to Help for details of each button. You can detach and move the tool bar anywhere in the main window by dragging. 4. Using the pop-up menu: You display the pop-up menu by clicking the right mouse button. Refer to Help for details of the pop-up menu commands. 5. Using the line command window: You enter commands in this window. Refer to Help for details of the supported line commands.
23
Source File Window

The Source File window displays the program source and expanded copy libraries. The debugger opens one window for each program being debugged. It opens these windows automatically when execution is interrupted in programs prepared for debugging. You can use the Program List window to open source windows. You can use the pop-up menu to open library files. See the figure below for an example of a source file window.
Figure 5: A Split Source File Window
24
You can use a division bar to split the Source File window and view two parts of the same source file simultaneously. The division bar starts as a small bar, called the split box, at the top of the vertical scroll bar. To split the screen click on the split box and drag it down. Colored highlighting is used in the source window to indicate various states and settings of the statements, such as:

Current statement - the next statement to be executed Current trace statement Statement with a breakpoint set Statement with a passage count set
The debugger colors the source code to distinguish user-defined text, reserved words and comments.
25
Program List Window

The Program List window lists all programs loaded in memory for debugging. To display this window select Program List on the Window menu.
Figure 6: The Program List Window
26
Data Watch Window

The Data Watch window displays the current contents of the selected data. It lets you observe and change the contents of the data items.
Figure 7: A Data Watch Window
Line Command window

The Line Command window accepts line commands and displays the results. To display the Line Command window select Line Command from the Window menu.
Figure 8: The Line Command Window
27
Refer to Appendix A. Debugger Commands for a list of line commands. Refer to Help for detailed specifications of the line commands.
Status Bar
The status bar displays the following information: An expanded explanation of the menu command or toolbar button under the mouse pointer. The event that interrupted execution. The cursor position in the source file window. Whether the debugger treats lower case letters as EQUAL or NOT EQUAL to upper case letters. Whether TRACE is on or off. Whether the operation history log is being written.
28
Using the Debugger

This section explains how to use the debugger for the following tasks: Setting breakpoints Checking and changing data contents Changing the statement execution sequence Breaking execution when data changes Tracing the execution path Tracing the program calling path Breaking into an executing program Allocating linkage section items Checking test coverage Restarting the debug session Automating debug operations Configuring the debugger Splitting the source screen Configuring source code font and colors Checking the status of debugger items
29
Setting Breakpoints
You can set breakpoints at specific locations, at the entry or exit of programs and on specific conditions being satisfied. You set simple breakpoints at the current cursor location by using the toolbar Set/Delete Breakpoint button or the breakpoint function on the pop-up menu. More complex breakpoints are set using the Debug menu Breakpoint function. In the command line window use the BREAK command. The Specific Execution Condition on the Continue menu offers another way of executing to a particular point in the program. This function allows you to execute the program up to a particular verb, location or access of a particular file. Use the Continue, Specific Execution function to execute up to the selected point(s).
Checking and Changing Data Contents

Use the functions Data and Watch Data on the Debug or pop-up menus to check and change the contents of data items. Watch Data windows stay active when the program is executing whereas you close the Data window before continuing execution. To update data in a Watch Data window, type in the new values and press ENTER. Execution must be halted to change the data values. Data, , and Watch Data, , are also available on the toolbar.
In the line command window LIST and SET correspond to the Data function, and DTRACE corresponds to the Watch Data function.
30
Breaking Execution when Data Changes

Sometimes you know that a data item does not have the correct value but it is not obvious where the incorrect value is coming from. In these situations you need to use the Data Monitor function. Data Monitor monitors the data item and interrupts execution when the contents change. You switch on the monitoring of a data item from the Watch Data dialog box or by using the MONITOR line command. For example, to find out where the application updates data item A:
Figure 9: Finding Data Modification Locations
31
Changing the Statement Execution Sequence

The debugger can bypass statements that contain errors and pass control to statements that are not in the original execution sequence. Use the Change Start-Point to Cursor function, on the Continue or pop-up menus, to change the program execution sequence. For example, to bypass line 220 in the program below:
Figure 10: Changing the Statement Execution Sequence
32
Tracing the Execution Path

You can often encounter situations where you can stop a program at the point an error occurs but there are many possible routes to that point. Figuring out the execution path to the point of error can be a very time consuming operation. The Trace function saves you that effort. The Trace function switches on recording of the flow of control. When execution is interrupted you can use the Backward Trace functions to retrace the path of execution. There are four trace functions:

Previous Statement: Steps backwards from the current trace sentence to the sentence that was executed before it. Next Statement: Steps forwards from the current trace sentence to the sentence that was executed after it. Previous Procedure: Jumps backwards from the current trace statement to the first statement in the procedure containing the statement, and then to the first statement in the procedure that was executed before the current trace procedure. Next Procedure: Jumps forwards to the first statement in the procedure that was executed after the current trace procedure.
The Trace function is not available as a line command.
33
For example, to confirm which location calls procedure PRM:
Figure 11: Tracing an Execution Path
Tracing the Program CALL Path

When data in the linkage section is incorrect or the timing of a program call is incorrect, you often need to confirm which program made the call. The debugger lets you check the calling path using the Call Stack function available from the Debug menu and the toolbar. Call Stack displays a list of the active programs in the call stack. It numbers the current program as 0, its caller as 1, the caller of number 1 as number 2, and so on up to the top level program.
34
For example, suppose the application executes the following sequence:

MAINPROG PROGRAMA PROGRAMC PROGRAMA MAINPROG PROGRAMB Breakpoint CALLS PROGRAMA CALLS PROGRAMC EXITS EXITS CALLS PROGRAMB CALLS PROGRAMC encountered in PROGRAMC.
Then the Call Stack list looks like this:
Figure 12: Call Stack List Window
Note that PROGRAMA does not feature in the list as it is no longer active in the CALL hierarchy.
Breaking into an Executing Program

You can break into looping programs, or regain control of programs being run, by pressing the ESC key. You can also select the Break function from the Continue menu or the toolbar.
35
If you are working with a Windows application, for example using PowerCOBOL generated code, you may need to take an action in the user window before control returns to the debugger.
Allocating Linkage Section Items

Finding linkage section allocation errors in the midst of debugging large program suites is potentially time consuming. You need to correct and recompile program source, rebuild the application, and restart debugging. The debugger provides the Linkage function to ease such situations. For example, if a calling program omits a parameter from the CALL statement, debugging of the subprogram can continue without interrupting the debugging session. Use the Linkage function to allocate an area in memory for the missing linkage section item. The debugger reallocates the allocated area when it returns control to the calling program from the subprogram.
Figure 13: Allocating Linkage Section Items
36
Checking Test Coverage

When testing programs you often want to be sure that certain sections or lines of code have at least been executed. The Passage Count function lets you do this. First determine the points in your programs that you want to check. Then set passage counts by either selecting the Passage Count function on the Debug menu or the Set Passage Count function on the pop-up menu. Execute the program. Selecting Debug, Update Passage Count Display, causes the highlight color to change for executed statements. Alternatively you can select Debug, Passage Count that displays the Passage Count window. This window gives a list of all passage count statements and the number of executions for each statement.
Restarting the Debug Session

You can restart debugging the same program, without terminating the debugger, by using the Continue, Re-debug function. All data is re-initialized and you can choose whether to retain or reset the following:

Breakpoints Passage counts Data watch windows The watch conditional expression.
37
Automating Debug Operations

The debugger supports two types of automated debugging: batch and automatic. Both types use a command file that contains debugger commands.
Batch Debugging
In this mode, you specify a command file at the start of debugging. The command file drives the whole debugging session; you do not have to interact with the debugger.
Automatic Debugging
With automatic debugging, you select a command file during a debugging session, and the debugger executes the commands in the file. Control returns to you when all the commands have been executed. Automatic debugging is useful when you want to repeat the execution of a string of commands.
Creating Command Files

You create command files by: Using a text editor Specifying a history file in the Start Debugging dialog (Batch Debugging tab) Starting and stopping history file creation during a debugging session using the Option, Output Log menu function or the ENV command.
38
You can use the history files, created by the debugger, as command files with no changes. Alternatively you can use a text editor to make appropriate changes to the history files or to select particular sections for use in batch or automated debugging. The following example shows a command file to set a breakpoint, and display a data value before and after the breakpoint.
break 47 list data-out cont list data-out cont quit ; ; ; ; ; ; Set a breakpoint Display data Run Display data Run Quit
The debugger treats characters following semicolons as comments.
Configuring the Debugger

You can use the Option, Environments function to configure the following aspects of the debugging environment: Line number display method: Display the number in the COBOL source file or a sequential line number generated by the compiler. Animation speed: Speed at which the Animate function executes statements. Collection of backward trace information: Whether the debugger stores backward trace information. Display source text of subprogram: Whether or not Animate and Backward Trace show the code of subprograms. Depth of PERFORM nesting displayed: The number of nested PERFORM statements for which Animate and Backward Trace will display the code.
39
Substitute character for non-displayable values: This is the character that the debugger substitutes for non-displayable byte values when displaying, printing and monitoring data. Capital/small letter: Whether the debugger handles uppercase characters and lowercase characters as equivalent
Splitting the Source Window

You can split the source code window into two separately scrollable windows. To do this click and drag the Split box that is in the top right hand corner of the window, immediately above the scroll bar.
Figure 14: The Split Box
40
Configuring Source Code Font and Colors

The View, Font and View, Color commands bring up dialog boxes that let you configure the font for the source code and the color of fifteen different attributes of the COBOL source display.
Checking the Status of the Debugger

The debugger maintains information about a number of items: breakpoints, passage counts, watch data, and watch conditional expression. It displays these in the dialog box for each function. The Breakpoint dialog box displays a list of the breakpoints set and whether they are enabled or disabled. The Passage Count dialog box displays a list of statements with passage counts, and the counts for these statements. The Watch Data dialog box displays a list of data items being watched or monitored. The Watch Conditional Expression dialog box displays the conditional expression being monitored.
41
Notes:
The target application should be a 32-bit application. The 32-bit debugger cannot debug 16-bit applications. The debugger supports programs up to 65,535 lines in length, including expanded libraries. When the debugger interrupts execution of a Windows application, it stops that applications processing. Therefore it cannot refresh the displays of its windows. If you want to inspect their current states, arrange your windows so the application windows are always visible. The Line Command window keeps up to about 5000 lines of command results. You can specify statement identification numbers in two different ways: editor line numbers or relative line numbers. You can only use both ways when debugging programs compiled with the NUMBER option. Programs compiled with NONUMBER can only use relative line numbers. To change between using editor line numbers and relative line numbers either use the ENV line command, or the Option, Environments, Display dialog. You cannot set breakpoints and passage counts directly in embedded SQL statements. When programs contain the clauses REPLACING, DISJOINING or JOINING, the debugger displays the original source without applying these clauses. If the position of statements or procedure names changes as a result of the source substitutions it is not possible to debug the programs correctly.
42
Chapter 3. Debugging in Windows 3.1

This chapter contains specific information about how to use the COBOL85 debugger to debug programs created under Windows 3.1. It details: Basic debugging procedures Resource and parameter requirements Debugger screens and windows Major debugger functions and commands.
44
Overview of the Debugger

The debugger helps you debug executable programs by displaying the source of the COBOL program being debugged. It uses highlighting to show the current execution statement and the locations of breakpoints. You control the debugger from the main window by using buttons, menus or line commands. The Windows 3.1 debugger has many features including: Breakpoints at specified locations Break on change of selected data items Break on satisfaction of a specified condition Break on execution of a particular verb or when a particular file is accessed Display and change data values Automated execution of debugger commands Recording and tracing of the execution path
This chapter describes how to use these features when debugging your programs.
45
Figure 15. The Debugger Showing Console, Source, Data, and Line Command Windows
46
Preparing Programs for Debugging

This section explains how to prepare COBOL programs for use with the debugger.
Figure 16. The Basic Procedure for using the Interactive Debugger
The general debugging procedure is: 1. Compile: See "Compiling for Debugging." 2. Link: See "Linking for Debugging." 3. Debug: Start debugging programs that have debugging information available. See "Debug Program types." 4. Execute: Execute the debugged program.
47
Debug Program Types

The debugger debugs executable programs (EXE) and dynamic link libraries (DLL) that are called from executable programs. This manual refers to these executable programs and dynamic link libraries as debug target programs. Usually, a debug target program consists of multiple COBOL source programs. For the debugger to recognize one of these programs for debugging, you need to create a debugging information file by compiling with the TEST option.
Figure 17. Programs Compiled With and Without the TEST Option

To prepare a program for debugging, specify the compiler option TEST when compiling the COBOL source program. This causes the compiler to create a debugging information file and place information used by the debugger in the object file.
48
The file name used for the debugging information file is the name of the COBOL source program with the extension SVD added. The debugger can execute programs compiled without the TEST option, and programs written in other languages, but you cannot view or debug their source code.

To link an object file for debugging, specify the link option "/CO". When you specify this option, the linker processes the debug information that the compiler writes to the object file. The debugger uses this information to link the source code to the executable program file or dynamic link library. If you do not want to view certain programs in the debugger, omit /CO the option.
49
Starting the Debugger

This section explains how to start the debugger and provide the information required for debugging.
Invoking the Debugger

To start the debugger, do one of the following: Select "WINSVD" from the Utility menu of the PROGRAMMING-STAFF window. Select "WINSVD.EXE" from the directory window of the file manager. Assign "WINSVD.EXE" an icon, then double-click on the icon to start it. Select the Execute command from the program manager or file manager menu, then specify the WINSVD command in command format.
You can only run one debug session at a time. When the debugger starts it displays the Start Parameter window. Enter the required options in the Start Parameter window (see Specifying Options Using the Debugger Start Parameter Dialog Box below), then click on the OK button. The debugger displays the main window. Start debugging using the menus and buttons on the main window.
50
Starting to Debug a Program

To debug a program, you need to specify the resources (COBOL source program and debugging information file) and parameters required by the debugger. This section explains how to specify start parameters in the debugger Start Parameter window and on the command line.
Specifying Options Using the Debugger Start Parameter Dialog Box

This section explains how to specify debugger start parameters using the debugger Start Parameter dialog box, shown below.
Figure 18. The Start Parameter Dialog Box
51
Command Line: Specify an executable program name to be debugged. Include the drive and path with the file name. If you do not specify an extension, EXE is assumed. The executable program is mandatory. If the executable program expects command line options option, leave at least one blank after the program name, then enter the options.
For example:
f:\exe\sample1.exe param1 | | | +--- Passed to sample.exe +--- Debugger activates this program.
Start Program Name Specify the external name of the first program you want to debug. The external program name must be prepared for debugging. You can omit this parameter. If you omit this parameter the debugger interrupts execution at, and displays the source for, the first program prepared for debugging in the EXE or called DLLs.
Command File Specify the name of a command file that contains a series of commands to executed by the debugger. If you do not supply an extension, .LOG is assumed. You can omit this parameter. For batch debugging and using command files, see "Automating Debugging Operations."
52
Log File If you want to create an operation history file specify the full drive, path, and file name for the file. The debugger writes debugging commands and their results to the file. If you do not supply an extension, .LOG is assumed. You can omit this parameter. Note that the only way of verifying the results of batch debugging (when you specify a Command File) is to specify a log file. If the file already exists, it is overwritten. Do not specify the same file as a Command File and Log File as it may be corrupted.
FORM Extension For programs that use screen and form descriptors enter the extensions for these files. If the files do not have extensions, enter None. You can omit this parameter. If you omit this parameter, the extension .SMD is used.
Source Text Specify the drive, path, and directory name containing the source files. To specify multiple directories, separate each one with a semicolon (;). You must provide this parameter if the COBOL source is not in the same directory as the executable. The debugger searches for the directories in the order specified. You can omit this parameter. If you omit this parameter, the debugger uses the directory containing the executable program.
53
Libraries Specify the drive, path, and directory name containing COBOL source libraries. To specify multiple directories, separate each one with a semicolon (;). You must provide this parameter if the COBOL libraries are not in the same directory as the executable. The debugger searches for the directories in the order specified. You can omit this parameter. If you omit this parameter, the debugger uses the directory containing the executable program.
Debug Information Specify the drive, path, and directory containing the debugging information files. To specify multiple directories, separate each one with a semicolon (;). You can omit this parameter. If you omit this parameter, the debugger uses the directory containing the executable program.
FORM Files Specify the drive, path, and directory name containing display and form descriptors. To specify multiple directories, separate each one with a semicolon (;). This parameter is required to debug a COBOL source program containing screen and form descriptor files using the source text manipulation function. You can omit this parameter. If you omit this parameter, the debugger uses the directory containing the executable program.
54
Subschema Files Specify the drive, path, and directory name containing the subschema library. To specify multiple directories, separate each one with a semicolon (;). This parameter is required to debug a COBOL source program containing subschema libraries fetched using source text manipulation. You can omit this parameter. If you omit this parameter, the debugger uses the directory containing the executable program.
Environment Specify the drive, path, and directory name containing a file for maintaining specified parameters and debugging environments (operating environment file). You can omit this parameter. If you omit this parameter, the debugger uses the directory containing the executable program. For details of the operating environment file, see "Debugger Operating Environment File."
55
Specifying Options on the Command Line

To start the debugger from the command line use the WINSVD command with the following format:
winsvd [start-parameter] executable-program-name [executionoption]
You must specify the parameters in the order shown above. If you only enter winsvd, you need to provide the application information in the Start Parameters dialog box. You must specify application-name if you want to enter any other information after winsvd. When you start the debugger with information on the command line, it comes up with the Start Parameters dialog box opened and the command line information entered in the appropriate fields. To start debugging, enter any further information in the Start Parameters dialog box, and click the OK button. See the list below for the supported start parameters. "- (hyphen)" can be used instead of "/ (slash)" as the first character of a start-parameter. The start parameter letter can be upper case or lower case. There should be no spaces between the start parameter letter and the following character string. To specify multiple start parameters, provide one or more blanks between start parameters.
56
Table 3. Start parameters Specification Format /g debugging-start-program-name /b command-file-name /l operation-history-file-name /e format-description-file-extent /s source-file-directory-name /c library-directory-name /d debugging-information-directoryname /m format-description-file-directoryname /a subschema-library-directoryname /i operating-environment-filedirectory-name /n Contents Specify a start program name in the Start debugging dialog box Specify a command file name in the Start debugging dialog box Specify an operation history file name in the Start debugging dialog box Specify a screen and file descriptor file extent in the Start debugging dialog box Specify a source file directory name in the Start debugging dialog box Specify a library directory name in the Start debugging dialog box Specify a debugging information directory name in the Start debugging dialog box Specify a screen and form descriptor file directory name in the Start debugging dialog box Specify a subschema library directory name in the Start debugging dialog box Specify an operating environment file directory name in the Start debugging dialog box Debugging is started without opening the Start debugging dialog box
For example, to enter a command with the following parameters and options: executable program file name: execution option: E:\EXE\SAMPLE1.EXE PARAM1
COBOL source program directory name: D:\SOURCE debugging information directory name: E:\SVD
winsvd /sd:\source /de:\svd e:\exe\sample1.exe param1
57
The Debugger Operating Environment File

The debugger can save the specified start parameters and values in an operating environment file. You can use this file to provide the start parameter values for future debugging sessions. If you specify an operating environment file directory when you start the debugger, the debugger uses the operating environment file in the specified directory. The debugger displays the values in the Start Parameter dialog box. If you do not specify an operating environment file directory, the debugger uses the directory specified in the development environment initialization file (APDF.INI). When you save the operating environment, the directory containing the operating environment file is written to the development environment initialization file. Therefore, after the operating environment is saved, the debugger displays the saved values on start-up unless you delete the operating environment file or specify a different operating environment file directory. When you save the operating environment the debugger overwrites any previously created operating environment file in the specified directory.
58
Overview of the Debugger Windows

This section describes the windows and functions of the debugger.
Main Window
When you start the debugger, it displays the source of your program. This is the main window of the debugger. It gives you access to various debugger functions while viewing your COBOL source.
Figure 19. Example of the main debugger window
You select functions in the main window by one of the following methods: Selecting a menu command or a shortcut key
59
Selecting a command button Double-clicking the left mouse button or clicking the right mouse button
Selecting a Menu Command or a Shortcut Key

Menu commands work in two ways: by selecting some text, then selecting the command, or by selecting the command, then specifying the target object and parameters. Menu commands that are selected after selecting text: Runto specified position Change execution start point Set breakpoint Set data monitoring Allocate linkage section Search condition Data control Set passage count
Commands where operands are specified after selecting the menu command: Change environment Rerun Quit Runto next n steps Runto specified position Specific execution condition
60
Data control Set data monitoring List data monitoring Allocate linkage section Search line Search condition Set breakpoint Manage breakpoint Set monitoring condition List program Automatic debugging Passage count control
Selecting a Command Button

The debugger provides command buttons for quick execution of common operations. See Help for information about how to use each command button.
Double-Clicking the Left Mouse Button or Clicking the Right Mouse Button
You can double-click the left mouse button to set or reset breakpoints. You can execute up to the line you are pointing at by clicking the right mouse button.
61
Data Trace Window

You can monitor data values in the data trace window by using the data monitoring function (DTRace). Up to 10 items can be monitored in the data trace window. You can also get the debugger to break execution when a particular item is changed. The modified data is displayed in the data trace window. You can only monitor one data item in this manner. If you specify two or more data modification execution breaks, the last one is used. An example display of a data trace window is shown below.
Figure 20. Example of the data trace window
62
Line-Command Window
Use the line command window to enter subcommands and display subcommand execution results. This window is displayed by selecting the line command window command from the Option menu. Use this window when executing subcommands with the keyboard. See "Subcommand Functions," for subcommand syntax and usage method. An example display of a line command window is shown below.
Figure 21. Example of the line command window
The line command window displays the previously executed subcommands and their results. These can be viewed by scrolling the window. You can re-enter previously executed subcommands by placing the cursor on the command and pressing ENTER. You can also edit the previously executed subcommands before re-entering them. If a subcommand produces a large amount of output, you can interrupt it by pressing the ESC key. For a list of the subcommands, see Appendix A, "Debugger Command List."
63
Debugger Functions
This section explains the debugger functions and how to use them.
Debugger Menus and Functions

The commands of each menu and the corresponding shortcut keys are listed below. For details of each function, see the Help information for each window.
Control Menu
ENV (SHIFT+F2): Changes the debugger environment. Rerun (SHIFT+F3): Restarts the program from the beginning. Quit (SHIFT+F4): Exits the debugger.
Runto Menu
Run (SHIFT+F5): Executes until the next break event occurs. Trace: Executes statements one at a time, at a preset speed, until the next break event occurs. Next(1): Executes statements for one step only. Next(n): SHIFT+F6: Executes statements for the specified number of steps. Position: Executes until the specified statement is reached. Exec on Condition (SHIFT+F7): Executes until the statement satisfying the specified execution condition is reached. Specify condition: Specify an execution condition.
64
Change StartPoint (SHIFT+F8): Changes the position where execution is restarted.
Break Menu
Set breakpoint (SHIFT+F9): Sets a breakpoint. Breakpoint control (SHIFT+F10): Deletes or changes the condition of a breakpoint. DataCHK (SHIFT+F11): Specify a conditional expression so that processing is broken when the condition is satisfied.
Data Menu
Data control (CTRL+F1): Displays, modifies, or prints data values. DTRace (CTRL+F2): Specify the data to be displayed and monitored on a data trace window. Monitor control (CTRL+F3): Displays a list of the data items being monitored and lets you delete items from the list or select an item to be monitored for changes. LINKage (CTRL+F4): Allocates a data area of a linkage section.
Window Menu
Current (CTRL+F5): Takes you to the current statement (the next statement to be executed). CALLS: Displays call path information of the program. LSEArch (CTRL+F6): Displays the specified line.
65
Next (CTRL+F7): Searches for the next occurrence of the character string specified in the search condition. SEArch: Specify a search condition. PROG (CTRL+F8): Lets you display the source of another program in the suite being debugged.
Option Menu
Line-Command Window (CTRL+F9): Displays a line command window and enables input of subcommands. AUTOrun (CTRL+F10): Executes the debugging commands contained in the specified file. Set Passage Count (CTRL+F11): Sets a passage count point. Passage Count control: Displays, initializes, or resets passage counts.
66
Using the Debugging Functions

This section explains how to use the debugger for the following tasks: Checking and changing data contents Changing the statement execution sequence Breaking execution when data changes Tracing the execution path Allocating linkage section items Restarting the debug session Automating debug operations Configuring the debugger Checking the status of debugger items Testing programs using functions specific to the GS-Series
67
Checking and Changing Data Contents

You can check the value of data items when execution is halted. To execute a program up to a specific position, set a breakpoint at that point, then execute the program using one of the Runto functions. To break program execution when the program is in a loop, use the ESC key. You then use the Data control function to check or modify the values of data items. For example, to stop program execution at line 250, check whether data A is 2, then continue processing in the following COBOL source program:
100 200 210 220 250 PIC 9 VALUE : PROCEDURE DIVISION. MOVE 2 TO PERFORM SUB. : ADD 1 TO : 01 A 0. A. B.
Follow this debugger operation procedure:

1. 2. 3. 4. 5. Menu Command Set breakpoint Run Data control (display) Data control (modification) Run Subcommand BREAK 250 CONT LIST A SET A = 2 CONT
1-2. The COBOL program is executed and execution is broken at line 250. 3. Check the contents of data A. 4. Set A to 2. 5. Run to the next breakpoint.
68
Changing the Statement Execution Sequence

The debugger can bypass statements that contain errors and pass control to statements that are not in the original execution sequence. Use the Change Startpoint function of the Runto menu, to change the program execution sequence. For example, to bypass line 220 in the program below:
100 150 210 220 230 500 510
01
PIC 9 VALUE 0. : PROCEDURE DIVISION. : MOVE 1 TO A. CALL "SUB". MOVE A TO B. : IDENTIFICATION DIVISION. PROGRAM-ID. SUB.

1. 2. 3. 4. Menu Command Set breakpoint Run Change StartPoint Run Subcommand BREAK 220 CONT SKIP 230 CONT
1-2. The COBOL program is executed and execution is broken at line 220. 3. CALL at line 220 is bypassed. 4. Run to the next breakpoint.
69
Breaking Execution when Data Changes

Sometimes you know that a data item does not have the correct value but it is not obvious where the incorrect value is coming from. In these situations you need to use the Data Monitor (Dtrace, Break at Change) function. Data Monitor monitors the data item and interrupts execution when the contents change. Alternatively you can set a condition in the Runto, Exec on Condition function. When "break at change" is specified for data monitoring, program execution is broken when the value of the specified data is changed. When monitoring data, the data is always displayed in the data trace window. When "Exec on condition" is executed, program execution is broken when the specified condition is satisfied. For example, to break the following COBOL source program when data A is changed by using the data monitoring function:
100 110 200 270 280 290 300 01 01 A B PIC 9 VALUE PIC 9. 0.
: PROCEDURE DIVISION. : KEISAN. ADD 1 TO COMPUTE A = B + COMPUTE B = B +
B. 1. 1.

1. 2. Menu Command Dtrace (specification of break at change) Run Subcommand MONITOR A CONT
Execution is interrupted at line 300, that is immediately following the setting of the value in data A. Check the contents of data A and modify as required.
70
Tracing the Execution Path

You can often encounter situations where you can stop a program at the point an error occurs but there are many possible routes to that point. Figuring out the execution path to the point of error can be a very time consuming operation. The trace function saves you that effort. The ENV, reverse trace collection option switches on recording of the flow of control. When execution is interrupted you can use the trace buttons to retrace the path of execution. There are four trace buttons:

Stmt <: Steps backwards from the current trace sentence to the sentence that was executed before it. Stmt >: Steps forwards from the current trace sentence to the sentence that was executed after it. Proc <: Jumps backwards from the current trace statement to the first statement in the procedure containing the statement, and then to the first statement in the procedure that was executed before the current trace procedure. Proc >: Jumps forwards to the first statement in the procedure that was executed after the current trace procedure.
The Trace function is not available as a line command. For example, to check the caller of procedure PRM in the following COBOL source program:
71
100 200 210 220 230 250 260 270
01
PIC 9 VALUE : PROCEDURE DIVISION. MOVE 1 TO PERFORM PRM. STOP RUN. : PRM. ADD 1 TO PRM-EXIT. :
0. A.
A.

1. 2. 3. 4. 5. Menu Command ENV (specification of reverse trace collection) Set breakpoint Run Stmt button (up) Stmt button (up) Subcommand ENV BTR BREAK 260 CONT no corresponding subcommand no corresponding subcommand
1-3. The COBOL program is executed and is broken at line 260. 4. The cursor is moved to line 220. 5. The cursor is moved to line 210.
72
Allocating Linkage Section Items

Finding linkage section allocation errors in the midst of debugging large program suites is potentially time consuming. You need to correct and recompile program source, rebuild the application, and restart debugging. The debugger provides the Linkage function to ease such situations. For example, if a calling program omits a parameter from the CALL statement, debugging of the subprogram can continue without interrupting the debugging session. Use the Linkage function to allocate an area in memory for the missing linkage section item. The debugger reallocates the allocated area when it returns control to the calling program from the subprogram.
Figure 22. Allocating Linkage Section Items
73
Restarting the Debug Session

You can restart debugging the same program, without terminating the debugger, by using the Control, Rereun function. All data is re-initialized and you can choose whether to retain or reset the following: Breakpoints Passage counts Monitoring conditions
Automating Debug Operations

The debugger supports two types of automated debugging: batch and automatic. Both types use a command file that contains debugger commands. Batch Debugging In this mode, you specify a command file at the start of debugging. The command file drives the whole debugging session; you do not have to interact with the debugger. Automatic Debugging With automatic debugging, you select a command file during a debugging session, and the debugger executes the commands in the file. Control returns to you when all the commands have been executed. Automatic debugging is useful when you want to repeat the execution of a string of commands.
74
Creating Command Files You create command files by: Using a text editor Specifying a log file in the Start Parameter dialog Starting and stopping log file creation during a debugging session using the ENV start and stop operation logging options.
You can use the log files, created by the debugger, as command files with no changes. Alternatively you can use a text editor to make appropriate changes to the log files or to select particular sections for use in batch or automated debugging. The following example shows a command file to set a breakpoint, and display a data value before and after the breakpoint.
break 47 ; Set a breakpoint list data-out ; Display data cont ; Run list data-out ; Display data cont ; Run quit ; Quit
The debugger treats characters following semicolons as comments.
75
Configuring the Debugger

You can use the Control, ENV function to configure the following aspects of the debugging environment: Line number display method: Display the number in the COBOL source file or a sequential line number generated by the compiler. Library text expansion and display: Whether the library is expanded in the main window Result of line command display: Whether execution results of the subcommand are displayed in the command input window during automatic debugging Operation logging collection: Whether a debugging operation log is collected, and the file name when a log is collected Trace speed: Speed of highlight movement during trace execution Collection of backward trace information: Whether backward trace information is collected Display source text of subprogram: Whether backward trace and trace are performed for the program currently being executed and whether subprograms are included Display nested level in the PERFORM statement: Nest level of the PERFORM statement for backward trace and trace Substitute character at attribute error: Character that substitutes characters that cannot be displayed by displaying, printing and monitoring data. Capital/small letter: Whether uppercase characters and lowercase characters are handled as equivalent
76
Checking the Status of the Debugger

The debugger maintains information about a number of items: breakpoints, passage counts, and monitored data. It displays these in the dialog box for each function or in response to the STATUS subcommand. The Breakpoint Control dialog box displays a list of the breakpoints set and whether they are enabled or disabled. The Monitor Control dialog box displays a list of data items being monitored. The Passage Count Control dialog box displays a list of statements with passage counts, and the counts for these statements.
Testing Programs That Use Functions Specific to the GS-Series

Programs that use the following functions specific to the GSSeries (machines available in Japan) can be executed using the debugger: Presentation file function with "CMD", "TRM", or "WST" specified as the symbolic destination Network database function
When you execute such programs, the debugger breaks execution at statements that access files specific to the GS-Series. At this point, the input data area can be changed or the contents of the output record area can be checked. Therefore, programs that use functions specific to the GS-Series can be tested with this system.
77
Subcommand Functions
This section explains the available debugger subcommands. Use subcommands when debugging with a line command window or automating debugging operation with a command file.
Coding Format
This section explains the coding format common to each subcommand, such as the subcommand syntax notation symbols.
Structure of a Subcommand
A subcommand consists of a subcommand name and operands. A subcommand name indicates the function of the subcommand, and operands provide additional information for execution. Use one or more blanks as separators between a subcommand name and an operand, and between operands. Operands include positional operands and keyword operands. A positional operand is input at a predetermined position in a predetermined sequence. A positional operand is indicated as a non-terminator symbol. When specifying a character string containing a blank in a positional operand, enclose the entire positional operand in parentheses. A keyword operand is identified by a specific character string. A keyword operand is indicated by a terminator symbol. When specifying a subparameter, however, specify a subparameter following a keyword by enclosing it in parentheses.
78
Subcommands and keyword operands are case-insensitive. Other operands may or may not be case-sensitive depending on the specification at compile time. When a nonnumeric literal is referenced, however, a character string is handled as specified regardless of the specification at compile time.
Syntax Notation
The syntax notation of subcommands is described below. Syntax notation symbols have a special meaning for describing syntax. Syntax notation symbols are described below.
{ }: One of the items enclosed by this symbol must be selected. {|}: Either item of the items separated by a "|" symbol must be selected. [ ]: Items enclosed by this symbol can be omitted. ... The item prior to this symbol can be specified repeatedly. _ (underline): Indicates the default value when all the items in the omission symbol are omitted. Non-terminator symbols are specified by replacing them with the actual value. Indicate a non-terminator symbol with an English character. Terminator symbols are specified with a predetermined character string. Terminator symbols include those that are indicated by English boldface characters and the following symbols:
() = :
79
& * # . Among the terminator symbols, sections that are described in uppercase letters indicate abbreviations of the terminator symbols. For instance, when "ENTry" is specified, "ENTRY" and "ENT" can be entered.
Explanation of Common Operands

This section describes operands that are common to the entire debugger.
Program Name
A program name indicates the program to be processed by the subcommand. Specify a program name in one of the following formats: * & external-program-name secondary-entry-name external-program-name.internal-program-name external-program-name.* external-program-name.internal-program-name.*
80
An external program is a program that is entered in the outermost position of one compile unit. An internal program is contained in an external program. A secondary entry name is a name of the entry point determined by the ENTRY statement. An asterisk (*) indicates all programs in the range. Table 4 lists the scope in each specification format.
Table 4. Specification formats and scope of program names Specification Format * (asterisk) & (ampersand) External-program-name. Secondary-entry-name External-program-name. internal-programname External-program-name.* External-program-name. internal-programname.* Scope All the programs Program currently being broken Specified external program Specified secondary entry point. A secondary entry point can be specified when the ENTRY operand is specified in each subcommand. Specified internal program Specified external program and all internal programs contained in the program Specified internal program and all the internal programs contained in the specified internal program
Program Qualification
Program qualification indicates the scope of a statement identification number and that of the identification name specified in the subcommand. For explanations about statement identification numbers and identification names, see "Statement Identification Number," and "Identification Name." Program qualification methods are explicitly specifying in the IN operand of the subcommand or using the currently valid program qualification (implicit program qualification) without specifying the IN operand.
81
Implicit program qualification is set automatically when program execution is broken. When execution of a debugged program is broken, the program in the break position is used as implicit program qualification. When execution of a program other than a debugged program is broken, the nearest debugged program in the calling path is used as the implicit program qualification. When no debugged programs are operating, implicit program qualification is not determined, and the IN operand must be specified. Implicit program qualification can be changed with the SCOPE subcommand. Implicit program qualification can be displayed with the STATUS subcommand with SCOPE specified. Specify program qualification to be specified in the IN operand and SCOPE subcommand as follows.
external-program-name [external-program-name].internal-program-name
When an external program name is omitted, the external program name of the implicit program qualification becomes valid. Table 5 lists statement identification numbers, search sequence, and program qualification search ranges.
Table 5. Program qualification search range Program Qualification Specification Format External Program Only Including Internal Program Editor line number Intra-file relative line number Line sequence number Paragraph name Section name Identifier Entire program including internal programs External programs (internal programs are not included) External program Entire program including internal programs (specification of an internal program name is invalid) Internal program Internal program (the parent program is also included for a global name)
82
Statement Identification Number

Statement identification number is used to reference a statement in a source program and specify which of the formats listed below is used. When the specified statement identification number is not unique within the search range, the first statement number defined within the search range of program qualification is used. The environment change function or specification of the ENV subcommand determines whether the subcommand operand is an editor line number, an intra-file relative line number, or line sequence number.
*SECTION-NAME Specify the section name entered in the program by using an asterisk (*) as a prefix. *PARAGRAPH-NAME Specify the paragraph name entered in the program by using an asterisk (*) as a prefix. When the paragraph name is not qualified by a section name and the program is operating, the paragraph name is first searched in the section from the position that execution is broken, then
83
searched from the beginning of the program. When the section contains the specified paragraph name, the first match becomes the valid paragraph. If the specified program is not active, the paragraph is searched from the beginning of the program. When a paragraph name is qualified with a section name, the paragraph is searched only within the specified section. When the specified paragraph name is detected, the first match is used. Specifying a section name or paragraph name is the same as specifying the first matching statement in the section or paragraph. COPY-QUALIFICATION-VALUE Specify this operand when referencing a statement in the COBOL library that is incorporated by the COPY statement. Specify a COPY qualification value by referencing a source window and compilation list. A COPY qualification value is the number that is assigned by a compiler automatically at compile time. COPY-SPECIFIER Specify this operand when referencing a statement in a COBOL library that is fetched by the COPY statement. For the COPY specifier, specify the statement identification number where the COPY statement is entered with an editor number, a intra-file relative line number, or a line sequence number. To specify line 1000 of COPYFILE, specify as follows.
BREAK 100/1000
84
EDITOR-NUMBER Specify the number entered in a sequence number area in the source program. INTRA-FILE-RELATIVE-LINE-NUMBER Specify the number of lines from the beginning of the file. This case applies when "Sequential" is specified for line number and "NOLIB" is specified for library text expansion in the environment change function or ENV subcommand. LINE-SEQUENCE-NUMBER This number is created by adding 1 from the first line of the file for the result obtained by execution of the REPLACE statement and COPY statement for the source program and source statement. This number is specified by referencing a source window or compilation list. INTRA-LINE-IDENTIFICATION-NUMBER Specify this operand when referencing a statement other than the first statement of the line when multiple statements are entered on one line of a program. When only one statement is entered on a line or the first statement is referenced even if multiple statements are entered on the line, this operand can be omitted. For an identification number of a line, specify a value by incrementing sequentially using a value of 1 for the first statement of the line.
Identification Name
The following five types of identifiers can be specified: Identifier Condition name Index name
85
Identifier
Special registers Symbolic-constant
The coding format of an identifier complies with the COBOL language specifications except for the subscript and reference modification. Specify subscript in the following format:
integer identifier[{+|-}integer] index-name[{+|-}integer] symbolic-constant[{+|-}integer]
Specify reference modification in the following format:

high-order-end-character-position: [length]
Use the following format to specify a high-order-end character position and length:
integer identifier[{+|-}integer] symbolic-constant[{+|-}integer]
Condition-Name The coding format of a condition-name complies with the COBOL specification except for the subscript. Use the following format to specify subscript:
integer identifier[{+|-}integer] index-name[{+|-}integer] symbolic-constant[{+|-}integer]
Index-Name The coding format of an index-name complies with the COBOL language specifications.
86
Special-Register The COBOL language specifications determine the specification format of a special register and whether a value can be changed by a debugger subcommand. The following special registers, however, cannot be specified. SHIFT-IN SHIFT-OUT ADDRESS OF
Symbolic-Constant The coding format of symbolic-constants complies with the COBOL language specifications.
Literal
A literal can be entered in the same format as for the COBOL language specifications. The following literal, however, cannot be entered:
[ALL] symbolic-character
When entering a literal, either a double quotation mark(") or apostrophe (') can be used. Mixed use, however, is not allowed.
Expression
The following types of expressions can be specified: Assignment expression Conditional expression Arithmetic expression
87
Rules of Assignment Expressions
Blanks are not required before and after "=" in an assignment expression. The assignment rules comply with the COBOL language specifications. When a hexadecimal nonnumeric literal is specified as a numeric item, however, the number of bytes occupied by the specified hexadecimal nonnumeric literal in memory and that of the numeric item must be the same. The specified hexadecimal nonnumeric literals are stored in memory in order from left to right unmodified. Rules of Conditional Expressions The following conditional expressions can be specified: Relation condition of a simple condition Combined condition of a complex condition
Specify the relation condition of a simple condition in the following format:
Literals cannot be specified for both members of a relational operator.
88
One or more blanks are required before and after the reserved word that forms a relational operator. No blanks are required, however, before and after the following relational operators: > < = >= =<
For a combined condition of a complex condition, combine a simple condition and logical operator "AND" or "OR". One or more blanks are required before and after a logical operator. Rules of Arithmetic Expressions Arithmetic expressions must be entered according to the following rules: In an arithmetic expression, the primary expression and the primary expression with an unary arithmetic operator can be entered. In a primary expression, a identifier, a literal, and a parenthesized arithmetic expression, and the LENG function can be entered.
The identifier and literal must be a numeric data item or numeric literal, figurative constant ZERO (ZEROS, ZEROES). In the LENG function, an argument must be a identifier, nonnumeric literal, hexadecimal nonnumeric literal, or national literal of other than an internal Boolean item.
89
Explanation of Subcommands
For the list of subcommands, see Appendix A, "Debugger Command List." For details of the syntax of each subcommand, see Help.
90
Notes
Multiple debuggers cannot be activated concurrently. The debugger does not acquire resources exclusively. Therefore, if the resources are accessed by other processes while the debugger is being used, operation errors may occur. When the REPLACE statement or the COPY statement with REPLACING, DISJOINING, or JOINING phrase is entered in a source program, the source program before the character string was replaced is displayed on the screen. When the position of the statement or procedure name changes before and after replacement, debugging cannot be performed correctly. A source program containing a valid description following the COPY statement in the same line cannot be debugged correctly. Debugging cannot be performed with an editor line number for a program having compiler option NONUMBER specified. When a debugger is operated while available conventional memory is low, a resource shortage may occur although there is sufficient available memory in Windows. A source program having a total number of lines that exceeds 65,535 after library expansion cannot be debugged.
91
The following operations must be performed while execution is halted: System menu and scroll bar operations on the console screen of an application System operations other than closing of system menu.
In the debugger, comparison of national blanks is always performed as NSPCOMP(NSP). When RERUN or QUIT is selected while message "program execution ended" is output at debugging of a program under AP/EF or COBPRTST, an incorrect message may be generated. In this case, re-execute the program until the message "broken due to termination of the program" is displayed, then select RERUN or QUIT. "Library expansion display" cannot be performed for programs that use the file define deck as a library. Binary items with lengths other than 2, 4, or 8 bytes are handled as alphanumeric data items in programs compiled with compiler option BINARY(BYTE) specified. Use the hexadecimal format when referencing or setting values.
92
Chapter 4. Debugging Mixed COBOL85 and PowerCOBOL

This chapter covers the details of debugging applications that contain mixtures of COBOL85 and PowerCOBOL code. Details covered are: How to prepare programs for debugging How to start the debugging process What to look out for when debugging
94
Overview
You can use the COBOL85 Debugger to debug applications that contain a mix of COBOL85 and PowerCOBOL code. This chapter explains how to use the COBOL85 debugger to debug such applications and covers some common situations you may encounter. You prepare PowerCOBOL and COBOL85 code for debugging as if you were working solely with one type of code. You bring up the main program under the COBOL85 debugger and debugging proceeds as normal. There is one difference in that the COBOL85 Debugger shows you the full, expanded, PowerCOBOL code. The debugger displays the main event loop, which PowerCOBOL usually hides, and some statements that you code within PowerCOBOL are expanded into MOVEs and CALLs to subroutines. Once you understand this additional code, you are essentially debugging a COBOL85 application. This chapter focuses on the 32-bit debugger but gives comments wherever the 16-bit debugger is significantly different. Note: When the main program is a PowerCOBOL sheet, you can use the PowerCOBOL Debug function to debug the PowerCOBOL code. This has the advantage that you do not see the expanded PowerCOBOL code, but the disadvantage that you cannot view and debug the COBOL85 code. Check the PowerCOBOL documentation for information about the PowerCOBOL Debug function.
95
Preparing Programs for Mixed COBOL Debugging

You code, compile and link both COBOL85 and PowerCOBOL programs as if you were working with only one type of COBOL.
Building COBOL85 Programs for Debugging

To prepare COBOL85 programs for debugging, compile them with the TEST directive and link them with the /DEBUG and /DEBUGTYPE:COFF options. Programming-Staff includes the linker options automatically for you when you specify the TEST compiler directive. (16-bit: Link with the /CO option. This is not set automatically by Programming-Staff.)
Building PowerCOBOL Programs for Debugging

PowerCOBOL programs to be debugged must have the "Build program for debug" option checked in the Compile Options dialog box. Checking this option also ensures that the programs are linked in the appropriate manner.
COBOL Run-Time Options

Fujitsu COBOL tailors its behavior at run-time by checking the settings of a number of environment variables and run-time options. You can set these variables in a variety of ways, documented in the COBOL85 2.0 User's Guide.
96
Before starting to debug it is a good idea to specify all the environment variables you require in the initialization file (COBOL85.CBR). To do this either edit the file, or use the Runtime Environment Setup dialog displayed when the COBOL runtime starts. You can keep the option to make adjustments when the program starts by setting @EnvSetWindow=USE. Settings to consider include: File allocation mappings. COBOL sub-program name to DLL file name mappings. Other environment settings specific to your application requirements. @EnvSetWindow=UNUSE. This suppresses the display of the Runtime Environment Setup dialog every time you start or restart the application in the debugger.
97
Starting Debugging Mixed COBOL Applications

Invoke the COBOL85 debugger, and start the main program of the application as described in Chapter 2 or 3. The screen below shows what you might see for a PowerCOBOL main program, with the source window maximized. Note that the code you first see for the PowerCOBOL program is not code that you wrote.
Figure 23: PowerCOBOL program source in the 32-bit COBOL85 debugger.
98
You are now ready to start debugging. See the next section for debugging tips.
Tips for Debugging Mixed COBOL Applications

Expanded PowerCOBOL Code
The COBOL85 Debugger shows you code that PowerCOBOL normally hides. There are three types of expanded code you will see: The main event loop Nested sub-programs to handle events Expanded code that handles PowerCOBOL items, methods and attributes.
These are explained below.
The Main Event Loop

All Windows window-managing programs have a controlling event loop. This is because the way Windows works is to pass events (or messages) to programs and it expects the programs to act on these messages immediately. Examples of events or messages are redisplay your window, button 1 was clicked, close your application. Each program receives messages and takes action on the messages received. A PowerCOBOL sheet receives the messages in its main procedure and determines the type of message in the EVALUATE
99
POWERMESSAGE statement. The main procedure then calls
nested sub-programs to handle the events.
When debugging within PowerCOBOL you do not see the main event loop as PowerCOBOL only shows the code that you wrote.
Nested Sub-Programs to Handle Events

PowerCOBOL creates nested sub-programs around code that you write to handle events. This is not visible to you within PowerCOBOL. However, when using the COBOL85 Debugger, you see all the code for these nested programs. Nested programs start with the code:
IDENTIFICATION DIVISION. PROGRAM-ID. "PROGRAM-NAME".
and end with the code:

END PROGRAM "PROGRAM-NAME".
"PROGRAM-NAME" usually has the structure:
item-event
e.g. EDIT1-CHANGE, EDIT1-RETURN, PUSH1-CLICK. The COBOL85 Debugger displays all the nested sub-programs in a single source file. Thus the COBOL85 Debugger lets you browse, search and set breakpoints in all the PowerCOBOL source code for your sheet.
100
Expanded Code for Items, Methods and Attributes.

The COBOL85 Debugger displays expanded and changed versions of statements that contain references to items, methods and attributes. For example: The PowerCOBOL method call:
CALL CLOSESHEET OF CALL85.
appears as:
CALL "XPOWCSCLOSEMYSELF" USING BY VALUE CALL85.
in the COBOL85 Debugger. The PowerCOBOL statement referencing an attribute of an item:

MOVE POW-TEXT OF EDIT1 TO ID-INPUT
appears as:
CALL "XPOWEDITGETTEXT" USING BY VALUE EDIT1 BY REFERENCE POW-0001 MOVE POW-0001 TO ID-INPUT
in the COBOL85 Debugger. You handle the expanded statements like any other COBOL statements. You set breakpoints, and view and change data values as if the statements were your own.
101
Apparently Inactive Code

Debugging any event-based graphical system can appear strange at first if you normally work with procedural code. The debugger can become unresponsive and the application window at times does not refresh itself as you might expect. In both cases it is easy to be clicking on windows wondering why nothing is happening. There are two basic reasons for these behaviors: There are times when the debugger is waiting for an event to come from the application window. At these times only the "Break" button is enabled on the debugger toolbar. (16-bit: All the menu text is disabled.) The debugger has stopped the application running (e.g., when a breakpoint has been encountered). There is nothing active to receive and process events from the application window. So clicking on the application window has no apparent effect. (16-bit: The environment may allow actions in the user window when the code is stopped in the debugger, but these actions will likely cause protection violations.)
Once you understand why the behaviors are happening it is reasonably easy to cope with them. If the debugger is not responding, look at its toolbar. If only the "Break" button is enabled the debugger is waiting for an event in the application window. Either switch to the application window and take an appropriate action, or click the "Break" button that may abort the application. If the user window is not responding, switch to the debugger. The debugger has halted execution for one reason or another.
102
Check the reason, check your breakpoints and restart the execution using one of the Continue menu functions. Sometimes you want to see the application window at the same time as viewing the code. You do this by sizing and positioning the application and debug windows appropriately.
Using Run to Next Program

Because you are debugging at least two programs (PowerCOBOL and COBOL85), and often have many PowerCOBOL generated nested sub-programs, you may choose to use the Run to Next Program function (16-bit: the RUNTO ENTRY function). If you are at the top of the event loop on the EVALUATE POWER-MESSAGE statement, it may appear that nothing is happening. Every time you click on "Run to Next Program" you come back to the same point. This happens because the PowerCOBOL sheet is receiving several messages from the Windows system. The event loop processes each message. The COBOL85 Debugger sees the event loop relinquishing control through the EXIT PROGRAM statement and then regaining control when the next message arrives. It therefore appears to the COBOL85 Debugger that a new program is being executed. To get to the sub-program of interest you may need to click on "Run to Next Program" several times.
103
Keeping or Regaining Control

As with any debugging operation, the best way of keeping control is to set breakpoints at appropriate points in the code. If the code appears to be running and not hitting the breakpoints you have set, you can use the "Break" function. However, this can cause the application to abort so you have to restart the application. (16-bit: Put the focus on the debugger window and press ESC even though the window appears to be inactive. The next action in the user window causes the execution to be interrupted.)
104
SVD File Does Not Match Program to be Debugged

If you are experimenting with ways of building the mixed application code together you may encounter a message from the COBOL85 Debugger that says: Debugging information file FILENAME.svd does not match the program to be debugged. The debugging information is ignored. This can happen when you compile the COBOL85 code in Programming-STAFF and the rest of the system in PowerCOBOL (or vice versa). To correct this you may need to Build within PowerCOBOL or Rebuild within Programming-STAFF. Rebuild in Programming-STAFF forces a recompilation whereas Build does not. Another possibility is that somehow one of the systems has lost the compiler "TEST" directive or Compile for Debug option.
Chapter 5. Debugging Visual Basic calling COBOL

This chapter covers the details of debugging Visual Basic applications calling COBOL. Details covered are: How to prepare programs for debugging How to start the dual debugging process How to stop the dual debugging process Dos, and Donts
106
Chapter 5. Debugging Visual Basic Calling COBOL
Overview
Fujitsu COBOL programs are designed to work well with Visual Basic. The main consideration in debugging these mixed language applications is in bringing up the two debugging environments. The COBOL subprograms are prepared exactly as if they were to be called from other COBOL programs. Because the Visual Basic program will be calling COBOL, Visual Basic is brought up under the COBOL85 debugger. This ensures that calls from Visual Basic to COBOL can be intercepted by the COBOL85 debugger and the appropriate actions taken to let you see your COBOL source code. When you are debugging mixed Visual Basic and COBOL applications you have two complex environments active. To ensure that they interact correctly it is important you follow the start-up and close-down steps documented in this chapter.
107
Preparing Programs for Debugging with Visual Basic

COBOL programs that are called from Visual Basic are prepared in exactly the same way as COBOL programs that are called from other COBOL programs. The only special consideration in writing the programs is to ensure that data passed through the Linkage Section must be compatible with Visual Basic data types. Similarly preparing COBOL programs for debugging requires the same steps as if they were to be debugged in a totally COBOL environment.

Programs to be debugged must be compiled with the TEST directive.

Programs to be debugged must be linked with the linker options: /DEBUG /DEBUGTYPE:COFF.
Making Files Accessible to Visual Basic

When the Visual Basic program makes a call to COBOL it has to be able to find the COBOL code and supporting library routines. At the time the call is made the systems current folder is
108
determined by Visual Basic and is most likely the folder containing the Visual Basic start-up module. There are therefore three options for ensuring the COBOL programs and supporting files can be found when Visual Basic makes its call: 1. Put the COBOL files in a directory on the PATH. To update the path change the PATH statement in the AUTOEXEC.BAT file. 2. Make the code in the Visual Basic program specify a full path for the COBOL subprogram. 3. Put the COBOL files in the directory that will be the current directory at the time the call is made. (Not recommended as you will have a mix of COBOL application and Visual Basic system files.)
COBOL Run-Time Options

Fujitsu COBOL tailors its behavior at run-time by checking the settings of a number of environment variables and run-time options. These variables can be set in a variety of ways, documented in the User Guide. Before starting to debug make sure that you have specified all the environment variables you require. These settings should be placed in the initialization file (COBOL85.CBR) either by editing, or by using the Runtime Environment Setup dialog displayed when the COBOL runtime is started. Settings to consider include: Set @EnvSetWindow=UNUSE so that the Runtime Environment Setup dialog is not displayed when Visual Basic calls COBOL. File allocation mappings.
109
COBOL sub-program name to DLL file name mappings. Other environment settings specific to your application requirements.
110
Starting Debugging with COBOL and Visual Basic

To debug applications in which Visual Basic programs call COBOL programs, the COBOL85 debugger is started first. You tell the debugger where the COBOL source and debugging information is stored then, instead of loading a COBOL program into the debugger, you specify Visual Basic as the application. Within Visual Basic you execute or debug the VB programs as normal and when Calls to COBOL are executed the COBOL85 debugger gains control so that you can debug the COBOL programs. This process is detailed in the following instructions. 1. Once you have the COBOL programs compiled, linked and stored in a suitable directory, start the COBOL85 debugger. It can be started from within Programming Staff or from the Windows desktop.
111
The debugger displays a blank debug window.
112
2. Select File, Start Debugging from the menu. The Start Debugging dialog box is displayed.
113
3. Enter, or browse for, the location of the Visual Basic program - VB5.exe (or VB32.exe for version 4.0). See the note at the end of this section if the path contains spaces or single quotes.
114
4. Enter the name of the Visual Basic program you wish to start in the Execution-time-option edit box. Alternatively, you can leave this field blank and load the program after Visual Basic starts.
115
5. Click on the Source tab. Enter, or browse for, the name of the directory containing your COBOL source. If your programs use source libraries and subschemas also enter these directory names. See the note at the end of this section if any of the directory names contain spaces or single quotes.
116
6. Click on the Debugging Information tab. Enter, or browse for, the name of the directory containing the debug information for the COBOL programs. The debug information is stored in the directory specified in the TEST compiler option, or the directory containing the COBOL source if no directory is specified in the TEST option. See the note at the end of this section if the path contains spaces or single quotes.
7. You are now ready to start debugging. Click on OK to invoke Visual Basic.
117
8. In Visual Basic start executing or debugging your Visual Basic program. The snapshot below shows a simple Visual Basic program that calls a COBOL program called COBDLL.
10. Step through the Call to JMPCINT2 which initializes the COBOL run-time system. Typically this is executed once at the beginning of the VB application.
118
11. Step into the Call to the COBOL program. On the first Call, it will appear that nothing is happening. You need to switch to the COBOL85 debugger window (this is titled VB5.exe - COBOL85 Debugger). On subsequent Calls to COBOL the COBOL85 debugger window is displayed automatically. The Called source is displayed.
Note: Sometimes a tool tip from the Visual Basic debug toolbar may remain visible on top of the COBOL85 debugger window. It does not affect the execution of the COBOL code or debugger.
119
12. Debug the COBOL code as normal. Note: a) The accelerator key for Step Into is F8 in both Visual Basic and the COBOL85 debugger. b) Remember to set breakpoints in the COBOL program before a Go or Run command as you may not be able to regain control in the COBOL source. 13. When you execute an EXIT PROGRAM statement in the top level COBOL program, control is returned to Visual Basic. 14. Continue debugging in Visual Basic and COBOL until you are ready to stop. Be sure to follow the instructions in the section Stopping Debugging with COBOL and Visual Basic when stopping debugging. Note: On directory names containing spaces or single quotes. In the current release of Fujitsu COBOL, the debugger Start Debugging dialog does not accept paths that contain spaces or single quotes. Both these characters are legal characters in Windows 95 and Windows NT . If you have these characters in your path names you need to substitute the MS-DOS name. To determine what the MS-DOS name is, right click on the directory when listed in the Browse window, and select Properties from the pop-up window. The MS-DOS name is one of the properties displayed. Type the MS-DOS name in place of the directory name(s) containing space(s) or single quote(s). (See the snapshot under step 4 above). The COBOL85 debugger remembers the details for the most recently executed applications so you do not have to re-enter the MS-DOS names every time you debug the application.
120
Stopping Debugging with COBOL and Visual Basic

It is important that the Visual Basic and COBOL debugging environments are closed down in the correct order. Failure to do so can result in one or both systems hanging. Close down the debugging in the following order: 1. If you are not already there, return to the Visual Basic environment by executing an EXIT PROGRAM statement in the COBOL program. 2. Step through or execute a Call to JMPCINT3. This tells the COBOL runtime to tidy up and close down. 3. Stop debugging or executing in Visual Basic. 4. Close Visual Basic. 5. Either Close the COBOL85 debugger, or start another debug session. To start another debug session use one of the following: - Select Continue, Re-debug. - Select File, Start Debugging - Select File, and a previously debugged program.
121
Dos and Donts in the Dual Debugging Environment

Do specify Application, Source and Debugging Information directories. Control may be transferred from one debugging system to the other at points where the current directory has changed. To be sure the COBOL system can find the files it requires these directories must be entered in the Start Debugging dialog box. Do set breakpoints in code before running. You may find it difficult to break into the COBOL or Visual Basic code if you run the code without first setting breakpoints at suitable points. Do close down in the proper order. Failure to close down in the proper order can cause either or both debugging systems to hang. Do NOT press Cancel in the Run-time Environment Setup window! It is best to ensure that the Run-time Environment Setup window is not displayed by putting the following setting in the COBOL initialization file:
@EnvSetWindow=UNUSE
If the window is displayed do not click the Cancel button. This tells the COBOL run-time not to execute the program but Visual Basic and the COBOL system expect the program to be executed.
122
Do NOT close down in an improper order! Failure to close down in the proper order can cause either or both debugging systems to hang.
Chapter 6. COBOL Trace and Check Functions

This chapter describes how to use the COBOL85 debugging functions of TRACE and CHECK. These functions are not currently supported in Windows 95 and Windows NT.
124
Outline of the Debugging Function

Two types of debugging functions are available for COBOL85: Tracing executed COBOL statements (TRACE function) Checking the referencing of an incorrect area (CHECK function)
To use the debugging function, specify the compiler option of each debugging function at compilation of the COBOL program, and specify the environment to operate the debugging function at execution of the program. Table 6 outlines the debugging functions and compiler options.
Table 6. Outline of the debugging functions and compiler options Function Name TRACE function Outline The following types of information are outputted: - Tracing result of executed statements - Line number and verb number of the statement that was executed at abnormal termination - Program name that contains the statements that were executed and program attribute information - Message output during execution [Purpose] - To ascertain at which statement abnormal termination occurred - To ascertain the path of the statements that were executed up to abnormal termination - To check the message output during execution Compiler Option TRACE
125
Table 7. Outline of the debugging functions and compiler options (cont.) Function Name CHECK function Outline The following items are checked. - Whether the subscript or index addresses an area outside of the range of a table when that table is referenced - Whether the reference position exceeds the data length at reference modification - Whether the contents of the target word are correct when the data containing the OCCURS DEPENDING ON clause is referenced [Purpose] - To prevent an operation error of the program due to a memory reference error Compiler Option CHECK
Statement Number
A statement number described in the subsequent explanation indicates the following expression:
line-number[verb-sequence-number-in-line-number]
LINE-NUMBER When compiler option NUMBER is valid, the format is "[COPYqualification-value-]user-line-number" and when NONUMBER is valid, the format is "[COPY-qualification-value-]sequencenumber-in-file." The sequence number in file is the value assigned in ascending order by the compiler in the unit of 1 starting from "1" as the first line in the file.
126
VERB-SEQUENCE-NUMBER-IN-LINE-NUMBER These are sequence numbers used to make each statement unique when multiple statements are entered at the same line number. Numbers are allocated in ascending order starting from 1 for the first statement and, 2, 3 ... subsequently. When a procedure-name is entered, a verb sequence number in the line number is omitted.
Using the TRACE Function

The TRACE function outputs trace information of the COBOL statements that have been executed up to program abnormal termination to a file. With the output trace information, the statement that caused abnormal termination and the process up to abnormal termination can be ascertained. This section describes how to use the TRACE function.
Flow of Debugging
The following section shows the flow of debugging operation when using the TRACE function:
127
Figure 24. Flow of debugging control
Trace Information
The TRACE function writes statement numbers of the COBOL statements that were executed up to abnormal termination as trace information.
Number of Trace Information Items

When compiler option TRACE is specified without specifying the number of information items at compile time, up to 200 trace information items are produced. When compiler option TRACE is specified with the number of information items, up to the number of trace information items specified are written.
128
The number of trace information items can be changed with execution time option r at execution time.
Trace Information Storage Destination

Trace information is stored in the file having the name of the executable program storage file, with the extensions TRC and TRO. The examples are shown below. Executable program storage destination: C:\PROG1.EXE Trace information storage destination (current information): C:\PROG1.TRC Trace information storage destination (information on the previous generation): C:\PROG1.TRO
Trace information is always stored in the file with extension TRC. When the number of information items stored reaches the number specified at compile time or execution time, the contents of the file with extension TRC are transferred to the file with extension TRO.
Output Format of Trace Information

The output format of trace information is shown below.
COBOL85 DEBUG INFORMATION DATE 95-04-14 TIME 11:39:22 TRACE INFORMATION (1) (2) (3) (4) 1 External-program-name [Internal-program-name] Compilation-date 2 1100.1 (5) 3 1200.1 4 1300.1 5 1300.2 6 JMPnnnnI-x xxxxxxxxx xx xxxxxxxxx. (6) :
(1) Trace information sequence number (10 digits): The value is incremented whenever trace information output is displayed. Since trace information is overwritten to two files alternately,
129
this value indicates the sequence number of the information from the start of the program. (2) External program name: An external program name is output. (3) Internal program name: The name is the output when an internal program operates. This information is not displayed for external programs. (4) Compilation date: When an external program operates, the compilation date and time of the program are output. (5) Statement or procedure-name/paragraph-name that was executed: The statement number of the statement, procedure name, or paragraph name that was executed is the output. (6) Execution time message: The output message from a runtime system during program execution.
Notes
Trace information can be collected only for COBOL programs compiled with compiler option TRACE specified.
130
Figure 25. Collecting TRACE information
The TRACE function performs processing other than the processing described in the COBOL program such as collection of trace information. Therefore, the program size increases and the execution speed deteriorates when the TRACE function is used. Use the TRACE function during debugging only. When debugging is completed, recompile the program with compiler option NOTRACE specified. The number of trace information items cannot be set to 0. When the TRACE function is valid, trace information is generated regardless of whether the program terminated normally or abnormally. When a program is executed again while a trace information file exists, the contents of the original trace information file will be lost. When a trace information file is no longer needed, delete the file.
131
Using the CHECK Function

The CHECK function checks subscripts, indexes, and reference modification. If the function detects an abnormality, it writes a message and terminates abnormally. Therefore, program operation errors can be prevented. This section describes how to use the CHECK function.
Flow of Debugging
The following section shows the flow of debugging operation when using the CHECK function.
Figure 26. Flow of debugging with CHECK function
132
Output Message
When detecting an abnormality in subscripts, indexes, or reference modification, the CHECK function produces a message. Normally, this message is written to a message box. The severity code of the message produced by the CHECK function is level E, however, when the number of messages reaches the specified count, a level U message is written. For severity codes, see Appendix F.
Message Contents
Checking Subscripts and Indexes
JMP0820I-E/U SUBSCRIPT/INDEX IS OUT OF RANGE. PGM=$1. LINE=$2. OPD=$3 ($4) PGM=program-name. LINE=statement number. OPD=dataname(dimension of data-name). [Response]Specify a correct value for the subscript or index indicated in the message, then re-execute.
Checking Reference Modification

JMP0821I-E/U REFERENCE MODIFIER IS OUT OF RANGE. PGM=$1. LINE=$2. OPD=$3. PGM=program-name. LINE=statement number. OPD=dataname. [Response]Correct the program so that reference modification of
133
the data item indicated in the message is performed within the specified range.
Checking a Target Word of the OCCURS DEPENDING ON Clause

JMP0822I-E/U ODO OBJECT VALUE IS OUT OF RANGE. PGM=$1. LINE=$2. OPD=$3. ODO=$4. PGM=program-name. LINE=statement number. OPD=dataname. ODO=name of target word of ODO clause [Response]Specify a correct value for the object (in the OCCURS DEPENDING ON clause) indicated in the message, then reexecute.
Message Output Count

Specify a message count in compiler option CHECK at compile time. The message count can be changed at execution time by using execution time option c. The CHECK function can also be suppressed by specifying execution time option noc. Program execution is continued until the message count reaches the specified count.
134
Examples of Using the CHECK Function

Checking Reference Modification
Program A : 000500 77 data-1 PIC X(12). 000600 77 data-2 PIC X(12). 000700 77 length-to-be-referenced PIC 9(4) BINARY. : 001100 MOVE 10 TO length-to-be-referenced. 001200 MOVE data-1 (1:length-to-be-referenced) TO data-2 (4:length-to-be-referenced). :
The following message is written for data 2: JMP0821I-E/U REFERENCE MODIFIER IS OUT OF RANGE. PGM=A. LINE=1200.1. OPD=data-2.
Checking Subscripts and Indexes

Program A : 000500 77 subscript PIC S9(4). 000600 01 dtable. 000700 02 table-1 OCCURS 10 TIMES INDEXED BY index-1. 000800 03 element-1 PIC X(5). : 001100 MOVE 15 TO subscript. 001200 ADD 1 TO element-1(subscript). 001300 SET index-1 TO 0. 001400 SUBTRACT 1 FROM element-1(index-1). :
When the ADD/SUBTRACT statement is executed, the following message is written: JMP0820I-E/U SUBSCRIPT/INDEX IS OUT OF RANGE. PGM=A. LINE=1200.1. OPD=element-1
135
JMP0820I-E/U SUBSCRIPT/INDEX IS OUT OF RANGE. PGM=A. LINE=1400.1. OPD=element-1
Checking Target Words of the OCCURS DEPENDING ON Clause

Program A : 77 subscript PIC S9(4). 77 cnt PIC S9(4). 01 dtable. 02 table-1 OCCURS 1 TO 10 TIMES DEPENDING ON cnt. 03 element-1 PIC X(5). : MOVE 5 TO subscript. MOVE 25 TO cnt. MOVE "ABCDE" TO element-1(subscript). :
000050 000060 000070 000080 000090 000110 000120 000130
The following message is written for the count: JMP0822I-E/U ODO OBJECT VALUE IS OUT OF RANGE. PGM=A. LINE=120.1. OPD=element-1. ODO=cnt.
Notes
Execution can be continued after an abnormality is detected by specifying a message output count, however, operation after detection of an abnormality cannot be guaranteed. The CHECK function performs processing other than the processing described in the COBOL program such as checking data. Therefore, the program size increases and execution speed deteriorates when the CHECK function is used. Use the CHECK function during debugging only. When debugging is completed, recompile the program with compiler option NOCHECK specified.
136
Appendix A. Debugger Command Lists

This appendix lists the debugger commands. Debugger commands differ slightly between Windows 3.1 and Windows 95/NT. See the debugger command table for each system. For details on the command specification format, refer to the help information of the system. For Windows 3.1: Refer to Table 8. For Windows 95 and Windows NT : Refer to Table 9
Table 8. Debugger command lists (16) Command Name AUTORUN BREAK CALLS CONTINUE COUNT DATACHK DELCOUNT DELDCHK DELDTR DELETE DELMON DTRACE ENV LINKAGE LIST LSEARCH MONITOR PRINT PROG RERUN Function Debugs automatically. Sets a breakpoint. Displays the calling path. Resumes execution. Sets a passage count point. Monitors satisfaction of a conditional expression. Cancels a passage count point. Cancels monitoring satisfaction of a conditional expression. Cancels monitoring changes in data item contents. Cancels a breakpoint. Cancels monitoring for changes in a data item. Monitors change in data item contents. (No interruption at change) Sets up and changes the debug environment. Acquires a data area in the linkage section. References data area contents. Changes display location of a source program. Monitors changes in data item contents. (Interruption at change) Prints data area contents. Changes source program displayed. Re-debug.
138
Appendix A. Debugger Command Lists
Table 8. Debugger command lists (16) (cont.) Command Name RUNTO SCOPE SEARCH SET SKIP STATUS QUIT WHERE Function Executes with a breakpoint specification. Changes program qualification. Searches for a character string. Changes data area contents. Changes the current execution position. Displays debug status. Ends debugging. Displays the current execution position. Table 9. Debugger command lists (32) Command Name AUTORUN BREAK CALLS CONTINUE COUNT DATACHK DELCOUNT DELDCHK DELDTR DELETE DELMON DTRACE ENV LINKAGE LIST MONITOR RERUN RUNTO SCOPE SET SKIP STATUS QUIT WHERE Function Debugs automatically. Sets a breakpoint. Displays the calling path. Resumes execution. Sets a passage count point. Monitors satisfaction of a conditional expression. Cancels a passage count point. Cancels monitoring satisfaction of a conditional expression. Cancels monitoring changes in data item contents. Cancels a breakpoint. Cancels monitoring for changes in a data item. Monitors change in data item contents. (No interruption at change) Sets up and changes the debug environment. Acquires a data area in the linkage section. References data area contents. Monitors changes in data item contents. (Interruption at change) Re-debug. Executes with a breakpoint specification. Changes program qualification. Changes data area contents. Changes the current execution position. Displays debug status. Ends debugging Displays the current execution position.
Index
A
allocating linkage items (16-bit), 72 allocating linkage items (32-bit), 35 arithmetic expressions (16-bit), 88 assignment expression (16-bit), 87 automatic debugging (16-bit), 73 automatic debugging (32-bit), 37 data trace window, 61 functions, 63 functions, using, 66 item status, 76 main window, 58 menu commands, 63 operands, common, 79 operating environment file, 57 overview, 44 procedures, 46 SCOPE, subcommand, 81 screens, 58 specifying start parameters, 50 starting, 49, 50 starting with options set, 55 subcommands, 77 debugger (32-bit) accelerator keys, 22 configuring colors, 40 configuring fonts, 40 data watch window, 26 debugging procedure, 11 functions, using, 28 item status, 40 limitations, 41 line command window, 22, 26 linking, 13 main window, 21 menu commands, 22 overview, 10 pop-up menu, 22 program list window, 25 specifying start-parameters, 15 splitting source window, 39 starting, 14 starting with options set, 18 status bar, 27 tool bar buttons, 22 debugging flow of, when using TRACE function, 126
B
batch debugging mode (16-bit), 73 batch debugging mode (32-bit), 37 Break (16-bit), 44 Break (32-bit), 34
C
CHECK function, 124 flow of debugging when using, 131 message, 132 message contents, 132 using, 131 COBOL Run-Time Options, 95, 108 command file (16-bit), 74 command file (32-bit), 37 command line starting 16-bit debugger, 55 starting 32-bit debugger, 18 conditional expressions (16-bit), 87 condition-name (16-bit), 85
D
data trace window (16-bit), 61 data watch window (32-bit), 26 DEBUG linker option, 13 debugger (16-bit), 43 additional features, 44
140
Index
debugging (16-bit) allocating linkage items, 72 automating, 73 batch, 73 breaking execution when data changes, 69 changing environment, 75 changing statement execution sequence, 68 checking data modification locations, 69 information file, 47, 48 PowerCOBOL and COBOL85, 94 required information prior to, 50 restarting, 73 setting breakpoints, 60 target programs, 47 testing programs using functions specific to the GS-Series, 76 tracing the execution path, 70 debugging (32-bit) allocating linkage items, 35 automating, 37 batch, 37 breaking execution when data changes, 30 breaking into an executing program, 34 changing data contents, 29 changing environment, 38 changing statement execution sequence, 31 checking data contents, 29 checking data modification locations, 30 information file, 12 PowerCOBOL and COBOL85, 94 preparing programs, 12 required information prior to, 15 restarting, 36 target programs, 12 tracing the execution path, 32 tracing the program CALL path, 33 debugging function using, 124 debugging functions, 124 DEBUGTYPE linker option, 13
I
identifier (16-bit) coding format, 85 types, 84 index-name, 85 information file, 12, 47 interactive debugger, 9
K
keyword operand, 77
L
line command window (16-bit), 62 line command window (32-bit), 26 line-number, 125 link options /CO (16-bit), 48 /DEBUG (32-bit), 13 /DEBUGTYPE (32-bit), 13 linkage section, allocating (16-bit), 72 linkage section, allocating (32-bit), 35 literal, 86
M
message count, 133 message output count, 135 monitoring data (16-bit), 69 monitoring data (32-bit), 30
N
NONUMBER, 125 NUMBER, 125
O
operands, 77
E
expressions (16-bit), 86
Index
141
P
passage counts (16-bit), 65, 137 passage counts (32-bit), 36 positional operand, 77 PowerCOBOL, 93 program name, operand, 79 program qualification search range, 81 program qualification, subcommand, 81
start parameters (32-bit), 19 statement identification number, 82 statement number, 125 subcommand coding format, 77 SVD file, 16, 104 symbolic-constant, 86 syntax notation, subcommand, 78
S
sequence number, 125 source window splitting, 39 special register, 86 splitting source window, 39 Start Debugging dialog box (32-bit), 15 Start Parameter dialog box (16-bit), 50 start parameters (16-bit) command line, 51 debug information, 53 environment, 54 FORM Extension, 52 FORM files, 53 libraries, 53 log file, 52 source text, 52 start program name, 51 subschema files, 54
T
TEST option, 12, 47 TRACE function, 124 using, 126 trace information, 127 collecting, 129 output format, 128 storing, 128 trace information items, 127
V
verb-sequence-number-in-line-number, 126 Visual Basic, debugging with, 105 Visual C++, debugging with, 13
W
WINSVD, 14, 49

Fujitsu COBOL Debugging Guide: Microsoft Windows Microsoft Windows 95 Microsoft Windows NT

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Fujitsu COBOL Debugging Guide: Microsoft Windows Microsoft Windows 95 Microsoft Windows NT

Transféré par

Droits d'auteur :

Formats disponibles

Microsoft Windows Microsoft Windows 95 Microsoft Windows NT

Fujitsu COBOL Debugging Guide

Fujitsu COBOL Debugging Guide

How this Manual is Organized

Fujitsu COBOL Debugging Guide

How to Use This Manual

Fujitsu COBOL Debugging Guide

Conventions Used in this Manual

Fujitsu COBOL Debugging Guide

Fujitsu COBOL Debugging Guide

Fujitsu COBOL Debugging Guide

Fujitsu COBOL Debugging Guide

Fujitsu COBOL Debugging Guide

Fujitsu COBOL Debugging Guide

Fujitsu COBOL Debugging Guide

Fujitsu COBOL Debugging Guide

Chapter 1. Introduction to Debugging with Fujitsu COBOL.

Chapter 1. Introduction to Debugging with Fujitsu COBOL.

Debugging with Fujitsu COBOL

Chapter 1. Introduction to Debugging with Fujitsu COBOL.

Features of the Debugger for Windows 95 and NT

Chapter 1. Introduction to Debugging with Fujitsu COBOL.

Chapter 1. Introduction to Debugging with Fujitsu COBOL.

Features of the Debugger for Windows 3.x

Chapter 1. Introduction to Debugging with Fujitsu COBOL.

Chapter 1. Introduction to Debugging with Fujitsu COBOL.

Features of the COBOL Debugging Functions

Chapter 1. Introduction to Debugging with Fujitsu COBOL.

Chapter 2. Debugging in Windows 95 and Windows NT

Chapter 2. Debugging in Windows 95 and Windows NT

Overview of the Debugger

Chapter 2. Debugging in Windows 95 and Windows NT

Preparing Programs for Debugging

Figure 1: Overview of the debugging procedure

Chapter 2. Debugging in Windows 95 and Windows NT

Debug Program Types

Figure 2: Debugging programs with and without TEST

Compiling for Debugging

Chapter 2. Debugging in Windows 95 and Windows NT

Linking for Debugging

Chapter 2. Debugging in Windows 95 and Windows NT

Starting the Debugger

Invoking the Debugger

Chapter 2. Debugging in Windows 95 and Windows NT

Starting to Debug a Program

Figure 3: The Start Debugging Dialog Box

Chapter 2. Debugging in Windows 95 and Windows NT

Chapter 2. Debugging in Windows 95 and Windows NT

Details of the Start Debugging Dialog Box Options

Chapter 2. Debugging in Windows 95 and Windows NT

Specifying Options on the Command Line

Chapter 2. Debugging in Windows 95 and Windows NT

Chapter 2. Debugging in Windows 95 and Windows NT

the command line would be:

Chapter 2. Debugging in Windows 95 and Windows NT

Overview of the Debugger Windows

Figure 4: Debugger Main Window

Chapter 2. Debugging in Windows 95 and Windows NT

Chapter 2. Debugging in Windows 95 and Windows NT

Source File Window

Figure 5: A Split Source File Window

Chapter 2. Debugging in Windows 95 and Windows NT