GT.M Socket Device Summary

This document summarizes the GT.M Socket Device Interface. The complete document, including the sample programs is found in the FTP area of this project. The intended readers of this document are (GT.)M programmers who need to write GT.M programs that interface with other TCP/IP processes.

The GT.M Socket Device Interface is the successor of the GT.M TCP Device Interface. It is closer to the MDC standard in its format and functionality. Major improvements over the GT.M TCP Device Interface lie in the delimiter handling and the device organization. There are, however, some deviations from the MDC standard, that relate directly to the GT.M model:

• It does not have the ability to pass sockets between processes, no matter if they are parent and child, siblings or not related at all.
• Error-trapping for the GT.M Socket Device Interface is handled at the device level (as is the case for all GT.M device error handling) instead of at the socket level (as stated in MDC standard).
• The ssvn ^$DEVICE is not supported (at all) by GT.M. In stead all changes can be monitored by inspecting $DEVICE and $KEY, or use of the ZHOW command.

In most operating environments the system maintains a "pool" of sockets. A program that needs to cummunicate over the network will request a socket (from the system), use it for a network connection, and return the socket (to the system). One program can work with multiple sockets, and sockets can often be passed to different processes. This model of handling and passing sockets is essential for many internet-based services.

The other important model in this context is the TCP/IP client-server model. In this model, there are servers, that provide services, and clients that request services. The essential difference is that the server is more or less "passive", whereas the client "actively" requests a service. The following steps depict the general flow of this model:

1. The server is started.
2. The server allocates a socket, and uses that socket to "bind" to a predefined, and well-known service port.
3. The server starts "listening" for incoming connection requests through the socket that is bound to the service port. Incoming requests are queued, and the server specifies the "depth" of this listen queue.
4. A client actively connects to the predefined port.
5. At the server side, a new socket is allocated when the connection request arrives. The new socket is passed to the server. From this moment two sockets are associated with the server: the "listen" socket, and the "connection" socket.
6. The server decides to accept, or to reject the connection. Similarly, the server decides to continue listening for new connection requests, or stop listening (by closing the "listen" socket).
7. If the server accepts the connection, the client and the server can exchange information (through the "connection" socket) until either side decides to close the connection.
8. After closing the connection, both the server, and the client release their "connection" socket.

The example client program connects to a specified host, at a specified port, sends one or more requests to the server, closes the connection and quits. The most important steps are discussed here:

• Construct a dummy, but "unique", devicename.
  set %ZNDev="SCK$"_$J
  The uniqueness of the devicename is a matter of taste: The GT.M Socket Device Interface uses the 'devicename' only as a dummy to identify the device within the process. If another process uses the same name, the OPEN command will still succeed.
• Open the device.
  OPEN %ZNDev:(param1:param2):%ZNTimeS:"SOCKET"
  For a client connection this is the all-in-one step. The device is opened with a timeout as specified by the parameter. This timeout specifies the maximum number of seconds that the process will wait for a successful completion of the connection. The actual time waiting for a connection can be longer due to certain network-related operations (such as host name lookups).
  The :"SOCKET" that follows the timeout specifies that the SOCKET-mnemonicspace is in effect (and thus device parameters apply to that mnemonicspace). The meaning of the device parameters (in the sample program) is as follows:
  • CONNECT=%ZNHost_":"_%ZNPort_":TCP"
    The CONNECT parameter expects an expression that contains the host (name or IP-address), the portnumber (on the host, numeric only), and the protocol (which must be "TCP" in all cases).
  • DELIMITER=$CHAR(13,10,58,27,95)
    The DELIMITER parameter defines the delimiter sequences that terminate a READ command. It consists of a list delimiters, separated by colons. Each delimiter can be one or more characters. In our example there are two delimiters $CHAR(13,10) and $CHAR(27,95). They are separated by a colon ($CHAR(58)).
  • ATTACH="client"
    The ATTACH parameter gives a name to the socket that will be allocated for the connection. Explicit naming of the client socket in this example has no extra use, because the socket is never moved around (e.g. by DETACHing it from this device, and ATTACHing it to another device owned by this process). So this too, is a matter of taste.
• Use the device (and it's only socket).
  USE %ZNDev:(IOERROR="TRAP":EXCEPTION="ZGOTO "_$ZLEVEL_":clientD")
SET ^SCKCLI($job,0,3)=$KEY
  After a successful OPEN, the USE-command will fill $KEY with "ESTABLISHED|socket_handle|host_ip_address". The IOERROR device parameter on the USE command specifies that IO exceptions shall be trapped as runtime errors. The GT.M Socket Device Interface recognizes this MDC standard parameter, but ignores it. The EXCEPTION device parameter is supported on all GT.M IO devices. It instructs GT.M to generate a runtime exception on device errors, and specifies the errorhandling code to be executed (similar to set $ZTRAP=).
• Communicate with server.
  . WRITE %ZNReq(%Z0),!
. READ %ZNRsp:%ZNTimeS ELSE set ^SCKCLI($job)="-2,timeout" quit
. set ^SCKCLI($job,%Z0,2)=$DEVICE
. set ^SCKCLI($job,%Z0,3)=$KEY
  Each request is written to the server. By appending ,! to the WRITE command, the first delimiter (in our case $CHAR(13,10)) is appended to the data stream, and the data is flushed. After writing the data, the response from the server is READ. This may result in a non-zero $DEVICE, or in data terminated by one of the delimiters (reflected in $KEY).
• Write a string with a different terminator:
  . WRITE %ZNReq_$CHAR(27,95) ;,#
  According to the specifications the program must explicitely force flushing the data by adding the "formfeed format" (#) to the WRITE-command (or wait until the TCP/IP layer decides to flush the data). However, the current GT.M Linux version will append a formfeed character ($CHAR(12)) to the datastream when you issue a WRITE #. So in the example programs the ",#" is commented out.
• Close the connection. Because the client only has one socket, the socket device itself is closed, which implicitely closes the connection as well. Before the device is closed, the ZSHOW command is used to store Device information ("D"), and intrinsic variables ("I") in a variable:
  ZSHOW "DI":^SCKCLI($job,"CLOSE") CLOSE %ZNDev

The example single connection server program opens a socket device, listens for an incoming connection, handles the requests from that connection, and quits. The most important steps are discussed here:

• Open the device.
  OPEN %ZNDev:(param1:param2):%ZNTimeS:"SOCKET"
  For a server connection this is the first step in the process. The meaning of the device parameters is as follows
  • ZLISTEN=%ZNPort_":TCP"
    The ZLISTEN parameter expects an expression that contains the portnumber (numeric only), and the protocol (which must be "TCP" in all cases). Because a server process runs on the "current host" by definition, there is no need to include a hostname (or IP-address).
  • DELIMITER=$CHAR(13,10,58,27,95)
    The same delimiters are used by the client and the server.
  • ATTACH="listener"
    The ATTACH parameter gives a name to the socket that will be allocated on the OPEN. This socket will, by definition, be used to listen for incoming connections. By naming this socket explicitely, it is possible to close the listen socket without closing the connection socket.
• Use the device.
  use %ZNDev set ^SCKSERV($job,0)=$KEY
  After a successful OPEN, one socket will be allocated (the listen-socket, named "listener"), and that socket will be "bound" to the listen port. This is reflected in the value of $KEY that is avaiable after the USE-command. $KEY will contain the following: "BOUND|socket_handle|portnumber".
• Start listening.
  WRITE /LISTEN(1) set ^SCKSERV($job,1)=$KEY
  The next step at the server side is to start listening for incoming connections. This is achieved by writing the mnemonic /LISTEN(1) to the Socket Device. The argument (1) establishes the listen-queue depth. $KEY will be set to "LISTENING|socket_handle|portnumber".
• Wait for connection.
  FOR DO QUIT:^SCKSERV($job)
. WRITE /WAIT(%ZNTimeS)
. IF $KEY]"" SET ^SCKSERV($job,2)=$KEY,^SCKSERV($job)=2 QUIT
  After establishing the listen-queue, the program repeatedly writes the /WAIT(%ZNTimeS) controlmnemonic and checks $KEY to find out about "events" on the TCP/IP port. The argument of the mnemonic specifies the maximum number of seconds to wait for an event. The GT.M Socket Device Interface recognizes two kind of events: connection events (reflected by a $KEY value with the format "CONNECT|socket_handle|remote_ipaddress"), and read events (reflected by a $KEY value with the format "READ|socket_handle|remote_ipaddress"). The sample program just waits for the first event (which must be a connection event).
• Store the "name" of the connection socket in a local variable.
  set %ZNSock=$piece($KEY,"|",2)
  Unlike the listensocket (or the connection socket of the client), the programmer cannot specify an explicit name for these sockets. The GT.M Socket Device Interface will provide a "name" for the socket.
• Close the listen socket, so another process can start listening on this TCP/IP port.
  CLOSE %ZNDev:(SOCKET="listener")
USE %ZNDev:(SOCKET=%ZNSock)
  There are different kinds of servers. This example program serves a single connection. So once the connection is made, the listen-socket will no longer be needed. By closing it explicitely at this moment another server process could start listening immediately. Closing the socket (as opposed to closing the device) is achieved by adding the SOCKET="listener" to the CLOSE command. Atfer closing the listen-socket, the program directs its IO operations explicitely to the connection socket.
• Read requests and write responses. Just as the client program, data may be terminated by either of the terminators (or by a timeout), and responses are flushed using either WRITE !, or WRITE #.
  IF $KEY=$CHAR(13,10) DO ;database request
. IF %ZNCmd="get" WRITE "val ",@%ZNData,! QUIT
IF $KEY=$CHAR(27,95) DO ;command
. WRITE %ZNCmd_$CHAR(27,95) ;,#
• Close device.
  CLOSE %ZNDev
  When the connection is terminated, either because of a device-error, or because the client sends a stop command, (or "someone" explicitely SET ^SCKSERV(jobnr),) this procedure is about to quit. It can close the device. This implicitely closes "all" sockets that are still associted with the device.