Re-engineering applications using optimized local adapters on WebSphere Application Server for z/OS


Reusing business logic available in Enterprise JavaBeans™ (EJBs) under the IBM WebSphere Application Server runtime by applications in traditional z/OS environments has typically been challenging and costly. Although the use of XML document-based technologies for communications between applications has gained momentum over the past several years, it remains ill-suited for synchronous calls between small application units co-located on the same z/OS system. For program-to-program communications between classic application environments on z/OS and those based on Java™ and running on WebSphere Application Server for z/OS, the overhead of Java serialization and de-serialization, coupled with the conversion to and from XML (for example, for SOAP) and subsequent copying of the message to and through the TCP/IP stack, can add significant latency, which can make the cost of delays and CPU consumption excessive, and, in many cases, prohibitive.

Optimized local adapters support was introduced in WebSphere Application Server V7 as a built-in feature for WebSphere Application Server for z/OS that gives z/OS application developers and architects an optimized alternative for synchronous calling between native language programs running in legacy application environments (like z/OS batch, CICS, and IMS) and those running on WebSphere Application Server for z/OS. Optimized local adapters were designed to provide a simple way for you to quickly start integrating legacy business logic with capabilities available in Java-based programs running on WebSphere Application Server.

  • For the COBOL, C/C++, PL/I, or Assembler language developer, the programming model is a call to an API to initiate the communications with the application server, and another API call to start invoking Java EE-based assets in WebSphere Application Server.
  • For the Java developer supporting a WebSphere Application Server-based application (EJB or servlet) and calling outbound from WebSphere Application Server to a legacy application, the programming model is the familiar JCA 1.5.

Along with very low-latency bi-directional calling, optimized local adapters provide additional optimizations for essential qualities of service that make it uniquely qualified for high performance interactions between applications in WebSphere Application Server and those in external address spaces running on the same z/OS image. The transfer and assertion of the current task’s user security context between address spaces is among these.

In the area of transactions, for calls between CICS and WebSphere Application Server, optimized local adapters provide local and global transaction support where CICS or WebSphere Application Server might be the initial requestor or coordinator. For calls from CICS applications to those in WebSphere Application Server, optimized local adapters provide a way to map workload context, ensuring that high priority CICS transactions retain that status once they call over to WebSphere Application Server. This will be explained further in the sections that follow.

Figure 1. What are optimized local adapters?
Figure 1.  What are optimized local adapters?
Figure 1. What are optimized local adapters?

How optimized local adapters work

Since its earliest days, WebSphere Application Server for z/OS has used a set of high performance communication services called Local Comm, which provides a set of cross-memory services that enable one WebSphere Application Server for z/OS server to quickly pass work to another and receive the results.

Optimized local adapters extend this technology and introduce new support that enables a standard, problem state application to switch into the needed state and drive the associated Local Comm services required to queue requests over to a specific WebSphere Application Server server. The process of introducing an address space to a specific server is called registration. During the optimized local adapters REGISTER API call, the application indicates which cell, node, and server it wishes to communicate with. It also provides a register name and information about the number of connections it wishes to establish and set as a maximum. Once the registration process completes, the application can begin communicating with any application installed in the target application server..


Calls to the optimized local adapter invocation or send request APIs do not result in an inbound JCA request to drive into the target EJB. Instead, a context switch to the WebSphere Application Server control region is made for these requests, and the request flows through a streamlined dispatch path to the target EJB method in the WebSphere Application Server servant region. For inbound calls to WebSphere Application Server EJBs, the target EJB must implement the optimized local adapter and interfaces, which include a target method, called execute(), that accepts a byte array and returns a byte array. A JAR file called ola_apis.jar is provided and contains these interfaces. This JAR file is located in the WebSphere Application Server for z/OS file system and must be included on the application’s build path.

Calls from WebSphere Application Server applications (EJBs or servlets) are supported by a new resource adapter provided by WebSphere Application Server called ola.rar. External address space applications are required to first use one of the optimized local adapter server APIs (Host Service or Receive Request) and identify themselves as target services. The WebSphere Application Server application then needs to set the Register name it wishes to contact on the Connection Specification and the Service Name on the Interaction Specification before making the call into the target service.

Calling unchanged CICS and IMS applications

Optimized local adapters provide capabilities that enable WebSphere Application Server applications to call existing, unchanged CICS and IMS transactions.

For CICS, the optimized local adapter CICS link server can be started in the CICS region using a new WebSphere Application Server-supplied CICS control transaction (BBOC). The link server accepts program LINK requests from WebSphere Application Server over optimized local adapters and calls the target CICS program using the EXEC CICS LINK API. It can pass a set of parameters to the program in either a COMMAREA or a CHANNEL/CONTAINER. It receives the response back and returns it to the caller in WebSphere Application Server.

For calling existing, unchanged IMS transactions, optimized local adapters provide a facility for making calls over IMS Open Transaction Manager Access (OTMA). These transactions can be driven in IMS message processing regions or fast path dependent regions.

Figure 2. The optimized local adapters interface
Figure 2.  The optimized local adapters interface
Figure 2. The optimized local adapters interface

Mapping parameter data to and from Java objects

When calling an optimized local adapters-capable EJB, the same data structures used by your native language application can be used to generate Java classes with getter and setter methods for each attribute in the data structure. When using IBM Rational® Application Developer or IBM Rational Developer for System z®, the CICS/IMS Java Data Binding wizard in the J2C category is the wizard that creates these Java classes. The wizard takes any COBOL, PL/I, or C data structure as input and generates a Java class with the associated getter and setter methods.

In addition to mapping numeric and byte fields, it also converts string data to the appropriate codepage when the correct codepage for your native language application is selected. When receiving data from a native language application, the byte stream is fed into a new instance of the class, and getter methods are used to read the attributes. When sending data to a native language application, a new instance of the class is created and setter methods are used to populate the attributes. The class is then serialized into a byte stream which is sent to the native language application. In most cases, the Java classes generated to map data for calls using optimized local adapters can also be used with applications using CICS Transaction Gateway or IMS Connect.

Security propagation

Optimized local adapters provide support for sharing security credentials between applications in external address spaces and WebSphere Application Server applications, depending on whether the work is passed into or out of WebSphere Application Server. Let’s examine security propagation in each direction separately.

Inbound to WebSphere Application Server

For batch z/OS applications making calls to WebSphere Application Server EJBs, the user ID on the running job’s thread, or TCB, at the time of the Register API call is the one used for all subsequent calls to WebSphere Application Server applications. This ID is propagated and asserted in the WebSphere Application Server EJB container. There is a System Access Facility (SAF) check during the Register API call for the user’s access to the target server’s CBIND SAF class. If the ID making the Register API call does not have at least READ access to this class, the register call will not be accepted.

CICS and IMS to WebSphere Application Server

In order for requests sent in to WebSphere Application Server from CICS to have the user ID on the current CICS task propagated to WebSphere Application Server, the CICS startup parameters must indicate SEC=Y. Without CICS security enabled, optimized local adapters will propagate the authority of the overall CICS region instead of an individual task user.

To direct optimized local adapters to use the credentials of the particular CICS transaction that initiated the work, set the reg_flag_C2Wprop flag when calling the Register API (BBOA1REG). Because it might not be permissable for a WebSphere Application Server application to make that kind of security-based decision, WebSphere Application Server administrators have the option to either configure the server to allow or deny this behavior. To indicate that this activity is permitted, define and set the environment variable ola_cicsuser_identity_propagate to 1 in the WebSphere Application Server administrative console. (Of course, if the variable was not set and you have to create or modify it, you’ll need to restart the servers within its scope in order for it to be activated. You will know the environment variable is not set if you attempt to use the Register API with the reg_flag_C2Wprop field set to 1 and the call fails with a return code 8 and reason code 21.)

For calling from IMS batch message processing regions, as for z/OS batch applications, the Job user ID is propagated and asserted in the WebSphere Application Server EJB container. For IMS message processing programs (MPPs) and fast path programs (IFPs,) the same process occurs: the identity on the current transactions thread (TCB) is propagated. For MPPs and IFPs, in order for the user ID to reflect the true IMS transaction’s user ID, you must implement the IMS Build Security Environment (DFSBSEX0) exit, which tells IMS to keep the TCB user ID context in sync with the current IMS transaction’s identity.

Outbound from WebSphere Application Server

For calling batch server programs from WebSphere Application Server, the user ID of the batch job is used for requests from WebSphere Application Server. There is no identity propagation in this scenario.

WebSphere Application Server to CICS and IMS

Thread level user ID propagation from WebSphere Application Server to CICS can be accomplished using the optimized local adapters CICS link server. To achieve this, you must start the link server with SEC=Y. When running in this mode, the optimized local adapter will propagate the identity of the user on the current thread to CICS and the link server will start up a link task using EXEC CICS START TRANSID(‘BBO#’) USER(<userid>). You need to ensure that the CICS SURROGAT SAF class is active and that the user ID under which the link server is running has authority to issue START TRANSID for the propagated user ID.

For WebSphere Application Server to IMS security propagation and assertion, you need to use the optimized local adapters over OTMA support. The WebSphere Application Server for z/OS server must be configured to run with the SyncToThread option enabled. Also, the IMS OTMA parameter OTMASE=FULL must be set. With this, the user ID under which the WebSphere Application Server application is running will be propagated and asserted in the IMS message processing or fast path dependent region where the transaction is dispatched. This does not apply to IMS batch message processing regions.

Global transactions support

(WebSphere Application Server and CICS only.)

Optimized local adapters provide two phase commit global transactions support for both CICS to WebSphere Application Server and WebSphere Application Server to CICS program invocations. Both the native language and EJB portions of an application can participate in the same global transaction using two phase commit when the native language portion of the application is running in CICS Transaction Server for z/OS.

When calling from CICS into an optimized local adapter EJB, a z/OS Resource Recovery Services (RRS) unit of recovery token is passed from CICS to WebSphere Application Server, which uses this token to create its own unit of recovery that is then cascaded to the unit of recovery received from CICS. When the CICS transaction reaches a syncpoint, RRS drives the WebSphere Application Server unit of recovery to completion.

When calling from WebSphere Application Server for z/OS into a CICS transaction using optimized local adapters, an XA-capable transaction context is passed from WebSphere Application Server to CICS. The optimized local adapter CICS link server running in CICS reads the XA transaction context and creates a new unit of work to run the specified native language program. When WebSphere Application Server reaches a syncpoint, XA protocol messages are exchanged between WebSphere Application Server and the link server. The link server drives the appropriate functions on the CICS OTS (OT) domain to complete the unit of work.

In order to use the global transaction support when calling into an optimized local adapters EJB, you must be using CICS Transaction Server for z/OS V3.1 or higher. To use the global transaction support when calling into a CICS transaction from WebSphere Application Server, you must be using CICS Transaction Server for z/OS V4.1 or higher. Optimized local adapters decide whether or not to propagate a transaction context based on the settings of the optimized local adapter CICS link server running inside CICS, as well as the transaction attributes of the Java application running inside WebSphere Application Server.

For example, if an EJB component calls a CICS program using the optimized local adapter link server, a transaction context will only be propagated and used if the EJB is currently participating in a global transaction, and the link server was started with transaction support enabled (BBOC with TX=Y). Similarly, if a CICS program calls an optimized local adapter EJB, the transaction context will only be propagated if the EJB is deployed with a transaction attribute that supports global transactions, such as tx_required.

Workload propagation

The z/OS workload management service class, under which optimized local adapter EJB requests are dispatched, can be configured using the workload management transaction class mapping XML file. This same file is used to configure service classes for other work types dispatched in WebSphere Application Server, such as HTTP and MDB requests. Requests are mapped to a WLM transaction class based on attributes of the request, such as the URL for HTTP requests. The workload management administrator then maps transaction classes to service classes by creating definitions in workload management, which are used to assign the priority of the request.

A new request type, called hslc, has been added to the mapping file to support optimized local adapter requests. The service name of the request is used to map the request to a transaction class. The service name can be wildcarded, which allows groups of similar services to be easily assigned to the same transaction class.

When the native language portion of the application is running in CICS transaction Server for z/OS, the transaction name of the CICS transaction can also be used when assigning a service class to the optimized local adapter EJB request. When the CICS transaction makes its optimized local adapter EJB request, the WLM performance block for the CICS transaction will be sent to WebSphere Application Server. The performance block will be inspected for a transaction name, and if one exists, it can be used to assign a service class for the optimized local adapter EJB request. This behavior is configured by setting a property in the workload management transaction class mapping file, and by creating definitions in workload management which map transaction names to service classes instead of transaction classes to service classes.

When using this technique for CICS transactions, it is possible to have both the CICS and WebSphere Application Server portion of the request run under the same service class by duplicating the workload management definition for the CICS transaction, and assigning the duplicate to the "CB" subsystem.


WebSphere Application Server for z/OS manages an internal buffer that holds optimized local adapter trace data. This 8MB buffer holds over 40,000 trace records that can be useful in diagnosing system and transaction work related to optimized local adapter requests. When the buffer fills, it wraps so that it provides a finite view back in time of optimized local adapter processing. The size of the time window depends on how quickly trace data is being created. This is affected by the amount of optimized local adapter processing, as well as the setting of the tracing granularity. While the amount of work using optimized local adapters varies, you have the ability to control how much tracing is captured.

Optimized local adapters enable you set three levels: 0 (none), 1 (coarse tracing), and 2 (detailed tracing). You might instinctively conclude that setting a more detailed trace level will generate more records and cause the buffer to wrap more quickly. This is true in general, but you can also target different trace levels for different optimized local adapter registrations, including setting a default for the entire daemon group. With different trace levels set for various registrations, the influx of data into the buffer also depends on the amount of activity in each connection being traced.

Setting up, activating, and printing trace data

Optimized local adapter trace support is dynamic, in the sense that it can be modified on the fly without requiring (for the most part) a server restart. After you decide which of the three available trace levels you wish to implement, the next thing to consider is when and where you want the tracing to take effect. There are two realms to consider. You can:

  • Trace existing registrations.
  • Pre-define trace parameters for registrations that have not yet been created.

Tracing for existing registrations can be set through the z/OS operator modify SETOLATRACE command. Traces can be enabled by registration name or by job name. Both of these can be used to set explicit registrations, or you can use asterisks in the names as wildcard characters to affect multiple connections in one modify command. Let's look at how the SETOLATRACE command can be used.

The operator modify command has a SETOLATRACE keyword with subsequent required parameters. The general form is:

F servername,SETOLATRACE=tracelevel,[ REGNAME=namestring | JOBNAME=namestring ]

where :

  • F is the z/OS modify console command.
  • servername is the target WebSphere Application Server for the command. (This will not be a daemon name.)
  • SETOLATRACE indicates you want to set the optimized local adapter trace level. The required parameter tracelevel is 0, 1, or 2.
  • REGNAME indicates you want to set the trace only for registrations that are matching.
  • JOBNAME indicates you likewise want to set the trace on for specific job names under which the registration was made.
  • namestring specifies the registration name or the job name you want to affect. It might be handy to remember that the namestring can contain wildcard characters (asterisk is the only supported character but you can use several in the namestring. A lone asterisk matches all registrations).

Refer to the WebSphere Application Server Information Center for more details, including examples for using this command.

Be aware that you can turn off all tracing of current registrations by using either of these commands:

  • F servername,SETOLATRACE=0,JOBNAME=*
  • F servername,SETOLATRACE=0,JOBNAME=*

If it is not possible to enter a modify command fast enough to catch certain data in the lifecycle of a registration, you might want to predefine trace parameters so that specific trace settings are immediately set when connections are established. You can pre-define a range of names or set a daemon group-wide default.

Server-wide tracing can be predefined using a optimized local adapter trace properties file. You can enter trace specifications in this file and then tell the daemon to activate the settings. Activating trace properties does not affect existing tracing; it affects how tracing will be set for future registrations.

To pre-define trace properties:

  1. Create a file in HFS. This file should be in EBCDIC and accessible by the daemon. The file is a simple line by line specification of trace property specifications according to this syntax:


    where namestring is an alphanumeric string that can contain asterisk wild characters. It specifies one or more registration names. For clarity, you can put the namestring in either single or double quotes. tracelevel is 0, 1, or 2. Any other value is considered to be 0.

    Trace property entries might look like this:

    Listing 1

    In the last line, *=2, sets a default trace level of 2. If no other specifications match a new registration, it gets, in this example, a trace level of 2.

    Be aware that the trace property entries are retained in the daemon's memory in the order in which they appear in the file. Therefore, when a registration is being created, its name is compared to the trace property entries from top to bottom. As soon as a match is found, the matching process ends. If, in the above example, the *=2 entry had been the first line in the file, it would match every new registration and no other entries will get a chance be compared.

    (Hint: A leading # character indicates the start of a comment, unless it is within a quoted string.)

  2. Create an environment variable with this name in the administrative console:


    This variable is a string and its value is the fully qualified path and filename of your trace properties file.

    (Big hint: Be sure to restart the WebSphere Application Server daemon to make active on all the associated nodes and servers.)

    After the daemon restart, all you need to do is activate the trace properties.

  3. Activate the trace properties by issuing the modify SETOLATRACEPROPS command and the new trace settings will begin to affect future registrations. The syntax is:


Another way to dynamically set trace information is for the application itself to indicate a desired trace level on the call to the BBOA1REG Register API. This setting will be active for the life of the registration unless changed by a SETOLATRACE modify command. Refer to the Information Center for more details on providing the trace level using the Register API.

To direct WebSphere Application Server to print the contents of the optimized local adapter internal trace buffer to the WebSphere Application Server SYSPRINT DD, you’ll need to issue this command:

F servername,DISPLAY,OLATRACE=jjjjj

where jjjjj = z/OS job name of external address space, or wildcard (*) for all.

You should see data that looks like Listing 2 in the SYSPRINT DD of the associated WebSphere Application Server control region:

Listing 2
******** OLATRACE Modify command output start ****************************     
******** Trace records for Jobname: *                                          
Trace: 2010/11/04 19:16:41.197 02 t=6C2580 c=UNK key=S2 tag= (10017001)        
  Description: BBGADISP - OLA Trace record dump                                
  Eye Catcher:  data_address=000002200e817980, data_length=8                   
  |OSet| A=000002200e817980  Length = 0008 |     EBCDIC     |     ASCII      | 
  |0000|C2C2D6C1 E3D9C1C5                  |BBOATRAE        |........        | 
  Version: 1                                                                   
  Size of entry: 192                                                           
  STCK time:  data_address=000002200e81798c, data_length=8                     
  |OSet| A=000002200e81798c  Length = 0008 |     EBCDIC     |     ASCII      | 
  |0000|C6CB10A9 43B3F513                  |F..z..5.        |....C...        | 
  'BBOA'+ Register name:  data_address=000002200e817994, data_length=12        
  |OSet| A=000002200e817994  Length = 000c |     EBCDIC     |     ASCII      | 
  |0000|D6D3C1C2 C3F2F6F1 40404040         |OLABC261        |........@@@@    | 
  WAS Server name:  data_address=000002200e8179a0, data_length=8               
  |OSet| A=000002200e8179a0  Length = 0008 |     EBCDIC     |     ASCII      | 
  |0000|C2C2D6E2 F0F0F140                  |BBOS001         |.......@        | 
  Job name or server name :  data_address=000002200e8179a8, data_length=8      
  |OSet| A=000002200e8179a8  Length = 0008 |     EBCDIC     |     ASCII      | 
  |0000|D6D3C1C2 C3C1D3D3                  |OLABCALL        |........        | 
  Job number: 0                                                                
  ASCB @: fc2580                                                               
  TCB @: 6c8250                                                                
  Message data:  data_address=000002200e8179c0, data_length=128                
  |OSet| A=000002200e8179c0  Length = 0080 |     EBCDIC     |     ASCII      |  
  |0000|C2C2D6C1 F0F7F0F2 C940C2C2 C7C1E2D9|BBOA0702I BBGASR|.........@......|  
  |0010|E5D840E4 978481A3 85D381A3 83884040|VQ UpdateLatch  |..@...........@@|  
  |0020|40404040 40404040 40404040 40404040|                |@@@@@@@@@@@@@@@@|  
  |0030|40404040 40404040 40404040 40404040|                |@@@@@@@@@@@@@@@@|  
  |0040|40404040 40404040 40404040 40404040|                |@@@@@@@@@@@@@@@@|  
  |0050|40404040 40404040 40400000 00000000|          ......|@@@@@@@@@@......|  
  |0060|00000000 00000000 00000000 00000000|................|................|  
  |0070|00000000 00000000 00000000 00000000|................|................|  
******** End of OLATRACE Modify command output ***************************

There are two additional ways to activate tracing for optimized local adapters. These are likely to be requested by the IBM service team in support of problem determination.

  • There is a WebSphere Application Server for z/OS native-level trace component for optimized local adapters that can be activated by issuing this command on the WebSphere Application Server control region :

    F servername,TRACEDATA=G

    After issuing this command, refer to the WebSphere Application Server control and servant region logs and look in the SYSPRINT DD.

  • There is also a Java package-level trace that can be enabled using this operator command:

    F servername,TRACEJAVA=’OLA=all’

    After issuing this, the associated trace data will also appear in the WebSphere Application Server control and servant region SYSPRINT DD.

Extending the WebSphere Application Server stack to legacy z/OS applications

Optimized local adapters provide a means for z/OS applications to harness the WebSphere Application Server for z/OS stack of capabilities. For example, a COBOL or Assembler batch program could call a wrapper EJB in WebSphere Application Server, which in turn drives out to a Web service using SOAP or RESTful style calling. This eliminates the need for the batch program to include an HTTP or Web services stack in its implementation to achieve this. Similarly, with a small proxy servlet that uses optimized local adapters to call a back end server program, an existing application in batch, CICS, or IMS could be reached from callers over Web technologies such as Web services.


Optimized local adapters can be an integral component of an application modernization and re-engineering strategy. By introducing a simple way to perform fine-grained synchronous calling between WebSphere Application Server applications and legacy z/OS environments, optimized local adapters support adds a new dimension to what is considered possible for z/OS application architects and developers. This feature introduces the ability to create composite applications that are made up of smaller components from various application environments like CICS, IMS, and WebSphere Application Server for z/OS. It also ties together the security, transactional, and workload context components from these environments.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Re-engineering applications using optimized local adapters on WebSphere Application Server for z/OS