Using Socket Devices
Chapter 9. Input/Output Processing

From an application perspective, the transport layers used by a socket device are stream-oriented, with no provisions for implicit application messages. Therefore, the following are two common protocols used to segment application messages.

The SOCKET device provides a facility for recognizing delimiters because parsing messages for delimiters is cumbersome.

TCP/IP is a stream-based protocol that guarantees that bytes arrive in the order in which they were sent. However, it does not guarantee that they will be grouped in the same packets.

If packets arrive infrequently, or at varying rates that are sometimes slow, a short interval can waste CPU cycles checking for an unlikely event. On the other hand, if the handling of packets is time critical, a long interval can introduce an undesirable latency. If packets arrive in a rapid and constant flow (an unusual situation), the interval doesn't matter as much, as there is always something in the buffer for the READ to work with. If you do not specify MOREREADTIME, SOCKET READ implements a dynamic approach of using a longer first interval of 200 ms when it finds no data, then shortening the interval to 10 ms when data starts to arrive. If you specify an interval, the SOCKET device always uses the specified interval and does not adjust dynamically. For more information on MOREREADTIME, refer to “MOREREADTIME”.

Most SOCKET READ operations terminate as a result of the first condition detected from (a) receipt of delimiters, (b) receipt of the maximum number of characters, or (c) expiration of a timeout. Note that all of these conditions are optional, and a specific READ may specify zero or more of them. This section refers to these three conditions as "defined terminating conditions". If a SOCKET READ is not subject to any of the defined terminating conditions, it terminates after it has received at least one character followed by an interval with no new characters. An error can also terminate a READ. While none of the terminating conditions is satisfied, the READ continues.

The following flowchart represents the logic of a SOCKET READ.

A SOCKET READ operation terminates if any of the following conditions are met:

* denotes Defined Terminating Conditions

A non-fixed-length read, with no timeout and no delimiters (the sixth row in the above table) requires a complex implementation of sequence of READs to ensure a predictable result. This is because the transport layer stream fragments delivered to the reader has only accidental correspondence with the operations performed by the writer. For example, the following:

Write "Message 1","Message 2" is presented to the reader as the stream "Message1Message2" but it can take from one (1) to 18 READ commands to retrieve the entire stream.

Messaging protocol should implement READ in any of the following ways:

Each device can have from zero (0) to 64 delimiters associated with it. Each delimiter can be from one (1) to 64 characters. All the delimiters declared for a device are valid for any READ from any associated socket, which means, any of the defined delimiters terminate the READ. The actual terminating delimiter is available in $KEY. A WRITE to a socket associated with a device with one or more delimiters inserts the first of the delimiters for any WRITE ! format.

The READ command may be used to obtain data from a socket. A READ operation terminates if any of the following are detected, in the order specified below:

A non-fixed-length read, with no timeout and no delimiters requires a complex implementation of sequence of READs to ensure a predictable result. This is because the transport layer stream fragments delivered to the reader has only accidental correspondence with the operations performed by the writer. For example, the following

Write "Message 1","Message 2"

is presented to the reader as the stream "Message1Message2" but it can take from one (1) to 18 READ commands to retrieve the entire stream.

The WRITE command sends data to a socket.

The WRITE command for SOCKET devices accepts the following controlmnemonics:

/L[ISTEN][(numexpr)]

where numexpr is in the range 1-5 and specifies the listen queue depth for a listening socket. By default, an OPEN or USE with LISTEN immediately sets the listen queue size to 1.

/W[AIT][(timeout)]

where timeout is a "numexpr" that specifies how long in seconds a server waits for a connection or data to become available on one of the sockets in the current Socket Device.

"WRITE !" inserts the character(s) of the first I/O delimiter (if any) to the sending buffer. If "ZFF=expr" has been specified, "WRITE #" inserts the characters of expr . Otherwise WRITE # has no effect. WRITE ! and WRITE # always maintain $X and $Y in a fashion that emulates a terminal cursor position except when the device is OPENed with a UTF CHSET because the units for $X and $Y for terminals are in display columns while for sockets they are in codepoints.

Each socket may be in one of the following states:Each socket may be in one of the following states (observable through $KEY):

A listening socket used for accepting new connections goes through these three states in one step with a single OPEN or USE. When a server does a WRITE /WAIT, a client can establish a connection which creates a new server socket. $KEY includes information about this new socket in the form of CONNECT|handle|<address> where <address> is the IP address for TCP sockets and path for LOCAL sockets.

Each socket may have one or more sockets waiting for either an incoming connection or data available to READ (observable through $ZKEY). $ZKEY contains semi-colon (";") separated list of entries detailing any waiting sockets for a current SOCKET device.

For more information on $KEY and $ZKEY, refer to Chapter 8: “Intrinsic Special Variables”.

The following table provides a brief summary of deviceparameters for socket devices. For more information, refer to “Open”, “Use”, and “Close”.

sockexamplemulti3.m demonstrates a use of $KEY and $ZKEY in a basic socket I/O setup. It launches two jobs: a server process which opens a listening socket and a client process which makes five connections to the server. The server sends a message to each connection socket. Even-numbered client sockets read the message partially but do not send a response back to the server. Odd-numbered client sockets receive the full message and respond to the server with the message "Ok.". The server reads two characters (but the client sends three) and $ZKEY shows sockets with unread characters.Please click to download the sockexamplemulti3.m program and follow instructions in the comments near the top of the program file. You can also download sockexamplemulti3.m from http://tinco.pair.com/bhaskar/gtm/doc/books/pg/UNIX_manual/sockexamplemulti3.m.

You can start a GT.M process in response to a connection request made using inetd/xinetd. The following example uses inetd/xinetd to implement a listener which responds to connections and messages just as the prior example.

In the configuration file for xinetd, define a new service called gtmserver. Set socket_type to "stream" and wait should be "no" as in the following snippet:

service gtmserver 
{ 
disable = no 
type = UNLISTED 
port = 7777 
socket_type = stream 
wait = no 
user = gtmuser 
server = /path/to/startgtm 
} 

If you define the server in /etc/services, the type and port options are not needed. For more information, the xinetd.conf man page for more details.

If you are using inetd, a line should be added to /etc/inetd.conf with the sockettype "stream", protocol "tcp", and the "nowait" flag should be specified as in the example below, which assumes a gtmserver service is defined in /etc/services:

gtmserver stream tcp nowait gtmuser /path/to/startgtm 

In both of the above examples, "gtmuser" is the name of the user the service gtmserver should be run as, and "/path/to/startgtm" is the name of a script which defines some environment variables needed by GT.M before starting it. Please check the man page for inetd.conf on your system since the details may be slightly different.

The minimum variables are $gtm_dist which should specify the directory containing the GT.M distribution and $gtmroutines. As an example:

#!/bin/bash 
cd /path/to/workarea 
export gtm_dist=/usr/local/gtm 
export gtmroutines="/var/myApp/o(/var/myApp/r) $gtm_dist" 
export gtmgbldir=/var/myApp/g/mumps.dat 
$gtm_dist/mumps -r start^server 

When start^server begins, the $PRINCIPAL device will already be connected and $KEY will contain "ESTABLISHED|socket_handle|remote_ip_address". In most cases, a USE should be executed to set various device parameters such as delimiters.

The ZSHOW "D" command provides both the local and remote addresses and ports:

0 OPEN SOCKET TOTAL=1 CURRENT=0 
SOCKET[0]=h11135182870 DESC=0 CONNECTED ACTIVE NOTRAP 
REMOTE=10.1.2.3@53731 LOCAL=10.2.3.4@7777 
ZDELAY ZIBFSIZE=1024 ZIBFSIZE=0