The acu_cobol() function allows you to call COBOL programs and control how they are executed. This function is required in order to build and invoke the ACUCOBOL-GT runtime with a transaction processing environment like CICS.

Note: This function deprecates the cobol() and cobol_no_stop() functions.

To call COBOL subroutines directly from C, you can use the acu_cobol() routine anytime after acu_initv() has been called and before acu_shutdown() has been called.

For more information, see Calling the Runtime From a C Main Program.


The acu_cobol() function has the following prototype:

int ASTDCALL acu_cobol(ACUCOBOLINFO *data);

The struct a_cobol_info structure is defined in lib/sub.h:

struct  a_cobol_info 
size_t       a_cobol_info_size;
char         *pgm_name;
int          num_params;
Argument     *params;
int          exit_code;
const char   *exit_msg;
int          signal_number;
int          call_error;
long         cobol_return_code; 
unsigned     no_stop:1; 
unsigned     cache:1; 
ADM_t        debug_method; 
char         *debug_method_string; 
void         *internal; /* internal should be NULL */
typedef struct a_cobol_info ACUCOBOLINFO;

The ADM_t type is described in lib/sub.h as an enumeration.

typedef enum tag_ACUCOBOL_DEBUG_METHODS 

The enumeration values describe the debugging method to be used for the program. See the Parameters section below for more information.


The a_cobol_info structure has the following parameters. Input variables are set before the call to acu_cobol() and output variables set after acu_cobol() returns:

a_cobol_info_size A size_t initialized to sizeof(a_cobol_info) to allow for future expansion (input)
pgm_name A char* that contains the name of the COBOL program to call (input)
num_params An int that contains the number of elements in the params array (input)
params An Argument* that contains an array of arguments sent to the COBOL program (input)
exit_code An int that contains the exit code. refer to the exit_code values in the Return Values section below (output)
exit_msg A const char* that contains the exit message. Its contents should not be modified. This pointer may be NULL. (output)
signal_number An int value of a signal that caused the COBOL_SIGNAL or COBOL_FATAL_ERROR. If the value is non-zero, the error was caused by this signal. (output)
call_error An int value that contains the call error. refer to the call_error values listed in the Return Values section below (output)
cobol_return_code A long value returned in "exit program.nnn" by a COBOL program called from acu_cobol(). The COBOL program can set this value by either setting the return-code or exiting the program. (output)
no_stop An unsigned value that, when set to "1", causes STOP RUN to be ignored (input)
cache An unsigned value that determines whether the runtime should maintain the program in a memory cache after it has been canceled. This parameter is useful for application servers like CICS that allow each program to be configured as resident or nonresident. (input)

If cache is FALSE ("0"), acu_cancel() removes the program from memory and sets the Working-Storage to its initial state on subsequent calls.

If cache is TRUE ("1"), acu_cancel() marks the program as "cached" and resets Working-Storage for the next call; the program remains in memory according to the caching rules. For information on managing logical and physical cancels that may affect the behavior of cache, see LOGICAL_CANCELS.

debug_method An ADM_t type that defines the debugger method to use for the program when acu_cobol() is called. The debug_method is deinitialized when the COBOL program returns. (input)

To enable background debugging, specify one of the following types:

  • ADM_NONE — For no debugging
  • ADM_XTERM — Debug using a new xterm
  • ADM_TERMINAL — Debug using an existing terminal through runcbl
  • ADM_THINCLIENT — Debug using a waiting thin client
Based on the debug_method selected, you may need to also specify debug_method_string:
debug_method_string A char* that sets the display setting for the debug_method (input)
  • For ADM_XTERM, set to the Xservername:displaynumber of the xterm or set to NULL to allow the xterm to use the default display given by the DISPLAY environment variable.
  • For ADM_TERMINAL, set the string to the tty device on which you will execute runcbl.
  • For ADM_THINCLIENT, set to client:port where the client is the host on which acuthin is executing and port is the port on which it is listening.
Note: The value of debug_method_string overrides the value, if any, in the DISPLAY configuration variable for the xterm.

See Background Debugging Options for more information.

internal a void pointer that is used by other extend products. Initialize the pointer internal to NULL.

Return values

The acu_cobol() function returns "0" if the call is successful and "-1" if the call failed.

The exit_code returns one of the following values defined in "sub.h":

Value   Description
COBOL_EXIT_PROGRAM 1 The called program finished via an EXIT PROGRAM statement (or equivalent, such as GOBACK).
COBOL_REMOTE_CALL 2 The called program 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 3 The run unit halted due to a STOP RUN statement, and the runtime has been configured to return to the caller instead of exiting to the system.
COBOL_CALL_ERROR 4 The called program could not be run and the acu_cobol() function has returned "-1". This applies only to programs called directly by acu_cobol(). On an error loading a subroutine, acu_cobol() returns COBOL_FATAL_ERROR.
COBOL_SIGNAL* 5 The runtime caught a system signal that would normally shut down the runtime, but the runtime has been configured to return to the caller instead. Any error message associated with this signal is returned in exit_msg.
COBOL_FATAL_ERROR* 6 A fatal error has occurred that would normally shut down the runtime, but the runtime has been configured to return to the caller instead. Any message associated with the error is returned in exit_msg.
COBOL_NONFATAL_ERROR 7 An error has occurred that causes the acu_cobol() function to return and prevents the runtime from continuing to run the current program only. The runtime remains in a stable state and it is safe to make subsequent calls to acu_cobol().
COBOL_DEBUGGER 8 The user has quit the ACUCOBOL-GT debugger. It is safe to make subsequent calls to acu_cobol() after this error occurs.

* After a COBOL_SIGNAL or COBOL_FATAL_ERROR error, the process should not make any further calls to acu_cobol(). If another call is necessary, you must first unload and reload the runtime. If you are dynamically loading the runtime shared library on UNIX/Linux or runtime DLL on Windows, you can do this using dlclose()/dlopen() or FreeLibrary()/LoadLibrary() respectively. If you are linking directly to the runtime libraries, you will need to exit and restart the current process. Consider wrapping your executable in a shell script or another main() program that checks for a particular exit code and then loops.

The call_error can be one of the following values:

Value   Description
CS_SUCCESSFUL 0 Call was successful.
CS_MISSING 1 Program file is missing or inaccessible.
CS_NOT_COBOL 2 Called file is not a COBOL program.
CS_INTERNAL 3 Corrupted program file
CS_MEMORY 4 Inadequate memory is available to load program.
CS_VERSION 5 Unsupported object code version number
CS_RECURSIVE 6 Recursive CALL of a program; program already in use.
CS_EXTERNAL 7 Too many external segments
CS_LARGE_MODEL 8 Large-model program is not supported.
CS_JAPANESE 14 Japanese extensions are not supported.
CS_MULTITHREADED 22 Multithreaded CALL RUN is illegal.
CS_AUTHORIZATION 23 Access denied.
CS_CONNECT_REFUSED 25 Connection refused; user count is exceeded on remote server.
CS_MISMATCHED_CPU 27 Program contains object code for a different processor.
CS_SERIAL_NUMBER 28 Incorrect serial number
CS_USER_COUNT_EXCEEDED     29 Connection refused; user count is exceeded on remote server.
CS_LICENSE 30 License error