home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / memory / emil / userman.doc < prev   
Encoding:
Text File  |  1991-05-07  |  5.7 KB  |  159 lines
  1.  
  2.  
  3.  
  4.  
  5.      Nicholas Wilt
  6.      Thermopress Marketing, Inc.
  7.      24 Harrison Circle
  8.      Pittsford, NY    14534-4109
  9.  
  10.      User's Manual for the Extended Memory Interface Library
  11.  
  12.      The Extended Memory Interface Library gives C programmers of
  13.      MS-DOS applications access to extended memory by interfacing
  14.      with the HIMEM.SYS extended memory manager.  It will let your
  15.      programs access extended memory on any machine with HIMEM.SYS
  16.      installed, including the millions of computers running
  17.      Windows 3.0.
  18.  
  19.      There are several advantages to using the Interface Library.
  20.      First and foremost, it makes extended memory available to the
  21.      DOS programmer.  Second, the access is "polite": a DOS
  22.      application can access extended memory even when running in a
  23.      DOS shell under Windows.  Finally, the disparate memory
  24.      management capabilities of the 286 and 386 are transparently
  25.      supported by HIMEM.SYS, so programmers using the Interface
  26.      Library need not worry about CPU autodetection or protected
  27.      mode issues.
  28.  
  29.      The freely distributable portion of the library consists of
  30.      the following files:
  31.  
  32.      File        Description
  33.      userman.doc    This documentation file
  34.      order.doc    Order form for the source code and technical
  35.             manual
  36.      hi.h        C header file for the library
  37.      hi.hpp     Turbo C++ header file for the library
  38.      hi.obj     FAR code object module for the library
  39.      makefile    Makefile to build testhi.exe
  40.      testhi.prj    Turbo C++ .PRJ file to build testhi.exe
  41.      testhi.c    C source file to demonstrate how to use the
  42.             library
  43.      testhi.exe    Compiled and linked executable for testhi.c
  44.  
  45.      The Library consists of a header file and an object module.
  46.      The object is FAR-callable, so the functions have all been
  47.      declared "far" in the header file.  The object has been
  48.      tested for use with Microsoft C and Turbo C and C++.  To use
  49.      it, you must link against hi.obj.  This may be accomplished
  50.      by adding "hi.obj" to the Project in the Turbo C++ IDE, or
  51.      adding "hi.obj" to the linker command line.  TESTHI.PRJ and
  52.      MAKEFILE illustrate each technique.
  53.  
  54.      The hi.hpp header file has been included for C++ users.  It
  55.      declares the functions with a "C" qualifier so the C++
  56.      compiler knows not to mangle the function names.  If you are
  57.      using C++, you should include hi.hpp rather than hi.h.
  58.  
  59.      If you use the Extended Memory Interface Library, I request
  60.      that you register your copy.  In exchange, I will send you
  61.      the assembler source code and a technical manual (on
  62.      electronic media) describing how it works.  See the order
  63.      form for details.
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      Using The Library
  71.  
  72.      Extended memory locations are specified as handle/offset
  73.      pairs.  The handle is a return value from himalloc(); it is a
  74.      protected mode segment descriptor, and specifies a block of
  75.      extended memory.  Certain functions which operate on blocks,
  76.      such as hifree(), hilock(), and hiunlock(), take only the
  77.      handle.  The offset is used to pinpoint a location in
  78.      extended memory; it is passed to hi2real() and real2hi().
  79.  
  80.      The function interface to the library is described below.
  81.      The source files (testhi.c and hi.h) provide a lot of
  82.      guidance as well.
  83.  
  84.      int pinghi();
  85.         This function returns nonzero if HIMEM is installed.
  86.  
  87.      void hiinit();
  88.         This function must be called once before any other
  89.          function in the library (except pinghi()).
  90.  
  91.      unsigned long hicontig();
  92.         Returns the size of the largest contiguous chunk of
  93.          memory.
  94.  
  95.      unsigned long himemavl();
  96.         Returns the total amount of extended memory available.
  97.  
  98.      unsigned himalloc(unsigned long size);
  99.         This function allocates extended memory and returns a
  100.          handle (actually a protected-mode segment descriptor) to
  101.          it.  Returns 0 if the memory cannot be allocated.
  102.  
  103.      void hifree(unsigned handle);
  104.         This function frees memory allocated by himalloc().
  105.  
  106.      hilock(unsigned handle);
  107.      hiunlock(unsigned handle);
  108.         These functions lock (write-protect) and unlock the
  109.          memory pointed to by the given handle.
  110.  
  111.      hi2real(void far *dest,
  112.          unsigned src,
  113.          unsigned long offset,
  114.          unsigned count);
  115.      real2hi(unsigned dest,
  116.          unsigned long offset,
  117.          void far *src,
  118.          unsigned count);
  119.  
  120.         These functions copy to/from extended memory.  real2hi
  121.      copies from the DOS memory location specified by src to an
  122.      extended memory location specified by the dest/offset pair.
  123.      hi2real copies from an extended memory location specified by
  124.      the src/offset pair to the DOS memory location specified by
  125.      dest.
  126.  
  127.      Return value: 1 if successful, 0 if not successful.
  128.  
  129.      IMPORTANT: THE BYTE COUNT MUST BE EVEN.
  130.  
  131.  
  132.  
  133.      Caveats
  134.  
  135.      - If your program crashes on the first call into the library,
  136.        you probably neglected to call hiinit().  You don't do any
  137.        harm calling hiinit() even if HIMEM is not present, so
  138.        unconditionally executing it first is the way to go.
  139.      - Avoid allocating small objects.  There are two reasons for
  140.        this:
  141.         - HIMEM allocates memory in increments of 1K.
  142.         - Intel processors have a limited number of segments
  143.           available (several thousand), so it is wise to
  144.           allocate large chunks and dice them up using the
  145.           offsets.
  146.      - Check return values.  real2hi(), in particular, can catch
  147.        protected-mode violations such as trying to write beyond a
  148.        handle's allocated space.
  149.      - Since DOS knows nothing about extended memory, it can't
  150.        know to free allocated chunks of extended memory when your
  151.        application exits.  You are responsible for hifree()'ing
  152.        all the extended memory you allocate.
  153.  
  154.      -------------------------------------------------------------
  155.  
  156.      Comments and suggestions are always welcome.  I may be
  157.      reached at the above address, or at my Internet address
  158.      (npw@eleazar.dartmouth.edu).
  159.