WebSphere Optimized Local Adapters

IBM WebSphere Optimized Local Adapters (OLA or WOLA) is a functional component of IBM's WebSphere Application Server for z/OS that provides an efficient cross-memory mechanism for calls both inbound to WAS z/OS and outbound from z/OS. Because it avoids the overhead of other communication mechanisms, it is capable of high volume exchange of messages. WOLA is an extension to the existing cross-memory exchange mechanism of WAS z/OS, with WOLA providing an external interface so z/OS address spaces outside the WAS z/OS server may participate in cross-memory exchanges. WOLA supports connectivity between a WAS z/OS server and one or more of the following: CICS, IMS, Batch, UNIX Systems Services and ALCS. WOLA was first made available in WAS z/OS Version 7, Fixpack 4 (7.0.0.4). Functional enhancements have appeared in subsequent fixpacks as documented in this article.

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:

• Messaging, such as Websphere MQ or other JMS providers.
• RMI/IIOP
• Web Services

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:

• IBM CICS
• Batch Jobs
• UNIX System Services (USS)
• Airline Control System (ALCS)
• IMS (support started with maintenance 7.0.0.12)

The programming languages supported in the external address spaces are:

• C/C++
• COBOL
• High Level Assembler
• PL/I

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).

Functional Updates, Part 1

Functional Updates, Part 3

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:

• Support for CICS, Batch, USS, and ALCS
• One-phase commit for outbound WAS into CICS (2PC into CICS TS 4.1 provided with 7.0.0.12)
• Two-phase commit for inbound CICS into WAS
• Native APIs
• JCA resource adapter

7.0.0.12

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

• Support for WOLA and IMS
• Two-phase commit transaction processing from WAS outbound to CICS TS 4.1

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:

• Multi-segment large message support (greater than 32K in size) for work with IMS
• Support for inbound transaction classification of WOLA calls separate from IIOP calls
• Identification within the SMF 120.9 record for WOLA calls as WOLA rather than IIOP
• Resource failure identification and alternative JNDI failover

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:

• failureThreshold - the number of consecutive getConnection() failures that must occur before automatic failover is invoked
• alternateResourceJNDIName - the JNDI name of the alternate connection factory to use if automatic failover is invoked
• resourceAvailabilityTestRetryInterval - the interval in seconds WAS employs to test for return of primary resource

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 APIs for C/C++ programs operating in 64-bit mode
• SMF 120 subtype 10 records for WOLA outbound calls from WAS (SMF 120 subtype 9 captures inbound call information)
• Work Distribution - the ability to round-robin outbound calls across multiple external registrations of the same name
• Proxy support for remote access - this takes two forms: inbound and outbound

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:

• Platform neutral server information section
• z/OS server information section
• Outbound Request information section
• WOLA Outbound Request type specific section
• Outbound Request transaction context section
• Outbound Request security context section
• Outbound Request CICS context section
• OTMA Outbound Request type specific section

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:

• Applications in IMS use set the "transaction supported" flag on register API
• Target WAS environment has ola_rrs_context_propagate = 1 environment variable set and enabled
• IMS Control Region needs to be running with RRS=Y

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:

• IMS Control Region needs to be running with RRS=Y
• Target WAS environment has ola_rrs_context_propagate_otma = 1 environment variable set and enabled

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:

• Send and receive one or more containers from target CICS program
• Channel name is set by you using setLinkTaskChanID() method
• Channel type is set by you using setLinkTaskChanType() method
• The names of the individual request containers are set by adding data to the MappedRecord, using the put() method.
• The keys of the MappedRecord correspond to the CICS container names, and the corresponding value will be used to fill the container in CICS.
• The response container names will be extracted from the channel after the CICS request is finished, and populated into a new MappedRecord, which is returned to the client.

Components

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

• Interface Modules -- provide the programmatic access to the OLA interface and the OLA APIs
• CICS Task Related User Exit, Link Task Server and control transaction -- provides a simplified mechanism for supporting outbound calls to program assets in CICS.
• JCA Resource Adapter -- provides the interface between the Java environment and the external environment
• Development Tooling Support -- provides the supporting classes for developing OLA-enabled applications
• Samples -- a set of C/C++, COBOL and Java samples that illustrate the use of the programming model

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^{[ clarification needed ]} 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:

Programming Considerations

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:

• If the external address space is CICS, then the user has the option to employ the supplied Link Server Task to act as the receiving agent on behalf of existing CICS program assets. The Link Server task (BBO$ by default) receives the call and issues an EXEC CICS LINK of the program named on interactionSpecImpl.setServiceName(). No changes to the existing CICS program are necessary provided it supports either COMMAREA or Channels/Containers.
• If the external address is IMS, then the call may be made using the IMS OTMA interface (which implies no change to your IMS application), or directly using OLA (which implies using the OLA APIs in the IMS program to "host a service").
• If the external address space is something other than CICS or IMS, then the program needs to "host a service" using one of the supplied APIs. That puts the program in a state ready to receive a call from the Java program in WAS z/OS. When the call is received it may then process the request and supply a response back to the Java program in WAS z/OS

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."

• Outbound to CICS—use the provided Link Server implementation; no changes to your CICS programs at all.
• Inbound to WAS—construct an EJB that takes the OLA call, then turns and calls the specified EJB. If the target EJB is in the same JVM then it can be highly efficient. If the target EJB is in the same cell on the same LPAR then the previously mentioned "local communications" function is used.

APIs

There are 13 APIs, categorized into the following categories:

• General Setup and Teardown -- BBOA1REG (register) and BBOA1URG (unregister)
• Inbound Basic -- BBOA1INV (invoke with automatic get response)
• Inbound Advanced -- BBOA1CNG (get connection), BBOA1SRQ (send request), BBOA1RCL (get response length), BBOA1GET (get message data), BBOA1CNR (release connection)
• Outbound Basic -- BBOA1SRV (host a service), BBOA1SRP (send response)
• Outbound Advanced -- BBOA1RCA (receive on connection any), BBOA1RCS (receive on connection specific), BBOA1GET (get message data), BBOA1SRP (send response) and BBOA1SRX (send an exception)

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:

• WAS --> CICS : The identity on the WAS thread used to call the WOLA API can be used to assert identity into CICS. In order to do this, the WOLA CICS link server must be used and started with the SEC=Y parameter and the CICS region must be running with SEC=YES and the ID the link server task runs under must have SURROGAT SAF authority to start transactions on behalf of the propagated user ID. Refer to the IBM InfoCenter for more details on this.
• WAS --> Batch, USS or ALCS : no attempt to assert identity is made. The target process runs under the identity used when it was started.
• CICS --> WAS : CICS can assert its region ID or the application user ID
• Batch, USS or ALCS : The external process will attempt to assert its identity into WAS z/OS.

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.

External links

• Redbooks: WebSphere on z/OS - Optimized Local Adapters
• IBM Techdocs: WebSphere z/OS Optimized Local Adapters
• IBM InfoCenter: Planning to use optimized local adapters for z/OS
• Video demonstrations can be seen on YouTube by searching on the keyword WASOLA1
• YouTube videos:
  • WP101490 - WOLA - Essentials of WOLA
  • WP101490 - WOLA - CICS
  • WP101490 - WOLA - IMS
  • WP101490 - WOLA - Native APIs Part 1 of 2
  • WP101490 - WOLA - Native APIs Part 2 of 2
  • WP101490 - WOLA - Java Considerations