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

.context XMSLIB
.context @L8060
:z3
\i\p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSLIB OverviewÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bQuick Reference Summary:\p

XMSHANDLE \iXMSalloc\p (WORD uBytes);
int \iXMSclose\p (void);
WORD \iXMSerrorCode\p (void);
int \iXMSfree\p (XMSHANDLE xhXM);
int \iXMSget\p (void * pDest, XMSHANDLE xhXM);
int \iXMSgetExt\p (void * pDest, XMSHANDLE xhXM, WORD uSrcOfs,
WORD uBytes);
WORD \iXMSgetLen\p (XMSHANDLE xhXM);
WORD \iXMSgetVersion\p (void);
int \iXMSinstalled\p (void);
int \iXMSopen\p (WORD uKbytes);
int \iXMSput\p (XMSHANDLE xhXM, const void * pSrc, WORD uBytes);

\bType and constant definitions:\p

\bXMSHANDLE\p Handle to an XMS memory buffer
\bXMSHNULL\p The `null' handle; an error condition


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());
}

.context XMSalloc
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSallocÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bXMSHANDLE XMSalloc (WORD uBytes);\p

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).

.context XMSclose
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMScloseÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bint XMSclose (void);\p

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.


.context XMSerrorCode
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSerrorCodeÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bWORD XMSerrorCode (void);\p

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.


.context XMSfree
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSfreeÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bint XMSfree (XMSHANDLE xhXM);\p

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.


.context XMSget
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSgetÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bint XMSget (void * pDest, XMSHANDLE xhXM);\p

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.


.context XMSgetExt
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSgetExtÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bint XMSgetExt (void * pDest, XMSHANDLE xhXM, WORD uSrcOfs,
WORD uBytes);\p

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.


.context XMSgetLen
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSgetLenÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bWORD XMSgetLen (XMSHANDLE xhXM);\p

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


.context XMSgetVersion
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSgetVersionÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


\bWORD XMSgetVersion (void);\p

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).


.context XMSinstalled
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSinstalledÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bint XMSinstalled (void);\p

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().


.context XMSopen
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSopenÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bint XMSopen (WORD uKbytes);\p

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.


.context XMSput
:z3
\i\p\aUp\v@L8060\v\i \p\aContents\vVTXLIB\v\i \p\aBack\v!B\v\i\p
ÄÄÄÄÄXMSputÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

\bint XMSput (XMSHANDLE xhXM, const void * pSrc, WORD uBytes);\p

Copies characters from buffer to the XMS buffer
addressed by the handle . The handle must have been reurned
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.