Accessing RM Data files from Managed Visual COBOL
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.
The WinForm will display the data being read from the RM 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. There are several ways to set environment variables before the program starts. We’re going to show how to this from within the managed code form. 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 to be invoked, in this 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 file 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 this all 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 this 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 solution.
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 Visual COBOL 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 have 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 process has become much simpler and as you can see in the completed method below is 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.
The ZIP file has all the necessary source code for you to follow along and see how to use environment variables in Visual COBOL 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...