Using the Liberty optimized local adapters APIs to invoke an enterprise bean from an external address space

Use the WebSphere optimized local adapter (WOLA) APIs to connect an external address space to a Liberty server and invoke a local stateless session bean.

Before you begin

To identify your enterprise bean as a potential target of an optimized local adapter call, your Enterprise JavaBean (EJB) application must implement the com.ibm.websphere.ola.ExecuteLocalBusiness interface as a local business interface. The interface is located in the wlp/dev/api/ibm/com.ibm.websphere.appserver.api.zosLocalAdapters_1.0.0.jar file.

For programs that are running under Customer Information Control System (CICS), the optimized local adapters task-related user exist (TRUE) program must be activated before a connection is made between CICS and the Liberty server. For more information, see Liberty server transactions for CICS: BBOC, BBO$, and BBO#.

The Liberty server must be active on the same z/OS® image that the register request originates from. Ensure that the current address space is already registered and bound to the target optimized local adapter group using the Register API. For more information about registering an external address space, see Registering an external address space with a local Liberty server using optimized local adapters.

About this task

This method of invoking a stateless session bean provides more flexibility and is for situations when you might not know the response area maximum length before you call. For a simplified method of invoking the bean when the response area length is known, see Using the Liberty Invoke API to call an enterprise bean from an external address space.

Procedure

  1. Call the Connection Get API, BBOA1CNG, from the native-language application in the client address space, passing the register name that you used when you called the Register API, BBOA1REG. The call returns a connection handle that must be used for all future API calls.
  2. Call the Send Request API, BBOA1SRQ, from the native-language application in the client address space. For the requestservicename parameter, specify the Java Naming and Directory Interface (JNDI) local business interface path name for the enterprise bean that you want to invoke. Use the JNDI name in the global JNDI namespace. The Liberty server then invokes the execute method for the local business interface that the EJB application implements.

    If you set the Send Request API async parameter to 0, the API returns the response length and the return value. You can then directly call the Get Message Data API.

    If you set the Send Request API async parameter to 1, control returns to the client application so you can call the Receive Response Length API.

  3. If you called the Send Request API with the async parameter set to 1, call the Receive Response Length API, BBOA1RCL, setting the async parameter to 0 or 1. The client application uses the response length that is returned by Receive Response Length API to ensure that it has an area large enough to hold the response data.

    If you set the Receive Response Length API async parameter to 0, the API blocks the thread until a response is received.

    If you set the Receive Response Length API async parameter to 1, the API returns immediately regardless of whether it received a response.

  4. Call the Get Message Data API, BBOA1GET, to copy the response data into the client application's buffer.
  5. The client application can continue to send requests and receive message data using the same connection handle until it sends all requests and is ready to release the connection. To release the connection, the application calls the Connection Release API, BBOA1CNR. Connection handles must be released before they can be retained on a Connection Get API call and used again.

Icon that indicates the type of topic Task topic

File name: twlp_dat_connectejbapi.html