=========================================================================
                 G C O S 8  M A I N F R A M E  E X P R E S S

                                v2.5.04

                     G C O S 8  N E T  E X P R E S S

                                v4.0.04

                        Windows NT/2000/XP RELEASE
   =========================================================================

                           VIRTUAL-C Support
                           =================

   TABLE OF CONTENTS
   =================

       Introduction
       COBOL to Virtual-C interface
       Compiling Virtual-C subroutines
       Run-time configuration
       Test
       Virtual-C TPRs
       Limitations
       DISCLAIMER

   Introduction
   ============

   MFE8/NE8 provides support of Virtual-C subroutines, however a number
   of limitations apply, and special interfacing is also required.

   A C or C++ compiler (32-bit) is required. Visual C++ 6.0 has been
   used for the examples provided, however, any other compiler which
   has the ability to create a 32-bit DLL, can be used.

   Since MFE8 is using dynamic linking, virtual-C subroutines cannot be
   linked with the COBOL application. By placing the subroutines into
   a Dynamic-Link-Library (DLL), these may be linked dynamically.

   A special interface is required, because the calling mechanism for
   COBOL and C is different, so to avoid changing the original COBOL
   source, a small interface module is used to 1) load the DLL and 2)
   adapt the call for interfacing with C.


        COBOL-85               Interface                 DLL
      *------------*         *------------*         *-----------*
      * CALL using * <-----> * CALL using * <-----> * subroutine*
      *------------*         *------------*         *-----------*


   COBOL to Virtual-C interface
   ============================

   W8CHELLO.CBL provides an example of a COBOL to C interface, and
   it may be used as a template. You may build multiple interface
   modules or include all virtual-C interfaces in one module.

   Each virtual-C subroutines must be defined as an entry-point in the
   interface, however the subroutine name must be prefixed so it does
   not conflict with the original subroutine name, ex.

       entry "W8Chello_Chello" using lk-arg1
                                     lk-arg2.
       Chello section.
       section-entry.

           move "Chello" to w8-called-name
           perform check-dll-load
           call WINAPI "CHello" using
                                by content lk-arg1
                                by reference lk-arg2
           .

       section-exit.
               exit program.

   If arguments are passed by reference (default), then a dummy argument
   description can be used, ex.

       01  lk-arg2  pic x(01).

   for by content, you need to described the argument equivalent to
   the caller, ex.

       01  lk-arg1  pic s9(9) comp-5.

       Note: COMP-6 becomes s9(9) comp-5.

   The interface module must be compiled as MF-Cobol, see COMP.BAT.

   Compiling Virtual-C subroutines
   ===============================

   CHello.CPP provides an example of a virtual-C subroutine, which
   has been included in the IntCHello workspace (for Visual C++).
   The virtual-C source is unchanged and you should normally not
   experience any compatibility error.

   IntCHello.CPP provides an example of a simple C stub, which is used
   to load the DLL from the Cobol to C interface module (W8CHello),
   and it may be used as a template. You may build multiple DLLs or
   all virtual-C subroutines in one DLL.

       extern void IntCHello(void);
       void IntCHello ( )
       {
       return;
       }

   IntChello.DEF provides an example of a DLL definition file, which
   is used to name the entry-points within the DLL, and it may be used
   as a template.

       LIBRARY   IntCHello
       DESCRIPTION "MFE8 Library of C routines"
       EXPORTS
          IntCHello  @1
          CHello     @2

   Note: The C stub must first ordinal entry in the DLL.

   When building the workspace IntCHello, a DLL file is generated in
   either 'Release" or 'Debug' directory.

   Run-time configuration
   ======================

   The use of a COBOL to C interface module, introduces a conflict
   since the original calling COBOL source use the name of the
   virtual-C subroutines, ex. CHello, whereas, MFE8 requires the CALL
   to be redirected to a prefix entry-point, ex. W8Chello_CHello.
   You need to use EQUATE mapping to acomplish this redirection, ex.

   [common]
   "Chello"     : "W8CHello_CHello"

   By including above entry in $G8WBGDIR\EQUATE.CFG, any call to
   "CHello" will be changed to "W8CHello_CHello". Remapping can be
   applied to any program via [COMMON] or to a specific program
   via [TCHELLO] tag.

   Equate mapping is NOT enabled by default, so you need either to
   enable this via $G8WBGDIR\PREP.CFG, ex.

   [DEFAULT-SECTION]
   EQUATE-MAPPING : ON

   or

   via a source directive, ex.

       *set>g8wb equate-mapping:ON
        IDENTIFICATION DIVISION.

   Note: Information message(s) document the equate actions taken
   during checking.

   Since the COBOL to C interface module utilize entry-points for
   each C subroutine interface, these cannot be found unless the
   interface module is loaded. You can pre-load the interface module
   through environment configuration in $G8WBGDIR\ENV.CFG, ex.

   [BATCH-SECTION]
   W8Chello

   [TP-SECTION]
   $somewhere\W8Chello

   The interface program is found through $COBDIR, or through a
   complete path if specified.

   The application DLL is found through $PATH, or through a complete
   path if specified in the interface program, ex.

        set ws-dll-ptr to entry "IntCHello.dll"

        or

        set ws-dll-ptr to entry "$somewhere\IntCHello.dll"

   Test
   ====

   TCHello.CBL provides an example of a COBOL-85 program calling
   the simple virtual-C subroutine CHello.

   Virtual-C TPRs
   ==============

   G8WB does NOT support virtual-C TPRs, however it may be possible,
   depending on the complexity of such TPR, to implement a TPR shell
   in COBOL-85 and call the virtual-C logic as a subroutine.

   Note: VMPS and others GCOS8/TP8 service calls are NOT supported
   from virtual-C.

   Limitations
   ===========

   Besides the limitations described above, you may experience
   compatibility problem between GCOS8 virtual-C and the PC
   compiler selected. Should this occur, you are adviced to change
   you logic to make it compatible in both environments (ANSI).

   Naming: You cannot use the same name for COBOL to C interface
   module and application DLL.

   DISCLAIMER
   ==========

   THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. B & C
   SOLUTION DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE
   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN
   NO EVENT SHALL B & C SOLUTION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES
   WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS
   OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF B & C SOLUTION OR ITS
   SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME
   STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR
   CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT
   APPLY. 

   =========================================================================
   GCOS8 Mainframe Express and GCOS Net Express are a trademarks of B & C
   Solution. All other trademarks and trade names are the property of their
   respective owners.
   =========================================================================
   Copyright (C) 1998-2003 B & C Solution. All Rights Reserved.