Using the Inbound TCP Adapters
This page describes how to use each of the TCP inbound adapters (EnsLib.TCP.CountedInboundAdapterOpens in a new tab, EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab, and EnsLib.TCP.TextLineInboundAdapterOpens in a new tab).
Overall Behavior
Each TCP inbound adapter checks for data on a specified port, reads the input, and sends the input as a stream to the associated business service. The business service, which you create and configure, uses this stream and communicates with the rest of the production. The following figure shows the overall flow:
In more detail:
-
Each time the adapter encounters input from its configured data source, it calls the internal ProcessInput() method of the business service class, passing the stream as an input argument.
-
The internal ProcessInput() method of the business service class executes. This method performs basic production tasks such as maintaining internal information as needed by all business services. You do not customize or override this method, which your business service class inherits.
-
The ProcessInput() method then calls your custom OnProcessInput() method, passing the input object. The requirements for this method are described later in this page.
The response message follows the same path, in reverse.
Creating a Business Service to Use a TCP Inbound Adapter
To use any of the TCP adapters in your production, create a new business service class as described here. 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 service class:
-
Your business service class should extend Ens.BusinessServiceOpens in a new tab.
-
In your class, the ADAPTER parameter should equal EnsLib.TCP.CountedInboundAdapterOpens in a new tab, EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab, or EnsLib.TCP.TextLineInboundAdapterOpens in a new tab.
-
Your class must implement the OnProcessInput() method, as described in “Implementing the OnProcessInput Method.”
-
Your class can implement the OnConnect() callback method. This method is called after the OnTask() method, each time the TCP inbound adapter establishes a new connection to or from a remote system.
If you implement this method, it must have the following signature:
Method OnConnect(pTimeout As %Numeric) As %Status
Implement OnConnect() 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 inbound adapter. It takes its value from the Read Timeout adapter setting. For details about Read Timeout, see “Reference for Settings.”
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 Service Class” in Developing Productions.
-
Your class can implement the OnInit() method to perform any special setup actions. This method is called from the %OnNew() method. If the Job Per Connection setting is set to true, then OnInit() is called from %OnNew() each time the listener spawns a new job to accept a connection.
-
Your class can implement the OnTearDown() method to perform any special tear down actions. This method is called from the %OnClose() method. Specifically, %OnClose() calls the OnTearDown() method of the adapter and then calls the OnTearDown() method of the business service. If the Job Per Connection setting is set to true, then OnTearDown() is called just before each connection job is closed.
Important:
If your new business service class includes custom code in the OnTearDown() method, the custom code must invoke the OnTearDown() method of the superclass to enable the proper functioning of the business service, for example:
//Sets a node of the ^%zexample global to the ID of the current process
// and invokes the OnTearDown() method of the superclass
Method OnTearDown() As %Status
{
set ^%zexample($i(^%zexample),"onteardown")=$j
Return ##super()
}
You must also implement Try/Catch logic as appropriate to handle errors. For information about invoking a superclass method, see ##superclass Syntax.
Example for EnsLib.TCP.TextLineInboundAdapter
The following is an example of a business service class that uses EnsLib.TCP.TextLineInboundAdapterOpens in a new tab.
Class TestTCPTextLine.AuthorizationTCPService Extends Ens.BusinessService
{
/// Name of the adapter class
Parameter ADAPTER = "EnsLib.TCP.TextLineInboundAdapter";
Method OnProcessInput(pInput As Ens.StringContainer,
pOutput As Ens.StringContainer) As %Status
{
set $ZT = "EXCEPTION"
set st = $$$OK
do {
if ('$isobject($get(pInput))) { quit }
// Input must have the following format: 'PatientCode:ProcedureCode'
set tSubject = pInput.StringValue
$$$TRACE("received line "_tSubject)
set req = ##class(TestTCPTextLine.AuthorizationRequest).%New()
set req.PatientCode = $piece(tSubject,":",1)
set req.ProcedureCode = $piece(tSubject,":",2)
set st = ..SendRequestSync("AuthorizationProcess", req, .resp)
quit:$$$ISERR(st)
set pOutput=
##class(Ens.StringContainer).%New(resp.AuthorizationFlag_
":"_resp.AuthorizationCode)
} while (0)
EXIT
//do ..Adapter.Disconnect()
quit st
EXCEPTION
set $ZT = ""
set st = $$$EnsSystemError
goto EXIT
}
}
Adding and Configuring the Business Service
To add your business service to a production, use the Management Portal to do the following:
-
Add an instance of your business service class to the production.
-
Configure the business service. For information on the settings, see “Reference for Settings.”
When you configure the business service, you specify a value for the Allowed IP Addresses settings, along other settings. Note that Allowed IP Addresses provides a way to enable the adapter to initiate the connection.
-
Enable the business service.
-
Run the production.
