CALL

General Format

Format 1

CALL {CLIENT} Program-Name      {IN THREAD}   [ HANDLE IN Handle-1 ]      [ USING { [ BY {REFERENCE} ] { {Parameter} } ... } ... ]                  {CONTENT  }     {OMITTED  }                  {VALUE    }          [ {RETURNING} INTO Return-Val ]     {GIVING   }     [ ON {EXCEPTION} Statement-1]        {OVERFLOW }     [ NOT ON {EXCEPTION} Statement-2]            {OVERFLOW }     [END-CALL]

Format 2

CALL RUN Program-Name     [ USING { [ BY {REFERENCE} ] { {Parameter} } ... } ... ]                  {CONTENT  }     {OMITTED  }                  {VALUE    }          [ {RETURNING} INTO Return-Val ]     {GIVING   }     [ ON {EXCEPTION} Statement-1]        {OVERFLOW }     [ NOT ON {EXCEPTION} Statement-2]            {OVERFLOW }     [END-CALL]

Format 3

CALL PROGRAM Program-Name     [ USING { [ BY {REFERENCE} ] { {Parameter} } ... } ... ]                  {CONTENT  }     {OMITTED  }                  {VALUE    }          [ {RETURNING} INTO Return-Val ]     {GIVING   }     [ ON {EXCEPTION} Statement-1]        {OVERFLOW }     [ NOT ON {EXCEPTION} Statement-2]            {OVERFLOW }     [END-CALL]

Syntax Rules

All Formats

1.	Program-Name shall be defined as an alphanumeric data item or String literal.

2.	Parameter shall reference an address-identifier or a data item defined in the file, working-storage, and linkage.

3.	Return-Val shall reference a data item defined in the file, working-storage or linkage.

4.	The USING clause can appear either before or after the GIVING clause.

Formats 1 and 2

5.	If the BY REFERENCE phrase is specified or implied for a Parameter, it shall be neither a strongly-typed group item.

General Rules

All Formats

1.	The instance of the program, or method that executes the CALL statement is the activating runtime element.

2.

The sequence of arguments in the USING phrase of the CALL statement and the sequence of formal parameters in the USING phrase of the called program’s procedure division header determine the correspondence between arguments and formal parameters. This correspondence is positional and not by name equivalence.

 

NOTE - The first argument corresponds to the first formal parameter, the second to the second, and the nth to the nth.

3.

Program-Name and Parameter are evaluated and item identification is done for Return-Val at the beginning of the execution of the CALL statement. If an exception condition exists, no program is called and execution proceeds as specified in general rule 6. If an exception condition does not exist, the value of identifier-2 is made available to the called program at the time control is transferred to that program.

4.	The program being called is identified by its program-name or its location, which is determined as follows:

A.	If Program-Name references an alphanumeric or national data item, program-name is the program-name of the program being called

B.	If the program being called is a COBOL program, the runtime system attempts to locate the program being called.

5.	If a fatal exception condition has not been raised, the program specified by the CALL statement is made available for execution and control is transferred to the called program.

6.	If the program was not successfully called the following actions occur:

A.

If the ON OVERFLOW or ON EXCEPTION phrase is specified in the CALL statement, control is transferred to Statement-1. Execution then continues according to the rules for each statement specified in Statement-1. If a procedure branching or conditional statement that 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 Statement-1, control is transferred to the end of the CALL statement and the NOT ON EXCEPTION phrase, if specified, is ignored.

ii.	If an ON OVERFLOW nor an ON EXCEPTION phrase is specified, an error is returned

B.

If the program was successfully called, after control is returned from the called program the ON OVERFLOW or ON EXCEPTION phrase, if specified, is ignored. Control is transferred to the end of the CALL statement or, if the NOT ON EXCEPTION phrase is specified, to Statement-2. If control is transferred to Statement-2, execution continues according to the rules for each statement specified in Statement-2.

7.	If a RETURNING phrase is specified, the result of the activated program is placed into Return-Val.

8.

BY CONTENT, BY REFERENCE and BY VALUE phrases are transitive across the parameters that follow them until another BY CONTENT, BY VALUE or BY REFERENCE phrase is encountered. If neither the BY CONTENT nor the BY VALUE nor the BY REFERENCE phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

9.

BY REFERENCE causes the address of the data item to be passed to the receiving program. BY CONTENT and BY VALUE cause the address of a copy of the data item to be sent, therefore any changes made to the parameter in the called program are not seen by the caller. When passing parameters to C functions with either BY CONTENT or BY REFERENCE clauses, isCOBOL passes the address of the data item, unless the data item is an integer, in that case the item value is passed.

10.	When a literal is passed, it’s passed as a USAGE DISPLAY data item.

11.	Dynamic length items are always passed BY REFERENCE.

12.	The program identified by Program-Name is searched among the paths specified by the iscobol.code_prefix setting. If the code-prefix is not set, then the program is searched in the Classpath.

13.	Extensions in Program-Name are automatically stripped by the runtime.

14.	Paths in Program-Name are resolved only if the program is searched in the code-prefix.

Format 1

1.	A called subroutine is searched in this order:

A.	if the name is the exact name of a shared library then the shared library is loaded in memory. Otherwise

B.	the subroutine is searched among the statically declared C functions. If not found

C.	the subroutine is searched among the C functions available in the already loaded shared libraries. If not found

D.	the subroutine is searched among the isCOBOL library subroutines. If not found

E.	the subroutine is searched among the user subroutines. If not found

F.	the runtime decorates the subroutine name in a shared library name (e.g. foo may become foo.dll or libfoo.so, depending on the O.S.) and tries to load it. If the library is successfully loaded, then the runtime looks for a function with the same name (foo), otherwise

G.	the subroutine is searched among the remote available subroutines, if any.

2.	The THREAD clause makes the called program run asynchronously with the calling program.

When a program is called asynchronously, it’s good practice to pass parameters BY VALUE. Passing parameters BY REFERENCE may produce unexpected results.

When a program is called asynchronously, the runtime looks for it only locally ignoring iscobol.remote.code_prefix.

3.

The CLIENT clause is used when running in ApplicationServer mode to execute the called program on a client machine. The called program on the client can be either a COBOL program, a library routine or a C function. If running without ApplicationServer, the CLIENT clause is ignored. Called COBOL programs on the client must not have been compiled with -cp option.

4.	On AIX systems some libraries (such as libdb2.a) can be called by dynamically specifying the member names. To achieve it with isCOBOL, use the following syntax:

CALL "/lib/foo.a(member.o)"

5.	On Windows systems it is possible to specify the calling convention when the DLL library is loaded. The convention can be specified by adding a slash character followed by the desired convention at the end of the DLL name. Use the following syntax to load a DLL library with CDECL convention:

CALL "foo.dll/0"

Use the following syntax to load a DLL library with PASCAL convention:

CALL "foo.dll/1"

The choosen convention will be adopted by the runtime when calling the functions stored in the loaded DLL library, regardless of the iscobol.dll_convention setting.

Format 2

1.	The CALL RUN statement makes the called program run asynchronously in a separate thread.

2.	The called program doesn’t inherit the environment set by the calling program, but starts in a clean environment instead.

Format 3

1.	CALL PROGRAM works as the CHAIN statement. It causes the current run unit to terminate and initiates a new run unit, but in this case USING parameters are passed to data items specified in the Linkage Section.

Recursive calls

A program may directly or indirectly call itself. Such a CALL statement is considered a recursive call. By default, isCOBOL shares the program data with all recursive calls. Set iscobol.recursion_data_global (boolean) * to false in order to make isCOBOL create a new copy of data for each instance of the program.

Examples

Format 1 - Call a program passing parameters, receiving return code and validating exception.

call "program1" using parm-1 parm-2   giving ret-code   on exception display message "Could not call program1" end-call

Format 1- Call a program on a different thread to run it in parallel with calling program saving the thread handle in p1-handle.

working-storage section. 77 p1-handle  usage handle of thread. ... procedure division. main.   call thread "program1" handle in p1-handle

Format 1 - Call a program client side when running from thin-client

call client "program1"

Format 2 - Call a program and run it in parallel with current one (on different thread).

call run "program1"

Format 3 - Call a program terminating the current run unit and starting a new one

call program "program1"