Liren Large Software Subsidy 5/05.iso/a/a012/1.ddi/README.EXE/TELEPATH.TXT

Text File | 1991-05-01 | 22.6 KB | 484 lines

                              REVIEW: Telepathy
                                By Steve Baker

(Editor's Note: Steve Baker will be reviewing three Clipper
communications packages in the next several issues of The Aquarium.
Look for reviews of SilverClip and CommTools to follow.)

Laaaaadies and Gentlemennnnnnn,

I have the distinct honor of being chosen to introduce to you, a
relative newcomer to the third-party communications game. Hailing from
Extrasensory Software, weighing in at one disk, one hundred
fifty-eight pages of documentation, and recently entering competition
in October 1990, ...

                         TELEPATHY!
         (flashbulbs, cheers, screams and clapping).

Did you ever want your Clipper program to dial the phone for you? Send
or receive a file to another computer? Work with a bar code reader?
Write a BBS program?  Make your own terminal program? Receive input
from an A-to-D converter?  And yes... even write your own version of a
program like Aquarium?  Can you say "Extrasensory Software" ten times
real fast?  Ok... neither can I.  How about "Telepathy"?

Telepathy is a communications library for Clipper Summer 87, and
Clipper 5.0.  With it, we can look incredibly smart if someone asks us
if we can perform serial communications from within our Clipper
programs.

The Telepathy Library

The Telepathy functions generally fit into the following categories
(these are my categories -- the Telepathy docs just group all the
functions in one place.)

                   SERIAL PORT CONTROL
                   UART STATUS / CONTROL
                   RECEIVING DATA
                   SENDING DATA
                   MODEM CONTROL
                   PROTOCOL FILE TRANSFER
                   TERMINAL EMULATION
                   BIT AND BYTE STUFF
                   EVENT NOTIFICATION
                   ERROR CONTROL

I have included a reference table in the "Source Code" section of this
article, that lists each function, and gives the Norton Guides
description of what it does.

Any "Clipper Head" will love the function design used in Telepathy.
Most functions are of the multi-purpose GetSet() type of design.  For
example, instead of one function to Get the current UART baud rate,
and one to set a new baud rate, there is a single function called
tp_baud().  This function returns the current setting, and sets a new
baud rate if desired, in the same manner as Clipper's SETCOLOR() and
SET() functions.  In addition, the modem status and UART status
functions have been designed to return information on several status
bits with one call, rather than have a separate function for each
status register of interest. This makes a lot of sense to me, and I
think that a Clipper user cannot help but like the Telepathy design
approach.

What's so good about Telepathy?

This is the hard part...  How to get the "feel" of the library across
to you so that you can appreciate how good it really is.  Rather than
ramble on about each function, I first want to try and give you an
overall view of what "stands out" about Telepathy (I'll ramble later).

Let me start by saying that I think the most notable quality of
Telepathy is the degree of access that you have in controlling and
responding to serial port communications. This control comes from
three concepts:

     1. The support of a user-specified Progress function
        during file transfer.
     2. The support of an idle function during all processing.
     3. The unique Telepathy Notification system.

Progress Function

During any protocol file transfer (and Telepathy supports a bevy of
formats), you can specify a user-defined function that will be called
repeatedly during the file transfer.  This is similar to the UDF that
can be specified in MemoEdit(), and is called on start and finish, and
after each block transmission.  On each call, your function is sent a
status code, the name of the file being transferred, the byte count,
and the error code. Using this design, your file transfers can have a
completely customized look to them.  I know of no other communications
library that gives you this ability without working in C.  (See the
accompanying source code for a sample Progress function.)

The Idle Function

All Telepathy functions that have to wait for input or output
repeatedly call a function called tp_idle().  By writing your own
tp_idle() function, and pre-empting the library version, you can have
control at all times. For example, even though you specified that a
function should wait forever to receive a certain string at the serial
port, you can still maintain control because that function will be
continuously calling your idle function while waiting. Any routine can
be aborted by the return value of tp_idle().  (See the source code
file for an example.) This function also applies to file transfers.
Powerful stuff!

The Notification System

Did I say the idle function was powerful?  Well if the idle function
was a 33 Mhz 386, then the Notification system is a Cray
supercomputer.  This system allows you to specify a particular
communications "event" to watch for, and what function to call when it
happens, and then go merrily along your way until one of the events
occurs.  To do this, Telepathy has 6 functions that allow you to
specify conditions to watch for.  You can ask for notification
whenever any of the following happens:

   - any input whatsoever is received at the serial port.
   - a certain character is received.
   - the output buffer is empty.
   - the input buffer fills up to a "high water" mark.
   - any of the modem status flags change value.
   - a certain amount of time has elapsed.

To request a notification, you call the correct function for the type
of notification you are requesting, and pass the name of the function
you want to branch to when the notification is received.  For example,
you could set your modem to auto-answer, and then request to be
notified whenever a Carrier was detected by the modem.  Your program
could continue doing whatever it does (now I sound like one of my
clients!) and then automatically branch to a routine to handle an
incoming data call when notified.  (See the source code for a sample
routine using notifications.)

To accomplish this feat, Telepathy makes use of Clipper's SET KEY
abilities.  When a notification condition is met, Telepathy stuffs a
special inkey() value into the keyboard, and issues a SET KEY command
for that inkey() value.  Branching will then automatically occur from
the next wait state encountered, just as it would for any SET KEY. The
system is designed so that only one SET KEY value is used for all
notifications, leaving you 31 remaining possibilities in the rest of
your program.

Input Watches

Another Telepathy feature that I mentally include with notifications,
is the ability to register up to 16 different strings to watch for.
When a watch string is registered, Telepathy looks for that string
whenever data is read from the receive buffer.  (Note that watches are
processed as data is read from the buffer -- notifications are posted
as events happen at the serial port.)  You can then query as to
whether any of the watch strings have been received, which string, and
how many times.

Protocol File Transfer

The supported file-transfer protocols in Telepathy are outstanding.
You receive support for the following protocols:

                Xmodem
                Xmodem-CRC
                Xmodem-1K  (sometimes called Ymodem)
                Ymodem     (sometimes called Ymodem batch)
                Ymodem_G
                Zmodem
                Kermit

In addition, all required support functions to control optional
settings for these protocols are provided.

As we already discussed, a custom Progress() function can be specified
for any of these protocols allowing completely customized status
displays during file transfer.


UART Status / Control

A host of functions exist to Get/Set the status of all registers, and
to control all flow control settings. If you will refer to the
detailed function list in the source code section, you will see that a
function exists to Get or Set just about everything you can think of.

A couple of functions deserve special recognition here for their
design:

The tp_lstat(), and the tp_mstat() functions return the status of the
Line Status Register, and modem registers respectively.  A string is
returned that contains an identifier for any "high" bit in the
register.  For example, if the modem carrier detect was high, and
Clear To Send was high, tp_mstat() would return "CK". Using this
design, you can receive a string from these functions that describes
the status of each register bit...in one function call.

The 16550 UART is also supported.  This is an improved version of the
NS16450 that can be put into an alternate FIFO mode which relieves the
CPU of some processing overhead.

Telepathy also supports user control of Hi-Water and Low-Water receive
buffer settings. You can specify these settings to control what
percentage of the receive buffer is filled when input is stopped and
started using flow control.

Serial Port Control

As you can see from the function listing in the source code section,
all of the functions you would expect to see are there for opening and
closing a serial port, and controlling all settings such as baud, stop
bits, parity, data bits etc. One design feature that I particularly
like, is the ability to specify all settings as parameters of the
tp_open() function. While there are separate functions to get/set an
individual setting, there is no need to call them after opening the
port. The port can be opened, and completely set up in one function
call.

In addition to the normal tp_open() function, there is also a function
named tp_reopen().  This function just opens the port with whatever
parameters it finds the serial adapter currently set to.  Using this
function you could close the port but leave the modem on-line, execute
an external program, and then reopen the port with the existing
settings.

Receiving Data

The functions for receiving information through the serial port
essentially use three strategies:

   1.  Passively let the input characters accumulate in a receive
       buffer and then search or retrieve the information in the
       buffer later.

   2.  Actively receive remote-entered information, process it
       as it is received, and assign it to a variable (such as a
       password or file name)

   3.  Actively monitor the information coming into the serial port
       and discard all received information until one of several
       special strings is received (such as logging onto a BBS and
       waiting for the right question)

The majority of functions deal with method one.  When a port is
opened, an input and output buffer is initialized, and the size can be
user-specified.  As characters are received, they are automatically
placed in the input buffer.  Using the receive functions, you can then
extract information from the buffer (tp_recv), determine how many
characters have been received (tp_inchrs), parse the information
(tp_recvto), look for specific information (tp_lookfor), empty the
buffer (tp_clearin) etc.

(See the source code routine SimpleTerm() for an example.)

The second method, using tp_recvln(), allows you to receive a line of
information from a remote user, and actively allow remote line
editing.  Think of this as a remote GET.  You could use this for
getting interactive input such as PassWords or FileNames.

The third method, using tp_waitfor(), actively watches the information
coming into the serial port, and throws everything away until one of
several strings is received.  This could be used while waiting for a
specific prompt to reply to when logging onto a BBS etc.  In my
opinion, this function is one of the most useful in the library.  It
allows you to specify a list of strings, or an array of strings to
wait for at the serial port. A time limit may be specified, or you may
have it wait forever. Whenever one of the strings comes into the port,
the function will return a numeric indicating the position in the
list/array of the string that it found, allowing you to branch to the
appropriate processing method.  I've had to write a considerable
amount of code with another comm library to obtain the same
functionality that this function gives you.

Transmitting Data

Sending information out the serial port is pretty simple.  After the
output buffer is initialized when you open the port, all you do is
stick whatever you want sent into the output buffer. To put a string
into the output buffer, the function tp_send() is used. Once a string
is in the buffer, Telepathy's internals and the UART take care of
whittling down the information in the buffer, and getting it out the
port, while observing whatever flow-control settings are in effect.

(See the source code routine SimpleTerm() for an example.)

Modem Control

You may be surprised that there are no internal library functions to
control the modem.  You are provided a .PRG file of modem-control
functions written in Clipper S87, that make use of the other Telepathy
functions.  I admit that at first I thought "Ah Ha! ... a weakness".
Having used another communications library in the past, I was used to
the modem stuff being accomplished by library functions.

After I did some testing and thinking though, it became clear to me
that there were some definite advantages to having the modem control
functions "out in the open".  Using a modem is like talking on the
phone in the old days when you had to have a third party "operator" on
the line with you (no, I'm not really THAT old). When you need to
make a call, you just pick up the phone (open comm port) and get the
operator's (modem's) attention.  We could do this by yelling
"Operator!" (AT) into the phone until the operator responded. If
the operator is listening, they will respond with "This is the
operator, I heard you..." (OK). Then we just yell "OPERATOR, connect
me with 555-1212 please"  (ATDT555-1212).  While you're talking to
your party on the other end, the operator just makes sure that your
conversation gets passed back and forth.  If you want the operator to
do anything special however, you have to get their attention again.
To do this, we could flash up and down on the receiver hook (+++) and
yell "Operator!" (AT), until the operator answered (OK).

So really, controlling a modem comes down to what you yell after you
get the modem's attention. Having these functions written in Clipper
gives you much more capability to handle any non-standard problems,
and also to review any assumptions that are made, and change them to
suit you.  I wrote a 5.0 version of some modem functions using the
Summer '87 file that came with Telepathy as a base.  Some of this code
is included in the source file as an example.

Terminal Emulation

Currently Telepathy supports both TTY, and ANSI terminal emulation.
VT-100, and VT-52 are not supported.

Bit and Byte Stuff

Several functions are provided for the bithead.  Ordinarily, I would
just mention these and say that it is perfectly clear what they are
used for... just not to me.  I feel that they need to get mentioned
however since Telepathy uses a "power of 2" return value for several
of it's "could be one, any, or all" types of functions.  An example
would be tp_hshk() which returns a number that represents all of the
current handshake settings (sort of like color numbers).  Rather than
getting quickly over my head trying to discuss bits and bytes, I will
just say that it is not necessary to try to extract information from
this number, or to try to build this number since individual functions
are available to do that for you. If you did want to play with the
bits though (yech...), bin_and() could be used to test these values,
and bin_or() could be used to build a value specifying multiple
settings.

Error Control

All of Telepathy's functions set an internal numeric error code
whenever an error is encountered.  Some functions will return an error
result directly, but all functions set the internal error code prior
to exiting.  The function tp_error() will return the error result of
the last Telepathy function called.  This allows you to test for error
conditions after every call to a communications function.  The
function tp_errmsg() will return a verbose description of an error
code returned by tp_error(). Error codes are generated for general
errors, file transfer errors, and Dos errors.  A header file is
supplied with the manifest constant definitions for these error codes.

A list of standardized error codes is provided in the source code
section.

Another nice feature of Telepathy that could be grouped under error
control, is the ability to disable its own interrupts on an unplanned
exit from your program.  Should your program abort to DOS rather
ungracefully, you don't have to worry about using a utility to disable
any interrupts that were in effect prior to exiting to DOS.

Installation

It would be reasonable to assume that if you are writing a program for
developers, your customer is capable of getting your program onto his
hard disk with a few basic instructions.  I agree with this, except
I've gotten lazy(ier) in my old age. It's gotten to the point where I
expect a completely automated installation routine for any commercial
program.  'Tis not the case with Telepathy. "Create this directory and
then copy these files and then..."  You get the idea. Certainly not
hard, but also not the lazy man's way.

Documentation

The Telepathy manual comes in a nice 3-ring binder with a "Just the
facts ma'am" look.  (Editor's Note: Joe Friday hailed from the City of
Angels, as does Extrasensory Software -- maybe there is a connection?)
In addition to the usual stuff, Telepathy has a wonderful "Serial
Communication Primer" that runs for a full eight pages.  In it, you
learn just about everything you need to know to have a reasonable
chance of actually understanding what you are doing with communication
programming.  In addition to the primer, there are general information
sections on Serial Programming, protocol File transfers, and the slick
Telepathy notification system.

The function documentation does not follow the Nantucket format of
Syntax, Arguments, Returns, Description, Examples, etc. Instead, the
function syntax is shown with an assignment variable, and then the
assignment variable is discussed along with the passing parameters.
Here is an example:

                tp_recv() - receive string

      cString = tp_recv(nPort[, nLength[, nTimeout]])

The return value of this function is documented by the Hungarian
notation of cString (if you want to more about this notation, see
Matt Maier's "Standards and Conventions" article in the 2/91
Aquarium), and by any remarks about cString in the rest of the
function documentation.  It is easy to tell what you are getting back
by looking at the assignment variable.

Unfortunately, this format does not tell you the whole story. I missed
the Returns section to clarify little exceptions to the rule. As an
example: tp_close() and tp_clearout() do not show a return variable,
and tp_baud() specifies that the old baud rate is always returned. As
it turns out, tp_close() actually returns an error code, tp_clearout()
returns NIL, and tp_baud() can return an error code under certain
circumstances. The first case was an omission that was corrected in
the Norton Guide file. The second case was undocumented probably
because it always returns NIL.  The third case is just undocumented. A
formal Return section would help clarify things in my opinion.

The printed manual suffers from the usual "first release" problems.
Most of the references to "see page __" are wrong and since they are
all 6 pages off, it's easy to see what happened. Coding examples are
extremely sparse, and what examples do exist are in Summer '87 format.

In addition to the printed manual, Telepathy comes with a nice Norton
Guide help file, a Tom Rettig help file, and a limited version of the
Tom Rettig engine.

In general, the documentation is good.  A Function cross-reference by
general task would be nice.  Without a doubt, the docs could use more
coding examples to show how each function was intended to be used.
What I found missing the most in the Telepathy manual, was a section
that says, "And now this is what you do with all this stuff to make a
communications program in Clipper...".  However, you do receive
several sample .PRG files however that help fill this void.

After Sale Support

Extrasensory Software offers several methods of getting assistance
after you purchase Telepathy.  You can contact them via voice phone
(although the hours are somewhat unusual), BIX, CompuServe
(76702,672), TelePath, UseNet, U.S. Mail, and even the Aquarium
Message Center (although this option is not mentioned in either the
manual or Norton Guide).  One thing I wish they had was a dedicated
BBS where one could find sample code and quick answers to routine
questions.   I found their support to be very good in general, and
their frequent update policy is outstanding.  You need only ask for
something and it's in the mail.

So How Much is it ... and what do I get...

I sound like a late-night TV salesman don't I?  Sorry... I'm just the
Aquarium reviewer and I can't even throw in a free Ginzu knife or
anything, but for a very reasonable $149.95, you get the whole
Telepathy package:

Telepathy comes on a single disk.  You receive both Clipper Summer
'87, and Clipper 5.0 versions.  The library comes in a non-overlay
version, and a version for dynamic overlays that is split into ROOT
and OVL modules. The overlay modules work with those linkers that
support dynamic overlaying of C and Assembler (the version of RTLINK
that comes with Clipper 5.0 cannot dynamically overlay C or ASM).

For documentation you receive a printed manual, a Norton Guide help
file, a Tom Rettig help file, and a limited version of the Tom Rettig
engine.

As a nice bonus, you receive CLIP, a handy compiler and linker driver
for Clipper.

Ordering Information:

Telepathy - $149

Extrasensory Software
4450 Murietta Ave.,  #8
Sherman Oaks, CA   91423
Orders  [phone]
Fax     [phone]
Support [phone]
Aquarium (address messages to Ira Emus or Dave Rifkind)
CompuServe (76702,672)
BIX (IRAE)

About the Author

Steve Baker is Programming Director for the Parkside Company, and we
are proud to introduce him to the Aquarium editorial staff.  Steve
welcomes your comments via the Aquarium Message Center or (if you
simply must use CompuServe) at ID 72007,3371.