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