HP OpenVMS Systems Documentation

HP COBOL
User Manual

A COBOL main (driver) program calls subprograms (contained or separately compiled). Image execution begins and ends in the main program's Procedure Division. The program contains one or more CALL statements and is a calling program.

A COBOL subprogram is called by a main program or another subprogram. The subprogram may or may not contain CALL statements. If a subprogram contains a CALL statement, it is both a calling and a called program. If the subprogram does not contain a CALL statement, it is a called program only.

Special Code for Programs Called "main" (Tru64 UNIX)

On the Tru64 UNIX operating system, if you have a main program called main, that program preempts a COBOL Run-Time Library (RTL) initialization routine also called main. This RTL routine is needed to make a CALL data-name statement (or cobfunc, cobcall, cobcancel ) work correctly. Your program main must supply the necessary code by calling the cob_init routine in the RTL. The cob_init routine specification (in C) is as follows:

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

<>

12.2 COBOL Program Attributes

Any HP COBOL program can have the INITIAL clause in the PROGRAM-ID paragraph. Data and files in a COBOL program can have the EXTERNAL clause.

12.2.1 The INITIAL Clause

A COBOL program with an INITIAL clause is returned to its initial state whenever that program exits. This ensures that it will be in its initial state the next time it is called.

During this initialization process, all internal program data whose description contains a VALUE clause is initialized to that defined value. Any item whose description does not include a VALUE clause will be initialized, and contain an undefined value.

When an INITIAL clause is present and when the program is called, an implicit CLOSE statement executes for all files in the open mode associated with internal file connectors.

When an INITIAL clause is not present, the status of the files and internal program data are the same as when the called program was exited.

The initial attribute is attained by specifying the INITIAL clause in the program's PROGRAM-ID paragraph. For example:

IDENTIFICATION DIVISION.
PROGRAM-ID.  TEST-PROG  INITIAL.

Storage of data can be external or internal to the program in which the data is declared. A file connector can also be external or internal to the program in which it is defined.

External data or files can be referenced by every program in a run unit that describes that data or those files as external.

The EXTERNAL clause indicates that data or a file is external. This clause is specified only in File Description entries in the FILE SECTION or in Record Description entries in the WORKING-STORAGE Section. The EXTERNAL clause is one method of sharing data between programs. For example, in the following Working-Storage Section entry, the data items in RECORD-1 are available to any program in the image that also describes RECORD-1 and its data items as EXTERNAL:

01  RECORD-1 EXTERNAL.
    03  ITEMA  PIC X.
    03  ITEMB  PIC X(20).
    03  ITEMC  PIC 99.

You control a multiple program run unit sequence by executing the following:

• A controlling CALL statement in the calling program (main or subprogram)
• An EXIT PROGRAM statement in the called subprogram

Contained COBOL programs have additional communication mechanisms that are explained in Section 12.5.

12.3.1 The CALL Statement

A CALL statement transfers the run unit's flow of control from the calling program to the beginning of the called subprogram's Procedure Division. Refer to the HP COBOL Reference Manual for the CALL statement format.

The first time the called subprogram gains the flow of control, it is in its initial state. Thereafter, each time it is called its state is the same as the last exit from that program, except when: (1) the called program has the INITIAL clause, or (2) the calling program cancels the called program.

In COBOL programs, to call a routine named SPECIALROUTINE from an overlying COBOL program you might use:

    MOVE "SPECIALROUTINE" TO ROUTINE-NAME.
    CALL ROUTINE-NAME.

If you need to call SPECIALROUTINE from a program in another language, use cobcall or cobfunc .

12.3.2 Nesting CALL Statements

A called subprogram can itself transfer control flow after receiving control from a main program or another subprogram. This technique is known as CALL statement nesting. For example, Figure 12-1 shows a nested image that executes a series of three CALL statements from three separate programs.

Figure 12-1 Nesting CALL Statements

The MAINPROG, SUB1, and SUB2 programs in Example 12-4 illustrate their execution sequence by displaying a series of 12 messages on the default output device. Image execution begins in MAINPROG with message number 1. It ends in MAINPROG with message number 12. The image's message sequence is shown following the program listings.

IDENTIFICATION DIVISION.
*
* MAINPROG is a calling program only
*
PROGRAM-ID. MAINPROG.
ENVIRONMENT DIVISION.
DATA DIVISION.
PROCEDURE DIVISION.
BEGIN.
    DISPLAY " 1. MAINPROG has control first.                    ".
    DISPLAY " 2. MAINPROG transfers control to SUB1             ".
    DISPLAY "         upon executing the following CALL.        ".
    CALL "SUB1"
    DISPLAY "11. MAINPROG has control last.                     ".
    DISPLAY "12. MAINPROG terminates the entire image upon      ".
    DISPLAY "         execution of the STOP RUN statement.      ".
    STOP RUN.
IDENTIFICATION DIVISION.
*
* SUB1 is both a called and calling subprogram
*
*      It is called by MAINPROG
*
*      It then calls SUB2
PROGRAM-ID. SUB1.
ENVIRONMENT DIVISION.
DATA DIVISION.
PROCEDURE DIVISION.
BEGIN.
    DISPLAY " 3.      This is the entry point to SUB1.          ".
    DISPLAY " 4. SUB1 now has control.                          ".
    DISPLAY " 5. SUB1 transfers control to SUB2.                ".
    CALL "SUB2"
    DISPLAY " 9. SUB1 regains control                           ".
    DISPLAY "10.      after executing the following             ".
    DISPLAY "         EXIT PROGRAM statement.                   ".
    EXIT PROGRAM.
IDENTIFICATION DIVISION.
*
* SUB2 is called subprogram only
*
*      It is called by SUB1
*
PROGRAM-ID. SUB2.
ENVIRONMENT DIVISION.
DATA DIVISION.
PROCEDURE DIVISION.
BEGIN.
    DISPLAY " 6.      This is the entry point to SUB2.          ".
    DISPLAY " 7. SUB2 now has control.                          ".
    DISPLAY " 8. SUB2 returns control to SUB1                   ".
    DISPLAY "         after executing the following             ".
    DISPLAY "         EXIT PROGRAM statement.                   ".
    EXIT PROGRAM.
    END PROGRAM SUB2.
    END PROGRAM SUB1.
    END PROGRAM MAINPROG.

Example 12-5 shows the messages printed to the default output device when the programs in Example 12-4 are run.

 1. MAINPROG has control first.
 2. MAINPROG transfers control to SUB1
         upon executing the following CALL.
 3.      This is the entry point to SUB1.
 4. SUB1 now has control.
 5. SUB1 transfers control to SUB2.
 6.      This is the entry point to SUB2.
 7. SUB2 now has control.
 8. SUB2 returns control to SUB1
         after executing the following
         EXIT PROGRAM statement.
 9. SUB1 regains control
10.      after executing the following
         EXIT PROGRAM statement.
11. MAINPROG has control last.
12. MAINPROG terminates the entire image upon
         execution of the STOP RUN statement.