\documentstyle[dina4,titlepage]{article} \textwidth13.5cm \begin{document} \begin{titlepage} \title{ {\Huge \bf ARexxBox}\\ {\Large \bf ARexx Interface Designer}\\ {\large Copyright \copyright 1992 by} } \author{ Michael Balzer\\ \\ Internet: balzer@heike.informatik.uni-dortmund.de\\ Zerberus: M.BALZER@AWORLD.ZER\\ \\ Wildermuthstraße 18\\ W-5828 Ennepetal 14\\ GERMANY } \date{\today} \maketitle \end{titlepage} \pagenumbering{roman} \tableofcontents \newpage \pagenumbering{arabic} \pagestyle{headings} \parskip1.5ex plus 0.5ex \parindent0ex \hyphenation{ARexx-Box Com-mand-Shell} \newcommand{\arb}{{\sc ARexxBox}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% los geht's %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Legal Stuff} \subsection{Copyright} \arb\ is copyright \copyright 1992 by Michael Balzer. All rights reserved. \arb\ is public domain software, there are no fees, payments, licenses or the like necessary, neither for the \arb\ itself nor for the generated code. But --- beeing a poor student :-) --- I certainly appreciate any donations. If you use \arb\ or its generated code to build an ARexx interface for some program (commercial, shareware or public domain), you must note this in the manual or the about requester of the program. Additionally I would like to hear about what kind of project you have done with \arb\ and what rexx commands your application supports. Please email me. \subsection{Distribution} \arb\ is public domain, you may copy it and distribute it as long as all files of the original distribution remain together and intact. I allow and encourage distribution on electronic services. With the exception of distributing this software on Commodores Native Developer's Upgrade Kits and their electronic equivalents, the \arb\ {\em must not} be sold commercially. Some german PD authors think about setting up a set of rules for selling PD software. This set of rules will most probably apply to prices of single disks as well as prices of collections such as the AmigaLibDisk CD ROMs. I herewith declare the \arb\ to fall under all clauses of this not yet existant set of rules which apply to copyrighted PD software. Most probably will the selling of PD discs with prices higher than 5 DM / 5 US\$ or as part of a CD ROM for more than 30 DM / 30 US\$ become illegal, so dealers should take care of this. \section{Introduction} You wouldn't read this manual if you were not already convinced of the importance and power of ARexx on the Amiga. So I only have to convince you of using \arb\ to implement ARexx interfaces for your programs ;-). \subsection{Why ARexxBox?} ARexxBox (inspired by the GadToolsBox by Jan van den Baard) is a tool, which greatly simplifies the design and implementation of an ARexx interface for a program. Some of the features are: \begin{itemize} \item Syntax and results of the arexx commands follows exactly the conventions suggested by the Style Guide, e.g.~ command arguments are parsed using the AmigaDOS ReadArgs function, and the keywords VAR and STEM are supported automatically. \item Each command may have an unlimited number of arguments and results. \item All ReadArgs template options are allowed for arguments and are supported {\em automatically}. For results, the options /N and /M are supported. \item Graphical user interface (designed using GadToolsBox :-). \item Creates C--Source: One module containing necessary basic functions and another containing the interface stub routines which you only have to add your code to. \item If desired, \arb\ can generate source for CommandShells, shells in which the user may enter arexx commands directly and view their output. \item CommandShells can be used to execute external macros. \item A program may open as many arexx ports and CommandShells as the system provides message ports. \item I already entered the standard commands suggested by the Style Guide. Example code for some of them is also included. \end{itemize} \subsection{System Requirements} There is only one real requirement for \arb\ as well as the generated code: AmigaOS 2.04 at least. There are no hardware requirements, \arb\ should run on any Amiga computer. Okay, there is {\em one} requirement: If you have only non-interlaced NTSC resolution, you have to switch overscan on to see the \arb\ window. Or set the system font to some 6 or 7 point sized... You should get a copy of Nico Fran\c{c}ois' reqtools.library if you don't already have one. To compile the generated source, you need an ANSI compatible C compiler which is also able to import functions from \verb!amiga.lib!. You need at least version 37.32 (12.11.91) of the \verb!amiga.lib! to be able to link the code. Version 37.32 of \verb!amiga.lib! comes with the Native Developer's Upgrade V37.4 (11/91), or maybe already came with your compiler. \section{Using the Program} Using \arb\ is quite normal amiga standard. If you ever used an amiga application, you can use \arb~. \subsection{Input} For entering some command definition, I suggest the following procedure: Press {\sc N}, enter the name of the ARexx command and then press {\sc Return}. \arb\ now converts the name to upper case, changes illegal character codes to underscores ('\_') and checks if the name is unique. If there is already such a command in the list, you can correct the name. Then enter the arguments. For each argument press {\sc E} and enter the name. \arb\ will check this name too. Proceed the same way with results, except the shortcut for a new result field is {\sc W}. You may move arguments and results around after selecting them, using the corresponding `up' and `do' gadgets, or you could delete them using the corresponding `Remove' gadget. Enter template options in ReadArgs style (see AutoDocs for DOS), for example \verb!ARG1/K/N! or \verb!LIST/M!. Only options \verb!/M! for list and \verb!/N! for numeric type are allowed for result fields. \subsection{MsgPort Basename} The `MsgPort Basename' is the default base name for any opened arexx message port of the application. The generated functions automatically append some incrementing number to this name until a port can be opened without conflict. The application should provide (as shown in the demo code) an argument or tooltype named ``PORTNAME'', so the user can set the base name to something else. The new portname will be handled exactly the same way (see sample code). Additionally, `MsgPort Basename' is used to identify the ARexx scripts belonging to that application: It becomes the default file extension for the application's ARexx programs. \subsection{CommandShell} Selecting this gadget switches code generation on for the CommandShell functions. You normally should leave this option selected, as the CommandShell functions can also be useful for executing external macros. \subsection{Merge in} This function merges another \arb\ binary file into the currently loaded one. Only functions not yet defined will be included. You can use this to create complex interface definitions from various small modules of commands importing only those functions needed. \subsection{Print} Is intended to be an aid in documentation of your interface. For each command, the name, syntax and results will be printed. Suggestions for another (better) format are very welcome. \subsection{Generate Source} Starts the source generator. The selected filename will be cut to it's base name (removing any extension {\tt .c, .h or \_rxif.c}), and then will be checked for existance and coexistance with other files to keep you from destroying your work. If a file {\tt name\_rxif.c} exists, \arb\ asks if you are sure to overwrite this. This question is essential, as there is probably code of yours in that module, so you should first save this in another file. Don't answer this question too fast! You have to merge the functions of the old and the new rxif modules after generating the new one. \arb\ generates three files: {\tt {\sl name}\_rxif.c}, {\tt {\sl name}.c} and {\tt {\sl name}.h}. \section{The Generated Source} \subsection{Files} \subsubsection{Basic Module} The basic module will be named {\tt {\sl name}.c} and should not be edited. It contains all basic functions of the ARexx interface, functions for sending ARexx commands, for managing rexx hosts, the ARexx dispatcher and maybe the functions for the CommandShell. You can find the exact descriptions of these functions in the included autodoc style formatted file \verb!ARexxBox.doc!. \subsubsection{Headerfile} The header file will be named {\tt {\sl name}.h}. It contains all structs and declarations of basic functions and rexx interface functions as well as the definitions of the corresponding data structures for parameters. Have a look at such a file to learn more. The define \verb!REXX_EXTENSION!\ contains the standard file extension for ARexx programs belonging to your application. So a \verb!SendRexxCommand(host, "test")!\ will try to start the ARexx script \verb!test.!. The extension is the same as the name used for message ports, which in turn should be the common project id (see Style Guide) for your application. The RexxHost structure contains a pointer to the message port, the ports name, a reply counter for unreplied messages and a pointer to a {\tt RDArgs} structure for argument parsing. For each new host, the management function {\tt SetupARexxHost()} will create a new instance of this structure. The string variable \verb!RexxPortBaseName!\ contains the base name for all message ports. \subsubsection{The Data Structures} Each ARexx command has a corresponding rxif rexx interface function with an attached data structure for the parameters and result codes. This structure consists of at least the two return code fields rc and rc2. If there are arguments to the function, the structure will also have a substructure called `arg' and if there are result fields, they will be contained in another substructure `res'. The substructures contain one variable for each entry in the corresponding list (args or results), the variable name is derived from the name in the list by converting the name to lower case (and removing the options). Example: An argument {\tt FILENAME/A/K} can be accessed from C through the variable \\ {\tt rxd\_struct.arg.filename}. The type of a variable will be \verb!char *! for text strings, \verb!long *! for numeric values (option /N). Boolean values (option /S or /T) will be simple \verb!long! types. Lists (option /M) will be represented by a pointer to an array of \verb!char *! resp. \verb!long *! (therefore \verb!char **! resp. \verb!long **!). The lists may have any length, the end of a list is marked by a NULL pointer in the array. The types and meanings of the result fields are following exactly the same manner. \subsubsection{Interface Module} The interface module (named {\tt {\sl name}\_rxif.c}) contains one function body for each defined ARexx command, in which you normally just can insert your special code and that's it. \subsection{Interface Functions} Each interface function will be called three times by the parser, first time for allocating memory for the parameter structure and inserting default values there, second time to actually do the work\footnote{Rem.: This call will only occur if the parsing was okay}, and third time for freeing the allocated memory. Thus it is possible to use your own local variables without hurting the reentrance ability (for multiple hosts). The local variables must be added to the parameter structure. To do this, you just define a new local structure with the original structure beeing a substructure of the new one, like this: \begin{verbatim} void rx_help( ..., struct rxd_help **rxd, ... ) { struct myrxd { struct rxd_help rxd; /* insert local variables here! */ ... } *rd = (struct myrxd *) *rxd; ... } \end{verbatim} The code tells you, which part of an interface function will be called when. \subsection{Results} The results of an ARexx command have to be assigned to the fields of the --- if existant --- substructure {\tt res} of the {\tt rxd} structure. The names and data types of the fields correspond to the names and template options of their command definition. So you alway return {\em pointers} to data, pointers to charaters or longs or arrays of such pointers, where a NULL entry marks the end. The formatting of the results according to the user--desired form will be done by the \arb\ routines. If none of the keywords VAR or STEM was given, the result will be in VAR format and will be placed into the common ARexx variable {\tt RESULT}. The STEM format consists of a list of assignments, which each have a variable name and the assigned value. A variable name is built from the supplied argument for STEM and the name of the result field followed by a dot and then either the word ``count'' or an index number. The first list entry will always be ``count'', yielding the number of values in the list. Example: The command {\tt INHALT} has a result {\tt INHLISTE/M}. An ARexx call of the form ``{\tt INHALT STEM TEST.}'' will produce a result list of the form: \begin{verbatim} TEST.INHLISTE.COUNT = TEST.INHLISTE.0 = TEST.INHLISTE.1 = ... TEST.INHLISTE.n-1 = \end{verbatim} The VAR format is derived from the STEM format by concatenating all list entries to one string, separated by SPACEs. Please note, that {\em you} have to take care of SPACEs in your results, if there are any, you should put quotes around the string before returning it to ARexx. \subsection{Errors} If errors occur during execution of a command, they have to be returned to the user somehow to give him a chance to react properly. ARexx normally only supplies the variable RC for this purpose. RC may contain a number, normally from 0 to 20, indicating a severity level. The \arb\ offers an extended method for this purpose. If an error occurs, the rexx routines automatically generate a new variable called RC2. This variable can hold error codes as well as error strings (descriptions), which can be used by the calling program or can be output to the user. For technical details see \verb!ARexxBox.doc!. \subsection{The Main Program} The main program has'nt much to do at all to get the rexx host up and running. It has to open {\tt exec.library}, {\tt dos.library} and {\tt rexxsyslib.library}, the first two of which will normally be opened by your compiler's startup code, so you just have to open the rexx library. Then you can create an ARexx host using the function {\tt SetupARexxHost()}. You may optionally give it another base name for the message port. All there remains to do is including the new port into the normal event loop and calling the arexx dispatcher for messages from the host's port. A CommandShell gets an input, an output (not necessarily different) and a prompt string and then runs until EOF. It is also possible to start a CommandShell asynchronously using {\tt dos.library / CreateNewProc}). The following is a (minimal) demonstration program: \begin{verbatim} #define HOSTSIG(host) (1L << host->port->mp_SigBit) void main( int argc, char *argv[] ) { struct RexxHost *myhost; BPTR fh; /* Init */ if( !(RexxSysBase = OpenLibrary( "rexxsyslib.library", 35 )) ) { printf( "No RexxSysLib\n" ); exit( 20 ); } /* open Host */ if( !(myhost = SetupARexxHost(NULL)) ) { printf( "No Host\n" ); exit( 20 ); } /* Number 1: The CommandShell... */ if( fh = Open( "CON:////CommandShell/AUTO", MODE_NEWFILE ) ) { CommandShell( myhost, fh, fh, "test> " ); Close( fh ); } else printf( "No Console\n" ); /* Number 2: 'Real' ARexx mode */ printf( "Address me on Port %s!\n", myhost->portname ); printf( "Cancel me with CTRL-C\n" ); while( 1 ) { long s = Wait( SIGBREAKF_CTRL_C | HOSTSIG(myhost) ); if( s == SIGBREAKF_CTRL_C ) break; else ARexxDispatch( myhost ); } CloseDownARexxHost( myhost ); CloseLibrary( RexxSysBase ); exit( 0 ); } \end{verbatim} \section{Other Stuff} This manual can't give you a detailed introduction to ARexx. A look at the corresponding chapters in the ``User Interface Style Guide'' by Commodore and the ``ARexx User's Reference Manual'' by William S. Hawes is strongly recommended. The \arb\ has been developed on an Amiga 2000 equipped with A2630, 7 MB RAM, GVP Series II with Quantum P210S and Seagate ST296N and a MultiVision flickerfixer plus NEC Multisync 3D. \arb\ was compiled using Manx's Aztec C 5.2a, I somehow got used to the thing... Pleese ekscuse mei bäd inglisch. \subsection{Thanks} I would like to thank the following persons: \begin{itemize} \item My active beta testers: Ralf Kaiser, Garry Glendown, Wolfgang Kueting and Stefan Zeiger. \item The Amiga--Crew of Commodore, for the Amiga and AmigaOS Release 2. \item Jan van den Baard, for his excellent GadToolsBox, which inspired me to program this tool and was a big aid for designing the user interface. \item Nico Fran\c{c}ois, for his ReqTools.Library with it's really programmer-- and user--friendly requesters. \item William S. Hawes for his marvelous Rexx port. \end{itemize} \subsection{Bug Reports and Comments} Please send me your bug reports and comments through email if possible! Please {\em always} tell me about your exact configuration when writing a bug report, and {\em always} provide a {\em minimal} sample program which reliably reproduces the bug! Describe the error as good as you can, this helps me in correcting it. Comments are very welcome! Michael Balzer \end{document}