home *** CD-ROM | disk | FTP | other *** search
/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / GLEN / QLIB43.ZIP / EMS.DOC < prev    next >
Text File  |  1990-03-18  |  7KB  |  181 lines
  1. Expanded Memory subroutines take advantage of expanded memory conforming
  2. to the Lotus/Intel/Microsoft (LIM) Expanded Memory Specification (EMS).
  3.  
  4. Three primary versions of the EMS have been released: 3.0, 3.2 and 4.0.
  5. QLIB's EMS subroutines will work with all EMS versions.
  6.  
  7. EMS memory is allocated in "pages" of 16k bytes (actually 16,384 bytes)
  8. each.
  9.  
  10. Error codes returned by QLIB's EMS subroutines are:
  11.  
  12.      0 = no error
  13.      &H80 = memory manager software error - non-recoverable
  14.      &H81 = expanded memory hardware error - non-recoverable
  15.      &H83 = invalid EMS handle
  16.      &H85 = no available EMS handles
  17.      &H87 = not enough memory pages
  18.      &H88 = not enough memory pages available
  19.      &H89 = you tried to allocate zero pages
  20.  
  21.  
  22.      Subroutine: EMS2DBL(handle%, value#, n%, oops%)
  23.      Subroutine: EMS2INT(handle%, value%, n%, oops%)
  24.      Subroutine: EMS2LNG(handle%, value&, n%, oops%)
  25.      Subroutine: EMS2SNG(handle%, value!, n%, oops%)
  26.  
  27.         These subroutines copy value% (or #, &, !) from the nth element
  28.      of an array stored in expanded memory.
  29.  
  30.      Example:
  31.      REM  An integer array has been stored in expanded memory, but
  32.      REM  I need to see what the 18th element of the array is.
  33.      REM  The 18th element is n% = 17, since the first element is
  34.      REM  n% = 0
  35.  
  36.      n% = 17
  37.      CALL EMS2INT(handle%, value%, n%, oops%)
  38.      a$ = "The 18th element is" + STR$(value%)
  39.      PRINT a$
  40.  
  41.  
  42.  
  43.      Subroutine: EMS2DBLArray(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  44.      Subroutine: EMS2INTArray(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  45.      Subroutine: EMS2LNGArray(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  46.      Subroutine: EMS2SNGArray(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  47.  
  48.         These subroutines copy data from an EMS "file" to an array.  See
  49.      INTArray2EMS for examples.
  50.  
  51.  
  52.  
  53.      Subroutine: DBL2EMS(handle%, value#, n%, oops%)
  54.      Subroutine: INT2EMS(handle%, value%, n%, oops%)
  55.      Subroutine: LNG2EMS(handle%, value&, n%, oops%)
  56.      Subroutine: SNG2EMS(handle%, value!, n%, oops%)
  57.  
  58.         Replaces the nth element of an array stored in expanded memory
  59.      with value% (or #, &, !).     This subroutine is the complement of
  60.      EMS2INT (or DBL, LNG, SNG).  See EMS2INT for examples.
  61.  
  62.  
  63.  
  64.      Subroutine: DBLArray2EMS(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  65.      Subroutine: INTArray2EMS(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  66.      Subroutine: LNGArray2EMS(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  67.      Subroutine: SNGArray2EMS(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  68.  
  69.         Copies an array to an EMS "file" opened by EMSopen.  Handle% is
  70.      the "file" handle returned by EMSopen, aSEG% and aPTR% are segment
  71.      and offset pointers to the array, EMSptr% is the first array element
  72.      in the EMS file where copying begins, and n% is the number of array
  73.      elements to copy.   Note that EMSptr% = 0 at the start of the EMS "file".
  74.  
  75.      Example:
  76.      DIM a%(7999)  ' a large integer array of 8000 elements
  77.                    ' this requires 16,000 bytes of EMS memory
  78.                    ' so only one EMS page is needed
  79.      n% = 8000
  80.      pages% = 1
  81.      CALL EMSopen(pages%, handle%, oops%)
  82.      IF oops% THEN ...   ' branch to error handling stuff
  83.  
  84.      EMSptr% = 0         ' start at the beginning of the memory block
  85.      aSEG% = VARSEG(a%(0)): aPTR% = VARPTR(a%(0))
  86.      CALL INTArray2EMS(handle%, aSEG%, aPTR%, EMSptr%, n%, oops%)
  87.  
  88.  
  89.  
  90.      Subroutine: EMSclose(handle%, oops%)
  91.  
  92.         Closes an EMS "file" opened by EMSopen and releases the
  93.      associated expanded memory.  DOS will not release expanded memory
  94.      when the program ends, so you must use EMSclose for all open EMS
  95.      "files" before the program ends.
  96.  
  97.      Example:
  98.      CALL EMSclose(handle%, oops%)
  99.  
  100.  
  101.  
  102.      Subroutine: EMSReady(ready%)
  103.  
  104.         Determines if EMS memory is installed in the computer.  Returns
  105.      ready% = -1 if EMS is installed, ready% = 0 if not.
  106.  
  107.      Example:
  108.      CALL EMSReady(ready%)
  109.      IF ready% THEN
  110.           PRINT "EMS is installed"
  111.           ELSE
  112.           PRINT "no EMS memory or driver not installed"
  113.      END IF
  114.  
  115.  
  116.  
  117.      Subroutine: EMSVersion(maj%, min%)
  118.  
  119.         Determines EMS version installed.  Use EMSReady to determine if
  120.      EMS memory is installed.
  121.  
  122.      Example:
  123.      CALL EMSVersion(maj%, min%)
  124.  
  125.  
  126.   
  127.      Subroutine: EMSSize(total%, free%)
  128.  
  129.         Determines the number of EMS memory pages available.
  130.  
  131.      Example:
  132.      CALL EMSSize(total%, free%)
  133.  
  134.  
  135.  
  136.      Subroutine: EMSopen(pages%, handle%, oops%)
  137.  
  138.         "Opens" an EMS "file" for subsequent operations.  You specify
  139.      how many EMS pages you want (16k bytes, each page), and EMSopen
  140.      returns a handle to use in read/write operations. DOS will not
  141.      release expanded memory when the program ends, so you must use
  142.      QLIB's EMSclose for all "open" EMS "files" before the program ends.
  143.      A maximum of 4 EMS pages (64k bytes) may be allocated to a handle.
  144.  
  145.      Example:
  146.      CALL EMSopen(pages%, handle%,oops%)
  147.  
  148.  
  149.  
  150.      Subroutine: EMSread(handle%, aseg%, aptr%, emsptr%, bytes%, oops%)
  151.  
  152.         Copies data from an EMS file opened by EMSopen to an array.
  153.      aseg% and aptr% are segment and offset pointers to the array, bytes%
  154.      is the number of bytes to be copied, and handle% is the handle returned
  155.      by EMSopen.  EMSptr% is the byte offset in the EMS "file" where you
  156.      want the read to start.  Note that EMSptr% = 0 at the start of the
  157.      "file".  This is a "generic" EMS read subroutine.  Simplified subroutines
  158.      for copying to or from numeric arrays are also available (see EMS2Array
  159.      subroutines).
  160.  
  161.      Example:
  162.      CALL EMSread(handle, aseg%, aptr, emsptr%, bytes%, oops%))
  163.  
  164.  
  165.  
  166.      Subroutine: EMSwrite(handle%, aseg%, aptr%, emsptr%, bytes%, oops%)
  167.  
  168.         Copies data from an array to an EMS file opened by EMSopen.
  169.      aseg% and aptr% are segment and offset pointers to the array, bytes%
  170.      is the number of bytes to be copied, and handle% is the handle returned
  171.      by EMSopen.  EMSptr% is the byte offset in the EMS "file" where you
  172.      want the write to start.  Note that EMSptr% = 0 at the start of the
  173.      "file".  This is a "generic" EMS write subroutine.  Simplified subroutines
  174.      for copying to or from numeric arrays are also available (see EMS2Array
  175.      subroutines).
  176.  
  177.      Example:
  178.      CALL EMSwrite(handle, aseg%, aptr, emsptr%, bytes%, oops%))
  179.  
  180.  
  181.