test/rexx/simplerexx/SimpleRexx.doc

   1                                 SimpleRexx
   2                                     by
   3                                Michael Sinz
   4
   5               A Simplified Interface into the world of ARexx
   6
   7
   8      ARexx,  ARexx,  ARexx.    2.0  has  ARexx.   So, why and how do I
   9      support ARexx?
  10
  11      The "Why?" has been answered elsewhere and that is not  what this
  12      article is  about.   Let it suffice that you should support ARexx
  13      within your application.  It  is  a  standard  that  Commodore is
  14      pushing and  we hope  that all  new applications  will have ARexx
  15      support.
  16
  17      As to the "How?",  that  is  what  this  article  is  about.   We
  18      understand that  your existing software may not currently support
  19      ARexx and that some of you may never even have looked at  what is
  20      needed to  support ARexx.   New applications can be designed with
  21      ARexx support in mind  and, with  the advent  of the  AppShell by
  22      David Junod,  the work  involved to support ARexx is nothing more
  23      than  what  is  needed  to  support   the  features   within  you
  24      application.    However,  existing  code  may  not  move into the
  25      AppShell to  easily and  you may  wish to  do a  minor upgrade to
  26      your application to support ARexx.
  27
  28      SimpleRexx is  a set  of routines that handle the low-level ARexx
  29      work for you in such a way as to have your application  work with
  30      or without ARexx on the target system.  The goal of SimpleRexx is
  31      to make adding at least the minimum level of ARexx  support to an
  32      application a trivial task.
  33
  34
  35                             Working with ARexx
  36
  37      REXX  is,  at  its  heart,  a  string  processing language.  Most
  38      everything that happens in REXX is in the form of  a string; even
  39      numbers are passed as ASCII representations in most situations.
  40
  41      The Amiga  implementation of REXX, known as ARexx, and is part of
  42      Release  2.0  of  AmigaDOS.      ARexx   has   a   very  complete
  43      implementation of  the REXX language plus the ability to send and
  44      receive control messages from "outside" sources.   ARexx  the can
  45      operate  on  them  in  synchronous fashion.  The messages contain
  46      text strings that are then interpreted by ARexx  as REXX commands
  47      or by the "outside" source (the Application) as its commands.
  48
  49      An application  that "supports ARexx" is one that can receive and
  50      send ARexx messages.  The messages  are, like  the REXX language,
  51      string  based  and  contain  the  command string of the operation
  52      wanted.
  53
  54      To make this even more interesting,  there are  ways to  send and
  55      receive data from ARexx.  The data can come in the message itself
  56      or via the ARexx RVI (Rexx Variable Interface).   In  either case
  57      data  can  be  transferred  to  and from ARexx.  A complete ARexx
  58      supporting application would need to be  able to  send data  to a
  59      requesting ARexx program/script and get data from that program.
  60
  61      The following  code shows how to use the ARexx support library to
  62      send and receive ARexx messages.  It also  is a  "wrapper" around
  63      these  functions  to  provide  a simplified interface to ARexx to
  64      help promote  and simplify  the idea  of adding  ARexx support to
  65      your existing applications.
  66
  67      SimpleRexxExample.c is  a very  simple example  of the use of the
  68      calls in SimpleRexx.  The test.rexx  script is  an example script
  69      to try  running while SimpleRexxExample is running.  It will send
  70      commands  to   SimpleRexxExample   in   order   to   control  it.
  71      test.results is the output of test.rexx.
  72
  73
  74                            Overview of Functions
  75
  76      The source  to SimpleRexx  is a single file.  It is SimpleRexx.c.
  77      The  header  file  to  that  contains  the  type  definitions and
  78      prototypes for the functions is in the file SimpleRexx.h.
  79
  80      Functions  that  are  "available"  via  SimpleRexx  are  used  as
  81      follows:
  82
  83
  84           rexx_handle=InitARexx(AppBaseName,Extension)
  85
  86                This initializes a SimpleRexx context.  The rexx_handle
  87                is much  like a  file handle in that it will be used in
  88                all  other  calls  that  make  use  of  this SimpleRexx
  89                context.    Since  all SimpleRexx calls correctly check
  90                the rexx_handle before doing work, you  do not  need to
  91                check the  return result of this call.  If ARexx is not
  92                available on your system,  SimpleRexx will  just not do
  93                anything.
  94
  95
  96           port_name=ARexxName(rexx_handle)
  97
  98                This  function  returns  a  pointer  to the name of the
  99                ARexx port for your context.  The name is based  on the
 100                AppBaseName  plus   an  invocation   number  such  that
 101                multiple copies of an application can  run at  the same
 102                time.  If you have no ARexx port, it returns NULL.
 103
 104
 105           sigmask=ARexxSignal(rexx_handle)
 106
 107                This  function  returns  the  signal  bit  mask that is
 108                needed for the port that is part of your context.  This
 109                should be  combined with  other signal masks to produce
 110                the argument to the Wait() call.  This  returns NULL if
 111                there is no signal mask.
 112
 113
 114           rmsg=GetARexxMsg(rexx_handle)
 115
 116                This  function  returns  the  next Rexx message that is
 117                waiting.  rmsg==NULL if there is no message or ARexx is
 118                not around.   rmsg==REXX_RETURN_ERROR if a message sent
 119                to ARexx via SendARexxMsg() returns an error.
 120
 121
 122           ReplyARexxMsg(rexx_handle,rmsg,result,error)
 123
 124                This function  replies  the  ARexx  message  gotten via
 125                GetARexxMsg().   The "result"  is a pointer to a result
 126                string that is  returned  via  OPTIONS  RESULTS  in the
 127                RESULT ARexx variable.  If you have no result, set this
 128                to NULL.  Error is the error severity  level.   If this
 129                is 0,  the result  string will  be returned, if this is
 130                non-zero, the error level will be returned in RC.
 131
 132
 133           worked=SendARexxMsg(rexx_handle,string,StringFileFlag)
 134
 135                This function sends the string to  ARexx.   It sets the
 136                default host  to the  context and  sets the RXFB_STRING
 137                bit in the  message  if  the  "StringFileFlag"  is set.
 138                This routine  returns FALSE if the message was not sent
 139                for some reason.
 140
 141
 142           worked=SetARexxLastError(rexx_handle,rmsg,ErrorString)
 143
 144                This function uses the RVI (Rexx Variable Interface) to
 145                set  a  variable  named  <AppBaseName>.LASTERROR to the
 146                ErrorString.  This is where the  "error" message should
 147                go if  there is  an error.  This function returns FALSE
 148                if this fails for any reason.
 149
 150
 151           FreeARexx(rexx_handle)
 152
 153                This closes a SimpleRexx  context.   The rexx_handle is
 154                one that  was gotten  from InitARexx().  The routine is
 155                fully error checked so that you can pass it a  NULL and
 156                it  will  do  nothing.    This is useful if you want to
 157                just blindly use the rexx_handle.