Demonstration Application

We provide two Visual Studio projects that contain the base application files you need to complete the OpenESQL Managed Code tutorials. We also provide several tutorial-specific files. For each tutorial, you create one solution and project, add to each the files that are specific to the tutorial, and also add and reference the two projects that contain the base application. Therefore, each solution is tailored to its corresponding tutorial; however, the base application is essentially the same for each. Any nuances in tutorial-specific demonstration files are detailed in the individual tutorials.

Base Application - BookDemo

The base application, referenced in these tutorials as BookDemo, is provided in two projects - SqlLegacyBook and SqlBookWrapper. To become familiar with how this application works, study the SqlLegacyBook Project and SqlBookWrapper Project sections below. These sections provide details of the programming logic, and how the projects work together.

To look at the source code directly, go to the %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\SQL\ado.net SqlLegacyBook and SqlBookWrapper subdirectories (default locations), and open the appropriate files in any text editor.

Look at the code for SqlBookWrapper.cbl. You see that the BookDetails method returns a pointer to the book-details host variable defined in book-rec-net.cpy. This host variable definition matches the working-storage host variable defined in book-rec.cpy and included by the sqlbook.cbl program. In effect, this enables the sqlbook.cbl program to see the book-detail host variable it expects, passed in by reference. The address is sent to it by reference to allow sqlbook.cbl code to update book-details based on SQL return values. sqlbook.cbl reads the stock number from this host variable, reads a database record from SQL Server, and then puts the data into the fields of the book-details host variable, and ultimately updates the values in SqlBookWrapper.cbl.

SqlLegacyBook Project

This is the main project used to query the SQL Server database. The project contains:

sqlbook.cbl: Performs operations on a SQL Server database to set and retrieve stock information about books. See the Demonstration Solution section in each tutorial for specifics.
book-rec.cpy: This file is included by sqlbook.cbl, and contains the linkage section book-details COBOL host variable definitions. These definitions are used exclusively by the legacy code.

SqlBookWrapper Project

This is the intermediary project that maps .NET data types onto COBOL data types. The project contains:

SqlBookWrapper.cbl

This program is an intermediary COBOL class that acts as an interface between a Web form or a service and the sqlbook program. Its purpose is to enable communication between the two languages by providing a mapping between the COBOL data types found in the sqlbook program and their .NET data type equivalents used by the Web form or service. See the Demonstration Solution section in each tutorial for any additional information on the supplied SqlBookWrapper.cbl file that applies to the tutorial.

COBOL Record

SqlBookWrapper contains the .NET side of the mapping definitions by defining the BookDetails method as a property. This is a pointer to the book-details host variable defined in the copybook, exposing each host variable field as a property, and thus enabling the Web form or service code to access the values as .NET properties instead of COBOL variables.

Run Units

SQLBookWrapper uses run units, which keep methods and data isolated to prevent corruption. This is important in an environment where a Web form or a service can be accessed by more than one user at a time.

BookDetails Method

BookDetails gets a pointer to the book-details host variable:

       method-id get property BookDetails.
       procedure division returning bookDetailsAddress as pointer.
           set bookDetailsAddress to address of book-details
       end method.

CallLegacyWithRunUnit Method

CallLegacyWithRunUnit handles the rest:

       method-id CallLegacyWithRunUnit.
       local-storage section.
       01 book-status pic x(5).
       01 book-message pic x(80).
       procedure division using by value bookFunction as string.
                        
       declare myRunUnit = new RunUnit()
       declare myProgram = new type SqlLegacyBook()
       declare myPossibleException as type System.Exception = null
       try
            invoke myRunUnit::Add(myProgram)
            invoke myProgram::SqlLegacyBook(by value bookFunction, by reference self::BookDetails, by reference book-status, by reference book-message)
               
       catch e as type System.Exception
            *> To catch a specific exception, specify the exception type in the CATCH above
            set myPossibleException to e
            set book-message to e::Message
       finally
            invoke myRunUnit::StopRun(0)
       end-try
       invoke self::RaiseExceptionIfError(book-status, book-message, myPossibleException)

       end method.

Where:

procedure division using by value bookFunction as string.: Is called from a Web form or service.
declare myRunUnit() = new RunUnit(): Creates a new instance of the RunUnit class. Using the DECLARE statement here enables you to define and create an object without having to explicitly declare it in working-storage.
declare myProgram = new type SqlLegacyBook(): Defines a new instance of the SqlLegacyBook class from the sqlbook.cbl program (in the SqlLegacyBook project). The procedural code in sqlbook.cbl is compiled as a class because it is in a managed project. Its program-id becomes the class name as well as the single static method available to be called.
declare myPossibleException as type System.Exception = null: Creates a new object of type System.Exception and initializes it to null.
invoke myRunUnit::Add(myProgram): Adds myProgram to a RunUnit. This dictates that when invoked, myProgram runs within the scope of the RunUnit, ensuring isolation in a multi-user environment (such as ASP.NET or WCF).
invoke myProgram::SqlLegacyBook(by value bookFunction, by value self::BookDetails, by reference book-status, by reference book-message): Invokes the SqlLegacyBook program (sqlbook.cbl in the SqlLegacyBook project) using the myProgram object, which is an intance of the SqlLegacyBook class. It passes the book function value that identifies the operation to perform on the database. The BookDetails property for the SqlBookWrapper.SqlBook object is provided as an address by reference, and both the book-status and book-message properties are set by reference.

book-rec-dotnet.cpy

The book-rec-dotnet.cpy file defines the working-storage book-details host variable. It provides COBOL host variable definitions with a PROPERTY clause that exposes them to .NET code as System.String properties. SqlBookWrapper.cbl includes the copybook using a COPY REPLACING statement:

working-storage section.
        copy "book-rec-dotnet.cpy" replacing == (prefix) == by == book ==.
    ...

The contents of book-rec-dotnet.cpy are:

    01 (prefix)-details.
        03 (prefix)-text-details.
            05 (prefix)-title  pic x(50) property as "Title".
        ...
        03 (prefix)-stockno pic x(4) property as "StockNumber".

Note: The solutions created for these tutorials are also provided in completed form with the Visual COBOL Samples Browser. To review the completed solutions:

Start the Visual COBOL Samples Browser. If you need instructions, see To start the Samples Browser.
From the drop-down menu at the top of the Visual COBOL Samples Browser, select Show managed only.
In the left pane, click SQL.
In the right pane, select the appropriate OESQL sample.