init_port(&port1, COM1, 1200L, DATABITS8,
   PARITY_NONE, STOPBITS1, txbuf, rxbuf);

If the rxbuf argument is not a null pointer, then init_port sets up an interrupt-handler for receiving characters into the buffer. If the txbuf argument is not a null pointer, then the function sets up a similar handler for transmitting characters. If both rxbuf and txbuf are null, then all I/O takes place in polled mode.

The default transmitter and receiver buffer sizes are set to 1,024 bytes and 2,048 bytes respectively. If these are inappropriate, then you must either change the #defines in COMM.H or call the lower-level c_open function. For c_open to work correctly, you must initialize several more fields in the COMM_PORT data structure in advance.

typedef union uart {
   UART8250 u8250; /* Intel */
   UARTZ80SIO uz80sio; /* Zilog */
   } UART;

The COMM_PORT function pointers designate Interrupt Service Routines (ISRs), low-level UART-specific services, and callback functions. The ISR function pointers in the COMM_PORT structure keep track of which ISRs belong to a given port. Generally, each communications port on the PC requires a dedicated Interrupt Request (IRQ) line. The PC architecture dictates that each IRQ line must have its own ISRs. The function pointers for low-level UART-specific services transmit and receive characters without requiring every function to be intimately familar with how UART works. The callback function pointers enable the CCT functions to better serve your application's environment. For example, you can transparently send a copy of the communications stream to your printer by pointing the p_out member to your own printer echoing function.

As mentioned earlier, the COMM_PORT data structure also contains a pointer to a MODEM data structure. The MODEM data structure holds all of the data needed to initialize a modem before connection. Nearly 100 initialization parameters can be set if desired. MODEM is composed almost entirely of Hayes Smartmodem command strings. For example, the dial_cmd member typically contains the ATDT dialing prefix. Nearly all modems manufactured within the last five years understand at least a subset of these commands.

The CCT provides several functions to take advantage of the MODEM information. Each of these functions locates a MODEM structure via a COMM_PORT. The modem_init function sends the initialization strings in MODEM. The modem_dial function takes a telephone number string and performs the dialing for you. The modem_hangup function hangs up the phone immediately. The general purpose modem_scmd function sends a command to the modem and returns a pointer to the reply buffer. For example, you use the following sequence to turn off the modem speaker:

strcpy(my_port->modem.speaker, "MO");
reply = modem_scmd(my_port,
   my_port->modem.speaker, BUF_SIZE);
if (strcmp(reply,"OK") != 0)
printf("Error: modem not responding!\n");

set_rx_xlat(&myport, PRINTER_ECHO, ON);

The CCT data translation functions also give you extensive control over newline handling. Special newline handling is often needed for communicating with mainframe hosts and UNIX workstations. As with other translations, newline handling can be independently specified for receiving and transmitting. The nine different options available include Linefeed to Carriage-Return (LF2CR) and Carriage-Return Linefeed to Linefeed (CRLF2LF).

Although programmable delays are not strictly a data translation, the same CCT functions enable them as well. The INTERBYTE_DELAY and TRAILINGBYTE_DELAY flags control delays. On receive, INTERBYTE_DELAY allows you to specify a timeout value to wait for each incoming character. On transmit, INTERBYTE_DELAY specifies a pause between each outgoing character. This is handy for communications sessions with mainframe hosts, which have notoriously poor receive buffering. TRAILINGBYTE_DELAY allows for extra time after the newline is transmitted or received.

Last, the translation functions also set up the flow control parameters. Flow control prevents overrunning the receive buffer when data is coming in faster than it can be processed. The C Communications Toolkit supports RTS/CTS, DTR/DSR, and XON/XOFF handshaking. For XON/XOFF control, you must also designate the characters used to represent these conditions. Some of the flow control techniques can be combined.

ret = freceive(&myport, &xinfo, protocol,
   10*1024L, transfer_progress);

With the CCT, sending a file is only slightly more complicated than receiving one. The primary difference is that files must be enqueued before sending them, even if only one file is going to be sent. The fqueue function takes a pointer to an XFER structure and a string containing the filename to enqueue. For multiple-file (a.k.a. batch) protocols, each invocation of fqueue adds another file to the list. The fsend function does the actual work of sending the file:

fqueue(&xinfo, "HAL_9000.ZIP");
fqueue (&xinfo, "TOOLKIT.DOC");
ret = fsend(&myport, &xinfo, YMODEM, transfer_progress);

The CCT makes the normally unwieldly Kermit protocol easy to use. To send or receive via Kermit, you need only add a call to init_kermit just before the actual freceive or fsend. init_kermit initializes a KERMIT_PARMS structure containing about 40 members. By modifying the KERMIT_PARMS structure, you can fine-tune the Kermit protocol parameters.

Although you can implement file transfer protocols that are not supported by CCT, it might be a daunting task to do so. The source code for the supplied protocols is heavily tailored toward the eccentricities of the XModem variants. However, you could still use the library source as a model for new protocol development.

t = init_term(&myport,
   vt100_write, vt100_conoutc);
t = init_term(&myport,
   ibmansi_write, ibmansi_conoutc);

Unfortunately, the CCT terminal emulations use the BIOS video INT 10h for all output. The INT 10h interface is an order of magnitude slower than writing directly to memory, which will undoubtedly reduce throughput on high speed (9,600 baud or greater) links.

The CCT takes a gentle approach to demonstrating typical communications applications and how they can be solved. The tutorial book presents a series of 17 complete mini-applications in order of increasing complexity from a polling dumb-terminal to a full transmit/receive interrupt-driven terminal. Along the way, the book shows capabilities such as terminal emulation and file transfer protocols. None of the tutorial programs demonstrates how to use the advanced features of the NS16550A UART.

The documentation discusses the Hayes command set and individually covers specifics of the Smartmodem 300, 1,200, and 2,400 baud models. The Hayes V-series is also mentioned, although the Hayes ULTRA 96 v.32 modem is not covered. The manual also ignores the differences between the Smartmodem 1200 and 1200EF (Extended Features) products. Although the CCT contains vendor-specific support for Telebit series modems, the manual does not list the Telebit extensions to the Hayes command set.

The manual precisely describes the XModem file transfer protocol. The authors correctly indicate all of XModem's faults, variants, and workarounds. All of the popular Xmodem extensions including XModem-CRC, XModem-1K, YModem, and YModem-G protocols are summarized. The Kermit file transfer protocol is treated the same as the Xmodem protocol. The documentation also describes the Kermit 8th-bit quoting and Run-Length Encoding (RLE) extensions that the CCT offers.

The function reference section groups the function calls by category. The functions are then presented alphabetically within each category. The notes for each function indicate its purposes, arguments, and return values. Additionally, the notes mention the header file in which it is declared, any hardware limitations it might have, and all of the lower-level functions that it might call.

One area of communications ignored by the tutorial programs and text is development of host (e.g. BBS) software with the toolkit. Although many of the issues are the same for both host and terminal modes, a novice could benefit from such a discussion. Topics for host support would include ring detection and answering, loss of carrier detection, line settings, and Hayes register settings for the host.

The manual does contain some typographical errors, but these are easily overlooked given the clarity of the explanations. There are also a few references to nonexistent figures and tables.

The back cover of the CCT manual and all of the advertising indicates that several intelligent multi-port serial boards are supported, including models from AST, CommTech, Digiboard, and Arnet. An intelligent multi-port serial board usually includes an onboard CPU, such as an Intel 80186. These boards typically cost more than the motherboard on your computer. A multi-port board may contain 4, 8, 16, or even 32 serial ports. These adapters often include onboard EPROM and RAM areas. The adapter RAM may be either privately transferred via DMA or mapped through a window in high DOS memory (like video RAM).

A thorough search of the documentation and source code revealed no references to any of these multi-port boards. After scouring the Magna Carta BBS, I discovered supplemental source code for the CommTech and Digiboard products which had been omitted from the CCT. I asked Andrew Chalk about this apparent support discrepancy. He said the CommTech and Digiboard drivers would be distributed in the future starting with CCT v1.01. Chalk also said that drivers for Star Gate ACL/II and the AST CC-832 adapters were currently being developed. The release dates for these drivers have not yet been announced at the time of this writing.

Support for the CommTech FASTCOMM4 board consists of 200 lines of C allowing it to be addressed as an array of serial ports. Support for the DigiBoard DigiCHANNEL COM/4i and COM/8i is much more extensive than for the CommTech board. The DigiCHANNEL driver provides methods to download communications functions and execute them on the adapter's own CPU. Special board-specific functions manipulate the command and data queues for each port. The CCT functions modified for the DigiCHANNEL board all have an xi_ prefix added to them. For example, the set_speed function is renamed xi_set_speed for the DigiCHANNEL. This function naming convention would seem to make it difficult for an application programmer to maintain a single set of device-independent source modules. An application programmer would most likely need to resort to #ifdefs to work around this naming convention.

If you are using a multi-port board that the CCT does not currently support, Magna Carta Software will consider adding support under an exchange agreement. If you are willing to loan the board to Magna Carta for 30 days, they will consider writing the drivers for you. In return, Magna Carta retains the rights to distribute the drivers in subsequent releases of CCT.

Both data structures and functions of the CCT have been revised since release 1.00 in May 1990. The revisions leading up to v1.00D require changes at the source code level to applications written with the initial version of CCT. These changes are fully documented in the release notes and are mainly oriented toward removing hardware-dependent code at the UART level — an admirable goal. The source-level interface should remain stable in future releases.

With a list price of $150, the C Communications Toolkit is the least expensive of the libraries I have seen. Other packages, such as the C Asynch Manager by Blaise Computing ($189), C Asynch Library by SilverWare ($250), and Essential Communications by South Mountain Software ($329), provide similar functionality but with a higher cost.

The CCT file transfer protocol suite is only missing ZModem capability. Z-Modem is by far the most efficient file transfer protocol available. ZModem offers CRC-32 error detection, dynamically negotiated block sizes, and the ability to restart aborted file transfers (Forsberg 1990). The Solid Link communications library by Solid Software ($199) is the only competitor that includes the ZModem protocol. However, the source code for Solid Link is optional and costs significantly more than the package itself.

Forsberg, Chuck. DSZ — a ZMODEM-90TM File Transfer Program. Portland, OR: Omen Technology Inc., 1990. This is the user's manual for Forsberg's implementation of the Z-Modem protocol. This file is available in the file DSZ1190.ZIP on my BBS.

Volkman, Victor. "TTYTALK: How Serial Telecommunication Works." The C Gazette (Summer 1988): pp 4-27. This article introduces TTYTALK, a C program CROSSTALK XVI compatible terminal program in C. Features include filtering, ASCII file transfer, command language, and dialing. Complete source code for this program is available in the file CGAZV3N1.ZIP on my BBS.

Magna Carta Software, Inc.
P.O. Box 475594
Garland, TX 75047-5594
Phone: (214) 226-6909
BBS: (214) 226-8088 (1200/2400 baud)