home *** CD-ROM | disk | FTP | other *** search
/ POINT Software Programming / PPROG1.ISO / basic / qlib / emsxms.doc < prev    next >
Text File  |  1993-05-27  |  28KB  |  798 lines
  1. QLIB5 EMSXMS.DOC expanded and extended memory subroutines
  2. Copyright (C) 1991-1993 Douglas Herr ■ all rights reserved
  3.  
  4.  
  5. Expanded Memory subroutines take advantage of expanded memory conforming
  6. to the Lotus/Intel/Microsoft (LIM) Expanded Memory Specification (EMS).
  7. QLIB EMS subroutines allow your programs to store vast amounts of data in
  8. Expanded memory rather than creating temporary files on a disk.  A well-
  9. designed program using Expanded memory can be much faster than if Expanded
  10. memory isn't used.
  11.  
  12. Three primary versions of the EMS have been released: 3.0, 3.2 and 4.0.
  13. QLIB's EMS subroutines will work with all EMS versions.
  14.  
  15. EMS memory is allocated in "pages" of 16k bytes (actually 16,384 bytes)
  16. each.
  17.  
  18. Error codes returned by QLIB's EMS subroutines are:
  19.  
  20.      0 = no error
  21.      &H80 = memory manager software error - non-recoverable
  22.      &H81 = expanded memory hardware error - non-recoverable
  23.      &H83 = invalid EMS handle
  24.      &H85 = no available EMS handles
  25.      &H87 = not enough memory pages
  26.      &H88 = not enough memory pages available
  27.      &H89 = you tried to allocate zero pages
  28.  
  29.  
  30. XMS memory is available on many 286 or better computers with a suitable
  31. driver.  On 286 computers, XMS memory will be much slower than EMS memory.
  32. XMS memory is not available on XT (or compatible) computers.
  33.  
  34. XMS error codes include:
  35.      0 = no error
  36.      &HA0 = all extended memory is allocated
  37.      &HA1 = no handles available
  38.      &HA2, &HA3, &HA5 = handle is invalid
  39.      &HA4, &HA6 = offset is invalid
  40.      &HA7 = length is invalid
  41.  
  42. QLIB includes disk-based Virtual Memory subroutines (VMS) which make
  43. possible the use of disk space as though it were RAM.  Error codes returned
  44. by VMS subroutines are DOS error codes.
  45.  
  46. QLIB's EMS, VMS and XMS subroutines were written with identical calling
  47. parameters and identical returned information for comparable subroutines.
  48. For example, AllocEMS and AllocXMS are both called with the number of bytes
  49. requested (AllocVMS also requires a filename).
  50.  
  51.  
  52.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  53.  
  54.      Function: handle% = AllocEMS(bytes&)
  55.      object file: ems.obj
  56.  
  57.         Allocates a block of EMS memory, returning a handle for subsequent
  58.      access to the memory block.  Up to 2,097,120 bytes may be allocated
  59.      per handle if that much EMS memory is installed.  Any EMS memory
  60.      blocks must be released with FreeEMS(handle%) before your program ends,
  61.      or the memory allocated by AllocEMS will not be available to any other
  62.      programs.  AllocEMS updates the EMSError flag if something went wrong.
  63.      Note that EMS memory is available in "pages" of 16k bytes; AllocEMS
  64.      will allocate multiple "pages" if required, but any EMS memory
  65.      allocation will be in multiples of 16k bytes.
  66.  
  67.      Example:
  68.         REM $INCLUDE: 'qlib.bi'
  69.         .
  70.         .
  71.         .
  72.         bytes& = 32000
  73.         handle% = AllocEMS(bytes&)
  74.         IF EMSError THEN ...            ' check for errors
  75.  
  76.  
  77.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  78.  
  79.      Function: handle% = AllocVMS(filename$, bytes&)
  80.      object file: allocvms.obj
  81.  
  82.         Reserves disk space for use as VMS memory, returning a handle for
  83.      subsequent access.  You must supply a filename for AllocVMS to use;
  84.      if a file of the same name already exists, is is lost.  Up to 2,097,120
  85.      bytes may be allocated (if you have that much disk space!!) per handle.
  86.      AllocVMS updates the DOSError flag if something went wrong.
  87.  
  88.      Example:
  89.         REM $INCLUDE: 'qlib.bi'
  90.         .
  91.         .
  92.         .
  93.         bytes& = 32000
  94.         filename$ = "vms1.tmp"
  95.         call AllocVMS(filename$, bytes&)
  96.         IF DOSError THEN ...             ' check for runtime errors
  97.  
  98.  
  99.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  100.  
  101.      Function: handle% = AllocXMS(bytes&)
  102.      object file: xms.obj
  103.  
  104.         Allocates a block of memory from extended memory, returning a
  105.      handle for subsequent access to the memory block.  AllocXMS updates
  106.      the XMSError flag if something went wrong.  Before exiting your program,
  107.      you must release any XMS handles with FreeXMS(handle%), or else
  108.      the memory allocated by AllocXMS will not be available to any other
  109.      programs.  XMS handles are in short supply, so you should plan your
  110.      program to use fewer large XMS blocks rather than many small XMS
  111.      blocks.  Note that bytes& is a LONG integer, and you may allocate as
  112.      much memory as your system has, up to 2,147,450,880 bytes.
  113.  
  114.      Example:
  115.         REM $INCLUDE: 'qlib.bi'
  116.         IF IsXMS THEN
  117.            bytes& = 100000
  118.            handle% = AllocXMS(bytes&)   ' allocate memory from XMS pool
  119.            IF XMSError GOTO oops
  120.         .
  121.         .
  122.         .
  123.  
  124.  
  125.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  126.  
  127.      Function: oops% = EMSError
  128.      object file: ems.obj
  129.  
  130.         EMSError is used after using a QLIB EMS function or subroutine to
  131.      determine if there was an EMS problem.  EMS error codes are listed on
  132.      the first page of this EMSXMS.DOC.
  133.  
  134.      Example:
  135.      REM $INCLUDE: 'qlib.bi'
  136.           .
  137.           .
  138.           .
  139.      handle% = AllocEMS(bytes&)
  140.      IF EMSError THEN  ...             ' test for errors
  141.                                        ' handle no good if errors
  142.  
  143.  
  144.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  145.  
  146.      Function: free& = EMSFree
  147.      object file: emsfree.obj
  148.  
  149.         EMSFree determines the total unallocated EMS memory available to
  150.      your program.  Note that free& is a LONG integer.
  151.  
  152.      Example:
  153.  
  154.      REM $INCLUDE: 'qlib.bi'
  155.      IF IsEMS THEN free& = EMSFree   ' get EMS memory available
  156.  
  157.  
  158.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  159.  
  160.      Function: total& = EMSTotal
  161.      object file: emsfree.obj
  162.  
  163.         EMSTotal determines the total EMS memory installed in the computer.
  164.      Note that total& is a LONG integer.
  165.  
  166.      Example:
  167.  
  168.      REM $INCLUDE: 'qlib.bi'
  169.      IF IsEMS THEN total& = EMSTotal   ' get EMS memory installed
  170.  
  171.  
  172.  
  173.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  174.  
  175.      Subroutine: EMSVersion(maj%, min%)
  176.      object file: ems30.obj
  177.  
  178.         Determines EMS version installed.  Use EMSReady to determine if
  179.      EMS memory is installed.
  180.  
  181.      Example:
  182.      CALL EMSVersion(maj%, min%)
  183.  
  184.  
  185.  
  186.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  187.  
  188.      Subroutine: EMGet(handle%, emsptr&, aseg%, aptr%, bytes&)
  189.      object file: emputget.obj (huge model: lowds2hi.obj)
  190.  
  191.         Copies data from EMS memory allocated by AllocEMS to an array.
  192.      aseg% and aptr% are segment and offset pointers to the array, bytes&
  193.      is the number of bytes to be copied, and handle% is the handle returned
  194.      by AllocEMS.  EMSptr& is the byte offset in the EMS memory block where
  195.      you want the read to start.  Note that EMSptr& = 0 at the start of the
  196.      block.  EMGet updates the EMSError flag.
  197.  
  198.      Example:
  199.      REM $INCLUDE: 'qlib.bi'
  200.      CALL EMGet(handle%, emsptr&, aseg%, aptr, bytes&)
  201.      IF EMSError THEN                                  ' check for errors
  202.  
  203.  
  204.  
  205.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  206.  
  207.      Subroutine: EMGet1(handle%, emsptr&, number%)
  208.      Subroutine: EMGet2(handle%, emsptr&, number%)
  209.      Subroutine: EMGet4(handle%, emsptr&, number[& or !])
  210.      Subroutine: EMGet8(handle%, emsptr&, number[# or @])
  211.      object file: emget.obj ($emspage.obj)
  212.  
  213.         Copies data from EMS memory to a single number.  EMGet1 gets a
  214.      single byte, EMGet2 gets an INTEGER, EMGet4 gets a LONG or SINGLE
  215.      number, and EMGet8 gets a DOUBLE, CURRENCY or COMPLEX number.
  216.      (COMPLEX number support may be found in COMPLEX.DOC.)  EMGet[n]
  217.      sets the EMSError flag if something went wrong.
  218.  
  219.      handle%                 = EMS handle
  220.      emsptr&                 = (LONG) offset of the number in the EMS block
  221.      number[%, &, !, # or @] = number returnd by EMGet[n]
  222.  
  223.      Example:
  224.         REM $INCLUDE: 'qlib.bi'
  225.         DIM a#(999)              ' DOUBLE array
  226.                                  ' program establishes values for array
  227.         .
  228.         .
  229.         .
  230.         REM  save a#() in EMS memory
  231.         IF IsEMS THEN
  232.              bytes& = CLNG(1000& * 8)            ' DOUBLE data is 8 bytes long
  233.              handle% = AllocEMS(bytes&)
  234.              IF EMSError THEN ...                ' check for errors
  235.  
  236.              aseg% = VARSEG(a#(0)): aptr% = VARPTR(a#(0))
  237.              emsptr& = 0
  238.              CALL EMPut(handle%, emsptr&, aseg%, aptr%, bytes&)
  239.              IF EMSError THEN ...                ' check for errors
  240.              .
  241.              .
  242.         ENDIF
  243.         .
  244.         .
  245.         REM I need to retrieve a#(12) from EMS
  246.         emsptr& = CLNG(12 * 8)                   ' calculate offset in EMS
  247.         CALL EMGet8(handle%, emsptr&, a#(12))
  248.  
  249.  
  250.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  251.  
  252.      Subroutine: EMPut(handle%, emoffset&, dataseg%, dataptr%, bytes&)
  253.      object file: emputget.obj ($emspage.obj)
  254.  
  255.          EMPut copies data to EMS memory from DOS or BASIC memory blocks.
  256.      EMPut safely handles even huge blocks of data > 64k in size.
  257.  
  258.      Example:
  259.          REM $INCLUDE: 'qlib.bi'
  260.          REM  I'll use expanded memory to store several 25-row text screens
  261.          REM  while I use graphics mode
  262.  
  263.          IF NOT IsEMS THEN
  264.               PRINT "This example uses EXPANDED memory"
  265.               PRINT "You cannot run this demo": END
  266.          ENDIF
  267.  
  268.          bytes& = 16000                    ' EMS drivers allocate
  269.                                            ' a minimum of 16k per block
  270.          handle% = AllocEMS(bytes&)
  271.          IF EMSError THEN
  272.               PRINT "There's a problem with EMS memory"
  273.               PRINT "You cannot run this demo": END
  274.          ENDIF
  275.  
  276.          bytes& = 4000                     ' 4,000 bytes for 80x25 screen
  277.          screenseg = &HB800                ' color monitor
  278.          emoffset& = 0
  279.  
  280.          FOR i = 0 to 3
  281.          CALL EMPut(handle%, emoffset&, screenseg, 0, bytes&)
  282.          emoffset& = emoffset& + bytes&
  283.          screenseg = screenseg + &H100
  284.          NEXT i
  285.          .
  286.          .
  287.          .
  288.  
  289.          REM  sometime later ...
  290.  
  291.          bytes& = 4000                     ' 4,000 bytes for 80x25 screen
  292.          screenseg = &HB800                ' color monitor
  293.          emoffset& = 0
  294.  
  295.          FOR i = 0 to 3
  296.          CALL EMGet(handle%, emoffset&, screenseg, 0, bytes&)
  297.          emoffset& = emoffset& + bytes&
  298.          screenseg = screenseg + &H0100
  299.          NEXT i
  300.  
  301.  
  302.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  303.  
  304.      Subroutine: EMPut1(handle%, emsptr&, number%)
  305.      Subroutine: EMPut2(handle%, emsptr&, number%)
  306.      Subroutine: EMPut4(handle%, emsptr&, number[& or !])
  307.      Subroutine: EMPut8(handle%, emsptr&, number[# or @])
  308.      object file: emget.obj ($emspage.obj)
  309.  
  310.         Copies data to EMS memory from a single number.  EMPut1 copies a
  311.      single byte, EMPut2 copies an INTEGER, EMPut4 copies a LONG or SINGLE
  312.      number, and EMPut8 copies a DOUBLE, CURRENCY or COMPLEX number.
  313.      (COMPLEX number support may be found in COMPLEX.DOC.)  EMPut[n]
  314.      sets the EMSError flag if something wnet wrong.
  315.  
  316.      handle%                 = EMS handle
  317.      emsptr&                 = (LONG) offset of the number in the EMS block
  318.      number[%, &, !, # or @] = number to be copied to EMS memory
  319.  
  320.      Example:
  321.         REM $INCLUDE: 'qlib.bi'
  322.         DIM a#(999)              ' DOUBLE array
  323.                                  ' program establishes values for array
  324.         .
  325.         .
  326.         .
  327.         REM  save a#() in EMS memory
  328.         IF IsEMS THEN
  329.              bytes& = CLNG(1000& * 8)            ' DOUBLE data is 8 bytes long
  330.              handle% = AllocEMS(bytes&)
  331.              IF EMSError THEN ...                ' check for errors
  332.  
  333.              aseg% = VARSEG(a#(0)): aptr% = VARPTR(a#(0))
  334.              emsptr& = 0
  335.              CALL EMPut(handle%, emsptr&, aseg%, aptr%, bytes&)
  336.              IF EMSError THEN ...                ' check for errors
  337.              .
  338.              .
  339.         ENDIF
  340.         .
  341.         .
  342.         REM a#(12) has changed and I need to update the the copy in EMS
  343.         emsptr& = CLNG(12 * 8)                   ' calculate offset in EMS
  344.         CALL EMPut8(handle%, emsptr&, a#(12))
  345.         IF EMSError THEN ...                     ' check for errors
  346.         
  347.  
  348.  
  349.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  350.  
  351.      Function: handle% = FLoadEMS(filename$)
  352.      object file: floadems.obj (ems.obj, q$alloc.obj, $asciiz.obj, fsize.obj)
  353.  
  354.         FLoadEMS reads a file from a disk and copies it into EMS memory.
  355.      FLoadEMS assumes that EMS is installed.  Use IsEMS to determine if
  356.      the computer has EMS memory.  FLoadEMS temporarily uses 16k of DOS
  357.      memory to read the file, but the file may be any size, up to
  358.      2,147,450,880 bytes if that much EMS is available.  This shouldn't be
  359.      a problem.  Several files may be loaded in EMS memory if memory is
  360.      available.  Use FreeEMS to release the EMS memory when you're done
  361.      using it.  If you don't release the EMS memory before the program
  362.      ends, that memory will not be available to other programs.
  363.  
  364.      Handle% returnd by FLoadEMS is a valid EMS handle, unless either
  365.      DOSError or EMSError <> 0.
  366.  
  367.      FLoadEMS fails if insufficient EMS memory is available, if 16k DOS
  368.      memory is not available, or if the specified file cannot be opened or
  369.      read.  See EMSError in this EMSXMS.DOC and DOSError in SYSTEM.DOC.
  370.  
  371.      Example:
  372.      REM $INCLUDE: 'qlib.bi'
  373.      SCREEN 12                          ' VGA graphics mode
  374.  
  375.      ' progam draws something on screen
  376.      ' I want to save the screen for later
  377.  
  378.      filename$ = "screen.12"            ' clever (?) file name
  379.      CALL GSave(filename$, oops)        ' see GRAPHICS.DOC
  380.      IF oops THEN                       ' check for errors
  381.          .
  382.          .
  383.          .
  384.      ENDIF
  385.          .
  386.          .
  387.          .
  388.      ' load "screen.12" into EMS memory
  389.      ' and copy to the screen
  390.      handle% = FLoadEMS(filename$)
  391.      IF DOSError OR EMSError THEN       ' check for errors
  392.          .                              ' handle% not valid if error
  393.          .
  394.          .
  395.      ENDIF
  396.      CALL GLoadEMS(handle%)             ' see GRAPHICS.DOC
  397.      IF EMSError THEN ...               ' more error control
  398.  
  399.      ' all done: release EMS memory
  400.      CALL FreeEMS(handle%)
  401.  
  402.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  403.  
  404.      Function: handle% = FLoadXMS(filename$)
  405.      object file: floadxms.obj (xms.obj, q$alloc.obj, $asciiz.obj, fsize.obj)
  406.  
  407.      Similar to FLoadEMS on previous page, but uses XMS memory instead of
  408.      EMS memory.
  409.  
  410.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  411.  
  412.      Subroutine: FreeEMS(handle%)
  413.      object file: ems.obj
  414.  
  415.      Releases a block of EMS memory allocated by AllocEMS.  Your program
  416.      should release any EMS blocks before the program terminates, or that
  417.      memory will not be available to other programs.  Do not confuse this
  418.      subroutine with the EMSFree function, which determines the total
  419.      expanded memory available.
  420.  
  421.      Example:
  422.          REM $INCLUDE: 'qlib.bi'
  423.          REM  this example allocates an EMS memory block and later
  424.          REM  releases it
  425.  
  426.          REM  see if extended memory is available
  427.          REM  and set a flag if so
  428.          EMSused = 0
  429.          IF IsEMS THEN
  430.               EMSused = 1
  431.               bytes& = 16384                  ' one EMS "page"
  432.               handle% = AllocEMS(bytes&)
  433.               IF EMSError THEM EMSused = 0
  434.          ENDIF
  435.          .                                   ' more program here
  436.          .
  437.          .
  438.          REM  release the EMS memory
  439.          CALL FreeEMS(handle%)
  440.  
  441.  
  442.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  443.  
  444.      Subroutine: FreeVMS(filename$, handle%)
  445.      object file: freevms.obj
  446.  
  447.      Closes and deletes temporary file used as VMS memory.  If you do not
  448.      call FreeVMS, you may end up with a disk full of temporary files.
  449.  
  450.      Example:
  451.          REM $INCLUDE: 'qlib.bi'
  452.          REM  this example allocates a VMS memory block and later
  453.          REM  releases it
  454.  
  455.          bytes& = 16384                      ' 16k
  456.          filename$ = "vms1.tmp"
  457.          handle% = AllocVMS(filename$, bytes&)
  458.          .                                   ' more program here
  459.          .
  460.          .
  461.          REM  release the VMS memory
  462.          CALL FreeVMS(filename$, handle%)
  463.  
  464.  
  465.  
  466.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  467.  
  468.      Subroutine: FreeXMS(handle%)
  469.      object file: xms.obj
  470.  
  471.      De-allocates (releases) extended memory allocated by AllocXMS.  Your
  472.      program should release all XMS memory block before exiting, or those
  473.      blocks will not be available to other programs.  Do not confuse this
  474.      subroutine with the XMSFree function, which determines the total
  475.      extended memory available.
  476.  
  477.      Example:
  478.          REM $INCLUDE: 'qlib.bi'
  479.          REM  this example allocates an XMS memory block and later
  480.          REM  releases it
  481.  
  482.          REM  see if extended memory is available
  483.          REM  and set a flag if so
  484.          XMSused = 0
  485.          IF IsXMS THEN
  486.               XMSused = 1
  487.               bytes& = 16384                 ' 16 kbytes
  488.               handle% = AllocXMS(kbytes&)
  489.               IF XMSError THEM XMSused = 0
  490.          ENDIF
  491.          .                                   ' more program here
  492.          .
  493.          .
  494.          REM  release the XMS memory
  495.          CALL FreeXMS(handle%)
  496.  
  497.  
  498.  
  499.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  500.  
  501.      Function: r% = IsEMS
  502.      object file: isems.obj
  503.  
  504.         Determines if EMS memory is installed in the computer.  Returns
  505.      r% = -1 if EMS is installed, r% = 0 if not.
  506.  
  507.      Example:
  508.      REM $INCLUDE: 'qlib.bi'
  509.  
  510.      IF IsEMS THEN
  511.           PRINT "EMS is installed"
  512.           ELSE
  513.           PRINT "no EMS memory or driver not installed"
  514.      END IF
  515.  
  516.  
  517.  
  518.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  519.  
  520.      Function: r% = IsXMS
  521.      object file: xms.obj
  522.  
  523.         Determines if XMS memory is installed in the computer.  Returns
  524.      r% = -1 if XMS is installed, r% = 0 if not.
  525.  
  526.      Example:
  527.      REM $INCLUDE: 'qlib.bi'
  528.  
  529.      IF IsXMS THEN
  530.           PRINT "XMS is installed"
  531.           ELSE
  532.           PRINT "no XMS memory or driver not installed"
  533.      END IF
  534.  
  535.  
  536.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  537.  
  538.      Subroutine: ReallocEMS(handle%, bytes&)
  539.      object files: realloce.obj (ems.obj)
  540.  
  541.      Requires EMS version 4.0
  542.  
  543.      ReallocEMS re-sizes an existing EMS memory block allocated by AllocEMS.
  544.      You may make the block larger or smaller with ReallocEMS.  Note that
  545.      bytes& is a LONG integer.
  546.  
  547.      Example:
  548.         REM $INCLUDE: 'qlib.bi'
  549.         .
  550.         .
  551.         .
  552.         bytes& = 32000
  553.         handle% = AllocEMS(bytes&)
  554.         IF EMSError THEN ...            ' check for errors
  555.         .
  556.         .
  557.         .
  558.         ' now I need to make the EMS block larger
  559.         bytes& = 72000
  560.         CALL ReallocEMS(handle%, bytes&)
  561.         IF EMSError THEN ...            ' check for errors
  562.  
  563.  
  564.  
  565.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  566.  
  567.      Subroutine: ReallocVMS(handle%, bytes&)
  568.      object files: reallocv.obj
  569.  
  570.      ReallocVMS re-sizes an existing VMS memory block allocated by AllocVMS.
  571.      Unlike ReallocEMS or ReallocXMS, ReallocVMS will only make the VMS
  572.      memory block larger.  If bytes& is smaller than the existing block
  573.      size, ReallocVMS does nothing.  Note that bytes& is a LONG integer.
  574.  
  575.      Example:
  576.         REM $INCLUDE: 'qlib.bi'
  577.         .
  578.         .
  579.         .
  580.         bytes& = 32000
  581.         filename$ = "tempfile.vms"
  582.         handle% = AllocVMS(filename$, bytes&)
  583.         IF DOSError THEN ...            ' check for errors
  584.         .
  585.         .
  586.         .
  587.         ' now I need to make the VMS block larger
  588.         bytes& = 72000
  589.         CALL ReallocVMS(handle%, bytes&)
  590.         IF DOSError THEN ...            ' check for errors
  591.  
  592.  
  593.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  594.  
  595.      Subroutine: ReallocXMS(handle%, bytes&)
  596.      object files: reallocx.obj (xms.obj)
  597.  
  598.      ReallocXMS re-sizes an existing XMS memory block allocated by AllocXMS.
  599.      You may make the block larger or smaller with ReallocXMS.  Note that
  600.      bytes& is a LONG integer.
  601.  
  602.      Example:
  603.         REM $INCLUDE: 'qlib.bi'
  604.         .
  605.         .
  606.         .
  607.         bytes& = 32000
  608.         handle% = AllocXMS(bytes&)
  609.         IF XMSError THEN ...            ' check for errors
  610.         .
  611.         .
  612.         .
  613.         ' now I need to make the XMS block larger
  614.         bytes& = 72000
  615.         CALL ReallocXMS(handle%, bytes&)
  616.         IF XMSError THEN ...            ' check for errors
  617.  
  618.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  619.  
  620.      Subroutine: VMGet(handle%, vmoffset&, dataseg%, dataoffset%, bytes&)
  621.      object files: vmputget.obj (lowes2hi.obj)
  622.  
  623.      VMGet copies data from a virtual memory block to DOS memory.
  624.      handle% is the VMS handle returned by AllocVMS, vmoffset is the
  625.      location in the virtual memory block where the data is stored (the
  626.      start of the block is at vmoffset& = 0), dataseg% and dataoffset%
  627.      define the location of the DOS memory area and bytes& is the number of
  628.      bytes to copy from extended memory to DOS memory.
  629.      Note that vmoffset& and bytes& are both LONG integers.
  630.  
  631.      Example:
  632.          REM $INCLUDE 'qlib.bi'
  633.          REM  I'll use virtual memory to store several 25-row text screens
  634.          REM  while I use graphics mode
  635.  
  636.          bytes& = 16384
  637.          handle% = AllocVMS(bytes&)
  638.          IF DOSError THEN
  639.               PRINT "There's a problem with VMS memory"
  640.               PRINT "You cannot run this demo": END
  641.          ENDIF
  642.  
  643.          bytes& = 4000                     ' 4,000 bytes for 80x25 screen
  644.          screenseg = &HB800                ' color monitor
  645.          vmoffset& = 0
  646.  
  647.          FOR i = 0 to 3
  648.          CALL VMPut(handle%, vmoffset&, screenseg, 0, bytes&)
  649.          vmoffset& = vmoffset& + bytes&
  650.          screenseg = screenseg + &H100
  651.          NEXT i
  652.          .
  653.          .
  654.          .
  655.  
  656.          REM  sometime later ...
  657.  
  658.          bytes& = 4000                     ' 4,000 bytes for 80x25 screen
  659.          screenseg = &HB800                ' color monitor
  660.          vmoffset& = 0
  661.  
  662.          FOR i = 0 to 3
  663.          CALL VMGet(handle%, vmoffset&, screenseg, 0, bytes&)
  664.          vmoffset& = vmoffset& + bytes&
  665.          screenseg = screenseg + &H0100
  666.          NEXT i
  667.  
  668.  
  669.  
  670.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  671.  
  672.      Subroutine: VMPut(handle%, vmoffset&, dataseg%, dataoffset%, bytes&)
  673.      object files: vmputget.obj (xms.obj)
  674.  
  675.      VMPut copies data from DOS memory to a virtual memory block.
  676.      See VMGet for example.
  677.  
  678.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  679.  
  680.      Function: kbytes% = XMSContig
  681.      object file: xmscont.obj (xms.obj)
  682.  
  683.      XMSContig determines the largest contiguous XMS memory block available
  684.      to your program.  The total available extended memory may more than
  685.      the value returned by XMSContig; see XMSFree.
  686.      Note that the number returned by XMSContig is kbytes, not bytes.
  687.  
  688.      Example:
  689.          REM $INCLUDE: 'qlib.bi'
  690.          IF IsXMS THEN
  691.              PRINT "Total XMS memory available is ";
  692.              PRINT XMSFree
  693.              PRINT "The largest contiguous XMS block is ";
  694.              PRINT XMSContig
  695.          ENDIF
  696.  
  697.  
  698.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  699.  
  700.      Function: errorcode% = XMSError
  701.      object file: xms.obj
  702.  
  703.      XMSError is used after a call to a QLIB XMS subroutine to determine if
  704.      an error was encountered by the XMS driver.
  705.  
  706.      Example:
  707.          REM $INCLUDE: 'qlib.bi'
  708.          IF IsXMS THEN
  709.              maxXMS = XMSFree              ' get total XMS memory available
  710.              IF XMSError THEN ...          ' check for errors after XMSFree
  711.          .
  712.          .
  713.          .
  714.  
  715.  
  716.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  717.  
  718.      Function: kbytes% = XMSFree
  719.      object file: xmsfree.obj (xms.obj)
  720.  
  721.      XMSFree determines the total XMS memory available to your program.
  722.      The available extended memory may not be contiguous; see XMSContig
  723.      to determine the largest contiguous block of XMS memory available.
  724.      Note that the number returned by XMSFree is kbytes, not bytes.
  725.      Do not confuse this function with the FreeXMS subroutine, which
  726.      releases a previously allocated XMS memory block.
  727.  
  728.      Example:
  729.          REM $INCLUDE: 'qlib.bi'
  730.          IF IsXMS THEN
  731.              PRINT "Total XMS memory available is ";
  732.              PRINT XMSFree
  733.          ENDIF
  734.  
  735.  
  736.  
  737.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  738.  
  739.      Subroutine: XMGet(handle%, xmoffset&, dataseg%, dataoffset%, bytes&)
  740.      object files: xmputget.obj (xms.obj)
  741.  
  742.      XMGet copies data from an extended memory block to DOS memory.
  743.      handle% is the XMS handle returned by AllocXMS, xmoffset is the
  744.      location in the extended memory block where the data is stored (the
  745.      start of the block is at xmoffset& = 0), dataseg% and dataoffset%
  746.      define the location of the DOS memory area and bytes& is the number of
  747.      bytes to copy from extended memory to DOS memory.
  748.      Note that xmoffset& and bytes& are both LONG integers.
  749.  
  750.      Example:
  751.          REM $INCLUDE 'qlib.bi'
  752.          REM  I'll use extended memory to store several 25-row text screens
  753.          REM  while I use graphics mode
  754.  
  755.          IF NOT IsXMS THEN PRINT "This example uses EXTENDED memory": END
  756.  
  757.          bytes& = 16384
  758.          handle% = AllocXMS(bytes&)
  759.          IF XMSError THEN
  760.               PRINT "There's a problem with XMS memory"
  761.               PRINT "You cannot run this demo": END
  762.          ENDIF
  763.  
  764.          bytes& = 4000                     ' 4,000 bytes for 80x25 screen
  765.          screenseg = &HB800                ' color monitor
  766.          xmoffset& = 0
  767.  
  768.          FOR i = 0 to 3
  769.          CALL XMPut(handle%, xmoffset&, screenseg, 0, bytes&)
  770.          xmoffset& = xmoffset& + bytes&
  771.          screenseg = screenseg + &H100
  772.          NEXT i
  773.          .
  774.          .
  775.          .
  776.  
  777.          REM  sometime later ...
  778.  
  779.          bytes& = 4000                     ' 4,000 bytes for 80x25 screen
  780.          screenseg = &HB800                ' color monitor
  781.          xmoffset& = 0
  782.  
  783.          FOR i = 0 to 3
  784.          CALL XMGet(handle%, xmoffset&, screenseg, 0, bytes&)
  785.          xmoffset& = xmoffset& + bytes&
  786.          screenseg = screenseg + &H0100
  787.          NEXT i
  788.  
  789.  
  790.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  791.  
  792.      Subroutine: XMPut(handle%, xmoffset&, dataseg%, dataoffset%, bytes&)
  793.      object files: xmputget.obj (xms.obj)
  794.  
  795.      XMPut copies data from DOS memory to an extended memory block.
  796.      See XMGet for example.
  797.  
  798.