CD Actual 13/CDA13.ISO/cdactual/demobin/share/program/C/AXMSLIB.ZIP/XMSLIB.DOC

Text File | 1992-02-28 | 9.8 KB | 279 lines

                  ┌───────────────────────────────────┐
                  │A(nother) C library for XMS memory │
                  ├───────────────────────────────────┤
                  │Version 1.0          February 1992 │
                  └───────────────────────────────────┘
Michael Wilson

        CIS:    100014,2743
        email:  [e-mail]

        Voice:  ([phone] ext 230 (daytime)

═════Introduction═══════════════════════════════════════════════════════════

I wrote this library when I needed a lot of data space for a program and
couldn't afford to buy a commercial virtual memory system. It provides a
reasonably familiar type of interface to memory allocation and freeing
functions, and hides most of the XMS details from the caller.

The library *requires* XMS memory, that is, extended memory (above the
1Mbyte mark) conforming to the XMS specification (v2.0 or later). This
type of memory can not be fitted in PC and XT (808x) machines. The
library does *not* work with expanded (EMS) memory.

It is assumed that you will have an XMS driver (usually, the HIMEM.SYS
that came with DOS 5 or WINDOWS 3.x) loaded, to provide the low level
XMS interface that the library uses.

This is version 1.0. As usual that means that it's probably not fully
debugged. I am also aware that the performance of the allocator is not
great; try to repetitively allocate and free one hundred thousand
100-byte blocks and you'll see what I mean (unless you have more than 10
Mbytes of XMS memory available...).

The system will perform more than adequately for large chunks of data,
or for small chunks that are only allocated once. Improvements will be
made in later versions, or you can roll your own (that's what source
code is for, after all).

A small demonstration program, which loads one or more text files into
extended memory and then lists it/them, is included, along with a
makefile to help you build it.

The code has been tested with Microsoft C v6.00A and Borland C++ v3.0 in
both small and large memory models.

The documentation below is also provided in Microsoft's QuickHelp
format, for use with the QH program supplied with MSC v6+.

Please pass comments and suggestions to me at either of the above
addresses.


═════XMSLIB Overview════════════════════════════════════════════════════════

Quick Reference Summary:

XMSHANDLE XMSalloc      (WORD uBytes);
int       XMSclose      (void);
WORD      XMSerrorCode  (void);
int       XMSfree       (XMSHANDLE xhXM);
int       XMSget        (void * pDest, XMSHANDLE xhXM);
int       XMSgetExt     (void * pDest, XMSHANDLE xhXM, WORD uSrcOfs,
                         WORD uBytes);
WORD      XMSgetLen     (XMSHANDLE xhXM);
WORD      XMSgetVersion (void);
int       XMSinstalled  (void);
int       XMSopen       (WORD uKbytes);
int       XMSput        (XMSHANDLE xhXM, const void * pSrc, WORD uBytes);

Type and constant definitions:

        XMSHANDLE   Handle to an XMS memory buffer
        XMSHNULL    The `null' handle; an error condition

Note:
        WORD        2-byte, unsigned quantity
        TRUE        Boolean value
        FALSE       Boolean value

are defined in a file called TYPES.H. You probably have you own
equivalents, so just replace the #include as necessary.

XMSLIB contains functions to allocate, free, read and write from
extended memory conforming to the XMS 2.0 (or later) specification.
A driver such as HIMEM.SYS must be loaded to make the memory available.

The XMS access must be performed as follows:

    if (XMSopen(x))
      {
      // XMS access permitted here...
      // .
      // .
      // .
      // End of XMS access

      if (!XMSclose())
        fprintf(stderr, "XMS error %x\n", XMSerrorCode());
      }


─────XMSalloc───────────────────────────────────────────────────────────────

XMSHANDLE XMSalloc (WORD uBytes);

Allocates a buffer of size <uBytes> characters in extended memory.

Returns a handle to the memory if successful, or XMSHNULL if not.

XMSopen() must be called before attempting to use this function. The
maximum size of the buffer is 65534 bytes (assuming that at least 64K
of XMS memory is available).


─────XMSclose───────────────────────────────────────────────────────────────

int       XMSclose (void);

Terminates access to XMS memory, returning all associated buffer space
(both in XMS and on the program's heap) to the system.

Returns TRUE if successful, else FALSE.

You must call this function before exiting the program. DOS does not
automatically release XMS memory claimed by a process, so a failure
to call XMSclose() will leave a reduced amount of XMS memory available
for other programs, or later execution of the same program, until the
system is reset.


─────XMSerrorCode───────────────────────────────────────────────────────────

WORD      XMSerrorCode (void);

Returns the XMS error code number pertaining to the most recent XMS
operation. If you need information on why an operation failed, call
this function immediately afterwards (and before calling any other
XMSLIB function).

Return codes are (refer to the XMS spec for full details):

   (0x80    Function not implemented)
    0x81    VDISK device detected
    0x82    A20 error
    0x8E    General driver error
    0x8F    Unrecoverable driver error
   (0x90    HMA does not exist)
   (0x91    HMA already in use)
   (0x92    DX less than /HMAMIN= parameter)
   (0x93    HMA is not allocated)
   (0x94    A20 line still enabled)
    0xA0    All extended memory is allocated
    0xA1    All available extended memory handles are in use
    0xA2    Handle is invalid
    0xA3    Source handle is invalid
    0xA4    Source offset is invalid
    0xA5    Destination handle is invalid
    0xA6    Destination offset is invalid
    0xA7    Length is invalid
   (0xA8    Move has invalid overlap)
    0xA9    Parity error
   (0xAA    Block is not locked)
   (0xAB    Block is locked)
   (0xAC    Block's lock count has overflowed)
   (0xAD    Lock failed)
   (0xB0    Smaller UMB is available)
   (0xB1    No UMBs are available)
   (0xB2    UMB segment number is invalid)

Because XMSLIB only uses a subset of the XMS API calls, several of
the error codes are most unlikely to occur. These are shown in
brackets. It would be unnecessary to, for example, store a descriptive
string for each of these in a program.


─────XMSfree────────────────────────────────────────────────────────────────

int       XMSfree (XMSHANDLE xhXM);

Frees the memory associated with handle <xhXM> for re-use. The handle
must have been returned previously be a call to XMSalloc(). Once the
memory has been freed, you can not rely on it to contain any data
previously copied in. Do not use a handle once it has been passed to
XMSfree().

Returns TRUE for success, FALSE for failure.



─────XMSget─────────────────────────────────────────────────────────────────

int       XMSget (void * pDest, XMSHANDLE xhXM);

Copies data from extended memory addressed by handle <xhXM> to a buffer
pointed to by <pDest>. The number of bytes copied is equal to the
argument passed to XMSalloc() to create the handle (i.e. the size of
the allocated buffer), or 1 BYTE MORE if the number of bytes was odd.

Returns TRUE if successful, FALSE on failure.



─────XMSgetExt──────────────────────────────────────────────────────────────

int       XMSgetExt (void * pDest, XMSHANDLE xhXM, WORD uSrcOfs,
                     WORD uBytes);

Copies data from extended memory addressed by handle <xhXM> to a buffer
pointed to by <pDest>. The number of bytes copied is equal to <uBytes>.
Data will be copied from an offset of <uSrcOfs> from the start of the
extended memory buffer addressed by the handle.

Returns TRUE if successful, FALSE on failure.



─────XMSgetLen──────────────────────────────────────────────────────────────

WORD      XMSgetLen (XMSHANDLE xhXM);

Returns the number of bytes of data which may be stored at the extended
memory buffer addressed by <xhXM>, or 0 on error.



─────XMSgetVersion──────────────────────────────────────────────────────────

WORD      XMSgetVersion (void);

Returns the version number of the XMS specification as a two byte BCD
number containing the major version number in the high byte and the
minor version number in the low byte (e.g. 0x0321 = version 3.21),
or 0 if XMS memory can not be accessed (call XMSopen() first).



─────XMSinstalled───────────────────────────────────────────────────────────

int       XMSinstalled (void);

Returns TRUE if XMS memory is installed in the system (and a suitable
driver is loaded), else FALSE.  Does not require a prior call to
XMSopen().



─────XMSopen────────────────────────────────────────────────────────────────

int       XMSopen (WORD uKbytes);

Initialises internal library data and attempts to reserve <uKbytes>
kilobytes of XMS memory for the program's use (e.g. XMSopen(100) will
attempt to reserve 100K of XMS memory).

If <uKbytes> is 0, XMSopen() will attempt to acquire ALL available
XMS memory for the program's use. (At least 64K of XMS memory must
be available for this feature to work).

Returns TRUE if successful, FALSE on error.

This function must be called before any functions which allocate, read
or write memory to or from XMS memory. It has a (small) overhead in
conventional memory of about 16 bytes per 64K of XMS used.



─────XMSput─────────────────────────────────────────────────────────────────

int       XMSput (XMSHANDLE xhXM, const void * pSrc, WORD uBytes);

Copies <uBytes> characters from buffer <pSrc> to the XMS buffer
addressed by the handle <xhXM>. The handle must have been returned
by an earlier call to XMSalloc(), and must not have subsequently been
released by a call to XMSfree().

Returns TRUE if successful, or FALSE if an error occurs.