With LegStar, developers would follow these three steps to Service-enable a COBOL program:

In this use case, initial COBOL code fragments describe the legacy program input and output structures.

The LegStar COBOL Structures to XML Schema Translator takes a COBOL fragment as input and creates an XML Schema with COBOL annotations. This generated XML Schema is known as a Mapping XML Schema since the COBOL annotations form the meta-data that maps each COBOL data item to an XML element type.

Some COBOL programs accept several input structures and several output structures, each described by a different code fragment. This step can therefore be repeated as necessary for each COBOL code fragment involved.

The generated XML Schema can be customized, and further annotated, by developers using standard XML Schema editors. In particular, developers can specify custom processing to deal with complex decisions related with COBOL REDEFINES for instance.

The LegStar COBOL Transformers Generator takes a Mapping XML Schema as input and produces a set of Java Classes. These generated classes are all that is needed for the runtime to perform Java, XML or JSON to mainframe data marshaling/unmarshaling.

The meta data that binds java fields to COBOL data items is stored as java annotations in a set of JAXB classes.

At runtime, mainframe data described by the initial COBOL fragment is typically encoded in a mainframe character set (EBCDIC) and contain compressed numerics and other mainframe specific formatted data. Conversion is totally bi-directional and completely independent of the origin or destination of the host data.

The LegStar Mainframe Service Generator, maps a mainframe program to a Web Service operation or Java method. The current version of LegStar supports CICS programs either Commarea or Container driven.

It is important to note that the tools behind each step are completely independent from each other. For instance, without an initial COBOL code fragment, developers could start from an XML Schema, edit the XML Schema to add COBOL binding annotations and then continue the remaining steps. This is not an uncommon use case, where the mainframe program is actually new and the starting point is an XML schema (An approach sometimes referred to as Contract-first).

For each of these steps, LegStar provides both Ant scripts and Eclipse plug-ins. Moving forward, the Eclipse plugins are the recommended tool as the parameter set needed by generators keeps increasing.

From a runtime perspective, this is how a request/reply message exchange would flow in an IBM CICS environment:

Starting from a Web Service client, SOAP requests are first processed by a standard Web Service stack. The LegStar-generated endpoint uses the JAX-WS standard API to communicate with the SOAP stack.

The XML payload extracted from SOAP requests is handed over by JAX-WS to the standard JAXB binding framework, which uses the LegStar-generated JAXB classes to parse the XML and produce a value object. The adapter endpoint implementation uses the LegStar COBOL Binding Runtime to transform java value objects to a mainframe payload. This transformation includes Unicode to EBCDIC conversions, numeric conversions, REDEFINES decision-making, etc…

Once data is in mainframe format, the endpoint uses a transport independent layer called LegStar Mainframe Adapter Runtime to invoke a remote program.

The LegStar Messaging Protocol used by the Mainframe Adapter Runtime is binary and implements a request/reply exchange pattern. It is designed to reduce the payload size and supports multiple input/output named structures such as CICS containers. Alternatively, the adapter runtime can use transport specific messaging protocols such as IBM CICS MQ Bridge.

The actual transport is selected at runtime from a configuration file. The following options are available:

When needed, LegStar provides z/OS modules, written in C/370 for CICS, to handle messaging on the Mainframe side (Not needed with CICS Websphere MQ Bridge). The CICS footprint of this architecture is minimal since all SOAP/XML processing occur off-host.

Any of the available transports can be used in a direct or pooled fashion. Pooling of connections, offered by LegStar Connection Pooling Engine, allows efficient connection reuse and enhances performances.

On the way back, mainframe data is converted to XML and then wrapped in a SOAP reply.