# Compaq COBOL

# User Manual

Order Number: AA--Q2G1G--TK

# November 2002

This manual provides information to help you develop Compaq COBOL programs for the OpenVMS Alpha, OpenVMS VAX, and Compaq Tru64 UNIX platforms.

Revision/Update Information: This manual supersedes the Compaq COBOL User Manual, Version 2.7 and the VAX COBOL User Manual, Version 5.4, as well as the online-only Compaq COBOL User Manual, Version 2.7 and Version 5.7.

Operating System and Version: OpenVMS Alpha Version 6.2 or higher;
OpenVMS VAX Version 6.2 or higher;
Tru64 UNIX Version 5.0 or higher

Software Version:
Compaq COBOL for OpenVMS Alpha Version 2.8;
Compaq COBOL for Tru64 UNIX Version 2.8;
Compaq COBOL for OpenVMS VAX Version 5.7

Compaq Computer Corporation Houston, Texas

© 2002 Compaq Information Technologies Group, L.P.

COMPAQ, the Compaq logo, OpenVMS, POLYCENTER, Tru64, VAX, and VMS, are trademarks of compaq Information Technologies Group, L.P. in the U.S. and/or other countries.

Motif, UNIX and X/Open are trademarks of The Open Group in the U.S. and/or other countries.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

None of Compaq, Hewlett-Packard Company ("HP") or any other direct or indirect subsidiary of HP shall be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq or HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6297

This manual is available on CD-ROM.

Contents | Index

# Preface

This manual provides information to help you develop Compaq COBOL programs for the OpenVMS Alpha, OpenVMS VAX, and Tru64 UNIX platforms.

The new name Compaq COBOL, unmodified, refers to the COBOL language on three platforms:

> OpenVMS Alpha
> OpenVMS VAX
> Tru64 UNIX

The three product names in full are:

> Compaq COBOL for OpenVMS Alpha (formerly DEC COBOL or DIGITAL COBOL)
> Compaq COBOL for OpenVMS VAX (formerly VAX COBOL or DIGITAL VAX COBOL)
> Compaq COBOL for Tru64 UNIX (formerly DEC COBOL or DIGITAL COBOL for DIGITAL UNIX or DEC OSF/1)

Any references to the former names in product documentation or other components should be construed as references to the Compaq COBOL names.

# Intended Audience

This manual is intended for experienced applications programmers who have a thorough understanding of the COBOL language. Some familiarity with your operating system is also recommended. This is not a tutorial manual.

If you are a new COBOL user, you may need to read introductory COBOL textbooks or take COBOL courses. Additional prerequisites are described at the beginning of each chapter or appendix, if appropriate.

# Document Structure

This manual is organized as follows:

- Chapter 1 describes how to create, compile, link, and run Compaq COBOL programs and how to develop programs at the command level.
- Chapter 2 describes how the Compaq COBOL compiler stores, represents, moves, and manipulates numeric data.
- Chapter 3 describes how the Compaq COBOL compiler stores, represents, moves, and manipulates nonnumeric data.
- Chapter 4 describes how to define, initialize, and access tables.
- Chapter 5 describes how to perform text manipulation using the STRING, UNSTRING, and INSPECT statements.
- Chapter 6 describes I/O services provided by the operating systems, including record management services.
- Chapter 7 describes how to include exception handling routines in Compaq COBOL programs.
- Chapter 8 describes file sharing and record locking for sequential, relative, and indexed files.
- Chapter 9 describes how to sort and merge files using the SORT and MERGE statements.
- Chapter 10 describes how to produce printed reports.
- Chapter 11 describes screen handling using the Compaq COBOL ACCEPT and DISPLAY statements.
- Chapter 12 describes how Compaq COBOL programs communicate with each other or with non-COBOL programs through the CALL statement and external data.
- Chapter 13 describes the use of Compaq COBOL in the OpenVMS Common Language Environment.
- Chapter 14 describes how to use the REFORMAT utility, which converts terminal format source programs to conventional ANSI format and converts conventional ANSI format source programs to terminal format.
- Chapter 15 presents guidelines for using the Compaq COBOL compiler optimization features.
- Chapter 16 describes how to use compile-time and run-time features to optimize the use of system resources while also maximizing run-time performance.
- Appendix A contains a list of Compaq COBOL specificatons and limits on the Tru64 UNIX and OpenVMS systems.
- Appendix B describes compatibility and portability issues between Compaq COBOL for OpenVMS VAX and Compaq COBOL on the Tru64 UNIX and OpenVMS Alpha systems.
- Appendix C describes optional programming productivity tools available on OpenVMS systems and Tru64 UNIX systems.
- Appendix D describes porting assistance for migrating applications between other COBOL compilers and Compaq COBOL.
- The Index indexes and references terms in this manual.

# Associated Documents

The following documents contain additional information directly related to various topics in this manual:

Compaq COBOL Reference Manual

This manual describes the concepts and rules of the Compaq COBOL programming language under the supported operating systems.

Release Notes

Consult the Compaq COBOL release notes for your installed version for late corrections and new features.

On the OpenVMS operating systems, the release notes are in:

> SYS$HELP:COBOLnnn.RELEASE_NOTES (ASCII text)
> SYS$HELP:COBOLnnn_RELEASE_NOTES.PS
> where nnn is the version and release number, for example, 028 for Version 2.8.

On the Tru64 UNIX operating system, the release notes are in:

> /usr/lib/cmplrs/cobol/relnotes

Compaq COBOL for OpenVMS Alpha Systems Installation Guide

This manual provides information on how to install Compaq COBOL on the OpenVMS Alpha operating system.

Compaq COBOL for OpenVMS VAX Systems Installation Guide

This manual provides information on how to install Compaq COBOL on the OpenVMS VAX operating system.

Compaq COBOL for Tru64 UNIX Systems Installation Guide

This manual provides information on how to install Compaq COBOL on the Tru64 UNIX operating system.

Compaq COBOL DBMS Database Programming Manual

This manual provides information on using Compaq COBOL for database programming with Oracle CODASYL DBMS on the OpenVMS Alpha and OpenVMS VAX operating systems.

The OpenVMS Documentation Set

This set contains information about using the features of the OpenVMS Alpha and OpenVMS VAX operating systems and their tools, including the OpenVMS Debugger.

The DECset Documentation

This documentation contains information about using DECset.

The Tru64 UNIX Documentation Set

This set contains information about using the features of the Tru64 UNIX operating system and its tools.

# Related Documents

For additional information about OpenVMS products and services, access the following World Wide Web address:

    http://www.compaq.com/

# Conventions

# References

The following table shows certain references and their respective meanings in this manual:

Reference | Meaning
--- | ---
OpenVMS | OpenVMS Alpha or OpenVMS VAX operating system
Tru64 UNIX | Tru64 UNIX operating system
DECset | DECset for OpenVMS

Tru64 UNIX was formerly known as DEC OSF/1 or as DIGITAL UNIX. Compaq COBOL was formerly known as DIGITAL COBOL or DEC COBOL. Compaq COBOL for OpenVMS VAX was formerly known as VAX COBOL or as DIGITAL VAX COBOL.

# Acknowledgment

COBOL is an industry language and is not the property of any company or group of companies, or of any organization or group of organizations.

No warranty, expressed or implied, is made by any contributor or by the CODASYL COBOL Committee as to the accuracy and functioning of the programming system and language. Moreover, no responsibility is assumed by any contributor, or by the committee, in connection therewith.

The authors and copyright holders of the copyrighted material used herein are as follows: FLOW-MATIC (trademark of Unisys Corporation), Programming for the UNIVAC (R) I and II, Data Automation Systems, copyrighted 1958, 1959, by Unisys Corporation; IBM Commercial Translator Form No. F28-8013, copyrighted 1959 by IBM; FACT, DSI 27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell.

They have specifically authorized the use of this material, in whole or in part, in the COBOL specifications. Such authorization extends to the reproduction and use of COBOL specifications in programming manuals or similar publications.

# How to Order Additional Documentation

Visit the following World Wide Web address for information about how to order additional documentation:

    http://www.openvms.compaq.com/doc/

# Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet | openvmsdoc@hp.com
Mail | Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

# Chapter 1
Developing Compaq COBOL Programs

Compaq COBOL is a family of powerful COBOL compilers produced by Compaq Computer Corporation. Compaq COBOL operates comfortably in the Compaq common language environment; on Alpha, it is based on GEM, which is the highly advanced code generator and optimizer that Compaq uses in its Alpha family of languages, which includes COBOL, C, C++, FORTRAN, BASIC, Ada, and PASCAL. In addition to standard COBOL features, Compaq COBOL includes extensions that make new application development efficient and effective, with features helpful in porting legacy COBOL programs to OpenVMS Alpha and Tru64 UNIX systems.

Developing software applications with Compaq COBOL will be a familiar process. You set up your development environment, create your source, compile, link, and run. A few of the specific tasks are:

- Choosing a reference format: terminal or ANSI
- Carefully considering Alpha architecture system resources; for example, you might invest more system resources at compile time to get faster execution at run time
- Using various system-independent features for program development

# 1.1 Developing Programs on Tru64 UNIX

This section briefly describes the Tru64 UNIX commands (commands used at the operating system prompt) that you use to create, compile, link, and run Compaq COBOL programs on Tru64 UNIX systems.

## 1.1.1 Creating a Compaq COBOL Program on Tru64 UNIX

Use a text editor, such as `vi` or `emacs` , to create and revise your source files. For instance, to edit the file `prog1.cob` using the `vi` editor, type:

    % vi prog1.cob

Figure 1-1 shows the basic steps in Compaq COBOL program development on Tru64 UNIX systems.

Figure 1-1 Commands for Developing Compaq COBOL Programs on Tru64 UNIX

When naming a source file, choose one of the four file name extensions that the `cobol` compiler recognizes as COBOL file suffixes. These suffixes are:

> .cob
> .COB
> .cbl
> .CBL

Table 1-1 shows other file name suffixes.

Table 1-1 Other File Name Suffixes
Suffix | Description
--- | ---
`.c` | Identifies C language files passed to the C compiler driver `cc` , which performs additional command line parsing before invoking the C language compiler.
`.s` | Identifies assembler files passed to `cc` . Compaq COBOL does not generate .s files.
`.o` | Identifies object files passed to `cc` , which are in turn passed to `ld` .
`.a` | Identifies archive object libraries passed to `cc` , which are in turn passed to `ld` . All routines in the specified object library will be searched during linking to resolve external references. This is one method of specifying special libraries for which the `cobol` command does not automatically search.
`.so` | Identifies shared object libraries passed to `cc` , which are in turn passed to `ld` . All routines in the specified object library will be searched during linking to resolve external references. This is one method of specifying special libraries for which the `cobol` command does not automatically search.

The following `cobol` command compiles the program named `prog1.cob` and automatically uses the linker `ld` to link the main program into an executable program file named `a.out` (the name used if you do not specify a name):

    % cobol prog1.cob

The `cobol` command automatically passes a standard default list of Tru64 UNIX and Compaq COBOL libraries to the `ld` linker. If all external routines used by a program reside in these standard libraries, additional libraries or object files are not specified on the `cobol` command line.

If your path definition includes the directory containing `a.out` , you can run the program by simply typing its name:

    % a.out

If the executable image is not in your current directory path, specify the directory path in addition to the file name.

The COPY Statement and Libraries

As you write a program, you can use the COPY statement in your source program to include text from another file. With the COPY statement, separate programs can share common source text kept in libraries, reducing development and testing time as well as storage. The Compaq COBOL Reference Manual explains how to use the COPY statement.

Special Considerations for Routines Named "main"

If you have a program or routine named "main," declared either in a Compaq COBOL or other module, your application may not work correctly. The Compaq COBOL library contains a routine named "main," which initializes the run-time environment for the CALL by data name statements, extended ACCEPT and DISPLAY statements, and some error handling. When your application also declares a "main," your routine preempts the Compaq COBOL routine, and the run-time initialization is not performed.

Compaq recommends that you not name a Compaq COBOL program "main."

If you have a C routine named "main," you can work around this problem by having the "main" routine directly call the Compaq COBOL initialization routine, cob_init. The cob_init routine interface (in C) is as follows:

       void cob_init (         /* init the RTL */
           int argc,           /* argument count */
           char **argv,        /* arguments */
           char **envp         /* environment variable pointers */ )

## 1.1.2 Compiling a Compaq COBOL Program on Tru64 UNIX

Compilation does the following for you:

- Detects errors in your program syntax
- Displays compiler messages on your terminal screen
- Generates machine language instructions from valid source statements
- Groups the instructions into an object module for the linker `ld`

To compile your program, use the `cobol` command.

The COBOL Command Driver

The `cobol` command invokes a compiler driver that is the actual user interface to the Compaq COBOL compiler. It accepts a list of command flags and file names and causes one or more processors (compiler, assembler, or linker) to process each file.

After the Compaq COBOL compiler processes the appropriate files to create one or more object files, the compiler driver passes a list of files, certain flags, and other information to the `cc` compiler. After the `cc` compiler (the default C compiler on your system) processes relevant files and information, it passes certain information (such as `.o` object files) to the `ld` linker. The `cobol` command executes each processor; if any processor returns other than normal status, further processing is discontinued and the Compaq COBOL compiler displays a message identifying the processor (and its returned status, in hexadecimal) before terminating its own execution.

### 1.1.2.1 Format of the COBOL Command on Tru64 UNIX

The `cobol` command has the following format:

`cobol [-flags [options]]... filename[.suffix] [filename[.suffix]]... [-flags [options]]...`

> ### -flags [options]

> Indicates either special actions to be performed by the compiler or linker, or special properties of input or output files. For details about command-line flags, see Section 1.1.2.2. If you specify the `-l` string flag (which indicates libraries to be searched by the linker) or an object library file name, place it after the file names and after other flags.

> ### filename.suffix

> Specifies the source files containing the program units to be compiled, where the file name has a suffix that indicates the type of file used. The recognized COBOL suffix characters are `.cob` , `.COB` , `.cbl` , and `.CBL` .

> Note that the compiler driver checks for a valid suffix on filename. If you omit suffix, or if it is not one of the types recognized by the `cobol` command, the file is assumed to be an object file and is passed directly to the linker.

An example `cobol` command line would be:

    % cobol -v test.cob pas.o

This command specifies the following:

- The `-v` flag displays the compilation and link passes with their arguments and files, including the libraries passed to `ld` .
- The file `test.cob` is passed to the Compaq COBOL compiler for compilation. The resulting object file is then linked.
- The object file `pas.o` is passed directly to the linker.

As an additional example, you might find that your compiler command lines are getting rather long, as shown in the following example:

    % cobol -rsv foreign_extensions -flagger high_fips -warn information zeroes.cob

To work around this, you may truncate compiler flag options (arguments) to their shortest unambiguous form, as follows:

    % cobol -rsv for -flagger high -warn info zeroes.cob

Next | Contents | Index