# Compaq COBOL
Reference Manual

Previous | Contents | Index

# 1.4 Sample Entry Format

The following format is used to describe most entries in this manual. Each COBOL division or major topic begins a new chapter and each entry begins on a new page. The entries are in functional or alphabetical order.

Entry-Name

Function
The function paragraph describes the function or the effect of the entry.

General Format
A general format shows the specific arrangement of elements in the entry. If there is more than one arrangement, the formats are numbered. All clauses (mandatory and optional) must be used in the sequence shown in the format. However, the syntax rules sometimes allow exceptions.

generic-term
Following the general format are definitions of its generic terms. These terms appear in the rules in italic type.

Syntax Rules
Syntax rules define or clarify the arrangement of words or elements. They can also impose further restrictions or relax restrictions implied by the general format.

General Rules
General rules define or clarify the meaning (or relationship of meanings) of an element or set of elements. They also define the semantics of an entry, describing its effects on program compilation or execution.

Technical Notes
Technical notes describe, in system-specific terms, any system-specific behavior, and any other Compaq COBOL behavior of note not described in the rules. They define relationships between the COBOL program and the operating system and its components.

Additional References
Additional references point to other relevant information in this manual, the Compaq COBOL User Manual, and other Compaq documentation sets.

Examples
Examples show the use of a statement, clause, or other entry. The Compaq COBOL User Manual contains other examples in application contexts.

The following example shows a general format:

Additional References

- Chapter 3, Identification Division
- Chapter 4, Environment Division
- Chapter 5, Data Division
- Chapter 6, Procedure Division

# Chapter 2
Organization of a COBOL Program

A COBOL source program is a syntactically correct set of COBOL statements that:

- Mark the beginning of the program
- Describe its physical environment
- Describe the data the program creates, receives as input, manipulates, and produces as output
- Specify the processing of the program's files and data

> ### identification-division

> represents a COBOL Identification Division.

> ### environment-division

> represents a COBOL Environment Division.

> ### data-division

> represents a COBOL Data Division.

> ### procedure-division

> represents a COBOL Procedure Division.

> ### source-program

> represents a contained (nested) COBOL source program. A COBOL source program may be nested; more than one source program may be present in a single source file.

> ### end-program-header

> represents a COBOL END PROGRAM header.

Syntax Rule

The end-program-header must be present if either:

1. The COBOL source program contains one or more other COBOL source programs.
2. The COBOL source program is contained within another COBOL source program.
3. The COBOL source program precedes another separately compiled program.

General Rules

1. The appropriate division header indicates the beginning of a division.
2. The following indicates the end of a division:
   1. Another division header
   2. An Identification Division header that indicates the start of another source program
   3. The end-program-header
   4. The physical position at which no further source lines occur
3. A COBOL source program may contain other COBOL source programs.
4. A COBOL source program that is directly or indirectly contained within another program is called a contained or nested program. It may reference certain resources in the containing program.
5. A separately compiled program has a nesting level number of 1. If this program contains other source-programs, it is the outermost containing program.
6. A contained program has a nesting level number greater than 1.

Additional References

- Identification Division
- Environment Division
- Data Division
- Procedure Division
- END PROGRAM Header

# 2.1 Program Structure

Figure 2-1 shows the basic structure of a COBOL program, which is organized in divisions, sections, paragraphs, sentences, and entries.

Figure 2-1 Structure of a COBOL Program

    IDENTIFICATION DIVISION.
       PROGRAM-ID. program-name.
       AUTHOR.
       INSTALLATION.
       DATE-WRITTEN.
       DATE-COMPILED.
       SECURITY.

    ENVIRONMENT DIVISION.
     CONFIGURATION SECTION.
       SOURCE-COMPUTER.
       OBJECT-COMPUTER.
       SPECIAL-NAMES.
     INPUT-OUTPUT SECTION.
       FILE-CONTROL.
       I-O-CONTROL.

    DATA DIVISION.
     SUBSCHEMA SECTION.
       subschema entries and keeplist entries
     FILE SECTION.
       file and record description entries
       report file description entries
       sort-merge file and record description entries
     WORKING-STORAGE SECTION.
       record description entries
     LINKAGE SECTION.
       record description entries
     REPORT SECTION.
       report and report group description entries.
     SCREEN SECTION.    (Alpha)
       screen description entries   (Alpha)

    PROCEDURE DIVISION.
     DECLARATIVES.
       sections
         paragraphs
           sentences
     END DECLARATIVES.
           .
           .
           .
       sections
         paragraphs
           sentences
           .
           .
           .
     END PROGRAM header

## 2.1.1 Division Header

A division header identifies and marks the beginning of a division. It is a specific combination of reserved words followed by a separator period. Division headers start in Area A.

Except for the COPY and REPLACE statements, and the END PROGRAM header (see Section 6.9 in Chapter 6), the statements, entries, paragraphs, and sections of a COBOL source program are grouped into four divisions in this order:

1. IDENTIFICATION DIVISION.
2. ENVIRONMENT DIVISION.
3. DATA DIVISION.
4. PROCEDURE DIVISION.

The end of a COBOL source program is indicated either by the END PROGRAM header ( Section 6.9) or by the end of that program's Procedure Division.

Only these items can immediately follow a division header:

- Another division header
- A section header
- A paragraph header or paragraph-name
- A comment line
- A blank line
- A DECLARATIVES header for the USE procedure sections (after the PROCEDURE DIVISION header only)
- A PROGRAM-ID paragraph (after the IDENTIFICATION DIVISION header only)

Only this item can immediately follow a DECLARATIVES header:

- A section header for a USE procedure

Note The PROCEDURE DIVISION header can contain a USING and GIVING phrase. (See Section 6.8.)

## 2.1.2 Section Header

A section header identifies and marks the beginning of a section in the Environment, Data, and Procedure Divisions. In the Environment and Data Divisions, a section header is a specific combination of reserved words followed by a separator period. In the Procedure Division, a section header is a user-defined word followed by the word SECTION (and an optional segment-number). A separator period always follows a section header. Section headers start in Area A.

The valid section headers follow for each division.

In the Environment Division:

> CONFIGURATION SECTION.
> INPUT-OUTPUT SECTION.

In the Data Division:

> FILE SECTION.
> WORKING-STORAGE SECTION.
> LINKAGE SECTION.
> REPORT SECTION.
> SCREEN SECTION. (Alpha)

In the Procedure Division:

> user-name SECTION [ segment-number ].

Only these items can immediately follow a section header:

- A division header
- Another section header
- A paragraph header or paragraph-name
- A comment line
- A USE statement (in the DECLARATIVES part of the Procedure Division only)
- A blank line
- A DATA DIVISION entry (in the Data Division)

## 2.1.3 Paragraph, Paragraph Header, Paragraph-Name

A paragraph consists of a paragraph header or paragraph-name (depending on the division) followed by zero, one, or more entries (or sentences).

A paragraph header is a reserved word followed by a separator period. Paragraph headers identify paragraphs in the Identification and Environment Divisions.

The paragraph headers are as follows:

Identification Division | Environment Division
--- | ---
PROGRAM-ID. | SOURCE-COMPUTER.
AUTHOR. | OBJECT-COMPUTER.
INSTALLATION. | SPECIAL-NAMES.
DATE-WRITTEN. | FILE-CONTROL.
DATE-COMPILED. | I-O-CONTROL.
SECURITY. |
OPTIONS. |

A paragraph-name is a user-defined word followed by a separator period. Paragraph-names identify paragraphs in the Procedure Division.

Paragraph headers and paragraph-names start in Area A of any line after the first line of a division or section.

The first entry or sentence of a paragraph begins either:

- On the same line as the paragraph header or paragraph-name
- In Area B of the next nonblank line that is not a comment line

Successive sentences or entries begin in Area B of either:

- The same line as the preceding entry or sentence
- The next nonblank line that is not a comment line

# 2.2 Data Division Entries

A Data Division entry begins with a level indicator or level-number and is followed, in order, by:

1. A space
2. The name of a data item, file connector, or screen item
3. A sequence of independent descriptive clauses
4. A separator period

The level indicators are as follows:

- FD (for file description entries)
- SD (for sort-merge file description entries)
- RD (for report file description entries)

Level indicators can begin anywhere to the right of Area A.

Entries that begin with level-numbers are called either data description or screen description entries, depending on their context. The level-number values are 01 to 49, 66, 77, and 88 for data description items and 01 to 49 for screen description entries. Level-numbers 01 to 09 can be represented as one- or two-digit numbers.

All data description entries and screen description entries can begin anywhere to the right of Margin A. However, indentation has no effect on level-number magnitude; it merely enhances readability.

# 2.3 Declaratives

Declaratives specify USE procedures to be executed only when certain conditions occur. You must write USE procedures at the beginning of the Procedure Division in consecutive sections. The key word DECLARATIVES begins the DECLARATIVES part of the Procedure Division; the pair of key words END DECLARATIVES ends it. Each of these reserved word phrases must be on a line by itself, starting in Area A; and be followed by a separator period. For example:

    PROCEDURE DIVISION.
    DECLARATIVES.
    IOERROR SECTION.
    USE AFTER ... .
    PAR-1.
        .
        .
        .
    END DECLARATIVES.

When you specify USE procedures, you must divide the remainder of the Procedure Division into sections.

# Chapter 3
Identification Division

# 3.1 Function

The Identification Division marks the beginning of a COBOL program. It also identifies a program and its source listing.

* These paragraphs are not described in individual entries; they follow the same format as the AUTHOR paragraph and are for documentation only.

Syntax Rules

1. The Identification Division must be the first entry in a COBOL program.
2. The Identification Division must begin with the IDENTIFICATION DIVISION header. The header consists of the reserved words IDENTIFICATION DIVISION followed by a separator period.
3. The PROGRAM-ID paragraph must immediately follow the IDENTIFICATION DIVISION header.

## 3.1.1 PROGRAM-ID Paragraph

Function

The PROGRAM-ID paragraph identifies a program and assigns selected program attributes.

General Format

> ### program-name

> is a user-defined word that names the program.

Syntax Rules

1. The PROGRAM-ID paragraph must be present in every program.
2. program-name must contain 1 to 31 characters and follow the rules for user-defined words.
3. Programs contained within a separately compiled program must have a unique program-name.
4. The optional COMMON clause may be used only if the program is contained within another program.
5. ident-string must be a nonnumeric literal 1 to 31 characters in length.
6. The optional IDENT clause cannot be used in a contained program.

General Rules

1. program-name is a user-defined word that identifies a COBOL program and its source listing. It appears as the first word in the first line of every page in the compiler source listing.
2. program-name represents the object program entry point.
3. If an executable image includes more than one separately compiled program, each separately compiled program must have a unique program-name.
4. The COMMON clause specifies a common program. A common program is contained within another program but may be called from programs other than that directly containing it.
5. Files associated with a called program's internal file connectors are not in the open mode:
   1. The first time the program is called
   2. The first time the program is called after execution of a CANCEL statement referring to the program
   3. Every time the program is called, if it has the INITIAL attribute
   On all other entries, the status and positioning of files in a called program are the same as when the program last exited.
6. The INITIAL clause specifies an initial program. Whenever the program is called, it and any programs contained within it are placed in their initial state, and the internal data in each program is initialized.
7. On OpenVMS, the IDENT clause specifies a literal string that is used for identification purposes. This string is written to the object file as the "module version."
   When the /ANALYSIS_DATA qualifier is included on the COBOL command, the string is written to the analysis data file as the module ident. <>
8. On Tru64 UNIX systems, program-name is case-sensitive. By default, program-name is converted to lowercase for all separately compiled program units. Any calls from other programs (Compaq COBOL as well as other languages) must specify the routine to be called in lowercase.
   However, if the `names` option is set to `uppercase` on the command line, calls from other programs must specify the routine to be called in uppercase. If the `names` option is set to `as_is` , the effect on program-name is as if `uppercase` were specified. (The `as_is` setting is used for calling non-COBOL programs with mixed case.) <>

Additional Reference

See Section 6.2.6, Scope of Names.

Examples

    PROGRAM-ID. PROGA.

    PROGRAM-ID. SUBR1 INITIAL.

    PROGRAM-ID. COMPUTE-PAY WITH IDENT "JOB6a-V1.1".   (OpenVMS)

    PROGRAM-ID.
        WRITEMASTERREPORT.

    PROGRAM-ID. PAYROLL IS COMMON.

## 3.1.2 AUTHOR

Function

The AUTHOR paragraph is for documentation only.

> ### comment-entry

> is a user-supplied comment about the program's author.

Syntax Rules

1. comment-entry can consist of any combination of characters from the computer character set.
2. comment-entry can span several lines in Area B. However, they cannot be continued by using a hyphen in the indicator area.
3. The end of comment-entry is the line before the next entry in Area A.

Examples

    AUTHOR. JOHN SMITH.

    AUTHOR. This program was written by John Smith
                                        1226 Main St.
                                        Merrimack, NH 03054

    AUTHOR.

## 3.1.3 DATE-COMPILED

Function

The DATE-COMPILED paragraph provides the compilation date in the source program listing file.

> ### comment-entry

> is user-supplied information about the date compiled.

Syntax Rules

1. comment-entry can consist of any combination of characters from the computer character set.
2. comment-entry can span several lines in Area B. However, it cannot be continued by using a hyphen in the indicator area.
3. The end of comment-entry is the line before the next entry in Area A.

General Rule

The paragraph-name DATE-COMPILED causes the current date to be inserted in your source program listing during compilation. Therefore, if a DATE-COMPILED paragraph is present in your source program, it will be replaced with a paragraph of the following form:

DATE-COMPILED. dd-mmm-yyyy.

## 3.1.4 OPTIONS (Alpha)

Function

The OPTIONS paragraph specifies information for use by the compiler in generating executable code for a source unit.

> ### arithmetic-clause

> specifies the method used in developing the intermediate results. The format is:

Syntax Rule

The period appearing in the general format after the arithmetic-clause may be omitted if the arithmetic-clause is not specified.

General Rules

1. The ARITHMETIC clause in the OPTIONS paragraph applies to the source element in which it is specified and to all source elements contained in that source element unless overridden by an ARITHMETIC clause in an OPTIONS paragraph in a contained source element.
2. If the NATIVE phrase is specified, the techniques used in handling arithmetic expressions and arithmetic statements shall be those specified for native arithmetic in the appendix on compatibility in the Compaq COBOL User Manual.
3. If the STANDARD phrase is specified, the techniques used in handling arithmetic expressions and arithmetic statements shall be those specified for standard arithmetic in the ANSI Standard for COBOL. (Refer to the appendix on compatibility in the Compaq COBOL User Manual.)
4. If the ARITHMETIC clause is not specified in this source element or a containing source element, it is as if the ARITHMETIC clause were specified with the NATIVE phrase. <>

Previous | Next | Contents | Index