rxgen.doc

     GenOpenLib() 
     GenCloseLib() 
     GenACall() 
     Function Description Format() 


rxgen.library/GenOpenLib


NAME
    GenOpenLib  -opens an exec library from Arexx

SYNOPSIS
    call GenOpenLib("library name",version)

FUNCTION
    REQUIREMENTS: the ARexx variables
                LIBS.libname
                LIBS.libname.OPENCOUNT
            should be properly initialized when you open the library for
            the first time.
            For example, if you want to open exec.library, use the
            following clauses:
                LIBS.EXEC = '0000 0000'x
                LIBS.EXEC.OPENCOUNT = 0
    Opens the specified library, using the specified version number.
    If the library can be opened, its base will be stored in LIBS.libname,
    and the open count (for GenOpenLib calls in the current program only)
    will be incremented in LIBS.libname.OPENCOUNT
    Failure to open the library will raise an ERROR

INPUTS
    "library name" is the name of the library you want to open
        (without .library suffix)
    version is an integer
RESULT
    You're not interested in the result (it is the opencount at this time,
    but this is subject to change).
    See above for side effects

EXAMPLE
    LIBS.intuition = '0000 0000'x
    LIBS.intuition.OPENCOUNT = 0
    call GenOpenLib("intuition",0)

BUGS
    Use of version not really tested.
    Multiple uses with different version numbers are not supported.


rxgen.library/GenCloseLib



NAME
    GenCloseLib     -close a library from Arexx

SYNOPSIS
    call GenCloseLib("libname")

FUNCTION
    REQUIREMENTS: same as GenOpenLib, it is also better if the
                  library has been opened...
    Closes a library that has been opened by GenOpenLib.
    Will fail if the opencount of the library is <= 0, otherwise,
    the library will be closed, and the opencount decremented. If the count
    gets null, then the base of the library will be set to 0.

INPUTS
    "libname" : the name of the library you want to close (what else ?)

RESULT
    You're not interested in the result (it is the opencount at this time,
    but this is subject to change).
    See above for side effects

EXAMPLE
    call GenCloseLib("intuition")

BUGS
    Maybe.


rxgen.library/GenACall

NAME
    GenACall        - call a function from ARexx

SYNOPSIS
    something = GenACall("libname","fname",par,...)

FUNCTION
    REQUIREMENTS:
        the library should have been opened (see GenOpenLib)
        the function fname should be defined by
            LIBS.libname.fname = 
        the format of the description is described later.
    GenACall will check the base of the library, convert your parameters
    following the description, and return (hopefully) the result.
    If the library base is 0, the function will abort (ERROR).
    If GenACall can't find the function description, it will abort.

INPUTS
    "libname" the name of the library your function belongs to
    "fname"   the name of the function
    par,...   parameters for the real function call. Many types allowed,
              check the format of the description

RESULT
    A 32 bit word, hopefully a correct one...

EXAMPLE
    pointer = GenACall("exec","FindPort",'FOO BAR')

BUGS
    Surely. None found.


rxgen.library/Function



Description of the format:
Let's take an example to fix the ideas
LIBS.exec.FindPort='FE7A'x||S||'200A'x
Thus, the format is a string containing:
    - two bytes for the offset of the function in the library
    - a variable number of characters that describe the type of
    conversion to be applied to the parameters
    - a SPACE (here obtained by '20'x)
    - a coding of the registers in which the parameters will be passed.

You don't have to find all this by yourself.
The FD2rxFD utility provided in this distribution is able to compute a
partial description from the FD.FILES (to be found on Extras disk).
Check the two directory variables in the program, and run
1> rx fd2rxfd exec
This will generate a file containing all (partial) function definitions
for the Exec library.

In this examples, the information given by the FD.FILES is
LIBS.exec.FindPort='FE7A'x||?||'200A'x
The question mark (?) is to be replaced by the proper type description.

    Technical digression: the problem lies in the fact that datas in ARexx are
    not typed. They all are represented by strings, with no way to determine
    safely and systematically if a particular data is a "real" string, or
    an integer, or a pointer.

You will have to find by yourself (consulting the proper docs) which kind
of conversion is needed.
In this version (1.0), the supported conversion are:
    I   the ARexx data represents an integer
        It will be converted internally to a 32bit integer with the AREXX
        function CVa2i().
        Valid data examples:        Invalid data:
            1                           'foobar'
            324

    S   the ARexx data represents a string.
        No conversion is applied. The pointer to the string is used as
        an argument
        Valid data: any

    A   the ARexx data represents a pointer.
        It MUST be a 4-byte long string, containing the value of the
        pointer (usual convention for pointers in AREXX).
        The "raw" value of the data will be used.
        Valid data examples:
            '00 00 00 00'x
            '00 00 06 76'x

In the example, the parameter is a port name, so the conversion should be S.


Register coding is
  D0 D1 D2 D3 D4 D5 D6 D7 A0 A1 A2 A3 A4 A5 A6 A7
  01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E ** **
   A6 is reserved for library base
   A7 is SP. Don't dare to use it.


Converted on 22 Apr 2000 with RexxDoesAmigaGuide2HTML 2.1 by Michael Ranner.