Special Topics

Adding a TCP Status Service

The EnsLib.TCP.StatusServiceOpens in a new tab class parses an incoming text string to determine what type of production status information is being requested, and then produces a reply string suitable for writing out to the console screen. A user can interact with the status service directly, or write a command script that contacts the status service, issues commands, and writes the replies to a text file for later analysis.

A developer enables interactions via the status service as follows:

1. Add an instance of EnsLib.TCP.StatusServiceOpens in a new tab to the production.

2. Configure the instance of EnsLib.TCP.StatusServiceOpens in a new tab to accept communications via a particular TCP port. Set a Port number and a list of Allowed IP Addresses from which to accept connections. These are only two of the several settings that are available to configure the TCP text line inbound adapter associated with the status service. For details, see “Reference for Settings.”

Once you have completed these steps, any time the status service is enabled and running, a user or command-line script can initiate a Telnet connection to the configured Port and send commands to the status service. Each command must be a text string that ends with the newline character (ASCII 10). The reply strings will also terminate with a newline.

The following table describes the supported command lines and the contents of the text string returned in each case.

Creating Custom TCP Adapter Classes

To create a custom subclass of a TCP adapter class, do the following in Studio:

1. On the File menu, click New, and then click the General tab.

2. Start the New Class Wizard by clicking InterSystems IRIS Class Definition and clicking OK.

   1. Enter a package and class name and click Next.

      Important:

      Be sure to avoid reserved package names; see “Reserved Package Names” in Developing Productions.

   2. Click Extends for the Class type.

   3. Click Browse next to Name of super class and navigate to the class that you want to subclass.

   4. Click OK.

   5. Click Finish.

   The result is a template class like the following, depending on the class you chose:

   Class MyTest.NewClass1 Extends EnsLib.TCP.InboundAdapter
   {
   
   }

   

3. You can override any property, method, class parameter, or other class member inherited from the class or its parent classes, or you can add new class members. The only requirements are as follows:

   • An inbound adapter class must implement the OnConnected() method.

     In your implementation, use helper methods inherited by your class.

   • An outbound adapter class define methods that create a TCP connection, read or write over the connection, and disconnect.

     To define these methods, use helper methods inherited by your class.

4. Compile the class, which also saves it.

Common Customizations in TCP Adapter Subclasses

The following list suggests some common customizations in TCP adapter subclasses, in addition to implementing the methods that the adapter needs:

• You can define a different value for InitialExpressions for the Terminators property.

  To specify an ASCII character, use the ObjectScript function $CHAR (abbreviated to $C). The following example from EnsLib.TCP.TextLineInboundAdapterOpens in a new tab sets Terminators to the newline character (ASCII 10):

  Property Terminators As %String [ InitialExpression = {$C(10)} ];
  

  

  For more information about functions like $CHAR, see “ObjectScript Functions” in the ObjectScript Reference.

  You can set Terminators to a single character or to a multi-character string. If you supply a string for the Terminators value, InterSystems IRIS uses the string as follows:

  • Any one of the characters in the string serves to terminate the input.

  • The complete string of characters is appended to the output.

• You can add properties and methods.

• You can add and remove settings. See “Adding and Removing Settings” in the article “Programming in InterSystems IRIS” in Developing Productions.

• If you need to require login credentials for the connection, simply add the property name Credentials to the SETTINGS list. The Credentials property is already defined as a %StringOpens in a new tab in the base class Ens.AdapterOpens in a new tab.

• (For inbound adapters) You can also enforce a pool size of 1 by setting the parameter SINGLEPOOLJOB = 1:

  /// Force a single listener job regardless of PoolSize setting
  Parameter SINGLEPOOLJOB = 1;
  

  

  Any subclass of this adapter class or a business service class that uses such an adapter class can use this parameter in its class code to better control the pool size.

• You can implement the OnInit() callback method to perform any special setup actions or initialize any structures.

  For inbound adapters, one of these actions might be to examine settings and initiate a connection between the adapter and the TCP client it will listen to, or to create any object properties that the adapter will use.

  For outbound adapters, one of these actions might be to examine settings and open a socket to a port on the TCP listener.

• For inbound adapters, you can implement the OnConnected() callback method.

  Whenever a connection exists to the configured TCP client, the adapter calls OnConnected() to read a stream from the TCP data source. This read operation is controlled by adapter settings.

  OnConnected() uses helper methods to parse the data.

  Upon successfully reading data, OnConnected() calls the production framework’s ProcessInput() method to pass the received data stream to the associated business service. If this call returns an outbound stream, OnConnected() writes that data as a reply to the TCP client.

  If no data is available to read from the TCP connection during the CallInterval time, OnConnected() returns without doing anything.