Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.3 / System Interoperability / Using TCP Adapters in Productions / Using the Outbound TCP Adapters
Previous section   Next section

Using the Outbound TCP Adapters

This chapter describes how to use each of the TCP outbound adapters (EnsLib.TCP.CountedOutboundAdapter, EnsLib.TCP.CountedXMLOutboundAdapter, and EnsLib.TCP.TextLineOutboundAdapter). It contains the following sections:
Tip:
InterSystems IRIS™ also provides specialized business service classes that use TCP adapters, and one of those might be suitable for your needs. If so, no programming would be needed. See “Connectivity Options” in Introducing Interoperability Productions.
Also, you can develop a new outbound adapter class based on the EnsLib.TCP.OutboundAdapter or any of its subclasses. See the section “Creating Custom TCP Adapter Classes,” later in this book.

Overview of Outbound TCP Adapter

InterSystems IRIS provides the following outbound TCP adapters, all of which are subclasses of EnsLib.TCP.OutboundAdapter:
  • EnsLib.TCP.CountedOutboundAdapter contains methods to read or write blocks of data across the TCP connection. InterSystems IRIS acts as a TCP client exchanging blocks of data with a TCP listener. The block length specified in the first 4 bytes of the block. This convention allows a business operation to send requests to an external TCP server for fulfillment.
  • EnsLib.TCP.CountedXMLOutboundAdapter sends XML exported objects out as a counted block of bytes over a TCP connection and imports a response object.
  • EnsLib.TCP.TextLineOutboundAdapter contains methods to read or write text strings across a TCP connection. InterSystems IRIS acts as a TCP client exchanging blocks of data with a TCP listener. The default terminator for the text strings is the newline character (ASCII 10).

Overall Behavior

Within a production, an outbound adapter is associated with a business operation that you create and configure. The business operation receives a message from within the production, looks up the message type, and executes the appropriate method. This method usually executes methods of the associated adapter.

Creating a Business Operation to Use a TCP Outbound Adapter

To create a business operation to use a TCP outbound adapter, you create a new business operation class. Later, add it to your production and configure it.
You must also create appropriate message classes, if none yet exist. See “Defining Messages” in Developing Productions.
The following list describes the basic requirements of the business operation class:
  • Your business operation class should extend Ens.BusinessOperation.
  • In your class, the INVOCATION parameter should specify the invocation style you want to use, which must be one of the following.
    • Queue means the message is created within one background job and placed on a queue, at which time the original job is released. Later, when the message is processed, a different background job is allocated for the task. This is the most common setting.
    • InProc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be released to the sender’s pool until the message is delivered to the target. This is only suitable for special cases.
  • Your class must define a message map that includes at least one entry. A message map is an XData block entry that has the following structure:
    XData MessageMap
    {
    <MapItems>
      <MapItem MessageType="messageclass">
        <Method>methodname</Method>
      </MapItem>
      ...
    </MapItems>
    }
    
    
  • Your class should define all the methods named in the message map. These methods are known as message handlers. Each message handler should have the following signature:
    Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
    
    Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class. In general, the method code will refer to properties and methods of the Adapter property of your business operation.
    For information on defining message classes, see “Defining Messages” in Developing Productions.
    For information on defining the message handler methods, see “Creating Message Handler Methods,” later in this chapter.
  • Your class can implement the OnConnect() callback method. This method is called each time the TCP outbound adapter establishes a new connection to or from a remote system.
    If you implement OnConnect() method, it must have the following signature:
    Method OnConnect(pTimeout As %Numeric) As %Status
    
    Implement this method if you need to take some action each time a new connection is established, for example to send a logon sequence or a handshake token. The timeout argument is automatically provided by the TCP outbound adapter. It takes its value from the ConnectTimeout adapter setting. For details, see “Settings for the TCP Outbound Adapters.”
    If OnConnect() returns an error status, the new connection fails and the adapter is disconnected. If an untrapped exception occurs within OnConnect(), the adapter catches it and continues as if OnConnect() were not implemented.
  • For other options and general information, see “Defining a Business Operation Class” in Developing Productions.
The following example shows the general structure that you need:
Class ETCP.NewOperation1 Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.TCP.CountedOutboundAdapter";

Parameter INVOCATION = "Queue";

Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
{
  Quit $$$ERROR($$$NotImplemented)
}

XData MessageMap
{
<MapItems>
  <MapItem MessageType="RequestClass">
    <Method>Sample</Method>
  </MapItem>
</MapItems>
}
}
Note:
Studio provides a wizard that you can use to create a business operation stub similar to the preceding. To access this wizard, click File —> New and then click the Production tab. Then click Business Operation and click OK.

Creating Message Handler Methods

When you create a business operation class for use with a TCP outbound adapter, typically your biggest task is writing message handlers for use with this adapter, that is, methods that receive production messages and then write files.
Each message handler method should have the following signature:
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class.
In general, the method should do the following:
  1. Examine the inbound request message.
  2. Using the information from the inbound request, call a method of the Adapter property of your business operation. For example, the following line invokes the Connect() method:
     set sc=..Adapter.Connect()
    
  3. Make sure that you set the output argument (pOutput). Typically you set this equal to the response message. This step is required.
  4. Return an appropriate status. This step is required.

Calling Adapter Methods from the Business Operation

Connect()
Method Connect(pTimeout As %Numeric) As %Status
Applies to all TCP outbound adapters.
Connect() opens a TCP socket to a port on the TCP listener machine. Connect() has one input argument, a %Numeric value that identifies the number of seconds to wait for the connection attempt to succeed. A typical call to the Connect() method gives this input argument the value of the configurable ConnectTimeout property.
If the Stay Connected adapter setting is set to –1, InterSystems IRIS creates the connection automatically at startup time, from within the OnInit() method. See “Reference for Settings.”
Disconnect()
Method Disconnect()
Applies to all TCP outbound adapters.
Disconnect() takes down the connection to the TCP listener.
SendMessageStream()
Method SendMessageStream(pRequestStream As %Stream.Object,
  ByRef pResponseStream As %CharacterStream = "%GlobalCharacterStream")
  As %Status
SendMessageStream() sends the stream contents as a counted block on the TCP socket.
SendMessageString()
Method SendMessageString(pRequestString As %String,
                Output pResponseString As %String) As %Status
SendMessageString() sends the string contents as a counted block on the TCP socket.
SendMessageXMLObj()
Method SendMessageXMLObj(pRequest As %RegisteredObject,
                Output pResponse As %RegisteredObject) As %Status
SendMessageXMLObj() sends the request object to the TCP listener as a counted XML block. If the Get Reply adapter setting is True, SendMessageXMLObj() also gets a reply from the TCP listener as a counted XML block, which it imports as an InterSystems IRIS object. For details on Get Reply, see “Reference for Settings.”
TestConnection()
Method TestConnection()
Applies to all TCP outbound adapters.
TestConnection() corrects the properties reflecting the connection state. If the adapter is connected, TestConnection() returns True. If not, TestConnection() calls Disconnect() and returns False.

Example for EnsLib.TCP.CountedOutboundAdapter

The following is an example of a business operation class that references the EnsLib.TCP.CountedOutboundAdapter.
Class Test.GeneralTCPOperation Extends Ens.BusinessOperation
{
 Parameter ADAPTER = "EnsLib.TCP.CountedOutboundAdapter";
 Parameter MAXREAD=30000;

 Method OnMessage(pReq As Test.GeneralSendRequest,
                 Output pResponse As Test.GeneralSendResponse) As %Status
 {
  Set str=
    pReq.Hr_pReq.DataLth_pReq.BID_pReq.Hr2_pReq.HrVacant_pReq.Cat_pReq.Hr3_pReq.Hr4
  Set tTextStream= ##class(%GlobalCharacterStream).%New()
  Set tSC=tTextStream.Write(str)
  Do pReq.Body2.Read(32) // Throw it away
  Set len=..#MAXREAD
  Set token= pReq.Body2.Read(.len)
  Set i=0
  While(len>0) {
     Set i=i+1
     Do tTextStream.Write(token)
     Set len=..#MAXREAD
     Set token= pReq.Body2.Read(.len)
  }
  Set tSC=
  ..Adapter.SendMessageStream(tTextStream,.tStreamReply) Quit:$$$ISERR(tSC) tSC
  Set pResponse=##class(Test.GeneralSendResponse).%New()
  Do tStreamReply.Rewind()
  Set pResponse.Body = tStreamReply.Read(,.tSC)
  Quit tSC
 }
}

Adding and Configuring the Business Operation

To add your business operation to a production, use the Management Portal to do the following:
  1. Add an instance of your business operation class to the production.
  2. Configure the business operation. For information on the settings, see “Reference for Settings.”
  3. Enable the business operation.
  4. Run the production.
Previous section   Next section