CALL Statement
The CALL statement transfers control from one program to another within the run unit.
The program containing the CALL statement is the calling program; the program identified in the CALL statement is the called subprogram. The calling program must contain a CALL statement at the point where another program is to be called.
IBM Extension In ILE COBOL, a subprogram may be a COBOL program, a program written in another IBM® i language, or an ILE procedure. End of IBM Extension
Processing of the CALL statement passes control to the first nondeclarative instruction of the called subprogram. Control returns to the calling program at the instruction following the CALL statement. If the called subprogram has no procedure division or nondeclarative section in the Procedure Division, the called subprogram issues an implicit EXIT PROGRAM.
Whenever program control is transferred by the CALL statement and the called program directly or indirectly executes its caller, a recursive call has been made. Programs defined with the RECURSIVE attribute can execute a CALL statement that directly or indirectly executes itself. ILE COBOL does not allow recursion in non-recursive programs. A run time error message will be generated if recursion is attempted for a non-recursive program. For more information on calling programs and the associated concepts and terminology, see the IBM Rational® Development Studio for i: ILE COBOL Programmer's Guide.
The RETURN-CODE special register can be used to pass return code information from a program to its caller. See RETURN-CODE Special Register for further information.
CALL statement processing passes control to the called subprogram. If a CALL statement has a linkage of program object and the CALL statement names a program that does not exist in the specified library at run time, an error message is issued. The ON EXCEPTION or OVERFLOW phrase can be used to specify an error handling procedure.
A called subprogram is in its initial state the first time it is called within a run unit. It is also in its initial state the first time it is called after a CANCEL statement.
A program is in its initial state each time it is called if it is an initial program (if its PROGRAM-ID paragraph contains the INITIAL clause). On all other entries into the called subprogram, the subprogram is in its last-used state, except in the case of the PERFORM statement control mechanisms; these are always set to their initial state.
Whenever an implicit or explicit STOP RUN occurs, the Languages and Utilities return code is set to 0. Otherwise, it is set to 2. The RETURN-CODE register is copied to the user portion of the work control block. See the RTVJOBA and DSPJOB commands in the CL Programming book for more information about return codes.
The user return code is set to 0 at the start of the processing of any COBOL program, and before a call is made to another program.
CALL Statement - Format 1 >>- CALL--------------------------------------------------------> >--+-identifier-1---------------------------------------------------------+--> '-+-------------------------------------------------------+--literal-1-' | (1) | +-LINKAGE------+------+--+----+--+-environment-name-1-+-+ | '-TYPE-' '-IS-' '-PROGRAM------------' | | (1) | '-PROGRAM-----------------------------------------------' >--+---------------------------------------+--------------------> | (1) | '-+----+--LIBRARY------+-identifier-5-+-' '-IN-' '-literal-4----' >--+--------------------------+---------------------------------> | .---------------. | | V | | '-USING----| BY Phrase |-+-' >--+-| ON EXCEPTION Phrase |--| NOT ON EXCEPTION Phrase |-+-----> '-+----+--OVERFLOW--imperative statement-3-------------' '-ON-' >--+----------+------------------------------------------------>< '-END-CALL-' BY Phrase .--------------------------------------. V | |--+-+-------------------+----+-+----------------+--identifier-2-+-+-+--| | '-+----+--REFERENCE-' | | (1) | | | | '-BY-' | '-ADDRESS OF-----' | | | | (1) | | | '---file-name-1--------------------' | | .--------------------------------------. | | V | | '-+----+--CONTENT----+-+----------------+--identifier-2-+-+-------' '-BY-' | | (1) | | | +-ADDRESS OF-----+ | | | (1) | | | '-LENGTH OF------' | | (1) | '-+-literal-2-------+--------------' | (1) | '-file-name-1-----' ON EXCEPTION Phrase |--+----+--EXCEPTION--imperative statement-1--------------------| '-ON-' NOT ON EXCEPTION Phrase |--NOT--+----+--EXCEPTION--imperative statement-2---------------| '-ON-'
- IBM Extension
CALL Statement - Format 2 >>- CALL--------------------------------------------------------> >--+-identifier-1---------------------------------------------------------+--> '-+-------------------------------------------------------+--literal-1-' | (1) | +-LINKAGE------+------+--+----+--+-environment-name-1-+-+ | '-TYPE-' '-IS-' '-PROCEDURE----------' | | (1) | '-PROCEDURE---------------------------------------------' >--+--------------------------+---------------------------------> | .---------------. | | V | | '-USING----| BY Phrase |-+-' >--+-----------------------------------------------------------+--> | (1) | '-+-RETURNING-----+--+------+--+------------+--identifier-4-' | (1) | '-INTO-' '-ADDRESS OF-' '-GIVING--------' >--+------------------------------------------------------+-----> +-| ON EXCEPTION Phrase |--| NOT ON EXCEPTION Phrase |-+ '-+----+--OVERFLOW--imperative statement-3-------------' '-ON-' >--+----------+------------------------------------------------>< '-END-CALL-' BY Phrase .--------------------------------------. V | |--+-+-------------------+----+-+----------------+--identifier-2-+-+-+--| | '-+----+--REFERENCE-' | | (1) | | | | '-BY-' | '-ADDRESS OF-----' | | | | (1) | | | '-+-file-name-1-----+--------------' | | | (1) | | | '-OMITTED---------' | | .--------------------------------------. | | V | | +-+----+--CONTENT----+-+----------------+--identifier-2-+-+-------+ | '-BY-' | | (1) | | | | | +-ADDRESS OF-----+ | | | | | (1) | | | | | '-LENGTH OF------' | | | | (1) | | | '-+-literal-2-------+--------------' | | | (1) | | | +-file-name-1-----+ | | | (1) | | | '-OMITTED---------' | '-| BY VALUE Phrase |---------------------------------------------' BY VALUE Phrase .-------------------------------------------------. (1) V | |--+----+--VALUE--------+-+------------+--identifier-3----------------+-+--| '-BY-' | +-ADDRESS OF-+ | | '-LENGTH OF--' | '-+-literal-3-------------------------------+-' '-+-float-literal-1-+--| SIZE IS Phrase |-' '-integer-1-------' SIZE IS Phrase |--+-------------------------+----------------------------------| '-SIZE--+----+--integer-2-' '-IS-' ON EXCEPTION Phrase |--+----+--EXCEPTION--imperative statement-1--------------------| '-ON-' NOT ON EXCEPTION Phrase |--NOT--+----+--EXCEPTION--imperative statement-2---------------| '-ON-'
- IBM Extension
- identifier-1
- Must be an alphanumeric or a procedure-pointer data item. For an alphanumeric data item, the following rules apply:
- If the linkage is to a program object, the contents of identifier-1 must conform to the rules for formation of a program-name. The first 10 characters of identifier-1 are used to make the correspondence between the calling and the called program.
- If the linkage is to a procedure, the first 256 characters of identifier-1 are used. The called procedure must be in the same compilation unit as the calling procedure.
- Depending on the compiler option *MONOPRC, the contents of identifier-1 might need to be uppercase and conform to the rules for formation of program-names.
Procedure-pointer data items must be set to the address of a program or a procedure using the SET statement prior to the CALL. For information on setting procedure-pointer data items, see Format 6 - Procedure-Pointer Data Item.
- literal-1
- The CALL linkage determines the type of program called and thus
also restricts the content and size of literal-1. The linkage made
is either to a program object or an ILE procedure. If the linkage
is to a program object, then literal-1 must be nonnumeric, uppercase
(except for an extended system name), and must conform to the rules
for formation of program-names. The first 10 characters of the literal
are used to make the correspondence between the calling program and
the called subprogram. Literal-1 can contain an extended name.
If the linkage is to an ILE procedure, then literal-1 must be nonnumeric and at most 256 characters long. Depending on the compiler option *MONOPRC, literal-1 might need to be uppercase and conform to the rules for formation of program-names. The literal must specify the program-name of the called subprogram.
