DOCS FOR AMIGALIBHOST VERSION 0.9

Legal Stuff
    AmigaLibHost is copyright ©1989 Joseph Pearce. The program AmigaLibHost,
its support AREXX programs and this document are freely redistributable.
They are not public domain. They may be included on disks with other freely
distributable software as long as such a collection is not sold for more than
$8.00US. All other rights reserved. This program is provided without warranty
and is provided "as is". Use at your own risk.


Amiga is a trademark of Commodore-Amiga, Inc.
AREXX is a product of William S. Hawes.


What Is This?
    AmigaLibHost is an AREXX host that allows an AREXX macro program to call
any Amiga library routine. This can be used as an alternative to using an
AREXX support library (like "rexxarplib.library" and "rexxsupport.library").
This provides functionality equalivent to BASIC's LIBRARY command.


Warning
    Making calls to AmigaLibHost circumvents AREXX's normal error handling.
You can easily crash the Amiga by making invalid calls. You are warned.


How to use.
    First, AmigaLibHost must be started up from either its icon or from a
CLI by typing "run AmigaLibHost". AREXX programs wanting to access this host
by adding the line

call ADDLIB 'AmigaLibHost',-20

to there program before any calls are mage to the host. The host understands
four commands: FINDLIB, SENDLIB, DONELIB and CLOSE. CLOSE causes the host to
terminate. FINDLIB is used to gain access to an Amiga library. For example:

INTUITIONBASE = FINDLIB("intuition,library",34)

where the number should be the correct library version number. Note that all
variables used in communicating with the library (like INTUITIONBASE) must
be in UPPERCASE. To end access to a library you use DONELIB:

call DONELIB(INTUITIONBASE)

The real work of the host involves the SENDLIB command. First, any Amiga
library function you call must have been previously defined in the program.
For example, to call the Intuition function DisplayBeep, the following
variables would have to be defined:

DISPLAYBEEP.BASE = INTUITIONBASE
DISPLAYBEEP.CALL = 'DISPLAYBEEP(SCREEN)(A0)'
DISPLAYBEEP.LVO = -96

These variables define the library BASE address, the CALLing conventions and
the Library Vector Offset of the function. If these terms are not familiar,
you may want to examine the Amiga Rom Kernel Manuals or find a programming
friend. An AREXX program named "fd2rx.rexx" is provided to create these
function definition variables from one of the function definition files
that can be found on the Extras disk that come with your Amiga. These are the
same files BASIC uses to create its BMAP files (see the BASIC manual for
information).

Anyway, you can then call DisplayBeep by sending SENDLIB the name of the 
function to call (as a string) and a list of parameters for the call. With
DisplayBeep, the only parameter is the address of the screen to flash or a
zero if you want all screens to flash. That is, the line

call 'SENDLIB'('DISPLAYBEEP',0)

causes AmigaLibHost to execute DisplayBeep, which causes all screens to
flash.

    By default, SENDLIB expects its parameters to be standard AREXX numerical
variables. To change a default, you must include an "exception" variable
corresponding to the parameter name in the CALL specification. In the above
example, the parameter in named SCREEN (see DISPLAYBEEP.CALL). To tell
AmigaLibHist of the exception, you assign a string varaible to
DISPLAYBEEP.SCREEN indicating the type of exception. The possible exceptions
are:

FUNCTION.PARAMETER = 'STRING'   /* Parameter will be an AREXX string. */
FUNCTION.PARAMETER = 'ZSTRING'  /* Parameter will be a string or 0 */
FUNCTION.PARAMETER = 'NSTRING'  /* Parameter will be a string or -1 */
FUNCITON.PARAMETER = 'LONG'     /* Parameter will be a 4-byte packed number */

A packed number is a number converted into 4 character string. See the AREXX
manual for details.

So, if we wanted to send DisplayBeep a LONG as SCREEN parameter, the
following would be done:

num = '00 00 00 00'X            /* 4-byte packed representation of zero */
DISPLAYBEEP.SCREEN = 'LONG'
call SENDLIB('DISPLAYBEEP',num)

Some Amiga function return results. AmigaLibHost automatically returns these
as AREXX numeric variables. This can be overridded also, be assigning 'STRING'
or 'LONG' to FUNCTION.RESULT. Using the fucntion ViewAddress as an example:

VIEWADDRESS.BASE = INTUITIONBASE
VIEWADDRESS.CALL = VIEWADDRESS()()        /* No parameters */
VIEWADDRESS.LVO = -294
VIEWADDRESS.RESULT = 'LONG'

view = SENDLIB('VIEWADDRESS')


Support AREXX programs:

    Three examples...
        beep.rexx     - does a DisplayBeep
        win.rexx      - opens an intuition window
        avfonts.rexx  - lists all the available fonts in memory of on disk
		joy.rexx      - read joystick port from AREXX

    Helpful stuff...
        alhend.rexx   - CLOSE's AmigaLibHist
        alhsup.rexx   - useful PEEK and POKE subroutines
        fd2rx.rexx    - converts a .fd file to a .rexx file

    To convert the "intuition_lib.fd" file from your Extras disk in df0: to a
file named "intuition.rexx" type at a CLI

rx fd2rx df0:fd1.3/intuition_lib.fd intuition.rexx

By sure rexxmast has been run previously.


                                           Happy REXXing
                                           Joseph Pearce
                                           August 23, 1989