Accessing COBOL Properties with C#

Overview

With the .NET environment there are many ways to extend your legacy COBOL assets and make them available to other technologies and languages. In another article we discussed the use of creating a COBOL interface class to interact between your existing COBOL applications and the languages in the .NET Framework. This article will review a new  option for exposing those assets via the use of Properties. As defined by Microsoft, Properties are "A class member that is like a public field, but that includes features such as versioning, encapsulation, and the ability to execute additional logic through get and set accessor methods."

But what are properties and how do you as a COBOL programmer expose your legacy code as a property? Utilizing Properties will require a bit of additional coding to your existing applications but once completed other .NET languages such as C# will be able to directly access and consume the resources of your COBOL code. (We will utilize C# in our example today.) We will also be utilizing Object Oriented COBOL, or OOCOBOL. OOCOBOL is very similar to Procedural based COBOL with the same sections and headers, and a few new sections as well. It is a very powerful language in the .NET environment and well worth your effort to learn the intricacies of the new standard.

COBOL Property Basics

NOTE: If this is your first time dealing with GET and SET methods, or properties in general it is suggested you review the online help for properties. NetCOBOL for .NET has some excellent help facilities. One of the first links you should review is: ms-help://MS.VSCC/Fujitsu.COBOL/UserGuide/COBNUGOOUsingProperties.htm. Copy and paste this link into Visual Studio.NET Search feature to locate the document. This is specific to COBOL. You may also wish to review the Microsoft help files for Properties.

In most cases a Property will have a GET and a SET method, as defined above. The GET method is used to obtain the current value of the property and the SET method is used to establish the property at a given value. The GET and SET methods are normally defined as PUBLIC methods to enable other classes to access them and work with the properties they are assigned.

In our example these are established as

Notice the colorization of the METHOD-ID line? The Fujitsu NetCOBOL for .NET compiler recognizes the GET and SET PROPERTY identifiers as reserved words within the COBOL language. The next item on the line is the variable you would like to establish as a Property, in this case the variable Result. The 'AS' phrase instructs the compiler to publish the variable in the following manner and name. For our example we used the same context and name, Result. The IS PUBLIC phrase is used to publish this property to the outside world so it can be accessed. As we will see in a little bit, the SET method is not required for our example but we elected to create one to show how it would appear.

The Methods themselves contain a LINKAGE SECTION to pass data in from within the class and a COMPUTE statement to populate the variable. The COMPUTE statement could have been replaced with a MOVE or a SET statement, we chose to use COMPUTE.

If you will look closely at the COMPUTE statements you will see that Result is populated (or gets its value) from a variable called WS-RESULT. WS-RESULT is an INSTANCE variable that is used by all of the instantiated methods within the class. How is this possible and more importantly how is this defined? An INSTANCE method or variable is created when a class object is instantiated with the 'NEW' method from another class. Basically it's a copy of the program in memory that you can now use in your run unit. The variables are defined in the OBJECT area of an OOCOBOL class in the following manner

The OBJECT header defines where the instantiated object begins. The Data Division and WORKING-STORAGE SECTION are headers you are already familiar with. The definition of WS-RESULT is the standard way in which a COBOL programmer would define a variable. It also happens to be the definition for an INT32 in the .NET Framework. .NET utilizes strong data typing to ensure conformity across programming languages when data is being passed back and forth. For more information on COBOL and .NET data types see the previous article titled "COBOL and .NET Data Types".

ComputeResult

The GET and SET methods are both relying on WS-RESULT to have a value that can be then passed to the outside world. Where though is this variable set? The method ComputeResult is where. The method is defined as follows

The method accepts two integer values, WS-NO1 and WS-NO2 from a calling entity. It then computes the product of the two integers, placing the result into WS-RESULT. A straight forward calculation of two integers. If you'll notice the code is nothing "out of the ordinary". It is wrapped with a METHOD-ID and an END METHOD identifier, but otherwise it is standard COBOL code. You could place your existing COBOL procedural code into a method and with a few minor updates also have it accessible as a method in .NET. This is the power of NETCOBOL for .NET, with minor updates to your code you can expose it to other languages your company has chosen for user interface development. These could be VB.NET, C#, ASP.NET or any of the other 20+ languages that comprise the .NET development environment. OK, so we've created our method and class. Now the question though is "How is this method called?"

C# calling

The COBOL method was called from a C# method. The WinForm we created has three text boxes to accept input and a command button to execute a method. The screen appears as

The command button, named button1, has a 'Click' event procedure that will call the COBOL method to calculate the result. Let me show you the method first and then let's dissect it into smaller, easily understood pieces.

At first the code may look confusing, but let's take it a line a time and review what each line of code is doing. While you may not be C# programmers the language is very easy to read and understand and once understood can assist COBOL programmers in better understanding the intricacies of the .NET Framework.

I won't review the event header line in much detail other than to say it establishes the definition of the Click event for the object, namely button1. The next line is a curly bracket, '{'. All C# coding is encased in these brackets. You will see at the end of the method another curly bracket, but this time facing the opposite way, '}'.  This denotes the extent of the method. In COBOL this syntax would be roughly equivalent to a PERFORM and END-PERFORM statement. OK, let's tackle the real meat of this method now. The method can be thought of in the following manner, Instantiate, Compute and Display.

Instantiate

Remember back in the COBOL section of this article I said the COBOL method had to be instantiated? Well instantiation is a fancy word for "making a copy of". We want to make a copy of the COBOL class for our run-unit and be able to access the properties of that copy. To do that requires a call to the 'NEW' method of a class. When you create a class the method 'NEW' is automatically created for you, a freebie if you will by the nice people of the compiler. The first line of code creates our copy, or instantiates the class.

COBOLResult cobolResult = new COBOLResult();

Remember: C# is case sensitive. If you notice the same name is used for the instantiation (cobolResult) as it is for the class definition (COBOLResult). Since the two variables are specified with different cases they are separate and distinct variables.

Compute

OK, we now have a copy of the class we can use in our run-unit. We can now call our method to compute the result of the two integers. This is done with the following code.

cobolResult.ComputeResult(Convert.ToInt32(textBox1.Text),                                          
Convert.ToInt32(textBox2.Text));

Although the code may seem a bit puzzling at first, after you work with C# a while you will begin to see how things are done. Let's look at the statement in detail, starting with the portion before the first left parenthesis '(', namely cobolResult.ComputeResult. cobolResult is the instantiated class from the first line of code, Our 'copy' to work with. ComputeResult is the method we are calling (remember the COBOL code: METHOD-ID. ComputeResult AS "ComputeResult"). The portion in the parenthesis are the parameters ComputeResult requires in order to do its job, but with an additional feature. The Convert.ToInt32 syntax is calling an internal .NET conversion routine to convert what follows, in this case textBox1.Text or textBox2.Text to a 32 bit integer. Remember, text boxes used for inputting information are in text format. You have to convert the information they contain to what ever format you require. In this case we are converting them to 32 bit integers in order to perform our calculation.

Display

If you will remember from our COBOL code the method ComputeResult will place the result of the COMPUTE statement in a field called WS-RESULT. In order to see the value on the screen we have to obtain, or get that result from the class. Notice I said the class, not the method. The method doesn't return the result. It placed it in a 'global variable' that is accessible via a property we defined in the GET method. The property was called Result.

textBox3.Text = cobolResult.Result.ToString();

The above line of code calls to our instantiated class, cobolResult, accessing the property we have made public Result. The 'ToString' method converts the integer value of Result to a character or text representation so we can display it on the screen. The textBox3.Text is the portion of the statement that will display the information to the screen, namely texBox3. The important point to make sure you understand is the method ComputeResult did not expose the results of the computation. It merely assigned a value to a variable and that variable was then accessed via a property we defined to publish the value to the outside world.

Summary

Spend some time working with Properties. You will see you can expose bits and pieces of your existing COBOL code via the .NET Framework to other entities to consume. Work in small pieces to begin with though until you get the hang of the process.  Review the attached code in the zip file. For best results split your display in VS.NET and review the code side-by-side so you can see what the call in C# is doing and the COBOL code at the same time. Although a bit more coding to begin with, in the long term Properties can save your VB, C# and Web Service coders time by already having access to existing core business logic.

Happy Coding!