Chapter 2: Coborbgen

This chapter describes the Coborbgen utility.

2.1 Overview

Support for CORBA within Server Express is provided by the Coborbgen utility.

The specific implementations that are currently supported are:

Iona's Object Request Broker (ORB) technology, Orbix.
Inprise's ORB technology, Visibroker for C++.

Coborbgen enables you to:

Distribute existing (legacy) COBOL applications as ORB components.
Develop and deploy, within the CORBA distributed environment, new business logic components written in COBOL.

Coborbgen:

Automatically wraps COBOL using C++ so that COBOL becomes an implementation of a C++ class.
Provides a thin COBOL wrapper. Any datatypes that are unique to COBOL, and cannot be handled by CORBA, are automatically converted as required into types that can be described using standard CORBA IDL.
Automatically generates IDL that describes the interface to the wrapped COBOL component, using the standard, language-neutral, CORBA Interface Definition Language (IDL).
IDL is used by the ORB's IDL compiler to generate stubs that connect the wrapped COBOL code to the ORB.

IDL can also be used to enable components written in other languages supported by the ORB to interface to components that have been written in COBOL.
Generates a makefile that can be used to build your executable CORBA component. This makefile:
1. Compiles your COBOL code.
2. Compiles the generated C++ wrapper code.
3. Uses the ORB's IDL compiler to generate additional C++ stubs that connect your code to the ORB.
4. Compiles the IDL generated C++ stubs.
5. Links everything into an executable CORBA component.

2.2 Prerequisites

To use Coborbgen, you must install:

A version of the C++ compiler required by the ORB you selected on your particular UNIX platform.
Version 2.3 or later of Iona's Orbix, if you want to use Orbix.
Inprise Visibroker for C++ 3.2 or later, if you want to use Visibroker:

2.3 Operation

You can use ORBs to develop and deploy distributed applications written in different languages. ORBs can interoperate across a broad range of different hardware environments.

There are currently several leading ORBs on the market that are used by many major companies. The two that MERANT supports specifically are:

Orbix, available from Iona Technologies
Visibroker for C++, available from Inprise.

ORBs support:

Multiple language bindings and full language transparency between application components.
Full multi-threading.
A range of Object Services.
A heterogeny of host platforms.

2.3.1 Creating CORBA components from COBOL

To process your COBOL:

Use the Coborbgen utility to generate the required ORB support.
When you use the coborbgen command line utility to process one or more COBOL programs, the utility generates a series of files. Those files comprise:
- IDL that describes the interface to your COBOL server.
- Additional COBOL to handle COBOL datatypes that cannot be described using standard CORBA IDL. (Remember that IDL is language neutral and needs to enable components written in other languages to interface to your COBOL server.)
- C++ to wrap your COBOL and enable the ORB to handle it as a C++ class.
- A makefile that you can use to build your client and server executables.
Run the generated makefile to create your executables.

There are specific examples provided to illustrate MERANT support for CORBA within Object COBOL:

The Grid Example. For more information, see the chapter The Grid Example.
The Order Example. For more information, see the chapter The Order Example.

Note: You should ensure that the COBOL you distribute has a well designed interface that is suitable for distribution.

Within the COBOL you distribute, all the callable entry points will be callable across the network. This includes the PROCEDURE DIVISION within all the programs you specify and also any ENTRY statements.

If, on the coborbgen command line, you use the option -client to specify COBOL code that is to act as the client side of a client/server relationship, then wrappers for the client side are also generated. In addition, the generated makefile builds an executable ORB client component and an executable ORB server component.

2.3.2 Coborbgen Syntax

The coborbgen command line is as follows:

    coborbgen filename1 [filename2 filename3 ...
filenamen] [options]

where:

filename1 [filename2 filename3 ... filenamen] are COBOL source filename(s)
every single PROCEDURE DIVISION and ENTRY statement is handled as a remotely accessible operation
you can specify:
- a single COBOL program with lots of ENTRY statements
- a whole series of programs with just a PROCEDURE DIVISION in each
- or some combination of the above
the valid values of [options] are:

	`-orbix`	Generates support for Orbix. (This is the default.)
	`-visi`	Generates support for Visibroker.
	`-cob option [-cob option ..]`	COBOL compiler options that are passed to coborbgen. Normally, you should not have to use this option. However, in some instances you may need to; for example, to specify a specific pre-processor that your COBOL code requires. Note: When using this option, take care. For example, your UNIX command line shell may strip off any quotes that you use. To prevent this happening, you could add appropriate preventive syntax by enclosing your entire `-cob` value in quotes. For example: -cob " ' currency-sign=="92" ' "
	`-make`	Directs coborbgen to generate a makefile to build executables.
	`-client c1 [c2 c3 ...]`	Passes the names of the COBOL source modules that, when compiled and linked together, form the executable client. If specified: A wrapper for a COBOL client is generated as well as a server wrapper. If the -make option is also specified, the makefile builds an executable client as well as an executable server.
	`-v`	Verbose option. Issues command line messages showing the progress of the coborbgen command. This also sets any verbose flags within the generated makefile.
	`-debug`	Directs coborbgen to insert debugging code into the generated server wrappers and to insert Animator options on the COBOL compiler's command line within the generated makefile. When run, any components built with this flag set issue a text message with details for: each call made into the legacy COBOL each return from a call to the legacy COBOL
	`-Octet`	This option specifies that COBOL DBCS types (`PIC N` and `PIC G`) are to be handled as arrays of octets. If not specified, the IDL `wstring` and `wchar` types are used (This alternative to the default is available because some products on some platforms do not handle the `wchar` and `wstring` IDL types.)

2.4 Debugging Distributed Components

In general, you can apply to CORBA the tests that you apply to your other applications. However, the distributed nature of a CORBA component means that there are extra considerations that you should take into account when testing.

2.4.1 How should I test?

It is recommended that you test your COBOL server logic on a local host before you add distribution logic to it. This testing should:

Ensure that no sequence or logic errors exist.
Check data values before and after statement execution to detect unexpected results.

When testing a distributed component, it is recommended that you follow a procedure similar to that outlined below:

Test and debug your COBOL client and server logic as standalone programs that call each other, without any distribution support in the loop.
(Even if you are writing COBOL servers for access by components written in other languages, it can still prove profitable initially to write a COBOL client test harness to check out the server logic).
Once you are happy with your client and server logic, add the Distribution support.
Test the Client Component in conjunction with the Server Component.
Finally, test your distributed Server Component in conjunction with the Client Components that will use the Server Component.

2.4.2 Testing and Debugging a Distributed Component

To test and debug a distributed component, use Animator:

Generate your application using the option -debug. Using this option ensures that the generated makefile uses the animate (-a) option when compiling the COBOL modules.
Build a client and a server for your distributed component, ready for animation.

Build a client and a server RTS to animate with. To do this, you can use the generated makefile. For example:

`make -f test.mak test-s.rts`	:	Builds an RTS for your server called `test-s.rts`
`make -f test.mak test-c.rts`	:	Builds an RTS for your client called `test-c.rts`
`make -f test.mak rts`	:	Builds an RTS for your server called `test-s.rts` and for your client called `test-c.rts`

To trigger the animator, set COBSW to +A.
Then, to animate a Client Component called test-c, use test-c.rts as follows:
```
   test-c.rts test-c
```

Introduction

The Grid Example