WebSphere Optimized Local Adapters
Encyclopedia
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. The following list summarizes the release time line and function provided:
Because it avoids the overhead of other communication mechanisms, it is capable of high volume exchange of messages.
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.
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.
s 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.
With fixpack 7.0.0.12 the IMS support was introduced, as well as the ability to propagate two-phase commit into CICS TS 4.1.
WOLA in WAS z/OS V8.0.0.0 provided multi-segment large messages (greater than 32K) in the IMS support; support for inbound transaction classification separate from IIOP, and identification in SMF 120.9 as an WOLA inbound call rather than IIOP; and the ability detect the loss of an external address space and fail over to an alternate connection factory for outbound calls, then fail back when the primary external address space returns. An example where this new function enhances availability is with CICS where WOLA provides the connection to a CICS routing region in a CICPlex. The loss of the primary routing region does not need to imply loss of connectivity to application regions in the CICSPlex. Provided there's a secondary routing region and a defined alternate connection factory, failover occurs on the next getConnection request. Fail back occurs when the primary routing region returns and a getConnection is issued.
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:
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:
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.
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:
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.
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."
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."
Transactional propagation is not supported inbound or outbound to batch, USS or Airlines Line Control.
IBM
International Business Machines Corporation or IBM is an American multinational technology and consulting corporation headquartered in Armonk, New York, United States. IBM manufactures and sells computer hardware and software, and it offers infrastructure, hosting and consulting services in areas...
's WebSphere Application Server for z/OS
WebSphere Application Server for z/OS
IBM WebSphere Application Server for z/OS is one of the platform implementations of IBM's WebSphere Application Server family. The current version is Version 8.0....
that provides an efficient cross-memory mechanism for calls both inbound to WAS z/OS and outbound from z/OS. The following list summarizes the release time line and function provided:
- 7.0.0.4 -- Initial release of the WebSphere Optimized Local Adapters. Batch, USS, CICS and ALCS support.
- 7.0.0.12 -- Second release of functionality. IMS support included along with two-phase commit outbound from WAS to CICS.
Because it avoids the overhead of other communication mechanisms, it is capable of high volume exchange of messages.
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 MQWebSphere MQIBM WebSphere MQ' is a family of network software products launched by IBM in March 1992. It was previously known as MQSeries, a trademark that IBM rebranded in 2002 to join the suite of WebSphere products. WebSphere MQ, which is often referred to simply as "MQ" by users, is IBM's Message...
or other JMS providers. - RMIRMIRMI can refer to:In computing:* RMI Corporation, a semiconductor company manufacturing CPUs* Remote Method Invocation, a Java application programming interface* Rights Management Information, under WIPO Internet Treaties...
/IIOP - Web ServiceWeb serviceA Web service is a method of communication between two electronic devices over the web.The W3C defines a "Web service" as "a software system designed to support interoperable machine-to-machine interaction over a network". It has an interface described in a machine-processable format...
s
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 spaceAddress space
In computing, an address space defines a range of discrete addresses, each of which may correspond to a network host, peripheral device, disk sector, a memory cell or other logical or physical entity.- Overview :...
s supported for WAS z/OS OLA are:
- IBM CICSCICSCustomer Information Control System is a transaction server that runs primarily on IBM mainframe systems under z/OS and z/VSE.CICS is a transaction manager designed for rapid, high-volume online processing. This processing is mostly interactive , but background transactions are possible...
- Batch Jobs
- UNIX System ServicesUNIX System ServicesUNIX System Services is a required, included component of z/OS. USS is a certified UNIX implementation optimized for mainframe architecture. It is the first UNIX 95 to not be derived from the AT&T source code...
(USS) - Airline Control System (ALCS)ALCS transaction monitorALCS, which stands for Airline Control System, is an application server that provides industrial-strength, online transaction management for mission-critical applications....
- IMSIMS-Organizations and institutes:* IMS International Medical Services, a department of the State University Medical Center Freiburg offering services for foreign patients....
(support started with maintenance 7.0.0.12)
The programming languages supported in the external address spaces are:
- C/C++C++C++ is a statically typed, free-form, multi-paradigm, compiled, general-purpose programming language. It is regarded as an intermediate-level language, as it comprises a combination of both high-level and low-level language features. It was developed by Bjarne Stroustrup starting in 1979 at Bell...
- COBOLCOBOLCOBOL is one of the oldest programming languages. Its name is an acronym for COmmon Business-Oriented Language, defining its primary domain in business, finance, and administrative systems for companies and governments....
- High Level Assembler
- PL/IPL/IPL/I is a procedural, imperative computer programming language designed for scientific, engineering, business and systems programming applications...
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
The function was first made available with the 7.0.0.4 maintenance fixpack to WebSphere Application Server for z/OS.With fixpack 7.0.0.12 the IMS support was introduced, as well as the ability to propagate two-phase commit into CICS TS 4.1.
WOLA in WAS z/OS V8.0.0.0 provided multi-segment large messages (greater than 32K) in the IMS support; support for inbound transaction classification separate from IIOP, and identification in SMF 120.9 as an WOLA inbound call rather than IIOP; and the ability detect the loss of an external address space and fail over to an alternate connection factory for outbound calls, then fail back when the primary external address space returns. An example where this new function enhances availability is with CICS where WOLA provides the connection to a CICS routing region in a CICPlex. The loss of the primary routing region does not need to imply loss of connectivity to application regions in the CICSPlex. Provided there's a secondary routing region and a defined alternate connection factory, failover occurs on the next getConnection request. Fail back occurs when the primary routing region returns and a getConnection is issued.
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
- CICSCICSCustomer Information Control System is a transaction server that runs primarily on IBM mainframe systems under z/OS and z/VSE.CICS is a transaction manager designed for rapid, high-volume online processing. This processing is mostly interactive , but background transactions are possible...
Task Related User Exit, Link Task Server and control transaction -- provides a simplified mechanism for supporting outbound calls to program assets in CICS. - JCAJCA- Organizations :* Josephite Community Aid, Australian charity founded in 1986* Jewish Colonization Association, created in 1891 to facilitate the mass emigration of Jews from Russia and other Eastern European countries* Joint Church Aid...
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 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 (Fixpack 7.0.0.12)
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:
- 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 interace 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."
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: Implementing optimized local adapters for z/OS
- Video demonstrations can be seen on You Tube by searching on the keyword WASOLA1
- You Tube videos:
- WP101490 - WOLA - Essentials of WOLA http://www.youtube.com/watch?v=bpUiJ-wp0qA
- WP101490 - WOLA - CICS http://www.youtube.com/watch?v=d3WWNWiQMJI
- WP101490 - WOLA - IMS http://www.youtube.com/watch?v=BDBQ1qbsRqo
- WP101490 - WOLA - Native APIs Part 1 of 2 http://www.youtube.com/watch?v=lNyg6tMUkXc
- WP101490 - WOLA - Native APIs Part 2 of 2 http://www.youtube.com/watch?v=7wNESRJ9lXY
- WP101490 - WOLA - Java Considerations http://www.youtube.com/watch?v=oVFSY_F6ceY