Example C-6 shows the Compaq C program POWER.C to be used in the sample debugging session shown in Example C-7.

Example C-6 Debugging Sample Program POWER.C

/* POWER.C This program contains two functions: "main" and * * "power." The main function passes a number to * * "power", which returns that number raised to the * * second power. */ main() { static int i, j; int power(int); i = 2; j = power(i); } power(int j) { return (j * j); }

Although this program contains no errors, Example C-7 shows some simple debugger commands that can be used to evaluate its execution. The callout numbers in this sample debugging session are keyed to the notes that follow.

Example C-7 A Sample Debugging Session

(1) $ CC/DEBUG/NOOPTIMIZE POWER $ LINK/DEBUG POWER $ RUN POWER OpenVMS DEBUG Version 6.n (2) %DEBUG-I-INITIAL, language is C, module set to 'POWER' (3) DBG> set break %LINE 13 (4) DBG> go (5) break at POWER\main\%LINE 13 (6) 13: j = power(i); (7) DBG> step/into (8) stepped to routine POWER\power 16: int j; DBG> step stepped to POWER\power\%LINE 18 18: return (j * j) (9) DBG> examine J (10) %DEBUG-W-NOSYMBOL, symbol 'J' is not in the symbol table DBG> examine j (11) POWER\power\j: 2 DBG> step stepped to POWER\main\%LINE 13+9 13: j = power(i); DBG> step stepped to POWER\main\%LINE 14 14: } DBG> examine j (12) POWER\main\j: 4 DBG> go (13) %DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion' (14) DBG> exit $

Key to Example C-7:

1. To execute a program with the debugger, you must compile and link the program with the /DEBUG qualifier. The Compaq C compiler compiles the source file with the /DEBUG=TRACEBACK qualifier by default. However, unless you compile your program with the /DEBUG qualifier, you cannot access all of the program's variables. Use the /NOOPTIMIZE qualifier to turn off compiler optimization that might interfere with debugging.
2. The OpenVMS Image Activator passes control to the debugger on execution of the image. The debugger displays the current programming language and the name of the object module that contains the main function, or the first function to be executed. Remember that the linker converts the names of object modules to uppercase letters.
3. You enter debugger commands at the following prompt:

   DBG>

   
   The SET BREAK command defines a point in the program where the debugger must suspend execution. In this example, SET BREAK tells the debugger to stop execution before execution of line number 13. After the debugger processes the SET BREAK command, it responds with the debugger prompt.

4. The GO command begins execution of the image.
5. The debugger indicates that execution is suspended at line 13 of the main function. The debugger specifies sections of the program by displaying the object module it is working in, delimited by a backslash character (\), followed by the name of the C function. The linker converted the name of the object module to uppercase letters but the debugger specifies the name of the function exactly as it is found in the source text.
6. The debugger displays the line of source text where it suspended execution. Refer to the source code listing in Example C-6 to follow the debugger as it steps through the lines of the program in this interactive debugging example.
7. The STEP/INTO command executes the first executable line in a function. The STEP command tells the debugger to execute the next line of code, but if the next line of code is a function call, the debugger will not step through the function code unless you use the /INTO qualifier. Use STEP/INTO to step through a user-defined or Compaq C RTL function.
8. When stepping through a function, the debugger specifies line numbers by displaying the object module, the C function, and %LINE followed by the line number in the source text, each delimited by a backslash. The code at that line number is then displayed.
9. The EXAMINE command displays the contents of a variable.
10. The debugger does not recognize the variable J as existing in the scope of the current module.
11. Because the debugger supports the case sensitivity of C variables, variable j exists but variable J does not. Refer to Example C-6 to review the program variables.
    In response to the EXAMINE command, the debugger displays the value of the variable j (2).
12. The value of variable j in function main is different from the local variable j in the power function. The power function executes properly, returning the value
    2² (4).
13. When execution is completed, the debugger displays the execution status (successful, in this example).
14. The EXIT command terminates the debugging session and returns to the DCL prompt.

The OpenVMS Text Processing Utility (TPU) (provided with the OpenVMS operating system) is a high-performance, programmable utility. TPU provides a number of special features, such as multiple buffers and windows, definable keys and key sequences, a procedural language, and a callable interface.

TPU serves as a base on which to layer other text processing applications, for example, text editors. The Extensible VAX Editor (EVE) is the editor provided with TPU. To invoke EVE, enter the following command at the DCL prompt:

$ EDIT/TPU USER.C

To exit from EVE, press the Do key to get the Command: prompt. If you want to save modifications to your file, enter the EXIT command. If you do not want to save the file or any modification to the file, enter the QUIT command.

For information on TPU and EVE, see the Guide to VMS Text Processing.

C.3 Language-Sensitive Editor and the Source Code Analyzer

The Compaq Language-Sensitive Editor (LSE) and the Compaq Source Code Analyzer (SCA) must be purchased separately from the OpenVMS operating system. LSE is a text editor intended specifically for software development. SCA is an interactive tool for program analysis.

These products are closely integrated; generally, SCA is invoked through LSE. LSE provides additional editing features that make SCA program analysis more efficient. In addition, LSE and SCA, in conjunction with the Compaq C compiler, provide a set of new enhancements supporting source code design and review.

In addition to text editing features, LSE provides the following software development features:

• Formatted language constructs, or templates, for most Compaq programming languages, including Compaq C. These templates include the keywords and punctuation used in source programs, and use placeholders to indicate locations in the source code where additional text is optional or required.
• Commands to compile, review, and correct compilation errors from within the editor.
• Integration with the DEC/Code Management System (CMS) for OpenVMS Systems. You can enter CMS commands from within the editor to make source file management more efficient.

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 Compaq language compilers, provide the following software design features:

• Pseudocode support, which includes a new LSE placeholder for delimiting pseudocode. Pseudocode is text that describes algorithms or design decisions. This feature allows you to write source code in shorthand, returning later to fill in code details.
• Placeholder processing, in which language compilers accept LSE placeholders and pseudocode as valid program elements during compilation. This feature allows you to test the validity of algorithms while programs are still in shorthand form.
• Comment processing, which includes design comment information in the SCA library. SCA performs cross-referencing and static analysis on this information in response to user queries.
• 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 modifications you make are reflected in the program code.
• A report tool, callable through LSE, that can print views, standard design reports, and customized reports.

The following sections provide entry, exit, and language-specific information on the combined use of LSE and SCA. For more information on LSE and SCA, see the Guide to Language-Sensitive Editor for VMS Systems and the Guide to Source Code Analyzer for VMS Systems. For more information on CMS, see the Guide to Code Management System for VMS Systems.

C.3.1 Preparing an SCA Library

SCA stores data generated by the Compaq C 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. This preparation involves the following steps:

1. Create an OpenVMS 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 your SCA library selection succeeded.

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

   $ CC/ANALYSIS_DATA PG1,PG2,PG3

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

4. Load the information in the data analysis files into your SCA library with the SCA 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 the SCA library has been prepared, enter LSE to begin an SCA session. Within this context, the integration of LSE and SCA provides commands that can be used only within LSE.

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

$ LSEDIT USER.C

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

To invoke SCA from the LSE prompt, enter the SCA command that you want to execute using the following syntax:

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

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

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

If you have several SCA commands to invoke, you might want to first invoke the SCA subsystem and then enter SCA commands:

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

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

C.3.3 Programming Language Placeholders and Tokens

The LSE language-sensitive features simplify the tasks of developing and maintaining software systems. These features include language-specific placeholders and tokens, aliases, comment and indentation control, and templates for subroutine libraries.

You can use LSE as a traditional text editor. In addition, you can use the power of LSE's tokens and placeholders to step through each program construct and supply text for those constructs that need it.

Placeholders are markers in the source code that indicate where you can provide program text. These placeholders help you to supply the appropriate syntax in a given context. You do not need to type placeholders; they are inserted for you by LSE. Placeholders are surrounded by brackets or braces and at (@) signs.

Placeholders are either optional or required. Required placeholders, indicated by braces ({}), represent places in the source code where you must provide program text. Optional placeholders, indicated by brackets ([]), represent places in the source code where you can either provide additional constructs or erase the placeholder.

You can move forward or backward from placeholder to placeholder. In addition, you can delete or expand placeholders as needed.

Tokens typically represent keywords in Compaq C. When expanded, tokens provide additional language constructs. You can type tokens directly into the buffer. You use tokens in situations, such as modifying an existing program, where you want to add additional language constructs and there are no placeholders. For example, typing IF and entering the EXPAND command causes a template for an IF construct to appear on your screen. You can also use tokens to bypass long menus in situations where expanding a placeholder, such as {@statement@}, will result in a lengthy menu.

You can use tokens to insert text when editing an existing file by typing the name for a function or keyword and entering the EXPAND command.

LSE provides commands for manipulating tokens and placeholders. Table C-1 shows these commands and their default key bindings.

Table C-1 Commands to Manipulate Tokens and Placeholders

Command	Key Binding	Function
EXPAND	Ctrl/E	Expands a placeholder.
UNEXPAND	PF1-Ctrl/E	Reverses the effect of the most recent placeholder expansion.
GOTO PLACEHOLDER/FORWARD	Ctrl/N	Moves the cursor forward to the next placeholder.
GOTO PLACEHOLDER/REVERSE	Ctrl/P	Moves the cursor backward to the next placeholder.
ERASE PLACEHOLDER/FORWARD	Ctrl/K	Erases a placeholder.
UNERASE PLACEHOLDER	PF1-Ctrl/K	Restores the most recently erased placeholder.
<downarrow symbol>	Down-arrow	Moves the indicator downward through a screen menu.
<uparrow symbol>	Up-arrow	Moves the indicator upward through a screen menu.
[Enter] [Return]	ENTER RETURN	Selects a menu option.

To display a list of all the defined tokens provided by Compaq C, enter the following LSE command:

LSE> SHOW TOKEN

To display a list of all the defined placeholders provided by Compaq C, enter the following LSE command:

LSE> SHOW PLACEHOLDER

To put either list into a separate file, first enter the appropriate SHOW command to put the list into the $SHOW buffer. Then enter the following commands:

LSE> GOTO BUFFER $SHOW LSE> WRITE filename

To obtain a hard copy of the list, use the PRINT command at DCL level to print the file you created.

To obtain information about a particular token or placeholder, specify a token name or placeholder name after the SHOW TOKEN or SHOW PLACEHOLDER command.

C.3.4 Compiling Source Code

To compile your source code and to review compilation errors without leaving the editing session, use the LSE commands COMPILE and REVIEW. The COMPILE command issues a DCL command in a subprocess to invoke the Compaq C compiler. The compiler then generates a file of compile-time diagnostic information that LSE uses to review compilation errors. The diagnostic information is generated with the /DIAGNOSTICS qualifier that LSE appends to the compilation command.

For example, if you enter the COMPILE command while in the buffer USER.C, the following DCL command is executed:

$ CC USER.C/DIAGNOSTICS=USER.DIA

LSE supports all the Compaq C compiler's command qualifiers as well as user-supplied command procedures.

The REVIEW command displays any diagnostic messages that result from a compilation. LSE displays the compilation errors in one window and the corresponding source code in a second window. This multiwindow capability allows you to review your errors while examining the associated source code.

To compile a Compaq C program that contains placeholders and design comments, include the following qualifiers to the COMPILE command:

LSE> COMPILE $/ANALYSIS_DATA/DESIGN

The /ANALYSIS_DATA qualifier generates a data analysis file containing source code analysis information. This information is provided to the SCA library.

The /DESIGN qualifier instructs the compiler to recognize placeholders and design comments as valid program elements. If the /ANALYSIS_DATA qualifier is also specified, the compiler includes information on placeholders and design comments in the data analysis file.

C.3.5 LSE Examples

The following examples show the expansions of Compaq C tokens and placeholders. The intent is to show the formats and guidelines that LSE provides, not to fully expand all tokens and placeholders. An arrow (->) indicates where in the example an action occurred.

To invoke LSE and the Compaq C language, use the following syntax:

LSEDIT [/qualifier...] filename.C

C.3.5.1 Compilation Unit

When you use the editor to create a new Compaq C program, the initial string {@compilation unit@} appears at the top of the screen:

-> {@compilation unit@} [End of file]

Use Ctrl/E to expand this initial string. The following is displayed:

-> [@#module@] [@module level comments@] [@include files@] [@macro definitions@] [@preprocessor directive@]... [@data type or declaration@]...; [@function definition@]...;

C.3.5.2 Preprocessor Lines

Erase the [@#module@] , [@module level comments@] , [@include files@] , and [@macro definitions@] . The cursor is then positioned on [@preprocessor directive@] . Expand [@preprocessor directive@] to duplicate it and display a menu. Then select the #include option:

1. Use the up and down arrows on the keypad to position the displayed selection arrow next to #include .
2. Press Return.

The following display results:

-> #include [@preprocessor directive@]... [@data type or declaration@]...; [@function definition@]...;

After selecting the #include option, another menu appears that lists the types of #include statements. Select the option #include {@module name@} . Your display now looks like this:

-> #include {@module name@} [@preprocessor directive@]... [@data type or declaration@]...; [@function definition@]...;

Type the value stdio over the placeholder {@module name@} .

Experiment with the LSE editor to expand other placeholders, such as [@data type or declaration@] , [@function definition@] , and so on.