Info on RexxHS support library and SAS 5.1 users
------------------------------------------------

To build:

    Type "rx smake" to copy the required .c and .h files from
    the parent directory.  It will run "lmk" automatically to
    build the library.


How it works:

    The only file you should really be interested in is the
    file rexxhs.c, since all the other files are just there to
    do the shared library gunk and their use is documented in
    the Amiga Programmer's Guide to ARexx.

    Basically the function library has exactly one entry point,
    called the dispatch function.  ARexx calls this entry point
    and passes a pointer to a RexxMsg structure (the same one that
    gets sent to function hosts) in one of the registers.  The
    gunk files stuff this pointer on the stack and call the "real"
    dispatch function in rexxhs.c.  This function takes the packet,
    gets the function name and the number of arguments, and then
    compares those against a list of functions it supports.  If
    it supports the desired function, it calls the appropriate internal
    code.  Otherwise it sets the primary result field to 5 and
    the secondary result field to 1 and returns back to ARexx.  ARexx
    now continues with the search through the Library List...

    The function implementations in rexxhs.c are pretty straightforward.
    The only toughie is ReplyToCall... as it turns out, ARexx keeps a
    list of packets that you retrieve using GetPkt().  When you call
    Reply(), ARexx removes the appropriate packet from its internal list.
    This is so that when the ARexx program exits, any unreplied packets
    can be replied to... so ReplyToCall() has to also remove a packet
    from the list.  Luckily, the structure is documented in the ARexx
    header files so it's not too obscure... the FindPacket() function
    in rexxhs.c does all the dirty work, making sure the pointer you
    pass to it is really a packet in the "waiting for reply" list.


Things to do:

    -- Better error checking and number conversion.
    -- Add a PktAction() function which would return a string representing
       the actual action in a packet (RXCOMM, RXFUNC, etc.).  Right
       now all you can do is assume that if IsFunctionCall() returns
       false then a packet is an RXCOMM packet.


Enjoy....

Eric Giguere
BIX     : giguere
Internet: giguere@csg.uwaterloo.ca