CALL statement

The CALL statement transfers control from one object program to another within the run unit.

The program containing the CALL statement is the calling program; the program identified in the CALL statement is the called subprogram. Called programs can contain CALL statements; however, only programs defined with the RECURSIVE clause can execute a CALL statement that directly or indirectly calls itself.

Format

exception-phrases

not-exception-phrase

identifier-1, literal-1

literal-1 must be an alphanumeric literal. identifier-1 must be an alphanumeric, alphabetic, or numeric data item described with USAGE DISPLAY such that its value can be a program-name.

The rules of formation for program-names are dependent on the PGMNAME compiler option. For details, see the discussion of program-names in PROGRAM-ID paragraph and also the description of PGMNAME in the Enterprise COBOL Programming Guide.

Usage note: Do not specify the name of a class or method in the CALL statement.

procedure-pointer-1

Must be defined with USAGE IS PROCEDURE-POINTER and must be set to a valid program entry point; otherwise, the results of the CALL statement are undefined.

After a program has been canceled by COBOL, released by PL/I or C, or deleted by assembler, any procedure-pointers that had been set to that program's entry point are no longer valid.

function-pointer-1

Must be defined with USAGE IS FUNCTION-POINTER and must be set to a valid function or program entry point; otherwise, the results of the CALL statement are undefined.

After a program has been canceled by COBOL, released by PL/I or C, or deleted by the assembler, any function-pointers that had been set to that function or program's entry point are no longer valid.

When the called subprogram is to be entered at the beginning of the PROCEDURE DIVISION, literal-1 or the contents of identifier-1 must specify the program-name of the called subprogram.

When the called subprogram is entered through an ENTRY statement, literal-1 or the contents of identifier-1 must be the same as the name specified in the called subprogram's ENTRY statement.

For information about how the compiler resolves calls to program-names found in multiple programs, see Conventions for program-names.

USING phrase

The USING phrase specifies arguments that are passed to the target program.

Include the USING phrase in the CALL statement only if there is a USING phrase in the PROCEDURE DIVISION header or the ENTRY statement through which the called program is run. The number of operands in each USING phrase must be identical.

For more information about the USING phrase, see The PROCEDURE DIVISION header.

The sequence of the operands in the USING phrase of the CALL statement and in the corresponding USING phrase in the called subprogram's PROCEDURE DIVISION header or ENTRY statement determines the correspondence between the operands used by the calling and called programs. This correspondence is positional.

The values of the parameters referenced in the USING phrase of the CALL statement are made available to the called subprogram at the time the CALL statement is executed. The description of the data items in the called program must describe the same number of character positions as the description of the corresponding data items in the calling program.

The BY CONTENT, BY REFERENCE, and BY VALUE phrases apply to parameters that follow them until another BY CONTENT, BY REFERENCE, or BY VALUE phrase is encountered. BY REFERENCE is assumed if you do not specify a BY CONTENT, BY REFERENCE, or BY VALUE phrase prior to the first parameter.

BY REFERENCE phrase

If the BY REFERENCE phrase is either specified or implied for a parameter, the corresponding data item in the calling program occupies the same storage area as the data item in the called program.

identifier-2: Can be any data item of any level in the DATA DIVISION. identifier-2 cannot be a function-identifier.
If it is defined in the LINKAGE SECTION or FILE SECTION, you must have already provided addressability for identifier-2 prior to invocation of the CALL statement. You can do this by coding either one of the following: SET ADDRESS OF identifier-2 TO pointer or PROCEDURE/ENTRY USING.
file-name-1: A file-name for a QSAM file. See Passing data in the Enterprise COBOL Programming Guide for details on using file-name with the CALL statement.
ADDRESS OF identifier-2: identifier-2 must be a level-01 or level-77 item defined in the LINKAGE SECTION.
OMITTED: Indicates that no argument is passed.

BY CONTENT phrase

If the BY CONTENT phrase is specified or implied for a parameter, the called program cannot change the value of this parameter as referenced in the CALL statement's USING phrase, though 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. Changes to the parameter in the called program do not affect the corresponding argument in the calling program.

identifier-3

Can be any data item of any level in the DATA DIVISION. identifier-3 cannot be a function identifier or an unbounded group.

If defined in the LINKAGE SECTION or FILE SECTION, you must have already provided addressability for identifier-3 prior to invocation of the CALL statement. You can do this by coding one of the following phrases:

SET ADDRESS OF identifier-3 TO pointer
PROCEDURE DIVISION USING
ENTRY USING

literal-2

Can be:

An alphanumeric literal
A figurative constant (except ALL literal or NULL/NULLS)
A DBCS literal
A national literal

LENGTH OF special register

For information about the LENGTH OF special register, see LENGTH OF.

ADDRESS OF identifier-3

identifier-3 must be a data item of any level except 66 or 88 defined in the LINKAGE SECTION, the WORKING-STORAGE SECTION, or the LOCAL-STORAGE SECTION.

OMITTED

Indicates that no argument is passed.

For alphanumeric literals, the called subprogram should describe the parameter as PIC X(n) USAGE DISPLAY, where n is the number of characters in the literal.

For DBCS literals, the called subprogram should describe the parameter as PIC G(n) USAGE DISPLAY-1, or PIC N(n) with implicit or explicit USAGE DISPLAY-1, where n is the length of the literal.

For national literals, the called subprogram should describe the parameter as PIC N(n) with implicit or explicit USAGE NATIONAL, where n is the length of the literal.

BY VALUE phrase

The BY VALUE phrase applies to all arguments that follow until overridden by another BY REFERENCE or BY CONTENT phrase.

If the BY VALUE phrase is specified or implied for an argument, the value of the argument is passed, not a reference to the sending data item. The called program can modify the formal parameter that corresponds to the BY VALUE argument, but any such changes do not affect the argument because the called program has access to a temporary copy of the sending data item.

Although BY VALUE arguments are primarily intended for communication with non-COBOL programs (such as C), they can also be used for COBOL-to-COBOL invocations. In this case, BY VALUE must be specified or implied for both the argument in the CALL USING phrase and the corresponding formal parameter in the PROCEDURE DIVISION USING phrase.

identifier-4

Must be an elementary data item in the DATA DIVISION. It must be one of the following items:

Binary (USAGE BINARY, COMP, COMP-4, or COMP-5)
Floating point (USAGE COMP-1 or COMP-2)
Function-pointer (USAGE FUNCTION-POINTER)
Pointer (USAGE POINTER)
Procedure-pointer (USAGE PROCEDURE-POINTER)
Object reference (USAGE OBJECT REFERENCE)
One single-byte alphanumeric character (such as PIC X or PIC A)
One national character (PIC N), described as an elementary data item of category national.

The following items can also be passed BY VALUE:

Reference-modified item of USAGE DISPLAY and length 1
Reference-modified item of USAGE NATIONAL and length 1
SHIFT-IN and SHIFT-OUT special registers
LINAGE-COUNTER special register when it is USAGE BINARY

ADDRESS OF identifier-4

identifier-4 must be a data item of any level except 66 or 88 defined in the LINKAGE SECTION, the WORKING-STORAGE SECTION, or the LOCAL-STORAGE SECTION.

LENGTH OF special register

A LENGTH OF special register passed BY VALUE is treated as a PIC 9(9) binary. For information about the LENGTH OF special register, see LENGTH OF.

literal-3

Must be of one of the following types:

A numeric literal
A figurative constant ZERO
A one-character alphanumeric literal
A one-character national literal
A symbolic character
A single-byte figurative constant
- SPACE
- QUOTE
- HIGH-VALUE
- LOW-VALUE

ZERO is treated as a numeric value; a fullword binary zero is passed.

If literal-3 is a fixed-point numeric literal, it must have a precision of nine or fewer digits. In this case, a fullword binary representation of the literal value is passed.

If literal-3 is a floating-point numeric literal, an 8-byte internal floating-point (COMP-2) representation of the value is passed.

literal-3 must not be a DBCS literal.

RETURNING phrase

identifier-5: The RETURNING data item, which can be any data item defined in the DATA DIVISION. The return value of the called program is implicitly stored into identifier-5.

You can specify the RETURNING phrase for calls to functions written in COBOL, C, or in other programming languages that use C linkage conventions. If you specify the RETURNING phrase on a CALL to a COBOL subprogram:

The called subprogram must specify the RETURNING phrase on its PROCEDURE DIVISION header.
identifier-5 and the corresponding PROCEDURE DIVISION RETURNING identifier in the target program must have the same PICTURE, USAGE, SIGN, SYNCHRONIZE, JUSTIFIED, and BLANK WHEN ZERO clauses (except that PICTURE clause currency symbols can differ, and periods and commas can be interchanged due to the DECIMAL POINT IS COMMA clause).
When the target returns, its return value is assigned to identifier-5 using the rules for the SET statement if identifier-6 is of usage INDEX, POINTER, FUNCTION-POINTER, PROCEDURE-POINTER, or OBJECT REFERENCE. When identifier-5 is of any other usage, the rules for the MOVE statement are used.

The CALL ... RETURNING data item is an output-only parameter. On entry to the called program, the initial state of the PROCEDURE DIVISION RETURNING data item has an undefined and unpredictable value. You must initialize the PROCEDURE DIVISION RETURNING data item in the called program before you reference its value. The value that is passed back to the calling program is the final value of the PROCEDURE DIVISION RETURNING data item when the called program returns.

Note: If a COBOL program returns a doubleword binary item via a PROCEDURE DIVISION RETURNING header to a calling COBOL program with a CALL ... RETURNING statement, an issue occurs if only one of the programs is recompiled with Enterprise COBOL V6. Both the called and calling programs must be recompiled with Enterprise COBOL V6 together, so that the linkage convention for the RETURNING item is consistent.

If an EXCEPTION or OVERFLOW occurs, identifier-5 is not changed. identifier-5 must not be reference-modified.

The RETURN-CODE special register is not set by execution of CALL statements that include the RETURNING phrase.

ON EXCEPTION phrase

An exception condition occurs when the called subprogram cannot be made available. At that time, one of the following two actions will occur:

If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. Execution then continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement. Otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the CALL statement and the NOT ON EXCEPTION phrase, if specified, is ignored.
If the ON EXCEPTION phrase is not specified in the CALL statement, the NOT ON EXCEPTION phrase, if specified, is ignored.

NOT ON EXCEPTION phrase

If an exception condition does not occur (that is, the called subprogram can be made available), control is transferred to the called program. After control is returned from the called program, control is transferred to:

imperative-statement-2, if the NOT ON EXCEPTION phrase is specified.
The end of the CALL statement in any other case. (If the ON EXCEPTION phrase is specified, it is ignored.)

If control is transferred to imperative-statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement. Otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the CALL statement.

ON OVERFLOW phrase

The ON OVERFLOW phrase has the same effect as the ON EXCEPTION phrase.

END-CALL phrase

This explicit scope terminator serves to delimit the scope of the CALL statement. END-CALL permits a conditional CALL statement to be nested in another conditional statement. END-CALL can also be used with an imperative CALL statement.

For more information, see Delimited scope statements.

Start of change

related references
PARMCHECK (Enterprise COBOL Programming Guide)