# Compaq COBOL
User Manual

Previous | Contents | Index

# Chapter 14
Using the REFORMAT Utility

The REFORMAT Utility converts source programs between terminal format and conventional ANSI format. Consider the two formats and their characteristics:

- Terminal format eliminates the line-number and identification fields of ANSI format and allows horizontal tab characters and short lines. It saves disk space and decreases compile time.
- Conventional ANSI format produces source programs compatible with the reference format as defined in the ANSI-85 COBOL Standard.

The Compaq COBOL Reference Manual describes both formats in detail.

On OpenVMS, REFORMAT is installed by the Compaq COBOL installation procedure (if you answered "yes" to the query during installation), and is placed in the following location:

      SYS$SYSTEM:REFORMAT.EXE  <>

This chapter provides the following information about using the REFORMAT utility:

- Running the REFORMAT utility ( Section 14.1)
- ANSI-to-terminal format conversion ( Section 14.2)
- Terminal-to-ANSI format conversion ( Section 14.3)
- REFORMAT error messages ( Section 14.4)

# 14.1 Running the REFORMAT Utility

On OpenVMS, you can define REFORMAT as a foreign command as follows:

    $ REFORMAT :== "$SYS$SYSTEM:REFORMAT.EXE"

Then you would type the following command:

    $  reformat  <>

On Tru64 UNIX, type the following:

    %  reformat  <>

The following example shows a typical session using the REFORMAT Utility (the command line prompt is omitted):

    REFORMAT -
    REFORMAT - Enter Y for ANSI-to-terminal conversion, or
    REFORMAT - Enter N (default) for terminal-to-ANSI conversion.
    REFORMAT - Enter ^Z to exit.
    REFORMAT - ANSI-to-terminal format conversion mode [ Y / [N] ]?

    n
    REFORMAT - Terminal-to-ANSI format selected
    REFORMAT - Terminal-format input file spec :

    myprog.cob
    REFORMAT -     ANSI-format output file spec:

    myprog2.cob
    REFORMAT - Columns 73 to 80:
    REFORMAT -      42 Terminal source code records converted to ANSI format
    REFORMAT -
    REFORMAT - Enter Y for ANSI-to-terminal conversion, or
    REFORMAT - Enter N (default) for terminal-to-ANSI conversion.
    REFORMAT - Enter ^Z to exit.
    REFORMAT - ANSI-to-terminal format conversion mode [ Y / [N] ]?

    ^Z
    REFORMAT -

In the preceding example, the following events took place:

1. The user typed n in response to the first prompt, indicating a desire to convert a file from Terminal to ANSI format (the user could have simply pressed Return, as the default direction is Terminal-to-ANSI).
2. The user typed myprog.cob in response to the prompt for an input file spec.
3. The user typed myprog2.cob in response to the prompt for an output file spec.
4. The program next prompted for an identification entry in columns 73 to 80, and the user simply pressed Return.
5. Ending that dialog, the program reported that it converted 42 source code records.
6. The program then repeated the original prompts, to which the user replied with a Ctrl/Z.

The Ctrl/Z ends this reformatting session.

# 14.2 ANSI-to-Terminal Format Conversion

REFORMAT converts each ANSI format source line to terminal format by:

- Removing the 6-character sequence field in the first six character positions of the ANSI format line
- Moving any continuation symbol (-) or comment symbols (* or /) from character position 7 into character position 1
- Moving the conditional compilation character (if any) from the ANSI format indicator area into character position 2 and inserting a backslash character (\) into character position 1 of the terminal format line
- Removing the identification entry field in character positions 73 to 80 of the ANSI format line
- Removing insignificant trailing spaces before character position 73 of the ANSI format line
- Replacing every form-feed record with a line containing a slash (/) in character position 1
- Placing the converted code in positions 1 to the end of the line, thereby creating a terminal format line

Note When you convert programs that contain continued nonnumeric literals you should examine those literals to see if they require any changes. (This should occur only when going from ANSI format to terminal format.)

# 14.3 Terminal-to-ANSI Format Conversion

REFORMAT converts each terminal format source line to ANSI format by:

- Placing a 6-character line number (000010) in the first six character positions of the first line and increasing it by 000010 for each subsequent line.
- Moving any continuation symbol (-), or the comment symbols (* or /) from character position 1 into character position 7.
- Removing the backslash character (\), if any, from character position 1 in terminal format and moving the following conditional compilation character into character position 7 of the ANSI format line.
- Replacing horizontal tabs with space characters at every eighth character position, starting at character position 5 and ending at the end of the line.
- Moving spaces into remaining character positions after the last character of code and before character position 73.
- Expanding a terminal line with more than 65 characters into two or more ANSI format lines and right-justifying these lines at character position 72.
- Placing either identification characters (if supplied at program initialization) or spaces into character positions 73 to 80.
- Right-justifying (at position 72) the first line of a continued nonnumeric literal. This ensures that the literal remains the same length as it was in the default format.
- Replacing every form-feed record with a line containing a slash (/) in position 7 and space characters in positions 8 to 72.
- Placing the converted code in character positions 8 to 72, thereby creating one or more ANSI format lines.

Note that it is possible to construct a terminal format line that converts to an invalid ANSI formatted line. Consider the case of a conditional compilation line with a long nonnumeric literal:

    \A   01   ART   PIC X(80)  VALUE "A ... A".

This statement cannot be reformatted to a valid ANSI statement. The literal is 80 characters long, which indicates that the literal must be continued on the next line by placing a continuation symbol (-) in the indicator area. The line is also a conditional compilation line, which indicates that the A is to be placed in the indicator area. Clearly both characters cannot be placed in the indicator area. Compaq COBOL continues the conditional compilation line by placing the A in the indicator area. This means the program remains valid if conditionals are not used in the compilation because the lines become comment lines. If conditionals are used, you must locate and correct these invalid lines. The reformat program is a text processor and does not perform the level of checking required by lines such as these. You detect this error during a compile operation.

# 14.4 REFORMAT Error Messages

If any of your responses to the prompts are incorrect, REFORMAT displays error messages. It replaces the parentheses and the parenthetical text with the appropriate format type you specified.

    REFORMAT - Error in opening (ANSI or terminal) format input file:
    REFORMAT -        (ANSI or terminal) format input file spec:

The system could not open the input file; either the file is not on the specified device or you typed the file name incorrectly.

The default device is SYS$DISK on OpenVMS systems; it is `stdin` on Tru64 UNIX systems.

To continue processing, examine the input file specification and type a corrected version. To process another file, type a new input file specification. To end execution, type Ctrl/Z (on OpenVMS systems) or CTRL/D (on Tru64 UNIX systems).

    REFORMAT - Error in opening (ANSI or terminal) format output file:
    REFORMAT -   (ANSI or terminal) format output file spec:

The system could not open the output file. An incorrectly typed file specification usually causes this error.

The default device is SYS$DISK on OpenVMS systems; it is ./ on Tru64 UNIX systems.

To continue, examine the output file specification and type a corrected version. To end execution, type Ctrl/Z (on OpenVMS systems) or CTRL/D (on Tru64 UNIX systems).

    REFORMAT - (ANSI or terminal) format input file is empty
    REFORMAT -     (ANSI or terminal) format input file spec:

The system opened an empty input file. To continue, type a new input file specification. To end execution, type Ctrl/Z (on OpenVMS systems) or CTRL/D (on Tru64 UNIX systems).

    REFORMAT - Error in reading (ANSI or terminal) format input file
    REFORMAT - Reformating aborted
    REFORMAT - n (ANSI or terminal) COBOL  source records converted to
                     (ANSI or terminal) format
    REFORMAT - ANSI-to-terminal format conversion mode [ Y or N ]?

REFORMAT failed to read a record from the input file. This error ends the conversion process. REFORMAT closes both files and displays the number of converted input records.

You can convert another file, or you can end the session by typing Ctrl/Z (on OpenVMS systems) or CTRL/D (on Tru64 UNIX systems).

    REFORMAT - Error in writing (ANSI or terminal) format output file
    REFORMAT - Reformatting aborted
    REFORMAT - n (ANSI or terminal) COBOL source records converted to
                     (ANSI or terminal) format
    REFORMAT - ANSI-to-terminal format conversion mode [ Y or N ]?

REFORMAT failed in an attempt to write an output record. It ends execution and closes both files.

To process another file, type a new input file specification and continue the prompting message sequence. To end execution, type Ctrl/Z (on OpenVMS systems) or CTRL/D (on Tru64 UNIX systems).

# Chapter 15
Optimizing Your Compaq COBOL Program

You can specify optimization and data alignment on the COBOL compiler command line to improve run-time performance. You can also decrease processing time and save storage space by writing programs that take advantage of compiler optimizations.

The information that you find here contains guidelines only, not rules. Follow those suggestions that fit your needs.

This chapter provides the following information about optimizing your Compaq COBOL programs on the OpenVMS and Tru64 UNIX operating systems:

- Specifying optimization on the compiler command line (Alpha) ( Section 15.1)
- Specifying alignment of data for optimum performance (Alpha) ( Section 15.2)
- Using COMP data items for speed ( Section 15.3)
- Other ways to improve the performance of operations on numeric data ( Section 15.4)
- Choices in Procedure Division statements ( Section 15.5)
- I/O operations ( Section 15.6)
- Optimizing file design ( Section 15.7)
- Optimizing image activation ( Section 15.8)

# 15.1 Specifying Optimization on the Compiler Command Line (Alpha)

The Compaq COBOL compiler is a highly optimizing compiler. Full optimization is the default with the COBOL compiler command and usually results in improved run-time performance. You can specify the desired level of optimization by adding a value to the optimize option. The various formats are provided here to illustrate the similarity in processes across the supported platforms.

On OpenVMS Alpha systems, the /OPTIMIZE qualifier has the following forms:

`/OPTIMIZE[=LEVEL=n]`

`/OPTIMIZE=TUNE=keyword`

or

`/NOOPTIMIZE <>`

On Tru64 UNIX systems, the `-O` flag and the `-tune` flag specify optimization. The `-O` flag has the following form:

`-On`

The `-tune` flag has the following form:

`-tune keyword <>`

The `-tune` flag is the equivalent of the /OPTIMIZE=TUNE qualifier.

On both systems, n is a number ranging from 0 to 4, specifying the level of optimization. In brief, these levels mean the following:

- Level 0---Has the same effect as /NOOPTIMIZE. All optimizations are turned off, and the compiler does not check for unassigned variables.
- Level 1---Enables local optimizations, including instruction scheduling and recognition of common subexpressions.
- Level 2---Enables all level 1 optimizations, and adds some global optimizations (such as split lifetime analysis, code motion, strength reduction and test replacement, and code scheduling).
- Level 3---Enables all level 2 optimizations, and adds more global optimizations (such as decimal shadowing, integer multiplication and division expansion, using shifts, loop unrolling, and code replication to eliminate branches). All optimizations are turned on.
- Level 4---Is identical to level 3 for COBOL. This is the default if you specify optimize with no value, or if you compile without specifying any form of the optimize option on the command line.

/OPTIMIZE=TUNE=keyword (or `-tune keyword` specifies the kind of optimized code to be generated, allowing you to tune optimization to the specific Alpha hardware. The keyword can be any of the following:

- GENERIC---Generates and schedules code that will execute well for both generations (EV4 and EV5 and later) of Alpha processors. This is the default.
  This provides generally efficient code for those cases where both processor generations are likely to be used.
- HOST---Generates and schedules code optimized for the processor generation in use on the system being used for compilation.
- EV4---Generates and schedules code optimized for the 21064, 21064A, 21066, and 21068 implementations of the Alpha chip.
- EV5---Generates and schedules code optimized for the 21164 implementation of the Alpha chip. This processor generation is faster than EV4.
- EV56---Generates code for some 21164 chip implementations that use the byte and word manipulation instruction extensions of the Alpha architecture.
  Programs compiled with the EV56 keyword might incur run-time emulation overhead on EV4 and EV5 processors, but will still run correctly on OpenVMS Version 7.1 (or later) systems.
- EV6---Generates and schedules code for the 21264 chip implementation that uses the following extensions to the base Alpha instruction set: BWX (Byte/Word manipulation) and MAX (Multimedia) instructions, square root and FIX (Floating-point convert) instructions.
- EV67---Generates and schedules code for the 21264A chip implementation that uses the following extensions to the base Alpha instruction set: BWX (Byte/Word manipulation) and MAX (Multimedia) instructions, square root and FIX (Floating-point convert) instructions, and CIX (Count) instructions.
- EV68---Generates and schedules code that uses the following extensions to the base Alpha instruction set: BWX (Byte/Word manipulation) and MAX (Multimedia) instructions, square root and FIX (Floating-point convert) instructions, and CIX (Count) instructions.
- PCA56---Generates code for the 21164PC chip implementation that uses the byte and word manipulation instruction extensions and multimedia instruction extensions of the Alpha architecture.
  Programs compiled with the PCA56 keyword might incur run-time emulation overhead on EV4, EV5, and EV56 processors, but will still run correctly on OpenVMS Version 7.1 (or later) systems.

/ARCHITECTURE Qualifier

The /ARCHITECTURE= `option` qualifier (or `-arch` option on Tru64 UNIX) determines the type of Alpha chip code that will be generated for a particular program.

The /ARCHITECTURE qualifier uses the same options (keywords) as the /OPTIMIZE=TUNE qualifier, and their definitions are similar. However, their effects are not identical. The /OPTIMIZE=TUNE qualifier is primarily used by certain higher-level optimizations for instruction scheduling purposes, while the /ARCHITECTURE qualifier determines the type of code instructions generated for the program unit being compiled.

OpenVMS Version 7.1 and subsequent releases provide an operating system kernel that includes an instruction emulator. This emulator allows new instructions, not implemented on the host processor chip, to execute and produce correct results. All Alpha processors implement a core set of instructions. Certain Alpha processor versions include additional instruction extensions. Applications using emulated instructions will run correctly, but might incur significant software emulation overhead at run time.

The following /ARCHITECTURE options are supported:

- GENERIC---Generates code that is appropriate for all Alpha processor generations. This is the default.
  Programs compiled with the GENERIC option run all implementations of the Alpha architecture without any instruction emulation overhead.
- HOST---Generates code for the processor generation in use on the system being used for compilation.
  Programs compiled with this option on other implementations of the Alpha architecture may encounter instruction emulation overhead.
- EV4---Generates code for the 21064, 21064A, 21066, and 21068 implementations of the Alpha architecture.
  Programs compiled with the EV4 option run without instruction emulation overhead on all Alpha processors.
- EV5---Generates code for some 21164 chip implementations of the Alpha architecture that use only the base set of Alpha instructions (no extensions).
  Programs compiled with the EV5 option run without instruction emulation overhead on all Alpha processors.
- EV56---Generates code for some 21164 chip implementations that use the byte and word manipulation instruction extensions of the Alpha architecture.
  Programs compiled with the EV56 option may incur emulation overhead on EV4 and EV5 processors, but will still run correctly on OpenVMS Version 7.1 (or later) systems.
- EV6---Generates code for the 21264 chip implementation that uses the following extensions to the base Alpha instruction set: BWX (Byte/Word manipulation) and MAX (Multimedia) instructions, square root and FIX (Floating-point convert) instructions.
  Programs compiled with the EV6 option may incur emulation overhead on EV4, EV5, EV56, and PCA56 processors, but will still run correctly on OpenVMS Version 7.1 (or later) systems.
- EV67---Generates code for the 21264A chip implementation that uses the following extensions to the base Alpha instruction set: BWX (Byte/Word manipulation) and MAX (Multimedia) instructions, square root and FIX (Floating-point convert) instructions, and CIX (Count) instructions.
  Programs compiled with the EV67 option may incur emulation overhead on EV4, EV5, EV56, EV6, and PCA56 processors, but will still run correctly on OpenVMS Version 7.1 (or later) systems.
- EV68---Generates code that uses the following extensions to the base Alpha instruction set: BWX (Byte/Word manipulation) and MAX (Multimedia) instructions, square root and FIX (Floating-point convert) instructions, and CIX (Count) instructions.
  Programs compiled with the EV68 option may incur emulation overhead on EV4, EV5, EV56, EV6, EV7, and PCA56 processors, but will still run correctly on OpenVMS Version 7.1 (or later) systems.
- PCA56---Generates code for the 21164PC chip implementation that uses the byte and word manipulation instruction extensions and multimedia instruction extensions of the Alpha architecture.
  Programs compiled with the PCA56 option may incur emulation overhead on EV4, EV5, and EV56 processors, but still run correctly on OpenVMS Version 7.1 (or later) systems.

Note If a program contains declarations of non-EXTERNAL variables that are not referenced in the program, the Compaq COBOL compiler does not allocate those variables. These variables are not affected by /OPTIMIZE; they simply are not allocated. This feature improves both resource usage and run-time performance, and allows the use of site "copybooks" that have numerous standardized variables. Only those copybook variables that are referenced will be allocated within a given program.

Optimization and Debugging

You should disable optimization when you compile a program for debugging. Optimizations can cause unexpected and confusing behavior in a debugging session by changing the order of machine code. When you turn optimization off, a debugging session is expedited and simplified because the machine code is put in the same order as the lines in your source program.

On the Tru64 UNIX operating system, full optimization, corresponding to the -O4 or -O flag, is the default unless you specify the `-g` flag on the command line for debugging. The `-g` flag disables optimization entirely, and displays this message:

    cobol: Warning:...File not optimized; use -g3 if both
    optimization and debugging wanted     <>

On OpenVMS Alpha systems, in general, specify /NOOPTIMIZE if you specify /DEBUG when you compile a program. If you specify /DEBUG but omit any form of the /OPTIMIZE qualifier on the command line, the compiler issues the following informational message:

    %COBOL-I-DEBUGOPT, /NOOPTIMIZE is recommended with /DEBUG

Unlike other informational messages, which are turned off by default, this message is issued even if /WARNINGS=NOINFORMATION is in effect. You can turn it off by specifying any form of the /OPTIMIZE qualifier.

If you need to debug optimized code, refer to the OpenVMS Debugger Manual. <>

Other Effects of Optimization

An effect of optimization is larger object modules and longer compile times. These potential disadvantages are typically outweighed by faster run times.

To speed compilations during program development, you may want to compile with the noobject option when you want to check syntax.

When checking for correct execution, you may want to compile initially with no optimization, and later with optimization when the program is executing correctly.

If your program is not executing correctly and you suspect an optimization-related problem, try compiling it with no optimization or with level 2 optimization. The latter is a compromise that can often help, because it turns off some of the more aggressive optimizations, such as decimal shadowing.

Previous | Next | Contents | Index