WebSphere Optimized Local Adapters

History

The WebSphere Optimized Local Adapters for WAS z/OS (WOLA or OLA for short) has its origins in a desire to provide an efficient inbound calling mechanism; that is, from outside the Java EE environment into it to exercise Java EE assets. This requirement was particularly pronounced on z/OS where traditional batch processing sought the use of a growing base of programming assets based on Java EE and EJB technology.

Other inbound solutions existed, for example:

While each had its respective strengths; each also had its particular shortcomings: overhead and latency; difficulty in construction; or deficiencies in the security or transaction propagation model.

This was the original design point for the Optimized Local Adapters. The architects of the solution extended the design to include bi-directional invocations: inbound to WAS z/OS from an external address space, and outbound from WAS to an external address space.

Technical Foundation

The architects of this solution chose to leverage an existing element of the WAS z/OS design called "local communications," a cross-memory mechanism used by WebSphere Application Server for z/OS since the V4.x days that optimized IIOP traffic between application servers on the same LPAR. OLA is essentially an externalization of that existing cross-memory mechanism so that address spaces outside WAS z/OS may connect and exchange messages across a shared memory space.

External address space programs access the OLA interface using a set of supplied APIs. Java programs running in WAS z/OS access the OLA interface through an implementation packaged as a standard JCA resource adapter.

Current Support

The currently supported external address spaces supported for WAS z/OS OLA are:

The programming languages supported in the external address spaces are:

Java is the programming language used to access WAS z/OS OLA from inside the Java EE containers of WAS z/OS.

Function Update History

IBM WebSphere Optimized Adapters function support has been updated as new versions or fixpacks are released. The function was first made available in WAS z/OS Version 7 Release 0 Fixpack 4 level (7.0.0.4).

7.0.0.4

WOLA was introduced with Fixpack 4 to the WAS z/OS Version 7 Release 0 product. Application of maintenance resulted in a new directory in the product file system that provided the WOLA modules, shared objects, JCA resource adapter and development class libraries. A shell script (olaInstall.sh) created the necessary UNIX symbolic links from the runtime environment to product install file system.

The functional supported offered in the 7.0.0.4 release was:

7.0.0.12

Fixpack 12 to WAS z/OS Version 7 Release 0 provided two updates to the WOLA support:

8.0.0.0

WebSphere Application Server for z/OS Version 8 Release 0 continued support for WebSphere Optimized Local Adapters. WOLA was shipped incorporated into the product, which meant running the olaInstall.sh was no longer required to create UNIX symbolic links to the product files. In addition the following function updates were provided:

Resource Failover and Failback

This function provides a means of detecting the loss of a data resource attached to a JCA connection factory and automatically failing over to a defined alternate JNDI. Detection of primary data resource recovery and failback is also an element of this functional design. The resource failover design is present in WebSphere Application Server Version 8 across all platforms for JDBC and JCA. WAS z/OS Version 8 provides support for WOLA resource failover as part of the general support for JCA resource failover. Invocation of the failover occurs when a configurable threshold number of getConnection() failures occur. After failover is invoked, all new getConnection() requests are routed to the alternate connection factory connection pool. Failback occurs when WAS z/OS determines the failed primary data resource has returned. New getConnection() requests are processed against the primary connection factory.

A common usage pattern for this function is outbound to CICS where the target CICS region is a routing region. This failover function provides the ability to architect multiple routing regions so that the loss of any single routing region does not affect the overall availability of CICS overall.

Several connection pool custom properties were added to support this resource failover and failback mechanism:

Note: other connection pool custom properties exist for this function. Search on string "cdat_dsfailover" in the WAS z/OS InfoCenter for a complete listing.

8.0.0.1 / 8.5.0.0

Note: WAS z/OS 8.5.0.0 provides WOLA support functionally identical to 8.0.0.1

Fixpack 1 to WebSphere Application Server for z/OS Version 8 provided the following functional updates to WOLA:

64-bit Callable Native API Modules

Prior to 8.0.0.1 the native API modules were supplied in 31-bit callable format only. These modules had the four-character prefix BBOA* associated with each module name.

With 8.0.0.1 both 31-bit and 64-bit callable API modules are provided. The 31-bit modules retain the four-character prefix BBOA* for each module name. The 64-bit modules carry the four-character prefix BBGA* for each module name.

The number of APIs remains the same as before: 13 specific APIs. Usage is the same as before.

InfoCenter Search: cdat_olaapis

SMF 120.10 for WOLA Outbound Calls

In WAS z/OS V7 the WOLA support for SMF was limited to inbound calls only. Inbound WOLA calls to target EJBs in the WAS z/OS container were identified as IIOP calls and captured by SMF as IIOP calls, indistinguishable from any other IIOP call. The normal WAS z/OS SMF 120 subtype 9 record (or 120.9 in shorthand notation) was used to capture the inbound call information.

With WAS z/OS 8.0.0.0 the SMF 120.9 record and capture function was modified to identify inbound WOLA calls separate from inbound IIOP calls.

With WAS z/OS 8.0.0.1 the SMF 120.10 record was created to capture information about outbound calls from WAS z/OS. The SMF 120.10 record has eight sections:

One record is created for each outbound request.

InfoCenter Search: rtrb_SMFsubtype10

Work Distribution

This functional update provides the ability to distribute outbound calls across multiple external address spaces registered into a given WAS z/OS server using the same registration name. A common usage pattern for this would multiple CICS regions with the same stateless target program service deployed. A new environment variable was created to indicate the type of work distribution desired. The following illustrates the usage of this function:

InfoCenter Search: cdat_olacustprop

Proxy Support: Inbound and Outbound

The cross-memory nature of WOLA communications implies the WAS z/OS server and the external address space must be on the same z/OS logical partition (LPAR). WAS z/OS 8.0.0.1 provides a proxy function to allow WOLA callers and WOLA targets to be located separately. This includes location on operating system instances other than z/OS. This function has two formats: proxy support for outbound calls, and proxy support for inbound calls.

Proxy Support for Outbound Calls

This provides a mechanism by which Java applications may use the supplied WOLA JCA resource adapter to access a target address space on remote z/OS. An example usage pattern would be development or test of a proposed an application. Access to the cross-memory WOLA connection on the target z/OS system is provided by a supplied WOLA proxy application installed in a WAS z/OS server enabled for WOLA. The following picture illustrates the topology:

The network flow from the application to the WAS z/OS system is by way of IIOP. The WOLA connection factory is informed of this IIOP flow to the proxy by way of several new custom properties to the connection pool. The proxy application on WAS z/OS receives the call and forwards it over an actual cross-memory WOLA connection to the named target service.

This topology has limitations compared to outbound WOLA calls on the same z/OS LPAR: global transactions requiring two-phase commit can not be propagated across the IIOP connection to the WOLA proxy, and the user identity on the WAS thread can not be asserted into the target service on z/OS.

Proxy Support for Inbound Calls

This provides a mechanism by which non-Java applications in an external address space may make inbound calls to a target WOLA-enabled EJB in a remote WAS instance, either on another z/OS LPAR or a distributed WAS platform. The same supplied WOLA proxy application installed in a local WAS z/OS instance is required to handle the initial cross-memory WOLA call and forward that to the named target EJB on the remote WAS instance. The following picture illustrates the topology:

The target WOLA-enabled EJB is unaware the proxy is in use. The inbound flow arrives as an IIOP call just as it does if cross-memory WOLA on the same LPAR was used. The calling program must indicate the flow will use the proxy service. This is done with a parameter on BBOA1INV (or BBOA1SRQ) of 2 for the requesttype parameter. This tells the local proxy application to treat requested service, which is specified as the JNDI name of the target EJB, as a request to invoke the EJB using IIOP. This requires the local and remote WAS instances to have federated names spaces or operate as a single cell for the JNDI lookup to succeed.

8.0.0.3 and 8.0.0.4 / 8.5.0.1

In 8.0.0.3 (and 8.5.0.1) WOLA support included in IBM Integration Designer for BPEL Processes.

In 8.0.0.4 (and 8.5.0.1) support updated to include RRS transaction context assertion from IMS dependent regions into WAS over WOLA:

8.0.0.5 (and 8.5.0.2)

Fixpack 8.0.0.5 / 8.5.0.2 provided two functional enhancements: (1) RRS transaction context assertion from WAS into IMS over WOLA / OTMA, and (2) enhanced support for CICS channels and containers.

For IMS transaction:

For enhanced support for CICS channels and containers, prior to 8.0.0.5 / 8.5.0.2 the CICS channels and containers support was limited to a single fixed-name channel for both request and response, and a single container of type BIT or CHAR. With 8.0.0.5 / 8.5.0.2:

Components

The Optimized Local Adapters may be categorized into the following components:

Overview of CICS support

The Optimized Local Adapters are implemented in CICS as a Task Related User Exit (TRUE). This is what provides the essential connectivity from CICS cross memory to the WAS z/OS address space.

In addition, a Link Server Task (BBO$) and a Link Invocation Task (BBO#) is supplied for calls from WAS to CICS. The BBO$/BBO# link server task shields programming specifics from CICS programs. The OLA call from WAS is handled by these supplied tasks, and the named CICS program is invoked with the standard EXEC CICS LINK call. The named CICS program remains unchanged and unaware the call came from WAS using OLA. The target program in CICS must be able to be invoked with a LINK call. Both COMMAREA and Channels/Containers is supported.

A BBOC transaction is also supplied to provide a set of control commands to do things such as manually start the TRUE (if not in PLTPI), stop the TRUE, start and stop the Link Server, as well as other control and management functions.

The OLA programming interface module library data set must be concatenated to the CICS region's DFHRPL DD statement.

The following picture summarizes the WOLA CICS support for transaction propagation and security assertion:

Overview of IMS support

The Optimized Local Adapters are implemented as an external subsystem to IMS. Usage is supported for Message Processing Programs (MPP), Batch Message Processing programs (BMP), IMS Fast Path (IFP) and Batch DL/I applications.

Calls from IMS into WAS use the External Subsystem Attach Facility (ESAF). This is the same interface as used by other subsystems such as DB2 or MQ.

Calls from WAS into the IMS dependent region may be done using OTMA or directly (that is, program in IMS uses OLA APIs to "host a service" as described below). OTMA provides OLA transparency to the IMS applications at a cost of some overhead. Using the OLA APIs in the IMS application reduces the overhead which results in better performance and throughput.

The programming APIs for IMS are the same format and syntax as introduced originally. But they have been updated to be aware of IMS if running there and to use ESAF.

Further, the ola.rar file that implements the JCA resource adapter for WAS must be the one shipped with Fixpack 7.0.0.12 or later to use with IMS. The method parameters have been updated for the IMS support and that update is made available to WAS by re-installing the ola.rar that comes with 7.0.0.12.

The following picture summarizes the WOLA IMS support for transaction propagation and security assertion:

Inbound to WAS z/OS

The external address space accesses the OLA mechanism through the supplied interface modules and documented APIs. There are 13 APIs at the present time. They are categorized below.

Java programs running in the WAS z/OS environment wishing to be the target of an invocation from outside must implement the OLA interface in a stateless session bean using the OLA class files supplied in the development tooling support.

Outbound from WAS z/OS

A Java program wishing to initiate an OLA call outbound may be implemented as either a servlet or EJB. The Java program codes to the supplied JCA resource adapter (ola.rar) using the class files supplied in the development tooling support.

External address spaces that are the target of the outbound call must be in a state ready to accept the call. Two basic models exist:

Synchronous and Asynchronous Operations

The APIs support both modes. Synchronous provides a simpler programming model because program control is not returned to the calling program until a response has been received. Asynchronous provides the architect with an opportunity to process other work without having to wait on a response coming back from a long running target process.

Modular Design

It is possible to design the OLA-specific programming artifacts to serve as "bridges" between the OLA interface and existing assets. That serves to minimize impact to existing programming assets and limits the degree of "platform lock in."

APIs

There are 13 APIs, categorized into the following categories:

The InfoCenter has a full write-up of each along with parameter lists and return code (RC) and reason codes (RSN). Search on cdat_olaapis.

Illustrations of Common API Patterns

A common inbound API usage model would be:

In this case the BBOA1REG API is used to register into the WebSphere Application Server for z/OS Daemon group (the cell short name), and multiple invocations of BBOA1INV are used to invoke the target EJB. BBOA1INV is synchronous so program control is held until the EJB returns a response. This API is useful when the calling program knows the size of the response message in advance. If the response message size is unknown at the time of the call then the more primitive APIs (BBOA1SRQ (send request), BBOA1RCL (get response length), BBOA1GET (get message data)) would be more appropriate.

When the calling program determines it has finished its work, it uses BBOA1URG to unregister from the Daemon group.

If the target Java program has a longer response interval then an asynchronous model is likely better. The following picture illustrates how an asynchronous call would be done using what is known as the primitive API: BBOA1SRQ with the async=1 parameter set:

As the picture illustrates, the asynchronous mode allows the non-Java program to get control and do other processing. That implies checking for a response at some future point. BBOA1RCL is used for that purpose. In this example BBOA1RCL is issued synchronously (parameter async=0). If a response is available BBOA1RCL will provide the length and program control returns to the program. If no response is available BBOA1RCL holds program control until one is available. BBOA1RCL with async=1 will return x'FFFFFFFF' if no response is available; program control is returned immediately.

Other illustrations for outbound may be found in the WP101490 document found on the IBM Techdocs website.

Note: Outbound from WAS to CICS would not require API coding. In that case the supplied BBO$/BBO# link server transactions would do that processing. Those link server transactions "host a service" using the internal constructs similar to the BBOA1SRV API. Outbound to a batch program would require the use of the APIs to "host a service."

Transactionality

The Optimized Local Adapters support two-phase commit (2PC) processing from CICS inbound to WAS.

With the advent of maintenance 7.0.0.12, the Optimized Local adapters also support two-phase commit outbound from WAS to CICS. Prior to 7.0.0.12 the transactional support from WAS to CICS was limited to "sync on return."

For IMS, support for transactional assertion inbound to WAS from IMS dependent regions was provided in fixpack 8.0.0.4 and 8.5.0.1. Transaction assertion outbound from WAS to IMS over WOLA/OTMA provided in fixpack 8.0.0.5.

Transactional propagation is not supported inbound or outbound to batch, USS or Airlines Line Control.

Security

The Optimized Local Adapters are capable of asserting identity in the following circumstances:

Limitations

The WAS z/OS Optimized Local Adapters can be used only within a given LPAR. It is a cross-memory mechanism and can not go between LPARs or off the machine.