Skip to main content

Using the Outbound TCP Adapters

This page describes how to use the primary TCP outbound adapters (EnsLib.TCP.CountedOutboundAdapterOpens in a new tab, EnsLib.TCP.CountedXMLOutboundAdapterOpens in a new tab, and EnsLib.TCP.TextLineOutboundAdapterOpens in a new tab).

Overview of Outbound TCP Adapter

InterSystems IRIS provides the following outbound TCP adapters, all of which are subclasses of EnsLib.TCP.OutboundAdapterOpens in a new tab:

  • EnsLib.TCP.CountedOutboundAdapterOpens in a new tab 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.CountedXMLOutboundAdapterOpens in a new tab sends XML exported objects out as a counted block of bytes over a TCP connection and imports a response object.

  • EnsLib.TCP.TextLineOutboundAdapterOpens in a new tab 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.

The following list describes the basic requirements of the business operation class:

  • Your business operation class should extend Ens.BusinessOperationOpens in a new tab.

  • In your class, the ADAPTER parameter should equal EnsLib.TCP.CountedOutboundAdapterOpens in a new tab, EnsLib.TCP.CountedXMLOutboundAdapterOpens in a new tab, or EnsLib.TCP.TextLineOutboundAdapterOpens in a new tab.

  • 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.

    For information on defining the message handler methods, see Creating Message Handler Methods.

  • 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.

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>
}
}

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()
    

    See Calling Adapter Methods from the Business Operation.

  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 %NumericOpens in a new tab 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

Applies to EnsLib.TCP.CountedOutboundAdapterOpens in a new tab

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

Applies to EnsLib.TCP.CountedOutboundAdapterOpens in a new tab and EnsLib.TCP.TextLineOutboundAdapterOpens in a new tab

SendMessageString() sends the string contents as a counted block on the TCP socket.

SendMessageXMLObj()
Method SendMessageXMLObj(pRequest As %RegisteredObject,
                 Output pResponse As %RegisteredObject,
                 pResponseClassname As %String) As %Status

Applies to EnsLib.TCP.CountedXMLOutboundAdapterOpens in a new tab

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.”

The pResponseClassname parameter is optional and requires the response object class definition to have a parameter called RESPONSECLASSNAME that equals a class name. The response class name is used to correlate the response data. It needs to be a persistent class that extends %XML.AdaptorOpens in a new tab.

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.CountedOutboundAdapterOpens in a new tab.

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.

Related Options

EnsLib.TCP contains additional TCP outbound adapters such as EnsLib.TCP.FramedOutboundAdapterOpens in a new tab. See the class reference for details.

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.

You can develop a new inbound adapter class based on the EnsLib.TCP.OutboundAdapterOpens in a new tab or any of its subclasses. See Creating Custom TCP Adapter Classes.

FeedbackOpens in a new tab