Tutorial: Creating Windows Forms in COBOL

Overview

This tutorial shows how to create a Windows form and how to make this interact with an existing COBOL program. The form is generated in managed COBOL. The form calls an intermediary program to map .NET data types onto COBOL data types. The intermediary program then calls the existing COBOL program to perform the business logic.

The solution has three programs:

Windows form. The Microsoft form designer enables you to create a Windows form in any .NET language, such as C# and COBOL. This tutorial shows how to generate these forms in .NET COBOL.
Existing COBOL program, the Book program. This program simulates a pre-existing COBOL program, which contains the business logic and which remains unchanged. This program is supplied and this tutorial adds it to the solution so that it is recompiled as managed code and exposed as a class that can be called by .NET managed code without needing any changes to the source.
Intermediary COBOL class, the BookWrapper program. This program acts as an interface between the client form and the pre-existing COBOL program. This intermediary class interfaces with the .NET client form using objects, and it interfaces with the existing COBOL using the standard COBOL PIC X data types. This intermediary class is supplied and this tutorial adds it to the solution.

Start Painting the Form

In this section, you create a Windows form and then you paint the form. You can also examine the code generated.

Create a managed Windows Forms project and choose or specify:
- COBOL Managed Projects and Windows Forms Application
- WinFormBook as the project name
- Tutorials as the project location
- WinBook as the solution name and check Create a directory for the solution
Paint four labels, three text boxes and one button on the form.

Edit the properties of the controls, being careful to not double-click any of the controls. Double-clicking creates an event for the control, which we don't want to do till the next step. Edit the properties to the following values:

Control	Name Property	Text Property
Label	label1	Stock Number
TextBox	textBoxStockNo (the case is significant)	(blank)
Label	label2	Title
TextBox	textBoxTitle (the case is significant)	(blank)
Label	label3	Price
Label	label4 (the case is significant)	(blank)
TextBox	textBoxPrice (the case is significant)	(blank)
Button	button1 (the case is significant)	Read

To display the properties right-click the label and then click Properties. You can then scroll to the relevant property and edit it.

Create a click event for the Read button. Do this by double-clicking the button, which creates an event called button1_Click , and then displays the code that is generated for the form.
Notice that the code for the button1_Click method doesn't do anything yet; the procedure division is empty. You can scroll through and review the rest of the generated code.
You can build the form, by clicking Build > Build WinFormBook . You should have no errors.

For more information on the generated code, see the tutorial Tutorial: Developing .NET Managed COBOL.

Handle the Click Events

Now you need to add the code for the button click, which needs to call the legacy COBOL program and to populate the form with the information returned.

In code view, find the button1_Click method. Update the code so that it reads as follows:

       method-id.  "button1_Click" final private.
       local-storage section.
       01 input-string string.
       01 my-exception type "System.Exception".
       procedure division using by value sender as object e as type "System.EventArgs".
           set input-string to textBoxStockNo::"Text"
           try
               set my-book to type "BookWrapper.Book"::"Read"(input-string)
               invoke self::"PopulateForm"(my-book)
           catch my-exception
               invoke self::"DisplayException"(my-exception)
           end-try
       end method "button1_Click".

Notice the red squigglies underlining some words. These indicate a syntax error from automatic parsing happening in the background. Hover over an underlined word and read the popup that gives information on the error. Notice that the status bar tells you the number of background parsing errors.

Hover over the words error-message and display the popup, which says that it cannot find the PopulateForm method. Add the following methods to your code, after the button1_Click method and before the end object statement.

       method-id.  "PopulateForm" final private.
       procedure division using my-book as type "BookWrapper.Book".
           if my-book <> null
               set textBoxStockNo::"Text"      to my-book::"StockNumber"
               set textBoxTitle::"Text"        to my-book::"Title"
               set textBoxPrice::"Text"        to type "System.Convert"::"ToString"(my-book::"RetailPrice")
           else
               set textBoxStockNo::"Text"      to "****"
               set textBoxTitle::"Text"        to "*************************************"
               set textBoxPrice::"Text"        to "****"
           end-if
       end method "PopulateForm".

       method-id. "DisplayException" private.
       procedure division using by value ex as type "System.Exception".
           set label4::"Text" to ex::"Message"
           set my-book to null
           invoke self::"PopulateForm"(my-book)
       end method "DisplayException".

The remaining errors are all associated with my-book. We will clear when we have added the legacy code.

Add the Legacy Code and the Wrapper Code

You now need to add the existing COBOL code that contains the business logic, so that the form can use it. This code is supplied in a LegacyBook project containing book.cbl.

In addition, you need some wrapper code to convert the data from .NET types to COBOL types. The Windows form uses .NET data types; these are System.String objects in our case. The book program uses COBOL types such as PIC X and PIC 99V99. The supplied program BookWrapper.cbl does this conversion, and you need to add this to the solution.

The supplied files are in the Examples subfolder, with all the Visual Studio and .NET examples, and in the Visual Studio Integration\Forms subfolder of your installation directory, which by default is %ProgramFiles(x86)%\Micro Focus\Studio Enterprise Edition x.x.

To add book.cbl and BookWrapper.cbl:

Copy the supplied LegacyBook and BookWrapper folders from the Forms folder into your tutorials directory.
Add the BookWrapper project to the solution, as follows:
1. Right-click the solution in the Solution Explorer.
2. Click Add > Existing project.
3. Browse to the BookWrapper folder, which is in the tutorials folder.
4. Select the project file BookWrapper.cblproj and click Open.
Now add the LegacyBook project in the same way.
Add a reference to the BookWrapper project in the WinFormBook project. To do this:
1. Right-click the WinFormBook project in the Solution Explorer.
2. Click Add Reference.
3. Go to the Projects tab.
4. Select BookWrapper and click OK.
Confirm that when the two supplied projects are built, their built .dll files are stored in the bin directory for the project WinFormBook. For the BookWrapper project and then the LegacyBook project:
1. In Solution Explorer, double-click the Properties folder for each project.
2. Click the COBOL tab in the properties.
3. Confirm that the Output Path is ..\bin\. You might need to adjust this relative path if your BookWrapper or LegacyBook directories are not siblings to the WinFormBook directory. Alternatively you can specify absolute paths.

Provide Access to the Legacy Code

You now need to add some code to the form to call the wrapper code and to clear the last of the red squigglies to do with my-book.

Declare the data item my-book in object working storage, as follows:
```
       01 my-book   type "BookWrapper.Book".
```
You should now have no parsing errors, now that BookWrapper is declared. If you do have errors, check the supplied demonstration in Forms\ WinBook to see where yours differs.
Set up an environment variable to point to the bookfile.* data files, which are supplied in BookData. To do this:
1. Right-click the project WinFormBook and click Add > New Item.
2. Select Application Configuration File in the templates pane.
3. Click Add.
  This adds an App.config file to the WinFormBook project.
4. In Solution Explorer, right-click App.config and choose Edit.
5. Enter the following details on the Environment tab of the Application Settings dialog:
  - Enter dd_bookfile in the Name field, which is the prefix dd_ followed by the name of the data file as declared in the program book.cbl.
  - In the Value field, enter the path and filename for bookfile.dat. For example, enter:
    - A hardcoded path such as %ProgramFiles(x86)%\Micro Focus\Studio Enterprise Edition x.x\Examples\Visual Studio Integration\BookData\bookfile.dat.
    - A path using an environment variable such as %ProgramFiles(x86)%\Micro Focus\Studio Enterprise Edition x.x\Examples\Visual Studio Integration\Forms\BookData\bookfile.dat.
6. Click Set.
7. Click OK.

Run the Application

You can now run the application.

Build the project. Set the form project as the starting project.
To do this right-click the WinFormBook project in the Solution Explorer and click Set as StartUp Project.
Click Debug > Start without Debugging.
Experiment entering information and using the Read button.
You can read data for stock numbers 1111 and 2222.

Examine the Sample Code

The sample code is available in the Examples\Visual Studio Integration folder, with all the Visual Studio and .NET examples, and in the Forms subfolder.

Client Windows Form

The client Windows form Form1.cbl is generated as COBOL. The user enters data into the form and receives the return data there. The client form does the following:

Extracts the input data from text boxes on the form as System.Strings.
Calls BookWrapper passing it the string objects.
Populates the text boxes on the form with the System.Strings.

Book Wrapper Program

The BookWrapper.cbl program acts as an intermediary between the pre-existing COBOL program book.cbl and the Windows form. This enables you to leave the pre-existing COBOL unchanged.

The important point here is that you need to use compatible types when mixing languages. The Windows form stores the data as .NET types and yet the Book program expects data as COBOL types.

The purpose of the BookWrapper program is to map your COBOL PICTUREs to .NET System.Strings. The program receives data from the Windows form as System.Strings, and maps them onto standard COBOL data types before passing them to the pre-existing book program.

The object working storage declares the data items in a book record by using a copybook, as follows:

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

The copybook book-rec-dotnet.cpy declares the book-details record. It declares book-title and book-stockno as COBOL pictures and also as properties so that Getter/Setter methods can be used to access them. The copybook contains:

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

The following get property method gets a pointer to the book-details record:

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

The Read method is implemented in the static section as follows:

       method-id. "Read". 
       local-storage section.
       01 file-status pic xx.
       procedure division using by value stockno-in as string
                          returning      myBook     as Book. 

           set myBook to new  Book()
           set myBook::"StockNumber" to stockno-in

           call "BookLegacy" using by value readRecord
                                   by value myBook::"BookDetails"
                                   by reference file-status       
            
           invoke "RaiseExceptionIfError" using file-status
           goback.
       end method "Read".

Where:

procedure division using ...
shows a .NET System.String, stockno-in, being passed in from client form. It also shows an instance of the Book class being returned. BookWrapper.cbl defines a new .NET type, Book, which can be used by programs written in any .NET language.
```
set myBook to new Book() 
```
creates a new instance of the BookWrapper class.
```
set mybook::"StockNumber"
```
takes the data from the .NET System.String (stockno-in) and stores it as the StockNumber property of myBook. This property is declared in the copybook as a picture string, and so the data is stored as a standard COBOL data type in book-stockno. The COBOL Compiler implicitly converts the data from the .NET string into a COBOL usage display item (pic x).
```
call "BookLegacy" using ... 
```
calls the legacy program, book.cbl. It passes it the “BookDetails” property of myBook. If you look at the code in BookWrapper.cbl, you can see that what BookDetails does is pass a pointer to the BookRecord structure defined in book-rec-net.cpy. This structure matches the structure in the old book-rec.cpy, so what the legacy Book program sees is a book record being passed in by reference – which is what it expects. Book reads the stock number from this record, reads a record from the indexed file, and then puts the data in the other fields of the record.
```
invoke "RaiseExceptionIfError" using file-status
```
checks the file status returned from reading the file, and raises a .NET exception if there was an error. Exceptions are the standard .NET mechanism for signaling error conditions.

Legacy Book Program

The book.cbl program is a long-standing demonstration program that has been shipped with Micro Focus products for several years. It is written in procedural COBOL. The program reads and writes to an indexed file containing book records.

In this solution, the Book program is recompiled to managed code without any changes. Recompiling the program exposes it as a class and exposes its main entry point as a static method.

The program's Linkage section defines data as standard COBOL types, such as PIC X, which non-COBOL client programs will not understand. These types need to be mapped to .NET compatible types before communication with the client program. This mapping is done by the intermediary program BookWrapper.cbl.