home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / FOXPRO / XMS / XMS.TXT
Text File  |  1993-01-29  |  8KB  |  241 lines
  1.     FORCE FAQ (Frequently Asked Questions)   (xms.faq 1.1)           1
  2.     ------------------------------------------------------------------
  3.  
  4.     Advanced Topic: Interfacing with an XMS driver
  5.  
  6.     Author: David Holmes
  7.  
  8.     Examples: Xstat.exe, Show.exe
  9.  
  10.     General discussion:
  11.     -----------------------------------------------------------------
  12.     Q:    How do I access XMS memory from a FORCE program?
  13.  
  14.     A:    Through the driver.  Unfortunately, the driver is meant
  15.     to be called by assembler functions, not by higher level
  16.     languages such as FORCE.  However, it's easy to get around that,
  17.     because FORCE takes to assembly language like a duck to water.
  18.  
  19.     Q:    I don't know assembler, so what can a guy do?
  20.  
  21.     A:    Well, you could learn it, but for most people, that's
  22.     just not a viable option, since it does take a while.  But, you
  23.     won't have to, because provided here in this special chapter of
  24.     the FAQ is a function called (very cleverly):
  25.  
  26.         call_driver()
  27.  
  28.     Call_driver() is an assembly language "wrapper" function, just
  29.     like the undocumented function Interrupt().  In order to use it,
  30.     you should know something about assembly language, mainly; what
  31.     registers are, and what they do.  If you don't, don't bother,
  32.     because I've also provided FORCE wrapper functions around the
  33.     Call_Driver() function, which allow you to access XMS memory in
  34.     a more readable, higher-level interface.  But, let's take a look
  35.     at the Call_Driver() function just for reference.  It's prototype
  36.     looks like this:
  37.  
  38.     FUNCTION LOGICAL call_driver PROTOTYPE
  39.        PARAMETERS VALUE LONG drv_address,;
  40.         UINT ax,         UINT bx,;
  41.         UINT cx,         UINT dx,;
  42.         UINT si,         UINT di,;
  43.         UINT bp,         UINT ds,;
  44.         UINT es
  45.  
  46.     If you know assembler, you'll see that all the 8086 registers
  47.     (with the exceptions SS, SP, CS, and IP) are passed in as
  48.     parameters.  Of course, they're not really the registers, but
  49.     their values are loaded into the corresponding registers before
  50.     the driver is called.  If you load up the registers like so:
  51.  
  52.         VARDEF
  53.             UINT    ax,bx,cx,dx,si,di,bp,ds,es
  54.         ENDDEF
  55.  
  56.         ax = 0x0800    && Service for querying available XMS
  57.  
  58.  
  59.     --------------------------------------------------------------------
  60.                                                                        1
  61.     FORCE FAQ (Frequently Asked Questions)                             2
  62.     --------------------------------------------------------------------
  63.     You can call the driver with the register AX being 0x0800.
  64.  
  65.         call_driver( xms_get_driver(), ax, bx, cx, dx, si, di,;
  66.                  bp, ds, es )
  67.  
  68.     The specifications for the XMS driver are such that for this
  69.     function, "return available extended memory in Kilobytes," the
  70.     available XMS will come back in DX.
  71.  
  72.     So, after the call to Call_driver(), you can look at your DX
  73.     variable to see how much XMS memory there is.
  74.  
  75.     Simple as that.  You'll find that the call_driver() function
  76.     mimics the Interrupt() function finally documented in UNDOC.FAQ.
  77.  
  78.     ------------------------------------------------------------------
  79.     Q:    Hm.  Still looks suspiciouly like assembler to me.  What
  80.     do you have the I can USE?
  81.  
  82.     A:    As promised, I've provided several wrapper functions
  83.     that hide the Call_driver() function from you, so that you
  84.     don't have to worry about it if you don't want to.  Let me
  85.     introduce them.
  86.  
  87.     FUNCTION LOGICAL    xms_installed
  88.     FUNCTION LONG        xms_get_driver
  89.     FUNCTION UINT        xms_get_version
  90.     FUNCTION INT        xms_avail
  91.     FUNCTION LOGICAL    xms_alloc
  92.     PROCEDURE        xms_free
  93.     FUNCTION LOGICAL    xms_copy
  94.     FUNCTION LONG        xms_lock
  95.     FUNCTION INT        xms_unlock
  96.  
  97.     * Plus two wrapper functions around xms_copy()
  98.  
  99.     FUNCTION LOGICAL    xms_insert
  100.     FUNCTION LOGICAL    xms_retrieve
  101.  
  102.     To use these functions, you'll need a little background on the
  103.     Extended Memory Specification.  First, the basics:
  104.  
  105.     XMS is the memory area defined as "anything above 1M," and blocks
  106.     of memory that reside in the XMS are referred to as Extended
  107.     Memory Blocks (EMB's).  Memory that resides between DOS 640K and
  108.     the 1M mark are called Upper Memory Blocks (UMB's), and may or
  109.     may not be supported by the XMS driver (Himem.sys does NOT support
  110.     them).
  111.  
  112.     Because EMB's are above the 1M mark, you cannot access them as
  113.     you would with normal memory.  This is because DOS pointers are
  114.     20 bits in length, giving you an address space of 1,048,576 bytes,
  115.     or roughly 1 Megabyte.  This is why the driver gives you a
  116.     ``handle'' instead of a pointer when you allocate an EMB.  With
  117.     this handle, you can ask the driver to copy memory below the
  118.     640K mark into the EMB, and vice versa.
  119.     --------------------------------------------------------------------
  120.                                                                        2
  121.     FORCE FAQ (Frequently Asked Questions)                             3
  122.     --------------------------------------------------------------------
  123.  
  124.     So, that's what all this is about, now let's see how you can do
  125.     it with the functions provided with this chapter.
  126.  
  127.     There are four functions that you'll use heavily when working with
  128.     XMS in FORCE.  They are xms_alloc(), xms_free(), xms_insert(),
  129.     and xms_retrieve().  The last two are just wrappers around the
  130.     xms_copy() function, and the first two you'll need to get and
  131.     free the XMS memory.  The rest of the functions are used internally
  132.     by these four functions.  For example, you don't need to worry
  133.     about the xms_get_driver() function, since it just returns the
  134.     address of the driver, and that's taken care of by all of the
  135.     functions in the XMS library.
  136.  
  137.     Let's suppose you wanted a slick way to save entire screens to
  138.     some convenient place, and bring them back at will.  You could
  139.     do something like this:
  140.  
  141.         VARDEF
  142.             INT        temp_handle
  143.             LONG        video_mem = 0xb8000000
  144.         ENDDEF
  145.  
  146.         PROCEDURE screen_to_xms
  147.  
  148.            xms_alloc( temp_handle, 4 )    && screens are 4K
  149.            xms_copy( &NULL, video_mem, temp_handle, 0, 4000 )
  150.  
  151.         ENDPRO
  152.  
  153.     Then, when you want your screen back:
  154.  
  155.         PROCEDURE xms_to_screen
  156.  
  157.            xms_copy( temp_handle, 0, &NULL, video_mem, 4000 )
  158.            xms_free( temp_handle )
  159.  
  160.         ENDPRO
  161.  
  162.     Or, suppose that you wanted a way to read a "screen" from disk,
  163.     copy it into XMS, and then call it up whenever you want.  You
  164.     could do something like this:
  165.  
  166.         VARDEF
  167.             BYTE        one_screen[4000]
  168.             INT        help_handle
  169.         ENDDEF
  170.  
  171.         PROCEDURE read_help_screen
  172.            PARAMETERS CONST CHAR filename
  173.  
  174.            VARDEF
  175.             UINT        file_handle
  176.            ENDDEF
  177.  
  178.  
  179.     --------------------------------------------------------------------
  180.                                                                        3
  181.     FORCE FAQ (Frequently Asked Questions)                             4
  182.     --------------------------------------------------------------------
  183.  
  184.            fb_open( file_handle, filename, &B_READ )
  185.            fb_read( file_handle, one_screen, 4000 )
  186.            fb_close( file_handle )
  187.  
  188.            xms_alloc( help_handle, 4 )
  189.            xms_insert( one_screen, help_handle, 0, 4000 )
  190.  
  191.         ENDPRO
  192.  
  193.     In fact, there's a sample program that shows you exactly how
  194.     you might want to implement this in the SAMPLE directory.
  195.  
  196.     Well, that's all for now.  I am of course, always available
  197.     on the BBS and CIS, so if you have any questions or comments,
  198.     feel free to contact me.
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.     --------------------------------------------------------------------
  240.                                                                        4
  241.