NAME

SYNOPSIS

::dmh::comm portname terminal_server_port

portname close

portname get n_chars seconds

portname getl n_bytes seconds

portname put message

portname putl code_list

portname receive callback ?msg_start? ?msg_stop?

portname recvbin callback ?start_codes? ?stop_codes?

portname reset

portname tracewin

DESCRIPTION

The comm command is used to manage communications over an RS-232 serial port. The command can also be used for serial communication with a TCP/IP socket connection. The latter is typically used to connect to a terminal server which in turn has serial port hardware connected to a remote device. Text and binary messages may be exchanged.

COMMAND SUMMARY

comm portname ?rs232_device?

The comm command creates a communication connection to the RS-232 port specified by rs232_device. A new Tcl command, and a new global data array are created with the name portname.

The global array of the name portname is used to store configuration parameters for the port 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. Also, do not use the variable name comm. This name is used dynamically to indicate which port has received the current message.

If the optional rs232_device is not specified, it defaults to COM1 on NT, /dev/ttyS0 on Linux, /dev/tty0 on AIX, /dev/ser1 on QNX, otherwise /dev/tty01.

comm portname terminal_server_port

This variation of the comm command creates a communication connection to an RS-232 port on a terminal server. The terminal_server_port is of the form hostname_or_IP_addr:socket_num. Optionally, the terminal_server_port ends with ,S to indicate a server connection. The latter is used in testing, but not to connect to real terminal servers. The software assumes a binary passthrough IP socket connection to the terminal server. Usually, you need to separately configure the terminal server so the port does not perform telnet control character mappings or other canonical processing. For example:

comm barcode2 /dev/tty0
comm bonder1 xyplex6:2100
comm test_server myhost:5003,S

If a terminal server connection is lost, the default configuration of the software tries to reconnect periodically. Refer to the active_reconnect and T5 configuration options below.

portname close

The close subcommand is used to discontinue communication. The subcommand erases the global array associated with the connection, and removes the portname as a command. The command does not wait for any active communication to complete.

portname get n_chars seconds

The get subcommand is used to receive a specified number of characters, n_chars, within a timeout interval specified by the seconds parameter. The return value is a Tcl string containing the received 8 bit characters, or an empty string if all of the requested data is not received within the interval. While receiving, the application continues to dispatch events. You are not allowed to nest calls to get or getl. The parameter n_chars must be between 1 and 1000. Recent versions of Tcl are able to represent binary codes in string data, including the null byte, so the get command can be used to obtain text or binary data.

portname getl n_bytes seconds

The getl subcommand is exactly like the get subcommand except that the usual return value is a list of integer codes representing the binary sequence of characters received. The codes are formatted using 0xNN hexadecimal notation.

portname put message

The put subcommand sends the text of the message argument out the port. A newline character or any other delimiter is not automatically sent. If you want to send newline characters, the Tcl interpreter allows you to encode them in text expressions using using \n. Also, you may encode arbitrary binary sequences using \xNN notation. See the man page Tcl for a description of backslash substitution. The comm command is aware of the internal UTF-8 representation of strings in Tcl, and is able to send and receive any 8 bit character code including the null byte. Older version of Tcl were not able to imbed the null byte in string data because it was interpreted as a string terminator.

portname putl 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 any binary codes, for example:

tty1 putl {0 0 0x1b 0x41}

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

portname receive callback ?msg_start? ?msg_stop?

Use the receive subcommand to isolate and process messages from data received at the port. Use the msg_start argument to indicate a character or sequence of characters which defines the start of a message, and similarly use the msg_stop argument to specify the end of a message. Arbitrary sequences of 8 bit characters may be specified. Both the msg_start and msg_stop arguments are optional. If neither one is specified, your callback code is executed with whatever data is read at the port. If only the start sequence is defined, the end of message is determined by the start of a subsequent message. Similarly, if the msg_start is an empty string, and the msg_stop argument is one or more characters, the start of a message is implied by the end of the previous message.

When a complete 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. This evaluation method allows you to code multiple Tcl statements in your callback or to set up additional procedure arguments that precede the appended ones for your custom procedures. The two arguments are (i) the portname, and (ii) the received message text. For example:

proc my_callback {portname msg} {
  puts "Port $portname received: $msg"
  }

tty1 receive my_callback "" "\n"

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.

portname recvbin callback ?start_codes? ?stop_codes?

The recvbin subcommand is the same as the receive subcommand except that the specification sequences for the start and stop of messages are expressed as lists of integers. This lets you specify binary codes that are awkward to specify using backslash escape sequences. Also, the message argument to the callback is formatted as a list of integer codes. At any given time, only the receive or the recvbin subcommand is active. In other words the incoming data is parsed as text messages or binary messages, 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" }

portname reset

The reset subcommand clears the state of the scanning code that is examing the incoming datastream for the start and stop of messages.

portname tracewin

The tracewin subcommand creates a trace window for the portname communication activity. The trace window has a menu with item selections to control the information displayed. This command is implemented as a Tcl procedure which can be dynamically loaded by the interpreter after the comm command is first used. This is explained in the section below, entitled AUTOLOAD LIBRARY. The recommended order of setting up a port with a tracing window is (1) use the comm command to create the portname object, (2) optionally set the TRACE value in the portname global array to display the desired level of trace detail, (3) use the tracewin subcommand to create the trace window, and (4) begin communication by using the put, putl, receive and/or recvbin subcommands.

The trace window has a menu item that brings up a Replay Window. The Replay Window allows you to send or receive any data that has been previously sent or received. It also allows you to save and load Replay session files. The re-receive feature is especially useful for you to debug and develop your interface software without needing to communicate with the actual equipment; the re-receive action simulates reception of the selected messages. The Tcl source code for the tracewin subcommand and for the Replay Window is provided. You may wish to customize it or write your own version(s). For example, you may wish to add menu items that cause custom messages to be sent, or add menu items to display application status.

CONFIGURATION OPTIONS

When you create a port communication object, portname, a global array is created with the name portname. Many 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. For example, if you change the BAUD parameter, the RS-232 hardware is reconfigured on the fly, even if you are in the middle of passing a message.

The remainder of this section is a description of the available configuraton options in alphabetical order.

active_reconnect, type: boolean, default: 1

For a terminal server client, this option specifies whether the client should periodically attempt to reconnect to the terminal server if a connection is established and then lost. The retry interval is specified by T5. The value of T5 should probably be set to a larger value than the default if you have dozens of connections on your workstation. Also, a connection attempt may make your process unresponsive for several minutes if the network, external node, or server is unresponsive. You may wish to make T5 larger if you have more than one connection in your process. This option does not apply to RS-232 connections.

BAUD, type: integer, default: 9600

This parameter sets the baud rate for the serial communication port. The values 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, and 57600 are supported by this software. Your tty device driver and hardware combination will limit the actual obtainable values. Typically the BAUD parameter has no effect on Terminal Servers which are configured directly at the Terminal Server hardware. Baud rate changes may be made at any time, and may disrupt any active message exchange.

CTSRTS, type: boolean, default: 0

Setting this value to 1 turns on CTS/RTS hardware handshaking. This option is not POSIX standard, and may not be available on your platform or for your hardware. This option is available on AIX, SunOS, and Windows NT when the hardware supports it.

DATABITS, type: integer, default: 8

This parameters sets the number of data bits for the serial communication port. Possible values are 7 or 8. This parameter has no effect on Terminal Servers which are configured directly at the Terminal Server hardware. Changes may be made at any time, and may disrupt any active message exchange.

PARITY, type: string, default: "none"

Setting this value to "none", "even", or "odd" causes the port to be reconfigured to the specified parity.

STOPBITS, type: integer, default: 1

Setting this value to 1 or 2 sets the number of stop bits for the serial communication port. This parameter has no effect on Terminal Servers which are configured directly at the Terminal Server hardware. Changes may be made at any time, and may disrupt any active message exchange.

T5, type: milliseconds, default: 10000

Connect Separation timeout. Specifies the delay between connection attempts for an IP terminal server connection. This option does not apply to RS-232 connections.

TRACE, type: unsigned (bits), default 0

Turns on diagnostic output. The display window created using the tracewin subcommand provides an interactive menu to set the TRACE option and a viewing window for the diagnostic output. However, it is possible to utilize the diagnostic output directly using the trace command. We have used this feature on a dial-up connection, when running dmh_wish with the -notk option and not using X-Windows. Diagnostic output can be written to four global variables portname(trace), portname(rtrace), portname(last_recv), and portname(last_send). The TRACE parameter is used as a bitfield. By setting specific bits, the corresponding output, tabulated below, is turned on.

General Tracing: Output to portname(trace)

Bit        Output Description

0x0001     Read and write calls
0x0002     Changing of port communication parameters 


Receive Tracing: Output to portname(rtrace)

Bit        Description for Received Data

0x0100     Parsing of data to isolate messages
0x0200     Received messages 
0x0400     Dispatch of callback code

Replay Tracing: Used for input to Replay Window

Bit        Description

0x0040     Reception data traced to portname(last_recv)
0x0080     Send data traced to portname(last_send)

Logging: Control over output file(s)

0x10000    Save traced data to log file(s)
0x20000    Compress log file when closing.

Saving of trace data to output files is indicated by setting the 0x10000 bit. The saving logic writes each day's output to a distinct file, in the directory named by the traceDir array element. The traceMax array element controls how many day files are saved per year. The traceMax array element value can be configured between 1 and 366. When file saving is initiated, the output filename is set to traceNNN.txt where the NNN value is the current day of the year, 0 to 365, modulo the traceMax value. If this file already exists and has been written to earlier in the same day, then the output is appended to it, otherwise the file is created as a new file. Note that if the traceMax value is set to 1, each day's output is saved to the same filename, trace000.txt. If the traceDir and traceMax array elements do not exist when trace data for file logging is first captured, the saving logic creates default values for them. The default values provide for saving the data from each connection in a separate subdirectory. When trace data is being written, the 0x20000 bit controls whether the logic attempts to compress the output file when it is closed at the end of the day (midnight). For compression to occur, the traceMax value must be greater than 1 and a non-blank compression command must exist as the array element traceZipCmd. The default assignment of traceZipCmd is similar to "zip -m tracetxt.zip". This command causes the data file from the previous day to be moved into the tracetxt.zip archive.

XONXOFF, type: boolean, default: 0

Setting this value to 1 turns on software XON/XOFF handshaking.

SEE ALSO

The usual file commands open and puts may be adequate for text-based communication that is delimited by newlines.

AUTHOR

KEYWORDS