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 Enterprise
Edition (Java EE) 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 about how to change the LocalTransaction
setting on an application deployment descriptor, see the topic, Configuring
transactional deployment attributes.
If your Java EE 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 Java EE application
component ends.
If your Java EE
application component is starting 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 Java EE 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 start inside CICS, for example:
InteractionSpecImpl isi = new InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
Attention: When
you use optimized local adapters over OTMA, the service name is not
defined and the target IMS™ transaction
is specified in the message stream. The service name can be set, but
it is not used for optimized local adapters 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 sync point during the RMLT or global transaction, the server task
issues a BBOX abend during the sync point. This causes the sync point
to fail and an ASPx abend is generated by CICS. The CICS application
should wait for WebSphere Application
Server to issue the sync point operation by calling the commit or
rollback method on the LocalTransaction object, or by letting the Java EE application component 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
about how to code the OTSTIMEOUT parameter on the transaction definition,
see the CICS Transaction Server
for z/OS Resource Definition
Guide.
If your Java EE
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 Java EE 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 start 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 start 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;
}