home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 13 / CDA13.ISO / cdactual / demobin / share / program / C / AXMSLIB.ZIP / XMSLIB.QH < prev    next >
Encoding:
Text File  |  1992-02-28  |  9.2 KB  |  247 lines
  1. .context XMSLIB
  2. .context @L8060
  3. :z3
  4.                                                           \i\p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  5. ─────XMSLIB Overview────────────────────────────────────────────────────────
  6.  
  7. \bQuick Reference Summary:\p
  8.  
  9. XMSHANDLE \iXMSalloc\p      (WORD uBytes);
  10. int       \iXMSclose\p      (void);
  11. WORD      \iXMSerrorCode\p  (void);
  12. int       \iXMSfree\p       (XMSHANDLE xhXM);
  13. int       \iXMSget\p        (void * pDest, XMSHANDLE xhXM);
  14. int       \iXMSgetExt\p     (void * pDest, XMSHANDLE xhXM, WORD uSrcOfs,
  15.                          WORD uBytes);
  16. WORD      \iXMSgetLen\p     (XMSHANDLE xhXM);
  17. WORD      \iXMSgetVersion\p (void);
  18. int       \iXMSinstalled\p  (void);
  19. int       \iXMSopen\p       (WORD uKbytes);
  20. int       \iXMSput\p        (XMSHANDLE xhXM, const void * pSrc, WORD uBytes);
  21.  
  22. \bType and constant definitions:\p
  23.  
  24.         \bXMSHANDLE\p   Handle to an XMS memory buffer
  25.         \bXMSHNULL\p    The `null' handle; an error condition
  26.  
  27.  
  28. XMSLIB contains functions to allocate, free, read and write from 
  29. extended memory conforming to the XMS 2.0 (or later) specification.
  30. A driver such as HIMEM.SYS must be loaded to make the memory available.
  31.  
  32. The XMS access must be performed as follows:
  33.  
  34.     if (XMSopen(x))
  35.       {
  36.       // XMS access permitted here...
  37.       // .
  38.       // .
  39.       // .
  40.       // End of XMS access
  41.       
  42.       if (!XMSclose())
  43.         fprintf(stderr, "XMS error %x\n", XMSerrorCode());
  44.       }
  45.  
  46. .context XMSalloc
  47. :z3
  48.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  49. ─────XMSalloc───────────────────────────────────────────────────────────────
  50.  
  51. \bXMSHANDLE XMSalloc (WORD uBytes);\p
  52.  
  53. Allocates a buffer of size <uBytes> characters in extended memory.
  54.  
  55. Returns a handle to the memory if successful, or XMSHNULL if not.
  56.  
  57. XMSopen() must be called before attempting to use this function. The
  58. maximum size of the buffer is 65534 bytes (assuming that at least 64K
  59. of XMS memory is available).
  60.  
  61. .context XMSclose
  62. :z3
  63.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  64. ─────XMSclose───────────────────────────────────────────────────────────────
  65.  
  66. \bint       XMSclose (void);\p
  67.  
  68. Terminates access to XMS memory, returning all associated buffer space
  69. (both in XMS and on the program's heap) to the system.
  70.  
  71. Returns TRUE if successful, else FALSE.
  72.  
  73. You must call this function before exiting the program. DOS does not
  74. automatically release XMS memory claimed by a process, so a failure
  75. to call XMSclose() will leave a reduced amount of XMS memory available
  76. for other programs, or later execution of the same program, until the
  77. system is reset.
  78.  
  79.  
  80. .context XMSerrorCode
  81. :z3
  82.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  83. ─────XMSerrorCode───────────────────────────────────────────────────────────
  84.  
  85. \bWORD      XMSerrorCode (void);\p
  86.  
  87. Returns the XMS error code number pertaining to the most recent XMS
  88. operation. If you need information on why an operation failed, call
  89. this function immediately afterwards (and before calling any other
  90. XMSLIB function).
  91.  
  92. Return codes are (refer to the XMS spec for full details):
  93.  
  94.    (0x80    Function not implemented)
  95.     0x81    VDISK device detected
  96.     0x82    A20 error
  97.     0x8E    General driver error
  98.     0x8F    Unrecoverable driver error
  99.    (0x90    HMA does not exist)
  100.    (0x91    HMA already in use)
  101.    (0x92    DX less than /HMAMIN= parameter)
  102.    (0x93    HMA is not allocated)
  103.    (0x94    A20 line still enabled)
  104.     0xA0    All extended memory is allocated
  105.     0xA1    All available extended memory handles are in use
  106.     0xA2    Handle is invalid
  107.     0xA3    Source handle is invalid
  108.     0xA4    Source offset is invalid
  109.     0xA5    Destination handle is invalid
  110.     0xA6    Destination offset is invalid
  111.     0xA7    Length is invalid
  112.    (0xA8    Move has invalid overlap)
  113.     0xA9    Parity error
  114.    (0xAA    Block is not locked)
  115.    (0xAB    Block is locked)
  116.    (0xAC    Block's lock count has overflowed)
  117.    (0xAD    Lock failed)
  118.    (0xB0    Smaller UMB is available)
  119.    (0xB1    No UMBs are available)
  120.    (0xB2    UMB segment number is invalid)
  121.  
  122. Because XMSLIB only uses a subset of the XMS API calls, several of
  123. the error codes are most unlikely to occur. These are shown in 
  124. brackets. It would be unnecessary to, for example, store a descriptive
  125. string for each of these in a program.
  126.  
  127.  
  128. .context XMSfree
  129. :z3
  130.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  131. ─────XMSfree────────────────────────────────────────────────────────────────
  132.  
  133. \bint       XMSfree (XMSHANDLE xhXM);\p
  134.  
  135. Frees the memory associated with handle <xhXM> for re-use. The handle
  136. must have been returned previously be a call to XMSalloc(). Once the
  137. memory has been freed, you can not rely on it to contain any data 
  138. previously copied in. Do not use a handle once it has been passed to
  139. XMSfree().
  140.  
  141. Returns TRUE for success, FALSE for failure.
  142.  
  143.  
  144. .context XMSget
  145. :z3
  146.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  147. ─────XMSget─────────────────────────────────────────────────────────────────
  148.  
  149. \bint       XMSget (void * pDest, XMSHANDLE xhXM);\p
  150.  
  151. Copies data from extended memory addressed by handle <xhXM> to a buffer
  152. pointed to by <pDest>. The number of bytes copied is equal to the 
  153. argument passed to XMSalloc() to create the handle (i.e. the size of
  154. the allocated buffer), or 1 BYTE MORE if the number of bytes was odd.
  155.  
  156. Returns TRUE if successful, FALSE on failure.
  157.  
  158.  
  159. .context XMSgetExt
  160. :z3
  161.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  162. ─────XMSgetExt──────────────────────────────────────────────────────────────
  163.  
  164. \bint       XMSgetExt (void * pDest, XMSHANDLE xhXM, WORD uSrcOfs,
  165.                      WORD uBytes);\p
  166.  
  167. Copies data from extended memory addressed by handle <xhXM> to a buffer
  168. pointed to by <pDest>. The number of bytes copied is equal to <uBytes>.
  169. Data will be copied from an offset of <uSrcOfs> from the start of the
  170. extended memory buffer addressed by the handle.
  171.  
  172. Returns TRUE if successful, FALSE on failure.
  173.  
  174.  
  175. .context XMSgetLen
  176. :z3
  177.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  178. ─────XMSgetLen──────────────────────────────────────────────────────────────
  179.  
  180. \bWORD      XMSgetLen (XMSHANDLE xhXM);\p
  181.  
  182. Returns the number of bytes of data which may be stored at the extended
  183. memory buffer addressed by <xhXM>, or 0 on error.
  184.  
  185.  
  186. .context XMSgetVersion
  187. :z3
  188.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  189. ─────XMSgetVersion──────────────────────────────────────────────────────────
  190.  
  191. \bWORD      XMSgetVersion (void);\p
  192.  
  193. Returns the version number of the XMS specification as a two byte BCD
  194. number containing the major version number in the high byte and the
  195. minor version number in the low byte (e.g. 0x0321 = version 3.21),
  196. or 0 if XMS memory can not be accessed (call XMSopen() first).
  197.  
  198.  
  199. .context XMSinstalled
  200. :z3
  201.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  202. ─────XMSinstalled───────────────────────────────────────────────────────────
  203.  
  204. \bint       XMSinstalled (void);\p
  205.  
  206. Returns TRUE if XMS memory is installed in the system (and a suitable
  207. driver is loaded), else FALSE.  Does not require a prior call to 
  208. XMSopen().
  209.  
  210.  
  211. .context XMSopen
  212. :z3
  213.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  214. ─────XMSopen────────────────────────────────────────────────────────────────
  215.  
  216. \bint       XMSopen (WORD uKbytes);\p
  217.  
  218. Initialises internal library data and attempts to reserve <uKbytes>
  219. kilobytes of XMS memory for the program's use (e.g. XMSopen(100) will
  220. attempt to reserve 100K of XMS memory).
  221.  
  222. If <uKbytes> is 0, XMSopen() will attempt to acquire ALL available
  223. XMS memory for the program's use. (At least 64K of XMS memory must
  224. be available for this feature to work).
  225.  
  226. Returns TRUE if successful, FALSE on error.
  227.  
  228. This function must be called before any functions which allocate, read
  229. or write memory to or from XMS memory. It has a (small) overhead in
  230. conventional memory of about 16 bytes per 64K of XMS used.
  231.  
  232.  
  233. .context XMSput
  234. :z3
  235.                                                      \i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
  236. ─────XMSput─────────────────────────────────────────────────────────────────
  237.  
  238. \bint       XMSput (XMSHANDLE xhXM, const void * pSrc, WORD uBytes);\p
  239.  
  240. Copies <uBytes> characters from buffer <pSrc> to the XMS buffer 
  241. addressed by the handle <xhXM>. The handle must have been reurned
  242. by an earlier call to XMSalloc(), and must not have subsequently been
  243. released by a call to XMSfree().
  244.  
  245. Returns TRUE if successful, or FALSE if an error occurs.
  246.  
  247.