You can call the program indirectly, by address. Data, pointers to data, and pointers to procedures can be passed as parameters to the called program, and returned by it. Parameter passing conventions can be controlled in order to allow the called program to be written in languages other than COBOL, using different conventions.
A called COBOL program can recursively call itself when it has the recursive attribute.
or national
data item.
, literal-2
, and literal-3
cannot be a figurative constant and must be an alphanumeric literal
or a national literal.
Local-Storage Section
or Linkage Section, and must be a level 01 data item, or a level 77 data item
, or an elementary item
, or any group item.
Identifier-2 must not be defined in the Working-Storage or File Section of a factory or an instance object.
Mnemonic-name must be defined in the Special-Names paragraph. See the topic The Special-Names Paragraph for details of how to do this and your COBOL system documentation on interfacing for details of which calling conventions are supported in your run-time environment.
, Local-Storage Section or Working-Storage Section,
and must be a level 01 data item, a level 77 data item
, or other level data item.
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.
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.
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.
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:
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.
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.
The mechanism used in this example is as follows:
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.
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.
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.
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 statement.
If identifier-3 is in the Linkage Section and has 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 cannot be modified by the called subprogram.
If the BY REFERENCE literal-2 phrase is specified or implied then the object program processes literal-2 as described for literal-3.
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-4 is specified, then both the implied data description of the additional data item and its contents are identical to that of identifier-4. If literal-3 is specified, then the implied data description of the additional item is equivalent to an alphanumeric data item with the same size as literal-3 and with its contents set to the value of literal-3. If LENGTH OF identifier-5 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-5.
If identifier-6 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-6, 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-6. This conversion and representation facilitates calling non-COBOL programs.
Otherwise, if identifier-6 is specified then the implied data description of the additional data item and its contents are identical to that of identifier-6.
If integer-1 is specified, then the data description of the additional item is equivalent to a signed numeric item USAGE COMP-5 that occupies the number of bytes of storage indicated by the value of integer-2, if specified, or the size of the system area otherwise (typically the size of a POINTER on the system).
If LENGTH OF identifier-7 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-7.
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.
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.
unless that calling program has the recursive attribute.
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.
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.