Problem:
This example demonstrates how to create Windows 32-bit .DLLs from a COBOL program which can be called by a Microsoft Visual Basic program. It also demonstrates how and when to use static and dynamic call-conventions and how to link .DLLs to the Net Express file handler MFFH.OBJ.
Resolution:
BUILD W/RELEASE: 3.1
INTRODUCTION
==========
This example demonstrates how to create Windows 32-bit .DLLs from a COBOL program which can be called by a Microsoft Visual Basic program. It also demonstrates how and when to use static and dynamic call-conventions and how to link .DLLs to the Net Express file handler MFFH.OBJ.
The project actually consists of a Visual Basic main program called DEMO1.EXE and a number of Net Express generated .DLLs. DEMO1.EXE displays a single form which interacts with the user. The form contains a number of buttons each of which when pressed will load a COBOL.DLL and call an entry point within it. Some of these entry points are called as functions and some are called as subprograms. Parameter passing between VB and Net Express is also demonstrated for the various types of VB data types such as integer, long, variable length string, currency etc.
Some of these .DLLs demonstrate how a VB program can call a COBOL .DLL which then accesses an ISAM file.
Some of the .DLLs call other .DLLs to demonstrate how these calls can be nested. All of them display some sort of progress by calling the COBOLDL2.DLL program which outputs a passed text string within a Windows message box.
This new revision of the VB-CALL-COBOL (formerly VB6D1NX3)was tested using the Microsoft Visual Basic 6.0 product provided with Visual Studio 6.0 and Net Express 3.1 with all fixpacks as of April 2001.
SOURCE FILES:
==========
Program Files
Description
--------------------- ---------------------------------------------------------
DEMO1.EXE Main program built by Visual Basic which presents the user interface.
DEMO1.MAK Visual Basic project file for creating DEMO1.EXE.
VBCOBOL.BAS Contains the Visual Basic data and function definitions for the DEMO1 program.
INITIALF.FRM Visual Basic definition for the user interface form. INITIALF.FRX
OLEAUT32.DLL Visual Basic run-time file for OLE automation. (Your OS may already have a
version of this.)
MSVBVM60.DLL Visual Basic run-time file. Required to run DEMO1.EXE outside of the
Visual Basic IDE.
COBOLDLL.CBL Source program for .DLL which contains multiple entry points. These entry
points are called to demonstrate calling functions and subprograms, parameter
passing and passing return values back to VB. Makes calls
to COBOLDL2.DLL, COBOLDL3.DLL and COBOLDL7.DLL.
COBOLDL2.CBL Source program for .DLL which is called by the other .DLLS in order to
display a passed text string using the Windows API call MessageBox.
COBOLDL3.CBL Source program for .DLL which is called from the CBLDLLPT entry point within
the program COBOLDLL.DLL. This program does the same processing as the
entry point CBLDLLEP within COBOLDLL.DLL but it shows how to perform file
handling operations within a called .DLL. It also calls the COBOLDL7.DLL
program to format a filename using the passed parameters and will check for
the existence of the file.
COBOLDL4.CBL Source program for .DLL which is intended to represent a typical monolithic
COBOL program. It has only one entry point at the beginning of the Procedure
Division. This program is called directly from DEMO1.EXE and does the same
file processing as the entry point within COBOLDL3.DLL. It also calls the
COBOLDL7.DLL program to format a filename using passed parameters and
will check for the existence of the file.
COBOLDL5.CBL Source program for .DLL which is called directly from DEMO1.EXE. It simply
loads the program COBOLDL6.DLL and calls the entry point CBLDL6EP within
it while passing mb-text as a parameter. CBLDL6EP will modify mb-text and
return control to COBOLDL5.DLL. It will then load COBOLDL2.DLL to display
the modified message.
COBOLDL6.CBL Source program for .DLL which is called from within the entry point CBLDL5EP
in the program COBOLDL5.DLL. When loaded it simply modifies the contents
of the passed parameter mb-text and returns to the calling program. When
the entry point CBLDL6EP is called it will also make a call to the file handling
example COBOLDL3.DLL.
COBOLDL7.CBL Source program for .DLL which is called from programs COBOLDLL.DLL,
COBOLDL3.DLL and COBOLDL4.DLL prior to the execution of the indexed
file I-O routine.
This program will format a filename using the passed parameters and will
check for the existence of the file. If the file does exist it will pass back 0 in
the status-code field. The Net Express "PC_" and "CBL_" library routines
are used to check the validity of the filename.
If the passed parameter switch debug-on is set to true (-1) then the status of
this program will be displayed by calling COBOLDL2.DLL which handles the
GUI display of a message box.
IDXFILE.DAT/IDX Indexed file which is referenced in this demo.
DOIT.BAT Batch file containing commands to create the COBOL .DLLs directly from a
Net Express command prompt. This was kept from the old example VB6D1NX3.
It is no longer needed as you can simply create the files by rebuilding
the project.
DEMO1.DOC Microsoft Word document kept from the old example VB6D1INX3 for historical
purposes. Contains some more detailed information pertaining to the original
creation of this demo.
REQUIREMENTS:
==========
This sample will run without Visual Basic 6.0 installed as the program DEMO1.EXE has already been compiled and linked and the necessary VB run-time files have been provided. If you wish to view, debug or modify the Visual Basic program then Visual Basic 6.0 or Visual Studio 6.0 must be installed on your system.
OPERATION:
========
There are several ways in which this example program can be run. You can run it standalone, without any debugging, you can run the Visual Basic program standalone while debugging the COBOL .DLLs or you can debug both the Visual Basic program and the COBOL programs simultaneously.
I. For all methods do the following:
1. Open the project file VB-CALL-COBOL.APP using Net Express.
2. From the Net Express menu select Options and then Animate. Under General make sure that the option "Show start animator prompt" has a check next to it. Press OK.
3. From the Project menu select Rebuild All. This will create the subdirectory DEBUG and create all the COBOL .DLL files in it. Since DEMO1.EXE, OLEAUT32.DLL and MSVBVM60.DLL are specified in the project they will also be copied to the DEBUG directory.
4. Additionally you need to copy the following files from the project directory to the DEBUG subdirectory:
DEMO1.MAK
DEMO1.VBW
VBCOBOL.BAS
INITIALF.FRM
INITIALF.FRX
IDXFILE.DAT
IDXFILE.IDX
II. To run standalone.
1. From the Start Menu/Programs/Merant/Net Express group open a Net Express Command Prompt.
2. Using the DOS CD command make the DEBUG directory your current directory. (i.e. cd \\vb-call-cobol\\debug)
3. Run DEMO1.EXE. The VB form will be displayed allowing you to select various options.
4. Press the Quit button to return to the command prompt.
III. To run VB standalone while animating the COBOL .DLLs.
1. Open the project file VB-CALL-COBOL.APP using Net Express.
2. From the Animate menu select Start Animating.
3. The Dialog box should contain DEBUG\\DEMO1.EXE. If it does not then press the Browse button and select this file.
4. Press OK and the VB form will be displayed allowing you to select various options.
5. Now when a COBOL .DLL is called its source code will be displayed in the Animator. You can step through the code to see how the .DLLs and entry points are called and you can also monitor the parameters being passed back and forth between VB and COBOL.
6. Press the Quit button on the form or select Stop Animating from the Net Express Animate menu.
IV. To debug the Visual Basic program while also animating the .DLLs.
1. The command to start Visual Basic 6.0 is VB6.EXE. If you do not know the drive and directory where this file resides then you must find it using the Find Files or Search command from your systems Start Menu. Make a note of the location of this file.
2. Open the project file VB-CALL-COBOL.APP using Net Express.
3. From the Animate menu select Start Animating.
4. In the Start Animating dialog box enter the full path name including drive, directory and command name of the VB6.EXE file on your system. (i.e. C:\\progra~1\\micros~1\\vb98\\vb6.exe. Press Ok and the Visual Basic IDE will start.
5. Select the Existing tab from the New Project window or select Open Project from the File menu and open up the file DEMO1.MAK in this demos project\\DEBUG directory. This will load the DEMO1 project into Visual Basic.
6. Select the Step Into option from the VB Debug menu or press the F8 key. This will start the DEMO1 program and display the Visual Basic source.
7. Continue to step through the source by pressing the F8 key for each line to execute.
8. When the form is displayed, press a button and the Visual Basic debugger will continue.
9. When you execute a statement which calls a COBOL .DLL entry point, the Net Express Animator will take over and allow you to step through the COBOL source code. When you reach an exit program statement within a .DLL that was called directly by DEMO1, control will return to the Visual Basic IDE. You may have to click on its icon on the Windows task bar to make it active as it may not come to the foreground automatically. This is also true for the Form itself. When it is called it may not display automatically so you will have to make it active by selecting it on the Windows task bar.
10. Continue to step through the source by pressing the F8 key for each line to execute.
11. To Quit select End from the Visual Basic Run menu and then close Visual Basic.
NOTE:
====
When .DLL programs make use of COBOL file I-O then the Net Express file handler module MFFH.OBJ must be linked to the .DLL. This is done automatically when the compiler directive CALLFH"MFFH" is used and the "Include system programs" option is checked under Project/Build Settings/Link/Advanced for the .DLL.
A problem arises when a .DLL using file I-O calls another .DLL which also uses file I-O. Only one copy of the MFFH.OBJ must be present within the run-unit. The first .DLL called must have MFFH.OBJ linked to it as described in the previous paragraph. The other .DLLs which are called from this one must NOT have MFFH.OBJ linked directly to them but instead they should link to the entry point MFFH within the first .DLL. In this example, the program COBOLDLL.DLL uses file I-O and then can call COBOLDL3.DLL or COBOLDL4.DLL which also use file I-O.
The following steps should be followed: (this is already done in this project, this is documented for reference purposes only!)
1. Use the compiler directive CALLFH"MFFH" for all .DLLs using file I-O.
2. Select Project/Build Settings from the main menu.
3. Select the Link tab and select Advanced in the category drop down.
4. Highlight the file COBOLDLL.DLL in the project tree.
5. Place a check next to the "Include system programs" option. This causes the file handler module MFFH.OBJ to be linked in.
6. Place a check next to the "Keep temporary Linker files" option. This causes the import library COBOLDLL.LIB to be saved in the project's DEBUG directory.
7. Highlight the file COBOLDL3.DLL in the project tree.
8. Uncheck the "Include system programs" option. This keeps the MFFH.OBJ from automatically being linked in.
9. Uncheck the "Keep temporary Linker files" option.
10. Add %TARGETDIR\\coboldll.lib to the "Link with these LIBs" field. This resolves the link to MFFH and points to the one in COBOLDLL.DLL.
11. Repeat steps 7 thru 10 for file COBOLDL4.DLL.
COBOLDL6.DLL calls COBOLDL3.DLL which uses file I-O but it does not have to be linked differently because it does not use file I-O itself.
RULES:
======
Here are some rules to live by when calling Net Express .DLLs:
Dynamic Calls:
1. A COBOL .DLL can be called dynamically.
2. A COBOL .DLL called dynamically must be canceled by the calling program.
3. Entry points in dynamically called COBOL .DLLs must also be called dynamically.
4. Do not cancel entry points.
Static Calls:
1. A COBOL .DLL can be called statically. (must use its import lib)
2. Do not cancel a COBOL .DLL which is called statically.
3. Entry points in statically called .DLLs must also be called statically.
4. Do not cancel entry points.
EXTFH:
1. EXTFH, (MFFH.OBJ) if required in any part of the application, must be linked into the first COBOL .DLL which is called from Visual Basic.
2. EXTFH must be linked into every .DLL requiring its file handling support. (directly or indirectly by using an import library)
3. You cannot cancel a .DLL containing EXTFH (MFFH.OBJ).
4. You must call a .DLL containing EXTFH (MFFH.OBJ) statically. (by using an import library)
For more information on the history of this demo see the Microsoft Word document DEMO1.DOC which is included in the project directory.
==========================================================
Keywords: Example, sample, demo, demonstration, mixed language, vb-call-cobol.zip
demo.ex
demo.ne
