Compaq COBOL
User Manual

Contents

Index

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

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

DBG> DEPOSIT SUB-2 = -42

Examine the contents of SUB-2.

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

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

DBG> EXAMINE CHARCT TESTA\TESTB\CHARCT: 3.00

Deposit four characters into CHARCT.

DBG> DEPOSIT CHARCT=15.95

CHARCT now contains 15.95.

DBG> EXAMINE CHARCT TESTA\TESTB\CHARCT: 15.95

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

Examine the contents of CHARCT.

DBG> EXAMINE CHARCT TESTA\TESTB\CHARCT: 15.95

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"

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"

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"

Deposit a value into CHARCT.

DBG> DEPOSIT CHARCT=8.00

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".

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

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'

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

DBG> EXIT $ <>

C.4.2.1 Separately Compiled Programs

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.3.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.5 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 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. See 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.

C.5.1 Notes on Compaq COBOL Support

Compaq COBOL supports the LSE and SCA program creation, analysis, and compilation features described in the preceding sections. Compaq COBOL 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--See the Guide to Language-Sensitive Editor.
On SCA--See the Guide to Source Code Analyzer for VMS Systems.
On CMS--See the Guide to Code Management System for VMS Systems.

C.5.2 Preparing an SCA Library

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:

Create a directory for your SCA library. For example:
$ CREATE/DIRECTORY PROJ:[USER.LIB1]
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.
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.
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.
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.

C.5.3 Starting and Terminating an LSE or an SCA Session

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.5.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

C.6 Using Oracle CDD/Repository (OpenVMS)

Oracle CDD/Repository is an optional software product available under a separate license. The Oracle CDD/Repository product lets you maintain shareable data definitions, such as record and field definitions. Oracle CDD/Repository data definitions are organized hierarchically in much the same way that files are organized in directories and subdirectories. For example, a repository for defining personnel data might have separate directories for each employee type.

Often, it is the job of a repository or data administrator to create repositories, define directory structures, and insert record and field definitions into the repository. In large organizations, many repositories can be linked together to form one logical repository. Once the repositories are established, the data definitions can be used throughout the organization by database administrators and application developers. If the paths are set up correctly, users can access definitions as if they were in a single repository.

Descriptions of data definitions are entered into the repository in a special-purpose language called Common Dictionary Operator (CDO). (Oracle CDD/Repository also supports both the Common Data Dictionary (Version 3) and CDD/Plus (Version 4) interfaces for use by existing databases and applications.) Oracle CDD/Repository converts the data descriptions to an internal form---making them independent of the language used to access them---and inserts them into the repository.

When you compile a COBOL program, Oracle CDD/Repository data definitions can be accessed by means of the COPY FROM DICTIONARY statement. If the attributes of the data definitions are consistent with Compaq COBOL requirements, the data definitions are included in the COBOL program. Oracle CDD/Repository data definitions, in the form of COBOL source code, can appear in source program listings if you specify the /LIST and /COPY_LIST qualifiers on the COBOL command line.

Oracle CDD/Repository can also store information about the structure of a program, such as the compiled modules that go into making an object module, or the record and field definitions that are used by COBOL programs. If, for example, a record definition needs to change, you can analyze the impact that change will have on the various programs that use it. When the definition is changed, Oracle CDD/Repository notifies the modules that the record definition is out of date, and the program can be recompiled.

To take advantage of dependency recording, you must:

Enable dependency recording by compiling your program with the /DEPENDENCY_DATA qualifier.
Direct the COBOL compiler to a repository or a compatibility dictionary in which to store the dependency information.

C.6.1 Creating Record and Field Definitions

The following example shows how you can use CDO to create a number of fields representing name and address information:

DEFINE FIELD NAME DATATYPE IS TEXT SIZE IS 25 CHARACTERS. DEFINE FIELD COMPANY_NAME DATATYPE IS TEXT SIZE IS 25 CHARACTERS. DEFINE FIELD STREET DATATYPE IS TEXT SIZE IS 20 CHARACTERS. DEFINE FIELD CITY DATATYPE IS TEXT SIZE IS 20 CHARACTERS. DEFINE FIELD STATE DATATYPE IS TEXT SIZE IS 2 CHARACTERS. DEFINE FIELD ZIP DATATYPE IS TEXT SIZE IS 5 CHARACTERS.

The fields can then be used to create records. The following example creates two records --- one for customer address information and one for employee address information:

DEFINE RECORD CUSTOMER_ADDRESS_RECORD. NAME. COMPANY_NAME. STREET. STATE. ZIP. END RECORD. DEFINE RECORD EMPLOYEE_ADDRESS_RECORD. NAME. STREET. STATE. ZIP. END RECORD.

C.6.2 Accessing Oracle CDD/Repository Definitions from Compaq COBOL Programs

You access repository data definitions from a COBOL program using the COPY FROM DICTIONARY statement. At compile time, the record definition and its attributes are extracted from the designated repository. Then the compiler converts the extracted definition into a COBOL declaration. For example, the following COBOL statements access the customer and employee address records defined earlier. These definitions have been placed in the repository directory DEVICE:[VMS_DIRECTORY]SALES.

IDENTIFICATION DIVISION. PROGRAM-ID. MASTER-FILE. DATA DIVISION. WORKING-STORAGE SECTION. COPY "DEVICE:[VMS_DIRECTORY]SALES.CUSTOMER_ADDRESS_RECORD" FROM DICTIONARY. COPY "DEVICE:[VMS_DIRECTORY]SALES.EMPLOYEE_ADDRESS_RECORD" FROM DICTIONARY. . . .

If you compile this program with the /LIST and /COPY_LIST qualifiers, the source listing includes the data definition translated into a COBOL declaration, as shown in the following example:

1 IDENTIFICATION DIVISION. 2 PROGRAM-ID. MASTER-FILE. 3 DATA DIVISION. 4 WORKING-STORAGE SECTION. 5 COPY "DEVICE:[VMS_DIRECTORY]SALES.CUSTOMER_ADDRESS_RECORD" FROM DICTIONARY. L 6 * L 7 *DEVICE:[VMS_DIRECTORY].SALES.CUSTOMER_ADDRESS_RECORD L 8 * L 9 01 CUSTOMER_ADDRESS_RECORD. L 10 02 NAME PIC X(25). L 11 02 COMPANY_NAME PIC X(25). L 12 02 STREET PIC X(20). L 13 02 CITY PIC X(20). L 14 02 STATE PIC X(2). L 15 02 ZIP PIC X(5). 16 COPY "NODE::DEVICE:[VMS_DIRECTORY]SALES.EMPLOYEE_ADDRESS_RECORD" FROM DICTIONARY. L 17 * L 18 *DEVICE:[VMS_DIRECTORY].SALES.EMPLOYEE_ADDRESS_RECORD L 19 * L 20 01 EMPLOYEE_ADDRESS_RECORD. L 21 02 NAME PIC X(25). L 22 02 STREET PIC X(20). L 23 02 CITY PIC X(20). L 24 02 STATE PIC X(2). L 25 02 ZIP PIC X(5). . . .

For more information on the COPY FROM DICTIONARY statement, refer to the Compaq COBOL Reference Manual. For more information on the /LIST and /COPY_LIST command qualifiers, invoke the online HELP facility for COBOL at the operating system prompt.

C.6.3 Recording Dependencies

When you compile a program with the /DEPENDENCY_DATA qualifier, the compiler creates the following repository objects to represent the compiled modules, the resulting object module, and the relationships between them:

A compiled module object is created for each separately compiled program. The name of the object is the PROGRAM-ID name with hyphens translated to underscores. Compiled module objects are put in the repository pointed to by the logical name CDD$DEFAULT, or in the compatibility dictionary if CDD$DEFAULT is not defined.
For each object file generated by the compilation, the compiler creates a temporary file object. Each compiled module object contains a pointer to a file object, and several compiled module objects can point to the same file object. At the end of the compilation, the file object does not actually exist in the repository. However, information relating the compiled module object and the object file does exist in the repository.

The /DEPENDENCY_DATA qualifier can also direct the compiler to create relationships between the compiled module object and other objects in the repository:

If the source file contains a COPY FROM DICTIONARY statement, the compiler creates a CDD$COMPILED_DEPENDS_ON relationship between the compiled module object and the record or field definition that is being copied. It also copies the repository object into the compiled module.
If the source file contains a RECORD statement, the compiler creates a relationship between the compiled module object and the specified repository object, but it does not copy the repository object into the compiled module. The relationship can be either CDD$COMPILED_DEPENDS_ON or CDD$COMPILED_DERIVED_FROM. The default relationship type is CDD$COMPILED_DEPENDS_ON.

For example, recall the program that used COPY FROM DICTIONARY to include the customer and employee address record definitions:

When this program is compiled with the /DEPENDENCY_DATA qualifier, the following objects are created in the repository:

A compiled module object called MASTER_FILE
A temporary file object representing the object file produced by the compilation
A relationship between the MASTER_FILE compiled module object and the object file
A relationship between the MASTER_FILE object and the CUSTOMER_ADDRESS_RECORD definition
A relationship between the MASTER_FILE object and the EMPLOYEE_ADDRESS_RECORD definition

In addition, the record definitions are included in the compiled module.

The COPY FROM DICTIONARY statement is used when you want to create a relationship between a compiled module and a record or field definition. The RECORD statement is used when you need to create a relationship between a compiled module and some other kind of repository object --- one that you do not want copied into the compiled module. For example, suppose you need to create a relationship between the MASTER_FILE compiled module object and a text file object, such as a functional specification. This relationship would indicate that the compiled module is derived from the functional specification. For example:

IDENTIFICATION DIVISION. PROGRAM-ID. MASTER-FILE. . . . PROCEDURE DIVISION. A0100. . . . RECORD DEPENDENCY "DEVICE:[VMS_DIRECTORY]SALES.SPECIFICATION" TYPE IS "CDD$COMPILED_DERIVED_FROM" IN DICTIONARY. . . .

When this program is compiled with the /DEPENDENCY_DATA qualifier, the compiler creates the following objects and relationships:

A compiled module object called MASTER_FILE
A temporary file object representing the object file produced by the compilation
A relationship between the MASTER_FILE compiled module object and the object file
A relationship between the MASTER_FILE object and the repository object called SPECIFICATION, which represents the functional specification text file

For more information on the RECORD statement, refer to the Compaq COBOL Reference Manual. For more information on the /DEPENDENCY_DATA qualifier, invoke the online HELP facility for COBOL at the operating system prompt.