Caché I/O Device Guide
UDP Client/Server Communication
[Back] [Next]
Go to:

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.

Caché supports two Internet Protocols (IP): TCP and UDP. These Internet Protocol allow Caché processes to communicate with processes on local or remote systems, whether or not those processes are running Caché.
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.
Caché on OpenVMS does not support UDP.
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,"")
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 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("")
  WRITE client.Send("message text",addrbin,3001)
You can specify a host name, an IPv4 address, or an IPv6 address to GetHostAddr(), as shown in the following examples:
  SET addrbin=##class(%Net.UDP).GetHostAddr("MYLAPTOP")       /* host name */
  SET addrbin=##class(%Net.UDP).GetHostAddr("")  /* IPv4 address */
  SET addrbin=##class(%Net.UDP).GetHostAddr("::1")            /* IPv6 address */
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)
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,!
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:
You can specify the IPv4 protocol as "".
An IPv6 address has the following full format. h is a hexadecimal number with four hexadecimal digits:
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 following is an IPv4 transmission:
 SET sobj=##class(%Net.UDP).%New(3001,"")

  SET inmsg=sobj.Recv() 
 SET cobj=##class(%Net.UDP).%New()   /* the default is IPv4 */
 SET bhost=##class(%Net.UDP).GetHostAddr("")
 SET outmsg="this is the message to send"
 WRITE cobj.Send(outmsg,bhost,3001) 
The following is an IPv6 transmission:
 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" } 
 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) 
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 Caché Programming Orientation Guide.