Calling the Runtime DLL

For 32-bit Windows users, the ACUCOBOL-GT runtime is available in a DLL file.

To call the runtime DLL from another programming language, you must add certain declarations to the source program. This example shows what you would use in Visual Basic:

Declare Function AcuInitialize Lib "wrun32.dll" _ 
   (Optional ByVal cmdLine As String) As Integer 
 
Declare Sub AcuShutdown Lib "wrun32.dll" () 
 
Declare Function AcuCall Lib "wrun32.dll" _ 
   (ByVal name As String, _ 
     Optional param1, _ 
     Optional param2, _ 
     Optional param3, _ 
     Optional param4, _ 
     Optional param5, _ 
     Optional param6, _ 
     Optional param7, _ 
     Optional param8, _ 
     Optional param9, _ 
     Optional param10, _ 
     Optional param11, _ 
     Optional param12, _ 
     Optional param13, _ 
     Optional param14) As Integer 
 
Declare Function AcuCall50 Lib "wrun32.dll" _ 
   (ByVal name As String, _ 
     Optional param1, _ 
... 
     Optional param50) As Integer
Note: Two declarations are shown. "AcuCall" supports 14 optional parameters, and "AcuCall50" supports 50 optional parameters. "AcuCall50" has the same format as "AcuCall", except that you must include the full list of 50 parameters in your declaration. The code example for "AcuCall50" was abbreviated.
Declare Function AcuGetCallError Lib"wrun32.dll" () As Integer 
 
Declare Sub AcuCancel Lib "wrun32.dll" (ByVal name As String)

After you add the declarations, you initialize the runtime, call the COBOL program(s) passing the program name and parameters, and shut down when you are finished. For example, in Visual Basic you would perform the following steps:

  1. Call "AcuInitialize" to pass the runtime's command-line options. For example:
    returnValue = AcuInitialize("-c myconfig -le myerrors")

    "AcuInitialize" returns a value of "0" on success and "-1" on failure. You can safely call "AcuInitialize" multiple times. The command line from the first call is used and is ignored on subsequent calls.

    You may use the runtime "-d" option to debug your ACUCOBOL-GT program. Specify "-d" in the command line to "AcuInitialize", and the debugger window appears when you actually call a COBOL program.

  2. Call "AcuCall" or "AcuCall50", passing the program name and parameters. For example, to call the program "vb-test" with "AcuCall", enter:
    returnValue = AcuCall("vbtest.acu", testNum, 
       testStr, testLongNum, testFloat)

    "AcuCall" returns "0" on success and "-1" on failure. If "AcuInitialize" hasn't been called yet, "AcuCall" calls it, passing an empty command line. If "AcuCall" returns "-1", you may call "AcuGetCallError" to get the error code. The error codes are as follows:

    -4 "AcuCall" (or "AcuCall50") has been called in multiple threads.
    -3 "AcuInitialize" failed. ("AcuInitialize" cannot be called after "AcuShutdown" in a single process.)
    1 Program missing or inaccessible
    2 Not a COBOL program
    3 Corrupted program
    4 Inadequate memory available
    5 Unsupported version of object code
    6 Program already in use
    7 Too many external segments
    25 Connection refused; perhaps AcuConnect is not running
    27 Program contains object code for a different processor
    28 Incorrect serial number
    30 License error
    Note: Two calls are available to you. "AcuCall" supports 14 optional parameters, and "AcuCall50" supports for up to 50 optional parameters. "AcuCall50" calls the runtime in the same way as "AcuCall", just use the appropriate name in the Visual Basic syntax. The return values are exactly the same. The declaration is similar, but you must declare all 50 parameters.
  3. Call "AcuShutdown" after you are completely finished using COBOL in your Visual Basic application. It is absolutely essential to call "AcuShutdown" from the VB program after the final call to COBOL. Failure to call "AcuShutdown" before the VB program ends will likely cause the Visual Basic integrated environment to crash, resulting in the loss of any unsaved VB program changes.
    Note: If a COBOL program issues a STOP RUN, "AcuCall" returns, the runtime environment is initialized, and the calling process continues running. This sequence occurs so that STOP RUN does not shut down the calling application or development environment you are using.
  4. To cancel a COBOL program, call "AcuCancel" passing the name of the program. For example:
    AcuCancel("vbtest.acu")