@database "rexxsyslib"
@master "Work:RKM/Includes&Autodocs/doc/rexxsyslib.doc"

@Node Main "rexxsyslib.doc"
@toc "2.0Includes_Autodocs/Autodocs"

@{" ClearRexxMsg() " Link "ClearRexxMsg()"}       @{" DeleteRexxMsg() " Link "DeleteRexxMsg()"}      @{" LockRexxBase() " Link "LockRexxBase()"}
@{" CreateArgstring() " Link "CreateArgstring()"}    @{" FillRexxMsg() " Link "FillRexxMsg()"}        @{" UnlockRexxBase() " Link "UnlockRexxBase()"}
@{" CreateRexxMsg() " Link "CreateRexxMsg()"}      @{" IsRexxMsg() " Link "IsRexxMsg()"}
@{" DeleteArgstring() " Link "DeleteArgstring()"}    @{" LengthArgstring() " Link "LengthArgstring()"}

@EndNode

@Node "ClearRexxMsg()" "rexxsyslib.library/ClearRexxMsg"

NAME
    ClearRexxMsg - Releases and clears the argument array in a @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99}

SYNOPSIS
    ClearRexxMsg(msgptr, count)
                 A0      D0

    VOID ClearRexxMsg(struct @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} *,ULONG);

FUNCTION
    This function will @{"DeleteArgstring()" Link "DeleteArgstring()"} one or more argstrings from
    the @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} and clear the slot.  The count is used to select the
    number of slots to clear.

INPUTS
    msgptr - A pointer to a @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99}
    count - The number of slots to be cleared.  The number can be from
            1 to 16.  (There are 16 slots)

RESULTS
    All of the slots in the given count will be cleared and the argstring
    will have been released.

SEE ALSO
    @{"FillRexxMsg()" Link "FillRexxMsg()"}, @{"DeleteRexxMsg()" Link "DeleteRexxMsg()"}, @{"DeleteArgstring()" Link "DeleteArgstring()"}, @{"CreateArgstring()" Link "CreateArgstring()"}

BUGS

@EndNode

@Node "CreateArgstring()" "rexxsyslib.library/CreateArgstring"

NAME
    CreateArgstring - Create an argument string structure

SYNOPSIS
    argstr = CreateArgstring(string, length)
    D0,A0                    A0      D0

    UBYTE *CreateArgstring(UBYTE *, ULONG);

FUNCTION
    Allocates a @{"RexxArg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 87} structure and copies the supplied string into it.
    The returned pointer points at the string part of the structure
    and can be treated like an ordinary string pointer.  (However, care
    must be taken that you do not change the string)

INPUTS
    string - A pointer at your input string
    length - The number of bytes of your input string you wish copied.
             (NOTE:  You are limited to 65,535 byte strings)

RESULTS
    argstr - A pointer to the argument string.  The results are returned
             in both A0 and D0.  You should always check the result
             as an allocation failure would cause an error.

SEE ALSO
    @{"DeleteArgstring()" Link "DeleteArgstring()"}, @{"LengthArgstring()" Link "LengthArgstring()"}, @{"ClearRexxMsg()" Link "ClearRexxMsg()"}, @{"FillRexxMsg()" Link "FillRexxMsg()"}

BUGS

@EndNode

@Node "CreateRexxMsg()" "rexxsyslib.library/CreateRexxMsg"

NAME
    CreateRexxMsg - Create an ARexx message structure

SYNOPSIS
    rexxmsg = CreateRexxMsg(port, extension, host)
    D0,A0                   A0    A1         D0

    struct @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} *CreateRexxMsg(struct @{"MsgPort" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/ports.h/Main" 29} *, UBYTE *, UBYTE *);

FUNCTION
    This functions allocates an ARexx message packet.  The @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99}
    consists of a standard EXEC message structure extended to include
    the ARexx specific information.

INPUTS
    port - A pointer to a public or private message port.  This *MUST*
           be a valid port as this is where the message will be replied.

    extension - A pointer to a NULL terminated string that is to be used
                as the default extension for the REXX scripts.  If this
                is NULL, the default is "REXX"

    host - A pointer to a NULL terminated string that is to be used
           as the default host port.  The name must be the same as the
           name of the public message port that is to be the default host.
           If this field is NULL, the default is REXX.

RESULTS
    rexxmsg - A @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} structure

NOTES
    The extension and host strings must remain valid for as long as the
    @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} exists as only the pointer to those strings are stored.

SEE ALSO
    @{"DeleteRexxMsg()" Link "DeleteRexxMsg()"}, @{"ClearRexxMsg()" Link "ClearRexxMsg()"}, @{"FillRexxMsg()" Link "FillRexxMsg()"}

BUGS

@EndNode

@Node "DeleteArgstring()" "rexxsyslib.library/DeleteArgstring"

NAME
    DeleteArgstring - Releases an Argstring created by @{"CreateArgstring()" Link "CreateArgstring()"}

SYNOPSIS
    DeleteArgstring(argstring)
                    A0

    VOID DeleteArgstring(UBYTE *);

FUNCTION
    Releases an argstring.  The argstring must have been created by ARexx

INPUTS
    argstring - A pointer to the string buffer of an argstring.

RESULTS

SEE ALSO
    @{"CreateArgstring()" Link "CreateArgstring()"}, @{"ClearRexxMsg()" Link "ClearRexxMsg()"}, @{"FillRexxMsg()" Link "FillRexxMsg()"}

BUGS

@EndNode

@Node "DeleteRexxMsg()" "rexxsyslib.library/DeleteRexxMsg"

NAME
    DeleteRexxMsg - Releases a @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} structure created by @{"CreateRexxMsg()" Link "CreateRexxMsg()"}

SYNOPSIS
    DeleteRexxMsg(packet)
                  A0

    VOID DeleteRexxMsg(struct @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} *);

FUNCTION
    The function releases an ARexx message packet that was allocated
    with @{"CreateRexxMsg()" Link "CreateRexxMsg()"}.  Any argument fields in the @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} structure
    should be cleared before calling this function as it does
    not release them for you.

INPUTS
    packet - A pointer to a @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} structure allocated by @{"CreateRexxMsg()" Link "CreateRexxMsg()"}

EXAMPLE
    if (rmsg=CreateRexxMsg(myport,"myapp","MYAPP_PORT"))
    {
            /* Do my think with rmsg */
            ClearRexxMsg(rmsg,16);  /* We may not want to clear all 16 */
            DeleteRexxMsg(rmsg);
    }

SEE ALSO
    @{"CreateRexxMsg()" Link "CreateRexxMsg()"}, @{"ClearRexxMsg()" Link "ClearRexxMsg()"}

BUGS

@EndNode

@Node "FillRexxMsg()" "rexxsyslib.library/FillRexxMsg"

NAME
    FillRexxMsg - Fill the argument strings as needed

SYNOPSIS
    result = FillRexxMsg(msgptr, count, mask)
    D0                   A0      D0     D1 [0:15]

    BOOL FillRexxMsg(struct @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} *,ULONG,ULONG);

FUNCTION
    This function will convert and install up to 16 argument strings into
    a @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} structure.  The message packet's argument fields must be
    set to either a pointer to a NULL terminated string or an integer value
    The mask, bits 0 to 15, correspond to the type of value is stored
    in the argument slot.  If the bit is cleared, the argument is a
    string pointer; if the bit is set, the argument is an integer.

INPUTS
    msgptr - Pointer to a @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} (allocated via CreateRexxMsg)
    count - The number of argument slots to fill in.  This number should
            be from 1 to 16.

    mask - A bit mask corresponding to the 16 fields that is used to
           determine the type of the field.

RESULTS
    result - A boolean.  If it is TRUE, the call worked.  If it is false,
             some allocation did not work.  All argstrings that were
             created will be released.

SEE ALSO
    @{"ClearRexxMsg()" Link "ClearRexxMsg()"}, @{"CreateArgstring()" Link "CreateArgstring()"}, @{"DeleteArgstring()" Link "DeleteArgstring()"}, @{"CreateRexxMsg()" Link "CreateRexxMsg()"}

BUGS

@EndNode

@Node "IsRexxMsg()" "rexxsyslib.library/IsRexxMsg"

NAME
    IsRexxMsg - Function to determine if a message came from ARexx

SYNOPSIS
    result = IsRexxMsg(msgptr)
    D0                 A0

    BOOL IsRexxMsg(struct @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99} *);

FUNCTION
    This function can be used to determine if a message came from an
    ARexx program.

INPUTS
    msgptr - A pointer to the suspected @{"RexxMsg" Link "ADCD_v1.2:Inc&AD2.0/Includes/rexx/storage.h/Main" 99}.

RESULTS
    result - A boolean:  TRUE if it is an ARexx message, FALSE if not.

SEE ALSO
    @{"CreateRexxMsg()" Link "CreateRexxMsg()"}

BUGS

@EndNode

@Node "LengthArgstring()" "rexxsyslib.library/LengthArgstring"

NAME
    LengthArgstring - Returns the length value stored in the argstring

SYNOPSIS
    length = LengthArgstring(argstring)
    D0                       A0

    ULONG LengthArgstring(UBYTE *);

FUNCTION
    This function returns the length value stored in the argstring.
    This is *NOT* the same as doing a strlen() type call on the
    argstring.  (Note that argstrings may contain NULLs)

INPUTS
    argstring - A pointer to an argstring that was created by ARexx

RESULTS
    length - The length of the argstring.

EXAMPLE

SEE ALSO
    @{"CreateArgstring()" Link "CreateArgstring()"}

BUGS

@EndNode

@Node "LockRexxBase()" "rexxsyslib.library/LockRexxBase"

NAME
    LockRexxBase - Obtain a semaphore lock on the RexxBase structure

SYNOPSIS
    LockRexxBase(resource)
                 D0

    VOID LockRexxBase(ULONG);

FUNCTION
    Secures the specified resource in the ARexx library base.

INPUTS
    resource - A manifest constant defining which resource to lock.
               ZERO locks all resources.

NOTES
    Currently, only ZERO resource type is available.  You *MUST* make
    sure that you do not call this function with an undefined value
    as it may become defined at some future date and cause unwanted
    behavior.

SEE ALSO
    @{"UnlockRexxBase()" Link "UnlockRexxBase()"}

BUGS

@EndNode

@Node "UnlockRexxBase()" "rexxsyslib.library/UnlockRexxBase"

NAME
    UnlockRexxBase - Release a semaphore lock on the RexxBase structure

SYNOPSIS
    UnlockRexxBase(resource)
                   D0

    VOID UnlockRexxBase(ULONG);

FUNCTION
    Releases the specified resource in the ARexx library base.

INPUTS
    resource - A manifest constant defining which resource to unlock.
               This value *MUST* match the value used in the matching
               @{"LockRexxBase()" Link "LockRexxBase()"} call.

NOTES
    Currently, only ZERO resource type is available.  You *MUST* make
    sure that you do not call this function with an undefined value
    as it may become defined at some future date and cause unwanted
    behavior.  You *MUST* make sure that you only call this function
    after a matching call to @{"LockRexxBase()" Link "LockRexxBase()"} was made.

SEE ALSO
    @{"LockRexxBase()" Link "LockRexxBase()"}

BUGS

@EndNode

