Using .NET Assemblies in COBOL

The .NET bridging interface includes a graphical utility known as NETDEFGEN. This utility allows you to view and select .NET assemblies for translation to a COBOL COPY file. It is similar to the AXDEFGEN utility that ACUCOBOL-GT provides for programming with ActiveX and COM objects. However, NETDEFGEN is designed to work with .NET assemblies.

The COPY files generated by NETDEFGEN supply the ACUCOBOL-GT compiler with all the necessary information for interfacing with .NET assemblies. When you include the COPY files in your COBOL program, you can interact with the .NET assembly via these COBOL statements: DISPLAY, CREATE, MODIFY, INQUIRE, and DESTROY.

Invoke .NET assemblies from your ACUCOBOL-GT program as follows:

If it is not installed already, install and register the .NET framework on your development system.
Run "netdefgen.exe". It is located in the \AcuGT\bin directory wherever you installed ACUCOBOL-GT on your machine. NETDEFGEN locates the .NET assemblies in the Global Assembly Cache (GAC) on the machine and lists them. For more information on the NETDEFGEN utility, see the NETDEFGEN Utility Reference later in this chapter.)
From the list of cached assemblies displayed in the NETDEFGEN dialog box, select the .NET assembly that you want to include in your COBOL program, then select the NameSpace class or classes that you specifically want to access.
Note: If the assembly of interest is not in the GAC, use the Browse button to navigate to the directory where the assembly resides.
Specify an output path and filename for the COBOL COPY file that will be generated. Click Generate when done.
The utility automatically generates a COPY file for the chosen assembly. For information on the contents of NETDEFGEN COPY files, see the NETDEFGEN Utility Reference.

The utility also generates something known as an event DLL. The event DLL is named after the NameSpace class found in the COPY file, appended by the suffix ".dll".
In a code editor, open your ACUCOBOL-GT program and go to its Environment Division/Configuration Section.
In the COBOL program's Special-Names paragraph, enter a COPY statement for the COPY file that you specified in step 4. If you are adding several .NET assemblies, copy several COPY files into this paragraph. Add a period at the end of the paragraph. For example:
```
SPECIAL-NAMES
COPY "netcontrol1.def".
COPY "netcontrol2.def".
.
```
Add the .NET control to your program. Minimally, you must include the ASSEMBLY-NAME, NAMESPACE, and CLASS-NAME parameters that are found in the COPY file.
If the .NET control that you are adding is graphical, (i.e., it has the word "Visual" in the COPY file NameSpace class definition), you can add it to your program in one of two ways:
1. Go to the Screen section of your program and add the new control to your screen. For example:
```
screen section.
01  screen-1.
    03 SOME-NETCONTROL, "@My.Assembly",
       LINE 1, COL 2,
       NAMESPACE IS "My.Test.Namespace",
       CLASS-NAME IS "MyGUIClass",
        CONSTRUCTOR IS CONSTRUCTOR2(PARM1, PARM2, PARM3,
       PARM4, PARM5, PARM6, PARM7),
       EVENT PROCEDURE IS USERCONTROL-EVENTS.
```
2. Go to your program's Procedure Division and create the control using the DISPLAY statement. For example:
```
DISPLAY "@My.Assembly"
     NAMESPACE IS "My.Test.Namespace"
     CLASS-NAME IS "MyGUIClass"
     EVENT PROCEDURE IS MY-EVENT-PROCEDURE 
     HANDLE IS MY-GUI-HANDLE.
If the .NET assembly that you are adding is non-graphical, use the CREATE statement to add it to your program as shown below:
CREATE "@My.Assembly"
     NAMESPACE IS "My.Test.Namespace"
     CLASS-NAME IS "MyClass"
     HANDLE IS MY-NONGUI-HANDLE.
```
  Note that .NET properties, methods, and events should always be prepended with an "@" sign in case they clash with COBOL reserved words or ACUCOBOL-GT graphical control property and style names. The "@" character identifies the relationship of the name to .NET or ActiveX.
Add any optional .NET parameters to the Screen Section, DISPLAY, or CREATE statement. For example, add the FILE-PATH parameter to point to assemblies that will not be placed in the end-user's GAC (you must first create an XML file containing the file path), or add the CONSTRUCTOR parameter to instantiate a class. Valid .NET parameters are described in NETDEFGEN COPY files.

Perform whatever functions you want on the control. If desired, you can modify a .NET control's properties or invoke methods using the MODIFY statement. For example:

MODIFY MY-NONGUI-HANDLE printIteration = NUMBRPRINTS.
MODIFY MY-NONGUI-HANDLE lastName = LAST-NAME. 
MODIFY MY-NONGUI-HANDLE "ToLog"("Hello From COBOL", 99, "It's a Good Thing").
If you want to retrieve a property value, you can use the INQUIRE statement.  For example:
INQUIRE MY-NONGUI-HANDLE printIteration IN QPRINTS.
INQUIRE MY-NONGUI-HANDLE lastName IN LAST-NAME.

To destroy .NET controls, use the DESTROY statement. Ultimately, all controls that you instantiated in step 7 should be destroyed. You can use DESTROY ALL to destroy all controls in the Screen section or created with a DISPLAY statement. However, if the control was created with a CREATE statement, then it must be destroyed with a Format 1 DESTROY handle-name statement.
Note: For details on using the CREATE, DISPLAY, MODIFY, INQUIRE, and DESTROY statements, see Procedure Division Statements. A complete sample program is provided below for your reference.
Compile the COBOL program.
Update the configuration file named "NetEvents.ini" with path statements of the event DLL(s) created when you ran NETDEFGEN, or place the DLL(s) in the same directory as the ACUCOBOL-GT runtime, "wrun32.exe". The runtime must be able to access these event DLLs as well as the .NET assembly itself.
Run your COBOL program via "wrun32.exe MyProgram.acu".

At run time, your COBOL program transparently starts the .NET CLR, loads the requisite .NET assemblies and event handlers, executes .NET assembly methods, and returns the results to the COBOL program.