home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / bgui.lzx / bgui / Classes / ARexxClass / arexxclass.doc < prev    next >
Encoding:
Text File  |  1995-04-24  |  10.7 KB  |  271 lines
  1.  
  2.                File: arexxclass.doc
  3.         Description: ARexxClass documentation.
  4.           Copyright: (C) Copyright 1994-1995 Jaba Development.
  5.                      (C) Copyright 1994-1995 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8. ------------------------------------------------------------------------------
  9.  
  10. TABLE OF CONTENTS
  11.  
  12. arexxclass/--background--
  13. arexxclass/Methods
  14. arexxclass/Attributes
  15.  
  16. arexxclass/--background--                            arexxclass/--background--
  17.  
  18.     NAME
  19.         Class:          arexxclass
  20.         Superclass:     ROOTCLASS
  21.         Include File    "ARexxClass.h"
  22.  
  23.     FUNCTION
  24.         To provide you with a very easy way to implement an ARexx host in your
  25.         programs.  The  class  will  take over all the grunt work for you like
  26.         host setup, message handling, argument parsing and so on. All you have
  27.         to do is to create an object from  this class  and  write  the command
  28.         code.
  29.  
  30.     NOTE
  31.         This class  is  provided as source code and two linkable ".o" modules.
  32.         To make  use  of  this class you should link with the  supplied object
  33.         code or,  if  your  compiler  does  not  like these object modules,  a
  34.         re-compiled version of the source.
  35.  
  36.         Also your program must open the following libraries:
  37.  
  38.         intuition.library       - V37 or better.
  39.         utility.library         - V37 or better.
  40.         rexxsyslib.library      - V36 or better.
  41.         dos.library             - V37 or better.
  42.  
  43.         Ofcourse these libraries must remain open until you are done using the
  44.         class.
  45.  
  46.         There are two linkable object modules supplied both compiled with DICE
  47.         v3.0. "arexxclass.o"  is  an  object  module  which uses normal system
  48.         memory allocation/deallocation routines. "arexxclass_p.o" is an object
  49.         module which uses memory pools for it's allocations. You will need the
  50.         3.1 amiga.lib  to  link with the later. Both modules are compiled with
  51.         registered args turned off.
  52.  
  53.         The source  of  this  class  is based on the source output of ARexxBox
  54.         V1.12 by Michael Baltzer.
  55.  
  56. arexxclass/Methods                                          arexxclass/Methods
  57.  
  58.     NEW METHODS
  59.         ACM_HANDLE_EVENT -- This method will handle all incoming  and outgoing
  60.                 message traffic from your host.   When  you are  signalled you
  61.                 simply call this method and everything is done for you.
  62.  
  63.                 No return code is specified for this method.
  64.  
  65.         ACM_EXECUTE -- This method allows you to  execute one of  the commands
  66.                 from your host. Any unknown command is shipped of to the ARexx
  67.                 server.    This  method  uses  the  following  custom  message
  68.                 structure:
  69.  
  70.                 struct acmExecute {
  71.                         ULONG           MethodID;       /* ACM_EXECUTE */
  72.                         UBYTE          *acme_CommandString;
  73.                         LONG           *acme_RC;
  74.                         LONG           *acme_RC2;
  75.                         UBYTE          *acme_Result;
  76.                         BPTR            acme_IO;
  77.                 };
  78.  
  79.                 acme_CommandString -- This must point to the command including
  80.                         arguments to execute.   If the command is found in the
  81.                         host  command  list  it  will  be  executed.   Unknown
  82.                         commands will be shipped off to the ARexx server.
  83.  
  84.                 acme_RC, acme_RC2, acme_Result --  If  you  wish to  know what
  85.                         errors occured during the execution of the command you
  86.                         may provide storage pointers here.  After  the command
  87.                         executed you  will  find  the  errors/result in  here.
  88.                         NOTE: If acme_RC is negative  it  means that  acme_RC2
  89.                               contains a pointer to an error string instead of
  90.                               an error number.
  91.  
  92.                 acme_IO -- If you execute a script using this  method  you can
  93.                         pass a pointer to the IO channel ARexx must  use here.
  94.                         This IO channel will be  closed  automatically for you
  95.                         after the command executed.
  96.  
  97.                 As errors are reported  in  acme_RC and  acme_RC2 this  method
  98.                 has no specific return code.
  99.  
  100.     CHANGED METHODS
  101.         None.
  102.  
  103. arexxclass/Attributes                                    arexxclass/Attributes
  104.  
  105.     NAME
  106.         AC_HostName -- ( STRPTR )
  107.  
  108.     FUNCTION
  109.         To supply  the  object  with  a base name it must use for it's message
  110.         port. Internally this base name is converted to find a unique version.
  111.         The class  does  this  by  appending a number to the base name. If you
  112.         need to  know the real host name simply OM_GET it after the object has
  113.         been created.
  114.  
  115.         If, for  example,  you  provide  a  base  name of "FOO" the class will
  116.         internally try  to  create a host port with the names "FOO.1", "FOO.2"
  117.         ... "FOO.99".  When  none of these names is unique the object creation
  118.         fails.
  119.  
  120.         This attribute must be valid or the object will fail to create.
  121.  
  122.         Default is NULL. Applicability is (IG).
  123.  
  124.     NAME
  125.         AC_FileExtention -- ( STRPTR )
  126.  
  127.     FUNCTION
  128.         To establish the file extention you will be using for your host.  This
  129.         file extention is used by the ARexx server to determine  what  file it
  130.         should try to open if the original file name did not open.
  131.  
  132.         Default = "rexx". Applicability is (I)
  133.  
  134.     NAME
  135.         AC_CommandList -- ( REXXCOMMAND * )
  136.  
  137.     FUNCTION
  138.         To provide  your  host  with  it's  commands. The data must be a valid
  139.         pointer to an array of the following structures:
  140.  
  141.         typedef struct {
  142.                 UBYTE           *rc_Name;
  143.                 UBYTE           *rc_ArgTemplate;
  144.                 VOID           (*rc_Func)( REXXARGS *, struct RexxMsg * );
  145.         } REXXCOMMAND;
  146.  
  147.         rc_Name -- This must be a pointer to the command name.  Although there
  148.                 are no restrictions it is advisable that commands are in upper
  149.                 case characters.
  150.  
  151.         rc_ArgTemplate -- If your command expects arguments this must point to
  152.                 a  standard  AmigaDOS argument template string. Internally the
  153.                 class will use  ReadArgs()  to  parse  the  arguments  for the
  154.                 command.  If  your  command does not expec s arguments you can
  155.                 set this to NULL.
  156.  
  157.         rc_Func -- This must be a pointer to your command routine. The routine
  158.                 will get called as follows with the arguments on the stack:
  159.  
  160.                 VOID command_func( REXXARGS *ra, struct RexxMsg *rxm );
  161.  
  162.                 ra -- This will be a pointer to the following structure:
  163.  
  164.                 typedef struct {
  165.                         ULONG   *ra_ArgList;
  166.                         LONG     ra_RC;
  167.                         LONG     ra_RC2;
  168.                         UBYTE   *ra_Result;
  169.                 } REXXARGS;
  170.  
  171.                 ra_ArgList -- This will point to an array of ULONGs containing
  172.                         the result of the ReadArgs() parse.  This  may also be
  173.                         NULL in which case  the  command  does  not expect any
  174.                         arguments.
  175.  
  176.                 ra_RC -- In here you can store the primary error (if any).
  177.  
  178.                 ra_RC2 -- In here you can store the secundary error.   If  you
  179.                         wish to  make  this  a  descriptive  error  string you
  180.                         should provide a negative primary error code I.E.:
  181.  
  182.                         VOID command( REXXARGS *ra, struct RexxMsg *rxm )
  183.                         {
  184.                                 /* Do your stuff... */
  185.  
  186.                                 ra->ra_RC  = -RC_ERROR;
  187.                                 ra->ra_RC2 = (LONG)"Out of memory!";
  188.                         }
  189.  
  190.                         If you want to provide a descriptive  error  code  you
  191.                         should provide a positive primary error code I.E.:
  192.  
  193.                         VOID command( REXXARGS *ra, struct RexxMsg *rxm )
  194.                         {
  195.                                 /* Do your stuff... */
  196.  
  197.                                 ra->ra_RC  = RC_ERROR;
  198.                                 ra->ra_RC2 = IoErr();
  199.                         }
  200.  
  201.                 ra_Result -- If your command has a result  of  some  kind  you
  202.                         should store a pointer to that result in here.  Please
  203.                         note that this is expected to  be  a  string so if you
  204.                         wish to return a  numeric  result  you  will  have  to
  205.                         convert it to a string first I.E.:
  206.  
  207.                         UBYTE                   buf[ 16 ];
  208.  
  209.                         VOID command( REXXARGS *ra, struct RexxMsg *rxm )
  210.                         {
  211.                                 UWORD                   number;
  212.  
  213.                                 /* Do your stuff... */
  214.  
  215.                                 if ( rxm && rxm->rm_Action & RXFF_RESULT ) {
  216.                                         sprintf( buf, "%ld", number );
  217.                                         ra->ra_Result = buf;
  218.                                 }
  219.                         }
  220.  
  221.         rxm -- This points to the RexxMessage structure of your command.  You
  222.                may  use this to setup  ARexx  variables  or  stem  variables.
  223.                Please note that this may be NULL.
  224.  
  225.         The array must be terminated with a NULL rc_Name field.
  226.  
  227.         This tag must be valid or the object will fail to create.
  228.  
  229.         Default is NULL. Applicability is (I).
  230.  
  231.     NAME
  232.         AC_ErrorCode -- ( ULONG * )
  233.  
  234.     FUNCTION
  235.         To provide storage space for the class to  store a  descriptive  error
  236.         code if the object creation fails.  If the object  creation  fails the
  237.         storage space provided can contain any of the following error codes:
  238.  
  239.         RXERR_NO_COMMAND_LIST     -- No command list was provided.
  240.         RXERR_NO_PORT_NAME        -- No host base name was provided.
  241.         RXERR_PORT_ALREADY_EXISTS -- The  class  was unable to create a unique
  242.                                      name of the base name you provided.
  243.         RXERR_OUT_OF_MEMORY       -- Not enough free memory.
  244.  
  245.         Default is NULL. Applicability is (I).
  246.  
  247.    SEE ALSO
  248.         AC_HostName, AC_CommandList
  249.  
  250.    NAME
  251.         AC_RexxHostMask -- ( ULONG * )
  252.  
  253.    FUNCTION
  254.         To obtain the host port signal mask.
  255.  
  256.         Example:
  257.  
  258.         Object *AO_Rexx;
  259.         ULONG   mask, sigrec;
  260.  
  261.         GetAttr( AC_RexxHostMask, AO_Rexx, &mask );
  262.  
  263.         do {
  264.                 sigrec = Wait( mask );
  265.  
  266.                 if ( sigrec & mask )
  267.                         DoMethod( AO_Rexx, ACM_HANDLE_EVENT );
  268.         } while ( ... );
  269.  
  270.         Applicability is (G)
  271.