Use this task when you 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 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.