

                         Review of
                      Eric  Gigure's         
           "Amiga Programmer's Guide to ARexx"
                       Reviewed by
                      Paul Gittings
                   2/27 Leichhardt St.,
                         Glebe,
                       NSW  2037
                      Australia

                   PH: 61+2+6928038
   Internet/ACSnet/AARnet: paulg@kralizec.zeta.org.au



If you have ever wanted to know how to make your application 
programs ARexx aware, then the "Amiga Programmer's Guide to 
ARexx" is the book for you.  Even though this book is over  
two years old many Amiga programmers will not have seen this 
book since it is only available through Commodore's Software 
Support department. I ordered my copy after seeing the book 
mentioned in an Amiga programming news group on the Internet.



The copy I received was not a book as such but 218 photo-
copied pages in a plastic ring binder.  Having received 
similarly prepared documentation from Commodore Australia in 
the past I was not surprised by this.  What did surprise me 
was the quality of the contents of the book.  This is one 
very well organized and written book and I sincerely hope to 
see it as an extra volume in the ROM Kernel Reference Manuals 
so that it can get the exposure (and binding) it deserves.



The programmer in the title of this book refers to an Amiga 
applications programmer, not a programmer interested in 
writing ARexx scripts. It was written with application 
programmers in mind, to supply them with the information 
necessary to add the power of ARexx to their new application 
programs.  The author expects his readers to have knowledge 
of ARexx, C, and Amiga programming in general. 



Since most people who will buy this book will already more 
than likely own some other book on ARexx programming I was 
surprised to find that the first few chapters do noting more 
than regurgitate the contents of William Hawes' "ARexx User's 
Reference Manual"; complete with yet another ARexx function 
reference (at lest the functions are listed in alphabetical 
order in the index). I think the average reader will skip 
over these early chapters and may use them later as needed 
for reference. 



It was in these early chapters where I first encountered a 
flaw which shows up through out the book; some cross 
references in the text instead of giving a page number or 
chapter number simply have "??". 



Adding ARexx support to your application programmers is all 
about messages; creating a message port, waiting for a 
message, processing a message and then replying to it.  The 
author introduces these steps with a simple example of a 
passive Passive Host (process incoming messages but does not 
send any of its own).  Each step in the process is very 
clearly explained and a complete C program listing is 
supplied (all source can also be found on the companion 
disk).  This C program, as are all others in the book, has 
been compiled with both the SAS/C Amiga C compiler (version 
5.10) and the Manx Aztec C compiler (version5.0e) using 2.0 
headers.  Since I don't own either of these compilers I can't 
verify this, but the examples I have tried all compile under 
DICE and GCC C compilers; some needed a bit of coaxing.





Having described how to write a passive Host the next logical 
step is to describe how to write an active host; one that 
sends messages to the ARexx resident process or to other 
hosts.  Messages to the ARexx resident process could  for 
example add/delete a function host or library, call an ARexx 
function or modify the Clip List. The steps required to do 
each of these options are very similar; the main steps are 
the same only the arguments and flags differ.  The standard 
steps are  fully explained via an example program; which 
calls a user specified ARexx function or sends a user 
supplied command string to the ARexx resident host. In 
addition to this example the arguments and flag values for 
the for the other types of messages explained.



Having described how to program a Host, one step at a time,  
to send and receive messages Gigure goes on to show that 
there is an easier way; using the Simple ARexx Interface, 
SimpleRexx.  The SimpleRexx library was written by Mike Sinz 
as a way to create and maintain an ARexx port in a safe and 
re-entrant way and at the same time  hide much of the 
gruntwork from the application programmer. A whole chapter  
of the book is given over to the description of the routines 
that make up this library (the library itself can be found on 
the book's companion disk).  



The final two chapters of the book examine how to extend the  
ARexx, language one through the development of Functions 
hosts and the other through function libraries.  A Function 
host is  an application with an ARexx port that knows how to 
deal with function call messages; an example of a Function 
host is the ARexx resident process. When an ARexx program 
encounters a call to a function (whose name it does not 
recognize) it queries each function host (and function 
libraries) to see if it is capable of handling the call, this 
search will continue until a host with a matching function is 
found (and the function is executed) or until all hosts  have 
been searched.  There is not much more to writing a function 
host that there was to an active host.  This chapter makes 
some additional comments on arguments and return codes and 
also explains how an application registers itself as a 
function host.  An example function host, written using the 
SimpleRexx routines, is given which adds functions to set or 
retrieve the values of the Amiga's colour registers.



The other way to extend ARexx is by use of function 
libraries.  A function library is a standard Amiga shared 
library with some additional conventions; the main one being 
the inclusion of a dispatch function.  The dispatch function 
is called when an ARexx program is looking for a function, 
the dispatch function will execute the desired function if 
the library contains it. The setting up a function library is 
a bit more involved than that of a function host.  The book 
reviews the features and requirements of standard Amiga 
libraries before proceeding on to the function library 
specific items. The book covers the creating of function 
libraries with both SAS/C and Aztec C (skeleton code is 
supplied for both compilers).



The book is finished off with 3 appendices (which duplicate 
material found in Hawes' book) and a comprehensive index. 
Other than the missing chapter references, the book is very 
well laid out and presented.  It has a clean and functional 
look about it. It is extremely well written. Much thought 
also seems to have gone into the writing of the examples; 
they are all well commented, not too trivial but still short 
enough to be easily understood. Some people may feel it 
unnecessary to list the source when the material can be found 
on the disk (I personally prefer it this way), also I wonder 
at the need to have ARexx functions described yet again with 
the inclusion of the material from Hawes' book, but I guess 
for the sake of completeness they are required.  The only 
real problem I have with the book is its general lack of 
availability.  I am sure if this book was more readily 
available that it would prove to be very popular amongst the 
Amiga programming community. This book is a must for anybody 
interested in adding ARexx functionality to their application 
programs or just plain interested in learning more about the 
workings of ARexx.



