Jump to content

WebSphere Optimized Local Adapters

From Alfawiki
IBM WebSphere Optimized Local Adapters (WOLA)
Company typeSoftware component
IndustryInformation technology
Founded2008; 18 years ago (2008)
ProductsCross-memory communication for WebSphere Application Server for z/OS
ParentIBM

IBM WebSphere Optimized Local Adapters (OLA or WOLA) serve as a vital element within IBM's WebSphere Application Server for z/OS, facilitating high-performance cross-memory communication both into and out of WAS z/OS. By circumventing the latency and overhead associated with alternative communication protocols, WOLA enables rapid message throughput. It enhances the built-in cross-memory capabilities of WAS z/OS by exposing an external interface, which permits z/OS address spaces beyond the WAS server to engage in these interactions. WOLA establishes connectivity between a WAS z/OS instance and various systems including CICS, IMS, Batch processes, UNIX System Services, and ALCS. Its initial release was part of WAS z/OS Version 7, Fixpack 4 (7.0.0.4), with continuous improvements introduced in subsequent fixpacks.

History

The inception of WOLA stemmed from a demand for an effective inbound invocation method—originating outside the Java EE environment and targeting it—particularly on z/OS platforms where batch workloads aimed to utilize Java EE and EJB components. Prior alternatives such as Websphere MQ, JMS implementations, RMI/IIOP, and Web Services presented drawbacks like increased latency, architectural complexity, or challenges related to security and transaction context propagation.

Initially conceived solely for inbound communication, WOLA’s design evolved to accommodate bidirectional calls, supporting both incoming requests to WAS z/OS from external address spaces and outgoing calls from WAS to external systems.

Technical Foundation

WOLA builds upon the "local communications" cross-memory feature integrated into WAS z/OS since version 4.x, which optimized IIOP traffic between servers located on the same LPAR. Fundamentally, WOLA externalizes this underlying mechanism, enabling address spaces outside the WAS z/OS environment to connect and exchange data through shared memory segments.

External applications interact with WOLA via provided APIs, whereas Java components running within WAS z/OS utilize a standard JCA resource adapter implementation.

Current Support

The external address spaces compatible with WAS z/OS OLA include:

Programming languages supported in these external address spaces encompass:

Within Java EE containers on WAS z/OS, Java is employed to access the OLA functionality.

Function Update History

The capabilities of IBM WebSphere Optimized Adapters have progressed alongside new releases and fixpacks. The initial introduction occurred with WAS z/OS Version 7 Release 0 Fixpack 4 (7.0.0.4).

7.0.0.4

WOLA debuted in Fixpack 4 for WAS z/OS Version 7 Release 0, delivering a dedicated directory containing WOLA modules, shared libraries, the JCA resource adapter, and development tools. Installation scripts such as olaInstall.sh established UNIX symbolic links between runtime and installation directories.

Notable features introduced in version 7.0.0.4 included:

  • Integration with CICS, Batch jobs, USS, and ALCS
  • Outbound one-phase commit support from WAS to CICS (with two-phase commit to CICS TS 4.1 added later in 7.0.0.12)
  • Inbound two-phase commit capability from CICS to WAS
  • Availability of native APIs
  • Inclusion of a JCA resource adapter

7.0.0.12

Fixpack 12 brought the following updates:

  • Introduction of WOLA functionality for IMS
  • Implementation of two-phase commit transaction handling from WAS outbound calls to CICS TS 4.1

8.0.0.0

With the release of WAS for z/OS Version 8, WOLA became an integrated component of the product, removing the requirement to execute olaInstall.sh to create symbolic links. Other improvements included:

  • Support for multi-segment large messages exceeding 32K in IMS integration
  • Classification of inbound transactions to differentiate WOLA calls from IIOP calls
  • Distinct identification of WOLA calls versus IIOP within SMF 120.9 records
  • Detection of resource failures coupled with alternative JNDI failover capabilities

Resource Failover and Failback

This functionality monitors the availability of data resources associated with a JCA connection factory and automatically switches to a backup JNDI resource upon failure, reverting back once the primary resource is operational again. While this capability exists across WAS platforms for JDBC and JCA, WAS z/OS Version 8 extends it specifically to WOLA.

Failover is triggered after a configurable number of consecutive getConnection() call failures, redirecting subsequent connection requests to the designated alternate pool until the original resource recovers.

This failover mechanism is particularly valuable for outbound connections targeting CICS routing regions, enhancing CICS availability by allowing multiple routing regions to be utilized.

Key connection pool properties supporting this feature include:

  • failureThreshold – number of successive getConnection() failures required before initiating failover
  • alternateResourceJNDIName – JNDI identifier of the backup connection factory
  • resourceAvailabilityTestRetryInterval – time interval in seconds between attempts to verify primary resource restoration

Note: Additional configuration properties are available; consult the WAS z/OS InfoCenter under "cdat_dsfailover" for comprehensive details.

8.0.0.1 / 8.5.0.0

Note: The WOLA features in WAS z/OS 8.5.0.0 are functionally equivalent to those in version 8.0.0.1.

Fixpack 1 for WAS for z/OS Version 8 introduced significant enhancements to WOLA capabilities:

  • Native APIs callable in 64-bit mode for C/C++ applications
  • SMF 120 subtype 10 records capturing detailed data on WOLA outbound calls from WAS (with SMF 120 subtype 9 covering inbound calls)
  • Work Distribution enabling outbound calls to be distributed round-robin among multiple external registrations sharing the same name
  • Proxy support facilitating remote access for both inbound and outbound calls

64-bit Callable Native API Modules

Prior to version 8.0.0.1, native API modules were only accessible as 31-bit callable libraries with names starting with BBOA*. Version 8.0.0.1 introduced new modules callable in 64-bit mode, identified by the prefix BBGA*, while maintaining existing 31-bit modules.

The total number of APIs remains at thirteen with no changes in their usage patterns.

InfoCenter Search: cdat_olaapis

SMF 120.10 for WOLA Outbound Calls

In WAS z/OS Version 7, SMF records were limited to inbound call tracking under SMF 120 subtype 9, which did not distinguish between WOLA and IIOP traffic.

Version 8.0.0.0 improved SMF subtype 9 by differentiating inbound WOLA calls from IIOP calls.

Version 8.0.0.1 added support for SMF subtype 10 records that provide detailed logging of outbound WOLA calls, consisting of eight sections including platform details, transaction context, and security context.

Each outbound invocation results in a single record being generated.

InfoCenter Search: rtrb_SMFsubtype10

Distribution of Workloads

This enhancement facilitates the allocation of outbound calls among several external address spaces registered under a single identifier within a WAS z/OS server—commonly applicable when multiple CICS regions host stateless target applications.

The preferred method for distributing workloads is specified through a newly introduced environment variable.


InfoCenter Search: cdat_olacustprop

Proxy Capabilities: Both Inbound and Outbound

Previously, WOLA’s cross-memory communication mandated that the WAS z/OS server and the external address space be located on the same z/OS LPAR.

Starting with version 8.0.0.1, proxy functionality allows WOLA clients and targets to function across different systems, including non-z/OS platforms, supporting proxy calls in both inbound and outbound directions.

Outbound Call Proxy Support

This feature permits Java applications to leverage the WOLA JCA resource adapter for connecting to a target address space residing on a remote z/OS system. Primarily used in development or testing scenarios, access to the cross-memory WOLA connection on the remote z/OS is facilitated by a WOLA proxy application deployed on a WAS z/OS server enabled for WOLA. Communication from the client application to the WAS z/OS server is conducted over IIOP. The WOLA connection factory is configured with specific properties that route calls via this proxy, which subsequently forwards them through a cross-memory WOLA link to the intended service.

Notable restrictions include lack of support for global transactions requiring two-phase commit over the IIOP connection and no capability to transfer user identity from the WAS thread to the target z/OS service.

Inbound Call Proxy Support

This functionality enables non-Java applications in external address spaces to initiate inbound calls to WOLA-enabled EJBs hosted on remote WAS instances, whether on another z/OS LPAR or distributed WAS environments. A local WOLA proxy application receives the initial cross-memory call and relays it over IIOP to the target EJB without exposing the proxy’s presence to the EJB itself. The calling program must specify a parameter indicating proxy usage, necessitating either federated namespaces or single cell configuration for JNDI lookups.

Versions 8.0.0.3 and 8.0.0.4 / 8.5.0.1 Enhancements

Version 8.0.0.3 (and 8.5.0.1) introduced integration of WOLA support within IBM Integration Designer specifically for BPEL process workflows.

Subsequently, version 8.0.0.4 (and 8.5.0.1) expanded capabilities by enabling propagation of RRS transaction context from IMS dependent regions into WAS via WOLA, contingent upon:

  • IMS applications activating the "transaction supported" flag during registration API calls
  • Enabling the environment variable ola_rrs_context_propagate = 1 on the target WAS system
  • Running IMS Control Region with RRS=Y

Version 8.0.0.5 (and 8.5.0.2) Updates

Fixpack 8.0.0.5 / 8.5.0.2 delivered two significant improvements: (1) assertion of RRS transaction context from WAS back into IMS through WOLA/OTMA, and (2) enhanced handling of CICS channels and containers.

For IMS transactions:

  • IMS Control Region must be configured with RRS=Y
  • The target WAS environment variable ola_rrs_context_propagate_otma = 1 must be set

Regarding CICS channels and containers, prior functionality was restricted to one fixed channel name and a single BIT or CHAR container per request-response cycle; this update introduces:

  • Support for multiple containers sent and received by target CICS programs
  • Configurable channel name and type using setLinkTaskChanID() and setLinkTaskChanType() methods
  • Request container names mapped as keys within a MappedRecord populated via put() method
  • Response containers extracted after CICS processing into a new MappedRecord returned to clients

Components

The Optimized Local Adapters include the following elements:

  • Interface Modules – enable programmatic interaction with the OLA interface and its APIs
  • CICS Task Related User Exit, Link Task Server, and control transaction – facilitate outbound communication with CICS program resources
  • JCA Resource Adapter – serves as a bridge between the Java environment and external systems
  • Development Tooling Support – provides classes necessary for building OLA-enabled applications
  • Samples – examples in C/C++, COBOL, and Java that illustrate the programming model

CICS Support Overview

Within CICS, Optimized Local Adapters utilize a Task Related User Exit (TRUE) to establish cross-memory connectivity to the WAS z/OS address space. The Link Server Task (BBO$) and Link Invocation Task (BBO#) manage requests from WAS to CICS, abstracting the complexity from CICS programs. WAS OLA invocations call CICS programs using standard EXEC CICS LINK commands without requiring modification of the target applications. Both COMMAREA and Channels/Containers mechanisms are supported.

A BBOC transaction is responsible for issuing control commands such as starting or stopping TRUE and the Link Server, along with other administrative tasks.

The OLA programming interface module library must be concatenated to the DFHRPL DD statement of the CICS region.

The diagram below summarizes WOLA support within CICS for transaction propagation and security assertion:


IMS Support Overview

Optimized Local Adapters function as an external subsystem for IMS, supporting Message Processing Programs (MPP), Batch Message Processing (BMP), IMS Fast Path (IFP), and Batch DL/I applications.

IMS calls into WAS employ the External Subsystem Attach Facility (ESAF), which is also used by DB2 and MQ. Conversely, calls from WAS into IMS-dependent regions can be executed either through OTMA or directly via OLA APIs; utilizing direct APIs improves performance by minimizing overhead.

IMS programming interfaces retain their original structure but are enhanced for IMS awareness and integration with ESAF. For IMS support, the JCA resource adapter's ola.rar file must be version 7.0.0.12 or newer, reflecting updated method signatures.

The diagram below depicts WOLA IMS support for transaction propagation and security assertion:


Inbound to WAS z/OS

External address spaces access OLA through provided interface modules and 13 documented APIs. Java applications running in WAS z/OS that handle external invocations must implement the OLA interface as stateless session beans using the supplied OLA class files.

Outbound from WAS z/OS

Java applications initiating outbound OLA requests may be servlets or EJBs, developed against the JCA resource adapter (ola.rar) with provided class files. The target external address spaces must be prepared to accept these calls:

  • For CICS, the Link Server Task (default BBO$) acts as the receiver, issuing EXEC CICS LINK commands to designated programs without requiring modifications if COMMAREA or Channels/Containers are supported.
  • For IMS, calls can be routed via IMS OTMA (which requires no changes to IMS applications) or through direct use of OLA APIs (requiring hosting a service).
  • Other external address spaces must "host a service" by implementing supplied APIs to receive and handle calls originating from WAS z/OS Java applications.

Synchronous and Asynchronous Operations

APIs accommodate both synchronous and asynchronous communication modes. Synchronous calls streamline development by halting execution until a response is received, whereas asynchronous calls permit simultaneous processing during extended operations.

Modular Design

OLA programming components serve as connectors between OLA interfaces and existing resources, reducing disruption and avoiding platform dependency:

  • For outbound communication to CICS, utilize Link Server without altering CICS programs.
  • For inbound communication to WAS, develop an EJB that accepts OLA calls and efficiently triggers target EJBs within the same JVM or cell through local interactions.

APIs

There are thirteen APIs categorized as follows:

  • General Setup and Teardown – BBOA1REG (registration) and BBOA1URG (unregistration)
  • Inbound Basic – BBOA1INV (invoke with automatic response retrieval)
  • Inbound Advanced – BBOA1CNG (establish connection), BBOA1SRQ (submit request), BBOA1RCL (retrieve response length), BBOA1GET (fetch message data), BBOA1CNR (close connection)
  • Outbound Basic – BBOA1SRV (service hosting), BBOA1SRP (send response)
  • Outbound Advanced – BBOA1RCA (receive on any connection), BBOA1RCS (receive on specific connection), BBOA1GET (fetch message data), BBOA1SRP (send response), and BBOA1SRX (transmit exception)

Comprehensive details on each API, including parameters and return codes, are available in the InfoCenter; search for cdat_olaapis.

Examples of Common API Usage Patterns

In a standard inbound scenario, registration with the WebSphere Application Server for z/OS Daemon group is performed using BBOA1REG, followed by multiple synchronous invocations of the target EJB via the BBOA1INV API. This method is optimal when the expected response size is predetermined. If the response size is uncertain, employing granular APIs such as BBOA1SRQ (send request), BBOA1RCL (retrieve response length), and BBOA1GET (obtain message data) is advisable. Upon completion, the application unregisters using BBOA1URG.

For extended response durations, an asynchronous approach using the primitive API BBOA1SRQ with async=1 is recommended. This enables the calling process to proceed with other tasks while waiting for a reply. Subsequently, the program synchronously invokes BBOA1RCL with async=0 to await the response; this call blocks until data arrives. When using async=1 with BBOA1RCL, it returns immediately with x'FFFFFFFF' if no response is yet available.

Further outbound examples can be found in IBM’s WP101490 documentation.

Note: Outbound interactions from WebSphere Application Server to CICS do not require direct API implementation; these are managed by provided BBO$/BBO# link server transactions that internally utilize mechanisms similar to the BBOA1SRV API. However, outbound calls targeting batch programs must employ these APIs to "host a service."

Transactionality

Optimized Local Adapters facilitate two-phase commit (2PC) transactions from CICS inbound to WAS.

Starting with maintenance release 7.0.0.12, two-phase commit support was extended to outbound transactions from WAS to CICS; previously, transactional handling was confined to "sync on return" operations.

For IMS environments, inbound transactional assertion from IMS dependent regions to WAS was introduced in fixpacks 8.0.0.4 and 8.5.0.1, while outbound transactional assertion from WAS to IMS via WOLA/OTMA became available in fixpack 8.0.0.5.

Transactional propagation is not supported for inbound or outbound interactions involving batch processes, USS, or Airlines Line Control systems.

Security

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

  • WAS → CICS: When the WOLA CICS link server operates with SEC=Y, the CICS region is configured with SEC=YES, and the link server task holds SURROGAT SAF authority to initiate transactions on behalf of the propagated user ID, identity from the WAS thread invoking the WOLA API can be passed into CICS.
  • WAS → Batch, USS, ALCS: Identity assertion is not performed; these target processes execute under their predefined startup credentials.
  • CICS → WAS: The identity asserted can be either the CICS region ID or the application user ID.
  • Batch, USS, ALCS → WAS: External processes make attempts to assert their identity into WAS running on z/OS.

Limitations

The operation of WAS z/OS Optimized Local Adapters is confined to a single LPAR as a cross-memory solution; they do not support communication across multiple LPARs or between different machines.

External links

Retrieved from "https://www.alfawiki.org/index.php?title=WebSphere_Optimized_Local_Adapters&oldid=28161"