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.
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 the PGMNAME compiler option in the COBOL for Windows Programming Guide.
identifier-1 cannot be a windowed date field.
Usage note: Do not specify the name of a class or method in the CALL statement.
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.
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.
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.
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.
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.
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.
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:
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.
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.
The following can also be passed BY 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.
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:
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.
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.
An exception condition occurs when the called subprogram cannot be made available. At that time, one of the following two actions will occur:
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:
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.
The ON OVERFLOW phrase has the same effect as the ON EXCEPTION 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.