+

Search Tips   |   Advanced Search

(zos)

Use the outbound APIs with the external address space or subsystem

Use this task to create an interaction between the outbound APIs and the external address space or subsystem.

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 WAS on z/OS application.

  1. 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. We 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 the 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 the 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 used to obtain our connection must have the RegisterName custom property set to participate in a global transaction.

  2. Create an interaction using the connection object, for example:

      Interaction int = con.createInteraction();

  3. Create an InteractionSpecImpl object and set the service name into the interaction spec. The service name describes the name of the method or function 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");

    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.

  4. Run the interaction using the created interaction spec, for example:

      int.execute(isi, null);

  5. If the application used an RMLT, commit or back out the work after you are finished with the 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.

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.

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 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 specified by the OTSTIMEOUT parameter, the CICS task 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 the 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;
   }


Related concepts

  • Calling existing IMS transactions with optimized local adapters over OTMA
  • Optimized local adapters for z/OS APIs
  • Optimized local adapters on WebSphere Application Server for z/OS


    Related tasks

  • Plan to use optimized local adapters for z/OS
  • Enable the server environment to use optimized local adapters
  • Enable optimized local adapters support in CICS
  • Use the optimized local adapters native APIs to invoke an EJB application from an external address space
  • Use the Invoke API to call an enterprise bean from an external address space
  • Calling an enterprise bean from an external address space within a client-initiated transaction
  • Calling an enterprise bean from an external address space while ignoring the client transaction context