Generating WebSphere Optimized Local Adapters outbound

WebSphere Optimized Local Adapters can be used to call applications running in external address spaces on z/OS. For optimal performance, these applications must run locally, on the same z/OS image. WebSphere Optimized Local Adapters also support calling applications on z/OS from applications running on a distributed WebSphere Application Server. This is called remote, or developer mode.

About this task

Important: J2C beans are formally supported and tested on WebSphere® Application Servers. Use in other Java™ environments should work, but are not tested extensively. If there are issues with the generated code and it can be isolated as such within a WebSphere Application Server environment, then it will be supported.

Here are the ways that you can use WebSphere Optimized Local Adapters to call outbound applications on WebSphere Application Server.

Calling Batch/UNIX System Services applications

WebSphere Optimized Local Adapter can be used to call batch and USS applications on z/OS that have been changed to use one of the WebSphere Optimized Local Adapter server APIs.

About this task

The WebSphere Optimized Local Adapter receive request (BBOA1RCV) or host service (BBOA1SRV) APIs can be used to make any application available to Java applications in WebSphere Application Server, which can then call them using JCA-style methods. For more information on using these APIs, see Optimized local adapters for z/OS APIs.

Applications running in z/OS batch, CICS, IMS, and USS can all use the WebSphere Optimized Local Adapter APIs to establish themselves as WebSphere Optimized Local Adapter servers, accepting requests from the WebSphere Application Server.

Calling existing CICS applications

WebSphere Optimized Local Adapter can be used for outbound calls in conjunction with the WebSphere Optimized Local Adapter CICS Link Server.

About this task

The WebSphere Optimized Local Adapter Link Server is an application that can be started in a CICS region and it serves as a server or as a proxy for calls to existing CICS programs. In this case, the WebSphere Application Server application calls existing unchanged CICS programs over an EXEC CICS LINK with either a communications area (COMMAREA), or a channel and container to pass in and get response data back.

The default mechanism used by WebSphere Optimized Local Adapter for passing the message payload to a CICS program is the COMMAREA. You can specify that a single CICS container deliver the request message and another be used for the response, by using connection factory properties. For a single request/response container, you set up the request record as an IndexedRecord containing a single entry. You can also specify that WebSphere Optimized Local Adapter deliver multiple messages in multiple containers for the channel name that you supply, by using setter methods or by indicating this is requested in the connection factory. For multiple records, you supply a MappedRecord to WebSphere Optimized Local Adapter for the outbound call to CICS. For more information on CICS Channels and Containers support in WebSphere Optimized Local Adapter, see WebSphere Application Server transactions BBOC, BBO$, BBO#.

Procedure

To generate an implementation that supports CICS containers:

  1. In the Data Import page, when prompted for the COBOL copy book file name, specify the COBOL WebSphere Optimized Local Adapter CICS channel to Java.
  2. When prompted for a CICS channel name to use, specify a request and response container name.
  3. Optional: You can add multiple container names and associate them with the same channel. By doing so, you provide separate mappings (copy books) for each container. This method is useful when using a MappedRecord to pass multiple containers and get multiple containers back from the CICS application.

What to do next

For information on the WebSphere Optimized Local Adapter connection factory properties related to the WebSphere Optimized Local Adapter CICS Link Server, see Connection factory considerations for optimized local adapters. For more details on using WebSphere Optimized Local Adapter with CICS applications, see (Optional) Use the CICS environment.

Calling existing IMS applications

The third way outbound calls can be made over WebSphere Optimized Local Adapter is for calling existing IMS transactions.

About this task

The third way outbound calls can be made over WebSphere Optimized Local Adapter is for calling existing IMS transactions. For this, WebSphere Optimized Local Adapter uses the IMS OTMA Callable Interface. There is a setter method on the WebSphere Optimized Local Adapter connection specification and connection factory that indicates OTMA is in use. WebSphere Application Server applications need to select an OTMA Server name and Group ID and they need to bundle their message payloads as IMS messages and then call the WebSphere Optimized Local Adapter resource adapter, selecting OTMA as the underlying protocol.

Supported message formats for WebSphere Optimized Local Adapter over OTMA

WebSphere Optimized Local Adapter over OTMA supports IMS multi-segment messages.

About this task

IMS request message data for WebSphere Optimized Local Adapter over OTMA must be constructed in the following standard IMS form: LLZZ or LLLLZZ plus IMS transaction ID (8 chars) plus IMS message data.

IMS response message data from the WebSphere Optimized Local Adapter over OTMA call can be returned as either LLZZ plus response data or LLLLZZ plus response data. It is recommended that you review the options for setting up WebSphere Optimized Local Adapter over OTMA to indicate you will be using LLZZ form or LLLLZZ form, WebSphere Optimized Local Adapter supports both for request and response payloads, and these can be set with setter methods on the connection specification or with properties on the connection factory.

When using the workbench Data Importer, inspect the COBOL copy book or PL/I structure, see which format is used for the IMS request payload (LLZZ or LLLLZZ), and select the associated flag in the WebSphere Optimized Local Adapter connection factory (or use the proper setter method) that is aligned with that format. For details on message payload formats, see Calling existing IMS transactions with optimized local adapters over OTMA. For details on WebSphere Optimized Local Adapter over OTMA, see (Optional) Use the IMS environment.

Propagating and asserting security credentials from an external address

WebSphere Optimized Local Adapter supports the propagation and assertion of security credentials from an external address space to the WebSphere Application Server Java bean container.

About this task

The manner of operation varies by the external environment type, whether batch, CICS, IMS. For calls from WebSphere Application Server into batch, user credentials are not propagated and the batch job always runs under the batch user ID. For CICS and IMS, WebSphere Optimized Local Adapter does support propagation and assertion of the user's identity, but you must be using the WebSphere Optimized Local Adapter CICS Link Server for CICS and the WebSphere Optimized Local Adapter over OTMA support for IMS. For more information on this implementation, see Securing optimized local adapters.

WebSphere Optimized Local Adapter also supports two-phase commit global transactions in both directions between WebSphere Application Server and CICS, and WebSphere Application Server and IMS. For more information on WebSphere Optimized Local Adapter and global transactions, see Calling an enterprise bean from an external address space within a client-initiated transaction.

For information on WebSphere Application Server and IMS global transactions, see Calling existing IMS transactions with optimized local adapters over OTMA.

Running WebSphere Optimized Local Adapter applications from a remotely connected application server

By running WebSphere Optimized Local Adapter in development or remote mode, you can connect remotely to WebSphere Application Server that is running on another z/OS system or an application server that is running on a distributed, non-z/OS system.

About this task

WebSphere Optimized Local Adapter is a local technology and the chief benefits are derived from running WebSphere Application Server z/OS colocated with your existing applications in CICS, IMS, and the batch environment. However, you can use the WebSphere Optimized Local Adapter resource adapter in a remotely connecting WebSphere Application Server that is running on either another z/OS system or an application server running on distributed, non-z/OS system. To do so, you must run WebSphere Optimized Local Adapter in development or remote mode, and must have installed the WebSphere Optimized Local Adapter proxy application in the WebSphere Application Server z/OS server to connect to for reaching z/OS assets. The WebSphere Application Server z/OS where the proxy application is running, must be colocated with the targeted back z/OS applications in CICS, IMS, or batch.

When using the remote mode, you can use workbench and WebSphere Application Server, and deploy or redeploy your application without having to make any changes in the WebSphere Application Server z/OS server where the WebSphere Optimized Local Adapter proxy is running. You might need to use this method when developing and testing application updates. For more information on using WebSphere Optimized Local Adapter in Development or Remote mode, see Optimized local adapters deployment in development mode

Generating a WebSphere Optimized Local Adapter outbound calling application: Sample steps

Assuming a scenario where an application, running in any environment, calls into an external address space, here are the steps and sample code to move data from one side to the other for the request and then back for the response.

Procedure

  1. Select File > New > Other > J2C.
  2. Click WebSphere Optimized Local Adapter (IBM:2), and click Next.
  3. On the Connector Import page, in the Connector Project field, accept the default value of ola; in the Target Server field, select the WebSphere Application Server version to use, and click Next.
  4. On the Adapter Style page, select Outbound, and click Next.
  5. On the Connection Properties dialog, enter the JNDI name for the connection factory that will be used for WebSphere Optimized Local Adapter outbound calls, and click Next.
  6. Under J2C Java Bean Output Properties, enter an existing or new project name, package, and Interface Implementation name to be created for this outbound call and click Next.
    1. On the Java Project page, the name that was entered for the project in the New J2C Java Bean page is displayed in the Name field. Ensure that it is correct. If the project name is not displayed, type the project name in the Name field.
    2. In the Name field, type a name for the Java project. To change the default Project location, click the Browse button to select a new location.
    3. In the Target runtime field, select the version of WebSphere Application Server to deploy to. This selection affects the compilation and runtime settings by modifying the class path entries for the project.
      Note: If you specify a new EAR project name, the EAR project is created in the default location with the lowest compatible Java EE version based on the version of the project being created. To specify a different version or a different location for the enterprise application, use the New Enterprise Application Project wizard.
    4. Accept the default Java Module version, or select a different version from the list. If you are creating J2C inbound applications, you must select Java 3.0.
      Important: If you select Java 3.0, the Java 3.0 wizard by default creates a local interface. To create a remote interface, create it manually by adding the @Remote(class= interface.java) annotation to the J2C bean.
    5. In the Configuration field, accept the default configuration, or click Modify and change the project facets for the project.
    6. To add the Java project to an EAR project, select Add project to an EAR.
    7. Choose the EAR project to add the Java module to, or type the name of a new EAR project in the EAR Project Name field, and click Next.
    8. On the Java Module page, in the Source folder field, accept the default for the source folder, ejbModule, or type a different source folder name for the Java project, and click Next.
    9. On the Configure Java module settings page, do these tasks:
      1. To keep the client interface classes for the enterprise beans in a separate Java client JAR file, click the Create an Java Client JAR module to hold the client interfaces and classes. This Java client JAR file is added to the enterprise application as a project utility JAR file.
      2. In the Name field, accept the default name of the Client JAR module, or type a different name.
      3. In the Client JAR URI field, accept the default name of the Client JAR file, or type a different name.
    10. Click Finish.
  7. In the J2C Java Bean Output Properties page,
    1. in the Java Project name field, ensure that the project name is correct or type the correct project name.
    2. in the Packkage name field, type your package name.
    3. in the Stateless Session Java name field, type your stateless session Java name.
    and click Next.
  8. In the Java Methods page, click Add to create a Java method.
  9. On the EJB Method page, in the name field, type a name for your Java method.
    1. in the Input Type field, click Browse to find an input or click New to create one.
      1. On the Data Import page, in the Choose mapping field, select COBOL to Java.
      2. in the COBOL file field, click Browse to locate your COBOL file, and click Next.
      3. On the Importer page, in the Platform field, select z/OS, in the Code page field, select IBM-1047, and in the Data structures field, select the data structure that you want to use, and click Next.
    2. On the Saving Properties page, ensure that the values for the helper class are listed, and click Finish.
  10. On the Java Methods page, in the Service name field, type the target WebSphere Optimized Local Adapter service name. This is name that the external address space application must have used with a WebSphere Optimized Local Adapter Receive Request or Host Service API. When using the WebSphere Optimized Local Adapter CICS Link Server, this is the name that will be matched against the provide Service name, or SVC parameter. When using WebSphere Optimized Local Adapter over OTMA, this is the IMS target transaction name. Click Finish.

Results

Sample Java class

Here is a sample generated WebSphere Optimized Local Adapter external call implementation that was created with the name of zCUSTCPY_Out. It was configured to use a JNDI name of eis/ola and a target service name of ZCUSTGET. This was generated to include data binding helper class that was created from a COBOL copy book with a Level 01 definition called CUSTOMER.

   package com.ibm.rad.ola.test;
   import javax.resource.ResourceException;
   import javax.resource.cci.Connection;
   import javax.resource.cci.Interaction;
   import javax.resource.cci.ConnectionFactory;
   import javax.resource.cci.ConnectionSpec;
   import javax.resource.cci.InteractionSpec;
   import javax.resource.cci.Record;
   import javax.resource.cci.ResourceAdapterMetaData;
   
   
   /**
    * @j2c.connectionFactory jndi-name="eis/ola"
    * @j2c.connectionSpec class="com.ibm.websphere.ola.ConnectionSpecImpl"
    * @generated
    */
   public class ZCICSCustGetImpl implements com.ibm.rad.ola.test.ZCICSCustGet {
   
   	private ConnectionSpec typeLevelConnectionSpec;
   	private InteractionSpec invokedInteractionSpec;
   	private InteractionSpec interactionSpec;
   	private ConnectionSpec connectionSpec;
   	private Connection connection;
   	private ConnectionFactory connectionFactory;
   
   	/**
   	 * @j2c.interactionSpec class="com.ibm.websphere.ola.InteractionSpecImpl"
   	 * @j2c.interactionSpec-property name="serviceName" value="ZCUSTGET"
   	 * @generated
   	 */
   	public com.ibm.rad.ola.test.CUSTOMER zCUSTCPY_Out(
   			com.ibm.rad.ola.test.CUSTOMER arg)
   			throws javax.resource.ResourceException {
   				ConnectionSpec cs = getConnectionSpec();
   				InteractionSpec is = interactionSpec;
   				try {
   					if (cs == null) {
   						cs = getTypeLevelConnectionSpec();
   					}
   					if (is == null) {
   						is = new com.ibm.websphere.ola.InteractionSpecImpl();
   						((com.ibm.websphere.ola.InteractionSpecImpl) is)
   								.setServiceName("ZCUSTGET");
   					}
   				} catch (Exception e) {
   					throw new ResourceException(e.getMessage());
   				}
   				com.ibm.rad.ola.test.CUSTOMER output = new 
					com.ibm.rad.ola.test.CUSTOMER();
   				invoke(cs, is, arg, output);
   				return output;
   			}
	
	< ... more generate methods follow ... >   

An application wishing to use this class simply needs to new up a CUSTOMER record to be passed as input and received as output and then new up an instance of zCUSTCPY_Out() to make the external call over the WebSphere Optimized Local Adapter resource adapter to the target application.

When installing the application that uses these tools, be sure to install the WebSphere Optimized Local Adapter resource adapter and create a connection factory with the same name that was specified in the prompt for JNDI name (in the example, the JNDI name is eis/ola). Also, the WebSphere Optimized Local Adapter Register name must be provided on the connection factory. When using WebSphere Optimized Local Adapter over OTMA, provide the IMS OTMA server name and group name on the connection factory. For information on the WebSphere Optimized Local Adapter connection factory properties related to the WebSphere Optimized Local Adapter over OTMA support, see Connection factory considerations for optimized local adapters.


Feedback