1. CALL

The CALL statement transfers control from one program to another while the program is running. The program that calls another program with the CALL statement is the calling program, and the one that is called by the calling program is the called program.

The called program can also call another program with the CALL statement. For a program to directly or indirectly call itself, the program needs to have been defined with RECURSIVE.

figure pd call
CALL Statement Format
figure pd exception phrases
CALL Statement Format - exception-phrases
figure pd not exception phrase
CALL Statement Format - not-exception-phrase

The following items are specified in the statement.

  • identifier-1, literal-1

    • identifier-1 must be defined as an alphanumeric, alphabetical or numeric item to specify a program name.

    • identifier-1cannot be a windowed date field. literal-1 must be an alphanumeric literal.

    • USAGE TYPE must be DISPLAY.

    • To execute the called program at the beginning of the procedure division, the data in literal-1 or identifier-1 must specify the program name as defined in the identification division of the called program.

      To execute the called program from a specific part defined by an ENTRY statement in the called program, the name declared in the ENTRY statement must be specified.

  • procedure-pointer-1, function-pointer-1

    • Must be a data item that has a valid program entry point.

  • USING phrase

    • Specifies arguments to pass to the called program.

      The number of arguments in the procedure division of the called program or that of the ENTRY statement must be identical to that of the USING phrase. The arguments are transferred in order. The value of the arguments declared by the USING phrase are valid while the called program is being executed.

    • The BY CONTENT, BY REFERENCE, and BY VALUE phrases are applied until another BY CONTENT, BY REFERENCE, and BY VALUE phrases appears.

      If BY CONTENT or BY VALUE is not specified, the default is BY REFERENCE.

  • BY REFERENCE phrase

    • The BY REFERENCE phrase passes the address value of the data item as an argument, rather than passing a copy of the data from the calling program. If the value of the argument passed from the called program to the calling program is modified, the modified value will remain even after the called program terminates.

    • The following items are specified in the phrase.

      Item Description

      identifier-2

      Any data item of any level defined in the data division can be specified.

      file-name-1

      File name for a QSAM file

      ADDRESS OF identifier-2

      identifier-2 must be a data item of level-01 or level-77 defined in the linkage section.

      OMITTED

      Does not pass any data item as an argument.

  • BY CONTENT phrase

    • The BY CONTENT phrase copies a value of an argument in a temporary point to pass it from the calling program to the called program. Even if the called program modifies a data value of an argument, data in the calling program will not change.

    • The following items are specified in the phrase.

      Item Description

      identifier-3

      Any data item of any level defined in the data division can be specified.

      literal-2

      Can be an alphanumeric literal, figurative constant, or DBCS literal.

      LENGTH OF special register

      For information about the LENGTH OF special register, refer to the "LENGTH OF" special register in COBOL Words.

      ADDRESS of identifier-3

      identifier-3 must be a data item of level-66 or level-88 defined in the linkage section, the working-storage section, or the local-storage section.

      OMITTED

      Does not pass any data item as an argument.

  • BY VALUE phrase

    • The BY VALUE phrase passes the values of data as arguments from the calling program to the called program. Thus, the called program cannot modify data of the calling program.

    • The BY VALUE phrase was primarily introduced for the interface between COBOL programs and non-COBOL languages (for example, the C language), but it can also be used between COBOL programs.

    • The following items are specified in the phrase.

      Item Description

      identifier-4

      Data items, not group items defined in the data division.

      One of the following can be specified.

      • Binary (USAGE BINARY, COMP, COMP-4, COMP-5)

      • Floating Point (USAGE COMP-1, COMP-2)

      • Function-pointer (USAGE FUNCTION-POINTER)

      • Pointer (USAGE POINTER)

      • Procedure-pointer (USAGE PROCEDURE-POINTER)

      • One single-byte alphanumeric character (such as PIC X or PIC A)

      If the BY VALUE phrase is also used, the following are available.

      • Reference-modified item of usage display and length 1

      • SHIFT-IN and SHIFT-OUT special registers

      • LINAGE-COUNTER special register when this has usage binary

      ADDRESS OF identifier-4

      Data items except level-66 or level-88 defined in the linkage-section, the working-storage section, or the local-storage section.

      LENGTH OF special register

      If a LENGTH OF special register is used, BY VALUE must be specified as a PIC 9(9) binary type.

      literal-3

      One of the following can be specified.

      • A numeric literal

      • A Figurative constant ZERO

      • A one-character alphanumeric literal

      • A symbolic character

      • A single-byte Figurative constant (SPACE, QUOTE, HIGH-VALUE, LOW-VALUE)

      The following rules apply.

      • ZERO is treated as a numeric value (a fullword binary zero is passed.).

      • If a fixed-point numeric literal, it has 9 or fewer digit precision.

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

  • RETURNING phrase

    • The following items are specified in the phrase.

      Item Description

      identifier-5

      identifier-5 can be any data item defined in the data division. The return value specified by the called program is stored.

    • If the called program has been written in COBOL or C, the RETURNING phrase of the CALL statement can be specified. To specify the RETURNING phrase in a CALL statement that calls a sub-program written in COBOL, note the following.

      • The called program must specify the RETURNING phrase in the procedure division.

      • identifier-5 specified in the RETURNING phrase of the calling program and the RETURNING phrase specified in the target program must share the same PICTURE, USAGE, SIGN, SYNCHRONIZE, JUSTIFIED, and BLANK WHEN ZERO clauses. (In the PICTURE clause, the currency sign may be different from each other, and periods and commas can vary based on the DECIMAL POINT IS COMMA clause.)

      • If the returned identifier-5 value is of USAGE INDEX, POINTER, FUNCTION-POINTER, or PROCEDURE-POINTER, it is treated as modified through a SET statement internally. If not, it is internally treated as modified through a MOVE statement .

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

      • RETURN-CODE is not set when executing a CALL statement that includes the RETURNING phrase.

  • ON EXCEPTION phrase

    • If an exception occurs while the called program is being executed, one of the following things occurs.

      • If the ON EXCEPTION phrase is specified, control is moved to imperative-statement-1.

      • If the ON EXCEPTION phrase is not specified in the CALL statement, NOT ON EXCEPTION, if specified, will be ignored.

  • NOT ON EXCEPTION phrase

    • If the called program executed successfully, control is moved to imperative-statement-2.

  • ON OVERFLOW phrase

    • The ON OVERFLOW phrase performs the same roles as those of the ON EXCEPTION phrase.

  • END-CALL phrase

    • The END-CALL phrase explicitly specifies that the CALL statement ends.