The CALL Statement

General Rules

General rules marked with an asterisk (*) are common to the CALL statement and to the CHAIN statement. In these rules, where "CALL or CHAIN statement" are specified, you should read "CALL statement" or "CHAIN statement" when applying the rules to the CALL statement or the CHAIN statement respectively.

1. Literal-1 or the content of the data item referenced by identifier-1 is the name of the called program

   or called procedure.

   The program in which the CALL statement appears is the calling program. If the program being called is a COBOL program, literal-1 or the content of the data item referenced by identifier-1 must contain the program-name contained in the Program-ID paragraph of the called program (see the topic The Program-ID Paragraph, particularly in regard to case sensitivity),

   or the entry-name contained in the ENTRY statement of a called program that must have been called previously and not canceled since. Alternatively, the name of the called program may be a name which identifies a file that contains executable program code for the called program. The result of specifying different names that identify the same file in two CALL statements or a CALL and a CANCEL statement are operating-system specific. See your COBOL system documentation for details of how your system matches the given name to previously called programs, program filenames or programs held in library files.

   If the program being called is not a COBOL program, the rules for the formation of the program or procedure name are given in the COBOL system documentation on interfacing.

2. The content of the data item referenced by procedure-pointer-1 is the address of the called program that must be already resident in memory. If the program being called is a COBOL program, the address of the called program must originally have been derived from a SET statement with an ENTRY phrase and no CANCEL statement for that program must have been subsequently executed. If the program being called is not a COBOL program then the address of the called program must originally have been derived from a CALL to a non-COBOL program or procedure. It is an error to attempt to CALL a program with an address that is equal to NULL.
3. If, when a CALL statement is executed, the program specified by the CALL statement is made available for execution, control is transferred to the called program. After control is returned from the called program, the ON OVERFLOW

   or ON EXCEPTION

   phrase is ignored and control is passed to the end of the CALL statement

   or, if the NOT ON EXCEPTION phrase is specified control is passed to imperative-statement-2. If control is passed 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 which 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.

4. When a CALL statement is executed, the program specified by the CALL statement is made available if it is already resident in memory. If it is not already resident in memory then an attempt may be made to dynamically load the program (see your COBOL system documentation on interfacing). If a program with the specified name can be dynamically located and a sufficient, contiguous area of free memory is available, then the program is dynamically loaded and made available for execution.

   If the program specified by the CALL is not resident in memory, is not available for dynamic loading or is available but is too large for the available memory, then the program cannot be made available at that time and one of the following two actions occurs:

   1. If the ON OVERFLOW

      or ON EXCEPTION

      phrase is specified in the CALL statement, 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 which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of 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.

   2.  If the ON OVERFLOW or ON EXCEPTION phrase is not specified in the CALL statement, the NOT ON EXCEPTION phrase, if specified, is ignored.

      Program execution stops, without an implicit CLOSE statement for any file that is in open mode in the run unit, and a run time error is displayed.

5. Two or more COBOL programs in the run unit can have the same program-name, and the reference in a CALL statement to such a program-name is resolved by using the scope-of-names conventions for program-names. See the topic Conventions for Program-names in the chapter Concepts of the COBOL Language. For example, when two programs in the run unit have the same name as that specified in a CALL statement:
   1. One of those two programs must also be contained directly or indirectly either within the separate program which includes the CALL statement or within the separate program which itself directly or indirectly contains the program which includes that CALL statement, and
   2. The other one of those two programs must be a different separate program.

   The mechanism used in this example is as follows:

   1. If one of the two programs having the same name as that specified in the CALL statement is directly contained within the program which includes that CALL statement, that program is called.
   2. If one of the two programs having the same name as that specified in the CALL statement possesses the common attribute and is directly contained within another program which directly or indirectly contains the program which includes the CALL statement, that common program is called unless the calling program is contained in that common program.
   3. Otherwise, the separate program is called.
6. If the called program is a COBOL program and does not possess the initial attribute, it and each COBOL program directly or indirectly contained within it, is in its initial state the first time it is called within a run unit and the first time it is called after a CANCEL of the called program.

   If the called program is not COBOL, it is only in its initial state the first time it is called within a run unit. A CANCEL of such a program has no effect.

   On all other entries into the called program, the state of the program and each program directly or indirectly contained within it remains unchanged from its state when last exited. Some implementations of languages other than COBOL may provide alternative semantics and, if available, these are detailed in your COBOL system documentation on interfacing.

7. If the called program possesses the intial attribute, it and each program directly or indirectly contained within it, is placed into its initial state every time the called program is called in a run unit. Whether a called program is in the initial state or last-used state is sensitive to the DYNAM Compiler directive.
8. Files associated with a called program's internal file connectors are not in the open mode when the program is in an initial state. See the topicIntial State Of A Program earlier in this chapter. On all other entries into the called program, the states and positioning of all such files are the same as when the called program was last exited.
9. The process of calling a program or exiting from a called program does not alter the status or positioning of a file associated with any external file connector.
10. If the program being called is a COBOL program, the USING phrase is included in the CALL statement only if there is a USING phrase in the PROCEDURE DIVISION header

    or ENTRY statement

    of the called program, in which case the number of operands in each USING phrase must be identical.

    The number of operands need not be identical.

11. If the program being called is not a COBOL program, the USING phrase is included in the CALL statement only if one or more parameters are declared for the called program, in which case the number of operands in the USING phrase must be identical to the number of parameters in the called program. (Some implementations of languages other than COBOL may allow the number of operands to be other than identical.) The COBOL language places no restrictions on the alignment of the addresses of data items, whereas non-COBOL languages typically do make assumptions about addresses and will fail in some way if a misaligned data item is referenced. Alignment can be achieved by one or more of the following actions:
    • Modifying group items to include additional filler items
    • Ensuring operands in the USING phrase are level 01 or level 77 data items in conjunction with the ALIGN Compiler directive or
    • Use of the SYNCHRONIZED clause in conjunction with the IBMCOMP Compiler directive.
12. * The sequence of appearance of the operands in the USING phrase of the CALL

    or CHAIN

    statement and in the corresponding USING phrase in the called program's PROCEDURE DIVISION header

    or ENTRY statement or parameter list if the called program is not COBOL

    determines the correspondence between the data names used by the calling and called programs. This correspondence is positional and not by name equivalence; the first operand in the CALL

    or CHAIN

    statement's USING phrase corresponds to the first operand in the called program's USING phrase or parameter list, the second to the second, etc.

    If the correspondence cannot be completed because the numbers of operands are different, then if the remaining unmatched operands are in the CALL or CHAIN statement they are ignored and if they are in the PROCEDURE DIVISION header or ENTRY statement or parameter list then they must not be referenced within the called program. The positional correspondence may vary depending on the calling conventions implied by mnemonic-name.

    In the case of index-name, no such correspondence is established. Index-names in the called and calling programs always refer to separate indices.

13. * The values of the parameters referenced in the USING phrase of the CALL statement are made available to the called program at the time the CALL statement is executed.
14. * If the BY REFERENCE identifier-4 phrase is

    either specified or

    implied for a parameter, the program operates as if the corresponding data item in the called program occupies the same storage area as the data item in the calling program. The description of the data item in the called program must describe the same number of character positions as described by the description of the corresponding data item in the calling program.

    If the BY REFERENCE ADDRESS OF phrase is specified or implied then the program operates as if an additional data item had been declared with USAGE POINTER and that data item passed BY REFERENCE with a value acquired by a SET data item TO ADDRESS OF identifier-3 and identifier-5 statement.

    If identifier-3 and identifier-5 are in the Linkage Section and have a level number other than 01 or 77 or is in the Working-Storage Section, this is equivalent to passing the item BY CONTENT; the address of identifier-3 or identifier-5 cannot be modified by the called subprogram.

    If the BY REFERENCE literal-3 phrase is specified or implied then the object program processes literal-3 as described for literal-4.

15. * 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. The data description of each parameter in the BY CONTENT phrase of the CALL statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the PROCEDURE DIVISION header.

    If the BY CONTENT phrase is specified or implied for a parameter, the object program operates as if an additional data item had been declared and this additional data item used as the parameter in a BY REFERENCE phrase. If identifier-6 is specified, then both the implied data description of the additional data item and its contents are identical to that of identifier-6. If literal-4 is specified, then the implied data description of the additional item is equivalent to an alphanumeric data item with the same size as literal-4 and with its contents set to the value of literal-4. If LENGTH OF identifier-7 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE BINARY, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-7.

16. *If the BY VALUE 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. The object program operates, conceptually, as if an additional data item had been declared in a system area (typically the stack), available to non-COBOL languages for passing parameters and that this additional data item occupies the same storage area as the data item in the called program.

    If identifier-8 is specified and is BINARY, COMP-4, COMP-5 or COMP-X, then the data description of the additional data item is identical to that of identifier-8, except its usage is COMP-5. The contents of the additional data item are identical to the COMP-5 representation of the contents of identifier-8. This conversion and representation facilitates calling non-COBOL programs.

    Otherwise, if identifier-8 is specified then the implied data description of the additional data item and its contents are identical to that of identifier-8.

    If literal-5 is specified, then the data description of the additional item is equivalent to a signed numeric item USAGE BINARY that occupies the number of bytes of storage indicated by the value of integer-1, if specified, or the size of the system area otherwise (typically the size of a POINTER on the system).

    If LENGTH OF identifier-9 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-9.

    If the program being called is a COBOL program, each parameter in the BY VALUE phrase of the CALL statement must have a corresponding parameter declared in the USING phrase of the PROCEDURE DIVISION header that also has the BY VALUE phrase specified or implied.

    The additional data item generated as a result of the CALL statement, described above, is related to this corresponding parameter in the called program, as follows.

    If the additional data item was subject to conversion from BINARY, COMP-4, COMP-5 or COMP-X to COMP-5, then the data description of the corresponding parameter in the called program must be identical to that of the data description of the additional data item with the exception that the corresponding parameter's USAGE can be any of BINARY, COMP-4, COMP-5 or COMP-X. On entry to the called COBOL program, a conversion from the USAGE COMP-5 of the additional data item to the USAGE of the corresponding parameter in the called program is performed.

    If the additional data item was not subject to conversion to COMP-5, the data description of each parameter in the called program must be the same as the corresponding additional data item. This means there is no conversion or extension or truncation, of the additional data item to match the corresponding parameter in the called program.

    If the program being called is not COBOL, the size of the additional data item should not exceed the maximum size of the system area (typically the size of a POINTER on the system); otherwise the system might become catastrophically corrupt.

17. A called program can pass data to the calling program either by using a parameter declared in the USING phrase of the calling program or by means of a returned value. A called program returns a value by means of an EXIT GIVING or GOBACK GIVING statement. As control is returned from the called program to the calling program, the returned value is held in a system area generally available for non-COBOL programs to return a value.

    The size of the system area (typically the size of a POINTER on the system) is determined outside the COBOL system and limits the maximum value the return value can take, but the return value might not utilize the full size of the system area. The returned value is available to the calling program after control is returned, either implicitly in the special register RETURN-CODE or explicitly in the data item specified in the GIVING phrase.

18. If the GIVING phrase is not specified and the calling convention specifies updating the RETURN-CODE special register (see the topic The Special-Names Paragraph) then the object program operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and the same size as the system area and as if a MOVE statement had been executed with the system area as the sending item and the RETURN-CODE special register as the receiving item.
19. If the GIVING INTO phrase is specified in the calling program, identifier-10 must describe the same number of character positions as is required to hold the return value in the system area and must be of the type and usage that is implied for the returned value by the manner in which the value was returned from the called program. When control returns to the calling program, identifier-10 contains the return value.
20. If the GIVING ADDRESS OF phrase is specified in the calling program, the called program must return a value with explicit or implicit USAGE POINTER. The object program operates as if the system area were declared as a COBOL data item with USAGE POINTER and as if a SET statement had been executed with the system area as the first operand and TO ADDRESS OF identifier-11 as the second operand.
21. It is an error to specify the GIVING phrase for a called program that does not return a value.
22. Called programs can contain CALL statements. However, a called program may not execute a CALL that directly or indirectly calls the calling program,

    unless that calling program has the recursive attribute.

23. If a CALL statement is executed within the range of a declarative, that CALL statement cannot directly or indirectly reference any called program to which control has been transferred and which has not completed execution.
24. The END-CALL phrase delimits the scope of the CALL statement.
25. Any values with implicit or explicit USAGE POINTER

    or USAGE PROCEDURE-POINTER

    that were originally derived from the address of a data item

    or procedure

    that is contained within a called program become invalid and must not be used after a CANCEL statement that references that called program is executed.

26. The OMITTED phrase is used to pass unused parameters to a subprogram without having to declare a dummy data item.
27. The OMITTED parameter is a BY REFERENCE parameter, equivalent to passing a null address to the calling subprogram. It is identical to BY VALUE 0 but is subject to the type checking of call prototypes as a BY REFERENCE parameter.
28. If BY REFERENCE does not immediately precede OMITTED, subsequent parameters are passed by the convention previously in force and the omitted parameter is treated as if the program had specified BY VALUE 0.
29. A numeric literal-3 or literal- is passed as an integer 32-bit comp-x item if it is not negative or as an integer 32-bit comp (binary) item if it is negative, even if the literal is not an integer. A decimal point in the numeric literal is ignored.
30. Mnemonic-name identifies the calling convention that this program uses when invoking the called program. If the calling convention assumed by the called program is different to that implied by mnemonic-name, then the COBOL system may become corrupt.
31. The run unit remains unaware of whether a called program is a COBOL program or a non-COBOL program or procedure until the called program has been located, prior to being made available for execution. The form of the program-name cannot be used, in general, to determine whether the program is a COBOL program or not. It is an error for a COBOL program and a non-COBOL program or for two non-COBOL programs to have the same program-name.
32. * The BY CONTENT, BY REFERENCE

    and BY VALUE

    phrases are transitive across the parameters which follow them until another BY CONTENT, BY REFERENCE

    or BY VALUE

    phrase is encountered.

    If no BY CONTENT, BY REFERENCE

    or BY VALUE

    phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.