CALL
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 considered only if
iscobol.code_prefix is set. Relative paths in
Program-Name are appended to the code-prefix paths.
16. A special register named RETURN-CODE is automatically created by the compiler and is shared by all programs of a run unit. This special register is defined as:
77 RETURN-CODE SIGNED-LONG EXTERNAL. |
If you call a C program , the return value of the C function is placed into this register. If you call the
SYSTEM library routine, the status of the call is placed into this register. The verbs
EXIT,
STOP, and
GOBACK can also place a value into the RETURN-CODE register. The compiler also creates an unsigned version of the return code called RETURN-UNSIGNED. It has the following implied definition:
77 RETURN-UNSIGNED REDEFINES RETURN-CODE UNSIGNED-LONG EXTERNAL. |
If the RETURNING phrase is used, then the return value of the called program is moved to Return-Val. This is accomplished by the following rule:
o If Return-Val is a signed data item, then the value of RETURN-CODE is moved to Return-Val.
o If Return-Val is unsigned, then RETURN-UNSIGNED is moved instead.
You should avoid using RETURN-CODE or RETURN-UNSIGNED for Return-Val. This is pointless because, after assigning a value to Return-Val, the CALL statement restores the previous value of RETURN-CODE.
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.
Note - The above search is performed only the first time the subroutine is called. Once found, the runtime keeps track of the subroutine location. The next time the same subroutine is called, the runtime looks for it directly in the right place. In this way, the performance of the CALL statement is improved.
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.
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.
A program compiled with
-cp option can’t call a C function with a CALL CLIENT statement, it can use only CALL.
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:
Use the following syntax to load a DLL library with PASCAL convention:
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 synchronously or 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
Format 2 - Call a program and run it in parallel with current one (on different thread).
Format 3 - Call a program terminating the current run unit and starting a new one