HP OpenVMS Systems Documentation

HP COBOL
User Manual

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

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.

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

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:

• The USING phrase in both the CALL statement and the Procedure Division header (see Section 12.4.1)
• The Linkage Section (see Section 12.4.2)
• The EXTERNAL clause (see Section 12.2.2)
• The GLOBAL clause (see Section 12.5.2)

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:

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

• REFERENCE---The address of (pointer to) the argument (arg) is passed to the calling program. This is the default mechanism.
• CONTENT---The address of a copy of the contents of arg is passed to the called program. Note that since a copy of the data is passed, the called program cannot change the original calling program data.
• VALUE---The value of arg is passed to the called program. If arg is a data name, its description in the Data Division can be as follows: (a) COMP usage with no scaling positions (the PICTURE clause can specify no more than nine digits) and (b) COMP-1 usage.
• On OpenVMS, DESCRIPTOR---The address of (pointer to) the data item's descriptor is passed to the called program. <>
  (Note that BY DESCRIPTOR is not supported by Tru64 UNIX. Refer to the HP COBOL Reference Manual, the CALL statement.)
• OMITTED---A value equivalent to BY VALUE 0 is passed to the called program. Note that OMITTED does not change the default mechanism.

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.