   =========================================================================
                              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.

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

