COBOL routines may be called from C routines. To accomplish this, you call the C function "cobol".
The first parameter passed to "cobol" is the name of the COBOL routine to call. This is resolved just as the name specified in a CALL statement is resolved.
The second parameter is the number of USING parameters you are passing.
The final parameter is an array that contains the USING parameters. This array is of type "Argument" and is described in detail in section C.3.2 under the discussion of the args parameter. Note that only the "a_address" and "a_length" fields need be supplied, although the other fields may be supplied also.
Programs that call the "cobol" routine must be sure to include "sub.h" (included with ACUCOBOL-GT in the "lib" directory). This includes a declaration of the "cobol" routine for all platforms. This ensures that you use the correct calling convention when calling the "cobol" routine. Refer to section C.3.1.1 above and Appendix M, Host Specific Information for details about calling subroutines that are located in DLLs.
The "cobol" function returns "0" if successful and "-1" if it fails. To discover the reason why the "cobol" function has returned, call the routine "cobol_exit_code" using the following prototype:
int cobol_exit_code ( char *msg, int msg_size );
You must include "sub.h" in the code that calls this function. The parameter "msg" may be set to NULL. If it is not NULL, it will be the address of a character array that is filled with any messages associated with a COBOL_SIGNAL or COBOL_FATAL_ERROR exit code (described below). The parameter "msg_size" should be set to the number of characters contained in the "msg" character array. "cobol_exit_code" returns one of the following values defined in "sub.h":
| COBOL_EXIT_PROGRAM
| The program called by "cobol" finished via an EXIT PROGRAM statement (or
equivalent, such as GOBACK).
|
| COBOL_REMOTE_CALL
| The program called by "cobol" is a remote program being run by AcuConnect. In
this case, the exact reason why the remote program finished is not available.
|
| COBOL_STOP_RUN
| The run unit halted due to a STOP RUN statement and the runtime has been
configured to return to the caller of "cobol" instead of exiting to the system.
|
| COBOL_CALL_ERROR
| The program passed to "cobol" could not be run for some reason. It should be
the case that the "cobol" function has returned with a status of "-1". See
below for ways to determine the exact reason the program could not be run. Note that this only applies to the program being directly run by "cobol". If
there is an error loading a subroutine of that program, this will be treated as a
fatal error (see COBOL_FATAL_ERROR below).
|
| COBOL_SIGNAL
| The runtime caught a system signal that would normally shutdown the runtime,
but the runtime has been configured to return to the caller of "cobol" instead.
If there is an error message associated with this signal, it is returned in
"msg".
|
| COBOL_FATAL_ERROR
| A fatal error has occurred that would normally shutdown the runtime, but the runtime has been configured to return to the caller of "cobol" instead. If there is a message associated with the error, it is returned in "msg". |
01 - Program file missing or inaccessible
02 - Called file not a COBOL program
03 - Corrupted program file
04 - Inadequate memory available to load program
05 - Unsupported object code version number
06 - Recursive CALL of a program
Code Example:
call_cobol ( str, length )
char *str;
int length;
{
Argument args[1];
args[0].a_address = str;
args[0].a_length = length;
if ( cobol ( "MYPROG", 1, args ) ) {
printf ("can't load MYPROG, reason code = %d\n",
A_call_err );
}
}