Using the Automation Server

To use the ACUCOBOL-GT Automation Server with other programming languages:

1. Register the ACUCOBOL-GT Automation 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 automation 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 Automation Server option on the server machine. Register the ACUCOBOL-GT Automation Server by running it with no command line options or with the "/RegServer" option. This command line option is not case sensitive.

The ACUCOBOL-GT Automation Server executable is in the ACUCOBOL-GT bin directory after installation. This file is named "AcuGT.exe". The ACUCOBOL-GT Automation 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 Automation 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 Automation Server, run "AcuGT /UnregServer".

2. Start the other programming language's development environment and add the current "ACUCOBOL-GT Library" to your project references.

3. 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

Then you can control the ACUCOBOL-GT Automation Server using the Initialize, Call, Call50, Cancel and Shutown methods described below. 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 Automation Server will call it for you, passing an empty command line parameter. Likewise, if you don't explicitly call "Shutdown", the Automation Server will call 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. This is 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 Automation 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 Automation 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 Automation Server is thread-safe, meaning that you are able to 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 located in MSDN Library Visual Studio 6.0 at:

Visual BasicDocumentation/Using Visual Basic/Component Tools Guide/
Creating ActiveX Components/Building Code Components/
Scalability and Multithreading/Creating a Multithreaded Test Application.

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

The ACUCOBOL-GT Automation Server object has the following methods.

Initialize

Initializes the ACUCOBOL-GT runtime.

Usage:

HRESULT Initialize([in] VARIANT *cmdLine)

Return Value:

"Initialize" returns one of the following result codes (Note that these values are given in hexadecimal format):

Name
Value
Description
S_OK
0
Call succeeded
ACUGT_E_UNEXPECTED
80040200
Unexpected error
ACUGT_E_INITIALIZE
80040201
OLE initialization failed. Make sure that the OLE libraries are the correct version.

Shutdown

Shuts down the runtime.

Usage:

void Shutdown(void)

Call

Calls the runtime.

Usage:

HRESULT Call([in] VARIANT *name,
   [in, out, optional] VARIANT *arg0,
   [in, out, optional] VARIANT *arg1,
   [in, out, optional] VARIANT *arg2,
   [in, out, optional] VARIANT *arg3,
   [in, out, optional] VARIANT *arg4,
   [in, out, optional] VARIANT *arg5,
   [in, out, optional] VARIANT *arg6,
   [in, out, optional] VARIANT *arg7,
   [in, out, optional] VARIANT *arg8,
   [in, out, optional] VARIANT *arg9,
   [in, out, optional] VARIANT *arg10,
   [in, out, optional] VARIANT *arg11,
   [in, out, optional] VARIANT *arg12
   [in, out, optional] VARIANT *arg13 )

Return Value:

"Call" returns one of the following result codes (Note that these values are given in hexadecimal format):

Name
Value
Description
S_OK
0
Call succeeded
ACUGT_E_UNEXPECTED
80040200
Unexpected error
ACUGT_E_MULTIPLE_THREADS
80040203
Call (or Call50) has been called in multiple threads (See "Calling the Runtime DLL)
ACUGT_E_INITIALIZE_FAILED
80040204
Initialize failed. (Initialize can not be called after Shutdown in a single process.) (See "Calling the Runtime DLL)
ACUGT_E_PROGRAM_MISSING
80040205
Program missing or inaccessible
ACUGT_E_NOT_COBOL
80040206
Not a COBOL program
ACUGT_E_CORRUPTED
80040207
Corrupted program
ACUGT_E_INADEQUATE_MEMORY
80040208
Inadequate memory available
ACUGT_E_UNSUPPORTED
80040209
Unsupported version of object code
ACUGT_E_PROGRAM_IN_USE
8004020A
Program already in use
ACUGT_E_TOO_MANY
8004020B
Too many external segments
ACUGT_E_CONNECTION_REFUSED
8004020C
Connection refused - perhaps AcuConnect is not running

Call50

"Call50" calls the runtime in the same way as "Call", except that you may have up to fifty optional parameters. Substitute "Call50" for the word "Call" in the Visual Basic syntax. The return values are exactly the same.

Note that when you call using "Call" or "Call50", you may not exceed fourteen parameters for "Call" or fifty parameters for "Call50."

Cancel

Cancels a COBOL program.

Usage:

void Cancel([in] VARIANT *program )

Name	Value	Description
S_OK	0	Call succeeded
ACUGT_E_UNEXPECTED	80040200	Unexpected error
ACUGT_E_INITIALIZE	80040201	OLE initialization failed. Make sure that the OLE libraries are the correct version.