This section provides an introduction to using the OpenVMS debugger with Compaq COBOL programs. It includes the following:

• A description of OpenVMS debugger support for Compaq COBOL
• A note about using both the /DEBUG qualifier and the /NOOPTIMIZE (Alpha only) qualifier when you compile images for debugging
• A sample debugging session that demonstrates using the debugger

For complete reference information on the OpenVMS debugger, refer to the OpenVMS Debugger Manual in the OpenVMS documentation set. Online help is immediately available to you during a debugging session when you type the HELP command at the debugger prompt (DBG>).

C.3.1 Notes on Compaq COBOL Support

In general, the OpenVMS debugger supports the data types and operators of Compaq COBOL and other debugger-supported languages. However, there are important language-specific limitations. (To get information about the supported data types and operators for a language, type the HELP LANGUAGE command at the DBG> prompt.)

The debugger shows source text included in a program with the COBOL COPY file statement or the COPY module of library statement. However, the debugger does not show text which was created with the COPY REPLACING or REPLACE statement, or included by the COPY text FROM DICTIONARY statement.

The debugger cannot show the original source lines associated with the code for a REPORT section. You can see the DATA SECTION source lines associated with a report, but no source lines are associated with the compiled code that generates the report.

C.3.2 Notes on Debugging Optimized Programs (Alpha)

The Compaq COBOL compiler is a highly optimizing compiler. Several of the optimizations it performs, such as instruction scheduling and label deletion, can cause unexpected behavior in the OpenVMS Debugger.

Instruction scheduling can make the debugger appear to execute statements out of order. A single COBOL source statement can often result in several machine instructions. A RISC architecture machine, like the Alpha processor, can start working on a new instruction every machine cycle, but not all instructions can complete within one machine cycle. If the output from one machine instruction is used as the input to a subsequent machine instruction, the machine cannot begin processing the second instruction until it has finished processing the first. In many cases an entirely separate instruction can execute in parallel with the first instruction to perform a related computation.

During instruction scheduling, instructions are reordered to minimize waiting time. As a result an instruction resulting from a subsequent COBOL statement can be scheduled in the middle of (or even before) a sequence of instructions from a preceding statement. This reordering NEVER changes the meaning of your program, but it can make your program's execution in the debugger seem incorrect. The most common symptom of instruction scheduling is that the pointer in the debugger source window jumps back and forth between lines when you use the debugger STEP command.

When the compiler performs label deletion, it deletes paragraph and section labels that you do not explicitly reference in your source program. This prevents you from setting breakpoints on the affected labels which can make the analysis and optimization of your program more difficult.

Because of these and other Compaq COBOL compiler optimizations, Compaq recommends that you use the /NOOPTIMIZE qualifier in conjunction with the /DEBUG qualifier when you are debugging your COBOL programs. Using /NOOPTIMIZE qualifier disables most of the Compaq COBOL optimizations. In particular it suppresses most instruction scheduling and all label deletion optimizations.

C.3.3 Sample Debugging Session (Alpha)

The following OpenVMS Alpha debugging session does not show the location of program errors; it is designed to show only the use of debugger features.

1. The following example shows how to compile and link a Compaq COBOL program consisting of a single compilation unit named TESTA.

   $ COBOL/DEBUG/NOOPTIMIZE TESTA $ LINK/DEBUG TESTA

   
   The /DEBUG qualifier on the COBOL command causes the compiler to write the debug symbol records associated with TESTA into the object module, TESTA.OBJ. These records allow you to use the names of variables and other symbols declared in TESTA in debugger commands. (If your program has several compilation units, you must compile each unit that you want to debug with the /DEBUG qualifier.)
   For Alpha, the /NOOPTIMIZE qualifier on the COBOL command disables default optimization for debugging. Because Compaq COBOL is, by default, a highly optimizing compiler, you will notice unusual and confusing program execution when you step through an optimized program with the debugger.
   The /DEBUG qualifier on the LINK command causes the linker to include all symbol information that is contained in TESTA.OBJ in the executable image. The qualifier also causes the image activator to start the debugger at run time. (If your program has several object modules, you might need to specify other modules in the LINK command.)

2. The RUN command starts the session. If you compile and link the program with /DEBUG, you do not need to use the /DEBUG qualifier in the RUN command.
   When you give the RUN command, the debugger displays its standard header, showing that the default language is COBOL and the default scope and module are your main program. The debugger returns control with the prompt, DBG>.

   $ RUN TESTA OpenVMS Alpha DEBUG Version V7.1-000 %DEBUG-I-INITIAL, Language: COBOL, Module: TESTA %DEBUG-I-NOTATMAIN, type GO to get reach MAIN program DBG>

3. Use the GO command to get to the start of the main program.

   DBG> GO break at routine TESTA 11: DISPLAY "ENTER WORD"

4. Set a breakpoint.

   DBG> SET BREAK %LINE 43

5. Begin execution with the GO command. The debugger displays the execution starting point, and the image continues until TESTA displays its prompt and waits for a response.

   DBG> GO ENTER WORD:

6. Enter the word to be reversed. Execution continues until the image reaches the breakpoint at line 43 of the contained program.

   abc break at TESTA\TESTB\%LINE 43 43: PERFORM LOOK-BACK VARYING SUB-1 FROM 20 BY -1

7. Set two breakpoints. When the debugger reaches line 50 of TESTB, it executes the commands in parentheses, displays the two data items, and resumes execution.

   DBG> SET BREAK %LINE 47 DBG> SET BREAK %LINE 50 DO (EXAMINE HOLD-CHARS;EXAMINE SUB-1;GO)

8. Display the active breakpoints.

   DBG> SHOW BREAK breakpoint at TESTA\TESTB\%LINE 43 breakpoint at TESTA\TESTB\%LINE 47 breakpoint at TESTA\TESTB\%LINE 50 do (EXAMINE HOLD-CHARS;EXAMINE SUB-1;GO)

9. Use the TYPE command to display the source lines where you set breakpoints.

   DBG> TYPE 43:50 module TESTA 43: PERFORM LOOK-BACK VARYING SUB-1 FROM 20 BY -1 44: UNTIL TEMP_CHAR (SUB-1) NOT = SPACE. 45: MOVE SUB-1 TO CHARCT. 46: PERFORM MOVE-IT VARYING SUB-2 FROM 1 BY 1 UNTIL SUB-1 = 0. 47: MOVE HOLD-WORD TO TEMP-WORD. 48: MOVE-IT. 49: MOVE TEMP-CHAR (SUB-1) TO HOLD-CHAR (SUB-2). 50: SUBTRACT 1 FROM SUB-1.

10. Set a tracepoint at line 15 of TESTA.

    DBG> SET TRACE %LINE 15

11. Set a watchpoint on the data item DISP-COUNT. When an instruction tries to change the contents of DISP-COUNT, the debugger returns control to you.

    DBG> SET WATCH DISP-COUNT DEBUG-I-WPTTRACE, non-static watchpoint, tracing every instruction

12. Execution resumes with the GO command. Before line 50 in TESTB executes, the debugger executes the contents of the DO command entered at step 7. It displays the contents of HOLD-CHARS and SUB-1, then resumes execution.

    DBG> GO break at TESTA\TESTB\%LINE 50 50: SUBTRACT 1 FROM SUB-1. TESTA\TESTB\HOLD-CHARS: CHARS: "c " TESTA\TESTB\SUB-1: 3 break at TESTA\TESTB\%LINE 50 50: SUBTRACT 1 FROM SUB-1. TESTA\TESTB\HOLD-CHARS CHARS: "cb " TESTA\TESTB\SUB-1: 2 break at TESTA\TESTB\%LINE 50 50: SUBTRACT 1 FROM SUB-1. TESTA\TESTB\HOLD-CHARS CHARS: "cba " TESTA\TESTB\SUB-1: 1 break at TESTA\TESTB\%LINE 47 47: MOVE HOLD-WORD TO TEMP-WORD. DBG>

13. Examine the contents of SUB-1.

    DBG> EXAMINE SUB-1 TESTA\TESTB\SUB-1: 0

14. Deposit the value --42 into data item SUB-2.

    DBG> DEPOSIT SUB-2 = -42

15. Examine the contents of SUB-2.

    DBG> EXAMINE SUB-2 TESTA\TESTB\SUB-2: -42

16. Examine the contents of CHARCT, whose picture is 99V99.

    DBG> EXAMINE CHARCT TESTA\TESTB\CHARCT: 3.00

17. Deposit four characters into CHARCT.

    DBG> DEPOSIT CHARCT=15.95

18. CHARCT now contains 15.95.

    DBG> EXAMINE CHARCT TESTA\TESTB\CHARCT: 15.95

19. Deposit an integer larger than CHARCT's definition. The debugger returns an error message.

    DBG> DEPOSIT CHARCT=2890 %DEBUG-E-DECOVF, decimal overflow at or near DEPOSIT

20. Examine the contents of CHARCT.

    DBG> EXAMINE CHARCT TESTA\TESTB\CHARCT: 15.95

21. You can examine any character of a subscripted data item by specifying the character position. The following EXAMINE command accesses the second character on TEMP-CHAR.

    DBG> EXAMINE TEMP-CHAR(2) TEMP-CHAR of TESTA\TESTB\TEMP-WORD(2): "b"

22. You can use the DEPOSIT command to put a value into any element of a table and examine its contents. In this example, "x" is deposited into the second character position of TEMP-CHAR.

    DBG> DEPOSIT TEMP-CHAR(2)="x" DBG> EXAMINE TEMP-CHAR(2) TEMP-CHAR of TESTA\TESTB\TEMP-WORD(2): "x"

23. You can qualify data names in debug commands as you can in COBOL. For example, if you examine IN-WORD while you debug your program, you can use the following DEBUG command:

    DBG> EXAMINE IN-WORD of TESTA-DATA IN-WORD OF TESTA\TESTA-DATA: "axc"

24. Deposit a value into CHARCT.

    DBG> DEPOSIT CHARCT=8.00

25. Resume execution with the GO command. The program TESTA displays the reversed word. When the image reaches line 19 in TESTA, the debugger detects that an instruction changed the contents of DISP-COUNT. Because you set a watchpoint on DISP-COUNT, the debugger displays the old and new values, then returns control to you.

    DBG> GO cba trace at TESTA\%LINE 15 15: PERFORM SHOW-IT. watch of DISP-COUNT of TESTA\TESTA-DATA at TESTA\%LINE 19+52 19: MOVE LET-CNT TO DISP-COUNT. old value = 0 new value = 3 break at TEST-A\%LINE 20 20: DISPLAY DISP-COUNT " CHARACTERS".

26. To see the image's current location, use the SHOW CALLS command.

    DBG> SHOW CALLS module name routine name line rel PC abs PC *TESTA TESTA 22 00000120 00030120 00000080 000306C0 LIB$INITIALIZE 85739D00 8576A530 00000080 7FE61F30

27. Resume execution with the GO command. TESTA executes its final display. The debugger regains control when STOP RUN executes.

    DBG> GO 03 CHARACTERS %DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion'

28. At this point, you can either examine the contents of data items or end the session with the EXIT command.

    DBG> EXIT $ <>

When you debug a Compaq COBOL program, the default module (which will be brought into the debugger) is the main module name. If your program consists of multiple separately compiled programs (SCPs), and was compiled with the /SEPARATE_COMPILATION qualifier (see Section 1.2.2.4 and Section B.4.2.8), each module that you wish to debug other than the main module must be identified to the debugger.

For example:

DBG> SET BREAK %LINE 43

In the previous example, the default module is the main module name. You can specify a different module in those cases where you use multiple separately compiled programs as follows:

DBG> SET BREAK modulename \ %LINE 43

In the preceding example, the default debug module becomes modulename. The same result can be obtained by using SET MODULE, as follows:

DBG> SET MODULE modulename DBG> SET BREAK %LINE 43

If modulename is a valid module, the default will be set to that module name and the debugger prompt will be returned. You can then set a breakpoint (or any other valid debugger action) in the new module source. If it is not a valid module, the system will advise you as follows:

DBG> SET MODULE invalidmodulename %DEBUG-E-NOSUCHMODU, module INVALIDMODULENAME is not in module chain

C.4 Language-Sensitive Editor (LSE) and the Source Code Analyzer (SCA) (OpenVMS)

The Language-Sensitive Editor (LSE) is a powerful and flexible text editor designed specifically for software development. The Source Code Analyzer (SCA) is an interactive tool for program analysis.

These products are closely integrated; generally, you can invoke SCA through LSE. LSE provides additional editing features that make SCA program analysis more efficient. In conjunction with the Compaq COBOL compiler, the two tools provide a set of new enhancements supporting source code design and review.

LSE also provides the following software development features:

• Formatted language constructs, or templates, for the programming languages it supports, including Compaq COBOL. These templates include the keywords and punctuation used in source programs.
• Commands to compile, review, and correct compilation errors from within the editor. The Compaq COBOL compiler for Alpha issues some diagnostics in a different sequence from Compaq COBOL for OpenVMS VAX. The LSE review of compilation errors reflects the sequence in which the particular compiler issues the diagnostics.
• Integration with Code Management System (CMS). You can issue CMS commands from within the editor to make source file management more efficient. Refer to the Guide to Code Management System for VMS Systems for more information.

SCA performs the following types of program analysis:

• Cross-referencing, which supplies information about program symbols and source files
• Static analysis, which provides information on how subprograms, symbols, and files are related

LSE and SCA together, in conjunction with compilers for supported languages, provide the following software design features:

• View support, which provides a reverse-design facility. LSE commands compress program code into overview line summaries. If you choose to edit these overview lines, the program code reflects the modifications you make.
• A report tool, callable through LSE, which can print views, standard design reports, and customized reports.

Compaq COBOL supports the LSE and SCA program creation, analysis, and compilation features described in the preceding sections. Compaq COBOL on OpenVMS Alpha does not support the LSE Program Design Facility (PDF) design comments, pseudocode placeholders, or the /DESIGN qualifier.

The following sections provide entry, exit, and language-specific information on the combined use of LSE and SCA.

For More Information:

• On LSE--Refer to the Guide to Language-Sensitive Editor.
• On SCA--Refer to the Guide to Source Code Analyzer for VMS Systems.
• On CMS--Refer to the Guide to Code Management System for VMS Systems.

SCA stores data generated by the Compaq COBOL compiler in an SCA library. The data in an SCA library contains information about all symbols, modules, and files encountered during a specific compilation of the source. You must prepare this library before you enter LSE to invoke SCA by following these steps:

1. Create a directory for your SCA library. For example:

   $ CREATE/DIRECTORY PROJ:[USER.LIB1]

2. Initialize and set the library with the SCA CREATE LIBRARY command. For example:

   $ SCA CREATE LIBRARY [.LIB1]

   
   If you have an existing SCA library that has been initialized, you make its contents visible to SCA by setting it with the SCA SET LIBRARY command. For example:

   $ SCA SET LIBRARY [.EXISTING_SCA_LIBARAY]

   
   A message appears in the message buffer at the bottom of your screen, indicating whether or not your SCA library selection succeeded.

3. Direct the COBOL compiler to generate data analysis files by appending the /ANALYSIS_DATA qualifier to the COBOL command. For example:

   $ COBOL/ANALYSIS_DATA PG1,PG2,PG3

   
   This command line compiles the input files PG1.COB, PG2.COB and PG3.COB, and generates corresponding output files for each input file, with the file types OBJ and ANA. The COBOL compiler puts these files in your current default directory.

4. Load the information in the data analysis files into your SCA library with the LOAD command. For example:

   $ SCA LOAD PG1,PG2,PG3

   
   This command loads your library with the modules contained in the data analysis files PG1.ANA, PG2.ANA, and PG3.ANA.

5. Once you have prepared the SCA library, you enter LSE to begin an SCA session. Within this context, the integration of LSE and SCA provides commands that you can use only within LSE.

To invoke LSE, issue the following command at the DCL prompt:

$ LSEDIT USER.COB

To end an LSE session, press CTRL/Z to get the LSE> prompt. If you wish to save modifications to your file, issue the EXIT command. If you do not wish to save the file or any modification to the file, issue the QUIT command.

To invoke SCA from LSE, type the SCA command that you wish to execute at the LSE> prompt, as in the following syntax:

LSE> command [parameter] [/qualifier...]

To invoke SCA from the DCL command line for the execution of a single command, you can use the following syntax:

$ SCA command [parameter] [/qualifier...]

If you have several SCA commands to invoke, you might wish to use the SCA subsystem to enter commands, as in the following syntax:

$ SCA SCA> command [parameter] [/qualifier...]

Typing EXIT (or pressing CTRL/Z) ends an SCA subsystem session and returns you to the DCL level.

C.4.4 Compiling from Within LSE

To compile a completed COBOL program, issue the following command at the LSE prompt:

LSE> COMPILE

To compile a COBOL program that contains placeholders and design comments, include the following qualifiers with the previous command:

LSE> COMPILE $/ANALYSIS_DATA

The /ANALYSIS_DATA qualifier causes the compiler to generate a data analysis file containing source code analysis information and to provide this information to the SCA library.

LSE provides several commands to help you review errors and examine your source code:

Command	Key Binding	Function