gennet40 utility

WTSupported in traditional Synergy on Windows

 

 

 

The gennet40 utility generates Synergy classes that wrap the classes defined in a .NET assembly.

To generate wrappers for all classes in an assembly, use this syntax:

gennet40 -output output_file -log log_file assembly [assembly...]

To generate wrappers for specific classes in an assembly, use this syntax:

gennet40 -output output_file -log log_file -s xml_file [xml_file...]

-output output_file

The path and filename of the generated Synergy source file. If an extension is not specified, .dbl will be added. You may use a full directory specification or an environment variable that contains a directory location. If output_file contains an environment variable (for example, MYDIR:myout.dbl), .INCLUDEs in the generated file will also use that environment variable. You can abbreviate -output to -o.

-log log_file

The path and filename of the generated log file. You can abbreviate -log to -l.

assembly

The names of one or more assemblies used for input. If assembly is contained in the GAC, do not specify a filename extension; in all other cases, you should include the extension. Assembly can be a full directory specification or an environment variable that contains a directory location. See Specifying an assembly in the Discussion for more information.

-s xml_file

An XML file that specifies individual classes within an assembly for which you want to generate wrappers. You can also specify a complete assembly in the XML file. See Specifying classes within an assembly (-s) in the Discussion for more information.

Discussion

Gennet40 generates wrappers for one or more .NET assemblies so you can use them in your Synergy applications.

Important

Never run gennet40 twice for a single linked unit. If you run it twice and then link the resulting files together, a “Class CRC mismatch: class class name in module module name” error (CLSCRC) will occur. If you need to rerun gennet40, delete all the existing gennet40 output files first.

Due to .NET Framework security restrictions, gennet40 should not be run against DLLs over a network share.

Compilation time and memory usage can be significant for the wrapper routines generated by gennet40. For large assemblies and assemblies with a large number of dependencies (e.g., .NET Framework assemblies), consider using -s to limit processing to only the classes you will use. See Specifying classes within an assembly (-s).

To use gennet40 follow these steps:

1. Run gennet40, specifying all of the assemblies (including dependent assemblies) that you want to use in your Synergy application.
gennet40 -o gen_output.dbl MyAssembly.dll

This will produce at least two .dbl files (named gen_output.dbl, gen_output1.dbl, gen_output2.dbl, etc.) and an .inc file (gen_output.inc). The latter is no longer needed, but if your setup already uses it, you can continue to do so. The filename.dbl file will contain one or more .INCLUDE statements for the other, numbered .dbl file(s). The exact number of files generated depends on the amount of input. If the input is large, gennet40 breaks the output into multiple files.

See Restrictions and adaptations for information on how various aspects of class wrapper generation are handled.

2. Prototype the generated file (the unnumbered one; gen_output.dbl in our example) using dblproto. See Synergy Prototype utility (dblproto) for more information.
dblproto -out=proto_output.dbp gen_output.dbl
3. Compile the Synergy output file that was created by gennet40 using -qrelaxed:interop to create a .dbo file. See Restrictions and adaptations for information on the requirement to use -qrelaxed:interop.
dbl -qrelaxed:interop -o gen_output.dbo gen_output.dbl
Important

Do not try to build a wrapper routine generated by gennet40 in debug mode.

4. Create a gen_output.elb file from the .dbo file you just created:
dblink –l gen_output.elb gen_output.dbo

We recommend that you use OLBs for gennet40-generated classes when they are used in conjunction with ELBs that contain routines or methods that call the gennet40-generated classes. When linking an ELB with these OLBs, use the -r and -R switches.

5. Compile your Synergy program that uses the wrappers. Make sure the compiler has access to prototypes generated in step 2.
dbl –o MyProgram.dbo MyProgram.dbl
6. Link in the .elb file you created in step 4 to your Synergy program and create a .dbr:
dblink –o MyProgram.dbr MyProgram.dbo gen_ouput.elb
7. Run your Synergy program:
dbr MyProgram.dbr
Note

If an assembly is loaded into gennet40 as a dependency and later at runtime has one of its types loaded before the original loading assembly, it will not be able to find the DLL outside of the GAC or the directory your program is running in.

Specifying an assembly

If assembly contains an environment variable (for example MYLOC:myassembly.dll) the generated wrapper will use that environment variable to load the assembly at runtime. Assemblies in the .NET global assembly cache (GAC) should not be specified with an environment variable. If neither an environment variable nor a physical path is specified, gennet40 searches for the assembly in the following order:

The gennet40 utility does not support search paths. If you specify an environment variable that is set to multiple directory paths, gennet40 will use only the first one.

If an assembly dependency fails to load from the GAC or the current gennet40.exe directory, gennet40 will try to load from each of the directories from which it has successfully loaded other assemblies. This list of directories is processed in order of appearance.

When running gennet40 on a DLL, the DLL filename and the assembly name must match. This restriction also applies to dependencies.

Specifying classes within an assembly (-s)

To specify a subset of the classes in an assembly, use the -s option. This option allows you to specify only the classes you want to build wrappers for, instead of creating a large number of unused classes. You do this by creating an XML file that specifies only the desired classes. Do not also specify assembly on the command line when you use the -s option; if you want to generate wrappers for all the classes in one assembly and only some of the classes in another assembly, specify both in the XML file.

Create an XML file with the following format:

<?xml version='1.0'?>
<assemblies>
   <assembly Name="D:\test\MyClassLibrary.dll">
       <class Name = "MyClassLibrary.Class2"/>
       <class Name = "MyClassLibrary.Class4"/>
   </assembly>
   <assembly Name="D:\test\YourClassLibrary.dll">
   </assembly>
</assemblies>

The resulting .dbl file will have wrappers for only Class2 and Class4 in MyClassLibrary and for all classes in YourClassLibrary.

Errors

Gennet40 may generate the following errors. In each of these cases, gennet40 will terminate with the error status and set the shell ErrorLevel to 1.

Error

Cause

Cannot find specified Assembly name

The specified assemblies cannot be opened and loaded as .NET assemblies.

Error opening output/log file

Output_file or log_file cannot be opened for output.

Restrictions and adaptations

As far as possible, the generated classes all have the same type information (methods, properties, fields, etc.) in Synergy/DE as they have in .NET, and they will use the DotNetObject methods described in Synergy .NET Assembly API to call their .NET equivalents.

Any features of .NET classes that cannot be emulated in Synergy/DE are omitted from the generated classes. Omitted features, types, and methods are reported in the log file. The following are known restrictions and adaptations:

See Synergy .NET Assembly API for more information.