Sign bit of DX set if unsuccessful.  Error code returned in AX (always DOS
  error code).
  Details:
     This routine will return DX:AX = 0 if XLIB contains free internal memory in
  sufficient quantity to meet conventional memory demands.
     If both DPMI and VCPI are present, then XLIBMEMREQ will assume that DPMI
  will be used if bit 0 of IFLAGS is clear (the default); otherwise, VCPI is
  assumed.  No additional conventional memory is needed if both DPMI and VCPI
  are absent.

  DPMIMEMREQ  (DPMI Memory Requirements)
  Purpose:  Find DPMI conventional memory requirements.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:  DX:AX = conventional memory requirements adjusted upward to
  integer multiple of 16.
  Details:
     This routine will return DX:AX = 0 if XLIB contains free internal memory in
  sufficient quantity to meet the conventional memory demands of DPMI.
     This routine does not assume the presence of DPMI.  It will return DX:AX =
  0 if DPMI is absent.

  VCPIMEMREQ (VCPI Memory Requirements)
  Purpose:  Find VCPI conventional memory requirements.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:  DX:AX = conventional memory requirements adjusted upward to
  integer multiple of 16.
  Details:  This routine simply loads DX:AX with a constant.







                                        19






  INITXLIB (Initialize XLIB)
  Purpose:  Check for presence of XMS, DPMI, and VCPI.  Configure XLIB
  accordingly.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:
     AX = 0 if successful, in which event DX and EAX are zero as well.
     AX <> 0 if unsuccessful.  XLIB error code returned in AX.  Specific error
  code returned in DX and in high word of EAX (EAH).  If AX = operating
  environment identification error or DOS memory allocation error, then DX and
  EAH = DOS error code.  If AX = DPMI error, then DX and EAH = DPMI 1.0 error
  code (if provided by host).  If AX = VCPI error, then DX and EAH are returned
  as zero.
  Details:
     If both DPMI and VCPI are present, then XLIB will be configured for DPMI if
  the zero bit of IFLAGS is clear.  If this bit is set, then XLIB will be
  configured for VCPI.  The bit is clear by default.
     This routine will likely attempt to allocate DOS memory; consequently, some
  DOS memory must be free.  The amount of DOS memory XLIB will attempt to
  allocate can be obtained by calling XLIBMEMREQ, VCPIMEMREQ, or DPMIMEMREQ.
     This routine should be called only once within a program.  Subsequent calls
  are returned with no action.  XLIB is terminated by INT 21 function 4C (DOS
  termination) issued from real mode.

  XLIBCONFIG (XLIB Configuration)
  Purpose:  Get XLIB configuration.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:
     AX = 0 if protected-mode structures not initialized.
     AX = XLIB configuration if protected-mode structures initialized.  Value of
  lower nibble identifies protected-mode host/server.  If 1 then DPMI.  If 2
  then VCPI.  If 3 then XLIB.  Bit 4 is set if XMS is initialized.
























                                        20






  Mode Switch Routines


       Mode switch routines require initialization of XLIB by INITXLIB.


  CALLPM (Call Protected Mode)
  Purpose:  Call protected-mode procedure in TSEG with near return.
  Mode:  Real
  Registers at Call:  SS:ESP = far real-mode return address (four bytes), near
  protected-mode target offset (four bytes).
  Return Registers:  Returns through RETPM.  See RETPM for details.
  Details:
     All CPU registers except EAX and EDX are saved.  The calling SS:ESP is
  saved at ORGSS:ORGESP after the return address and argument have been popped.
  XLIB interrupt handlers are enabled.  Entry point receives SS = TSEGDSEL with
  1000H free bytes on the stack.  The return address on the stack is a near
  return to RETPM.  Entry point receives segments DS = FLATDSEL, ES = TSEGDSEL,
  FS = DSEGSEL, and GS = DGROUPSEL.
     If bit 2 of OFLAGS is set, then the FPU state is also saved; the FPU is
  initialized, and FPUCW is loaded to the control word.
     If bit 1 of OFLAGS is set, then the XLIB interrupt handler for the FPU will
  not be enabled.

  RETPM (Return From Protected Mode)
  Purpose:  Return control to real mode with partial register restoration.
  CPU Mode:  Protected
  Registers at Call:  None
  Return Registers:  No return
  Details:
     RETPM switches to real mode and then restores all segment registers and ESP
  to values as of call to either CALLPM or ENTERPM.  XLIB interrupt handlers are
  disabled.  Control is then transferred to the real-mode return address as of
  call to CALLPM/ENTERPM.
     If bit 2 of OFLAGS is set, then RETPM also restores FPU state.
     RETPM will successfully execute regardless of stack state.

  ENTERPM (Enter Protected Mode)
  Purpose:  Call protected mode procedure in TSEG with near return.
  Mode:  Real
  Registers at Call:  SS:ESP = far real-mode return address (four bytes), near
  protected mode target offset (four bytes).
  Return Registers:  Returns through EXITPM.  See EXITPM for details.
  Details:  This routine executes exactly as CALLPM except that a near return to
  EXITPM is placed on the stack rather than to RETPM.

  EXITPM (Exit Protected Mode)
  Purpose:  Return control to real mode with general register restoration.
  CPU Mode:  Protected
  Registers at Call:  None
  Return Registers:  No return
  Details:
     EXITPM switches to real mode and then restores all registers except EAX and
  EDX to values as of call to either CALLPM or ENTERPM.  The system and control



                                        21






  flags in EFLAGS are also restored.  XLIB interrupt handlers are disabled.
  Control is then transferred to the real-mode return address as of call to
  CALLPM/ENTERPM.
     If bit 2 of OFLAGS is set, then EXITPM also restores FPU registers.
     EXITPM will successfully execute regardless of stack state.
     The XLIB FPU interrupt handler performs a jump to EXITPM upon occurrence of
  any unmasked FPU exception.

  CALLRM (Call a Real-Mode Procedure)
  Purpose:  From protected mode, call a real-mode procedure with far return.
  CPU Mode:  Protected
  Registers at Call:  SS:ESP = near protected-mode return address (four bytes),
  far real-mode target address (four bytes).
  Return Registers:  All segment registers and ESP are restored.
  Details:
     The calling SS:ESP is saved at CALLSS:CALLESP after popping the return
  address and arguments.  The called routine receives the XLIB real-mode stack
  (SS = DSEG) with 200H free bytes.  Data segment settings are DS = DGROUP and
  ES = DSEG.
     Code called by this routine cannot perform XLIB shifts back to protected
  mode, including calls to XLIB memory management procedures or procedures
  managing interrupt vectors.



































                                        22






  Memory Management Routines


       Memory management routines require initialization of XLIB by INITXLIB.


  PMGETDOSMEM (Protected Mode - Get DOS Memory)
  Purpose:  Allocate DOS memory block.
  CPU Mode:  Protected
  Registers at Call:  EAX = desired size of block in bytes.
  Return Registers:
     EAX = 0 if successful.  Block handle returned in EBX.  Number of allocated
  bytes returned in ECX.  Linear address of allocated block returned in EDX.
     EAX = error code if unsuccessful.  AX = XLIB error code.  High word of EAX
  (EAH) will be set to DOS error code.  If DPMI is active, then EAH will be DPMI
  error code (codes supplied by DPMI .9 and up).
  Details:
     The returned block size will always be an integer multiple of 16.
     Call with EAX = 0 to get largest available DOS memory block (not total free
  memory) in ECX (EAX, EBX, and EDX are preserved).
     If DPMI is active, then the handle is actually a selector with base address
  set to the linear address of the block.  If DPMI is not active, then the
  handle will be the segment of the block.
     In real mode, DOS memory may be allocated directly from DOS (INT 21H
  function 48H); however, this call will likely fail under DPMI protected mode.

  PMFREEDOSMEM (Protected Mode - Free DOS Memory)
  Purpose:  Release previously allocated DOS memory block.
  CPU Mode:  Protected
  Registers at Call:  EAX = block handle.
  Return Registers:  EAX = 0 if successful; otherwise, EAX = error code.  AX =
  XLIB error.  High word of EAX (EAH) will be DOS error code.  If DPMI is
  active, then EAH will equal DPMI error code (codes supplied by DPMI .9 and
  up).
  Details:  In real mode, DOS memory may be released directly by DOS (INT 21H
  function 49H); however, this call will likely fail under DPMI protected mode.

  GETMEM (Get Memory)
  Purpose:  Allocate extended memory block.
  CPU Mode:  Real
  Registers at Call:  EAX = desired size of block in bytes.
  Return Registers:
     EAX = 0 if successful.  Block handle returned in EBX.  Number of allocated
  bytes returned in ECX.  Logical address of allocated block returned in EDX.
     EAX = error code if unsuccessful.  AX = XLIB error code.  If DPMI is
  active, then high word of EAX (EAH) will be DPMI 1.0 error code (if provided
  by host).  If XMS is active, then EAH = XMS error code.
  Details:
     The returned block size will always be an integer multiple of eight.  Under
  XMS the returned block size will be a 1K multiple.  Under VCPI and most DPMI
  hosts, block sizes will be 4K multiples.
     If XMS is present in conjunction with either DPMI or VCPI, no extended
  memory will be requested through XMS.  All extended memory will be requested
  through the active protected-mode interface.



                                        23






     XMS is never used to allocate from the HMA or from UMBs.  XLIB will however
  allocate from the HMA in the absence of a memory management interface.
     Call with EAX = 0 to get largest available extended memory block (not total
  free memory) in ECX (EBX and EDX preserved).  This call can also return with
  error condition in EAX.

  FREEMEM (Free Memory)
  Purpose:  Release previously allocated extended memory block.
  CPU Mode:  Real
  Registers at Call:  EAX = block handle.
  Return Registers:  EAX = 0 if successful; otherwise, EAX = error code.  AX =
  XLIB error code.  If DPMI is active, then the high word of EAX (EAH) will be
  DPMI 1.0 error code (if provided by host).  If XMS is active, then EAH = XMS
  error code.
  Details:  FREEMEM does not release page tables allocated under VCPI.  Call
  RESETMEM for this purpose.

  RESETMEM (Reset Memory)
  Purpose:  Release all previously allocated extended memory.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:  EAX = 0 if successful; otherwise, EAX = error code.  AX =
  XLIB error code.  If DPMI is active, then the high word of EAX (EAH) will be
  DPMI 1.0 error code (if provided by host).  If XMS is active, then EAH = XMS
  error code.
  Details:
     GETMEM will automatically allocate page tables as needed under VCPI.
  RESETMEM will release such tables.
     RESETMEM is always called upon execution of INT 21 function 4C (DOS
  termination)

  PMGETMEM  (Protected Mode - Get Memory)
  Purpose:  Allocate extended memory bloc