HP 3000 Manuals HP 3000 Manuals
General Formats (Cont.)
The CALL Statement
Function.
The CALL statement causes control to be transferred from one object
program to another within the run unit.
For MF only: You may CALL the target object program procedure
indirectly, by address. Data, pointers to data, and pointers to
procedures can be passed as parameters to the called program procedure,
and returned by it. Parameter passing conventions can be controlled in
order to allow the called program procedure to be written in languages
other than COBOL, using different conventions. A called COBOL program
can recursively call itself when a Local-Storage Section exists.
Examples:.
1. An example of using procedure-pointer in a CALL statement is
provided in the Examples chapter in your Language Reference -
Additional Topics.
General Format.
![[]](../../pic3k/M015064/FFN2003c50.gif)
Directives.
1. In addition to system directives which provide flagging and modify
the reserved word list, the following directives may impact either
the syntax or semantics described in this section. See your COBOL
System Reference for details.
* ALIGN - specifies the memory boundaries on which data items
of 01-level or 77-level are aligned.
* CASE - determines whether upper-case and lower-case letters
are considered equivalent.
* DEFAULTCALLS - controls which calling convention is the
default.
* DYNAM - determines whether programs invoked by a CALL
literal statement can be cancelled or not.
* FOLD-CALL-NAME - determines whether you are guaranteed to
find a called subprogram when the calling and called
programs do not use the same upper-case and lower-case
letters for the program-name.
* IBMCOMP - turns on word-storage mode.
* MAPNAME - impacts the handling of non-alphabetic characters
in the program-name.
Syntax Rules.
Syntax 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. For MF only: Mnemonic-name is necessary only if the object
program that is to be invoked will expect a calling convention
other than that used as the default by your COBOL system.
Typically, the default COBOL calling convention is consistent with
that used by a significant implementation of a non-COBOL language
for the run-time environment.
Mnemonic-name must be defined in the SPECIAL-NAMES paragraph. See
the section The SPECIAL-NAMES Paragraph earlier in this chapter
for details of how to do this and your COBOL System Reference for
details of which calling conventions are supported in your
run-time environment.
2. *Identifier-1 must be defined as an alphanumeric data item such
that its value can be a COBOL or non-COBOL program-name.
3. *Literal-1 , literal-2 (MF only) , and literal-3 (MF and VSC2
only) must be nonnumeric literals and cannot be a figurative
constant.
4. *Integer-1 may be signed.
5. *Identifier-2 and identifier-4 must be defined as a data item in
the File Section, Working-Storage Section, Communications Section
or Linkage Section, and must be a level 01 data item, or a level
77 data item , or an elementary item (ANS85 only) , or any group
item (MF only).
6. *Identifier-3 must be defined as a data item in the Linkage
Section or Working-Storage Section , and must be a level 01 data
item, a level 77 data item , or other level data .
7. *Neither identifier-5, identifier-6, identifier-7, nor
identifier-8 can be a function-identifier.
8. *For MF only: GIVING and RETURNING are equivalent.
9. *For MF only: Identifier-8 must be no larger than 8 bytes in
size.
10. For MF only: Identifier-9 must be defined as a data item in the
Linkage Section with a level number of 01 or 77.
11. For MF only: If the CALL statement specifies literal-1 (but not
if it specifies identifier-1 or procedure-pointer-1), and if a
call prototype (a program with the EXTERNAL clause in its
PROGRAM-ID paragraph) has been included in the current compilation
unit with a name that matches literal-1, then the following items
are validated during syntax checking:
* The number of parameters required
* The type of parameters
* The call convention
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. For MF only: Mnemonic-name identifies the calling convention
that this program will use 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.
2. Literal-1 or the content of the data item referenced by
idenitifier-1 is the name of the called program or called
procedure (MF only). The program in which the CALL statement
appears is the calling program. If the program being called is a
COBOL program, the name of the called program must contain the
program-name contained in the PROGRAM-ID paragraph of the called
program (see The Program-ID Paragraph earlier in this chapter,
particularly in regard to case sensitivity)
For MF only: 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
contain 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 Reference for details of how your system
matches the given name to previously called programs, program
filenames or programs held in library files.
For MF only: 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 Reference.
3. For MF only: 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 the program must have been executed since.
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.
4. 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 (ANS85 only)
phrase is ignored and control is passed to the end of the CALL
statement
For ANS85 only: or, if the NOT ON EXCEPTION phrase is
specified, 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.
5. 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
Reference). 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 finds
insufficient memory in which to load, then the program cannot be
made available at that time and one of the following two actions
will occur:
a. If the ON OVERFLOW or ON EXCEPTION (ANS85 only) 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 .
b. If the ON OVERFLOW or ON EXCEPTION phrase is not specified
in the CALL statement, the NOT ON EXCEPTION phrase, if
specified, is ignored. (ANS85 only)
Program execution will stop, without any implicit close
statement for any file that is in open mode in the run
unit, and a run time error will be displayed.
6. 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.
For ANS85 only: Two or more COBOL programs in the run unit can
have he 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 section 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:
a. 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
b. The other one of those two programs must be a different
separate program.
7. The mechanism used in this example is as follows:
a. For ANS85 only: If one of the two programs having the same
name as that specified in the CALL statement is directly
contained within the the program which includes that CALL
statement, that program is called.
b. For ANS85 only: 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.
c. For ANS85 only: Otherwise, a separate program is called.
8. 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 will be detailed in
your COBOL System Reference.
9. For ANS85 only: 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
directive. See your COBOL System Reference for details.
10. For ANS85 only: 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 section Intial State Of A Program earlier
in this chapter.
On all other entries into the called program, the states and
positioning of all such files is the same as when the called
program was last exited.
11. For ANS85 only: 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.
12. 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 (OSVS, VSC2,
and MF only) of the called program, in which case the number of
operands in each USING phrase must be identical.
For MF only: The number of operands need not be identical.
13. For MF only: 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 numberof parameters in the called program. (Some
implementations of languages other than COBOL may allow the number
of operands to be other than identical. See your COBOL System
Reference.) 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 directive or
* use of the SYNCHRONIZED clause in conjunction with the IBM
COMP directive.
14. *The sequence of appearance of the operands in the USING phrase of
the CALL or CHAIN (MF only) 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 (MF only) 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 (MF only) 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.
For MF only: 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.
15. *For ANS85 only: 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.
16. *For ANS85 only: The BY CONTENT, BY REFERENCE and BY VALUE (MF
only) phrases are transitive across the parameters which follow
them until another BY CONTENT, BY REFERENCE or BY VALUE (MF only)
phrase is encountered.
If no BY CONTENT, BY REFERENCE or BY VALUE (MF only) phrase is
specified prior to the first parameter, the BY REFERENCE phrase is
assumed.
17. *If the BY REFERENCE identifier-2 phrase is either specified or
(ANS85 only) implied for a parameter, the object 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.
For VSC2 and MF only: If the BY REFERENCE OF ADDRESS phrase is
specified or implied then the object 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 ADDRESS OF identifier-3 statement.
For VSC2 and MF only: 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, it is equivalent to passing the item BY
CONTENT and the address of identifier-3 cannot be modified by the
called subprogram.
For MF only: If the BY REFERENCE literal-2 is specified or
implied then the object program processes literal-2 as described
for literal-3.
18. *For XOPEN and MF only: 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.
For MF only: 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
(9) USAGE BINARY and its contents set to the number of bytes of
storage allocated to identifier-5.
19. *For MF only: If the BY VALUE phrase is specified or implied
for a parameter, the called program cannot change the value of
this parameter 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-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 integer-1 is specified then
the implied data description of the additional item is equivalent
to a signed numeric item USAGE COMP-5 that occupies the number of
bytes of storage specified by the value of integer-2, if
specified, or 4 bytes otherwise. If LENGTH OF identifier-7 is
specified then the data description of the additional item is
equivalent to PIC S9 (9) USAGE BINARY and its contents set to the
number of bytes of storage allocated to identifier-7.
Each parameter in the BY VALUE phrase of the CALL statement has a
conceptual additional data item parameter in the USING phrase of
the PROCEDURE DIVISION header and a corresponding parameter
declared in the called program. The data description of each such
parameter in the called program must be the same, meaning no
conversion or extension or truncation, as the data description of
the corresponding conceptual additional data item. In addition,
the implied size of the conceptual data item must not exceed the
maximum size of the system area (typically 4 bytes but see your
COBOL System Reference for details) otherwise the system may
become catastrophically corrupt.
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 in the USING phrase of the PROCEDURE
DIVISION header that also has the BY VALUE phrase specified or
implied.
If the program being called is non-COBOL, see your COBOL System
Reference for details of when you need to use the BY VALUE clause.
20. For MF only: A called program may 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 at least 4 bytes but see
your COBOL System Reference for details) is determined outside the
COBOL system and limits the maximum value the return value can
take, but the return value may 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.
21. For MF only: If the GIVING phrase is not specified and the
calling convention specifies updating the RETURN-CODE special
register (see Calling Convention in the earlier section
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.
(See the section Special Registers in the chapter Concepts of the
COBOL Language for details of RETURN-CODE.
22. For MF only: If the GIVING INTO phrase is specified in the
calling program, identifier-8 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-8 contains the return value.
23. For MF only: 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-9 as
the second operand.
24. For MF only: It is an error to specify the GIVING phrase for a
called program that does not return a value
25. Called programs can contain CALL statements. However, if the
Local-Storage Section has not been declared, (MF only) a called
program may not execute a CALL that directly or indirectly calls
the calling program. 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.
26. For ANS85 only: The END-CALL phrase delimits the scope of the
CALL statement.
27. For VSC2 and MF only: Any values with implicit or explicit USAGE
POINTER or USAGE PROCEDURE-POINTER (MF only) that were originally
derived from the address of a data item or procedure (MF only)
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.
28. For MF only: The OMITTED phrase is used to pass unused
parameters to a subprogram without having to declare a dummy data
item.
29. For MF only: 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 SIZE 4 but is subject to the type
checking of call prototypes as a BY REFERENCE parameter.
30. For MF only: 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 SIZE 4.