Using the ACUCOBOL-GT COM Server

For ease of use in Windows environments, the ACUCOBOL-GT runtime is available as a COM server. With the COM server, you can treat the ACUCOBOL-GT system as a COM object and include it in applications that support COM.

To use the COM server in other programs:

Register the ACUCOBOL-GT COM server. Registration occurs automatically when you load the ACUCOBOL-GT runtime using the setup program that comes with the software.
When you distribute your application, if you are not using the ACUCOBOL-GT setup program, you will have to install and register the COM server on each user's machine. If you are using it as a remote server, you must install and register the ACUCOBOL-GT runtime with the COM server option on the server machine. Register the ACUCOBOL-GT COM server by running it with no command-line options or with the "/RegServer" option. This command-line option is not case sensitive.

Note: On 64-bit operating systems you must run with elevated priviliges.

The ACUCOBOL-GT COM server executable is in the ACUCOBOL-GT bin directory after installation. This file is named "AcuGT.exe". The ACUCOBOL-GT COM server requires the same files as the ACUCOBOL-GT runtime, except for "wrun32.exe". Two additional files, "AcuGT.exe" and "AcuGT.tlb", must be installed on the machine in a single directory. For the COM server to work, the runtime DLL "wrun32.dll" must either be in the same directory as "AcuGT.exe" or somewhere else in the Windows DLL search path. If you move "AcuGT.exe" to a different directory, you must register it again from the new location.

Note:
If you ever need to unregister the ACUCOBOL-GT COM server, run "AcuGT /UnregServer".
Start the other programming language's development environment and add the current "ACUCOBOL-GT Library" to your project references.
Add code to declare and create the AcuGT object. For example, in Visual Basic you could enter:
```
Dim cblObj As Object
Set cblObj = New AcuGT
```

Control the ACUCOBOL-GT COM server using the "Initialize", "Call", "Call50", "Cancel", and "Shutdown" methods described in Methods of the COM server object. For example, from Visual Basic you would enter:

cblObj.Initialize "-d"   ' Start ACUCOBOL-GT in debug mode
retVal = cblObj.Call(programName, arg0, arg1, arg2)
cblObj.Shutdown

or use the "With" construct. For example:

With cblObj
  .Initialize "-e @myserver:\myprogs\errorfile"
  .Call "*myserver:\myprogs\program1.acu", "call1", 1.2, 37
  .Call "*myserver:\myprogs\program1.acu", "call2", 2.3, 38
  .Call "*myserver:\myprogs\program1.acu", "call3", 3.4, 39
  .Cancel "*myserver:\myprogs\program1.acu"
End With

If you don't explicitly call "Initialize", the COM server calls it for you, passing an empty command-line parameter. Likewise, if you don't explicitly call "Shutdown", the COM server calls it for you when the object is destroyed.

In this example, after the AcuGT object is created in Visual Basic, "Initialize" is called automatically. Then, when the AcuGT object is destroyed at the end of the subroutine, the "Shutdown" method is called automatically:

Private Sub Command1_Click()
  Dim cblObj As Object
  Set cblObj = New AcuGT
  cblObj.Call "program"
End Sub

If you have several COBOL calls to make, it is much more efficient to create the AcuGT object as a Public variable in the module, class, or form initialization. For example, this may be done using the Visual Basic CreateObject function:

Dim cblObj As Object
Set cblObj = CreateObject("AcuGT.Application");

The Visual Basic CreateObject function takes an optional second parameter–the name of the network server where the object is created. For example, if you want to run the COBOL program on a remote machine named MOOSE, use the following syntax:

Set cblObj = CreateObject("AcuGT.Application", "MOOSE");

The COM server sets the "current directory" for COBOL programs to the directory containing "AcuGT.exe". This allows you to use relative directory paths when you specify file names. For example, suppose you have installed the COM server in C:\AUTOSRV\BIN, the COBOL programs and configuration files you want to use in C:\AUTOSRV\PROGRAMS and the data files in C:\AUTOSRV\DATA. You could then call the "Initialize" method with "-c ..\PROGRAMS\CONFIG", set CODE_PREFIX to "..\PROGRAMS" and set FILE_PREFIX to "..\DATA".

The ACUCOBOL-GT COM server is thread-safe, meaning that you can run COBOL programs asynchronously. To do this, you must create a new thread and a new AcuGT object in that thread. Then you call the COBOL program from that thread.

For an example of how to create new threads in Visual Basic, see Creating a Multithreaded Test Application in the Visual Basic documentation.

It is a good idea to trap errors and handle them with your own Visual Basic error handler. For example:

   On Error GoTo ErrHandler
   cblObj.Call "program"
Exit Sub

ErrHandler:
   myval = MsgBox(Err.Description, vbOKOnly, 
      "Call not successful")
End Sub