Accessing RM Data files from managed Visual COBOL

With the Micro Focus purchase of Liant in 2008 the Micro Focus product suite expanded to include the RM/COBOL file system. Until the recently released Visual COBOL R4 (VCr4) there was no way for the Micro Focus product suite to access the RM files. VCr4 changed that by integrating RM file access into the native compiler.

But what about access from a managed environment?

The purpose of this article is to provide the reader with an example of how to read the RM file system from a native COBOL program and have it display on a managed WinForm. We will thus cover two topics in this article, accessing RM files from native code and calling a native module from managed code. For a review of creating WinForm project please see the Micro Focus documentation. We will concentrate on calling the native module and the configuration of accessing the RM file system.

Let's begin by looking at our WinForm.

WinForm

The WinForm will display the data being read from the Vision file. The information being displayed is basic contact information from a client file and appears as follows:


We'll display the basic contact information of Account number, name and address for each record in the file. One of the key components to enabling the RM file access is defining the environment and to accomplish that we need to set a runtime environment variable.

Setting Environment Variables

In our process we need to have the environment defined and ready when the form comes up. To accomplish this we need to modify the 'NEW' method of the form. The 'NEW' method is the default method invoked when a form is first created and it's here that we need to establish the environment.

Locate the 'NEW' method in the WinForm. We are going to insert the following line of code after the 'initializeComponent' statement:


From a recent article about Environment Variables we are going to invoke the Environment Class and the static method SetEnvironmentVariable. Your completed 'NEW' method should look like the following:



The question you are more than likely asking though is "What the heck is A_CONFIG and acurmfm.cfg?

RM Environment Definition

To access the RM file system, Visual COBOL uses a file handler called ACUFH. It uses a configuration file to indicate which file system is tobe involved, in the case RMFM. The A_CONFIG is an environment variable that points to the location of the ACUFH configuration file. In our example we named that 'acurmfm.cfg'. If you'll notice there is no path information present so it is located in the same directory where the executable is, in this case where the WinForm is:

C:\vcdemo\Projects\RMFiles\WinForm01\bin\Debug on my machine.

The acurmfm.cfg file sets the default file system. The file is a text based file and opening it with Notepad shows the following:


We've set the DEFAULT_FILESYSTEM to the Ryan McFarland File Manager (RMFM).

Setting these variables and creating the configuration files in the proper location is really all there is to gaining access to the RM file system, with one exception. Accessing the RM file system is only available in the native environment.

We now have to access the file from a native module.

Native Program Configuration

A critical step in making all this work is the CALLFH compiler directive. The CALLFH compiler directive has to be set for the native program or project that will be making the calls to the RM file system. To set the compiler directive in the native project, select the project, right click and then select "Properties" (or double-click on the Properties in Solution Explorer).



The Properties page will be displayed. Click on the 'COBOL' tab on the left navigation pane. There is a textbox for 'Additional Directives'. Click in there and enter 'RM CALLFH("ACUFH")'. Setting the RM directive when you submit your RM/COBOL source programs to the COBOL system ensures that most of the programs are accepted the first time they are submitted. The additional syntax enabled by the RM directive is documented in the section Ryan McFarland COBOL V2.0 Syntax Support in your Language Reference. The CALLFH("ACUFH") directive invokes the callable file handler, enabling access to the ACUFH file handler, which is how the Visual COBOL runtime accesses the RM data files.

When you have updated the Compiler Directives textbox your screen should look similar to the following:



Click the 'Save All' button and rebuild your application.


Native Program Access

With VCr4 Micro Focus has made the interaction between managed and native modules even easier than ever. We will assume you're comfortable with creating native applications in VisualCOBOL and concentrate instead on how to create the plumbing necessary to make the interaction occur.

The first thing to know is the native application has to be compiled as dynamic link library or DLL. Make sure you have a clean compile on your module. Select the References tab in the managed code project in the Solution Explorer window, right click and select 'Add Reference'.


When the Add Reference window appears click on the Browse button at the top of the form.


The browser will start in the current directory which is the WinForm01 project directory. Browse to where your native DLL is located to access the RM data files. In our example this will be

 
C:\vcdemo\projects\RMFiles\bin\x86\debug and in this location we'll find our DLL

Select the DLL and click OK. The DLL will be added to the References for the WinForm project and expanding the Reference tab in the Solution Explorer will show


Once you've added the native DLL as a reference you need to ensure that it's copied into the output directory of the managed project. To copy the DLL to the right location, right-click on the reference you just added and select 'Properties'. Look for the "Copy Local" entry and ensure that it's set to 'True'.



Once you've added the reference to the native DLL the final task is to code the call to the native DLL from within the managed code. This proces has become much simpler as as you see in the completed method below s nothing more than a simple 'CALL' statement that you're already used to working with. The runtime environment manages the interaction between the managed and native environments for you.




That's all there is to it. You should be able to execute your managed code project, having it access a native DLL that will in turn access the RM File Manager to return data.

Wrap-Up

The ZIP file has all the necessary source code for you to follow along and see how to use environment variables in VisualCOBOL and access a native DLL from a managed WinForm. Being able to utilize your existing COBOL modules for .NET enables you to safely and without risk extend your business to new areas and will greatly expand the interoperability and life of your existing COBOL applications. While the process may seem complicated at first, spend a few minutes and analyze what we've done in this article. The steps will be basically the same for you and will greatly extend the usefulness of your existing applications to the .NET Framework. And that's what it's all about...

Happy Coding!