home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d4xx / d459 / rxgen.lha / Rxgen / rxgen.doc < prev    next >
Text File  |  1991-02-18  |  6KB  |  180 lines
  1. TABLE OF CONTENTS
  2.  
  3. rxgen.library/GenOpenLib
  4. rxgen.library/GenCloseLib
  5. rxgen.library/GenACall
  6. rxgen.library/Function Description Format
  7.  
  8.  
  9. rxgen.library/GenOpenLib                             rxgen.library/GenOpenLib
  10.  
  11. NAME
  12.     GenOpenLib  -opens an exec library from Arexx
  13.  
  14. SYNOPSIS
  15.     call GenOpenLib("library name",version)
  16.  
  17. FUNCTION
  18.     REQUIREMENTS: the ARexx variables
  19.                 LIBS.libname
  20.                 LIBS.libname.OPENCOUNT
  21.             should be properly initialized when you open the library for
  22.             the first time.
  23.             For example, if you want to open exec.library, use the
  24.             following clauses:
  25.                 LIBS.EXEC = '0000 0000'x
  26.                 LIBS.EXEC.OPENCOUNT = 0
  27.     Opens the specified library, using the specified version number.
  28.     If the library can be opened, its base will be stored in LIBS.libname,
  29.     and the open count (for GenOpenLib calls in the current program only)
  30.     will be incremented in LIBS.libname.OPENCOUNT
  31.     Failure to open the library will raise an ERROR
  32.  
  33. INPUTS
  34.     "library name" is the name of the library you want to open
  35.         (without .library suffix)
  36.     version is an integer
  37. RESULT
  38.     You're not interested in the result (it is the opencount at this time,
  39.     but this is subject to change).
  40.     See above for side effects
  41.  
  42. EXAMPLE
  43.     LIBS.intuition = '0000 0000'x
  44.     LIBS.intuition.OPENCOUNT = 0
  45.     call GenOpenLib("intuition",0)
  46.  
  47. BUGS
  48.     Use of version not really tested.
  49.     Multiple uses with different version numbers are not supported.
  50.  
  51.  
  52. rxgen.library/GenCloseLib                           rxgen.library/GenCloseLib
  53.  
  54.  
  55. NAME
  56.     GenCloseLib     -close a library from Arexx
  57.  
  58. SYNOPSIS
  59.     call GenCloseLib("libname")
  60.  
  61. FUNCTION
  62.     REQUIREMENTS: same as GenOpenLib, it is also better if the
  63.                   library has been opened...
  64.     Closes a library that has been opened by GenOpenLib.
  65.     Will fail if the opencount of the library is <= 0, otherwise,
  66.     the library will be closed, and the opencount decremented. If the count
  67.     gets null, then the base of the library will be set to 0.
  68.  
  69. INPUTS
  70.     "libname" : the name of the library you want to close (what else ?)
  71.  
  72. RESULT
  73.     You're not interested in the result (it is the opencount at this time,
  74.     but this is subject to change).
  75.     See above for side effects
  76.  
  77. EXAMPLE
  78.     call GenCloseLib("intuition")
  79.  
  80. BUGS
  81.     Maybe.
  82.  
  83.  
  84. rxgen.library/GenACall                                  rxgen.library/GenACall
  85. NAME
  86.     GenACall        - call a function from ARexx
  87.  
  88. SYNOPSIS
  89.     something = GenACall("libname","fname",par,...)
  90.  
  91. FUNCTION
  92.     REQUIREMENTS:
  93.         the library should have been opened (see GenOpenLib)
  94.         the function fname should be defined by
  95.             LIBS.libname.fname = <description>
  96.         the format of the description is described later.
  97.     GenACall will check the base of the library, convert your parameters
  98.     following the description, and return (hopefully) the result.
  99.     If the library base is 0, the function will abort (ERROR).
  100.     If GenACall can't find the function description, it will abort.
  101.  
  102. INPUTS
  103.     "libname" the name of the library your function belongs to
  104.     "fname"   the name of the function
  105.     par,...   parameters for the real function call. Many types allowed,
  106.               check the format of the description
  107.  
  108. RESULT
  109.     A 32 bit word, hopefully a correct one...
  110.  
  111. EXAMPLE
  112.     pointer = GenACall("exec","FindPort",'FOO BAR')
  113.  
  114. BUGS
  115.     Surely. None found.
  116.  
  117.  
  118. rxgen.library/Function Description Format
  119.  
  120.  
  121. Description of the format:
  122. Let's take an example to fix the ideas
  123. LIBS.exec.FindPort='FE7A'x||S||'200A'x
  124. Thus, the format is a string containing:
  125.     - two bytes for the offset of the function in the library
  126.     - a variable number of characters that describe the type of
  127.     conversion to be applied to the parameters
  128.     - a SPACE (here obtained by '20'x)
  129.     - a coding of the registers in which the parameters will be passed.
  130.  
  131. You don't have to find all this by yourself.
  132. The FD2rxFD utility provided in this distribution is able to compute a
  133. partial description from the FD.FILES (to be found on Extras disk).
  134. Check the two directory variables in the program, and run
  135. 1> rx fd2rxfd exec
  136. This will generate a file containing all (partial) function definitions
  137. for the Exec library.
  138.  
  139. In this examples, the information given by the FD.FILES is
  140. LIBS.exec.FindPort='FE7A'x||?||'200A'x
  141. The question mark (?) is to be replaced by the proper type description.
  142.  
  143.     Technical digression: the problem lies in the fact that datas in ARexx are
  144.     not typed. They all are represented by strings, with no way to determine
  145.     safely and systematically if a particular data is a "real" string, or
  146.     an integer, or a pointer.
  147.  
  148. You will have to find by yourself (consulting the proper docs) which kind
  149. of conversion is needed.
  150. In this version (1.0), the supported conversion are:
  151.     I   the ARexx data represents an integer
  152.         It will be converted internally to a 32bit integer with the AREXX
  153.         function CVa2i().
  154.         Valid data examples:        Invalid data:
  155.             1                           'foobar'
  156.             324
  157.  
  158.     S   the ARexx data represents a string.
  159.         No conversion is applied. The pointer to the string is used as
  160.         an argument
  161.         Valid data: any
  162.  
  163.     A   the ARexx data represents a pointer.
  164.         It MUST be a 4-byte long string, containing the value of the
  165.         pointer (usual convention for pointers in AREXX).
  166.         The "raw" value of the data will be used.
  167.         Valid data examples:
  168.             '00 00 00 00'x
  169.             '00 00 06 76'x
  170.  
  171. In the example, the parameter is a port name, so the conversion should be S.
  172.  
  173.  
  174. Register coding is
  175.   D0 D1 D2 D3 D4 D5 D6 D7 A0 A1 A2 A3 A4 A5 A6 A7
  176.   01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E ** **
  177.    A6 is reserved for library base
  178.    A7 is SP. Don't dare to use it.
  179.  
  180.