Visual Basic Programming With Cobol-RPC


Introduction

Cobol-RPC works in a Visual Basic environment by providing a Visual Basic function named CallCobol that allows the Visual Basic application to execute server Cobol programs.

The CallCobol function allows the Visual Basic application to supply the name of the Cobol program to execute and the data to be passed to the Cobol program. The data passed between the Visual Basic client and the Cobol server can be a Visual Basic structure or fixed length string. The server program receives the data in the Linkage Section. Alphanumeric data is in the same format in Visual Basic and Cobol so it requires no special handling. Numeric data is in a different format, so Cobol-RPC provides routines for manipulating numeric data that make it portable also.

The rest of this section describes the details of this interface.

Components

Cobol-RPC has two components specific to the Visual Basic client. The first component is a Visual Basic code module which contains the declarations and subroutines needed to call the server and manipulate numeric data in a portable fashion. The name of this module is contained in the release notes. This module must be included in any Visual Basic projects that use Cobol-RPC. This module declares the following functions and subroutines:

Function/Subroutine Description
Call Cobol Calls a Cobol program
ShutDownRPC Terminates RPC processing
CobolToVB Converts Cobol numeric data to Visual Basic format
VBToCobol Stores Visual Basic numeric data in Cobol format

These functions are discussed in detail in the following sections.

The second component is a DLL which does the actual interfacing. The name of this DLL is contained in the release notes. This DLL is installed in the Windows directory.

The CallCobol Function

A Visual Basic program uses the CallCobol function to call Cobol programs on the server. The function looks like this:

    status = CallCobol(programname, argument, argsize)

where

status indicates the success or failure of the function call, 0 if successful, 1 if unsuccessful

programname is a literal or string variable containing the name of the Cobol program to call

argument is the structure or fixed length string to pass to the server program

argsize is the size of the data to pass to the server program

This interface allows the Visual Basic program to call any Cobol program on the server and pass it a structure or fixed length string.

When a Visual Basic program is ready to exit or quit using Cobol-RPC it should execute the ShutdownRPC subroutine as follows:

    Call ShutdownRPC

This subroutine terminates Cobol-RPC support and frees resources. Failure to make this call will not cause any problems, just delay the freeing of resources until the Cobol-RPC client DLL is unloaded.

Passing a Structure to the Server

Cobol clients can pass almost any type of data to a server program, since both programs share the same data storage techniques. Passing data between Visual Basic and Cobol requires more care. Cobol-RPC implements a simple but flexible technique for passing data between the Visual Basic client and the Cobol server.

The Visual Basic program can pass a fixed length string or user-defined structure to the server. In most cases you will want to use a structure. With a structure you can create a meaningful block of data that will also be declared in the server Cobol program's Linkage Section. The structure can contain any number of fields, but each field must be defined as a fixed length string. Cobol-RPC provides a subroutine for moving numeric values in and out of fixed length strings to allow the sharing of numeric data with the Cobol server program. Let's look at an example of how this works.

In our example a Visual Basic program needs to call two Cobol programs, one to retrieve a customer balance and one to store it. To accomplish this we need to pass a structure between the client and server that contains the customer name and balance. On the Visual Basic side we will define the structure as follows:

Type CustData
    Dim CustName As String * 30
    Dim CustBal  As String * 10
End Type

Note that both variables are declared as a fixed length string. That makes sense for CustName, but why CustBal?

Since Visual Basic and Cobol do not share a common type of numeric data, some translation will be required. In order to minimize changes in the server's legacy code, the translation is done on the client. The Visual Basic declaration of CustBal is used to reserve the appropriate amount of space for storing the numeric value. The actual contents of the field will be manipulated using two special routines, CobolToVB and VBToCobol.

The Cobol declaration of our structure completes the puzzle. Here's the Linkage Section of our two server programs.

LINKAGE SECTION.
01 CUST-DATA. 
    03 CUST-NAME        PIC X(30).
    03 CUST-BAL         PIC S9(7)V99 TRAILING SEPARATE.
PROCEDURE DIVISION USING CUST-DATA.

You can see that CUST-BAL is declared as a DISPLAY type numeric field with a trailing separate sign. With seven integer digits and two decimal digits, plus a trailing sign, it will occupy 10 bytes. That is the size we declared in the Visual Basic definition.

All numeric fields passed between Visual Basic and Cobol must be declared in this manner. If the field has a sign it must be trailing separate. The Visual Basic definition of the field must be a fixed length string with the same number of bytes as the Cobol definition.

Now let's look at how these fields are used. This is how our sample application will retrieve a customer balance.

Dim Result
Dim Balance

CustName = "Jones, Bob"
Result = CallCobol("GETBAL", CustData, LEN(CustData))
If (Result = 0) Then
    Balance =CobolToVB(CustBal, 2)
EndIf

First, CustName is loaded with the name of the customer whose balance is to be retrieved. Then the CallCobol function is used to call the server program GETBAL which retrieves the data into the CustData structure. Notice that the LEN function is used to pass the size of the CustData structure.

If the call is successful the CobolToVB function is used to translate the Cobol balance value into a Visual Basic numeric field. The CobolToVB function is described as follows:

    value = CobolToVB(field, decdigits)

where

value is the Visual Basic format numeric value of the field

field is the field in the structure where the value is stored

decdigits is the number of decimal digits in the stored value

The decdigits field is very important. Since Visual Basic doesn't know how many decimal digits are contained in the field this information is essential to apply the proper scaling to the value.

The data stored in the CustBal field is in a readable format since the Cobol data is display type with trailing sign. This means you can easily examine the contents of CustBal or any other Cobol data item with the Visual Basic debugger.

The CobolToVB function can be also be used directly in calculations. The following code could be used to calculate a new balance.

Dim NewBalance
Dim TrxAmount
NewBalance = TrxAmount + CobolToVB(CustBal, 2)

Now we want to take this NewBalance value and record it as the customer's new balance. Here's the code we would use:

Dim Result
Dim NewBalance
Dim TrxAmount

NewBalance = TrxAmount + CobolToVB(CustBal, 2)
VBToCobol(CustBal, NewBalance, 2, "y")
Result = CallCobol("SETBAL",CustData, LEN(CustData)

First NewBalance is calculated using TrxAmount and the CobolToVB function. Then the value of the CustBal field is changed to NewBalance using the VBToCobol subroutine. Then the Cobol program SETBAL is called to store the new balance.

The VBToCobol function, used to store Visual Basic numeric values in Cobol format, is described as follows:

    VBToCobol(field, value, decdigits, signed)

where

field is the field where the value is to be stored

value is the Visual Basic numeric value to be stored

decdigits is the number of decimal digits in the Cobol definition of the field

signed is "y" or "Y" if the Cobol definition of the field includes a sign

In our example the numeric value NewBalance is stored in the field CustBal. CustBal is defined in Cobol as having two decimal digits and a sign.

The example above uses two steps to update the value of CustBal. First the new value is calculated in NewBalance. Then it is stored in CustBal. This can be done in a single step.

VBToCobol(CustBal, TrxAmount + CobolToVB(CustBal, 2), 2, "y")

The VBToCobol subroutine stores the value calculated by adding TrxAmount to the numeric value returned by CobolToVB(CustBal, 2). It stores the value using 2 decimal digits and a sign. Since the current value of CustBal is retrieved before the new value is stored, the statement will execute correctly.

Passing a String to the Server

Instead of using a structure, you can pass a string to server programs. You must use a fixed length string when passing a string to ensure that the string on the client is the same size as the parameter declared in the Cobol program. In addition, a string must always be passed with the ByVal keyword. The following is an example of correctly passing a string to the server program.

On the client:

    Dim MyString * 80
    MyString = "Sample Data for Server"
    result = CallCobol("STRING", ByVal MyString, LEN(MyString)

On the server:

LINKAGE SECTION

    01 MYSTRING     PIC X(80).
    PROCEDURE DIVISION USING MYSTRING.

Home | About | Products | Contact
Distributors | Library | Register

Copyright 1996 by England Technical Services, Inc.