Use this task to create an interaction between the outbound
APIs and the external address space or subsystem.
Before you begin
Establish a connection with an external address space or subsystem
as described in the topic, Using the optimized local adapters to call
an external address space or subsystem from a WebSphere® Application Server on z/OS® application.
Procedure
- (Optional) Start a resource manager
local transaction (RMLT) if you are using a Customer Information Control
System (CICS®) server task that
supports transactions. To use a CICS server task that supports transactions,
the keyword TXN=Y is used when starting the server task. You can start
an RMLT to encapsulate several interactions in a single unit of work.
Your Java 2 Enterprise Edition
(J2EE) application component must not be running on a global transaction
and must have a LocalTransaction boundary set to Application in its
application deployment descriptor. The following example shows how
to start the local transaction using the LocalTransaction object,
after the deployment descriptor has been changed:
LocalTransaction lt = con.getLocalTransaction();
lt.begin();
For more information on how to change the LocalTransaction
setting on an application deployment descriptor, see the topic, Configuring
transactional deployment attributes.
If your J2EE
application component is configured to use the LocalTransaction boundary,ContainerAtBoundary,
the connection is automatically enlisted in an RMLT when the connection
is obtained. The work that is done when using that connection is automatically
completed when the J2EE application component ends.
If your
J2EE application component is executing in a global transaction, the
connector is automatically enlisted in the global transaction when
the connection is obtained. The work done when using that connection
is automatically completed when the J2EE application component ends.
The ConnectionFactory object that is used to obtain your connection
must have the RegisterName custom property set to participate in a
global transaction.
- Create an interaction using the connection object, for
example:
Interaction int = con.createInteraction();
- Create an InteractionSpecImpl object and set the service
name into the interaction spec. The service name describes
the name of the method or function that you want to call on the remote
system. The service name was provided when the remote system called
the host or one of the Receive Request APIs, or when using the Customer
Information Control System (CICS)
server task is the program name to execute inside CICS, for example:
InteractionSpecImpl isi = new InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
When
using optimized local adapters over OTMA, the service name is not
defined and the target IMS transaction is specified in the message
stream. It can be set, but it is not used for optimized local adapter
calls over OTMA. For more information, see the topic Calling existing
IMS transactions with optimized local adapters over OTMA.
- Run the interaction using the created interaction spec,
for example:
int.execute(isi, null);
- If your application used an RMLT,
commit or back out the work after you are finished with your last
interaction. Use the commit or rollback methods on the
LocalTransaction object, for example:
lt.commit();
Results
The interaction with the external address space or subsystem
is complete.
Attention: When using
an RMLT or global transaction, if the CICS application
issues a syncpoint during the during the RMLT or global transaction,
the server task issues a BBOX abend during the syncpoint. This causes
the syncpoint to fail and an ASPx abend is generated by CICS. The CICS application
should wait for WebSphere Application
Server to issue the syncpoint operation by calling the commit or rollback
method on the LocalTransaction object, or by allowing the J2EE application
component to finish.
Attention: If
you want to define the maximum time that a CICS transaction can run when a global transaction
context or RMLT is imported into CICS from WebSphere, modify the OTSTIMEOUT
parameter value on the transaction definition that is used to start
the CICS link server link task.
By default, the transaction name is BBO#. If the CICS transaction run time exceeds the time that
is specified by the OTSTIMEOUT parameter, the CICS task that is running the CICS transaction abends, causing the entire
global transaction or RMLT to roll back. For information on how to
code the OTSTIMEOUT parameter on the transaction definition, see the CICS Transaction Server for z/OS Resource Definition Guide.
If your J2EE application component is participating
in an RMLT or global transaction, and the application is communicating
with a batch program or a CICS link
server started with keyword TXN=N, the optimized local adapter connection
is not able to establish a connection to the target program. The
target program is not able to provide the transaction capabilities
required by the J2EE application. An exception displays with minor
code 0xC9C24C3B. This code indicates that the target registration
name is found but is not enabled for transactions. Only CICS link servers enabled with keyword TXN=Y
can support propagating transactions from WebSphere Application Server for z/OS.
Example
The following method shows how to invoke an interaction with
input and output data as a byte array (byte[]):
public byte[] driveInteraction(javax.resource.cci.ConnectionFactory cf,
javax.resource.cci.Connection con,byte[] inputDataBytes),throws javax.resource.ResourceException
{
// Create an interaction using the optimized local adapter connection
javax.resource.cci.Interaction i = con.createInteraction();
// The InteractionSpec describes the service we want to call
com.ibm.websphere.ola.InteractionSpecImpl isi = new com.ibm.websphere.ola.InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
// The input data is specified using an IndexedRecord. The first
// slot in the indexed record contains the input data bytes.
javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
javax.resource.cci.IndexedRecord ir = rf.createIndexedRecord(null);
ir.add(inputDataBytes);
// The interaction returns another IndexedRecord, whose first
// slot contains the output data bytes.
javax.resource.cci.Record or = i.execute(isi, ir);
byte[] outputDataBytes = null;
if (or != null)
{
outputDataBytes = (byte[])((javax.resource.cci.IndexedRecord)or).get(0);
}
// Return the output data to the caller
return outputDataBytes;
}
The following method shows how to invoke an interaction
using a Rational
® Application
Developer generated copybook Record object:
/**
* An example of driving an optimized local adapter interaction, using a Rational Application Developer copybook mapping
* class as input (inputRecord) and receiving a Rational Application Developer copybook mapping as
* output.
*/
public javax.resource.cci.Record driveInteraction(
javax.resource.cci.Connection con,
javax.resource.cci.Record inputRecord)
throws javax.resource.ResourceException
{
// Create an interaction using the OLA connection
javax.resource.cci.Interaction i = con.createInteraction();
// The InteractionSpec describes the service we want to call com.ibm.websphere.ola.InteractionSpecImpl isi =
new com.ibm.websphere.ola.InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
// The Rational Application Developer generated copybook implements
// javax.resource.cci.Record and can be passed directly to the interaction.
// The interaction returns an IndexedRecord, whose first slot contains
// the output data bytes.
javax.resource.cci.Record or = i.execute(isi, inputRecord);
javax.resource.cci.Record outputRecord = null;
if (or != null)
{
// In this example, RADGeneratedOutputType is the name of the Rational Application Developer
// generated copybook mapping class.
outputRecord = new RADGeneratedOutputType();
// The output bytes are stored in the output record returned on the
// interaction, which is an IndexedRecord.
byte[] outputDataBytes =
(byte[])((javax.resource.cci.IndexedRecord)or).get(0);
// To convert the output bytes to another Rational Application Developer generated copybook,
// call the setBytes(byte[]) method of that class. The class will
// implement the com.ibm.etools.marshall.RecordBytes interface.
((com.ibm.etools.marshall.RecordBytes)outputRecord)
.setBytes(outputDataBytes);
}
// Return the output data to the caller
return outputRecord;
}