=========================================================================
M I C R O F O C U S
E A R L Y R E L E A S E
V3.1.39
=========================================================================
CALL PROTOTYPES
===============
This document is a supplement for the chapter "Program Definition" in
your Language Reference.
TABLE OF CONTENTS
=================
FUNCTION
GENERAL FORMAT
SYNTAX RULES
EXAMPLE
FUNCTION
========
A CALL prototype is a skeleton program which serves to define the
characteristics of a called subprogram. These characteristics include the
number of parameters required, the type of these parameters and the
calling convention. If a program contains a CALL statement referring to a
subprogram for which a prototype exists, the CALL statement is checked
against the prototype. If there is an explicit mismatch, an error is
given. If the CALL statement leaves some characteristic (such as the call
convention) undefined, this is derived from the prototype.
The prototype is defined as a complete "EXTERNAL" program, which is a
skeleton consisting only of Program-ID, Linkage Section and PROCEDURE
DIVISION USING, with further optional ENTRY statements. These EXTERNAL
programs are placed before the real source programs in a similar way to
multi-program source files.
GENERAL FORMAT
==============
PROGRAM-ID. program-name IS EXTERNAL program.
---------- --------
PROCEDURE DIVISION [mnemonic-name]
--------- --------
{data-name-1 }
[USING {[BY REFERENCE] {type-def-1 [DELIMITED]}...}...
----- --------- {ANY }
{data-name-2}
{ BY VALUE {type-def-2 }... }
----- {ANY }
[GIVING/RETURNING {data-name-3}]
------ --------- {type-def-3 }
ENTRY entry-name [mnemonic-name]
-----
{data-name-1 [DELIMITED]}
[USING {[BY REFERENCE] {type-def-1 [DELIMITED]}...}...
----- --------- {ANY }
{data-name-2}
{ BY VALUE {type-def-2 }... }
----- {ANY }
[GIVING/RETURNING {data-name-3}]
------ --------- {type-def-3 }
Note: All data-names must be 01 level records in the Linkage Section,
but you can replace any of them with the name of a type
definition.
The GIVING/RETURNING phrase is allowed only in the PROCEDURE
DIVISION USING and ENTRY statements for EXTERNAL programs.
SYNTAX RULES
============
1. If a call convention is specified in the CALL statement, it must
match that specified (implicitly or explicitly) in the prototype. If
no call convention is specified in the CALL statement, the call
convention specified (implicitly or explicitly) in the prototype is
used.
2. The number of parameters specified in the CALL statement must equal
the number of parameters specified in the prototype.
3. For each parameter specified in the CALL statement, the following
rules apply:
a) If there is a BY REFERENCE or a BY CONTENT phrase associated with
the parameter, the corresponding parameter in the prototype must
be specified BY REFERENCE.
b) If there is a BY VALUE phrase associated with the parameter, the
corresponding parameter in the prototype must be specified BY
VALUE.
c) If the parameter in the CALL statement has no BY REFERENCE, BY
CONTENT or BY VALUE phrase, the phrase specified (implicitly or
explicitly) in the prototype is used.
d) If the parameter in the prototype is of class numeric, or it is a
pointer or index data-item, then the parameter in the CALL must
have the same data definition.
e) If the parameter in the prototype is of class alphanumeric, the
parameter in the CALL must also be of class alphanumeric and be
at least as long as the parameter in the prototype.
f) If ANY is specified in the prototype, the parameter in the
CALL statement may be of any class.
4. If the CALL statement includes the GIVING or RETURNING clause, the
prototype must also include the clause, and vice versa. The data
definition of the data item specified in the CALL must be the same as
that of the data item specified in the prototype.
5. The DELIMITED phrase in the prototype may be used only for
alphanumeric parameters. In this case, the corresponding parameter in
the CALL statement is moved to an implicitly allocated data area, and
a binary 0 (x"00") is placed immediately following this copy of the
data. The intention is to help in interfacing to languages such as C,
which use the ASCII convention for text strings.
EXAMPLE
=======
program-id. callsub is external.
special-names.
call-convention 3 is some-language.
linkage section.
01 x1 pic 9(4) comp-5.
01 x2 pic xx.
01 x3 pic 9(8).
procedure division some-language using
by value x1
by reference x2
by reference x3.
entry "callsub2" using x2 delimited
any
x1.
end program callsub.
program-id. prog-1.
special-names.
call-convention 3 is some-language
call-convention 4 is other-language.
working-storage section.
01 x1 pic 9(4) comp-5.
01 x2.
03 pic 9(4) comp-5.
03 pic x(20).
01 x3 pic 9(8).
01 x4 pic 9(9) comp-5.
01 x5 pic x.
01 x6 pic x(20).
procedure division.
call "callsub" using x1 x2 x3 *> Equivalent to call using
*> by value x1
*> by reference x2
*> by reference x3
call "callsub" using x1 x2
*> Generates an error since
*> number of parameters is wrong.
call other-language "callsub" using x1 x2 x3
*> Generates an error since
*> call-convention is wrong.
call "callsub" using by reference x1 x2 x3
*> Generates an error since x1
*> should be passed by value.
call "callsub" using 99 x2 x3 *> Equivalent to call using
*> by value 99 size 2
*> by reference x2
*> by reference x3
call "callsub" using x4 x2 x3 *> Generates an error since
*> x4 has wrong length
call "callsub" using x1 x5 x3 *> Generates an error
*> since x5 is too small.
call "callsub2" using "Hello" x2 x1
*> Equivalent to:
*> move "Hello" & x"00" to temp
*> call "callsub2" using
*> temp x2 x1
call "callsub2" using x6 x2 x1
*> Equivalent to:
*> move x6 to temp
*> move x"00" to temp (21:1)
*> call "callsub2" using
*> temp x2 x1
call "callsub2" using x6 x2 x1 x4
*> Generates an error
*> for too many parameters.
=========================================================================
Micro Focus is a registered trademark of Micro Focus Limited.
=========================================================================
@(#)Vrn/callprot.1/3.1.03/15Jul93/nrV
Copyright (C) 1992-93 Micro Focus Limited