@database ARexxSupervisor.guide

@node Main "ARexxSupervisor.doc - Table of contents"
Welcome  to  ARexxSupervisor  1.0,  by Frédéric DELACROIX.  This is the doc
file  that  should always be with the program for public distribution.  And
now, like every reasonnable guide file,here is a TOC:

				TABLE OF CONTENTS

@{"COPYRIGHT,DISTRIBUTION and DISCLAMER" link copyright}    <-- This is very important!
@{"CREDITS and SPECIAL THANKS" link credits}

@{"SYSTEM REQUIREMENTS" link system}    <-- My advise is you check this!
@{"WHAT IS AREXXSUPERVISOR ?" link whatisit}
@{"STARTING AREXXSUPERVISOR" link starting}
@{"AREXXSUPERVISOR'S WINDOW" link window}

@{"FUTURE IMPROVEMENTS" link future}
@{"CONTACTING THE AUTHOR" link contact}    <-- Don't forget !
@endnode

@node copyright "Copyright,distribution and disclaimer"
ARexxSupervisor  1.0  was  entirely written by F.DELACROIX on the wonderful
HiSoft DevPac 3.  IT REMAINS COPYRIGHTED BY ME.  However,the program is re-
leased  as  SHAREWARE.  This means that public distribution is allowed (and
encouraged) as long as:

	-  NO  profit is made beyond MINIMAL copy&posting fees (you may not
charge more than Fred Fish does for a single AmigaLib Disk)

	-  The  WHOLE  archive  (or,say,  all  files)  is (are) distributed
UNMODIFIED   IN   ANY   WAY.    There   is   although  one  exception:   as
ARexxSupervisor  is  provided in two languages (for now),french and english
,you  may spread only one of them (this applies only to the guide files for
now,but  locali-  zation is coming soon).  Yet,I'd prefer you to distribute
both  if  you are releasing ARexxSupervisor on a wide-spread internationnal
PD-library.

Please  note  also  that  ARexxSupervisor is SHAREWARE, meaning that if you
continue  use it after an evaluation period you MUST send me a contribution
(suggested  amount is $10 or equivalent).  The source is available from me,
just  add  $10  dollars  more.   My address can be found at the end of this
document.

As  always,  I  must  mention  that  I  do  not make ANY guarantee that the
program,although  tested  a  lot,  does  not contain any bug,and,therefore,
should  a  problem  arise  and cause direct or indirect damage, I CANNOT BE
HELD  RESPONSIBLE  FOR ANYTHING.  YOU USE AREXXSUPERVISOR AT YOUR OWN RISK.
@endnode

@node credits "Credits and special thanks"
ARexxSupervisor was written on an Amiga 500 (OS 2.04),running the marvelous
HiSoft  Devpac  3.   ARexx  is  copyright © 1987 by William S.  Hawes.  The
great  reqtools.library  is Copyright © Nico François (it is not sup- plied
in  this  archive  but  you  could find it everywhere in public domain disk
libraries).   The  Graphic  User  Interface  was created by GadToolsBox 2.0
(available  on  Fish 852) which is ©1991-93 Jaba Development, optimized and
adapted by myself.

My special thanx and greetinks to:
- Serge HAMMOUCHE from France-Festival-Distribution
- Commodore and Jay Miner for designing the Amiga ;-)
- Yves QUIQUEMPOIS
- François JACOBS
- Philippe DUSSART
@endnode

@node system "System Requirements"
ARexxSupervisor will need the following to run:

	-  Kickstart  V37 or newer (OS 2.04), it will not run on the old OS
1.3.  The only thing you can do in this case is...  UPGRADE !

	-  reqtools.library V38+ © Nico François, which can be found nearly
everywhere (not Nico, the library :-)

	-  ARexx.   This  is  normally provided on your Workbench 2.0 disk.
Note  that  you  must  run RexxMast BEFORE running ARexxSupervisor (this is
normally done is the 2.0 startup-sequence)

	-  the  amigaguide.library  (which  you  possess,  because  you are
reading  this  file).   It  can  be found on Fish 870.  However it is not a
fatal error not having installed this library, the online-help feature will
simply be disabled.

	- some knowledge about programming & debugging ARexx interfaces!
@endnode

@node whatisit "What is ARexxSupervisor ?"
ARexxSupervisor  is  mainly  a  tool for the developpers of you who want to
integrate and properly test/debug ARexx interfaces in their programs.

ARexxSupervisor provides a means of mouse-controlling the data that is sent
to  a valid ARexx port.  Be careful however, it is easy to make destructive
actions or provoke deadlocks or gurus.
@endnode

@node starting "Starting ARexxSupervisor"
ARexxSupervisor can be launched either from @{"CLI" link cli} or from @{"Workbench" link workbench}.
@endnode

@node cli "Starting ARexxSupervisor from CLI"
CLI usage is: ARexxSupervisor [PUBSCREEN <name>]
              PUBSCREEN/K
This  means that you can make ARexxSupervisor's window appear on any public
screen that is already opened.  Example:
ARexxSupervisor PUBSCREEN DEVPAC.1 or ARexxSupervisor PUBSCREEN=DEVPAC.1
will make ARexxSupervisor use Devpac 3's screen.  The default is to use the
default  public  screen  (normally  the  Workbench  screen).  If the public
screen is not opened or is in private state,ARexxSupervisor "falls back" to
the default.
@endnode

@node workbench "Starting ARexxSupervisor from Workbench"
You  start ARexxSupervisor from the Workbench by simply double-clicking its
icon.   There  is  currently  one tooltype defined:  PUBSCREEN=<name>.  See
@{"CLI usage" link cli} for more information.
@endnode

@node window "ARexxSupervisor's window"
When  ARexxSupervisor  comes  up,it opens a large window (it should however
fit  on  an NTSC screen), with a nice GadTools interface made of a bunch of
gadgets.   Those  of you who are already familiar with ARexx will recognize
all  fields  of an ARexxMessage structure,plus some more auxiliary gadgets.
Let's see their use individually:

@{"?" link infoBUT}			@{"Type" link typeCYC}			@{"Result" link resultCB}
@{"Help" link helpBUT}			@{"FileExt" link fileextSTR}			@{"String" link stringCB}
@{"I" link iconifyBUT}			@{"StdIn" link stdinSTR}			@{"Token" link tokenCB}
@{"Q" link quitBUT}			@{"StdOut" link stdoutSTR}			@{"Send Message" link sendmessageBUT}
@{"Halt" link haltBUT}			@{"ARGx" link argSTR}   (x=0...F)	@{"Result1" link result1TEX}
@{"Global Trace" link globaltraceCB}		@{"NoIO" link noioCB}			@{"Result2" link result2TEX}
@{"Port" link portSTR}

Please note that most of these gadgets have an underlined character,meaning
that  their functions can be accessed by the keyboard by pressing the given
key.   Exceptions  to  this rule are the iconification gadget (which has no
keyboard shortcut), and the Help gadget, which can be accessed via the Help
key.   Of  course,  for these shortcuts to work,there must not be an active
string gadget.

Another feature is the Help key,which,when pressed while a string gadget is
active  (apart  from  the Port and FileExt string gadgets) brings up a file
requester.  The contents of this file requester are then put in the gadget.
@endnode

@node infoBUT "? gadget / ? key: Information"
Nothing really alarming:  this brings up the information requester, showing
some importants things like the shareware notice and my address.
@endnode

@node helpBUT "Help gadget / Help key: Show help file"
This  gadget  displays this file (but maybe that's how you had it displayed
just now!).  For this feature to work correctly,you need amigaguide.library
tobe  installed  in your LIBS:  directory (see @{"SYSTEM REQUIREMENTS" link system}),
otherwise  it  won't  show  up.   The file you're reading now must be named
ARexxSupervisor.guide  and be in your amigaguide path (which can be set via
the  SetEnv command,see your amigaguide documentation).  I suggest you copy
it to your HELP:  directory.

If  the file is successfully displayed by AmigaGuide, the program is put to
sleep until all AmigaGuide windows are closed.
@endnode

@node iconifyBUT "I gadget: Iconification"
This gadget is used to iconify the program when you think it takes too much
room  on  your  screen.   You  will  of  course  need the workbench.library
installed  to do this.  The result will be closing of the main window and a
new  AppIcon  will  be added on the workbench screen.  If an error in crea-
ting the AppIcon occurs, the window won't close.

When  you  want  the program to come back, just double-click on the AppIcon
and  a requester will pop up asking if you want to wake the program,quit or
cancel the operation.  Click on Wake up and the window will re-open.  If it
cannot  (because of low memory...),you will have to wait some more.  If you
chose  Quit,the program will finish,unless it is still waiting for ARexx to
reply a message previously sent (don't want to wake the guru,do you?  :-)

Plus,  if  ARexxSupervisor  was  waiting for a reply, it will automatically
wake up on receiving it.  This is it.
@endnode

@node quitBUT "Q gadget / Q key / close gadget: Quit program"
Do I really have to explain this function?  This will cause ARexxSupervisor
to  end,  unless it is waiting for a reply, in which case a requester would
pop up, giving you the opportunity to iconify instead.
@endnode

@node haltBUT "Halt gadget / H key: Stop execution of all ARexx programs"
This  function  is  absolutely the same as if you typed HI in a Shell:  all
ARexx  scripts  will stop (unless they trapped this case) and will issue an
"execution halted" message.

Note that this must be your LAST chance to stop a program that has gone out
of control.  Indeed, stopping all programs is not a polite thing to do; you
could destroy important data for other processes.
@endnode

@node globaltraceCB "Global trace gadget / G key: force all ARexx programs into trace mode"
This  is  a  checkbox, so it has two states:  activated or not.  When it is
not  selected,  all  ARexx  programs run normally.  When it is checked, all
ARexx programs will come into interactive trace mode.  For the execution of
a  program to continue,you must press RETURN in its output console (it MUST
be  an  interactive  console)  or  in  the  global tracing console if it is
opened.   So  you  can examine variables...  to see what is wrong with your
program.

But  again, beware that is function affects the whole environment, and thus
must be used with caution.

Note:   you would get the same result by running the program TS for set and
TE for clear.
@endnode

@node portSTR "Port gadget / P key: destination port name"
Enter  there  the name of the port to be addressed for sending the message.
Note that this name IS case-sensitive.  The port need not be opened at that
time,  but  it will have to when you "Send Message".  This will for example
be  AMIGAGUIDE.1 for the first occurence of an amigaguide process.  Also,be
careful what you send to someone.  Normally,for example, only ARexx is able
to  understand messages like Open Tracing Console.  It is very easy to send
nonsense messages!

The port at which you can reach ARexx's master process is named REXX.
@endnode

@node typeCYC "Type gadget / Y key: type of the RexxMsg"
This cycle gadget controls the type of the Message that is to be sent.

These types are:
@{"Send command" link sendcommand}			@{"Add clip entry" link addclipentry}
@{"Invoke function" link invokefunction}			@{"Remove clip entry" link removeclipentry}
@{"Close tracing console" link closetracingconsole}		@{"Add library" link addlibrary}
@{"Open tracing console" link opentracingconsole}		@{"Remove library" link removelibrary}

At  send  time,the  type  field will be or'ed with the modifier flags (only
significant  ones).   Normally,only Send command and Invoke function should
be sent to other hosts than REXX.
@endnode

@node sendcommand "Send command"
This  means that the message is a command to be executed by the host.  ARG0
contains  normally  the  name of the command (which is normally a file name
for REXX) followed by the argument string.  ARG1 to ARGF are unused.

The  "Token"  modifier  flag  however  forces  ARexx  to tokenize the whole
string,which can then have many argument strings.

"NoIO" will prevent the new process from inheriting the StdIO streams.

The  "String"  modifier  will tell REXX this is "string file" rather than a
file name.

The  "Result"  modifier  will  request  the  host to send a result for this
command (commands generally do not return a result).
@endnode

@node invokefunction "Invoke function"
The message will request the host to perform an action,from which it should
return  a  result.   The  function name is in ARG0 and the arguments are in
ARG1 to ARGF.

A  result  is  requested by supplying the corresponding modifier flag.  The
"String" and "NoIO" modifiers have the same effect as for Send Command.

The  result  will be placed in Result2 if there was no error (if Error1 was
0).
@endnode

@node closetracingconsole "Close tracing console"
This message will make the global tracing console close if it was open.

It is only meaningful for the REXX port.
@endnode

@node opentracingconsole "Open tracing console"
This  will  make the global tracing console open, and all programs that are
in trace mode will send their tracing information to this window instead of
their   StdErr  or  StdOut  streams  (which  might  not  be  interactive!).
However,it  can  be  confusing  if  several programs are in trace mode at a
time.

Send only to REXX.
@endnode

@node addclipentry "Add clip entry"
ARexx  maintains a "clip list" which is shared by all processes.  This adds
an  entry  to  this  list.  ARG0 is the name of the clip entry, ARG1 is its
value.   ARG2 is automatically filled with the length of ARG1.  This is one
restriction of using ARexxSupervisor:  you cannot put any kind of data in a
clip entry,you must use a string.  Hope this won't matter too much.

Send only to REXX.
@endnode

@node removeclipentry "Remove clip entry"
This  will  simply remove an entry from the clip list.  ARG0 is the name of
the entry to remove.

Send only to REXX.
@endnode

@node addlibrary "Add library"
This  type  will  add  a  function library to ARexx's internal list,so that
programs can access their functions.

ARG0 is the name of the library (ex:amigaguide.library),

ARG1 is the priority whithin this list.It must be a number between -100 and
100.  (ex:  0)

ARG2 is the query offset for the library.  For amigaguide,this is -30.

ARG3 is the version requested for the library.  0 will match any version.

This message is intended for REXX only.
@endnode

@node removelibrary "Remove library"
This  message  will  of  course  remove  the specified library from ARexx's
internal library list.

ARG0 is the name of the library to remove. ex:amigaguide.library.
@endnode

@node fileextSTR "FileExt gadget / X key: File extension"
This  is  the  file  extension  that  will  be  appended to a filename when
searching  for  an  ARexx program.  This mechanism is used to differentiate
programs written for different hosts (.rexx,.editor, etc...).
@endnode

@node stdinSTR "StdIn gadget / I key: Standard input stream"
This  is  the  stream  that will be used for input.  If This is not a valid
filename  (like  CON:////Hello),  then the StdIn will be the same stream as
StdOut.  And If StdOut is not valid either, NIL:  will be used.

Please  remember  that  this  stream is ALWAYS opened by ARexxSupervisor in
MODE_OLDFILE,  whereas  StdOut  is  ALWAYS  opened  in MODE_NEWFILE.  So be
careful.

If  you press help while the gadget is active,a file requester will appear.
@endnode

@node stdoutSTR "StdOut gadget / O key: Standard output stream"
Here  is  the  other stream:  the one that is used for outputs.  Be careful
that  if  you intend to use the tracing features of ARexx, you must provide
an  interactive  stream,or deadlocks can happen.  To be safe, you may first
open  the  global  tracing  console.  See description of the @{"StdIn" link stdinSTR}
gadget for more info.
@endnode

@node argSTR "ARGx gadgets / 0..F keys: Argument strings"
These  16 string gadgets are the argument that will be used for passing the
message  to  the  host.  Their use can vary widely depending on the type of
message,  but  the  cases  where all 16 slots are used are very scarce.  In
fact  this  can  only happen for functions.  If you press Help while one of
these gadgets is active, a file requester appears.
@endnode

@node noioCB "NoIO gadget / N key: NoIO modifier flag"
When  checked,this  modifier  flag suppresses inheritance of the IO streams
for the child process (StdIn and StdOut are ignored).
@endnode

@node resultCB "Result gadget / R key: Result modifier flag"
This  flag  must be set when you want the command or function you invoke to
return you a result.
@endnode

@node stringCB "String gadget / S key: String modifier flag"
This modifier tells ARexx that the ARG0 string is not the name of a program
but the program itself (it is a "String file").
@endnode

@node tokenCB "Token gadget / T key: Token modifier flag"
This  flag  tells  ARexx to parse ARG0 so that the command receives not one
but many argument strings.
@endnode

@node sendmessageBUT "Send message gadget/ M key: Send message to host"
This  button  will actually create the RexxMsg structure and send it to the
host  whose name is given in the @{"Port" link portSTR} gadget.  All fields
are  filled  and  the  message  is  sent,  ARexxSupervisor disables all its
gadgets except iconification,help,information,Halt,Trace,Quit.  Quitting is
however  disabled  as  long  as  the message is not replied.  ARexx usually
replies  the  message  when the program is over.  ARexxSupervisor then sets
the Result gadgets accordingly,enables the gadgets again and resumes normal
operation.
@endnode

@node result1TEX "Result1 gadget: Primary result code"
This  is  the  primary  result code from the function previously performed.
Usually,  a  non-null  value indicates an error code or severity level.  If
Result2 is empty,this is a return code from a function, shown as:
Return  code:   %ld.  If Result2 is not null, this an error severity level,
shown  as:   Severity  level:   %ld  , and Result2 contains the Error code:
Error code:  %ld.

If  Result1  is  NULL,  Result2 may contain the result from the function or
command   that   was   requested   by   the  Result  modifier  flag  (still
following?:-).

The value of this gadget may be found in the environment variable named
AResult1.
@endnode

@node result2TEX "Result2 gadget: Secondary result code"
This  is  the  secondary result from the previous call.  For further infor-
mation see the @{"Result1" link result1TEX} gadget.

The  value  of  this  gadget  is copied into the environment variable named
AResult2.
@endnode

@node future "Future improvements"
ARexxSupervisor  is of course subject to improvements.  If you can think of
something  you  would  like to see included in the next release,just let me
know.  Some of them I already have in mind:
	- total localization
	- auto-RexxMast
	- an ARexx port !
	- whatever you can think of !
@endnode

@node contact "Contacting the author"
Please don't forget that ARexxSupervisor is SHAREWARE.  If you find it use-
ful,  send  me  a  little contribution (I suggest $10 or equivalent) to the
address below.
			Frédéric DELACROIX
			5 rue d'Artres
			59269 QUERENAING
			FRANCE, EARTH

Also, any bug report/suggestion/postcards are welcome.

Note  to  translators:   If  you  make  a  translated  version  of this doc
file,send it to me so that I can include it in the next release.
@endnode