Problem:
Demonstrates the use of the .NET Platform Invoke functionality in order to use the COBOL CALL statement to call entry points and functions within unmanaged Windows dynamic Link Libraries created with Net Express 4.0, Microsoft Visual C/C 6.0 and also to call Windows system API functions. This program also demonstrates the use of the new .NET COBOL structured exception handling syntax to catch run-time exceptions and also shows how to create and use a user-defined exception class.
Resolution:
BUILD W/RELEASE: Net Express 4.0 with .NET add-on installed.
The 'CallUnmanagedDll.zip' file actually contains three different projects which can all be extracted into a single folder on your hard disk. You can create a folder such as 'C:\\CallUnmanagedDll' into which you can extract the entire contents of the zip file, including the subfolder structures '.\\bin\\debug' and '.obj\\debug'.
The main source program within each project contains documentation in the form
of comments within the source, which explains the use and build instructions
for that particular project.
PROJECT FILES:
=========
Program Files Description
---------------- -----------------------------------------------------------
CallUnmanagedDll.sln Visual Studio .NET 2003 Solution file.
CallUnmanagedDll.cbl COBOL source program that is compiled to managed code.
CallUnmanagedDll.cblproj Visual Studio .NET project settings.
callcobdll.app Net Express 4.0 Project file.
callcobdll.cbl COBOL source program that is compiled to unmanaged 'callcobdll.dll'.
callcdll.dsw Microsoft Visual C/C 6.0 Project workspace file.
callcdll.dsp Microsoft Visual C/C 6.0 Project file.
callcdll.cpp C source program that is compiled to unmanaged 'callcdll.dll'.
callcdll.h C header file containing call function prototypes.
callcdll.* Other files created by the Microsoft Visual C/C compiler.
Readme.txt This project documentation text file.
REQUIREMENTS:
==========
Installation of Net Express 4.0 and the add-on product, Net Express with .NET. Also requires installation of the Microsoft Visual Studio .NET 2003 product or the Microsoft Visual Studio .NET 2003 partner edition provided by Micro Focus.
OPERATION:
========
1. Extract the demonstration files.
Unzip the contents of the file 'CallUnmanagedDll.zip' into a new folder on your hard disk. The folder 'C:\\CallUnmanagedDll' is recommended. The subfolder structure of '.\\bin\\debug' and '.\\obj\\debug' should also be created.
2. View the demo's .NET Solution files.
Start the Visual Studio .NET 2003 IDE and select File>Open Solution from the IDE menu and open the file 'CallUnmanagedDll.sln'.
If the Solution Explorer window is not currently displayed then select the option View>Solution Explorer from the IDE menu.
Expand the Solution Explorer's project tree to view the contents of it's References and Source folders.
Double-click on the source file 'CallUnmanagedDll.cbl' to open it in the editor. Read through the program source code as the documentation for the program is embedded in the program as comments.
3. Add required references to the unmanaged programs that are called by the demo.
The pre-compiled and pre-linked unmanaged programs 'callcobdll.dll' and 'callcdll.dll' should already exist within the project's subfolder '.\\bin\\debug'.
You need to add references to the unmanaged Dynamic Link Libraries that the demo will be calling. By default, the only references that should appear in the References folder are 'System' and 'System.Data'. If this is the first time that you have opened the solution file for this demo and references to 'kernel32', 'callcobdll' or 'callcdll' also appear in the References folder then they must be removed and then added again. You can remove these references by right-clicking on the reference name and selecting 'Remove'.
To add the required references, right-click on the References folder and select 'Add Reference'. From the Add References window, click on the Browse button. Assuming that the demo was extracted into the folder 'C:\\CallUnmanagedDll', navigate to the folder 'C:\\CallUnmanagedDll\\bin\\debug'. Highlight the two files, 'callcobdll.dll' and 'callcdll.dll' using the mouse and the left Ctrl key and then click on the Open button. The files should appear in the Selected Components list. Click on the OK button and they will be added to the Project References folder.
You also need to add a reference to the system module 'kernel32.dll' since this module contains the function "GetComputerName" which is called by the demo. The location of this file is operating system dependent. Under Windows XP you would add a reference as described in the previous paragraph, but you would navigate to the folder 'C:\\WINNT\\SYSTEM32' and then select the file 'kernel32.dll'. This file should then also appear in the Project References folder.
4. Creating the demo program .NET assembly 'CallUnmanagedDll.exe'.
Select File>Save All from the IDE menu, to save the changes that have been made so far. Select Build>Rebuild Solution from the IDE menu. This will create the .NET assembly 'CallUnmanagedDll.exe' in the project's '.\\bin\\debug folder'.
5. Running the demo program.
This program is created as a Console based application. This means that a character-based Windows console will be created when the program is started. All program input and output via COBOL ACCEPT and DISPLAY statements will appear in the console window. The unmanaged programs 'callcobdll' and 'callcdll' also output information to this same console window. 'callcobdll' uses COBOL DISPLAY statements and 'callcdll' uses the standard C function 'fprintf' to the 'stdout' device.
You can run this program at full speed from within the Visual Studio .NET IDE by pressing the F5 key. You can also insert breakpoints at specified source lines and use F5 to run the program until it reaches the breakpoint.
To debug the demo program by stepping through each source line, press the F11 key to start the program and then press F11 again for each line of source.
If you wish to step through the unmanaged program 'callcdll.c' at the source code level, then you only need to open the project's properties and under the section Configuration>Debugging, change the option 'Enable Unmanaged Debugging' to 'True'.
6. Demonstrating the user-defined exception 'RetCodeException'.
In the paragraph, 105-call-unmanaged-c, after the call to the 'ReturnInteger' function, there is a comment telling you how to demonstrate the use of user-defined exceptions by commenting out one source line and replacing it by the following source line. You should step through the complete demo, as-is, first and then make these changes, Rebuild the Solution and then step through the program's source a second time in order to demonstrate this feature.
7. Making modifications to the demo or unmanaged .DLL programs.
If you wish to make modifications to the umanaged programs, 'callcobdll.cbl' or 'callcdll.cpp', remember to Rebuild their projects to create new .DLLs and then move them from the project\\DEBUG folder to the project\\bin\\debug folder in order to replace the current copies with the new ones.
You must then remove the current references to these files in the Project References folder and then go through the steps of adding a reference for each new .DLL. (see step 3 above).
You must then Rebuild the Solution. (see step 4 above).
==========================================================
Keywords: Example, sample, demo, demonstration, .NET, callunmanageddll.zip
demo.ex
demo.ne
