purposes.



                                        8






       From protected mode, interrupt vectors can be managed with PMSETPMIV and
  PMGETPMIV.  These procedures have the same specifications as SETPMIV and
  GETPMIV.
       Interrupt handlers installed with SETPMIV/PMSETPMIV are never disabled by
  XLIB and will therefore always be active under protected-mode execution.
  These handlers will not be active under real-mode execution in tha absence of
  DPMI.  That is, real-mode interrupts are never deflected to protected mode in
  such environments.  However if DPMI is active, then all hardware interrupts
  (IRQs 0-15) and the software interrupts:  1CH (BIOS timer tick), 23H (DOS CTRL
  C), and 24H (DOS critical error) are deflected from real mode to the installed
  protected-mode handler.  If the user has not installed protected-mode handlers
  for these interrupts, then they are serviced by default handlers in the DPMI
  host.  The default handlers service the interrupts with the inherited real-
  mode handlers.
       Under DPMI, all hardware interrupts and software interrupts 0-7 will
  receive control with interrupts disabled.  Since DPMI virtualizes the
  interrupt flag, the IRET instruction may not reenable interrupts.
  Consequently, all handlers for these interrupts should execute STI before
  executing IRET.  This is not a concern if the interrupts are cascaded.
       Hardware interrupts IRQ 0 through IRQ 7 are typically assigned to
  interrupt numbers 08H through 0FH, while IRQs 8 through 15 are typically
  assigned interrupt numbers 70H through 77H.  However, IRQs may be remapped
  under either VCPI or DPMI.  The current mappings may be loaded from IRQ0INTNO
  (IRQ 0 interrupt number) and IRQ8INTNO.  These are public BYTE locations in
  DSEG.  They should be read only after the call to INITXLIB.
































                                        9






                               5. Memory Management


       XLIB supplies memory management procedures for both real mode and
  protected mode.  These procedures are configured at initialization to work
  with the currently resident memory management interfaces.
       Conventional memory may be allocated and released in real mode through
  DOS in usual fashion (INT 21H functions 48H and 49H).  However, DOS functions
  may not work properly in protected mode.  Therefore, use the XLIB routines
  PMGETDOSMEM and PMFREEDOSMEM for such requests.  Call PMGETDOSMEM with the
  requested number of bytes in EAX.  If successful (EAX returned as zero), then
  the linear address of the allocated block is returned in EDX; the allocated
  block size is returned in ECX and will be at least as large as the requested
  size.  A block handle is returned in EBX.  Call PMFREEDOSMEM to release a
  previously allocated block.  The block handle should be in EAX upon call.
       Call PMGETDOSMEM with EAX = 0 to get the largest available DOS memory
  block.  The call is successful if EAX is returned as zero, in which event the
  size of the largest available block will be in ECX (EBX and EDX are
  preserved).
       The real-mode extended memory management procedures are GETMEM, FREEMEM,
  and RESETMEM.  Allocate memory by calling GETMEM with the number of bytes
  requested in EAX.  With successful execution (EAX returned as zero), GETMEM
  will return with the linear address of the allocated extended memory block in
  EDX.  The size of the allocated block will be returned in ECX and will be at
  least as large as the requested size.  The memory block handle will be
  returned in EBX.  Release the block by calling FREEMEM with the block handle
  in EAX.  Release all previously allocated extended memory at once by calling
  RESETMEM.
       The protected-mode memory management procedures are PMGETMEM, PMFREEMEM,
  and PMRESETMEM.  These procedures function exactly as the corresponding real-
  mode procedures:  GETMEM, FREEMEM, and RESETMEM.
       GETMEM and PMGETMEM can also be used to obtain the size of the largest
  available extended memory block (not total free memory).  Call with EAX = 0
  for this purpose.  If this call is successful (EAX returned as zero), then the
  size of the largest free block will be returned in ECX (EBX and EDX are
  preserved).
       XLIB will seek extended memory through XMS only if it is present and if
  both DPMI and VCPI are absent.  If either protected-mode interface is present,
  then all extended memory will be allocated through the configured interface.
       XLIB will not use XMS to allocate memory from the high memory area (HMA)
  or from upper memory blocks (UMBs).  XLIB will however allocate from the HMA
  when it has full responsibility for extended memory management (DPMI, VCPI,
  and XMS are all absent).  XLIB never issues calls under the Expanded Memory
  Specification (EMS).













                                        10






                              6. XLIB Initialization


       Most XLIB procedures should be called only after XLIB has been
  initialized by calling INITXLIB.  This procedure will examine the operating
  environment for the presence of DPMI, VCPI, and XMS.  It will then perform
  extensive code modifications upon itself to accommodate the resident software.
  INITXLIB is to be called only once within a program.  Subsequent calls have no
  effect.
       If XLIB finds that neither DPMI nor VCPI are present, then XLIB will
  completely handle all mode switching and interrupt management.  If XLIB finds
  that XMS is absent also, then XLIB will handle all extended memory management.
  If XLIB finds that both DPMI and VCPI are present, then it will configure
  itself for DPMI by default.  However, the default may be changed by setting
  bit 0 of IFLAGS (initialization flags) before calling INITXLIB.  If this bit
  is set, then VCPI is given priority over DPMI.  IFLAGS is a public WORD
  location in DSEG.
       INITXLIB will probably attempt to allocate some conventional memory
  through DOS.  Since high-level language modules and assembly language modules
  often claim all available DOS memory by default, INITXLIB may fail for lack of
  available DOS memory.  This problem can be averted with assembly language
  modules by linking with the CPARM:1 parameter.  This forces the assembly
  language module to claim no more DOS memory than is necessary.  High-level
  language modules should call XLIBMEMREQ (XLIB memory requirements) to obtain
  conventional memory requirements in DX:AX (measured in bytes), and then
  release at least this much memory.  This process is illustrated for Microsoft
  BASIC in the next example.  C does not allocate all DOS memory and therefore
  does not require such special action.
       If both VCPI and DPMI are present, then conventional memory requirements
  will depend upon which of these interfaces is to be chosen by INITXLIB.  In
  such cases, XLIBMEMREQ will return DPMI memory requirements if bit 0 of IFLAGS
  is clear, and will return VCPI requirements otherwise.  Therefore, this bit
  should be set to the appropriate value by the user before calling XLIBMEMREQ.
  DPMI conventional memory requirements may by obtained in DX:AX by calling
  DPMIMEMREQ.  VCPI conventional memory requirements may be obtained in DX:AX by
  calling VCPIMEMREQ.
       The XLIB routine XLIBCONFIG (XLIB configuration) returns the results of
  INITXLIB.  The initialized protected-mode configuration is returned in AX.
  The value of the lower nibble specifies the configured protected-mode
  interface.  The value will be 1 for DPMI, 2 for VCPI, and 3 for XLIB.  Bit 4
  of AX will be set if XMS is configured.  XLIBCONFIG is a real-mode routine.
















                                        11






                               7. XLIB Termination


       XLIB is terminated simply by executing INT 21 function 4CH (DOS
  termination) from real mode.  This function must not be called from protected
  mode.  Upon termination, XLIB releases all previously allocated memory and
  resets all interrupt vectors to their original values.
       Termination of DPMI requires that INT 21 function 4CH be executed from
  protected mode.  XLIB intercepts INT 21 calls and determines if the function
  number is 4CH.  If so, and if DPMI is active, then XLIB shifts to protected
  mode and issues the call.














































                                        12






                  8. Using XLIB in High-Level Language Libraries


       The following program illustrates the usage of XLIB in libraries called
  from Microsoft BASIC 7.0.  The library contains a protected-mode procedure
  which sums the elements in a single precision array created within BASIC.  The
  general methodolgy here is recommended for developing assembly language
  libraries.
       Since BASIC cannot call a 32-bit segment, a real-mode interface procedure
  must be placed in a 16-bit segment to receive the BASIC call and then transfer
  execution to 32-bit protected mode.  The interface procedure is call SUMARRAY
  while the 32-bit protected-mode procedure which actually sums the array
  elements is called SUMARRAY32.
       BASIC must pass certain arguments to the library procedures.  These
  include the array address and the number of elements to be summed.  These
  arguments could be passed on the stack; however, such approach proves awkward
  since the stack must be changed when entering protected mode.  Consequently,
  BASIC places all arguments in a contiguous block of memory called a "control
  block," and then passes only the address of the control block to the library.
  BASIC constructs the control block with a user-defined type.
       The first four bytes of the control block are reserved for placement of
  error codes by the library procedures.  Also, the address of the control block
  is placed in CCODEPTR so that any FPU exceptions will be signalled in the
  error code location as well.  Were an FPU exception to occur, the FPU
  interrupt handler will immediately transfer control to EXITPM which will shift
  to real-mode, restore registers, and return control to BASIC.
       The library also contains a real-mode function called LINADR which may be
  called by BASIC to convert segment addresses to linear addresses.
       An example of this same program for Microsoft C 7.0 is included in
  Appendix D.


  Example 2:  Calling Protected-Mode Libraries From BASIC
  -----------------------------------------------------------------------------
                            +++++++++++++++++++++++++
                            + ASSEMBLY CODE LIBRARY +
                            +++++++++++++++++++++++++


  ;The following library should be combined with XLIB.LIB using the Microsoft
  ;LINK and LIB utilities.  If BASIC is to be executed from the QBX
  ;environment, then a quick library must be loaded with the environment.  See
  ;BASIC documentation for instructions.


                 .MODEL         LARGE,PASCAL
                 .386P

                 INCLUDE        XLIB.INC

  CSEG           SEGMENT PARA PUBLIC USE16 'CODE'
                 ASSUME CS:CSEG, DS:DSEG





                                        13






  ;Function to calculate linear address from segment address on stack.
  ;Returns linear address in DX:AX.
  LINADR         PROC FAR PUBLIC,
                 SEGADR:DWORD                  ;Segment address of variable
                 XOR            EAX,EAX        ;Clear high words