Compaq COBOL
User Manual
Previous Contents Index

Chapter 12
Interprogram Communication

COBOL programs can communicate with each other, as well as with non-COBOL programs. Program-to-program communication is conducted by using one (or combinations) of the following:

This chapter includes the following information about interprogram communication:

12.1 Multiple COBOL Program Run Units

A multiple COBOL program run unit consists of either of the following:

Separately compiled programs can be concatenated in one source file, or can be written as separate source files.

12.1.1 Examples of COBOL Run Units

Example 12-1 shows a run unit with three separately compiled programs, none of which have contained programs. MAIN-PROGRAM ((1)) calls separate program SUB1 ((2)), that calls separate program SUB2 ((3)).

Example 12-1 Run Unit with Three Separately Compiled Programs 

  IDENTIFICATION DIVISION.               IDENTIFICATION DIVISION. 
  PROGRAM-ID. MAIN-PROGRAM. (1)           PROGRAM-ID.  SUB1.       (2)
  .                                      . 
  .                                      . 
  .                                      . 
  CALL SUB1.                             CALL SUB2. 
  .                                      . 
  .                                      . 
  .                                      . 
  
  STOP RUN.                              EXIT PROGRAM. 
  END PROGRAM MAIN-PROGRAM               END PROGRAM SUB1. 
 
                     IDENTIFICATION DIVISION. 
                     PROGRAM-ID.  SUB2.      (3)
                     . 
                     . 
                     . 
                     EXIT PROGRAM. 
                     END PROGRAM SUB2.

Note
A separately compiled program has a nesting level number of 1. If this program contains other source programs, it is the outermost containing program. A contained program has a nesting level number greater
than 1.

Example 12-2 shows a run unit with one main program ((4)) and two contained programs (SUB1 ((5)) is a directly contained program of MAIN-PROGRAM; SUB2 ((6)) is an indirectly contained program of MAIN-PROGRAM).

Example 12-2 Run Unit with a Main Program and Two Contained Programs 

                IDENTIFICATION DIVISION. 
                PROGRAM-ID.  MAIN-PROGRAM. (4)
                . 
                . 
                . 
                CALL SUB1. 
                . 
                . 
                . 
                STOP RUN. 
 
                IDENTIFICATION DIVISION. 
                PROGRAM-ID.  SUB1.       (5)
                . 
                . 
                . 
                CALL SUB2. 
                EXIT PROGRAM. 
 
                IDENTIFICATION DIVISION. 
                PROGRAM-ID.  SUB2.       (6)
                . 
                . 
                . 
                EXIT PROGRAM. 
        
                END PROGRAM  SUB2. 
                END PROGRAM  SUB1. 
                END PROGRAM MAIN-PROGRAM.

Example 12-3 shows a run unit with three separately compiled programs ((7), (10), and (11)). One of the separately compiled programs, MAIN-PROGRAM ((7)), has two directly contained programs, SUB1 and SUB2 ((8) and (9)).

Example 12-3 Run Unit with Three Separately Compiled Programs, One with Two Contained Programs 

                IDENTIFICATION DIVISION. 
                PROGRAM-ID.  MAIN-PROGRAM. (7)
                . 
                . 
                . 
                CALL SUB1. 
                CALL SUB2. 
                . 
                STOP RUN. 
 
                IDENTIFICATION DIVISION. 
                PROGRAM-ID.  SUB1.        (8)
                . 
                . 
                . 
                CALL SUB3. 
                EXIT PROGRAM. 
                END PROGRAM SUB1. 
               
                IDENTIFICATION DIVISION. 
                PROGRAM-ID.  SUB2.       (9)
                . 
                . 
                . 
                EXIT PROGRAM. 
                END PROGRAM  SUB2. 
                END PROGRAM MAIN-PROGRAM. 
 
                IDENTIFICATION DIVISION. 
                PROGRAM-ID.  SUB3.       (10)
                . 
                . 
                . 
                CALL SUB4. 
                . 
                . 
                . 
                STOP RUN. 
 
                IDENTIFICATION DIVISION. 
                PROGRAM-ID.  SUB4.       (11)
                . 
                . 
                . 
                EXIT PROGRAM.

12.1.2 Calling Procedures

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 */              
    )

Note
A Compaq COBOL program called MAIN will only interfere with main if it was compiled with the -names lowercase flag.

<>

12.2 COBOL Program Attributes

Any Compaq 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.

12.2.2 The EXTERNAL Clause

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.

Note
EXTERNAL files and data must be described identically in all programs in which they are defined.

12.3 Transferring Flow of Control

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

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 Compaq 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.

Note
A program cannot cancel itself nor can any program cancel the program that called it.

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.

Example 12-4 Execution Sequence of Nested CALL Statements 

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.

Example 12-5 Sequence of Messages Displayed 

 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.

12.3.3 The EXIT PROGRAM Statement

To return control to the calling program, the called subprogram executes an EXIT PROGRAM statement.

You can include more than one EXIT PROGRAM statement in a subprogram. However, if it appears in a consecutive sequence of imperative statements, the EXIT PROGRAM statement must appear as the last statement of the sequence. For example: 


IF A = B DISPLAY "A equals B", EXIT PROGRAM. 
 
READ INPUT-FILE    AT END DISPLAY "End of input file" 
                   PERFORM END-OF-FILE-ROUTINE 
                   EXIT PROGRAM.

If you do not include an EXIT PROGRAM statement in a subprogram, the compiler generates one at the end of the program.

On executing an EXIT PROGRAM statement in a called subprogram, control returns to the statement following the calling program's CALL statement or the first imperative statement in a NOT ON EXCEPTION clause specified for that CALL statement.

On executing an EXIT PROGRAM statement in a main program, the EXIT PROGRAM is ignored and control continues with the next statement.

Figure 12-2 shows how control is passed between programs.

Figure 12-2 Transfer of Control Flow from a Main Program to Multiple Subprograms

12.3.4 CALL Literal Versus CALL Data Name

CALL data name requires that all modules be specified to link the run unit. In Example 12-6 with 3 files (C1.COB, C2.COB, and C3.COB), there is no link-time reference to C3, but the C3 module must be explicitly included in the link of the run unit so that the C3 reference can be dynamically resolved at run-time.

Example 12-6 CALL Literal Versus CALL Data Name 

IDENTIFICATION DIVISION. 
PROGRAM-ID. C1. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 W1 PIC XX VALUE "C3". 
PROCEDURE DIVISION. 
P0. DISPLAY "***C1***". 
 CALL "C2". 
 CALL W1. 
 STOP RUN. 
 
IDENTIFICATION DIVISION. 
PROGRAM-ID. C2. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
PROCEDURE DIVISION. 
P0. DISPLAY "***C2***". 
 EXIT PROGRAM. 
 
IDENTIFICATION DIVISION. 
PROGRAM-ID. C3. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
PROCEDURE DIVISION. 
P0. DISPLAY "***C3***". 
 EXIT PROGRAM.

Results for OpenVMS: 


$ cobol c1,c2,c3 
$ link c1 
%LINK-W-NUDFSYMS, 1 undefined symbol: 
%LINK-I-UDFSYM,  C2 
$ link c1,c2 
$ run c1 
***C1*** 
***C2*** 
%COB-F-CALL_FAILED, call failed to find program C3 
$ link c1,c2,c3 
$ run c1 
***C1*** 
***C2*** 
***C3***

Results for Tru64 UNIX: 


 
csh> cobol c1.cob 
ld: 
Unresolved: 
c2 
cobol: Severe: Failed while trying to link. 
csh> cobol c1.cob c2.cob 
c1.cob: 
c2.cob: 
csh> a.out 
***C1*** 
***C2*** 
cobrtl: severe: call failed to find program C3 
csh> cobol c1.cob c2.cob c3.cob 
c1.cob: 
c2.cob: 
c3.cob: 
csh> a.out 
***C1*** 
***C2*** 
***C3***

12.4 Accessing Another Program's Data Division

In a multiple COBOL program run unit, a called subprogram can access some of its calling program's Data Division. The calling program controls how much of it will be accessible to the called subprogram in the following ways:

12.4.1 The USING Phrase

To access a calling program's Data Division, use a CALL statement in the calling program and a Procedure Division USING phrase in the called program. The USING phrases of both the CALL statement and the Procedure Division header must contain an equal number of data names. (See Figure 12-3.)

Figure 12-3 Accessing Another Program's Data Division

In Figure 12-3, when execution control transfers to SUB, it can access the four data items in the calling program by referring to the data names in its Procedure Division USING phrase. For example, the data names correspond as follows:
Data Name in MAINPROG
(Calling Program) 		Corresponding Data Name in SUB
(Called Subprogram)
A PART
B AMOUNT
C COLOR
D COST

The CALL statement can make data available to the called program by the following argument-passing mechanisms:

Note
A called COBOL subprogram must have arguments passed to it using BY REFERENCE, which is the default, or BY CONTENT. BY VALUE, OMITTED, and BY DESCRIPTOR are Compaq extensions and will not work as expected if passed to a COBOL program. These argument-passing mechanisms are necessary when calling Run-Time Library Routines and system service routines as described in Chapter 13.

The mechanism for each argument in the CALL statement USING phrase must be the same as the mechanism for each argument in the called program's parameter list.

If the BY REFERENCE phrase is either specified or implied for a parameter, the called program references the same storage area for the data item as the calling program. This mechanism ensures that the contents of the parameter in the calling program are always identical to the contents of the parameter in the called program.

If the BY CONTENT phrase is either specified or implied for a parameter, only the initial value of the parameter is made available to the called program. The called program references a separate storage area for the data item. This mechanism ensures that the called program cannot change the contents of the parameter in the calling program's USING phrase. However, the called program can change the value of the data item referenced by the corresponding data name in the called program's Procedure Division header.

Once a mechanism is established in a CALL statement, successive arguments default to the established mechanism until a new mechanism is used. For example: 


CALL "TESTPRO" USING ITEM-A 
  BY VALUE ITEM-B

Note that ITEM-A is passed using the BY REFERENCE phrase and that ITEM-B is passed using the BY VALUE phrase.

If the OMITTED phrase is specified for a parameter, the established call mechanism does not change.

One other mechanism of the CALL verb is the ability to use a GIVING phrase in the CALL statement. This allows the subprogram to return a value through the data item in the GIVING phrase. For example: 


CALL "FUNCTION" USING ITEMA ITEMB 
    GIVING ITEMC.

Values can also be returned through the BY REFERENCE parameter in the USING phrase. However, the GIVING phrase uses the return value by immediate value mechanism. Use of this mechanism requires that the GIVING result (ITEMC) be an elementary integer numeric data item with COMP, COMP-1, or COMP-2 usage and no scaling positions.

The RETURN-CODE special register provides an alternative mechanism for returning a value from a called program to the calling program.

The order in which USING identifiers appear in both calling and called programs determines the correspondence of single sets of data available to the called subprogram. The correspondence is by position, not by name.

Previous Next Contents Index