Skip to main content
Previous sectionNext section

UDP Client/Server Communication

This chapter describes how to set up remote communication between processes using UDP. For local communication between processes using pipes or using Interjob Communication (IJC) devices, refer to the Local Interprocess Communication chapter of this manual.

InterSystems IRIS® data platform supports two Internet Protocols (IP): TCP and UDP. These Internet Protocol allow InterSystems IRIS processes to communicate with processes on local or remote systems, whether or not those processes are running InterSystems IRIS.

  • TCP: the InterSystems IRIS Transmission Control Protocol (TCP) binding. Establishes a two-way connection between a server and a single client. Provides reliable byte stream transmission of data with error checking and correction, and message acknowledgement. For details, refer to the TCP Client/Server Communication chapter of this manual.

  • UDP: the InterSystems IRIS User Datagram Protocol (UDP) binding. Provides two-way message transfer between a server and a large number of clients. UDP is not connection-based; each data packet transmission is an independent event. Provides fast and lightweight data transmission for local packet broadcasts and remote multicasting. Inherently less reliable than TCP. Does not provide message acknowledgement.

UDP is supported through the %Net.UDP class. This class provides methods to Send() a packet to a specified destination and port, to Recv() a packet from the socket, and to Reply() to the transmitter of the last received packet.

The destination is identified as a local host name or an IPv4 or IPv6 host address. The port can be either a specified port number or a dynamic port assignment.

Establishing a UDP Socket

To use UDP, you must use the %New() method to create a UDP socket object. This object instance is then used to send, receive, and reply to packet transmissions.

When you create a UDP socket object you can specify the port number and the host address, as shown in the following example:

  SET UPDOref=##class(%Net.UDP).%New(3001,"0.0.0.0")
Copy code to clipboard

Both the port number and the host address are optional. The %New() method returns the oref (object reference) of the UDP socket object instance.

There are two sides to a UDP transmission:

  • The server waits to receive a request and then provides the requested information. Thus this side of the transmission may be referred to as the Receiver or the Provider. When a provider creates an UDP object, it must define a port number on which it will receive requests.

  • The client sends a request for information and then receives a reply. Thus this side of the transmission may be referred to as the Sender or the Requestor. When a requestor creates an UDP object, it can use a dynamic port number. The default is 0. When it sends a packet, it must specify the host name and port number of the provider.

The Host Address

The Send() method specifies the binary address of the destination. This is a binary version of the host address. You must create this binary host address by using the GetHostAddr() method, as follows:

  SET client=##class(%Net.UDP).%New()
  SET addrbin=##class(%Net.UDP).GetHostAddr("172.16.61.196")
  WRITE client.Send("message text",addrbin,3001)
Copy code to clipboard

You can specify a host name, an IPv4 address, or an IPv6 address to GetHostAddr(), as shown in the following examples:

  SET hostname="MYLAPTOP"
  SET IPv4="172.16.61.196"
  SET IPv6="::1"
  SET flag=$SYSTEM.INetInfo.CheckAddressExist(hostname)
  IF flag=1 { SET addrbin=##class(%Net.UDP).GetHostAddr(hostname)
              WRITE "host name valid",! }
     ELSE { WRITE "not a hostname: ",hostname,! }
  SET flag=$SYSTEM.INetInfo.CheckAddressExist(IPv4)
  IF flag=1 { SET addrbin=##class(%Net.UDP).GetHostAddr(IPv4)
              WRITE "IPv4 valid",! }
     ELSE { WRITE "not an IPv4 address: ",IPv4,! }
  SET flag=$SYSTEM.INetInfo.CheckAddressExist(IPv6)
  IF flag=1 { SET addrbin=##class(%Net.UDP).GetHostAddr(IPv6)
              WRITE "IPv6 valid",! }
     ELSE { WRITE "not an IPv6 address: ",IPv6,! }
Copy code to clipboard

You can expand this binary host address back to the host name using the AddrToHostName() method, as shown in the following example:

  SET addrbin=##class(%Net.UDP).GetHostAddr("MYLAPTOP")
  WRITE $SYSTEM.INetInfo.AddrToHostName(addrbin)
Copy code to clipboard

You can use the LocalHostName() method to determine your host name. You can use the HostNameToAddr() method to translate a host name to an IPv4 or IPv6 address, as shown in the following example:

  SET localhost=$SYSTEM.INetInfo.LocalHostName()            /* get host name */
     WRITE "local host name is ",localhost,!
  SET addrbin=##class(%Net.UDP).GetHostAddr(localhost)      /* compress to binary address */
     WRITE "binary form of IP address is ",addrbin,!
  SET hostname=$SYSTEM.INetInfo.AddrToHostName(addrbin)     /* expand binary address to host name */
     WRITE "binary IP address expands to ",hostname,!
  SET ipaddr=$SYSTEM.INetInfo.HostNameToAddr(hostname)      /* host name to IP address */
     WRITE "hostname corresponds to IP address ",ipaddr,!
Copy code to clipboard

IPv4 and IPv6

UDP supports both IPv4 and IPv6 Internet protocols. Because these protocols are incompatible, both the server and the client must use the same Internet protocol or the transmission will fail.

An IPv4 address has the following format. n is a decimal integer in the range 0 through 255:

n.n.n.n

You can specify the IPv4 protocol as "0.0.0.0".

An IPv6 address has the following full format. h is a hexadecimal number with four hexadecimal digits:

h:h:h:h:h:h:h:h

Commonly, IPv6 addresses are abbreviated by eliminating leading zeros and replacing consecutive sections of zeros with a double colon (::); only one double colon may be used in an IPv6 address. By using IPv4 abbreviation rules, you can specify the IPv6 protocol as "::" (meaning that all eight h sections have the value 0000).

To establish the Internet protocol:

  • The client must establish either IPv4 or IPv6 in the %New() method. The default is IPv4.

  • This must match the IPv4 or IPv6 protocol specified in the GetHostAddr() method and supplied (in binary form) in the Send() method.

The following is an IPv4 transmission:

Server
 SET sobj=##class(%Net.UDP).%New(3001,"127.0.0.1")



  SET inmsg=sobj.Recv() 
Copy code to clipboard
Client
 SET cobj=##class(%Net.UDP).%New()   /* the default is IPv4 */
 SET bhost=##class(%Net.UDP).GetHostAddr("127.0.0.1")
 SET outmsg="this is the message to send"
 WRITE cobj.Send(outmsg,bhost,3001) 
Copy code to clipboard

The following is an IPv6 transmission:

Server
 SET x=##class(%SYSTEM.INetInfo).IsIPV6Enabled()
 IF x=1 {
    SET sobj=##class(%Net.UDP).%New(3001,"::1")



  SET inmsg=sobj.Recv() }
  ELSE {WRITE "IPv6 not enabled" } 
Copy code to clipboard
Client
 SET cobj=##class(%Net.UDP).%New(0,"::")
 SET bhost=##class(%Net.UDP).GetHostAddr("::1")
 SET outmsg="this is the message to send"
 WRITE cobj.Send(outmsg,bhost,3001) 
Copy code to clipboard

Methods for handling host addresses are found in the %SYSTEM.INetInfo class documentation. Further details on IPv4 and IPv6 formats can be found in the section “Use of IPv6 Addressing” in the chapter “Server Configuration Options” in the Orientation Guide for Server-Side Programming.