Use
this task when you want to use the optimized local
adapters native APIs to connect an external address space to WebSphere® Application
Server for z/OS® and invoke an Enterprise JavaBeans® (EJB)
application that is deployed on the application server.
Before you begin
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 WebSphere Application Server. 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, WebSphere Application Server 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 WebSphere Application Server
daemon group with a call to the Register, BBOA1REG API.
About this task
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.
Procedure
- 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.
- The client application gathers
its parameters and designates
the target service name as the Java® Naming
and Directory Interface (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 WebSphere Application Server
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.
- In the WebSphere Application Server 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.
- 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.
- 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.
- 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 that are configured as non-transactional. For
example, when using CICS, you want to align a unit of work with an
RRS unit of recovery, and a syncpoint under CICS must be propagated
to WebSphere Application Server, 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.
- 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.
- 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.
Results
The client
invoked a stateless session bean from WebSphere Application Server using the optimized
local adapter APIs.