Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!cwjcc!ukma!rutgers!apple!bloom-beacon!oberon!pollux.usc.edu!papa
From: papa@pollux.usc.edu (Marco Papa)
Newsgroups: comp.sys.amiga.tech
Subject: Adding ARexx support to a Comm Program (A Tutorial)
Message-ID: <12718@oberon.USC.EDU>
Date: 11 Oct 88 03:48:40 GMT
Sender: news@oberon.USC.EDU
Reply-To: papa@pollux.usc.edu (Marco Papa)
Organization: Felsina Software, Los Angeles, CA
Lines: 84

I was just noticing that Tony Sumrall is going to be adding ARexx support
to VT100.  Since he is not done yet,  and I have done such a job for
a commercial product (A-Talk III), it seems appropriate to share my 
experiences. Hopefully other communication programs will be able to use these 
ideas, too.  Note that I have to acknowledge the helpful discussions I had
with Willy Langeveld of SLAC [which had the first ARexx comm implementation
for his terminal program VLT], and of course the several phone calls I had with
Bill Hawes, author of ARexx.

Adding ARExx support to a terminal program that ALREADY has a script language
is much easier than adding it to another program that does not have such a
built-in feature.  The author of MicroFiche Filer Plus found this out pretty 
soon. As a result of this, adding "full" ARexx suppport to a program with a 
script language will take about 5K of object code and 1 week of work.  Adding
ARexx support to a program missing the script language takes the above time
PLUS the time to build the script language itself, which can be a big effort in
itself.

Now back to the terminal program script language.  Most terminal script 
commands should be executable from ARexx.  A few do not make real sense:
GOTO, EXIT for example should be skipped, since there is no "current" script
being executed and no labels to GOTO.  DELAY and WAIT should be supported,
though.  Willy's VLT does not support them, but Willy's idea on how to 
support them worked: delay the reply of the message until the DELAY time 
has passed, the WAIT has succedeed or a TIMEOUT has expired.  This worked just
fine in A-Talk III.

VLT provided 1-way communications between ARexx and the VLT: ARexx port:
VLT accepts messages that tells it to execute commands and always replies a
"success" message.  First of all, return codes should be used to report
whether the command was successful or not.  Error codes should be reported for
such things as DIAL not successful, CAPTURE OPEN failed, Download failed 
an such.

But moreover there should be a way to return information from the host 
computer.  This will give you full two-way communication.  One way to implement
this is to allow storing of strings [or entire lines] in a buffer and add
a command, available only when invoked from ARexx, to return the string as
an ARexx ArgString.  The primary return code would be 0 and the
secondary return code would be the string obtained from the host.

The entire program would look like this considering an example of two-way
communication between a terminal program and a database manager:

OPTIONS RESULTS		       ask for ArgStrings
'REPLY "hello"^M"'             send a string to the host
'GETLINE'                      get the reply from the host computer
'STRING'                       this is the command that returns the line
                               gotten from the previous command as an ArgString
IF RC=0 THEN SAY "returned" RESULT

Note that ARexx stores the returned ArgString in the variable called RESULTS.

If the whole thing has been started by a database program, the database program
could get some notion of what happend on the "host" computer, one level further
down from the terminal program it was talking to.

The entire loop looks like this:

    send command
        V
DBMS --------> AREXX -----> TERM pgm -----> host comnputer +
							   |
							   |
DBMS <-------- AREXX <------ TERM pgm <--------------------+
          ^
          |
    get result of command
       on host computer

As we have found out from early uses of this technique from our beta testers,
you can implement quite complex and powerful Arexx scripts with it.

I hope that this was useful to some, and at least explained what extra power
one can get by adding such a simple and cheap interface (in terms of coding 
involved).

Enjoy.

-- Marco Papa 'Doc'
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
uucp:...!pollux!papa       BIX:papa       ARPAnet:pollux!papa@oberon.usc.edu
 "There's Alpha, Beta, Gamma and Diga!" -- Leo Schwab [quoting Rick Unland]
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=