Category : C Source Code
Archive   : AXMSLIB.ZIP
Filename : XMSLIB.DOC

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³A(nother) C library for XMS memory ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³Version 1.0 February 1992 ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
Michael Wilson

CIS: 100014,2743
email: [email protected]

Voice: (+44) 279 429644 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 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 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 to a buffer
pointed to by . 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 to a buffer
pointed to by . The number of bytes copied is equal to .
Data will be copied from an offset of 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 , 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
kilobytes of XMS memory for the program's use (e.g. XMSopen(100) will
attempt to reserve 100K of XMS memory).

If 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 characters from buffer to the XMS buffer
addressed by the handle . 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.