Product Overview

This document outlines the architecture of S7RClientSS library (Java) which is a class providing service connectivity to TIBCO Substation ES™ TCP interface. The following are two types of Substation ES™ services that are implemented.

Recipes

Recipes are a service type for Java applications or TIBCO ActiveMatrix BusinessWorks 6.x processes to initiate an exchange of data between the open systems environment and a CICS or IMS application (through Substation ES™). The initiator for a recipe resides in the Open System side with Substation ES and its back-end application being the “server”. Recipe Services used by application are registered by Substation ES.

Triggers

Triggers are a service type for Java applications or ActiveMatrix BusinessWorks 6.x processes allowing asynchronous data processing from z/OS programs (via Substation ES). The initiator is a back-end business application sending data via Substation ES. No response payload is allowed for a trigger except for an Ack or Nack indication.

A Java Application or ActiveMatrix BusinessWorks 6.x process can register for only one service Id.

More than one Java application or ActiveMatrix BusinessWorks 6.x process can register for the same service Id which allows for scalability (both on the same or different machines). Each instance of a service establishes a "connection" to Substation ES and registers its service type and name.

For trigger services that register to the same service Id, Substation ES will "round robin" the trigger messages across registrations. It does not behave the same way as a fan-out, as a single message is currently only sent to one of the registrations.

The connection is authorized by SAF via a call from TIBCO Substation ES using an SAF user-id and password provided by the client in the "connect" protocol. The service Id is verified by the TIBCO Substation ES instance against the Configuration File. If a match for the service Id is not found in the configuration file (match is case sensitive), then the registration is rejected. The configuration file definition for the recipe indicates the back-end system that will handle a message and the way the message is to be delivered (i.e., DFHCOMMAREA, container, start transaction, and so on). No mapping or conversion will be done on the request or response payload message even though they are specified in the configuration file definition. They are Opaque objects.

The conversion rules for input and output in the recipe are ignored.

The size of the input data object is determined by the message data. For commArea processing where the business output data is larger than the input data, the input message data must equal the maximum commArea size needed not exceeding 32000 bytes. The handling of messages for a connection is serial. For each connection, the Substation ES flow is:
  • Substation ES Loop
    1. Receive a message from the Java client
    2. Send the message to the back-end system (CICS, IMS, and so on)
    3. Wait for BES response
    4. Send response message back to Java client

To handle more than one message concurrently, you must create additional instances of your application or have additional threads in your application (each with their own connection token). The input source for a request message created by the application can be input from different source types, such as HTTP, JMS, RV, file, SOAP, REST, and so on. The same is true for the output data. The Java application will receive a response message from Substation in an OPAQUE format (bytes array). The message will arrive in the character set determined by the back-end application.

Trigger Services are registered by Substation ES. The connection is authorized by Substation ES via SAF user-id and password. The service Id is verified by the Substation ES TCP interface. If a match for the service Id is not found in the configuration file (match is case sensitive), then the registration is rejected. The configuration file definition for the trigger indicates how back-end system trigger messages are handled. The trigger message created by the back-end system must contain the service Id to be used. Only one trigger definition will be used per trigger message. No mapping or converse will be done on the Trigger request. They are Opaque objects. The conversion rules for output in the trigger definition are ignored. The message sent via TCP is an exact copy of the trigger message in the code page the back-end application created. The handling of messages on a trigger connection is asynchronous. For each trigger connection the Substation ES flow is:
  • Substation ES Loop
    1. Substation ES gets a trigger message from any back-end system
    2. Determine the Trigger message Service Id and which TCP connections support the service. If none found: a "Reliable" trigger message is discarded; a "Guaranteed" trigger message is returned to the BES as not delivered.
      1. If active trigger definition found
      2. Substation ES determines which TCP connection to use
      3. Send message to TCP Connection (Java and ActiveMatrix BusinessWorks application)
      4. If "Guaranteed" message - wait for "ack" or "nack"
        1. Return appropriate status to BES (ack, nack, timeout, and so on)
      5. If "Reliable" message - then done.
    3. Java Loop
      1. Wait on message
      2. Get data as byte array or string type
      3. Analyze data and process data (you could spawn this)
      4. If message requires "ack" or "nack"
        1. Issue appropriate "ack" or "nack" method
      5. Loop back to step a. and wait for the next message.

Substation ES has many TCP worker threads. They are NOT dedicated to one Service connect, but are shared among all the recipe and trigger events.

To handle more than one message concurrently, you must create more instances of your Java application. The output destination for your Java application is up to your application. It can be HTTP, JMS, RV, file, SOAP, REST, etc.

Note: Substation ES TCP Interface uses socket processing, which is a buffered method. It is the Java application's responsibility to make sure it can keep up with the messages being sent to it. If the connection rejects the message due to "out of memory" condition, then Substation ES will handle the trigger message based on its type (Reliable triggers are thrown away - Guaranteed are re-queued for later handling)