Alternatively, call serialPrintch with a buffer and its length.

To receive characters, call serialGetch with a buffer, its length, and the minimum number of characters to get. If fewer than the specified number of characters are available, no characters will be read in. Otherwise, serialGetch fills in the buffer and returns the number of characters read.

The EventLoop and MainFormHandleEvent routines are slightly different than in our original Hello, World. EventLoop's call to EvtGetEvent uses a timeout of 1 tick. This means that after 1-tick delay, we'll get a nilEvent. MainFormHandleEvent uses that event to check the serial port -- trying to receive any characters first, then sending them right back out.

These routines are rather simplistic and aren't terribly efficient. You wouldn't use them as-is for most programs, but they're fine as a starting point. They don't use callbacks to indicate that characters are available, so the Palm device must poll to see if any characters have been received. This is wasteful since the program never goes into "sleep". It's constantly wasting battery power saying "Any chars? Nope... Ok, so any chars?" It reminds me of my kids when they want something...

Usually serial I/O is handled by interrupts, the way a telephone or doorbell works. You don't constantly pick up the phone and say "hello". You wait for it to interrupt you; then you stop what you're doing and talk on the phone. This same process inside the computer is called interrupt handling. When the UART receives a character, it "pulls an interrupt" (think of ringing the phone) and the processor stops what it's doing and handles the interrupt. When the interrupt handling is complete, the processor returns to what it was doing before.

Polling is more like when you're waiting for a letter to arrive, so you obsessively check your mailbox every few minutes. The letter doesn't arrive any faster, but you sure waste a lot of time and energy checking the mailbox until it does arrive!

This same waste occurs in the Palm device. If the program knew it would be interrupted for a signal that there were characters received, then it could be either doing something else or go into low-power sleep mode to preserve battery life. Internally, that's actually going on, but the SerialEcho program keeps "checking the mailbox" so it doesn't get to go to sleep.

Another problem with the sample routine is that there's no error handling -- they'll work fine until an error occurs. Once that happens, SerReceive stops returning characters until SerClearErr is called. With directly-connected equipment, errors are fairly rare, though, so again, this is good enough for an introduction.

A few anomalies
The serial port on the Palm device isn't complete, and contains several hidden "gotcha's."

First, the RS-232 signals aren't fully represented. The Data Terminal Ready line isn't controlled the way the specs say it should be. Most of the time this isn't a problem, but it does cause trouble with some modems. Other rarely-used signals aren't supplied at all.