@database rexxer.guide

@$VER: Rexxer V1.10 - (C)Copyright Amiga Foundation Classes

This guide file has been created using AutoGuide V1.05 - By Fabio Rotondo (fsoft@intercom.it).

@node Main "Amiga Foundation Classes: Rexxer"



              ** Rexxer - Original By Fabio Rotondo and Andrea Galimberti **

                       * Part of the Amiga Foundation Classes *

        @{" Introduction " link "Rexxer_introduction"} @{" Author's Info " link "author"} @{" Amiga Foundation Classes " LINK "AFC.Guide/main"} @{" History " LINK "rexxer_history"}

   Requires: @{" validPortName " LINK "validPortName.guide/main"}

   Class Base: $000D0000

   NEW COMMANDS                          BRIEF DESCRIPTION
   -------------------------------------------------------------------------
   @{" rexxer(portname, start)             " link "Rexxer_Rexxer"} Initailizes the class.
   @{" get(parserproc)                     " link "Rexxer_Get"} Gets an ARexx message.
   @{" getanswer()                         " link "Rexxer_GetAnswer"} Gets an ARexx reply string from a host.
   @{" name()                              " link "Rexxer_Name"} Returns the port name.
   @{" port()                              " link "Rexxer_port"} Returns class port.
   @{" rc()                                " link "Rexxer_rc"} Gets message RC.
   @{" reply(mes, rc=0, resultstr=NIL)     " link "Rexxer_reply"} Replies TO an ARexx message.
   @{" result()                            " link "Rexxer_result"} Gets message result.
   @{" send(hostname, command)             " link "Rexxer_send"} Sends an ARexx message TO a program.
   @{" sigbit()                            " link "Rexxer_sigbit"} Gets the signal bitmask of the class.
   @{" version()                           " link "Rexxer_version"} Returns Rexxer version.



   @{" Error Table " LINK Rexxer_ErrorTable}
@endnode

@node Rexxer_History "Amiga Foundation Classes: Rexxer / History"

  HISTORY

  v1.10 - Added the "validPortName" AFC function to allow better performances in
          looking for the right ARexx Port name.

  v1.00 - First AFC release.

          Thanks to Wouter who fixed a very nasty problem in the send() method.

@endNode

@node "Rexxer_Introduction" "Introduction"

  INTRODUCTION

  Rexxer is a class to create and handle ARexx ports and messages.
  Using this class, you'll be able to send messages to other programs,
  to receive messages to external programs and to share data with them.

  This class has been designed to be extremely easy to use.

  We hope you'll like it.

@endnode

@node "author" "Author's Info"

    Original By:    Fabio Rotondo     (fsoft@intercom.it)
                    Andrea Galimberti

    E Version By:   Fabio Rotondo
                    Andrea Galimberti

    Addresses:

            Fabio Rotondo
            C.so Vercelli 9
            28100 Novara
            ITALY

            e-mail: fsoft@intercom.it
                    Fabio.Rotondo@deagostini.it

            Phone:  (ITA) - (0)321 -   459676  (home)
                    (ITA) - (0)2   - 38086520  (office)
                    (ITA) - (0)338 -  7336477  (GSM Phone)

            Fax:    (ITA) - (0)2   - 38086278

            Web:    http://www.intercom.it/~fsoft               (my home page)

                    http://www.intercom.it/~fsoft/ablast.html   (Amiga Blast Home Page)



            Andrea Galimberti
            Via E.Villoresi 279
            Turbigo (MI)
            ITALY

            Phone:  (ITA) - (0)331 - 871009   (home)

@endnode

@node Rexxer_ErrorTable "Rexxer / Error Table "

VALUE           | DESCRIPTION
----------------+--------------------------------------------------------------------
$0000           | No Memory.
$0001           | "Double Port": you are trying to create a port that already exists.
$0002           | Error during port creation.
$0003           | Cannot find "rexxsyslib.library"
$0004           | Error creating the message using CreateRexxMsg() call.
@endnode

@node "Rexxer_Rexxer" "Amiga Foundation Classes: Rexxer/Rexxer()"

           NAME: rexxer(portname:PTR TO CHAR, start = 1)

       SYNOPSIS: rexxer(STRPTR portname, CHAR start = 1)

    DESCRIPTION: This is the class constructor.
                 During class initialization, the port of the Rexx handler
                 will be created, so you have to provide the port name as
                 a parameter.


          INPUT: portname     - Name of the port, ex. "AREXX_TEST"
                                NOTE: to follow Commodore's Style Guide,
                                      you should provide a complete
                                      UPPERCASE port name, without spaces.

                 start        - (Optional) The portname number.
                                Ex. in 'DOPUS.1' the ".1" is the number.

          NOTES: - The portname you should provide is just the basename.

                   * DO NOT PROVIDE COMPLETE NAMES, SUCH AS 'DOPUS.1' *
                   * BUT JUST 'DOPUS'                                 *

                 - The ARexx Port name may differ from the original
                   basename + number you'll provide.
                   Use the @{" name() " LINK "Rexxer_name"} method to
                   know the _right_ name of your ARexx Port.
        RESULTS:

       SEE ALSO: @{" name() " LINK "Rexxer_name"}

                 @{" validPortName " LINK "validPortName.guide/main"}
@endnode

@node "Rexxer_get" "Amiga Foundation Classes: Rexxer/get()"

           NAME: get(parseproc)

       SYNOPSIS: get((VOID *) parserproc (STRPTR))

    DESCRIPTION: This method looks for queued ARexx messages and
                 pass them to the 'parseproc' you should provide.
                 The parseproc MUST return three values:

                    quit    - If TRUE, it means that the application should quit.
                    rc      - RC result value
                    result  - An (optional) result string. You can provide it ONLY
                              when RC is 0.

          INPUT: parseproc  - Parsing procedure to be called.

        RESULTS: this method returns THREE values:

                    quit
                    rc
                    result

                 see above for their discussion.

          NOTES: The ARexx message received will be automatically replied with
                 rc and result parameters you will provide, using the
                 @{" reply() " LINK "Rexxer_reply"} method.
                 So remember: YOU SHOULD NOT REPLY TO A MESSAGE ARRIVED TO YOUR
                 PORT.

       SEE ALSO: @{" send()  " LINK "Rexxer_send"}
                 @{" reply() " LINK "Rexxer_reply"}
@endnode

@node "Rexxer_reply" "Amiga Foundation Classes: Rexxer/reply()"

           NAME: reply(mes:PTR TO rexxmsg, rc=0, resultstring = NIL)

       SYNOPSIS: void reply(struct RexxMsg * mes, LONG rc=0, STRPTR resultstr=NULL)

    DESCRIPTION: this method reply to a previosly received ARexx message.
                 If you use the @{" get() " LINK "Rexxer_get"} method
                 you should not worry about this method to reply to messages,
                 because they will be automatically replied.

          INPUT: mes          - Original ARexx message

                 rc           - RC to return

                 resultstring - Result String to return

        RESULTS:

       SEE ALSO: @{" get() " LINK "Rexxer_get"}
@endnode

@node "Rexxer_send" "Amiga Foundation Classes: Rexxer/send()"

           NAME: send(hostname:PTR TO CHAR, command:PTR TO CHAR)

       SYNOPSIS: BOOL send(STRPTR hostname, STRPTR command)

    DESCRIPTION: this method sends an ARexx message to another program.

          INPUT: hostname     - This is the port name of the program you wish
                                to contact (ex. 'DOPUS.1' for Directory Opus)

                 command      - The string you wish to send to the program you
                                are contacting.

        RESULTS: This method returns THREE values:

                  success     - TRUE means "Message sent successfully"

                                FALSE      "Something went wrong" (usually: port not found)

                  rc          - The RC code returned by the ARexx host contacted.

                  result      - The RESULT string returned by the ARexx host contacted.

           NOTE: It is safe to address the RESULT string with just a char pointer because
                 the RESULT string is stored internally in Rexxer class.
                 Of course, the RESULT string will not change until you'll create and send
                 a new ARexx message.
                 If you want to store the RESULT string for further uses, please consider
                 StrCopy()ing it inside a variable you own.

       SEE ALSO: @{" get()        " LINK "Rexxer_get"}
                 @{" getanswer()  " LINK "Rexxer_getanswer"}
                 @{" rc()         " LINK "Rexxer_rc"}
                 @{" result()     " LINK "Rexxer_result"}
@endnode

@node "Rexxer_getanswer" "Amiga Foundation Classes: Rexxer/getanswer()"

           NAME: getanswer()

       SYNOPSIS: void getanswer( void )

    DESCRIPTION: this method forces the Rexxer class to wait for an answer
                 from an hosts it has contacted.

                 * This is a very LOW LEVEL function and you should never  *
                 * use it for everyday applications, because it could hang *
                 * up your machine. Be carefull!!!                         *


          INPUT: NONE

        RESULTS: This method returns TWO values:

                    rc      - The last RC arrived

                    result  - The last RESULT arrived

       SEE ALSO: @{" rc()     " LINK "Rexxer_rc"}
                 @{" result() " LINK "Rexxer_result"}
@endnode

@node "Rexxer_rc" "Amiga Foundation Classes: Rexxer/rc()"

           NAME: rc()

       SYNOPSIS: LONG rc( VOID )

    DESCRIPTION: This method returns the last RC received by
                 @{" getanswer() " LINK "Rexxer_getanswer"} OR @{" send() " LINK Rexxer_send}

          INPUT: NONE

        RESULTS: a LONG value containing the last RC received.

       SEE ALSO: @{" send()      " LINK "Rexxer_send"}
                 @{" getanswer() " LINK "Rexxer_getanswer"}
                 @{" result()    " LINK "Rexxer_result"}
@endnode

@node "Rexxer_result" "Amiga Foundation Classes: Rexxer/result()"

           NAME: result()

       SYNOPSIS: STRPTR result( VOID )

    DESCRIPTION: This method returns the last result received by
                 @{" getanswer() " LINK "Rexxer_getanswer"} OR @{" send() " LINK Rexxer_send}

          INPUT: NONE

        RESULTS: a PTR TO CHAT (STRPTR) value containing the last result received.

       SEE ALSO: @{" send()      " LINK "Rexxer_send"}
                 @{" getanswer() " LINK "Rexxer_getanswer"}
                 @{" rc()        " LINK "Rexxer_rc"}
@endnode

@node "Rexxer_name" "Amiga Foundation Classes: Rexxer/name()"

           NAME: name()

       SYNOPSIS: STRPTR name( VOID )

    DESCRIPTION: This method returns the ARexx Port name.

          INPUT: NONE

        RESULTS: a PTR TO CHAT (STRPTR) value containing the ARexx Port Name.

       SEE ALSO: @{" validPortName() " LINK "validPortName.guide/main"}
@endnode

@node "Rexxer_port" "Amiga Foundation Classes: Rexxer/port()"

           NAME: port()

       SYNOPSIS: MsgPort *  port( VOID )

    DESCRIPTION: This method returns a pointer TO the message port of the class.

          INPUT: NONE

        RESULTS: a MsgPort * value relative TO the Port of the class.

       SEE ALSO:
@endnode

@node "Rexxer_sigbit" "Amiga Foundation Classes: Rexxer/sigbit()"

           NAME: sigbit()

       SYNOPSIS: ULONG sigbit( VOID )

    DESCRIPTION: This method returns the signal bit mask FOR the Wait()
                 command.

          INPUT: NONE

        RESULTS: a LONG containing the signal bitmask.

       SEE ALSO:
@endnode

