@DATABASE
@Author Conversion program
@NODE MAIN "RIARexx Library"
.---------------------------------------------------------------------------.
|                          @{b}RI ARexx Library   V2.5@{ub}                          |
`---------------------------------------------------------------------------'

                        ©1996 Red When Excited Ltd

       Undocumented commands added by Toby Zuijdveld 02/03/1999.
                      mailto: hotcakes@abacus.net.au

			   @{"     Overview     " link OVERVIEW}

                               Command Index
  
           @{" RXCreatePort  " link RXCreatePort}                  @{"  RXErrorCode     " link RXErrorCode}    
           @{" RXDeletePort  " link RXDeletePort}                  @{"  RXSendCommand   " link RXSendCommand}  
           @{" RXCreateMsg   " link RXCreateMsg}                  @{"  RXExecuteScript " link RXExecuteScript}
           @{" RXSetArg      " link RXSetArg}                  @{"  RXSetMsgType    " link RXSetMsgType}   
           @{" RXReadPort    " link RXReadPort}                  @{"  RXGetResult     " link RXGetResult}    
           @{" RXWaitPort    " link RXWaitPort}                  @{"  RXWaitResult    " link RXWaitResult}   
           @{" RXGetArg      " link RXGetArg}                  @{"  RXWaitResults   " link RXWaitResults}  
           @{" RXNextArg     " link RXNextArg}                  @{"  RXRunCommand    " link RXRunCommand}   
           @{" RXNumArgs     " link RXNumArgs}                  @{"  RXRunScript     " link RXRunScript}    
           @{" RXReplyMsg    " link RXReplyMsg}                  @{"  RXPriority      " link RXPriority}     
           @{" RXSendMsg     " link RXSendMsg}                  @{"  RXResults       " link RXResults}      
           @{" RXSendersName " link RXSendersName}                  @{"  RXDefaultPort   " link RXDefaultPort}  
           @{" RXComResult   " link RXComResult}

            RXWaitReplies                     RXReturnCode   

                                @{" Examples " LINK Examples}

                               @{"Main Document" link "REDBLITZLIBS.GUIDE/MAIN"}
                               @{"Library Index" link "REDBLITZLIBS.GUIDE/LIBRARYLIST"}

@ENDNODE MAIN

@NODE OVERVIEW "Whats it all about?"

                                   @{fg shine}Overview@{fg text}

The RI ARexx Library is designed to allow the Blitz application programmer
to add an ARexx port to their program. It provides simple commands for
creating an ARexx port, sending ARexx commands to other ports, and reading
the ARexx port for incoming commands.

@ENDNODE OVERVIEW

@NODE RXCreatePort

@{fg shine}Function: RXCreatePort@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : msgport.l=RXCreatePort(portname$)

  This function attempts to create a public message port with the name
<portname$>. It returns a pointer to the message port or 0 if it fails.
Failure is usually due to a public message port existing with the same
name. This must be called before any other RIARexxLib commands.

@ENDNODE RXCreatePort

@NODE RXDeletePort

@{fg shine}Statement: RXDeletePort@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : RXDeletePort

  This command removes and free's your message port so that no further
messages can arrive. It will wait until all replies (which want a result)
have been received and replies to all new messages with the error code
HOSTNOTFOUND.

@ENDNODE RXDeltePort

@NODE RXCreateMsg

@{fg shine}Function: RXCreateMsg@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : rexxmsg.l=RXCreateMsg

  This function attempts to allocate memory for an ARexx message. It returns
a pointer to the message or 0 for failure. It will fail if no message
port has been opened, or, if there is insufficient memory.

This must be called before calling RXCreateArg, RXSendMsg,
RXFreeArgs, RXFreeArg, RXFreeArgsWait

@ENDNODE RXCreateMsg

@NODE RXSetArg

@{fg shine}Statement/Function: RXSetarg@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Synrax : [success=]RXSetArg([rexxmsg,]argnumber,arg$)

  This command attempts to store the argument <arg$> into the message
argument slot specified by argnumber. Valid argument numbers are 1-16.

This command will return -1 for success, or 0 for failure.

@ENDNODE RXSetArg

@NODE RXReadPort

@{fg shine}Function: RXReadPort@{fg text}
-----------------------------------------------------------------------------
Modes  ; Amiga
Syntax : rexxmsg=RXReadPort

  This function reads the message port created with RXCreatePort to see
if a message is waiting. If there is, it returns a pointer to the message
else 0. The return value from this function should be used with RXGetArg,
RXReplyMsg, RXSendersName, RXNumArgs

@ENDNODE RXReadPort

@NODE RXWaitPort

@{fg shine}Function: RXWaitPort@{fg text}
-----------------------------------------------------------------------------
Modes  ; Amiga
Syntax : rexxmsg=RXWaitPort

  This function waits at the message port created with RXCreatePort, for a
message to arrive. It returns a pointer to the message else 0 (no port).
The return value from this function should be used with RXGetArg,
RXReplyMsg, RXSendersName, RXNumArgs

@ENDNODE RXWaitPort

@NODE RXGetArg

@{fg shine}Function: RXGetArg@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : arg$=RXGetArg([rexxmsg,]argnum)

  This function returns the <argnum> argument from a message read using
RXReadMsg/RXWaitMsg. The return result is a string.

@ENDNODE RXGetArg

@NODE RXNumArgs

@{fg shine}Function: RXNumArgs@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : numargs=RXNumArgs([rexxmsg])

  This function will return the number of arguments contained in a message
received through RXReadPort/RXWaitPort.

@ENDNODE RXNumArgs

@NODE RXReplyMsg

@{fg shine}Statement: RXReplyMsg@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : RXReplyMsg errorcode[,return$]

  This statement will reply to a message recevied via RXReadPort/RXWaitPort
signalling to the sender that he/she can free the memory for it.

errorcode is the errorcode to return. 0 for no error

The optional return$ parameter is a result string to be returned.

e.g.

   address 'ThatPort'
   RESULT=MYAREXXCOMMAND("MY PARAMETER")
   SAY(RESULT)

The variable RESULT would contain the string <return$>

NOTE: You should extract any information from the recevied rexxmsg BEFORE
      you reply to it.

@ENDNODE RXReplyMsg

@NODE RXSendMsg

@{fg shine}Statement/Function: RXSendMsg@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : [success=]RXSendMsg([rexxmsg,]portname$)

  This command will attempt to send the message created with RXCreateMsg
to the public message port specified in <portname$>. It will return -1
if all was ok, else 0. (eg. couldnt find port, no such rexxmsg)

@ENDNODE RXSendMsg

@NODE RXSendersName

@{fg shine}Function: RXSendersName@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : portname$=RXSendersName

  This function will return the mesage port name of the task which sent
you the message read by RXReadPort/RXWaitPort.

@ENDNODE RXSendersName

@NODE RXErrorCode

@{fg shine}Function: RXErrorCode@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : errorcode=RXErrorCode[(rexxmsg)]

  If rexxmsg is not given, this function returns the error code number for
the most recent message sent with RXRunCommand/RXRunScript/RXSendCommand
RXExecuteScript

If rexxmsg is given, this function returns the error code number for
the given rexxmsg.

e.g.

If RXSendCommand("REXX","SAY('Hello')"="" Then NPrint "Error "+Str$(RXErrorCode)

@ENDNODE RXErrorCode

@NODE RXSendCommand

@{fg shine}Statement/Function: RXSendCommand@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : [result$=]RXSendCommand([port$,]command$)

  This function is a quick way of sending ARexx messages.

If port$ is omitted, this will send the message to the default port
specified with RXDefaultPort (or REXX if no default port is set)

command$ should be a valid arexx command. Multiple commands are available
by separating with a ;

Single quotes (') can be used instead of Chr$(34) to save typing

e.g.

            RXSendCommand("REQUEST 'Please' 'Insert Volume' 'Yes|No')
 instead of RXSendCommand("REQUEST "+Chr$(34)+"Please"+Chr$(34)+" "+Chr.....

This function returns a result string. NULL string for error or an
empty return string.

@ENDNODE RXSendCommand

@NODE RXExecuteScript

@{fg shine}Statement/Function: RXExecuteScript@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : [result$=]RXExecuteScript(scriptname$)

  This command tells ARexx to execute the ARexx script <scriptname$>. The
result string is the result returned by ARexx.

@ENDNODE RXExecuteScript

@NODE RXRunCommand

@{fg shine}Statement: RXRunCommand@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : RXRunCommand command$

  This function is a quick way of sending ARexx messages. It is identical
to RXSendCommand except that: 

  a) It does not return a result string
  b) It does not wait for a reply

@ENDNODE RXRunCommand

@NODE RXRunScript

@{fg shine}Statement: RXRunScript@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : RXRunScript scriptname$

  This command tells ARexx to execute the ARexx script <scriptname$>. It is
identical to RXExecuteScript except that: 

  a) It does not return a result string
  b) It does not wait for a reply

@ENDNODE RXRunScript

@NODE RXGetResult

@{fg shine}Function: RXGetResult@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : result$=RXGetResult

  This function will look at your message port for a reply to the last
message sent and return the result string.

@ENDNODE RXGetResult

@NODE RXWaitResult

@{fg shine}Function: RXWaitResult@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : result$=RXGetResult

  This function will wait for a reply to the last message sent and return the
result string.

@ENDNODE RXWaitResult

@NODE RXMsgScript

@{fg shine}Statement/Function: RXMsgScript@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : [suc=]RXMsgScript rexxmsg

  This command sends a previously created rexxmsg to REXX telling it to
execute the first argument as a script file.

e.g.

	rexxmsg.l=RXCreateMsg
        RXCreateArg rexxmsg,1,"RAM:TEST.rexx"
        RXMsgScript rexxmsg

@ENDNODE RXMsgScript

@NODE RXResults

@{fg shine}Statement: RXResults@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : RXResults On|Off

  This command lets you choose whether the ARexx commmands which return a
result will actually look for a result or not.

e.g.

     RXResults Off : RXSendCommand("BLAH")

It will not wait for a result. When the message is replied to, the message
is automatically free'd and no result is taken.

@ENDNODE RXResults

@NODE RXPriority

@{fg shine}Statement: RXPriority@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : RXPriority pri

  This command lets you specify a priority for your function host (the higher
the value, the earlier your port is passed a function). This must be called
BEFORE RXCreatePort

@ENDNODE RXPriority

@NODE RXComResult

@{fg shine}Function: RXComResult@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : RXComResult

  This function determines whether or not the last RX______ Command was
successfull or not. 0 indiciates success, -1 indicates failure.

@ENDNODE

@NODE RXDefaultPort

@{fg shine}Statement: RXDefaultPort@{fg text}
-----------------------------------------------------------------------------
Modes  : Amiga
Syntax : RXDefaultPort portname$

  This command lets you specify the name of the default port for commands
which are not given a port name. The default default :-)  portname is REXX

@ENDNODE RXDefaultPort

@NODE Examples

                                  @{b}@{u}Example@{ub}@{uu}

@NODE Examples "Example Programs"

                             @{b}@{u}Example Programs@{ub}@{uu}

@{fg shine}EXAMPLE 1@{fg text} - An example of ARexx :

	@{" Load Example 1 " system "run >NIL: Blitz2:REDHelp/ShowExample FILE=Blitz2:REDHelp/REDBlitzLibs/Examples/RIARexxLib1.bb"}
	@{" Compile It!    " system "run >NIL: Blitz2:REDHelp/ShowExample FILE=COMPILE"}

@ENDNODE Examples