This set of routines provides EMS support. That is, they provide C-level access to the services of an EMS driver. To use them, an EMS driver needs to be installed - this can be your plain vanilla EMM386 on the desktop, or the special EMM200 driver that provides EMS support using the HORNET hardware for the palmtop.
EMS can be very useful for PAL applications. Instead of using up the conventional memory, programs can benefit from this additional memory space for storing large amounts of data including graphical screen information.
Available functions:
EmsInit
: Initialize and check EMS for driver presence.
EmsCheck
: Check for the presence of an EMS driver.
EmsAlloc
: Allocate a specified number of EMS pages.
EmsMap
: Map a given logical page into the physical frame.
EmsFree
: Free an allocated EMS block.
EmsFrameSeg
: Return segment address of the EMS frame.
EmsFreeCnt
: Return the number of free EMS pages available.
EmsLastError
: Return last error reported by an EMS routine.
EmsPageCnt
: Return the total number of EMS pages available.
EmsVersion
: Return version of EMS driver.
EmsInit
Check for the presence of an EMS driver, initialize EMS
and return a far pointer to the EMS page. This is usually the
first function that should be called before using any other
EMS function. #include "pal.h"
void far *EmsInit(void);None.
Returns a far pointer to the EMS frame (and also stores it).
Returns NULL if initialization has failed, or EMS support
is not available. You can also use the EmsCheck() function to check
for the EMS driver presence.
/* Initialize & check EMS presence */
if(!EmsInit()) FatalExit("EMS support not available", 1);EmsCheck
Checks for the presence of an EMS driver. This function
or EmsInit() should be called first when using the EMS
functions. #include "pal.h"
int EmsCheck(void);None.
TRUE if the EMS driver is found, FALSE otherwise.
Usually EmsInit() is used instead of this function, since
it checks for EMS presence _and_ initializes at the same
time.
/* Check for EMS presence */
if(!EmsCheck()) FatalExit("EMS support not available", 1);EmsAlloc
Allocates n-pages from the Expanded Memory, and returns
a handle I.D. #include "pal.h"
int EmsAlloc(int Pages);
int Pages - Number of pages (16KB blocks) to allocate.
e.g.: 8 pages = 128k of memory. Returns a Handle number that can be used later to
free the allocated pages with EmsFree().
Returns EMS_ERR on error.
#include <stdio.h>
#include <stdlib.h>
#include <dos.h>
#include "pal.h"
void main(void)
{
int Handle;
int LogicalPage = 1;
int PhysicalPage = 0; /* 0-3 */
/* initialize PAL */
if(!PalInit(1)) FatalExit("Pal init fail", 1);
/* Initialize & check EMS presence */
if(!EmsInit()) FatalExit("EMS support not available", 1);
/* Allocate 4 pages of EMS */
if((Handle = EmsAlloc(4)) == EMS_ERR)
FatalExit("EMS Alloc fail",1);
/* save screen contents in EMS */
GetImg(0, 0, 639, 199, EmsMap(Handle, LogicalPage, PhysicalPage));
/* draw a black rectangle on the screen */
SetColor(BLACK_COLOR);
Rectangle(50,50,400,150, SOLID_FILL);
GetKey(); /* wait for a key */
/* restore screen contents from EMS memory */
PutImg(0, 0, FORCE_RULE, EmsMap(Handle, LogicalPage, PhysicalPage));
/* free allocated EMS storage */
EmsFree(Handle);
PalDeInit(1);
}
EmsMap
Maps a given logical page into a physical frame.
#include "pal.h"
void far *EmsMap(int Handle, int LogPage, int PhysPage);
handle - The handle ID returned by the EmsAlloc() function.
logPage - Logical page number.
PsysPage - Physical page number (0-3).
Returns a far pointer to the EMS frame.
See the EmsAlloc() function.
EmsFree
Frees a previously allocated EMS block, specified by
its HANDLE number. #include "pal.h"
int EmsFree(int Handle);
Handle - Handle I.D. previously returned by the EmsAlloc()
function.Returns TRUE on success, FALSE otherwise.
You can use EmsAlloc() to allocate EMS blocks.
See the EmsAlloc() function.
EmsFrameSeg
Returns the SEGMENT address of the EMS frame. The OFFSET
is not needed because it's always zero. (that's why the
address starts always at 16-byte boundaries). #include "pal.h"
WORD EmsFrameSeg(void);None.
Returns the SEGMENT address (SEG:0000) of the EMS frame.
See the EmsVersion() function.
EmsFreeCnt
Returns the number of free EMS pages available for
allocation. #include "pal.h"
int EmsFreeCnt(void);None.
Number of free EMS pages available. Each page is 16KB.
See the EmsVersion() function.
EmsLastError
Returns the last error reported by an EMS function, if any.
#include "pal.h"
int EmsLastError(void);None.
Last EMS-error number (EMS_ERR).
EmsPageCnt
Returns the total number of EMS pages available.
#include "pal.h"
int EmsPageCnt(void);None.
Number of EMS pages available.
See the EmsVersion() function.
EmsVersion
Returns the version number of the EMS driver.
#include "pal.h"
int EmsVersion(void);None.
Version number of the EMS driver.
e.g.: 320 is Version 3.20.
void EmsReport(void)
{
MsgBox(" EMS Status report ",
"|Version of EMS driver : %d|"
"Total pages available : %d|"
"Number of free pages : %d|"
"Frame segment location: %04X|",
NULL, " OK ",
EmsVersion(), EmsPageCnt(), EmsFreeCnt(), EmsFrameSeg());
}