==========
rexxsyslib
==========

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

======================================= ======================================= ======================================= ======================================= 
`ClearRexxMsg()`_                       `CreateArgstring()`_                    `CreateRexxMsg()`_                      `CVa2i()`_                              
`CVi2a()`_                              `CVi2arg()`_                            `DeleteArgstring()`_                    `DeleteRexxMsg()`_                      
`FillRexxMsg()`_                        `IsRexxMsg()`_                          `LengthArgstring()`_                    `LockRexxBase()`_                       
`StrcmpN()`_                            `Strlen()`_                             `UnlockRexxBase()`_                     
======================================= ======================================= ======================================= ======================================= 

-----------

ClearRexxMsg()
==============

Synopsis
~~~~~~~~
::

 VOID ClearRexxMsg(
          struct RexxMsg * msgptr,
          ULONG count );

Function
~~~~~~~~
::

     This function will clear a specified number of arguments by calling
     DeleteArgstring on them.


Inputs
~~~~~~
::

     msgptr - RexxMsg to clear the arguments from
     count  - The number of arguments in the message to clear


Result
~~~~~~
::

     void



See also
~~~~~~~~

`FillRexxMsg()`_ `DeleteArgstring()`_ 

----------

CreateArgstring()
=================

Synopsis
~~~~~~~~
::

 UBYTE * CreateArgstring(
          CONST UBYTE * string,
          ULONG length );

Function
~~~~~~~~
::

     This function will create a RexxArg structure and copy the supplied
     string into it.


Inputs
~~~~~~
::

     string - String to copy into the RexxArg structure
     length - Length of the string to copy.


Result
~~~~~~
::

     A pointer to the string part of the allocated RexxArg structure.


Notes
~~~~~
::

     Pointer to the string returned by this function may be used as a
     null terminated C string but should be considered read-only.



See also
~~~~~~~~

`DeleteArgstring()`_ `LengthArgstring()`_ 

----------

CreateRexxMsg()
===============

Synopsis
~~~~~~~~
::

 struct RexxMsg * CreateRexxMsg(
          struct MsgPort * port,
          UBYTE          * extension,
          UBYTE          * host );

Function
~~~~~~~~
::

     Creation and initialization of a RexxMsg structure


Inputs
~~~~~~
::

     port      - ReplyPort where the message is replied when it has been
                 handled
     extension - The filename extension to use when searching for macros
     host      - Name of the port to use as the initial command host
                 (e.g. as used in the ADDRESS Rexx statement). When NULL
                 is given "REXX" will be used.


Result
~~~~~~
::

     Pointer to the freshly allocated RexxMsg.



See also
~~~~~~~~

`DeleteRexxMsg()`_ `IsRexxMsg()`_ `FillRexxMsg()`_ `ClearRexxMsg()`_ 

----------

CVa2i()
=======

Synopsis
~~~~~~~~
::

 LONG CVa2i(
          UBYTE * buffer );

Function
~~~~~~~~
::

     This function converts an ASCII string to a signed 32-bit integer.
     The string scanning is stopped when a non-digit character is found or
     the integer value would overflow.
     The function returns both the number of bytes scanned
     and the integer value.


Inputs
~~~~~~
::

     buffer (A0) - A pointer to the first character of the ASCII string.


Result
~~~~~~
::

     value  (D0) - The signed integer obtained from the string.
     digits (D1) - The number of digits scanned from the string, plus one
                   if there was a leading + or -.


Notes
~~~~~
::

     This function is excluded from the C headers and is only
     implemented for m68k CPUs.
     The ARexx User's Reference Manual (1987) is incorrect.
     The result registers listed above are the correct ones.
     Registers A2-A7 and D2-D7 are preserved across the call.



----------

CVi2a()
=======

Synopsis
~~~~~~~~
::

 LONG CVi2a(
          UBYTE * buffer,
          LONG value,
          UWORD digits );

Function
~~~~~~~~
::

     This function writes the digits of the signed 32-bit integer value
     to the buffer given, including the terminating NUL character.
     The function returns both the number of bytes written
     and a pointer to the NUL character in the buffer.


Inputs
~~~~~~
::

     buffer (A0) - A pointer to the destination buffer.
     value  (D0) - A signed 32-bit integer to generate the characters from.
     digits (D1) - The max number of digits to write, including any sign
                   but excluding the terminating NUL character.
                   Zero means no limit.


Result
~~~~~~
::

     length  (D0) - The number of bytes written, excluding the terminating
                    NUL character.
     pointer (A0) - A pointer to the terminating NUL character.


Example
~~~~~~~
::

     Setting value=-2000 and digits=3 will yield the string "-00".


Notes
~~~~~
::

     If digits is less than the number of characters needed, the least
     significant digits that fit will be written. Any sign needed will be
     included.
     This function is excluded from the C headers and is only
     implemented for m68k CPUs.
     Registers A2-A7 and D2-D7 are preserved across the call.



----------

CVi2arg()
=========

Synopsis
~~~~~~~~
::

 UBYTE * CVi2arg(
          LONG value );

Function
~~~~~~~~
::

     This function creates an argstring containing a string representation
     of the signed 32-bit integer value given.
     The argstring can be freed with DeleteArgstring().


Inputs
~~~~~~
::

     value  (D0) - A signed 32-bit integer to generate the characters from.


Result
~~~~~~
::

     pointer (D0, A0) - A pointer on the same format that CreateArgstring() returns.


Notes
~~~~~
::

     This function is excluded from the C headers and is only
     implemented for m68k CPUs.
     The ARexx User's Reference Manual (1987) is incorrect.
     There is no "digits" argument.
     Registers A2-A7 and D2-D7 are preserved across the call.



----------

DeleteArgstring()
=================

Synopsis
~~~~~~~~
::

 VOID DeleteArgstring(
          UBYTE * argstring );

Function
~~~~~~~~
::

     Deletes a RexxArg structure previously created with CreateArgstring


Inputs
~~~~~~
::

     Pointer to the string part of the RexxArg structure returned from
     CreateArgstring


Result
~~~~~~
::

     void



See also
~~~~~~~~

`CreateArgstring()`_ 

----------

DeleteRexxMsg()
===============

Synopsis
~~~~~~~~
::

 VOID DeleteRexxMsg(
          struct RexxMsg * packet );

Function
~~~~~~~~
::

      Deletes a RexxMsg structure


Inputs
~~~~~~
::

      packet - The RexxMsg to delete.


Result
~~~~~~
::

      void



See also
~~~~~~~~

`CreateRexxMsg()`_ 

----------

FillRexxMsg()
=============

Synopsis
~~~~~~~~
::

 BOOL FillRexxMsg(
          struct RexxMsg * msgptr,
          ULONG count,
          ULONG mask );

Function
~~~~~~~~
::

     This function will convert the value(s) provided in rm_Args of the
     RexxMsg. The input can be either a string or a number.


Inputs
~~~~~~
::

     msgptr - RexxMsg to create the RexxArgs for.
     count  - The number of ARGs in the rm_Args structure field that is
              filled with a value and has to be converted.
     mask   - Bits 0 to 'count' from this mask indicate whether the
              corresponding value in rm_Args is a string or a number. When
              the bit is cleared the value is a pointer to a string. When
              it is set it is treated as a signed integer.


Result
~~~~~~
::

     Returns TRUE if succeeded, FALSE otherwise. When FALSE is returned all
     memory already allocated will be freed before returning.


Example
~~~~~~~
::

     This code will convert a string and a number to RexxArgs:

     struct RexxMsg *rm;

     ...

     rm->rm_Args[0] = "Test";
     rm->rm_Args[1] = (UBYTE *)5;

     if (!FillRexxMsg(rm, 2, 1<<1))
     ...



See also
~~~~~~~~

`ClearRexxMsg()`_ `CreateRexxMsg()`_ `CreateArgstring()`_ 

----------

IsRexxMsg()
===========

Synopsis
~~~~~~~~
::

 BOOL IsRexxMsg(
          struct RexxMsg * msgptr );

Function
~~~~~~~~
::

     Test to see if given Message is a RexxMsg


Inputs
~~~~~~
::

     msgptr - Message to test


Result
~~~~~~
::

     TRUE if it is one, FALSE otherwise



See also
~~~~~~~~

`CreateRexxMsg()`_ 

----------

LengthArgstring()
=================

Synopsis
~~~~~~~~
::

 ULONG LengthArgstring(
          UBYTE * argstring );

Function
~~~~~~~~
::

     This will return the length of a string created with CreateArgstring


Inputs
~~~~~~
::

     argstring - Pointer to the string part of a RexxArg structure returned
                 from CreateArgstring


Result
~~~~~~
::

     length of the argstring



See also
~~~~~~~~

`CreateArgstring()`_ 

----------

LockRexxBase()
==============

Synopsis
~~~~~~~~
::

 VOID LockRexxBase(
          ULONG resource );


----------

StrcmpN()
=========

Synopsis
~~~~~~~~
::

 ULONG StrcmpN(
          UBYTE * string1,
          UBYTE * string2,
          ULONG length );

Function
~~~~~~~~
::

     This function compares the strings for the specified number of
     characters.


Inputs
~~~~~~
::

     string1 (A0) - A pointer to the first character of the first string.
     string2 (A1) - Likewise for the second string.
     length  (D0) - The number of characters to compare.


Result
~~~~~~
::

     test (D0) - -1 if the second string is less, 0 if equal, 1 if greater.
     If one string ends it is considered less than a string that continues.
     The CCR flags are updated according to the result.


Notes
~~~~~
::

     This function is excluded from the C headers and is only
     implemented for m68k CPUs.
     The ARexx User's Reference Manual (1987) incorrectly says that 1 is
     returned if the first string is greater.
     Registers A2-A7 and D2-D7 are preserved across the call.



----------

Strlen()
========

Synopsis
~~~~~~~~
::

 ULONG Strlen(
          UBYTE * string );

Function
~~~~~~~~
::

     This function returns the length of the provided ASCII string,
     and sets the Z flag of the m68k CCR if the string is empty.


Inputs
~~~~~~
::

     string (A0) - A pointer to the first character of the ASCII string.


Result
~~~~~~
::

     length (D0) - The length of the ASCII string.
     The CCR Z flag is set if the length is zero.


Notes
~~~~~
::

     This function is excluded from the C headers and is only
     implemented for m68k CPUs.
     Registers A0, A2-A7, and D2-D7 are preserved across the call.



----------

UnlockRexxBase()
================

Synopsis
~~~~~~~~
::

 VOID UnlockRexxBase(
          ULONG resource );


