Using TCP Adapters with Ensemble
Using the Outbound TCP Adapters
[Back] [Next]
Go to:

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:

Ensemble 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 Ensemble.
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
Ensemble provides the following outbound TCP adapters, all of which are subclasses of EnsLib.TCP.OutboundAdapter:
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 Ensemble Messages in Developing Ensemble Productions.
The following list describes the basic requirements of the 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
  <MapItem MessageType="RequestClass">
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 Ensemble 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 an Ensemble request message class, and ResponseClass is the name of an Ensemble 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
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, Ensemble creates the connection automatically at startup time, from within the OnInit() method. See Reference for Settings.”
Method Disconnect()
Applies to all TCP outbound adapters.
Disconnect() takes down the connection to the TCP listener.
Method SendMessageStream(pRequestStream As %Stream.Object,
  ByRef pResponseStream As %CharacterStream = "%GlobalCharacterStream")
  As %Status
Applies to EnsLib.TCP.CountedOutboundAdapter
SendMessageStream() sends the stream contents as a counted block on the TCP socket.
Method SendMessageString(pRequestString As %String,
                Output pResponseString As %String) As %Status
Applies to EnsLib.TCP.CountedOutboundAdapter and EnsLib.TCP.TextLineOutboundAdapter
SendMessageString() sends the string contents as a counted block on the TCP socket.
Method SendMessageXMLObj(pRequest As %RegisteredObject,
                Output pResponse As %RegisteredObject) As %Status
Applies to EnsLib.TCP.CountedXMLOutboundAdapter
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 Ensemble object. For details on Get Reply, see Reference for Settings.”
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=
  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 an Ensemble production, use the Management Portal to do the following:
  1. Add an instance of your business operation class to the Ensemble production.
  2. Configure the business operation. For information on the settings, see Reference for Settings.”
  3. Enable the business operation.
  4. Run the production.