udp Tcl Command

NAME

udp - UDP protocol communication for Tcl/Tk scripts

SYNOPSIS

::dmh::udp name ?-port port? ?-myaddr IP_or_hostname?

name close

name put destination message

name putl destination code_list

name receive callback

name recvbin callback

DESCRIPTION

The udp command is used to send and receive UDP datagram messages over an IP network. In contrast to the stream oriented nature of TCP/IP, UDP is connectionless protocol where individual datagrams are sent with little overhead beyond IP address management. There is no support in the UDP protocol for sending messages that exceed the size of a datagram (approximately 64k).

COMMAND SUMMARY

udp name ?-port port? ?-myaddr IP_or_hostname?

The udp command creates a new Tcl command, and a new global data array with the name name for using UDP communication. The optional -port port arguments are used to specify a port number for receiving. If no port is specified, a system chosen value is used. The optional -myaddr IP_or_hostname arguments are used in the case of a computer that supports multiple IP numbers and/or multiple hostnames. You are able to specify which network interface should be used.

The global array of the name name is used to store configuration parameters for the network connection and related data. Do not try to use the same name in your application as a global scalar variable. You may add your own data elements to the array, if you avoid naming conflicts with this software. The data item name(port) is set to the port number used for receiving. The data item name(sender) is set to the IP number and port of the sender of the latest received datagram.

name close

The close subcommand is used to discontinue communication. The subcommand erases the global array associated with the connection, and removes the name as a command.

name put destination message

The put subcommand sends the text of the message to the specified destination. The destination is either a Tcl list of the destination hostname (or IP address) and the destination port, or the same two values separated by a colon. The software caches a network address structure for each destination the first time it is used. The system you are running on can be determined using the commands dp_hostname, or info hostname. You can also specify a port on your own system using the hostname of localhost. Examples:

uconn put localhost:5692 "Is anybody home?"
uconn put [info hostname]:5692 "Is anybody home?"
$conn put baloo:7890 "Testing 1,2,3"

name putl destination code_list

The putl subcommand is similar to the put subcommand except that it is called with a list of integer codes representing the binary sequence of characters to be sent. This subcommand allows you to send binary zeroes as in:

$udp_if putl system109:6600 {0 0 0x1b 0x41}

The above example demonstrates that hexadecimal notation may be used for members of the code_list argument.

name receive callback

Use the receive subcommand to receive and process messages. When a UDP message has been received, your callback Tcl code is executed as follows. It is treated as a list, concatenated with two arguments, and evaluated at the topmost, global level of the interpreter. The two concatenated arguments are (i) the udp instance name, and (ii) the received message text. For example:


proc my_callback {name msg} {
  puts "Udp $name received: $msg"
  }

u1 receive my_callback

If your callback argument is an empty string, receiving is stopped. Use the receive or recvbin command again, possibly with a different callback to resume receiving. During the time your callback code is being executed, you will not receive additional UDP messages on the active udp instance. This is done deliberately so that you do not have to code for re-entrant execution in your callback.

name recvbin callback

The recvbin subcommand is the same as the receive subcommand except that the message argument to the callback is formatted as a list of integer codes. This lets you deal with receiving binary messages including null characters in Tcl. At any given time, only the receive or the recvbin subcommand is active. In other words the incoming data is parsed as text or binary, but not both. The latest executed subcommand is the one that is active.

In Tcl, a common method to convert characters to integers and vice-versa is to use the scan and format commands:


set ch "E"
# convert character $ch to integer i
scan $ch %c i
# and back
set ch2 [format %c $i]
if { $ch == $ch2 } { puts "The example works" }

CONFIGURATION OPTIONS

When you create a udp communication object, name, a global array is created with the name name. Some of the elements of this array are actually configuration parameters, that you may inspect or modify. We suggest using the inspect application during development for this purpose.

The software is designed to react and utilize your updated configuration values immediately. The remainder of this section is a description of the available configuraton options in alphabetical order.

BLOCKING, type: boolean, default: 1

This parameter is used to change the low level blocking behavior on system read and write calls. Under ordinary circumstances this will not affect your application since the receive command does not attempt a read call until data is ready, and the put command should be able to write a datagram without getting stuck.

BUFFSIZE, type: integer, default: 8192

This parameter is used to change the size of buffers that are used in the kernel to read and write UDP messages. You will not be able to receive a UDP message that exceeds this size. Depending on the platform, you will get an error or your received message will be truncated if it is bigger than the buffer size. You can specify a size between 1000 and 1000000 bytes.

TRACE, type: unsigned (bits), default 0

Turns on diagnostic output. Diagnostic output is written to the global variable name(trace)

General Tracing: Output to name(trace)

TRACE Bit Output Description

0x0001 Read and write calls

The udp command has been updated to support IPv6 network addresses. By default, hostnames and IP address strings are resolved as IPv4 addresses. The variable ::dmh::udpAddressFamily can be set to the values of inet, inet6, or unspec to resolve the address string as IPv4, IPv6, or as unspecified, respectively. The value of this variable has to be set before an address string is resolved the first time because the address data structure is cached.

AUTHOR

KEYWORDS

UDP TCP/IP communication