home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / CPROG / XMS.ZIP / XMS.DOC < prev    next >
Text File  |  1993-03-18  |  16KB  |  354 lines
  1.     
  2.                                    XMS.ASM
  3.                     Extended Memory Driver for QuickBASIC 4.0+
  4.     
  5.                        (C) 1993 by One World Software.
  6.                                  P.O. Box 269
  7.                             Bronston, KY 42518-0269
  8.                               BBS: (606) 561-5766
  9.                               Author: Robin Duffy
  10.     
  11.          Now you can use extended memory (if available) from your
  12.     QuickBASIC programs with just a few simple calls. This package
  13.     provides a rudimentry interface to HIMEM.SYS for QuickBASIC 4.0+ and
  14.     BASCOM 6. Routines are provided to initialize, allocate, release, and
  15.     otherwise manipulate XMS memory directly from your program.
  16.     
  17.          My personal thanks go to Ethan Winer. The overall concept of an
  18.     interface for XMS memory was inspired by his method of interfacing
  19.     expanded memory with QuickBASIC. Without his brilliant work I would
  20.     have never thought to set this up as an integrated package.
  21.     
  22.      REQUIREMENTS:
  23.     
  24.          1. Requires a 80286 or better processor that has extended
  25.             memory available (goes without saying).
  26.     
  27.          2. Requires HIMEM.SYS to be loaded via CONFIG.SYS.  These
  28.             routines will work with extended memory managers that adhere
  29.             to the Lotus/Intel/Microsoft/AST eXtended Memory Specification
  30.             (XMS) version 2.0 or greater and will not work with other
  31.             extended memory managers.
  32.     
  33.          3. Requires DOS 3.0 or greater. This is a requirement of HIMEM
  34.             and not of this software. These routines may be called with
  35.             any DOS version, but will only work if HIMEM is loaded.
  36.     
  37.     INSTALLATION:
  38.     
  39.          The XMS driver is provided as an object file ready for inclusion
  40.     in your favorite library. You will need LIB.EXE and LINK.EXE to create
  41.     linking and Quick libraries. To add XMS.OBJ to your library you can
  42.     use the following command:
  43.     
  44.               LIB  mylib +xms;
  45.     
  46.     where mylib is the name of your present linking library. If you do not
  47.     use special libraries, use the default library QB.LIB.
  48.     
  49.          Next create a Quick library for use in the editing environment
  50.     with LINK.EXE like this:
  51.     
  52.               LINK /q/se:256 mylib.lib xms,,nul,bqlb40
  53.     
  54.     If you are using QB 4.5, substitute BQLB45 for bqlb40.
  55.     
  56.          XMS is now ready for use. Start the QB environment with the /L
  57.     switch and the name of your Quick library to make it available inside
  58.     the QB editor.
  59.     
  60.     GENERAL NOTES:
  61.     
  62.          1. This code will work in the QB environment. However, you must
  63.             explicitly release the memory you have allocated from your
  64.             program BEFORE IT ENDS. QB will NOT release it when it exits!
  65.             You may otherwise set breakpoints, trace, etc. without any
  66.             problems. Do not make edits that require program restarts or
  67.             the memory will be lost until the next reboot.
  68.     
  69.          2. Remember that if XMSError shows an error, any subsequent
  70.             successful operation will reset it to zero. See XMSError
  71.             later in this text for more info.
  72.     
  73.          3. Writes and reads from extended memory take a little longer
  74.             than accesses to conventional memory. This is not a fault
  75.             of this software. Rather, it takes time for HIMEM.SYS to
  76.             switch the processor in and out of protected mode. However,
  77.             these extended accesses are still hundreds of times faster
  78.             than disk accesses.
  79.     
  80.          4. All these routines may be safely called on any machine even if
  81.             it has no extended memory.  They all reference a flag set by
  82.             InitXMS, and just return if no memory is available.  This
  83.             greatly simplifies the effort required to use this stuff.
  84.     
  85.          In the spirit of programmer to programmer, I am not requiring any
  86.     compensation for the use of these routines. You may use them as you
  87.     see fit. However, since these routines are free, I will not be held
  88.     responsible for any damages resulting from use of these routines.
  89.     Likewise I do not guarrantee the accuracy of any information provided
  90.     here. It would be a nice gesture if you mention where you got this in
  91.     your program source code.
  92.     
  93.          Below is a reference for the routines supported by this driver.
  94.     Although crude at this point, the routines still provide a very usable
  95.     and convenient interface for extended memory. Unless otherwise noted,
  96.     all parameters are integers.
  97.     
  98.     ----------------------------------------------------------------------
  99.     INITXMS: Basic sub
  100.     
  101.          This routine must be called prior to any others in this driver
  102.     for extended memory to be available for your program.
  103.     
  104.          CALL InitXMS(There%, MemSize%)
  105.     
  106.          There% - on exit will contain a -1 (XMS is good) or a zero (XMS
  107.                   not installed or unavailable).
  108.     
  109.          MemSize% - if There% is -1, this will contain the amount of
  110.                   extended memory available (in K bytes) for your use.
  111.                   This will probably be less than the machine total
  112.     ---------------------------------------------------------------------
  113.     XMSERROR: Basic function
  114.     
  115.          This function returns the success of the last XMS operation. You
  116.     may test the success of any operation right afterward by referencing
  117.     this function.  Because it is a function, it must be declared before
  118.     it may be used.
  119.     
  120.          DECLARE FUNCTION XMSError%()
  121.     
  122.          Status% = XMSError%
  123.     
  124.          Status%  -  0 = last operation sucessful
  125.                     -1 = last operation resulted in error
  126.     
  127.          You can test this function after every routine except for
  128.     InitXMS. It should be noted that any sucessful operation after the
  129.     operation causing the error will clear this function. If extended
  130.     memory is not available (for whatever reason), this function will
  131.     always return an error condition (because XMS memory is not there).
  132.     
  133.          See also WhichXError, which returns the actual error code, and
  134.     the table of error codes at the end of this text.
  135.     ---------------------------------------------------------------------
  136.     GETXMS: Basic function
  137.     
  138.          This function allocates an extended memory block for your use and
  139.     returns a handle (much like DOS file handles) used for all future
  140.     references to this block. Your program can use multiple blocks.
  141.     Because it is a function, it must be declared before it may be used.
  142.     
  143.          DECLARE FUNCTION GetXMS%(Amount%)
  144.     
  145.          Handle% = GetXMS(Amount%)
  146.     
  147.     Where:
  148.          Handle% - returns the block handle. 0 means error in allocation.
  149.     
  150.          Amount% - On entry, set this to the size block desired (in K
  151.                    bytes).
  152.     ---------------------------------------------------------------------
  153.     FREEXMS: Basic sub
  154.     
  155.          This sub will release memory allocated by GetXMS.
  156.     
  157.          CALL FreeXMS(Handle%)
  158.     
  159.          where Handle% is the block handle assigned by GetXMS. It is
  160.     important to release any memory you allocate prior to exiting your
  161.     program. This memory is not automatically released by DOS at
  162.     termination as is conventional memory, but instead remains allocated.
  163.     Failure to deallocate XMS memory will cause it to be "lost" until the
  164.     next time the host machine is rebooted.
  165.     ---------------------------------------------------------------------
  166.     ARRAY2XMS: Basic sub
  167.     
  168.          This sub will copy a block from conventional far memory to an
  169.     allocated block of XMS memory. This block may be all or part of an
  170.     integer, long integer, or user type array. Using the optional long
  171.     syntax you may save any continuous portion of convential memory to
  172.     XMS, including the screen!
  173.     
  174.         CALL Array2XMS(SEG Array%(Start%), Handle%, NumBytes&)
  175.                               or
  176.         CALL Array2XMS(BYVAL FromSeg%, BYVAL FromOff%, Handle%, NumBytes&)
  177.     
  178.     Where:
  179.          Array%(Start%) - Start of conventional memory block to transfer
  180.     
  181.          Handle% - Handle assigned by GetXMS
  182.     
  183.          NumBytes& - long integer specifying the number of bytes to
  184.               transfer.  If a constant is used, it should be appended
  185.               by a "&" specifier (forcing a long reference).
  186.     
  187.          Optionally, you can pass the starting segment and offset of the
  188.     source block by using the BYVAL keyword.
  189.     ---------------------------------------------------------------------
  190.     XMS2ARRAY: Basic sub
  191.     
  192.          This sub will copy a previously saved block from extended memory
  193.     to a block in conventional memory. This is the compliment to Array2XMS.
  194.     
  195.          CALL XMS2Array(Handle%, SEG Array%(Start%), NumBytes&)
  196.                              or
  197.          CALL XMS2Array(Handle%, BYVAL ToSeg%, BYVAL ToOff%, NumBytes&)
  198.     
  199.     Where:
  200.          Handle% - handle of XMS block of stored data
  201.     
  202.          Array(Start%) - start of destination block in normal memory.
  203.     
  204.          NumBytes&  - long integer specifying the number of bytes to
  205.               transfer. If a constant is used, it should be appended
  206.               by a "&" specifier (forcing a long reference).
  207.     
  208.          Optionally, you can pass the starting segment and offset of the
  209.     destination block by using the BYVAL keyword.
  210.     ---------------------------------------------------------------------
  211.     XGETELEMENT: Basic sub
  212.     
  213.           This sub will return a portion of a block of XMS memory into a
  214.           variable. This is handy for retrieving a single value from a
  215.           saved block of XMS.
  216.     
  217.         CALL XGetElement(Handle%, Variable, EleLen%, EleNum%)
  218.     
  219.     Where:
  220.         Handle% - Handle assigned to XMS block by GetXMS
  221.     
  222.         Variable - Variable to receive the returned value. This variable
  223.               can be any type of variable except a conventional string.
  224.     
  225.         EleLen% - Integer describing the length of the elements stored in
  226.               in the XMS block. This value must be an even number. Thus,
  227.               integers would be 2, long integers are 4, etc. You may
  228.               specify any length, but it is assumed all elements stored
  229.               in the block are the same length.
  230.     
  231.         EleNum% - the element number to retrieve. This value is used
  232.               with EleLen% to determine the offset into the XMS block
  233.               to start reading. The first element is considered to be
  234.               element number one, not zero.
  235.     
  236.           Variable types supported are integers, long integers, single and
  237.     double precision numbers, and user type variables AS LONG AS THE LENGTH
  238.     OF THE VARIABLE IS EVEN. This variable cannot be a conventional string.
  239.     If the variable length is odd it will be forced even without error.
  240.     ---------------------------------------------------------------------
  241.     XSETELEMENT: Basic sub
  242.     
  243.          This is the compliment procedure for GETELEMENT. The syntax is
  244.     identical to XGETELEMENT, except that Variable holds the value to
  245.     place into XMS. All restrictions and notes for XGETELEMENT apply to
  246.     this procedure.
  247.     ---------------------------------------------------------------------
  248.     XMS2XMS: Basic Sub
  249.     
  250.          This sub will copy any continuous portion from one block of XMS
  251.          to another block of XMS. The move is performed entirely within
  252.          XMS - no conventional memory is required.
  253.     
  254.          CALL XMS2XMS(SHand%, SOffset&, DHand%, DOffset&, NumBytes&)
  255.     
  256.     Where:
  257.          SHand% - the handle of the source XMS block as returned by
  258.                   GetXMS.
  259.     
  260.          SOffset& - the 32 bit offset into the source block to start
  261.                   reading. If a constant is used it should be appended
  262.                   by the "&" specifier, forcing a long reference.
  263.     
  264.          DHand% - the handle of the destination block of XMS as returned
  265.                   by GetXMS. This can be the same handle as the source
  266.                   handle (see note below).
  267.     
  268.          DOffset& - the 32 bit offset into the destination block to place
  269.                   the copy. If a constant is used it should be appended by
  270.                   the "&" specifier, forcing a long reference.
  271.     
  272.          NumBytes& - the number of bytes to copy. This must be an even
  273.                   number. Odd numbers are forced even without indication.
  274.                   If a constant is used it should be appended by the "&"
  275.                   specifier, forcing a long reference.
  276.     
  277.          Block copies can be performed within the same block as long as
  278.     any overlap is in the forward direction (i.e. the source offset is
  279.     less than the destination offset).
  280.     ---------------------------------------------------------------------
  281.     WHICHXERROR: Basic function
  282.     
  283.          This function returns the actual error code as supplied by
  284.     HIMEM.SYS (see notes on XMSError). Where XMSError provides an easy
  285.     check for errors, this procedure gives you the actual error code.
  286.     Because it is a function, it must be declared before it may be used.
  287.     
  288.          DECLARE FUNCTION WhichXError%()
  289.     
  290.          Code% = WhichXError%
  291.     
  292.          Code% receives the actual error code generated by HIMEM.SYS. If
  293.     XMS memory is unavailable for any reason, this function will always
  294.     return error 128 - "Function not supported".
  295.     ---------------------------------------------------------------------
  296.     SETXERROR: Basic sub
  297.     
  298.          This sub will set the error value returned by WhichXError.
  299.     
  300.          CALL SetXError(ErrorCode%)
  301.     
  302.          where ErrorCode% is the value to set.
  303.     
  304.          This sub is handy for many purposes, among those being
  305.     communications between modules and procedures. For example, if you
  306.     decide to use XMS memory as an array (using the XGET and XSETELEMENT
  307.     procedures), you can set an illegal element code if user input is out
  308.     of bounds.
  309.     
  310.          The value you specify should be in the range of 0 - 255. If the
  311.     value is greater than 255, only the low byte of the value passed will
  312.     be used.
  313.     
  314.          Please note this sub will not work if XMS is not available. This
  315.     is to avoid confusion on the part of WhichXError. WhichXError will
  316.     always return a "Function not supported" error if XMS is not present.
  317.     ---------------------------------------------------------------------
  318.                             ERROR CODES RETURNED
  319.     
  320.          The error codes returned by this driver are the actual HIMEM.SYS
  321.     error codes, so not all will apply to this package. In the spirit of
  322.     completeness I shall include all codes I have documentation on. The
  323.     driver takes no action upon errors beyond reporting their occurrence.
  324.     This is left up for you to handle.
  325.     
  326.     128  Function not supported
  327.     129  VDisk was detected
  328.     130  An A20 error occurred
  329.     142  General driver error (HIMEM.SYS)
  330.     143  Fatal driver error (HIMEM.SYS)
  331.     144  HMA does not exist
  332.     145  HMA is already in use
  333.     147  HMA is not allocated
  334.     148  A20 still enabled
  335.     160  Not enough memory
  336.     161  All handles are allocated
  337.     162  Invalid handle
  338.     163  Source handle invalid
  339.     164  Source offset is invalid
  340.     165  Destination handle is invalid
  341.     166  Destination offset is invalid
  342.     167  Invalid length parameter
  343.     168  Move has invalid overlap
  344.     169  Parity error occurred
  345.     170  Block is not locked
  346.     171  Block is locked
  347.     172  Block lock count overflow
  348.     173  Lock failed
  349.     176  Only a smaller UMB is available
  350.     177  No UMB's are available
  351.     178  UMB segment is invalid
  352.     
  353.                        ** End of documentation **
  354.