=========================================================================

Micro Focus
N E T E X P R E S S
=========================================================================
PROJECT VB-CALL-COBOL
=====================
DATE CREATED: June 12, 2001
=============
BUILD W/RELEASE: 3.1
================
TABLE OF CONTENTS
=================
INTRODUCTION
SOURCE FILES
REQUIREMENTS
OPERATION
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.
=========================================================================