home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 283.lha / AmigaLibHost_v0.9 / amigalibhost.doc < prev    next >
Encoding:
Text File  |  1989-09-07  |  5.3 KB  |  134 lines
  1.                     DOCS FOR AMIGALIBHOST VERSION 0.9
  2.  
  3. Legal Stuff
  4.     AmigaLibHost is copyright ©1989 Joseph Pearce. The program AmigaLibHost,
  5. its support AREXX programs and this document are freely redistributable.
  6. They are not public domain. They may be included on disks with other freely
  7. distributable software as long as such a collection is not sold for more than
  8. $8.00US. All other rights reserved. This program is provided without warranty
  9. and is provided "as is". Use at your own risk.
  10.  
  11.  
  12. Amiga is a trademark of Commodore-Amiga, Inc.
  13. AREXX is a product of William S. Hawes.
  14.  
  15.  
  16. What Is This?
  17.     AmigaLibHost is an AREXX host that allows an AREXX macro program to call
  18. any Amiga library routine. This can be used as an alternative to using an
  19. AREXX support library (like "rexxarplib.library" and "rexxsupport.library").
  20. This provides functionality equalivent to BASIC's LIBRARY command.
  21.  
  22.  
  23. Warning
  24.     Making calls to AmigaLibHost circumvents AREXX's normal error handling.
  25. You can easily crash the Amiga by making invalid calls. You are warned.
  26.  
  27.  
  28. How to use.
  29.     First, AmigaLibHost must be started up from either its icon or from a
  30. CLI by typing "run AmigaLibHost". AREXX programs wanting to access this host
  31. by adding the line
  32.  
  33. call ADDLIB 'AmigaLibHost',-20
  34.  
  35. to there program before any calls are mage to the host. The host understands
  36. four commands: FINDLIB, SENDLIB, DONELIB and CLOSE. CLOSE causes the host to
  37. terminate. FINDLIB is used to gain access to an Amiga library. For example:
  38.  
  39. INTUITIONBASE = FINDLIB("intuition,library",34)
  40.  
  41. where the number should be the correct library version number. Note that all
  42. variables used in communicating with the library (like INTUITIONBASE) must
  43. be in UPPERCASE. To end access to a library you use DONELIB:
  44.  
  45. call DONELIB(INTUITIONBASE)
  46.  
  47. The real work of the host involves the SENDLIB command. First, any Amiga
  48. library function you call must have been previously defined in the program.
  49. For example, to call the Intuition function DisplayBeep, the following
  50. variables would have to be defined:
  51.  
  52. DISPLAYBEEP.BASE = INTUITIONBASE
  53. DISPLAYBEEP.CALL = 'DISPLAYBEEP(SCREEN)(A0)'
  54. DISPLAYBEEP.LVO = -96
  55.  
  56. These variables define the library BASE address, the CALLing conventions and
  57. the Library Vector Offset of the function. If these terms are not familiar,
  58. you may want to examine the Amiga Rom Kernel Manuals or find a programming
  59. friend. An AREXX program named "fd2rx.rexx" is provided to create these
  60. function definition variables from one of the function definition files
  61. that can be found on the Extras disk that come with your Amiga. These are the
  62. same files BASIC uses to create its BMAP files (see the BASIC manual for
  63. information).
  64.  
  65. Anyway, you can then call DisplayBeep by sending SENDLIB the name of the 
  66. function to call (as a string) and a list of parameters for the call. With
  67. DisplayBeep, the only parameter is the address of the screen to flash or a
  68. zero if you want all screens to flash. That is, the line
  69.  
  70. call 'SENDLIB'('DISPLAYBEEP',0)
  71.  
  72. causes AmigaLibHost to execute DisplayBeep, which causes all screens to
  73. flash.
  74.  
  75.     By default, SENDLIB expects its parameters to be standard AREXX numerical
  76. variables. To change a default, you must include an "exception" variable
  77. corresponding to the parameter name in the CALL specification. In the above
  78. example, the parameter in named SCREEN (see DISPLAYBEEP.CALL). To tell
  79. AmigaLibHist of the exception, you assign a string varaible to
  80. DISPLAYBEEP.SCREEN indicating the type of exception. The possible exceptions
  81. are:
  82.  
  83. FUNCTION.PARAMETER = 'STRING'   /* Parameter will be an AREXX string. */
  84. FUNCTION.PARAMETER = 'ZSTRING'  /* Parameter will be a string or 0 */
  85. FUNCTION.PARAMETER = 'NSTRING'  /* Parameter will be a string or -1 */
  86. FUNCITON.PARAMETER = 'LONG'     /* Parameter will be a 4-byte packed number */
  87.  
  88. A packed number is a number converted into 4 character string. See the AREXX
  89. manual for details.
  90.  
  91. So, if we wanted to send DisplayBeep a LONG as SCREEN parameter, the
  92. following would be done:
  93.  
  94. num = '00 00 00 00'X            /* 4-byte packed representation of zero */
  95. DISPLAYBEEP.SCREEN = 'LONG'
  96. call SENDLIB('DISPLAYBEEP',num)
  97.  
  98. Some Amiga function return results. AmigaLibHost automatically returns these
  99. as AREXX numeric variables. This can be overridded also, be assigning 'STRING'
  100. or 'LONG' to FUNCTION.RESULT. Using the fucntion ViewAddress as an example:
  101.  
  102. VIEWADDRESS.BASE = INTUITIONBASE
  103. VIEWADDRESS.CALL = VIEWADDRESS()()        /* No parameters */
  104. VIEWADDRESS.LVO = -294
  105. VIEWADDRESS.RESULT = 'LONG'
  106.  
  107. view = SENDLIB('VIEWADDRESS')
  108.  
  109.  
  110. Support AREXX programs:
  111.  
  112.     Three examples...
  113.         beep.rexx     - does a DisplayBeep
  114.         win.rexx      - opens an intuition window
  115.         avfonts.rexx  - lists all the available fonts in memory of on disk
  116.         joy.rexx      - read joystick port from AREXX
  117.  
  118.     Helpful stuff...
  119.         alhend.rexx   - CLOSE's AmigaLibHist
  120.         alhsup.rexx   - useful PEEK and POKE subroutines
  121.         fd2rx.rexx    - converts a .fd file to a .rexx file
  122.  
  123.     To convert the "intuition_lib.fd" file from your Extras disk in df0: to a
  124. file named "intuition.rexx" type at a CLI
  125.  
  126. rx fd2rx df0:fd1.3/intuition_lib.fd intuition.rexx
  127.  
  128. By sure rexxmast has been run previously.
  129.  
  130.  
  131.                                            Happy REXXing
  132.                                            Joseph Pearce
  133.                                            August 23, 1989
  134.