Tutorials: OpenESQL .NET Code

Includes tutorials that take you through the creation of Visual Studio projects with OpenESQL .NET code applications using run units as the isolation level for multi-user environments, including WCF, WPF, ASP.NET, and OO.

Assumptions

These tutorials are written from the perspective that all of the following is true. Specific instructions for setting up your environment to adhere to these assumptions is found in the Before you begin a tutorial section that follows:

  • Windows File Explorer is set to show file names and extensions.
  • You are running the latest version of Visual COBOL, which has been installed on your local machine using default installation settings.
  • You have installed and can access a supported version of Microsoft SQL Server.
  • Visual COBOL is started on your local machine.
  • Your parent project directory is c:\tutorials\SQL. If you choose to use an alternative parent project directory, adjust the instructions accordingly.
  • You have addressed all of the items in the Before you begin a tutorial section below.

Before you begin a tutorial

Install Microsoft SQL Server
To complete any of the OpenESQL .NET tutorials, you must have Microsoft SQL Server, including the SQL Server Management Studio, installed and configured on your machine. For information on current supported versions, see the Database Access - OpenESQL section of the Additional Software Requirements on Windows topic.
Set Windows File Explorer options
These tutorials assume that your Windows File Explorer options are set to use the Details layout, and to show file name extensions. See your Windows documentation for more information.
Create a parent project directory
Create a directory in which to store the project files imported or created while completing this tutorial, which cites a parent project directory of c:\tutorials\SQL.
Start Visual Studio
If you need instructions to get Visual Studio started on your local machine, see To start Visual Studio.
Note: If Visual Studio prompts you on startup to select an initial action, click Continue without code.

Demonstration Application - BookDemo

Your Visual COBOL installation provides two Visual Studio projects that contain the base application files you need to complete the OpenESQL .NET 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.

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-dotnet.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 reference 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 instance 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".

Sequence

You must work through Tutorial: Prepare the SQL Server Environment before proceeding to another OpenESQL .NET Code tutorial. However, the four OpenESQL .NET Code tutorials are not interdependent and may be done in any order:

Parent topic: .NET COBOL Tutorials
Related concepts
Additional Software Requirements
Related tasks
To start Visual Studio