Der Mediaplex Sampler - Die 6 von Plex/6_v_plex.zip/6_v_plex/DISK5/DOS_42/XLIB30.ZIP/XLIB.DOC

Text File | 1993-12-20 | 129KB | 3,240 lines

                             XLIB PROGRAMMER'S MANUAL
                                   VERSION 3.0

                              (DOS Extender Library)

                                TechniLib Company























                    Copyright 1993, by TechniLib (TM) Company
                               All Rights Reserved






                          TERMS OF USE AND DISTRIBUTION


       XLIB is a shareware product; therefore, unregistered copies of XLIB are
  made available free of charge so that potential purchasers will have the
  opportunity to examine and test the software before committing payment.
  Distribution of unregistered copies of XLIB to other potential users is also
  permitted and appreciated.  However, usage and distribution of XLIB must
  conform to the following conditions.  In the following statement, the term
  "commercial distribution," includes shareware distribution.

  1) XLIB and accompanying software must be distributed together in copies of
  the original archive provided by TechniLib.  Neither the archive nor
  individual files therein may be modified.

  2) The XLIB archive may be distributed in combination with other shareware
  products; however, the XLIB archive may not be distributed with other
  commercially distributed software without written consent of TechniLib.

  3) Copies of XLIB which have been used to develop software for commercial
  distribution must be registered before such software is marketed.  Copies of
  XLIB which have been used to develop noncommercial software must be registered
  if such software is to be regularly used either by the developer or others.

  4) Commercially distributed software must embed XLIB procedures in the
  software code.  Files contained in the XLIB archive may not be placed in the
  distribution media.

  5) XLIB is designed to offer a set of services to other executable code.  XLIB
  may not be used to develop software for commercial distribution which will
  essentially offer any of these same services to other executable code.
  Exceptions to this condition require written consent of TechniLib.

  6) Rights afforded by registering a single copy of XLIB pertain only to a
  single computer.

  7) XLIB may be registered for a fee of $40.00 per copy.  Accompany payment
  with the registration form included in the XLIB archive.  Registrants will be
  entitled to the most recent version of the XLIB archive.


                              DISCLAIMER OF WARRANTY


       XLIB AND ALL ACCOMPANYING SOFTWARE AND LITERATURE ARE DISTRIBUTED WITH
  THE EXCLUSION OF ANY AND ALL IMPLIED WARRANTIES, AND WITH THE EXCLUSION OF
  WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  TechniLib
  SHALL HAVE NO LIABILITY FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  RESULTING FROM THE USE OF XLIB OR ACCOMPANYING MATERIALS.  The user assumes
  the entire risk of using this software.


                    Copyright 1993, by TechniLib (TM) Company
                               All Rights Reserved






                                TABLE OF CONTENTS


  CHAPTERS
                                                                      Page
  1.  Introduction                                                       1
  2.  XLIB Conventions and Structure                                     4
  3.  XLIB Initialization and Termination                                7
  4.  Mode Switching                                                    10
  5.  Inline Mode Switching                                             14
  6.  Interrupt Management                                              18
  7.  Memory Management                                                 24
  8.  File Management                                                   28
  9.  Descriptor Management                                             33
  10. Using XLIB in High-Level Language Libraries                       34


  TABLES
                                                                      Page
  1.  XLIB Segments and Selectors by Public Symbol                       5
  2.  IFLAGS Settings for Memory Allocation Control                      8
  3.  CALLPM/ENTERPM Register Storage Locations by Public Symbol        12
  4.  CALLRM Register Storage Locations by Public Symbol                13
  5.  XLIB File Control Block Structure                                 28


  EXAMPLES
                                                                      Page
  1.  Simple Mode Switching Under XLIB                                   3
  2.  Using INLINEPM/INLINERM in C                                      15
  3.  Calling Protected-Mode Libraries From BASIC                       34


  APPENDICES
                                                                      Page
  A. Description of XLIB Public Data                                    38
  B. XLIB Error Codes                                                   41
  C. DPMI 1.0 Error Codes                                               43
  D. XMS Error Codes                                                    44
  E. Calling Protected-Mode Libraries From C                            45
  F. Reporting Problems With XLIB                                       47
  G. The SWITCHPM and SWITCHRM Procedures                               48






                                 1. Introduction


       XLIB is an assembly language library which greatly simplifies protected-
  mode programming under the Microsoft DOS operating system.  Assembly language
  programmers will likely abandon real-mode programming after acquiring XLIB.
  With only two calls to XLIB procedures, assembly language programs can be
  utilizing the simplicity and power of 32-bit processing.  C and C++ programs
  can harness the powers of 16-bit protected mode using inline assembly.
  Additionally, the XLIB archive contains a second library call EASYX which can
  be used by all high-level languages to gain access to extended memory.
       XLIB is designed for the Intel 386, 486, and Pentium processors.  XLIB
  fully utilizes the 32-bit processing powers of these chips and makes these
  powers available to the user.  The compactness of XLIB follows largely from
  the fact that much of it is written in 32-bit code.
       Previous versions of XLIB contained only Microsoft compatible files;
  however, the archive for XLIB version 3.0 includes libraries and sample code
  in both Microsoft and Borland formats.
       XLIB is used to produce extended DOS applications.  DOS is unfortunately
  limited by the fact that it is a real-mode operating system intended to manage
  only real-mode programs.  Real-mode programs cannot use memory addresses
  requiring more than 20 bits, or use memory offsets requiring more than 16
  bits.  Such programs are further limited by the fact that 32-bit instructions
  execute awkwardly in real-mode.  When the processor is in real-mode, it will
  expect all 32-bit instructions to be preceded by at least one prefix.  Each of
  these prefixes consumes one byte of memory and requires at least one clock to
  execute.  Such limitations do not exist in 32-bit protected mode.  Extended
  DOS applications overcome the limitations of DOS with their ability to execute
  in both real and protected modes.  DOS services can be utilized from real mode
  while the 32-bit processing power of the CPU can be utilized from protected
  mode.
       There are presently several 32-bit operating systems available on the
  market.  Such systems include IBM OS/2, Microsoft Windows NT, and UNIX.  These
  systems can manage programs which operate exclusively in protected mode.  Such
  programs are generally easier to develop than extended DOS applications.
  However, extended DOS applications have an advantage in that they can execute
  under all of these operating systems because all of these systems can emulate
  DOS.
       Of course DOS will eventually become obsolete.  Future programs will
  likely operate exclusively in protected mode using the flat (unsegmented)
  memory model.  The memory models supported by XLIB approximate the flat model;
  therefore, code written for XLIB will require little modification when being
  transported to flat-model operating environments.  Indeed, many procedures
  will require no modification whatsoever.  Moreover, XLIB includes flat-model
  descriptors which may be used to execute genuine flat-model code.  XLIB does
  not load and relocate such code; however, it does provide all the necessary
  tools to develop such procedures.
       XLIB procedures handle important tasks such as mode switching between
  real and protected modes, memory management under protected mode, protected-
  mode interrupt management, and protected-mode file management.  XLIB includes
  routines to perform these tasks in the absence of a protected-mode interface,
  or in the presence of the Virtual Control Program Interface (VCPI), or the DOS
  Protected Mode Interface (DPMI, version .9 or higher).  XLIB can also manage
  extended memory through the Extended Memory Specification (XMS).  This



                                        1






  versatility makes XLIB compatible with nearly all common operating
  environments for 386, 486, and Pentium processors.
       Upon initialization, XLIB will examine the operating environment for the
  presence of DPMI, VCPI, and XMS, and then configure itself accordingly.  The
  client program may therefore perform calls to XLIB procedures with few
  concerns as to the environment in which it is executing.
       This manual is not intended to teach protected-mode programming.  It is
  assumed that the reader has a general knowledge of protected mode and a
  working knowledge of assembly language.  Programmers who are unfamiliar with
  assembly language and who need protected-mode execution merely to access
  extended memory from within high-level languages should consider using the
  EASYX library.  This library is a real-mode interface to XLIB.  It contains
  procedures which may be utilized without assembly language.  The documentation
  for EASYX is included in the XLIB archive.  The reader might wish to refer to
  this documentation now; however, the present document may still be needed for
  technical reference.
       XLIB relieves the programmer of descriptor table management by supplying
  a set of predefined segments along with their associated descriptors and
  selectors.  Many protected-mode procedures will require no modification for
  XLIB other than being placed in the proper segment.  XLIB provides a single
  32-bit segment for protected-mode routines.  This segment may be larger than
  64K, but must reside in conventional memory so that DOS can load it.  However,
  code within this segment may access data throughout the address space.  XLIB
  does allow user-defined descriptors; however, these should be needful only in
  very rare cases.
       The following program illustrates the simplicity with which protected-
  mode execution may be initiated and terminated with XLIB.  The program was
  written with the Microsoft Assembler (MASM).  It first initializes XLIB by
  calling a procedure called INITXLIB.  After confirming that initialization is
  successful, the program then transfers control to a 32-bit protected-mode
  procedure which prints a message to the screen.  Control is transferred by
  placing the protected-mode target address on the stack and then calling an
  XLIB procedure named CALLPM (call protected mode).  CALLPM will expect the
  target procedure to be contained in a segment called TSEG.  The protected-mode
  procedure in TSEG returns control to real or virtual 8086 (V86) mode simply by
  executing the RET instruction.





















                                        2






  Example 1:  Simple Mode Switching Under XLIB
  _____________________________________________________________________________
                 .MODEL        LARGE,PASCAL
                 .386P

                 INCLUDE        XLIB.INC       ;Include XLIB public symbols
                 INCLUDELIB     XLIB.LIB       ;Link with XLIB.LIB

                 .STACK         1024
                 .CODE
                 .STARTUP

                 CALL           INITXLIB       ;Initialize XLIB
                 OR             EAX,EAX        ;EAX = 0 if successful
                 JZ             INITDONE
                 .EXIT          0              ;Initialization failed

  INITDONE:      PUSHD          OFFSET DEMOPROC
                 CALL           CALLPM         ;Execute DEMOPROC in protected
                 .EXIT          0

  ;Protected-mode routines must be placed in following segment:
  TSEG           SEGMENT PARA PUBLIC USE32 'CODE'
                 ASSUME CS:TSEG, SS:TSEG, DS:TSEG, ES:TSEG, FS:DSEG, GS:DGROUP

  ;Protected-mode routine to print message to the screen using DOS function.
  DEMOPROC       PROC NEAR
                 MOV            EBX,OFFSET PMMSG
                 MOV            AH,02H
  MSGLOOP:       MOV            DL,CS:[EBX]    ;32-bit offset!!!!!
                 OR             DL,DL
                 JZ             EXIT
                 INT            21H            ;Print character with DOS
                 INC            EBX
                 JMP            MSGLOOP
  EXIT:          RET                           ;Go back to real or V86 mode
  PMMSG          DB  "In 32-bit protected mode!!!  "
                 DB  "Returning to real mode.",10,13,0
  DEMOPROC       ENDP

  TSEG           ENDS
                 END
  _____________________________________________________________________________


       The framework presented in the above program is extremely simple;
  nonetheless, it will meet the demands of many protected-mode programs.  Most
  protected-mode programs will require no further complications apart from a few
  calls to XLIB extended memory management procedures.
       To achieve the simplicity of the above program, XLIB must handle numerous
  complexities internally.  This manual attempts to give the reader thorough
  insight into the workings of XLIB.  It also discusses at length the numerous
  configuration options that are available to the programmer.




                                        3






                        2. XLIB Conventions and Structure


       The XLIB archive contains files for both Microsoft and Borland languages.
  The files for Borland have the same names as those for Microsoft except a "B"
  is added to the base name.  For example, XLIB.LIB is the XLIB library intended
  for Microsoft languages whereas XLIBB.LIB is intended for Borland languages.
  Sample code in this document is always for Microsoft languages; however,
  Borland versions may be found in the archive.  Important information about
  using XLIB with Microsoft and Borland languages has been included in the
  README.DOC file.
       The Microsoft version of XLIB was developed and tested under Microsoft
  DOS version 6.0 using Microsoft Assembler (MASM) version 6.11, Microsoft LINK
  version 5.31.009, and Microsoft LIB version 3.20.01.  The Borland version of
  XLIB was developed and tested using Turbo Assembler (TASM) version 3.1, TLINK
  version 5.0, and TLIB version 3.02.
       XLIB has been tested under Microsoft Windows 3.1, Qualitas 386MAX version
  6.02, Quarterdeck QEMM versions 6.02 and 7.03, Quarterdeck QDPMI versions 1.01
  and 1.03, Quarterdeck DESQview version 2.42, and IBM OS/2 version 2.1.
       XLIB public procedures and public data are explained in the following
  chapters.  A detailed explanation of most XLIB public data is also included in
  Appendix A.  This chapter sets forth rules which will be generally applicable
  to all XLIB data and procedures.
       Though it is sometimes necessary for XLIB to distinguish between real
  mode and virtual 8086 mode; this document uses the term "real mode" to include
  virtual 8086 mode.
       All public real-mode procedures and 16-bit protected-mode procedures in
  XLIB are located in a segment called CSEG.  The user may also place code in
  CSEG but is rarely required to do so.  All public XLIB procedures in CSEG have
  far returns.
       All public 32-bit protected-mode procedures in XLIB are located in a 32-
  bit segment called TSEG and have near returns.  XLIB will also expect the user
  to place all 32-bit procedures in TSEG and will expect these procedures to
  have near returns.  This policy is adopted to achieve approximation to the
  flat model.
       Nearly all XLIB protected-mode procedures are 32-bit routines.  The only
  exceptions to this rule are the inline mode-switch procedures discussed in
  Chapter 5.  This policy is implemented to approximate the flat model.  There
  are very few circumstances in which 16-bit protected mode is preferable to 32-
  bit protected mode.  One can generally increase program speed and reduce
  program size by writing the code for 32-bit segments.
       TSEG may be larger than 64K provided that certain rules are observed.
  XLIB adheres to all of the necessary rules.  First, only 32-bit protected-mode
  code should be placed in TSEG.  The processor will not generally be able to
  execute real-mode code in this segment because the offsets will be 32-bit
  values.  Second, real-mode code should never write to or read from TSEG.  Such
  instructions will also require 32-bit offsets.  Modifications to TSEG should
  be done from a TSEG protected-mode procedure.  Finally, segment constants
  should never be encoded in TSEG.  For example, the symbols CSEG, TSEG, DSEG,
  and DGROUP should not be found in TSEG.  DOS will not be able to perform
  relocation edits on these constants if they are in a segment larger than 64K.
  To read these values from TSEG, initialize memory locations in a 16-bit
  segment to the values and then read the memory locations.  Memory locations in
  DSEG have already been initialized for XLIB segments (see Appendix A).



                                        4






  Microsoft LINK will issue a warning for code segments exceeding 64K; however,
  this warning may be safely ignored provided that the above rules are observed.
       All XLIB procedures may be called with interrupts enabled and will return
  with interrupts enabled provided that they were enabled upon call.
       With one exception, all XLIB public data is contained in a 16-bit segment
  called DSEG.  The user may also place data in DSEG but is rarely required to
  do so.
       XLIB uses the PASCAL calling and naming convention.  The PASCAL
  convention is equivalent to the BASIC and FORTRAN conventions.  C programmers
  must adapt XLIB procedures and symbols with declarations which specify the
  PASCAL convention.  The header file XLIB.H contains such declarations.
       XLIB routines which can encounter error conditions will always return
  XLIB error codes in AX.  A list of such error codes is presented in Appendix
  B.  In most cases, DX or the high word of EAX will be returned with specific
  information about the error, such as DPMI, XMS, or DOS error codes.  DPMI
  error codes are presented in Appendix C.  XMS error codes are in Appendix D.
       Selectors for all XLIB segments are placed in public WORD locations in
  segment DSEG.  The following table gives the name of each predefined selector
  along with its associated segment name and description:


  Table 1:  XLIB Segments and Selectors by Public Symbol
  _____________________________________________________________________________
  Selector Name    Segment Name      Description
  -------------    ------------      -----------
  CSEGSEL          CSEG              XLIB 16-bit code segment
  CSEGDSEL         CSEG              Data selector to CSEG
  TSEGSEL          TSEG              32-bit code segment
  TSEGDSEL         TSEG              Data selector to TSEG
  DSEGSEL          DSEG              XLIB data segment
  FLATSEL          .                 Flat-model code
  FLATDSEL         .                 Flat-model data
  DGROUPSEL        DGROUP            DGROUP data group
  SCRNSEL          .                 Screen data
  MAINCSSEL        .                 CS selector for main caller
  MAINSSSEL        .                 SS selector for main caller
  MAINDSSEL        .                 DS selector for main caller
  MAINESSEL        .                 ES selector for main caller
  ILCSSEL          .                 Inline CS selector
  ILSSSEL          .                 Inline SS selector
  ILDSSEL          .                 Inline DS selector
  _____________________________________________________________________________


       The flat-model and TSEG descriptors have limit FFFFFFFFH.  All other
  descriptors have limit FFFFH.  The screen descriptor has base set to B8000H
  for color monitors and B0000H for monochrome monitors.  MAINCSSEL, MAINSSEL,
  MAINDSSEL, and MAINESSEL are selectors to descriptors which have base
  addresses matching the contents of CS, SS, DS, and ES as of the call to
  INITXLIB.  ILCSSEL, ILSSSEL, and ILDSSEL are selectors used by the inline
  mode-switch procedures (see Chapter 5).  The base addresses of the
  corresponding descriptors are adjusted dynamically.
       All data segments are writable.  The data descriptors have their big bits
  set; consequently, implicit stack instructions will use ESP rather then SP.



                                        5






  All code segments are readable and nonconforming.  Descriptor privilege levels
  and requested privilege levels are set to zero unless DPMI is installed.
  Privilege levels under DPMI will generally be set to three.
       The values contained in the above selectors will be different under DPMI
  than other environments.  Moreover, DPMI selector values can differ in
  different environments and under different hosts.  Therefore, the user should
  not assume these values to be constant.
       Since selector values are stored in DSEG, the user must never lose track
  of the DSEG selector.  This could prove a problem in interrupt handlers where
  no assumptions can be made as to register contents.  Consequently, XLIB places
  a copy of the DSEG selector in TSEG where it can always be found.  It is
  stored under WORD symbol CSDSEGSEL and may be read with CS override.  For
  example from TSEG code you can always load DS with DSEGSEL using MOV
  DS,CS:CSDSEGSEL.
       XLIB never uses selectors past DGROUPSEL in Table 1.  The user may
  therefore redefine the associated descriptors if desired (see Chapter 9).
  Selector values however should not be changed.








































                                        6






                      3. XLIB Initialization and Termination


       XLIB procedures apart from those presented in this chapter should be
  called only after XLIB has been initialized by calling INITXLIB.  This routine
  will examine the operating environment for the presence of DPMI, VCPI, and
  XMS.  It will then perform extensive code modifications upon XLIB 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 possibly attempt to allocate some memory through DOS.
  Since high-level language modules and assembly language modules often claim
  all available conventional memory, INITXLIB may fail for lack of available
  memory.  This problem can be averted with MASM programs by linking with the
  CPARM:1 parameter.  This forces the program to claim no more conventional
  memory than is necessary.  TASM programs and some high-level language programs
  should release memory to DOS during initialization.  This process is
  illustrated for TASM in the file EXAMP1B.ASM.  In some cases, the main program
  will need to retain all memory except what is necessary for XLIB.  The XLIB
  procedure XLIBMEMREQ (XLIB memory requirements) may be called to obtain
  conventional memory requirements for XLIB.  Usage of XLIBMEMREQ is illustrated
  for Microsoft BASIC in Chapter 10.  C and C++ do not allocate all conventional
  memory and therefore do not require any 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 (the default), 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 be obtained by
  calling DPMIMEMREQ.  These will vary from host to host.  VCPI conventional
  memory requirements may be obtained by calling VCPIMEMREQ.  VCPI requirements
  are slightly over 12K and are the same for all servers.
       One of the principle function of XLIB is of course to make protected-mode
  interfaces and memory management interfaces transparent to the client program.
  However, there are special cases where a program should be informed as to
  which interfaces are implemented.  In such cases, the procedure XLIBCONFIG
  (XLIB configuration) may be called to determine the how XLIB has been
  configured by INITXLIB.
       XLIB is terminated with INT 21H function 4CH (DOS termination) issued
  either from real or protected mode.










                                        7






  Detailed Specifications


  INITXLIB (Initialize XLIB)
  Purpose:  Check for presence of XMS, DPMI, and VCPI, then configure XLIB to
  operate with the installed interfaces.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:
     AX = 0 if successful, in which event DX and EAX are zero as well.  The
  configured interfaces may be identified by calling XLIBCONFIG (see below).
     AX <> 0 if unsuccessful.  An XLIB error code is returned in AX.  A specific
  error code is returned in DX and in the high word of EAX (EAH).  If AX = 11H
  or 12H, then DX and EAH will equal a DOS error code.  If AX = DPMI error, then
  DX and EAH will equal a 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 possibly attempt to allocate conventional memory.  The
  amount of memory XLIB will attempt to allocate can be obtained by calling
  XLIBMEMREQ (see below).  The general address range from which this memory is
  allocated can be controlled by appropriately setting the high byte of IFLAGS.
  Alternative values for this byte are presented in Table 2.  The byte has a
  value of 2 by default.  This setting forces XLIB to allocate from the highest
  available address in conventional memory.  Under certain settings of IFLAGS,
  XLIB can also allocate from upper memory (DOS 5.0 or higher).
     Descriptors are created for the segments loaded in CS, SS, DS, and ES as of
  call to this routine.  The selectors for these descriptors are MAINCSSEL,
  MAINSSSEL, MAINDSSEL, and MAINESSEL.  These descriptors are never used by
  other XLIB procedures.  They are provided to augment development of protected-
  mode libraries.  Protected-mode library routines may access the stack and data
  of the main program through these descriptors.
     INITXLIB should be called only once within a program.  Subsequent calls are
  returned with no action.  XLIB is terminated by INT 21H function 4CH (DOS
  termination) issued from either real or protected mode.


  Table 2:  IFLAGS Settings for Memory Allocation Control
  _____________________________________________________________________________
  Bits 8-15     Implied Memory Allocation Location
  ---------     ----------------------------------
  00H           Lowest available address in conventional memory (00000H-9FFFFH)
  01H           Best fit in conventional memory
  02H           Highest available address in conventional memory
  40H           Lowest available address in upper memory (A0000H-FFFFFH)
  41H           Best fit in upper memory
  42H           Highest available address in upper memory
  81H           Follow strategy 40H by 00H if necessary
  82H           Follow strategy 41H by 01H if necessary
  83H           Follow strategy 42H by 02H if necessary
  _____________________________________________________________________________




                                        8






  XLIBMEMREQ (XLIB Memory Requirements)
  Purpose:  Find XLIB conventional memory requirements.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:
     Sign bit of DX clear if successful.  Memory requirements in bytes are
  returned in DX:AX.
     Sign bit of DX set if unsuccessful.  An error code is returned in AX
  (always a DOS error code).
  Details:
     DX:AX is adjusted upward to an integer multiple of 16.
     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.
     This routine will return DX:AX = 0 if XLIB contains free internal memory in
  sufficient quantity to meet conventional memory demands.
     This routine obtains DPMI requirements by calling DPMIMEMREQ (see below)
  and VCPI requirements by calling VCPIMEMREQ.

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

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

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







                                        9






                                4. Mode Switching


       As illustrated in Example 1, CALLPM may be used to transfer control to
  32-bit protected mode in segment TSEG.  When execution is returned to real
  mode, segment registers, ESP, system flags, and control flags are restored to
  their original values.
       Execution may also be transferred to protected mode in TSEG with the
  ENTERPM (enter protected mode) procedure.  This procedure is specially
  designed to accommodate mixed-language programming with high-level languages
  operating in real mode.  High-level language modules may be linked with
  libraries containing protected-mode procedures.  These procedures may then be
  called from high-level code.  However, such procedures must generally be
  careful to restore register state.  ENTERPM restores register state as
  required by Microsoft high-level languages.  In particular, ENTERPM restores
  all registers except EAX, EDX, and the status flags.  EAX and EDX are not
  restored because these are typically used by high-level languages for return
  values.  ENTERPM otherwise functions exactly as CALLPM.
       Both CALLPM and ENTERPM save register state as of call.  CALLPM and
  ENTERPM will also save and restore the state of the floating point unit (FPU)
  if requested.  FPU save/restore can be enabled by setting bit 2 of OFLAGS
  (operation flags).  The bit is clear by default.  OFLAGS is a public WORD in
  DSEG.
       FPU state is saved with the FSAVE instruction executed from real mode.
  This instruction resets the FPU; consequently, the FPU control word must be
  redefined.  XLIB will therefore load FPUCW (FPU control word) to the FPU
  control word after performing FSAVE.  FPUCW is a public WORD location in DSEG.
       After entering protected mode through CALLPM or ENTERPM, control would
  typically be returned to real mode with the RET instruction.  However, control
  may also be returned to real mode by jumping to either RETPM or EXITPM.  These
  are both procedures in TSEG.  They will successfully return control to real
  mode regardless of the stack state; therefore, they can be useful for
  debugging.  For example, an unidentified area of protected-mode code that is
  causing the system to crash can be isolated by placing jumps to EXITPM at
  alternative locations.
       RETPM returns control to the real-mode caller of CALLPM/ENTERPM after
  restoring segment registers, ESP, system flags, and control flags.  EXITPM
  returns control to the real mode caller after restoring all registers except
  EAX, EDX, and the status flags.
       The return address placed on the stack by CALLPM is actually a near
  return to RETPM.  Likewise, ENTERPM places a near return to EXITPM.  CALLPM
  and ENTERPM are otherwise identical procedures.
       Once within protected mode, far procedures in real mode can be called
  using CALLRM.  CALLRM may be called only by protected-mode procedures in TSEG.
       XLIB contains two hardware interrupt handlers that are typically
  activated upon entry to protected mode.  These handlers are fully explained in
  Chapter 6.  The first handler is hooked to the keyboard interrupt.  This
  handler manages hot key detection.  The second handler is hooked to the FPU
  interrupt and is designed to handle FPU exceptions.








                                        10






  Detailed Specifications


  CALLPM (Call Protected Mode)
  Purpose:  Call a protected-mode procedure in TSEG with near return.
  CPU Mode:  Real
  Registers at Call:  SS:ESP = 32-bit protected-mode target offset.
  Return Registers:  Returns through RETPM.  See RETPM for details.
  Details:
     All CPU registers except EAX and EDX are saved at locations presented in
  Table 3.  The stack is saved after the return address and argument have been
  popped.
     The target receives SS = TSEGDSEL with 1000H free bytes on the stack.  The
  return address on the stack is a near return to RETPM.  The target receives by
  default:  DS = FLATDSEL, ES = TSEGDSEL, FS = DSEGSEL, and GS = DGROUPSEL.
  Other registers, including the status flags, are received at values as of
  call.
     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.
     XLIB hardware interrupt handlers are enabled (see Chapter 6).  However, if
  bit 1 of OFLAGS is set, then the XLIB interrupt handler for the FPU will not
  be enabled.
     If an FPU exception occurs after CALLPM, and if the FPU exception handler
  is enabled, then protected mode will be exited through EXITPM rather than
  RETPM.  If FPU save/restore is not enabled, then real-mode will receive an
  initialized FPU with control word set to the value existing as of the
  exception.
     The user may change the stack after the mode switch.
     DS, ES, FS, and GS are actually loaded from:  PMDS, PMES, PMFS, and PMGS.
  These are public WORD locations in DSEG and are initialized to the default
  selectors by INITXLIB.  The user however may change these selectors to any
  legal values after initialization.

  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, ESP,
  system flags, and control flags to values as of call to either CALLPM or
  ENTERPM.  XLIB hardware interrupt handlers are disabled (see Chapter 6).
  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 a protected mode procedure in TSEG with near return.
  CPU Mode:  Real
  Registers at Call:  SS:ESP = 32-bit protected-mode target offset.
  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.



                                        11






  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,
  EDX, and status flags to values as of call to either CALLPM or ENTERPM.  XLIB
  hardware interrupt handlers are disabled (see Chapter 6).  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 state.
     EXITPM will successfully execute regardless of stack state.
     The FPU exception handler performs a jump to EXITPM upon occurrence of any
  unmasked FPU exception.


  Table 3:  CALLPM/ENTERPM Register Storage Locations by Public Symbol
  _____________________________________________________________________________
  Register           Symbol              Symbol Type
  --------           ------              -----------
  EBX                ORGEBX              DWORD
  ECX                ORGECX              DWORD
  ESI                ORGESI              DWORD
  EDI                ORGEDI              DWORD
  EBP                ORGEBP              DWORD
  ESP                ORGESP              DWORD
  EFLAGS             ORGEFLAGS           DWORD
  SS                 ORGSS               WORD
  DS                 ORGDS               WORD
  ES                 ORGES               WORD
  FS                 ORGFS               WORD
  GS                 ORGGS               WORD
  FPU State          ORGFPU              BYTE[94]
  _____________________________________________________________________________


  CALLRM (Call a Real-Mode Procedure)
  Purpose:  Call a real-mode routine with far return from protected mode.
  CPU Mode:  Protected
  Registers at Call:  SS:ESP = far real-mode target address (four bytes).
  Return Registers:  All segment registers and ESP are restored.  Other
  registers, including status flags, are received with values as of the real-
  mode RET instruction.
  Details:
     This is a near procedure in TSEG.  It must therefore be called from TSEG.
     Segment registers and ESP are saved at locations presented in Table 4.  The
  stack is saved after popping the return address and argument.
     The target receives the XLIB real-mode stack (SS = DSEG) with 200H free
  bytes.  By default, the target receives DS = DGROUP, ES = DSEG, FS = DSEG, and
  GS = DSEG.  Other registers, including status flags, are received at values as
  of call.
     Code called by this routine should not perform calls to XLIB procedures
  other than SWITCHPM and SWITCHRM (see Appendix G).  Most real-mode procedures




                                        12






  in XLIB issue calls to CALLPM; however, neither this procedure nor ENTERPM are
  reentrant.
     DS and ES are actually loaded from RMDS and RMES.  These are public WORD
  locations in DSEG and are initialized to the default values.  However, the
  user may change these values if desired.
     This procedure does not change values in OFLAGS; consequently, XLIB
  hardware interrupt handlers remain enabled in real mode if they were enabled
  as of call (see Chapter 6).
     FPU exceptions in real mode are handled the same as in protected mode;
  however, system software is less apt to be left in regular state after real-
  mode exceptions.  FPU instructions should therefore be executed in protected
  mode where possible.


  Table 4:  CALLRM Register Storage Locations by Public Symbol
  _____________________________________________________________________________
  Register           Symbol              Symbol Type
  --------           ------              -----------
  ESP                CALLESP             DWORD
  SS                 CALLSS              WORD
  DS                 CALLDS              WORD
  ES                 CALLES              WORD
  FS                 CALLFS              WORD
  GS                 CALLGS              WORD
  _____________________________________________________________________________
































                                        13






                             5. Inline Mode Switching


       XLIB includes two routines to perform mode switching in C and C++
  programs using inline assembly.  These procedures are very versatile and
  simple.  They switch the processor between real mode and 16-bit protected
  mode.  A third routine is included to facilitate calls from 16-bit protected-
  mode to 32-bit near procedures in TSEG.
       Call INLINEPM to switch to 16-bit protected mode.  Descriptors are
  automatically created for CS, SS, and DS.  These registers are returned
  containing selectors to the respective descriptors.  ES is returned containing
  DSEGSEL.  ES may therefore be used to load other XLIB selectors to segment
  registers.
       Call INLINERM to return to real-mode.  This function should be called
  from the same segment as the previous call to INLINEPM and should be using the
  same stack segment.  INLINERM restores segment registers to values which
  existed as of the call to INLINEPM.
       The following Microsoft C 7.0 program illustrates the usage of these
  procedures.  The program contains a C subroutine called "getextmem" which uses
  INLINEPM and INLINERM to retrieve a DWORD from extended memory.
       Since the Microsoft C 7.0 compiler does not recognize 32-bit assembly
  instructions, the following program attains access to 32-bit registers by
  encoding prefixes in front of 16-bit instructions.  These prefixes are
  inserted with the _emit directive.  Also observe that INLINERM is called
  indirect through a supplied pointer in DSEG called INLINERMPTR.  This is done
  to ensure that the intersegment call loads CS with the protected-mode selector
  for CSEG (CSEGSEL) rather than with the segment constant.
       A Borland C version of this program is contained in the file EXAMP2B.C.
  The Borland version is somewhat simpler than the following program because 32-
  bit registers can be used in Borland C provided that TASM is used to perform
  the assembly.
       This program may fail if an attempt is made to access logical addresses
  which are either protected or undefined in the page tables.
























                                        14






  Example 2:  Using INLINEPM/INLINERM in C
  _____________________________________________________________________________
  #include <stdio.h>
  #include <xlib.h>
  #define som _emit 0x66               /*Switch operand mode*/
  #define sam _emit 0x67               /*Switch address mode*/
  long __far getextmem(long address);
  int goterr = 0;                      /*Error flag*/

  void main(void)
  {
    long l, xaddress;
    l = INITXLIB();                    /*Initialize XLIB*/
    if(l != 0)                         /*See if an error occurred*/
    {
      printf("Library initialization error:  %lX\n",l);
      return;
    }

    xaddress = 0x100000;               /*Read first dword in 2ond meg*/
    l = getextmem(xaddress);           /*See if an error occurred*/
    if(goterr != 0)
    {
      printf("Inline mode-switch error:  %lX\n",l);
      return;
    }
    printf("[%lX] = %lX\n",xaddress,l);
  }

  long __far getextmem(long address)
  {
    __asm
    {
      som                             ;mov  eax,[bp+6]
      mov       ax,[bp+6]             ;  ""
      call      INLINEPM              ;Switch to 16-bit protected mode
      jc        error                 ;Error code in ax
      mov       ds,es:FLATDSEL        ;Switch to flat data model
      sam                             ;push dword ptr [eax]
      som                             ;  ""
      _emit     0ffh                  ;  ""
      _emit     030h                  ;  ""
      pop       ax                    ;Return address contents in dx:ax
      pop       dx
      call      es:INLINERMPTR        ;Switch back to real mode by calling
      jmp       done                  ;INLINERM indirect.  A direct call would
                                      ;load cs with an invalid value.
  error:
      xor       dx,dx                 ;Return error code in dx:ax
      inc       goterr                ;Set error flag
  done:
    }
  }
  _____________________________________________________________________________



                                        15






  Detailed Specifications


  INLINEPM (Inline Protected-Mode)
  Purpose:  Return to real-mode caller in 16-bit protected mode.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:
     CF clear if successful.  Descriptors are created for CS, SS, and DS.  These
  descriptors have base addresses matching the calling contents of the
  respective segment registers.  The segment registers are returned containing
  selectors to these descriptors.  These selectors are also stored in DSEG at
  the public WORD locations ILCSSEL, ILSSSEL, and ILDSSEL.  See Chapter 2 for
  further details as to descriptor specifications.  ES, FS, and GS are returned
  containing DSEGSEL.  Protected mode receives other registers, except the
  status flags, at values as of call.
     CF set if unsuccessful.  The processor will still be in real mode.
  Unsuccessful execution can occur only under DPMI.  EAX is returned with an
  error code.  AX = XLIB error code.  The high word of EAX will equal a DPMI 1.0
  error code (if provided by host).  Other registers, except the status flags,
  are unchanged.
  Details:
     INLINEPM stores segment registers at the same locations used by CALLPM and
  ENTERPM (Table 1).  INLINERM (see below) then restores these registers.  C
  will require that other registers be preserved also; however, the user is
  responsible for managing these.
     XLIB hardware interrupt handlers are not activated by this procedure (see
  Chapter 6).  The keyboard handler may be enabled by the user if hot key
  detection is needful; however, the FPU exception handler should never be
  enabled.  Therefore, hot key detection should be enabled by setting both bits
  0 and 1 in OFLAGS.
     SP is preserved through the mode switch; however, the high word of ESP is
  set to zero.  The high word must be cleared since SS is set to a descriptor
  having FFFFH limit and having its big bit set.
     If multiple calls are made to INLINEPM with the same values in CS, SS, and
  DS, then descriptors are created only on the first call.  Subsequent calls
  will therefore execute more quickly.

  INLINERM (Inline Real-Mode)
  Purpose:  Return to 16-bit protected-mode caller in real mode.
  CPU Mode:  16-bit protected mode
  Registers at Call:  CS and SS must equal values as of return from INLINEPM.
  Return Registers:  Segment registers are restored to values existing as of
  former call to INLINEPM.  Real mode receives other registers, except status
  flags, at values as of call.
  Details:
     Since INLINERM will be called intersegment, caution must be taken that CS
  is loaded with CSEGSEL and not CSEG.  XLIB provides a far pointer to this
  procedure called INLINERMPTR which may be used to execute the call.
     INLINERM and CALL32 are the only 16-bit protected-mode procedures in XLIB.
  They are also the only protected-mode procedures having far returns.






                                        16






  CALL32 (Call 32-bit Protected-Mode)
  Purpose:  Call a 32-bit protected-mode near procedure in segment TSEG from 16-
  bit protected-mode.
  CPU Mode:  16-bit protected mode
  Registers at Call:  SS:ESP =  32-bit protected-mode target offset.
  Return Registers:  All registers, including status flags, are returned with
  values existing as of the 32-bit RET instruction.
  Details:
     CALL32 is a far procedure; therefore, caution must be taken that calls to
  CALL32 load CS with CSEGSEL instead of CSEG.  XLIB provides a far pointer to
  this procedure in DSEG called CALL32PTR which may be used to execute the call.
     CALL32 and INLINERM are the only 16-bit protected-mode procedures in XLIB.
  They are also the only protected-mode procedures having far returns.
     This procedure does not alter the state of OFLAGS.











































                                        17






                             6. Interrupt Management


       Interrupt management is the most complicated task performed by XLIB.
  Accordingly, this chapter is the most difficult section of the user's manual.
  In general, this chapter may be ignored for programs which do not install
  interrupt handlers, do not require hot key detection, and do not use floating
  point operations.


  XLIB Interrupt Handlers


       XLIB handles nearly all interrupts occurring in protected mode by
  shifting to real mode and calling the currently installed real-mode interrupt
  handlers.  In all but three cases, XLIB uses inherited real-mode handlers.
  XLIB installs its own handlers only for the DOS interrupt (INT 21H), the
  keyboard interrupt (INT 9), and the FPU interrupt (INT 75H).
       The DOS interrupt handler (INT 21H) intercepts all DOS calls and
  determines if termination is requested (AH = 4CH).  If not, then the interrupt
  is immediately cascaded to DOS.  If so, then XLIB performs housecleaning
  before relaying the request to DOS.  Under DPMI, XLIB will restore all
  interrupt vectors and release all allocated descriptors.  The DPMI host
  automatically releases all allocated memory.  Under other configurations, XLIB
  will reset all real-mode interrupt vectors and release all allocated extended
  memory.
       INT 21H function 4CH may be executed in either real mode or protected
  mode.  DPMI hosts will expect this function to be executed from protected
  mode; consequently, XLIB will switch to protected mode before relaying the
  request to DPMI.  XLIB also installs a protected-mode handler for INT 21H
  under DPMI.  This is to ensure that XLIB will see the termination request
  before the DPMI host.
       The keyboard interrupt handler is intended to facilitate termination of
  protected-mode procedures with a keypress.  When a user-defined hot key is
  pressed, the keyboard interrupt handler will modify a flag variable.  This
  flag variable may then be polled periodically in the main thread of execution.
  The keyboard interrupt handler is a real-mode routine.
       The inconvenience of having to poll the flag variable is unfortunately
  necessary.  It is not generally safe to terminate within a hardware interrupt
  handler, particularly in protected-mode environments.  A hardware interrupt
  generated by a keypress may have interrupted system software in the middle of
  a system maintenance operation.  Termination in such cases would likely leave
  the system in an irregular and potentially unstable state.
       Matters are further complicated in most protected-mode environments.  For
  example, a DPMI host will trap all hardware interrupts before cascading them
  to interrupt handlers.  If control is not returned to the host with the IRET
  instruction, then the host will be left in an irregular state.  Moreover, the
  trapping procedure will likely switch stacks before relaying the interrupt to
  the handler; consequently, the handler cannot determine the final return
  address and therefore cannot change this address to a termination procedure.
  These complications will nearly always occur when hardware interrupts are
  virtualized.  Virtual 8086 mode interrupts will almost certainly be
  virtualized in either VCPI-based or DPMI-based environments.




                                        18






       When a key is pressed, the keyboard interrupt handler will examine the
  key to determine if it is the hot key.  If not, then the interrupt is cascaded
  to the inherited real-mode handler.  If so, then a hot key flag is recorded to
  a DWORD whose linear address is recorded at CCODEPTR (condition code pointer).
  The hot key is not cascaded.  CCODEPTR is a public DWORD in DSEG.  The hot key
  flag is listed among XLIB error codes in Appendix B.
       CCODEPTR initially contains the linear address to public DWORD location
  CCODE which is in DSEG.  Therefore, the hot key flag would be written to CCODE
  by default.  CCODEPTR may be changed by the user; however, it must point to an
  address in conventional memory.
       The hot key specification is stored in DSEG at a public WORD location
  called HOTKEY.  The lower byte of HOTKEY contains the scan code of the hot key
  while the upper byte specifies the state of the shift keys.  Bit 8 specifies
  the state of SHIFT; bit 9 specifies CTRL, and bit 10 specifies ALT.  All other
  bits are ignored.  Set bits require that the designated shift key be pressed.
  The default setting for HOTKEY is zero.  This setting disables hot key
  detection since no key has a zero scan code.
       The XLIB interrupt handler for FPU exceptions performs three major
  functions upon the occurrence of any FPU exception that is unmasked in the FPU
  control word.  First, an error code is loaded to EAX and is also recorded at
  the linear address in CCODEPTR.  Next, the FPU is initialized with FNINIT (the
  FPU control word is preserved).  Third, control is transferred to EXITPM to
  return to real mode.  The high word stored in EAX and in the condition code
  will be the FPU status word.  This word may be examined to determine the
  nature of the exception.  The FPU interrupt handler is a real-mode routine.
       The response of the FPU to exception conditions is largely determined by
  the settings in the FPU control word.  If FPU save/restore is enabled, then
  the FPU control word will be set to FPUCW upon execution of CALLPM/ENTERPM.
  The default value for FPUCW is 0332H.  This sets rounding control to nearest,
  precision control to 64 bits, and unmasks exceptions for overflow, zero
  divide, and invalid operations.  Exceptions for underflow, precision, and
  denormalized operations are masked, and are therefore handled internally by
  the FPU.  FPUCW may be modified by the user.
       As explained above, the machine may be left in an unstable state after a
  program has been terminated from within a hardware interrupt handler.  This
  can also be the case for the FPU interrupt handler.  However, it will be safe
  to continue execution after FPU exceptions under clean configurations.  This
  follows because interrupts are not virtualized and because the exception will
  never be generated in the operating system (DOS does not use the FPU).  Nor
  should there be any problem with continuing execution after an exception in
  protected-mode under VCPI.  This follows since protected-mode interrupts
  cannot be virtualized under VCPI.  Exceptions occurring in virtual 8086 mode
  or under DPMI protected mode may however leave the machine in an irregular
  state.  Reboot may be necessary in these cases.
       All tested DPMI hosts appear to be restored to normal state by execution
  of INT 21H function 4CH (DOS termination).  However, the DPMI specifications
  offer no guarantees to this approach.  FPU exceptions in virtual 8086 mode are
  generally no problem in single-task environments; however, they will
  frequently prove problematic under a multitasker such as DESQview.
       Bit 0 of OFLAGS is used by XLIB to simultaneously enable or disable all
  of its own hardware interrupt handlers.  Setting the bit enables the handlers.
  XLIB sets this bit upon calls to CALLPM/ENTERPM and clears the bit upon
  return.  All interrupts are immediately cascaded to the inherited real-mode
  handlers when the bit is clear.  Therefore, FPU exceptions are handled by XLIB



                                        19






  only after calls to CALLPM/ENTERPM.  Accordingly, hot key detection is enabled
  only after calls to CALLPM/ENTERPM.  The user may set the bit under other
  circumstances; however, XLIB will not be able to properly handle FPU
  exceptions in these cases.  The bit should be set by the user only when hot
  key detection is desired and when it is certain that the FPU exception handler
  will not be invoked.
       The FPU exception handler may be permanently disabled by setting bit 1 in
  OFLAGS.  If this bit is set, then the FPU interrupt handler simply cascades
  the interrupt to the inherited real-mode handler.  XLIB will set the bit
  during initialization if an FPU is not present; it is otherwise cleared.
       Real-mode software interrupts which receive or return values in segment
  registers cannot be used within protected mode because the deflection routine
  will restore selectors to segment registers upon completion of the interrupt.
  To use such software interrupts, one must switch to real mode through CALLRM;
  issue the interrupt, and then transfer the segment registers to other
  registers or to memory before returning to protected mode.
       Certain software interrupts use status flags for return flags, typically
  to signal error conditions.  This is particularly the case for DOS interrupts.
  The deflection routine will pass these alterations to the code which issued
  the interrupt.


  Installation of Interrupt Handlers


       The user may install real-mode interrupt handlers in usual fashion.  Such
  handlers will also receive interrupts occurring in protected mode because
  either XLIB or the DPMI host will deflect all protected-mode interrupts.  If
  XLIB deflects the interrupt, then the handler will receive SS = DSEG with ESP
  set to 100H free bytes.  Stack sizes under DPMI will depend upon the host, but
  must contain a minimum of 200H free bytes to meet DPMI specifications.
       The DOS routines to get and set interrupt vectors (INT 21H functions 35H
  and 25H) receive and return values through segment registers; consequently,
  they cannot be used in protected mode.  Instead, use the XLIB procedures
  PMGETRMIV and PMSETRMIV (protected mode - get/set real-mode interrupt vector).
       The user may install a protected-mode interrupt handler from real mode by
  calling SETPMIV (set protected-mode interrupt vector).  The current protected-
  mode interrupt vector may be obtained by calling GETPMIV.
       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 the absence of
  DPMI.  That is, real-mode interrupts are never deflected to protected-mode
  handlers 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.  Therefore the protected-mode handler
  always receives the interrupt first.  If the handler cascades the interrupt,
  then the real-mode handler will receive it next.  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 typically deflect
  the interrupts to the real-mode handlers.



                                        20






       If the programmer wishes to install a protected-mode interrupt handler
  for a hardware interrupt or for INT 1CH, INT 23H, or INT 24H, then
  consideration must be given to the fact that treatment of these interrupts
  will differ under different protected-mode configurations.  As noted above,
  the DPMI host will always send these interrupts to the protected-mode handler
  regardless of the CPU mode in which the interrupt occurred.  If DPMI is not
  installed, then protected-mode handlers receive control only under protected-
  mode interrupts.  Therefore, if the protected-mode handler is to receive real-
  mode interrupts under such configurations, the programmer must install a real-
  mode handler to perform the deflection.
       XLIB includes a procedure called DEFLECTPM which can be used within a
  real-mode interrupt handler to deflect control to a protected-mode handler.
  DEFLECTPM functions only under VCPI and XLIB mode switching.  If DPMI is
  installed, then the procedure returns with no action.  The intent of this
  procedure is to enable simulation of DPMI treatment of hardware interrupts,
  INT 1CH, INT 23H, and INT 24H.
       Observe that if the real-mode handler deflects to the protected-mode
  handler, then the latter should not cascade the interrupt since an infinite
  loop would result.  This follows because the initial protected-mode handler
  deflects to the real-mode handler.
       Were one to use DEFLECTPM in a real-mode handler for the interrupts named
  above, then the protected-mode handler will receive all interrupts regardless
  of the protected-mode configuration.  This occurs naturally under DPMI.
  DEFLECTPM ensures that it will occur under other configurations.  Observe that
  under DPMI, the real-mode handler will never be executed.
       It is sometimes important that interrupt handlers execute in shortest
  possible CPU time.  This would typically be the case for handlers of the
  communication ports.  Since mode switching is time consuming, such handlers
  should be installed for the CPU mode which is expected to receive the most
  interrupts.
       If DPMI is installed, then it is possible for multiple clients to operate
  in a single virtual machine.  In such cases, DPMI will always send hardware
  interrupts to the primary client (the most recently installed client in the
  virtual machine).
       Under DPMI, all protected-mode handlers for 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.  Other protected-mode interrupts do not affect the
  interrupt flag.
       All real-mode interrupt handlers will receive control with interrupts
  disabled regardless of the protected-mode configuration.  All protected-mode
  handlers will receive control with interrupts disabled under VCPI or XLIB mode
  switching.  However, if DPMI is installed, then protected-mode software
  interrupts apart from 0-7 will receive the virtual interrupt flag at its value
  as of the INT instruction.  That is, DPMI does not alter the interrupt flag in
  these cases.
       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 are remapped in
  some operating environments, typically to facilitate exception handling.  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.



                                        21






       DESQview does remap hardware interrupts; however, its interrupt handlers
  for the new locations generally transfer control to the addresses at the
  conventional vectors.  DESQview must be started with a command-line switch if
  it is to accommodate certain hardware interrupts.  In particular, the FPU
  interrupt will not function properly under DESQview unless DESQview is started
  with DV /HW:75:C.


  Detailed Specifications


  PMGETRMIV (Protected Mode - Get Real-Mode Interrupt Vector)
  Purpose:  Retrieve address of real-mode interrupt handler.
  CPU Mode:  Protected
  Registers at Call:  AL = interrupt number.
  Return Registers:  Handler address returned in CX:DX.
  Details:  The DOS routine for this purpose (INT 21H function 35H) is not
  useful because it returns a value in ES.

  PMSETRMIV (Protected Mode - Set Real-Mode Interrupt Vector)
  Purpose:  Set address of real-mode interrupt handler.
  CPU Mode:  Protected
  Registers at Call:  AL = interrupt number, CX:DX = address of handler.
  Return Registers:  None
  Details:
     The DOS routine for this purpose (INT 21H function 25H) is not useful
  because it requires an argument in DS.
     Real-mode interrupt handlers will also be called when interrupts occur in
  protected mode provided that the protected-mode interrupt handler cascades the
  interrupt.  The default protected-mode handlers do in fact cascade all
  interrupts.
     XLIB never disables handlers installed by this procedure.

  GETPMIV (Get Protected-Mode Interrupt Vector)
  Purpose:  Retrieve address of protected-mode interrupt handler from interrupt
  descriptor table.
  CPU Mode:  Real
  Registers at Call:  AL = interrupt number.
  Return Registers:  Handler address returned in CX:EDX (CX is a selector).
  Details:  This routine does not return addresses of CPU exception handlers
  under DPMI.  Use DPMI functions directly for this purpose.

  SETPMIV (Set Protected-Mode Interrupt Vector)
  Purpose:  Set address of protected-mode interrupt handler in interrupt
  descriptor table.
  CPU Mode:  Real
  Registers at Call:  AL = interrupt number.  Handler address in CX:EDX (CX is a
  selector).
  Return Registers:  EAX = 0 if successful.  EAX = error code if unsuccessful.
  AX = XLIB error code.  If DPMI is installed then the high word of EAX will
  contain a DPMI 1.0 error code (if provided by host).






                                        22






  Details:
     XLIB never disables handlers installed by this procedure.
     Protected-mode interrupt handlers never receive interrupts occurring in
  real mode unless DPMI is active.  Under DPMI all hardware interrupts (IRQs 0-
  15) and software interrupts 1CH, 23H, and 24H are deflected from real mode to
  the installed protected-mode handler.  The protected-mode handler therefore
  receives control of the interrupt first.  It may cascade the interrupt if so
  desired, in which event, the real-mode handler receives the interrupt next. If
  no protected-mode handler has been installed, then DPMI generally deflects the
  interrupt to the real-mode handler.
     All protected-mode handlers will receive control with interrupts disabled
  unless DPMI is installed.  Under DPMI, protected-mode software interrupts
  apart from 0-7 do not alter the state of the virtual interrupt flag.
     Protected-mode handlers under DPMI for hardware interrupts and software
  interrupts 0-7 should execute STI before IRET to ensure that the virtual
  interrupt flag is enabled.
     If multiple DPMI clients are running in the same virtual machine, then the
  primary client (most recently installed client) always receives hardware
  interrupts.
     If DPMI is installed, then protected-mode interrupt vectors should be reset
  to original values before termination.
     This routine should not be used to install CPU exception handlers under
  DPMI.  DPMI functions should be used for this purpose.

  PMGETPMIV (Protected Mode - Get Protected-Mode Interrupt Vector)
  Purpose:  Retrieve address of protected-mode interrupt handler from interrupt
  descriptor table.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of GETPMIV.  See GETPMIV
  for specifications.

  PMSETPMIV (Protected Mode - Set Protected-Mode Interrupt Vector)
  Purpose:  Set address of protected-mode interrupt handler in interrupt
  descriptor table.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of SETPMIV.  See SETPMIV
  for specifications.

  DEFLECTPM (Deflect to Protected-Mode)
  Purpose:  Call a protected-mode interrupt handler.
  CPU Mode:  Real
  Registers at Call:  SS:ESP = interrupt number (2 bytes)
  Return Registers:  All registers except segment registers and ESP are returned
  at values as of the protected-mode IRET instruction.
  Details:
     This procedure can be used only under VCPI and XLIB mode switching.  It
  returns with no action under DPMI.  The routine is intended to simulate DPMI
  treatment of hardware interrupts, INT 1CH, INT 23H, and INT24H.  The routine
  may be called from a real-mode interrupt handler to deflect the interrupt to
  the protected-mode handler.
     The protected-mode handler should not cascade the interrupt; otherwise, an
  infinite loop will result.





                                        23






                               7. Memory Management


       XLIB supplies memory management procedures for both real and protected
  modes.  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.  PMFREEDOSMEM can also be used
  to find the amount of available DOS memory.
       The real-mode extended memory management procedures are GETMEM, FREEMEM,
  and RESETMEM.  GETMEM is used to allocate a block of extended memory.  FREEMEM
  may then be used to release the block.  RESETMEM releases all previously
  allocated blocks at once.  GETMEM may also be used to find the amount of
  available extended memory.
       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.
       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).
       Under DPMI and VCPI, the CPU will typically be operating in page mode.
  Under this mode of operation, memory may be remapped such that logical
  addresses are not equal to physical addresses.  Addresses specified in the
  instruction code are logical addresses.  The physical addresses are the
  locations in memory which are actually accessed.  Typically, a programmer need
  not be concerned with the difference between these two types of addresses.
  However, the difference must be recognized when working with input/output
  devices which map to certain physical location in memory.  XLIB includes
  routines called MAPIO and PMMAPIO which assign a logical addresses to a
  specified physical addresses.  The physical addresses can then be accessed via
  the assigned logical addresses.


  Detailed Specifications


  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.  A block handle is returned in EBX.  The number of
  allocated bytes is returned in ECX.  The linear address of allocated block is
  returned in EDX.
     EAX = error code if unsuccessful.  AX = XLIB error code.  The high word of
  EAX (EAH) will be set to a DOS error code.  If DPMI is active, then EAH will
  be a DPMI error code (codes are supplied by DPMI .9 and up).



                                        24






  Details:
     The block will always be paragraph aligned and will have size equal to an
  integer multiple of 16.
     The location in free memory from which the block is allocated will depend
  upon the allocation strategy in force as of call (see INT 21H function 58H).
     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.  The high word of EAX (EAH) will be a DOS error code.  If DPMI is
  active, then EAH will equal a DPMI error code (codes are 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.  A block handle is returned in EBX.  The number of
  allocated bytes is returned in ECX.  The logical address of allocated block is
  returned in EDX.
     EAX = error code if unsuccessful.  AX = XLIB error code.  If DPMI is
  active, then the high word of EAX (EAH) will be a DPMI 1.0 error code (if
  provided by host).  If XMS is active, then EAH = XMS error code.
  Details:
     The page size for extended memory allocations is contained in PAGESIZE.
  PAGESIZE is a DWORD in DSEG and should be read after initialization.  The
  blocks will have addresses that are PAGESIZE aligned and will have sizes equal
  to an integer multiple of PAGESIZE.  PAGESIZE will equal:  1024 for XMS, 4096
  for VCPI, 4096 for most DPMI hosts, and 16 in the absence of a memory manager.
     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.
     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 are preserved).  This call can also return
  with an error condition in EAX.








                                        25






  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 a
  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 a
  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.
     If DPMI is not installed, then RESETMEM will be called upon execution of
  INT 21H function 4C (DOS termination).  DPMI hosts reset extended memory
  automatically.

  PMGETMEM  (Protected Mode - Get Memory)
  Purpose:  Allocate extended memory block.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of GETMEM.  See GETMEM
  for specifications.

  PMFREEMEM  (Protected Mode - Free Memory)
  Purpose:  Free previously allocated extended memory block.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of FREEMEM.  See FREEMEM
  for specifications.

  PMRESETMEM (Protected Mode - Reset Memory)
  Purpose:  Free all previously allocated extended memory.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of RESETMEM.  See
  RESETMEM for specifications.














                                        26






  MAPIO (Map Input/Output Device)
  Purpose:  Create a logical address mapping for an input/output device which
  maps to a fixed physical memory address.
  CPU Mode:  Real
  Registers at Call:  EDX = first physical address to be mapped.  EAX = size of
  physical address block.
  Return Registers:
     EAX = 0 if successful, in which event, EDX = the logical address for
  accessing the physical memory.
     EAX = error code if unsuccessful.  AX = XLIB error code.  If DPMI is
  active, then the high word of EAX (EAH) will be a DPMI 1.0 error code (if
  provided by host).  If XMS is active, then EAH = XMS error code.
  Details:
     DPMI will not allow mapping of physical addresses within the first
  megabyte; however, such mappings are allowed under other configurations.
     Logical addresses will always equal physical addresses in the absence of
  VCPI and DPMI because the processor will not be operating in page mode.  In
  such cases, MAPIO simply performs validity checks on EDX and EAX.
     MAPIO will automatically allocate page tables as needed under VCPI.
  RESETMEM will release such tables.
     Memory-mapped input/output devices are not typically mapped within the
  range of available memory since this would leave the possibility of confusing
  such addresses with ordinary memory.  Instead, such devices are mapped beyond
  the highest address that would otherwise be available.

  PMMAPIO (Protected Mode - Map Input/Output Device)
  Purpose:  Create a logical address mapping for an input/output device which
  maps to a fixed physical memory address.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of MAPIO.  See MAPIO for
  specifications.


























                                        27






                                8. File Management


       XLIB file management procedures are low-level routines with powerful
  capabilities.  These routines can load files to extended memory or save
  extended memory to files.  They can read and write files either sequentially
  or randomly.
       All XLIB file management routines will receive and return values in a
  contiguous block of memory called a "file control block" (not to be confused
  with DOS file control blocks).  The file control block must be located in
  conventional memory and must have the form presented in Table 5.


  Table 5:  XLIB File Control Block Structure
  _____________________________________________________________________________
  Field Name   Field Type        Field Description
  ----------   ----------        -----------------
  CONDCODE     DWORD             Condition code from file operation
  FNAME        BYTE[68]          File path and name (zero terminated string)
  FHANDLE      WORD              File handle assigned by DOS
  FPTRMODE     WORD              File pointer mode
  FPTR         DWORD             File pointer
  BLKADR       DWORD             Memory source/destination address
  BLKSIZE      DWORD             Size of transfer block in bytes
  BUFADR       DWORD             Buffer address (conventional memory address)
  BUFSIZE      WORD              Buffer size in bytes
  CONTROL      WORD              Control word
  _____________________________________________________________________________


       CONDCODE is used to return error codes.
       FNAME is a zero-terminated ASCII string defining the file path and name.
  There cannot be more than 67 characters in this string, excluding the
  termination character.
       BLKADR and BLKSIZE define the source/destination memory block for the
  transfer.  This block may be in either conventional or extended memory.
  BLKADR is a linear address.
       XLIB uses DOS to access the disk.  DOS cannot read or write to extended
  memory; consequently, a conventional memory buffer must be set up for the DOS
  transfers.  File management routines shift to protected mode to perform
  transfers between the buffer and the source/destination memory.  BUFADR and
  BUFSIZE define the conventional memory buffer.  BUFADR is a linear address.
       For fastest transfers, the memory block and the buffer should be DWORD
  aligned and should have sizes equal to an integer multiple of four.
       FPTR and FPTRMODE specify the file pointer setting to be used before
  transfers to or from the disk.  FPTRMODE specifies how FPTR is to be
  interpreted.  The following values are valid for FPTRMODE:


  FPTRMODE    FPTR Interpretation
  0           Unsigned offset from the beginning of the file
  1           Signed offset from the current file pointer
  2           Signed offset from the end of the file
  3           FPTR is ignored.  Use current file pointer (sequential mode)



                                        28






       CONTROL is not used in the present version of XLIB.  Set all bits in
  CONTROL to zero.
       In assembly language or C, the file control block would typically be
  defined by a structure.  In BASIC, the file control block can be defined with
  a user defined type.
       Values are transferred to and from all file routines in EAX and in the
  file control block.  All routines should be called with the linear address of
  the file control block in EAX.  All routines return with two copies of the
  error code - one in EAX and one in the condition code of the file control
  block.  A zero error code indicates successful execution.
       Since these routines perform disk operations, special precautions should
  be taken to ensure that parameters in the file control block are properly
  defined before performing calls.  In particular, one should always make sure
  that the source/destination memory block and the conventional memory buffer
  are properly defined.  A safe rule is to simply set the buffer size to zero
  because this forces XLIB to supply a buffer when opening or creating the file.


  Detailed Specifications


  XCREATE (Create File)
  Purpose:  Create and open a new file of specified name in specified directory.
  CPU Mode:  Real
  Registers at Call:  EAX = linear address of file control block.
  Control Block at Call:  FNAME = file path and name.
  Return Registers:  EAX = error code.  AX = XLIB error code.  If a DOS error
  occurred, then the high word of EAX will be set to the DOS error code.
  Control Block at Return:  CONDCODE = error code.  If CONDCODE = 0, then
  FHANDLE = file handle assigned by DOS.  If the procedure is called with
  BUFSIZE = 0, then XLIB will set BUFADR and BUFSIZE to its own internal buffer.
  Details:
     If the file already exists, then it will be truncated to zero length.
     The size and location of the internal buffer will depend upon how XLIB was
  initialized.  If DPMI is active, then the buffer will be slightly larger than
  2K; otherwise, the buffer will be slightly larger than 1K.  The linear address
  and size of the buffer may be obtained from FILEBUFADR (DWORD), and
  FILEBUFSIZE (WORD) in DSEG.
     Files created by this routine will be given both read and write access.
     This routine uses INT 21H function 3CH to create the file.

  XOPEN (Open File)
  Purpose:  Open existing file of specified name in specified directory.
  CPU Mode:  Real
  Registers at Call:  EAX = linear address of file control block.
  Control Block at Call:  FNAME = file path and name.
  Return Registers:  EAX = error code.  AX = XLIB error code.  If a DOS error
  occurred, then the high word of EAX will be set to the DOS error code.
  Control Block at Return:  CONDCODE = error code.  If CONDCODE = 0, then
  FHANDLE = file handle assigned by DOS.  If the procedure is called with
  BUFSIZE = 0, then XLIB will set BUFADR and BUFSIZE to its own internal buffer.






                                        29






  Details:
     The file is opened for both read and write access.
     The size and location of the internal buffer will depend upon how XLIB was
  initialized.  If DPMI is active, then the buffer will be slightly larger than
  2K; otherwise, the buffer will be slightly larger than 1K.  The linear address
  and size of the buffer may be obtained from FILEBUFADR (DWORD), and
  FILEBUFSIZE (WORD) in DSEG.
     This routine uses INT 21H function 3DH to open the file.

  XCLOSE (Close File)
  Purpose:  Close previously opened file.
  CPU Mode:  Real
  Registers at Call:  EAX = linear address of file control block.
  Control Block at Call:  FHANDLE = file handle.
  Return Registers:  EAX = error code.  AX = XLIB error code.  If a DOS error
  occurred, then the high word of EAX will be set to the DOS error code.
  Control Block at Return:  CONDCODE = error code.
  Details:  This routine uses INT 21H function 3EH to close the file.

  XSAVE (Save File)
  Purpose:  Create file with contents equal to specified memory block.
  CPU Mode:  Real
  Registers at Call:  EAX = linear address of file control block.
  Control Block at Call:  FNAME = file path and name.  BLKADR/BLKSIZE = address
  and size of memory block to provide file contents.  BUFADR/BUFSIZE = address
  and size of conventional memory buffer.
  Return Registers:  EAX = error code.  AX = XLIB error code.  If a DOS error
  occurred, then the high word of EAX will be set to the DOS error code.
  Control Block at Return:  CONDCODE = error code.
  Details:
     The file cannot already be open.  The file is both created and closed by
  this routine.
     This routine will replace any previously existing file named FNAME.
     BLKADR/BLKSIZE may define a conventional memory block provided that this
  block is not overlapped by BUFADR/BUFSIZE.
     If this routine is called with BUFSIZE = 0, then XLIB will automatically
  set BUFADR and BUFSIZE to its own internal buffer.
     This routine transfers the source memory to the file through the buffer.
  Transfers from buffer to disk are accomplished with INT 21H function 40H.

  XLOAD (Load File)
  Purpose:  Load file contents to specified memory block.
  CPU Mode:  Real
  Registers at Call:  EAX = linear address of file control block.
  Control Block at Call:  FNAME = file path and name.  BLKADR/BLKSIZE = address
  and size of memory block to receive file contents.  BUFADR/BUFSIZE = address
  and size of conventional memory buffer.
  Return Registers:  EAX = error code.  AX = XLIB error code.  If a DOS error
  occurred, then the high word of EAX will be set to the DOS error code.
  Control Block at Return:  CONDCODE = error code.  If CONDCODE = 0, then
  BLKSIZE = actual number of bytes transferred.






                                        30






  Details:
     The file cannot already be open.  The file is both opened and closed by
  this routine.
     The value of BLKSIZE as of call is interpreted as an upper limit on the
  number of bytes to transfer.  The entire file is loaded provided that it does
  not contain more than BLKSIZE bytes.
     BLKADR/BLKSIZE may define a conventional memory block provided that this
  block is not overlapped by BUFADR/BUFSIZE.
     If this routine is called with BUFSIZE = 0, then XLIB will automatically
  set BUFADR and BUFSIZE to its own internal buffer.
     This routine uses INT 21H function 3FH to transfer the disk contents to the
  buffer.  It then transfers the buffer contents to the destination memory.

  XWRITE (Write to File)
  Purpose:  Write specified memory block to specified location in open file.
  CPU Mode:  Real
  Registers at Call:  EAX = linear address of file control block.
  Control Block at Call:  FHANDLE = file handle.  FPTR/FPTRMODE = file pointer
  setting for beginning of transfer.  BLKADR/BLKSIZE = address and size of
  memory block to provide file contents.  BUFADR/BUFSIZE = address and size of
  conventional memory buffer.
  Return Registers:  EAX = error code.  AX = XLIB error code.  If a DOS error
  occurred, then the high word of EAX will be set to the DOS error code.
  Control Block at Return:  CONDCODE = error code.
  Details:
     The file must be opened with XOPEN or XCREATE before using this routine.
     BLKADR/BLKSIZE may define a conventional memory block provided that this
  block is not overlapped by BUFADR/BUFSIZE.
     This routine uses INT 21H function 42H to set the file pointer.  The source
  memory is then transferred through the buffer to disk.  Transfers from buffer
  to disk are accomplished with INT 21H function 40H.
     Sequential transfers should set FPTRMODE = 3 for fastest execution.

  XREAD (Read From File)
  Purpose:  Load specified memory block from specified location in open file.
  CPU Mode:  Real
  Registers at Call:  EAX = linear address of file control block.
  Control Block at Call:  FHANDLE = file handle.  FPTR/FPTRMODE = file pointer
  setting for beginning of transfer.  BLKADR/BLKSIZE = address and size of
  memory block to receive file contents.  BUFADR/BUFSIZE = address and size of
  conventional memory buffer.
  Return Registers:  EAX = error code.  AX = XLIB error code.  If a DOS error
  occurred, then the high word of EAX will be set to the DOS error code.
  Control Block at Return:  CONDCODE = error code.  If CONDCODE = 0, then
  BLKSIZE = actual number of bytes transferred.
  Details:
     The file must be opened with XOPEN or XCREATE before using this routine.
     BLKADR/BLKSIZE may define a conventional memory block provided that this
  block is not overlapped by BUFADR/BUFSIZE.
     This routine uses INT 21H function 42H to set the file pointer.  The file
  contents are then transferred to the destination memory through the buffer.
  The file contents are transferred to the buffer using INT 21H function 3FH.
     Sequential transfers should set FPTRMODE = 3 for fastest execution.




                                        31






  PMXCREATE (Protected Mode - Create File)
  Purpose:  Create and open a new file of specified name in specified directory.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of XCREATE.  See XCREATE
  for details.

  PMXOPEN (Protected Mode - Open File)
  Purpose:  Open an existing file of specified name in specified directory.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of XOPEN.  See XOPEN for
  details.

  PMXCLOSE (Protected Mode - Close File)
  Purpose:  Close previously opened file.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of XCLOSE.  See XCLOSE
  for details.

  PMXSAVE (Protected Mode - Save File)
  Purpose:  Create file with contents equal to specified memory block.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of XSAVE.  See XSAVE for
  details.

  PMXLOAD (Protected Mode - Load File)
  Purpose:  Load file contents to specified memory block.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of XLOAD.  See XLOAD for
  details.

  PMXWRITE (Protected Mode - Write to File)
  Purpose:  Write specified memory block to specified location in open file.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of XWRITE.  See XWRITE
  for details.

  PMXREAD (Protected Mode - Read From File)
  Purpose:  Load specified memory block from specified location in open file.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of XREAD.  See XREAD for
  details.
















                                        32






                             9. Descriptor Management


       All selectors in Table 1 up to DGROUPSEL are used by XLIB procedures;
  consequently, the corresponding descriptors should never be changed.  However,
  descriptors for the other selectors may be modified.  XLIB includes a
  procedure called SETDESC (set descriptor) to facilitate such modifications.  A
  second routine called PMSETDESC is the protected-mode version of SETDESC.
       Descriptors corresponding to the inline selectors should not be changed
  in programs which also use the inline mode-switch procedures.


  Detailed Specifications


  SETDESC (Set Descriptor)
  Purpose:  Change a descriptor in the local descriptor table.
  CPU Mode:  Real
  Registers at Call:  BX = selector.  EDX:EAX = the new descriptor.
  Return Registers:  EAX = error code.  AX = XLIB error code.  If DPMI is
  installed, then the high word of EAX will equal a DPMI 1.0 error code (if
  provided by host).  EDX may be returned with some modifications to the access
  rights bits.
  Details:
     The access rights bits in EDX will be edited before installation of the
  descriptor.  In particular:  The application bit will be set to indicate an
  application segment (rather than a system segment).  Reserved bits will be
  given proper settings.  The descriptor privilege level will be set to the
  appropriate value.  If the descriptor corresponds to a code segment, then the
  descriptor will also be marked as readable and nonconforming.
     Segment registers which are loaded with the old value of the descriptor
  will not necessarily be reloaded when the descriptor is changed.

  PMSETDESC (Protected Mode - Set Descriptor)
  Purpose:  Change a descriptor in the local descriptor table.
  CPU Mode:  Protected
  Details:  This routine is the protected-mode version of SETDESC.  See SETDESC
  for details.



















                                        33






                 10. 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 methodology 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 the BASIC caller.
       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 E.  An example for Borland C is included in the files EXAMP3B.C and
  EXAMP3B.ASM.


  Example 3:  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







                                        34






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

  ;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
                 XOR            EDX,EDX
                 MOV            AX,WORD PTR SEGADR[0]
                 MOV            DX,WORD PTR SEGADR[2]
                 SHL            EDX,4          ;Calculate linear address
                 ADD            EDX,EAX
                 MOV            AX,DX
                 SHR            EDX,16         ;Return linear address in DX:AX
                 RET
  LINADR         ENDP

  ;Structure defining control block for SUMARRAY.
  ARRAYDATA      STRUCT
    CONDCODE     DWORD          0              ;Condition code
    N            DWORD          0              ;Number of elements to sum
    ADDRESS      DWORD          0              ;Address of first element
    SUM          DWORD          0              ;Sum of array elements
  ARRAYDATA      ENDS

  ;Real-mode interface to SUMARRAY32.  Segment address of control block having
  ;structure ARRAYDATA should be on the stack.
  SUMARRAY       PROC FAR PUBLIC,
                 CBSEGADR:DWORD                ;Control block segment address
                 PUSH           DS
                 PUSHW          DSEG
                 POP            DS
                 XOR            EAX,EAX        ;Clear high words
                 XOR            EDX,EDX
                 MOV            AX,WORD PTR CBSEGADR[2]
                 MOV            DX,WORD PTR CBSEGADR[0]
                 SHL            EAX,4          ;Calculate linear address
                 ADD            EAX,EDX
                 MOV            CCODEPTR,EAX   ;Reset condition code address
                 POP            DS             ;Pop calling DS
                 PUSHD          OFFSET SUMARRAY32
                 CALL           ENTERPM        ;Execute SUMARRAY32 in protected
                 RET
  SUMARRAY       ENDP

  CSEG           ENDS










                                        35






  TSEG           SEGMENT PARA PUBLIC USE32 'CODE'
                 ASSUME CS:TSEG, SS:TSEG, DS:TSEG, ES:TSEG, FS:DSEG, GS:DGROUP

  ;Sum the elements of a single precision array.  Array parameters are stored
  ;in a control block having structure of ARRAYDATA.  The linear address of the
  ;control block is stored at CCODEPTR.  An error code of -1 is returned in the
  ;condition code of the control block if the number of array elements is zero.
  ;XLIB places an error code in the control block if an FPU exception occurs
  ;while calculating the sum.  This error code will have the FPU status word in
  ;the high word and the XLIB FPU error code in the low word.  Observe that this
  ;routine will be called with DS = FLATDSEL (flat-model data descriptor) and
  ;FS = DSEGSEL (DSEG data descriptor).
  SUMARRAY32     PROC NEAR
                 MOV            EBX,FS:CCODEPTR               ;Get control block
                 MOV            EDX,ARRAYDATA.ADDRESS[EBX]    ;Get array address
                 MOV            ESI,ARRAYDATA.N[EBX]          ;Get N
                 SUB            ESI,1
                 JB             NODATA                        ;Error:  N = 0
                 FLDZ                                         ;Initialize sum
  SUMLOOP:       FADD           DWORD PTR [EDX+4*ESI]
                 SUB            ESI,1
                 JAE            SUMLOOP
                 FSTP           ARRAYDATA.SUM[EBX]            ;Save sum
                 RET
  NODATA:        MOV            ARRAYDATA.CONDCODE[EBX],-1    ;Record error code
                 RET
  SUMARRAY32     ENDP

  TSEG           ENDS
                 END


                              +++++++++++++++++++++
                              + BASIC MAIN MODULE +
                              +++++++++++++++++++++


  'The following Microsoft BASIC 7.0 program should be linked with the above
  'library.  The BASIC program first initializes XLIB.  Next, it creates a
  'single precision array.  A control block for SUMARRAY is then constructed
  'and the call to SUMARRAY is executed.  Finally, the condition code in the
  'control block is inspected and results are printed.

  DEFINT A-Z

  'Declare XLIB procedures
  DECLARE FUNCTION XLIBMEMREQ& ()
  DECLARE FUNCTION INITXLIB& ()
  DECLARE FUNCTION XLIBCONFIG% ()

  'Declare procedures in the library linked with XLIB
  DECLARE FUNCTION LINADR& (SEG VARIABLE AS ANY)
  DECLARE SUB SUMARRAY (SEG VARIABLE AS ANY)




                                        36






  'Structure for the control block
  TYPE ARRAYDATA
    CONDCODE AS LONG      'Location to receive any error codes
    N AS LONG             'Number of elements to be summed
    ADDRESS AS LONG       'Linear address of the array
    SUM AS SINGLE         'Location for array sum
  END TYPE

  'Check XLIBCONFIG to see if XLIB has already been initialized.  If not then
  'call XLIBMEMREQ to find amount of conventional memory needed by XLIB and
  'release at least this amount with the BASIC SETMEM function.  XLIBMEMREQ
  'returns with sign bit of DX set if an error occurred.  The error is then
  'identified by AX.  XLIB will not be terminated upon completion of this
  'program in the Microsoft QBX environment; therefore, initialization is
  'required only once within the environment.
  IF XLIBCONFIG = 0 THEN
    TEMP& = XLIBMEMREQ
    IF TEMP& >= 0& THEN
      IF TEMP& > 0 THEN TEMP& = SETMEM(-TEMP& - 16&)
      TEMP& = INITXLIB                 'INITXLIB error code returned in TEMP&
    ELSE
      TEMP& = TEMP& AND &H7FFFFFFF     'Mask sign bit to leave error code only
    END IF
    IF TEMP& THEN
      PRINT "Library initialization error:  "; HEX$(TEMP&)
      END
    END IF
  END IF

  DIM A(100) AS SINGLE
  DIM AD AS ARRAYDATA

  FOR I = 0 TO 100            'Assign numbers to array
    A(I) = I
  NEXT I

  AD.CONDCODE = 0&            'Clear the error code
  AD.N = 50&                  'Sum first 50 elements
  AD.ADDRESS = LINADR(A(0))   'Calculate and record linear address of A(0)

  CALL SUMARRAY(AD)

  IF AD.CONDCODE THEN
    PRINT "Error: ";HEX$(AD.CONDCODE)
  ELSE
    PRINT "Sum: ";AD.SUM      'Should equal 1225
  ENDIF

  END
  _____________________________________________________________________________







                                        37






                   Appendix A: Description of XLIB Public Data


       The following is a summary of most public symbols for XLIB data.  These
  symbols pertain to segment DSEG except where otherwise noted.  This summary
  excludes many of the symbols presented in tables one through four.  All XLIB
  symbols conform to the PASCAL naming convention.

  Symbol:  CALL32PTR (CALL32 Pointer)
  Symbol Type:  DWORD
  Default Setting:  Far 16-bit protected-mode address of CALL32 procedure
  Description:  This location is a pointer to the CALL32 procedure and is
  included to facilitate intersegment calls.  The contents of the location
  should not be changed.

  Symbols:  CCODEPTR/CCODE (Condition Code Pointer/Condition Code)
  Symbol Types:  DWORD/DWORD
  Default Settings:  CCODEPTR = linear address of CCODE.  CCODE = 0.
  Descriptions:  XLIB interrupt handlers will place flags in the condition code
  to signal the occurrence of the interrupt.  Flags are placed for FPU
  exceptions and hot key presses.  CCODEPTR initially contains the linear
  address of CCODE.  CCODEPTR may be changed by the user, but must point to a
  DWORD in conventional memory.  The user is responsible for initializing the
  condition code.

  Symbol:  CSDSEGSEL (Code Segment Copy of DSEGSEL)
  Symbol Type:  WORD
  Default Setting:  Varies with operating environment
  Description:  This is a WORD in TSEG containing the value of the DSEG
  selector.  Since XLIB selector values are not constant, they must be read from
  memory locations.  Such locations are placed in segment DSEG (see Table 1);
  however, one must know the DSEG selector to read these locations.  Therefore,
  a copy of the DSEG selector is placed in the code segment where it can always
  be found.

  Symbols:  CSEGVAL, TSEGVAL, DSEGVAL, DGROUPVAL (Segment Values)
  Symbol Types:  WORD
  Default Settings:  CSEG, TSEG, DSEG, DGROUP
  Descriptions:  These are memory locations initialized to the respective
  segment values.  Code in TSEG should not contain segment constants since DOS
  may not be able to handle them in relocation edits.  Read these locations to
  get segment values.  User segments should be handled the same way.  These
  locations should not be changed.

  Symbols:  FILEBUFADR/FILEBUFSIZE (File Buffer Specifications)
  Symbol Types:  DWORD/WORD
  Default Settings:  Varies with operating environment
  Descriptions:  FILEBUFADR contains the linear address of the internal file
  buffer in XLIB.  FILEBUFSIZE contains the size of the buffer in bytes.  This
  buffer is used only by the file management routines.  The size and location of
  the buffer will depend upon the operating environment.  If DPMI is active,
  then the buffer will be slightly larger than 2K; it is otherwise slightly
  larger than 1K.  These location should be read only after initialization.




                                        38






  Symbol:  FPUCW (Floating Point Unit Control Word)
  Symbol Type:  WORD
  Default Setting:  0332H
  Description:  FPUCW is optionally loaded to the FPU control word by CALLPM and
  ENTERPM.  The default sets rounding control to nearest, precision control to
  64 bits, and unmasks exceptions for overflow, zero divide, and invalid
  operations.  Exceptions for underflow, precision, and denormalized operations
  are masked, and are therefore handled internally by the FPU.  Set bit 2 of
  OFLAGS to enable FPU save/restore and load of FPUCW.

  Symbol:  HOTKEY (Hot Key)
  Symbol Type:  WORD
  Default Setting:  0H
  Description:  HOTKEY specifies the hot key for the keyboard interrupt handler.
  The low byte of HOTKEY specifies the scan code for the key.  The upper byte
  specifies the state of the shift keys.  Bit 8 specifies SHIFT; bit 9 specifies
  CTLR, and bit 10 specifies ALT.  Set bits mean that the designated key must be
  pressed.  All other bits are ignored.  When the hot key is pressed, the XLIB
  keyboard interrupt handler will record the hot key flag at the DWORD whose
  linear address is stored at CCODEPTR.  The default setting for HOTKEY is 0.
  This setting effectively disables hot key detection since no key has a zero
  scan code.

  Symbol:  IFLAGS (Initialization Flags)
  Symbol Type:  WORD
  Default Setting:  0200
  Description:  IFLAGS is used by INITXLIB to control the initialization
  process.  Bit 0 of IFLAGS determines DPMI/VCPI priority in the event that both
  interfaces are present.  If this bit is clear then DPMI will be installed in
  such cases.  The upper byte of IFLAGS determines the strategy to be used by
  INITXLIB if conventional memory is to be allocated.  The possible strategies
  are presented in Table 2.  The default causes XLIB to allocate from the
  highest available address in conventional memory.

  Symbol:  INLINERMPTR (INLINERM Pointer)
  Symbol Type:  DWORD
  Default Setting:  Far 16-bit protected-mode address of INLINERM procedure
  Description:  This location is a pointer to the INLINERM procedure and is
  included to facilitate intersegment calls.  The contents of the location
  should not be changed.

  Symbols:  IRQ0INTNO/IRQ8INTNO (IRQ X Interrupt Number)
  Symbol Types:  BYTE/BYTE
  Default Settings:  Varies with operating environment
  Descriptions:  Specifies the interrupt number assigned to IRQ X.  IRQs 0
  through 7 and IRQs 8 through 15 are assigned to contiguous interrupt numbers.
  These locations are valid only after call to INITXLIB.  Typically, IRQ 0 is
  assigned to interrupt 8, and IRQ 8 is assigned to interrupt 70H; however,
  these assignments may have been changed by system software.








                                        39






  Symbol:  OFLAGS (Operation Flags)
  Symbol Type:  WORD
  Default Setting:  Varies with operating environment
  Description:  OFLAGS controls post-initialization operation of XLIB.
     Setting bit 0 enables XLIB hardware interrupt handlers.  These handlers
  will continue to receive interrupts but will always cascade them when the bit
  is clear.  XLIB sets this bit only at calls to CALLPM and ENTERPM and then
  clears the bit upon return.  When the bit is clear, hot key detection is
  disabled, and the XLIB FPU interrupt handler is disabled.
     Setting bit 1 causes all FPU interrupts to be cascaded to the inherited
  real-mode interrupt handler.  This bit is initialized by INITXLIB.  It is set
  if no FPU is present; it is otherwise cleared.
     Setting bit 2 enables FPU save/restore in CALLPM and ENTERPM.  Setting this
  bit also causes load of FPUCW to the FPU control word.  The bit is clear by
  default.

  Symbol:  PAGESIZE (Page Size)
  Symbol Type:  DWORD
  Default Setting:  Varies with operating environment
  Description:  This memory location contains the minimum unit (in bytes) for
  extended memory allocation.  PAGESIZE is initialized by INITXLIB.  It will
  contain 4096 for VCPI, 1024 for XMS, and 16 for clean configurations.  Values
  can vary under DPMI but will typically equal 4096.  Extended memory requests
  are rounded up to the nearest integer multiple of PAGESIZE.  Extended memory
  blocks will be PAGESIZE aligned.

  Symbols:  PMDS, PMES, PMFS, PMGS (Protected-Mode Segments)
  Symbol Types:  WORD
  Default Settings:  FLATDSEL, TSEGDSEL, DSEGSEL, DGROUPSEL
  Descriptions:  These memory locations are loaded to data segment registers by
  CALLPM and ENTERPM before transferring control to the protected-mode target.
  These locations are respectively loaded to DS, ES, FS, and GS.  The contents
  of these locations may be changed to any legal selectors after the call to
  INITXLIB.

  Symbols:  RMDS, RMES (Real-Mode Segments)
  Symbol Types:  WORD
  Default Settings:  DGROUP, DSEG
  Descriptions:  These memory locations are loaded to data segment registers by
  CALLRM before transferring control to the real-mode target.  These locations
  are respectively loaded to DS and ES.  The contents of these locations may be
  changed if desired.















                                        40






                           Appendix B: XLIB Error Codes


       XLIB error codes are always returned in AX.  In many cases, the high word
  of EAX will be returned with specific information about the error, such as
  XMS, DPMI, or DOS error codes.
       Although error codes are not provided in the DPMI .9 specification, many
  DPMI .9 hosts do return DPMI 1.0 error codes.  DPMI 1.0 error codes may in
  fact be DOS error codes returned to the DPMI host by DOS.  If the sign bit
  (bit 15) of the error code is clear, then the error code was issued by DOS.


  Condition Code Flags
  01H     FPU exception
  02H     Hot key pressed

  General Errors
  10H     Illegal address
  11H     Unable to identify operating environment
  12H     DOS memory allocation failure
  13H     DOS memory release error
  14H     Failed to enable A20
  15H     Insufficient logical address space
  16H     Insufficient number of extended memory block handles
  17H     Bad extended memory block handle
  18H     Bad selector
  19H     Unable to create file
  1AH     Unable to open file
  1BH     Unable to read file
  1CH     Unable to write file
  1DH     Unable to set file pointer
  1EH     Unable to close file
  1FH     Disk full

  Errors Occurring Under DPMI (See Appendix C for codes returned by DPMI)
  20H     Protected mode initialization failure
  21H     Descriptor allocation error
  22H     Descriptor installation error
  23H     Unable to switch protected mode interrupt vector
  24H     Insufficient extended memory error
  25H     Extended memory allocation error
  26H     Extended memory release error
  27H     DPMI DOS memory allocation error
  28H     DPMI DOS memory release error
  29H     Unable to set descriptor base address
  2AH     DPMI physical address mapping error

  Errors Occurring Under XMS (See Appendix D for codes returned by XMS)
  30H     Unable to measure available extended memory
  31H     Insufficient extended memory error
  32H     Extended memory allocation error
  33H     Unable to lock extended memory
  34H     Unable to unlock extended memory
  35H     Extended memory release error



                                        41






  Errors Occurring Under VCPI
  40H     Error in determining protected mode entry point
  41H     Unable to determine physical address of DOS memory page
  42H     Unable to determine hardware interrupt mappings
  43H     Insufficient extended memory error
  44H     Unable to determine number of free extended memory pages
  45H     Extended memory allocation error
  46H     Extended memory release error

















































                                        42






                         Appendix C: DPMI 1.0 Error Codes


       DPMI 1.0 error codes may in fact be DOS error codes returned to the DPMI
  host by DOS.  If the sign bit (bit 15) of the error code is clear, then the
  error code was issued by DOS.


  Number   Explanation
  8001H    Unsupported function
  8002H    Invalid state for requested operation
  8003H    System integrity would be endangered
  8004H    Deadlock situation detected by host
  8005H    Serialization request cancelled
  8010H    Resource unavailable
  8011H    Host unable to allocate descriptor
  8012H    Linear memory unavailable
  8013H    Physical memory unavailable
  8014H    Backing store unavailable
  8015H    Callback specifications cannot be allocated
  8016H    Cannot allocate handle
  8017H    Lock count limits exceeded
  8018H    Resource owned exclusively by another client
  8019H    Resource already shared by another client
  8021H    Invalid value
  8022H    Invalid selector
  8023H    Invalid handle
  8024H    Invalid callback
  8025H    Invalid linear address
  8026H    Request not supported by hardware



























                                        43






                           Appendix D: XMS Error Codes


  Number   Explanation
  80H      Function not implemented
  81H      VDISK was detected
  82H      An A20 error occurred
  8EH      General driver error
  8FH      Unrecoverable driver error
  90H      HMA does not exist
  91H      HMA is already in use
  92H      Attempt to allocate less than HMAMIN of HMA
  93H      HMA is not allocated
  94H      A20 is still enabled
  A0H      All extended memory is allocated
  A1H      All available handles are allocated
  A2H      Invalid handle
  A3H      Source handle is invalid
  A4H      Source offset is invalid
  A5H      Destination handle is invalid
  A6H      Destination offset is invalid
  A7H      Length is invalid
  A8H      Move has an invalid overlap
  A9H      Parity error
  AAH      Block is not locked
  ABH      Block is locked
  ACH      Block lock count overflow
  ADH      Lock failed
  B0H      Only a smaller upper memory block (UMB) is available
  B1H      No UMB's are available
  B2H      UMB segment number is invalid


























                                        44






               Appendix E: Calling Protected-Mode Libraries From C


       This appendix contains a C version of the BASIC program presented in
  Example 3.  Microsoft C version 7.0 is used to create a float array.  C then
  calls a protected-mode assembly language procedure in a library to sum the
  elements of the array.  The assembly language library in Example 3 will work
  here with no modification.  C calls a real-mode procedure called SUMARRAY.
  This procedure then transfers control to a 32-bit protected-mode procedure
  called SUMARRAY32.  The latter procedure performs the actual calculations.
       Parameters defining the array are placed in a contiguous block of memory
  defined by a C structure.  C passes the address of this structure to the
  library.  The first four bytes in the structure are reserved for error codes.
  The linear address of the structure is placed in CCODEPTR so that any FPU
  exceptions will be recorded by the FPU interrupt handler in the error code
  location.  The SUMARRAY32 procedure will also record an error if the parameter
  defining the number of elements to be summed is zero.
       The C code is somewhat simpler than the corresponding BASIC code because
  conventional memory does not have to be released prior to calling INITXLIB.
  This follows because C does not claim all DOS memory as does BASIC.
       C is more powerful than BASIC in that it can access data under external
  symbols whereas BASIC cannot.  Access to XLIB public data is made possible in
  C by including the header file called XLIB.H.  This file makes all XLIB public
  data and public real-mode procedures visible to C.  It also contains
  declarations which adapt the PASCAL conventions of XLIB.
       A Borland version of this program and of the accompanying library may be
  found in the files EXAMP3B.C and EXAMP3B.ASM.






























                                        45






  _____________________________________________________________________________
  /*The following Microsoft C 7.0 program should be linked with the assembly
  language library in Example 3.  Combine the library with XLIB.LIB using the
  Microsoft LIB utility.  The C program first initializes XLIB.  Next, it
  creates a float array.  A control block for SUMARRAY is then constructed
  and the call to SUMARRAY is executed.  Finally, the condition code in the
  control block is inspected and results are printed.*/

  #include <stdio.h>
  #include <xlib.h>

  extern long __far __pascal LINADR(void __far *ptr);
  extern void __far __pascal SUMARRAY(void __far *ptr);

  struct arraydata            /*Structure for passing arguments to SUMARRAY*/
  {
    long condcode;
    long n;
    long address;
    float sum;
  } ad;

  main()
  {
    int i;
    long temp;
    float a[101];
    temp = INITXLIB();        /*Initialize XLIB*/
    if (temp != 0)            /*See if an error occurred*/
    {
      printf("Initialization Error:  %lX\n",temp);
      return 0;
    }

    for(i = 0; i <= 100; i++)   /*Initialize a[]*/
      a[i] = i;

    ad.condcode = 0;            /*Initialize the condition code*/
    ad.n = 50;                  /*Will sum the first 50 elements in a[]*/
    ad.address = LINADR(a);     /*Compute and record linear address of a[]*/

    SUMARRAY(&ad);              /*Sum the array elements*/
    if (ad.condcode != 0)       /*See if an FPU error occurred*/
    {
      printf("Error:  %lX\n",ad.condcode);
      return 0;
    }
    printf("Sum:  %f\n",ad.sum);   /*The sum should be 1225*/
  }
  _____________________________________________________________________________







                                        46






                     Appendix F: Reporting Problems With XLIB


       All efforts to isolate and report problems with XLIB will be appreciated.
  The following steps will greatly facilitate bug-tracking:

  1) Ensure that your own program always checks the error codes returned by XLIB
  procedures.  These codes will likely resolve the problem.  If not, then make
  note of the code.

  2) Attempt to execute your program under DPMI, VCPI, and in the absence of
  both.  If the problem relates to memory management, then also attempt to
  execute your program in the presence of XMS but in the absence of DPMI and
  VCPI, then attempt to execute in the absence of all three interfaces.  It will
  generally be found that the problem occurs only under a specific interface.
  If so, then note the interface under which the problem occurs.

  3) If the problem occurs only under one interface, then attempt to execute
  your program under different implementations of the interface.  For example, a
  DPMI host is contained in Windows 3.1, 386MAX, QDPMI, and OS/2 2.x.  Try
  executing your program under each host and make note of the results.  Problems
  occurring only under one host are generally indicative of bugs in the host
  rather than XLIB.

  4) Try different options on your compiler, assembler, and linker.  It is
  sometimes the case that code is not processed properly under some options.

  5) Report problems to:

  Dr. David Pyles
  TechniLib Company
  P.O. Box 6818
  Jackson, Ms. 39282
  [phone]























                                        47






                 Appendix G: The SWITCHPM and SWITCHRM Procedures


       SWITCHPM and SWITCHRM are the primitive mode-switch routines used by
  nearly all XLIB procedures requiring execution in both real and protected
  modes.  They are made public for users who need to perform mode switching
  tasks not provided by XLIB.  These routines do not conform to the general
  conventions followed by other XLIB procedures; consequently, they are
  presented in an appendix.
       There are special situations in which CALLPM and ENTERPM may not be
  suitable for performing mode switches.  For example, suppose one has a
  protected-mode hardware interrupt handler that is intended to service
  interrupts occurring in both real and protected modes.  Unless DPMI is
  installed, the user will have to write a second handler to deflect real-mode
  interrupts to the protected-mode handler.  CALLPM and ENTERPM could not be
  used in the event that the interrupt occurred in a real-mode procedure called
  from protected mode will CALLRM.  This follows because CALLPM and ENTERPM are
  not reentrant.  Instead, the user must perform the mode switches either with
  DEFLECTPM or with SWITCHPM and SWITCHRM.  The user might also wish to use
  SWITCHPM and SWITCHRM to avoid the overhead of CALLPM and ENTERPM.  SWITCHPM
  and SWITCHRM perform mode switches in minimum CPU time.
       Both SWITCHPM and SWITCHRM are near procedures in CSEG; therefore, they
  must be called from this segment.  SWITCHPM returns to the caller in 16-bit
  protected mode.  SWITCHRM returns to the caller in real mode.  Both procedures
  must be called with a stack in DSEG.  Do not use XLIB stacks for this purpose.
       SWITCHPM returns with CS = CSEGSEL and with all other segments equal to
  DSEGSEL.  All other registers, except the status flags, are preserved.
       SWITCHRM returns with CS = CSEG and with SS, DS, and ES set to DSEG.  FS
  and GS are undefined.  All other registers, except the status flags, are
  preserved.



























                                        48