ContentsIndexPreviousNext

Calling the Runtime DLL

In order to call the ACUCOBOL-GT 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: There are two declarations shown above. "AcuCall" supports fourteen optional parameters, and "AcuCall50" supports fifty optional parameters. "AcuCall50" has the same format as "AcuCall", except that you must include the full list of fifty 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)

Then you must 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. It is safe to 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 will appear when you actually call a COBOL program.

2. Then 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 will call 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

Note that there are two calls available to you. "AcuCall" supports fourteen optional parameters, and "AcuCall50" provides support for up to fifty 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 fifty parameters.
3. Call AcuShutdown after you are completely finished using COBOL in your Visual Basic application.
Important note: 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 that if a COBOL program issues a STOP RUN, AcuCall will return, the runtime environment will be initialized, and the calling process will continue running. This is so that STOP RUN will 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")