+

Search Tips   |   Advanced Search

(ZOS) Use the optimized local adapters native APIs to invoke an EJB application from an external address space

Use this task when we want to use the optimized local adapters native APIs to connect an external address space to CICS Application Server for z/OS and invoke an EJB application that is deployed on the application server.

The WebSphere Application Server daemon group must be active on the same z/OS image that the register request originates from.

When running under Customer Information Control System (CICS), the optimized local adapters task related user exit (TRUE) program must be activated before a connection is made between CICS and WAS. To read about how the TRUE program is activated by the transactions, see the topic, Installing the BBOC, BBO$ and BBO# transactions on the client environment, and the topic, WAS transactions BBOC, BBO$, BBO#. For programs running in z/OS batch and UNIX Systems Services (USS), activating the TRUE program is not required. Ensure that the current address space has already registered and bound to the target WAS daemon group with a call to the Register, BBOA1REG API.

The adapter APIs invoke a stateless session bean is from an external native language program and retrieves the response. This is designed for exploiters wanting more flexibility and where the response area maximum length is not known before-hand.


Tasks

  1. The client address space native language application, such as Cobol, PL/I, C/C++, assembler program, calls the BBOA1CNG Connection Get API and passes the register name it used for the register call. A connection handle is returned that must be used for all future API calls.

  2. The client application gathers its parameters and designates the target service name as the JNDI home interface path name for the enterprise bean that it wants to invoke and calls the BBOA1SRQ Send Request API. This results in a connection to the WAS control region and then to a Workload Manager (WLM)-derived servant region where the passed JNDI home interface executes its create method. The preset method, execute, is located and invoked with the byte array parameters. Control returns immediately back to the caller if the asynchronous parameter is specified and set to 1. When the asynchronous parameter is set to 0 (zero), the API returns the length of the response in the ResponseLength parameter, as well as the return value.
  3. In the WAS servant, the execute method of the target bean invokes business logic. The execute method of a target bean can now invoke the business logic it requires before returning the response data as a serialized byte array back to the native language caller.
  4. A 0 (zero) return code and reason code indicates that the Client API Send_Request was queued successfully. With the asynchronous parameter set to 0 (zero), the response length is provided in the ResponseLength parameter, as well as the return value. With the asynchronous parameter set to 1, the response might not be ready and a call to the BBOA1RCL Receive_RespLen API is required to determine if the response arrived and the length response.

  5. For asynchronous Send_Request calls, the client application calls the BBOA1RCL Receive_RespLen API with either asynchronous 0|1 call. The asynchronous 0 (zero) call indicates that the adapter API must block the thread until a response is received. The asynchronous 1 call indicates that the adapter API returns immediately whether the response has arrived or not.
  6. A 0 (zero) return code and reason code indicate that the Receive_RespLen client API call successfully completed. With the asynchronous parameter set to 1, a ResponseLength and return value of all 0xFFs indicates there is no response received yet on the passed connection. This provides the client application with more control over the way it sends requests and receives responses. The client can group send requests and send them in sequence over a group of connections and then periodically poll these connections for responses. A connection that is processing a Send_Request with the asynchronous 1 call, cannot be passed another Send_Request for the same connection until the related Receive_RespLen and Get_Data API calls are processed.

    Important: Using these APIs asynchronously with the asynchronous parameter set to 1, grouping send requests, and processing them simultaneously, can only be done on connections configured as non-transactional. For example, when using CICS, we want to align a unit of work with an RRS unit of recovery, and a syncpoint under CICS must be propagated to WAS, there can only be a single connection to a specific WebSphere server in the current CICS task. That request receives a warning return code, which indicates that the adapter does not propagate the commit across more than one connection to the same server in the same CICS task.

  7. Client applications use the response length that is returned by Receive_RespLen API to ensure it has an area large enough to hold the response data and uses the BBOA1GET Get Data API call to copy the response data into its buffer.
  8. Client applications repeat this using the same connection handle until it is ready to release the connection. When the connection is released, the BBOA1CNR Connection_Release is called. Connection handles must be released before they can be retained on a Connection Get API call and used again.

The client invoked a stateless session bean from WAS using the optimized local adapter APIs.


Related:

  • Optimized local adapters on WAS for z/OS
  • Optimized local adapters for z/OS APIs
  • Enable optimized local adapters support in CICS
  • Install the WebSphere BBOC, BBO$ and BBO# transactions in CICS
  • WAS transactions BBOC, BBO$, BBO#