# Compaq COBOL
User Manual

Previous | Contents | Index

### 1.2.4.5 Interpreting Run-Time Messages

During execution, an image can generate a fatal error called an exception condition. When an exception condition occurs, the system displays a message. Run-time messages can also be issued by the OpenVMS system or by other utilities such as SORT. Other kinds of errors that can occur at run time include program run errors and run-time input/output errors.

Run-time messages have the following format:

`%COB-s-ident, message-text`

> ### %COB

> The program name of the Compaq COBOL Run-Time Library. This prefix indicates a run-time message.

> ### s

> The severity of the error. As with messages from the compiler and the linker, the severity indicator can be F (Fatal), E (Error), W (Warning), or I (Informational).

> ### ident

> The message identification. This is a descriptive abbreviation of the message text.

> ### message-text

> The run-time message. This portion may contain more than one line of output. A message generally provides you with enough information to determine the cause of the error so that you can correct it.

The following example shows a run-time message issued for an illegal divide:

    %COB-E-DIVBY-ZER, divide by zero; execution continues

Both the compiler and the OpenVMS Run-Time Library include facilities for detecting and reporting errors. You can use the OpenVMS Debugger and the traceback facility to help you locate errors that occur during program execution. For a description of Compaq COBOL run-time messages, use the HELP COBOL Run-Time Messages command.

Run-Time Messages

Faulty program logic can cause abnormal termination. If errors occur at run time, the Run-Time Library (RTL) displays a message with the same general format as system error messages. In addition, the system traceback facility displays a list of the routines that were active when the error occurred.

When an error occurs, TRACEBACK produces a symbolic dump of the active call frames. A call frame represents one execution of a routine. For each call frame, TRACEBACK displays the following information:

1. The module name (program-id)
2. The routine name (program-id)
3. The source listing line number where the error or CALL occurred
4. Program-counter (PC) information

You can also use the OpenVMS Debugger to examine the machine code instruction. To do this, compile and link the program using the /DEBUG qualifier. When you run the program, you automatically enter the debugger. Once in the debugger, you could use the EXAMINE/INSTRUCTION command to examine the contents of the failed instruction. You could also use the debugger in screen mode, which would indicate where the error occurred.

For more information about the OpenVMS Debugger, refer to Appendix C and the OpenVMS Debugger Manual.

# 1.3 Compaq COBOL and Alpha Architecture System Resources

For many user applications, the Compaq COBOL compiler requires significantly more system resources than Compaq COBOL for OpenVMS VAX. In fact, unless you have adjusted your system resource parameters accordingly, the attempt to compile may fail because of insufficient virtual memory. Also, for very large programs (greater than 10,000 lines), you might experience extremely long compile times. Knowing why Compaq COBOL requires more memory can help you take actions to avoid resource problems.

## 1.3.1 Compilation Performance

The Alpha architecture is a RISC (reduced instruction set computer) architecture. Many other processor architectures, including the VAX, are CISC (complex instruction set computer) architectures. The main distinguishing characteristic of a RISC machine is that it has few instructions and each instruction does a small amount of work. A CISC machine generally has many instructions, most of which perform many complicated operations in one step.

By reducing the amount of work that is done in each instruction (and by reducing the number of instructions), the complexity of the hardware is reduced. These hardware changes, plus others, result in an increase in the number of instructions per second that can be completed. The result is much faster overall system performance.

A tradeoff of RISC systems is that compilers for these architectures generally must do a great deal more work than a corresponding compiler for a CISC architecture. For example, the compiler must compute the best way to use all of the functional units of the processor, and it must determine how to make the best use of registers and on-chip data cache because reads and writes to main memory are generally slow compared to the speed of the processor.

The code generation portion of the Compaq COBOL for OpenVMS VAX compiler was developed for the CISC architecture of the VAX. The compiler examines one COBOL statement at a time, determines the VAX instructions to be constructed to execute that statement, and then moves on to the next one. Subsequently it uses "Peephole" optimization to enhance the performance of the generated machine code.

On the other hand, the Compaq COBOL compiler on Alpha was developed for the Alpha RISC architecture. It is a globally optimizing compiler based on the most recent compiler technology. It does many optimizations including Peephole, loop unrolling, and instruction pipelining. Also, the compiler uses mathematical graph theory to construct an internal representation of the entire COBOL program, and it repeatedly traverses this structure at compile time, to produce the most efficient machine code for the program. This results in very high performance code, to the benefit of your users at run time. Although the Compaq COBOL compiler on OpenVMS Alpha requires more resources than some other compilers to do this additional work at compile time, this cost is offset by better performance during the many run times that follow.

To reduce the impact on system resources at compile time, do the following:

- Use /NOOPTIMIZE or `-O0` on the compile command line when initially developing and testing programs. The optimizer is one of the heaviest users of system resources in the COBOL compiler and is turned on by default. Also, the higher the optimization level, the more memory required by the compiler.
- Check system tuning. Because the Compaq COBOL compiler often needs a great deal of virtual memory, you may need to increase virtual memory for developers who use the compiler. This results in decreased paging and improvements in compile time.
- Check program sizes. Larger amounts of system resources are used during compilation for large monolithic source files. It is possible that your application is already composed of several separately compiled program units (different PROGRAM IDs not nested), but all in the same .COB. On Alpha systems with Compaq COBOL, compilation performance improves if you split the program units into separate (smaller) .COB files (possibly one for each separately compiled program unit).

Note Large arrays (tables) can have a significant impact on compile time and resource requirements. In addition to the size of the program source, you should also examine the amount of space allocated in your Data Division, particularly for arrays. The number of array elements as well as the size of the array elements is significant. This impact can be minimized in two ways: by system tuning (as suggested in this section), which will optimize system resources for the compile, and by using INITIALIZE instead of VALUE in your data definitions, which will improve compilation performance.

## 1.3.2 Tuning OpenVMS Alpha for Large Compaq COBOL Compiles

The recommendations that follow were determined by compiling one set of very large Compaq COBOL modules on OpenVMS Alpha. While your results may vary, the principles are generally applicable. For more detailed information on OpenVMS Alpha tuning, refer to the OpenVMS System Manager's Manual, particularly the sections on Managing System Parameters and Managing System Page, Swap, and Dump Files.

Note that many tuning exercises are more beneficial if you work with a relatively quiet system, submit batch jobs, and retain the log files for later analysis.

### 1.3.2.1 Optimizing Virtual Memory Usage

If your system does not have enough virtual memory allocated, the compile may fail, with the "%LIB-E-INSVIRMEM, insufficient virtual memory" error reported.

OpenVMS has two parameters that control the amount of virtual memory available to a process. One is the system generation parameter VIRTUALPAGECNT, which sets an upper bound on the number of pagelets of virtual memory for any process in the system. The other control is the AUTHORIZE parameter PGFLQUOTA, which determines the number of pagelets a process can reserve in the system's page file(s).

After an "insufficient virtual memory" error, you can issue the DCL command $SHOW PROCESS/ACCOUNTING to see the "Peak virtual size" used by the process (or look at the "Peak page file size" at the end of a batch job log file). If the peak size is at the system generation parameter VIRTUALPAGECNT, you will need to raise this value. If the peak size is below VIRTUALPAGECNT, and at or above PGFLQUOTA, run AUTHORIZE to increase PGFLQUOTA for the COBOL users. (Peak size can exceed PGFLQUOTA because some virtual memory, such as read-only image code, is not allocated page file space.)

It is difficult to predict precisely how much virtual memory will be required for a compilation, but a starting point for system tuning may be computed by multiplying 250 times the size of the largest program in disk blocks (including all COPY files referenced). Alternatively, multiply 25 times the number of lines in the program (including all COPY files).

The resulting figure can then be used as a starting point for the system generation parameter VIRTUALPAGECNT. Put that figure in the parameter file SYS$SYSTEM:MODPARAMS.DAT. For example, if you estimate 370,000 pages, add the following line in MODPARAMS, run AUTOGEN and reboot:

    MIN_VIRTUALPAGECNT = 400000

If the compilation now completes successfully, use the command $SHOW PROCESS/ACCOUNTING to determine the Peak Virtual Size; if the actual peak is significantly less than the value computed above, you can reduce VIRTUALPAGECNT.

When modifying VIRTUALPAGECNT and PGFLQUOTA, you may also need to increase the size of the page file.

### 1.3.2.2 Optimizing Physical Memory Usage

In any evaluation of your system's physical memory, two of the questions to consider are:

> Is there enough memory on the system?
> Is enough available to the process running the compilation?

More specifically:

- If the physical memory on the system is too small, the command $LOGOUT/FULL (which is automatically issued at the end of a batch job) will show a high number of faults (>100,000 for a single compilation) and an elapsed time value that greatly exceeds the Charged CPU time value, as the system waits for disk I/Os to resolve page faults. In this situation, tuning attempts may be of limited benefit.
- If the physical memory on the system is adequate, but the physical memory allotted to the process running the compilation is too small, you may still observe a large number of faults, but elapsed time may remain closer to CPU time. This is because OpenVMS Alpha resolves page faults from the page caches (free list, modified list) whenever possible, avoiding the relatively slow disk I/Os. In this situation, basic tuning may also be beneficial.

The amount of physical memory required will vary, but it should be a large percentage of the process peak virtual size---as close to 100% as practical. The reason is that the compiler makes multiple passes over the internal representation of the program. A page that falls out of the working set in one pass is probably going to be needed again on the very next pass.

The physical memory present on the system can be determined by the DCL command $SHOW MEMORY/PHYSICAL. The physical memory used by the compilation is reported as "Peak working set size" by the command SHOW PROCESS/ACCOUNTING or at the end of a batch log file.

More physical memory can be made available to a process by minimizing the number of competing processes on the system (for example, by compiling one module at a time or by scheduling large compiles for off-peak time periods; late at night is a good time in some situations).

More physical memory can also be made available to a process (if it is present on the machine) by adjusting the system generation parameter WSMAX and the corresponding WSEXTENT (in AUTHORIZE). Approach such adjustments with great caution, as the system may hang if memory is oversubscribed and you create a situation where OpenVMS Alpha effectively has no options to reclaim memory. The following guidelines can help:

- Set the COBOL user WSEXTENT (in AUTHORIZE or INITIALIZE/QUEUE) to match WSMAX.
- Keep WSQUOTA (in AUTHORIZE or INITIALIZE/QUEUE) low. Make sure that no process or batch queue has a WSQUOTA of more than approximately 20% of physical memory. The difference between WSEXTENT and WSQUOTA allows OpenVMS Alpha to manage memory to meet varying demands.
- Use AUTOGEN. AUTOGEN will attempt to make a consistent set of changes that do not interfere with each other.
  By default, AUTOGEN will set the maximum working set (system generation parameter WSMAX) to 25% of physical memory. This value is reasonable for a workstation or multi-user system with many active processes.
  WSMAX can be increased to a somewhat larger value by editing MODPARAMS.DAT. For a system with 64 MB1 of physical memory, set WSMAX to no more than approximately 40% of physical memory, or 52000 pagelets (1 MB = 2048 pagelets). With 128 MB or more of physical memory, a setting of 50% of physical memory can be attempted.

The effects of physical memory on compilation time were studied for a set of seven large modules. These modules ranged in size from approximately 1600 to 3300 disk blocks. Your results may differ, but to give a rough appreciation for the effect of physical memory on compilation time, note that:

- When the amount of physical memory available to the processes matched the amount of virtual memory, the elapsed times were close to the CPU times.
- As the physical memory was reduced, CPU times rose only slightly---approximately 10%.
- As the physical memory was reduced, elapsed times were elongated, at the rate of approximately 1 hour for each 100 MB of difference between Peak Virtual Size and the actual memory available. For example, when compiling a program that used a Peak Virtual Size of 947760 pagelets, or 463 MB, on a system where approximately 180 MB of physical memory was available to user processes, the compile required approximately 3 hours more than on a 512 MB system.

Your results may differ from those shown in this section and will be strongly affected by the speed of the devices that are used for paging.

Note that the requirements for virtual memory and physical memory can also be reduced by breaking large modules into smaller modules.

### 1.3.2.3 Improving Compile Performance with Separate Compilation (OpenVMS Alpha)

The /SEPARATE_COMPILATION qualifier can improve compile-time performance for large source files that are made up of multiple separately compiled programs (SCPs). For programs compiled without this qualifier, the compiler engine parses the entire compilation unit and uses system resources (sized for the total job) for the duration of this compilation. When you use the /SEPARATE_COMPILATION qualifier, the compilation is replaced by a smaller series of operations, and memory structures that are needed for individual procedures are reclaimed and recycled. See Section 1.2.2.4 for additional information. <>

## 1.3.3 Choosing a Reference Format

You need to choose a reference format before you set out to write a Compaq COBOL program, and you must be aware of the format at compile time. The Compaq COBOL compiler accepts source code written in either terminal or ANSI reference format. You cannot mix reference formats in the same source file.

On OpenVMS, when copying text from Oracle CDD/Repository, the Compaq COBOL compiler translates the record descriptions into the reference format of the source program. <>

### 1.3.3.1 Terminal Reference Format

Compaq recommends using terminal format, a Compaq optional format, when you create source files from interactive terminals. The compiler accepts terminal format as the default reference format.

Terminal format eliminates the line number and identification fields of ANSI format and allows horizontal tab characters and short lines. Terminal format saves disk space and decreases compile time. It is easier to edit source code written in terminal format.

The following table shows the structure and content of a terminal reference source line: To select ANSI format, specify the `-ansi` flag (on Tru64 UNIX systems) or the /ANSI_FORMAT qualifier (on OpenVMS systems) at compile time. You can choose this format if your COBOL program is written for a compiler that uses ANSI format.

For ANSI format, the compiler expects 80-character program lines. The following table shows the structure and content of an ANSI reference source line:

Character Positions | Contents
--- | ---
1 to 6 | Optional sequence numbers
7 | Indicators
8 to 11 | Area A
12 to 72 | Area B
73 to 80 | Optional Area

For more information about the two reference formats, refer to the Compaq COBOL Reference Manual.

### 1.3.3.2 Converting Between Reference Formats

The REFORMAT utility allows you to convert a terminal format program to ANSI format and vice versa. You can also use REFORMAT to match the formats of Compaq COBOL source files and library files when their formats are not the same. See Chapter 14 for a description of the REFORMAT utility.

Note #### 1 MB= megabytes

# 1.4 Program Run Messages

Incorrect or undesirable program results are usually caused by data errors or program logic errors. You can resolve most of these errors by desk-checking your program and by using a debugger.

## 1.4.1 Data Errors

Faulty or incorrectly defined data often produce incorrect results. Data errors can sometimes be attributed to one or more of the following actions:

- Incorrect picture size. As shown in the following sample of a partial program, if the picture size of a receiving data item is too small, your data may be truncated:

      77   COUNTER   PIC S9.
           .
           .
           .
      PROCEDURE DIVISION.
           .
           .
           .
       LOOP.
           ADD 1 TO COUNTER
           IF COUNTER < 10 GO TO LOOP.

  The IF clause will produce an infinite loop because of the one-digit size limit of COUNTER, which is PIC S9. If COUNTER were PIC S99, or if the clause used 9 instead of 10, the condition could be false, causing a proper exit from the loop.
- Incorrect record field position. The record field positions that you specify in your program may not agree with a file's record field positions. For example, a file could have this record description:

      01  PAY-RECORD.
          03  P-NUMBER       PIC X(5).
          03  P-WEEKLY-AMT   PIC S9(5)V99  COMP-3.
          03  P-MONTHLY-AMT  PIC S9(5)V99  COMP-3.
          03  P-YEARLY-AMT   PIC S9(5)V99  COMP-3.
              .
              .
              .

  Incorrectly positioning these fields can produce faulty data.

In the following example, a program references the file incorrectly. The field described as P-YEARLY-AMT actually contains P-MONTHLY-AMT data, and vice versa.

    01  PAY-RECORD.
        03  P-NUMBER       PIC X(5).
        03  P-WEEKLY-AMT   PIC S9(5)V99  COMP-3.
        03  P-YEARLY-AMT   PIC S9(5)V99  COMP-3.
        03  P-MONTHLY-AMT  PIC S9(5)V99  COMP-3.
            .
            .
            .
    PROCEDURE DIVISION.
    ADD-TOTALS.
        ADD P-MONTHLY-AMT TO TOTAL-MONTHLY-AMT.
            .
            .
            .

You can minimize record field position errors by writing your file and record descriptions in a library file and then using the COPY statement in your programs. On OpenVMS systems, you can also use the COPY FROM DICTIONARY statement.

Choosing your test data carefully can minimize faulty data problems. For instance, rather than using actual or ideal data, use test files that include data extremes.

Determining when a program produces incorrect results can often help your debugging effort. You can do this by maintaining audit counts (such as total master in = nnn, total transactions in = nnn, total deletions = nnn, total master out = nnn) and displaying the audit counts when the program ends. Using conditional compilation lines (see Section 1.2.2.7) in your program can also help you to debug it.

Previous | Next | Contents | Index