



	XMSBCP
	XMS Interface for Borland C/C++ and Borland Pascal
	Version 1.1

	Developed by Tanescu A. Horatiu
	April 1997


	Short description of constants/types/variables/functions



	Constants


XMS ERROR CODES:

 XE_NOERROR		0x00  no error, successful operation

 XE_NOTIMPLEMENTED	0x80  the function is not implemented
 XE_VDISK		0x81  a VDISK device is detected
 XE_A20			0x82  an A20 error occurs
 XE_DRVFAULT		0x8E  a general driver error occurs
 XE_UNRECOVERABLE	0x8F  an unrecoverable driver error occurs

 XE_NO_HMA		0x90  the HMA does not exist
 XE_NO_FREEHMA		0x91  the HMA is already in use
 XE_BAD_HMAMINSIZE	0x92  DX is less than the /HMAMIN= parameter
 XE_HMANOTALLOCATED	0x93  the HMA is not allocated
 XE_A20ENABLED		0x94  the A20 line is still enabled

 XE_NO_FREEMEM		0xA0  all extended memory is allocated
 XE_NO_FREEHANDLES	0xA1  all available extended memory handles are in use
 XE_BAD_HANDLE 		0xA2  the handle is invalid
 XE_BAD_SRC_HANDLE	0xA3  the SourceHandle is invalid
 XE_BAD_SRC_OFF		0xA4  the SourceOffset is invalid
 XE_BAD_DEST_HANDLE	0xA5  the DestHandle is invalid
 XE_BAD_DEST_OFF	0xA6  the DestOffset is invalid
 XE_BAD_LEN		0xA7  the Length is invalid
 XE_BAD_OVERLAP		0xA8  the move has an invalid overlap
 XE_PARITY		0xA9  a parity error occurs
 XE_UNLOCKED		0xAA  the block is not locked
 XE_LOCKED		0xAB  the block is locked
 XE_LOCKCOUNTOF		0xAC  the block's lock count overflows
 XE_LOCKFAIL		0xAD  the lock fails

 XE_UMB2BIG		0xB0  a smaller UMB is available
 XE_NO_UMBS		0xB1  no UMBs are available
 XE_BAD_UMBSEG		0xB2  the UMB segment number is invalid


Miscellaneous constants

 HMASEG			0xFFFF High Memory Area (HMA) Segment
 HMASTARTOFF		0x0010 HMA Starting Offset
 HMAENDOFF		0xFFFF HMA Ending Offset



	Types


- 16-bit handle to an extended memory block.

  C:
  typedef unsigned int xmhandle;

  PASCAL:
  type
    XMHandle = Word;

  This type is used by extended memory blocks (EMBs) handling functions.


- Structure (record) used by the generic memory transfer routine
  (xmemcpy/XMemCopy).

  C:
  typedef struct {
    unsigned long xmc_count;
    xmhandle      xmc_srchandle;
    unsigned long xmc_srcoff;
    xmhandle      xmc_desthandle;
    unsigned long xmc_destoff;
  } xmemcpy_t;

  PASCAL:
  type
    TXMCopyRec = record
      Count        : Longint;
      SourceHandle : XMHandle;
      SourceOff    : Longint;
      DestHandle   : XMHandle;
      DestOff      : Longint;
    end;



	Variables


- Error status variable

  C:
  unsigned char xmserrno;

  PASCAL:
  var
    XMSError : Byte;

  All the functions from this library (except the initialization functions)
  change this variable to reflect the status of the last XMS operation.
  See also the XMS Error Codes Constants.


- Indicator of the existence of an XMS driver

  C:
  unsigned char xmsinstalled;

  PASCAL:
  var
    XMSInstalled : Boolean;

  Set to 1 (TRUE) by the initialization function if an XMS driver is
  found, otherwise set to 0 (FALSE).



	Initialization Functions


C:	int _xmsdrivercheck(void);
PASCAL: function XMSDriverCheck : Boolean;

	Determines if an XMS driver is installed.

C:	void _getxmsfunct(void);
PASCAL: procedure GetXMSFunct;

	Returns the address of the XMS driver's control function.

C:	int initxms(void);
PASCAL: procedure InitXMS;

	Inits the XMS library.
	MUST BE CALLED BEFORE ANY OTHER ROUTINE!

> For C users:
	If an XMS driver is found, xmsinstalled is set to 1, otherwise is
	set to 0.
	Initxms is automatically called when you include xms.h (a #pragma
	startup initxms directive is placed in xms.h).

> For Pascal users:
	If an XMS driver is found, XMSInstalled is set to True, otherwise is
	set to False.
	InitXMS is automatically called when you use xms.tpu (XMSInit is
	called in the initialization part of the xms unit).


	Driver Information Functions


C:	unsigned int xmsver(void);
PASCAL:	function XMSVersion : Word;

	Returns the XMS driver version number. If the result is 300 then
	the version is 3.00.

C:	unsigned int xmsverinfo(unsigned int* revision, int* HMA);
PASCAL:	function XMSVersionInfo(var Revision : Word; var HMA : Boolean) : Word;

	Returns the XMS driver version number and internal revision number
	and query the existence of HMA.



NOTE:	the following routines return an error code in xmserrno (C) or in
	XMSError (PASCAL). If the significance of the return value is not
	specified in the description of the routine it is assumed that it
        returns a non-zero value (in C) / True (in Pascal) on success and
        a zero value (in C) / False (in Pascal) on error.



	High Memory Area (HMA) Management Functions


C:	int hmarequest(unsigned int reqsize);
PASCAL:	function HMARequest(ReqSize : Word) : Boolean;

	Attempts to reserve the high memory area to the caller. Reqsize
	contains the bytes which are needed (up to 65520 bytes). If an
	application fails to release the HMA before it terminates, the HMA
	becomes unavailable to the other programs until the system is
	restarted.

C:	int hmarelease(void);
PASCAL:	function HMARelease : Boolean;

	Releases the high memory area and allows other programs to use it.


	A20 Management Functions


C:	int globalenableA20(void);
PASCAL:	function GlobalEnableA20 : Boolean;

C:	int globaldisableA20(void);
PASCAL:	function GlobalDisableA20 : Boolean;

C:	int localenableA20(void);
PASCAL:	function LocalEnableA20 : Boolean;

C:	int localdisableA20(void);
PASCAL:	function LocalDisableA20 : Boolean;

C:	int queryA20(void);
PASCAL:	function QueryA20 : Boolean;

        Refer to the XMS specification for information.


	eXtended Memory Management Functions


C:	unsigned int xmfreespace(void);
PASCAL:	function XMFreeSpace : Word;

	Returns the amount of free extended memory in K-bytes.

C:	unsigned int xmcontig(void);
PASCAL:	function XMContig : Word;

	Returns the size of the largest free extended memory block in
	K-bytes.

C:	xmhandle xmalloc(unsigned int size);
PASCAL:	function XMAlloc(Size : Word) : XMHandle;

	Allocates an extended memory block and returns a handler which is
	used by the other extended memory routines to refer to this block.
        If the allocation fails, the returned handle is null. Size is in
	K-bytes.

C:	int xmfree(xmhandle hxmem);
PASCAL:	function XMFree(Handle : XMHandle) : Boolean;

	Frees an extended memory block previously allocated using xmalloc.
	If a program fails to release the allocated extended memory before
	it terminates, the memory becomes unavailable to other programs until
	the system is restarted. Locked blocks can't be freed.

C:	unsigned long xmlock(xmhandle hxmem);
PASCAL:	function XMLock(Handle : XMHandle) : Longint;

	Locks an extended memory block and returns its base address as a
	32-bit linear address. Locked memory blocks are guaranteed not to
	move.

C:	int xmunlock(xmhandle hxmem);
PASCAL:	function XMUnlock(Handle : XMHandle) : Boolean;

	Unlocks a locked extended memory block. Any 32-bit pointers to the
	block become invalid and should not be used.

C:	int xmhandleinfo(xmhandle hxmem, unsigned int* size, unsigned char* lockcount, unsigned char* freehandles);
PASCAL:	function XMHandleInfo(Handle : XMHandle; var Size : Word; var LockCount, FreeHandles : Byte) : Boolean;

	Returns additional information about an extended memory block: the
        size in K-bytes and the number of locks. Freehandles is the number
	of free handlers which are available.

C:	int xmrealloc(xmhandle hxmem, unsigned int newsize);
PASCAL:	function XMRealloc(Handle : XMHandle; NewSize : Word) : Boolean;

	Reallocates a previously allocated extended memory block. Locked
	blocks can't be resized. Size is in K-bytes.


	eXtended Memory Transfer Functions


VERY IMPORTANT NOTE:	For each of the following transfer functions the size
			(in bytes) of the transferred block must be EVEN!

C:	int xmemcpy(xmemcpy_t *x);
PASCAL: function XMemCopy(const CopyRec : TXMCopyRec) : Boolean;

	Transfers an extended memory block (generic function).

C:	int _xmemcpy(unsigned long n, xmhandle srchandle, unsigned long srcoff, xmhandle desthandle, unsigned long destoff);
PASCAL:	function _XMemCopy(N : Longint; SrcHandle : XMHandle; SrcOff : Longint; DestHandle : XMHandle; DestOff : Longint) : Boolean;

	Transfers an extended memory block (generic function). In C/C++ it is
        used by the following 4 functions. In Pascal is provided for
        compatibility with the C/C++ version.

C:	int ctoxm(xmhandle desthandle, unsigned long destoff, void far *src, unsigned long n);
PASCAL:	function CopyCMemToXMem(DestHandle : XMHandle; DestOff : Longint; Src : Pointer; N : Longint) : Boolean;

	Transfers a block from conventional to extended memory. The size (in
	bytes) of the transferred block (n) must be even.

C:	int xmtoc(void far *dest, xmhandle srchandle, unsigned long srcoff, unsigned long n);
PASCAL:	function CopyXMemToCMem(Dest : Pointer; SrcHandle : XMHandle; SrcOff : Longint; N : Longint) : Boolean;

	Transfers a block from extended to conventional memory. The size (in
	bytes) of the transferred block (n) must be even.

C:	int xmtoxm(xmhandle desthandle, unsigned long destoff, xmhandle srchandle, unsigned long srcoff, unsigned long n);
PASCAL:	function CopyXMem(DestHandle : XMHandle; DestOff : Longint; SrcHandle : XMHandle; SrcOff : Longint; N : Longint) : Boolean;

	Transfers a block within extended memory. The size (in bytes) of the
	transferred block (n) must be even.

C:	int ctoc(void far *dest, void far *src, unsigned long n);
PASCAL:	function CopyMem(Dest : Pointer; Src : Pointer; N : Longint) : Boolean;

	Transfers a block within conventional memory. The size (in bytes) of
	the transferred block (n) must be even.


	Upper Memory Blocks (UMB) Management Functions


C:	unsigned int umballoc(unsigned int* size);
PASCAL:	function UMBAlloc(var Size : Word) : Word;

	Attempts to allocate an upper memory block of the specified size in
	paragraphs. On success the function returns the segment base of the
	allocated block and size contains the actual size of the allocated
	block in paragraphs. On error, the function returns 0 and the size
	of the largest free UMB is returned in size.

C:	int umbfree(unsigned int umbseg);
PASCAL:	function UMBFree(UMBSeg : Word) : Boolean;

	Frees a previously allocated upper memory block.

C:	int umbrealloc(unsigned int umbseg, unsigned int* size);
PASCAL:	function UMBReAlloc(UMBSeg : Word; var Size : Word) : Boolean;

	Reallocates an upper memory block to a newly specified size. Size
        is in paragraphs.


	XMS error functions


C:	char* xmserrormsg(int errorcode);
PASCAL:	function XMSErrorMsg(ErrorCode : Byte) : string;

	Returns the description of an XMS error message.

C:	void pxmserror(const char *s);
PASCAL:	procedure PrintXMSError(const S : string);

	Prints (in C on stderr) the description of the last XMS error that
	occured, followed by ":" and by the user string (S).
