NETDEFGEN Utility Reference

The NETDEFGEN utility is a wizard-based application designed to facilitate the consumption of .NET assemblies from Windows-based ACUCOBOL-GT programs. The role of NETDEFGEN is to locate the names of .NET assemblies on the user’s machine and generate a COBOL COPY file for the selected assembly.

The COPY file is used by the ACUCOBOL-GT compiler for syntax and parameter type checking as well as efficient code generation. For instructions on how to use NETDEFGEN and what to do with the COPY file once it is generated, see Using .NET Assemblies in COBOL.

NETDEFGEN interrogates the assembly and produces an English translation for NameSpaces, classes, methods, enumerations, properties, and events that the ACUCOBOL-GT compiler understands. At run time, the COBOL program accesses the assembly using a NameSpace and class from the COPY file.

The resultant COPY file is included in a COBOL program for use by the compiler and programmer. In addition to the COPY file, NETDEFGEN generates event handlers for each class in the assembly. This is native MSIL code that listens for .NET assembly events, routes them to the ACUCOBOL-GT runtime, which in turn delivers events to the COBOL program. Event handlers are loaded by the runtime when the COBOL program executes a DISPLAY or CREATE statement or has a reference to an assembly in a Screen Section. The runtime locates event handlers from a configuration file called "NetEvents.ini". This file contains a list of directory paths indicating where to search for event handlers. "NetEvents.ini" must be located in the same directory as the runtime. If "NetEvents.ini" is not present, the runtime attempts to load event handlers from the folder where the runtime is located.

Windows base types-such as integer, unsigned integer, float, double, byte, character, and character string-are supported. Any method or constructor requiring parameter object creation by the COBOL program fails. For instructions on how to use .NET objects as parameters, see Creating and Passing .NET Objects as Parameters.

Note: If you want to include a .NET assembly in your COBOL application,you must first acquire it and install it on the development machine. If you have downloaded the control off the Internet, you may need to license it for distribution. see .NET Control Distribution and Licensing for more information.

The netdefgen.exe file is located in the \AcuGT\bin directory wherever you installed ACUCOBOL-GT. It is accessible from the Windows Start menu. When you run NETDEFGEN, the opening wizard screen appears:

Field or Button	Description
Assembly Location	Browse to the directory where the assembly from which you want to produce a COPY file resides. By default, this is the computer’s path to the Global Assembly Cache (GAC). Click the GAC button to restore this field to the GAC path at any time.
Assemblies	If the Global Assembly Cache (GAC) is the currently selected Assembly Location, then a tree view is displayed that contains all the assemblies found in the GAC. Due to the large number of assemblies, the list is grouped by processor architecture. If the directory selected is other than the GAC, then all of the DLL and EXE files in that directory are listed (both assemblies and non-assemblies). Select the assembly of interest from the list. All NameSpaces and classes found in that assembly display in the list box labeled Namespace Classes.
Help	Click the Help button to view the help file for the utility.
Exit	Select Exit from the menu bar to exit the utility.
Settings	Select Settings from the menu bar to change the default settings of the utility, including diagnostic settings. See Changing Default NETDEFGEN Settings for more information.

After selecting the Assembly desrired, click Next to continue to the next page.

Field or Button	Description
Namespace Classes	By default, when an assembly has been selected from the Assemblies list, all of the items found in the assembly are selected. Assemblies can contain many NameSpaces and classes, which can result in very large COPY files containing many references and declaration that are unused by your application. To reduce the size of your COPY file, select only those items that are needed by your application.

Click Next to continue to the next page.

Field or Button	Description
Class Members	The Tree View shows the Data Members (constructors, methods. fields, properties, and events) for the selected classes. By default, all members are selected. Uncheck the boxes next to any members you do not need in your COBOL application. Constructors cannot be unchecked. If the class is an enumerator, you may uncheck the whole class but not individual value fields.
Show Inherited Members	Checking this box will display all data members that are inherited from every ancestor. This will usually add a massive number of data members to the list. Use this option if a property, method, etc. that you want to use in your COBOL application is inherited from a parent class.

Field or Button

Description

Class Members

The Tree View shows the Data Members (constructors, methods. fields, properties, and events) for the selected classes. By default, all members are selected. Uncheck the boxes next to any members you do not need in your COBOL application.

Constructors cannot be unchecked.

If the class is an enumerator, you may uncheck the whole class but not individual value fields.

Show Inherited Members

Checking this box will display all data members that are inherited from every ancestor. This will usually add a massive number of data members to the list. Use this option if a property, method, etc. that you want to use in your COBOL application is inherited from a parent class.

Click Next to continue to the next page.

Field or Button	Description
Copy File Location	Browse to the directory and filename of the COPY file to generate. If event handlers are generated, they will be located in the same directory with a filename prefix of the NameSpace and Class and a suffix of .dll.

Click Next to continue to the next page.

Field or Button	Description
Stored Objects.	If any of the Properties, Methods, etc., have parameters that are .NET objects, they will be listed here. To use MODIFY or INQUIRE on these objects, they must be included in the generic NETOBJECT class. If you only need to pass these objects from one strongly defined class to another, you do not need a definition for them. For detailed information on using objects as parameters, see Creating and Passing .NET objects as parameters.
Skip	Don't care about Stored Objects? Click the Skip button and no NetObject definition file will be generated.

Field or Button

Description

Stored Objects.

If any of the Properties, Methods, etc., have parameters that are .NET objects, they will be listed here. To use MODIFY or INQUIRE on these objects, they must be included in the generic NETOBJECT class. If you only need to pass these objects from one strongly defined class to another, you do not need a definition for them.

For detailed information on using objects as parameters, see Creating and Passing .NET objects as parameters.

Skip

Don't care about Stored Objects? Click the Skip button and no NetObject definition file will be generated.

Click Next to continue to the next page.

Field or Button	Description
Stored Object Master List	These are the Stored Objects whose members will be included in the NetObject definition file. It starts out with the objects that were selected on the previous page. You can add more objects as needed (see Add to Master List below). Select an object to display its Data Members.
Data Members	The Tree View shows the Data Members (methods. fields, and properties) for the selected object. By default, all members are checked. Uncheck the boxes next to any members you do not need in your COBOL application. If the object is an enumerator, you may uncheck the whole class but not individual value fields.
Show Inherited Members	Checking this box will display all data members that are inherited from every ancestor. This will usually add a massive number of data members to the list. Use this option if a property, method, etc. that you want to use in your COBOL application is inherited from a parent class.
More Stored Objects	If any of the selected members have parameters that are also objects, they will be listed here.
Add to Master List	To add nested objects to the master list for inclusion in the NetObject COPY file, select the objects and click this button. You may then select them and edit their Data Members.

Click Next to continue to the next page.

Field or Button	Description
Stored Object Copy File Location	Browse to the directory and filename of the NetObject COPY file to generate.
Append or Overwrite	All Fields, Properties, and Methods for all Stored Objects that will be used in the COBOL program must be defined in the generic NETOBJECT class. Select Append to add the Stored Object definitions to an existing NetObject copy file. Select Overwrite to generate a new file. These options only appear if the file exists.

Field or Button

Description

Stored Object Copy File Location

Browse to the directory and filename of the NetObject COPY file to generate.

Append or Overwrite

All Fields, Properties, and Methods for all Stored Objects that will be used in the COBOL program must be defined in the generic NETOBJECT class.

Select Append to add the Stored Object definitions to an existing NetObject copy file.

Select Overwrite to generate a new file.

These options only appear if the file exists.

Click Next to continue to the next page.

Field or Button	Description
Generate	Click this button to generate the COPY file, any required event handlers, and the NetObject COPY file if necessary. Success or failure messages appear when the process is complete.