XLIB PROGRAMMER'S MANUAL
                                   VERSION 1.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 $45.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                                     3
  3. Mode Switching                                                     5
  4. Interrupt Management                                               7
  5. Memory Management                                                 10
  6. XLIB Initialization                                               11
  7. XLIB Termination                                                  12
  8. Using XLIB in High-Level Language Libraries                       13


  TABLES
                                                                     Page
  1. XLIB Segments and Selectors by Public Symbol                       3
  2. CALLPM/ENTERPM Register Storage Locations by Public Symbol         6
  3. CALLRM Register Storage Locations by Public Symbol                 6


  EXAMPLES
                                                                     Page
  1. Simple Mode Switching Under XLIB                                   2
  2. Calling Protected-Mode Libraries From BASIC                       13


  APPENDICES
                                                                     Page
  A. Summary of XLIB Public Data                                       17
  B. Summary of XLIB Public Procedures                                 19
  C. XLIB Error Codes                                                  27
  D. Calling Protected-Mode Libraries From C                           28
  E. Reporting Problems With XLIB                                      30
  F. DPMI 1.0 Error Codes                                              31
  G. XMS Error Codes                                                   32
  H. The SWITCHPM and SWITCHRM Procedures                              33






                                 1. Introduction


       XLIB is an assembly language library which may be used with assembly
  language programs to greatly simplify protected-mode programming under the
  Microsoft DOS operating system.  Assembly language programmers can be writing
  protected-mode code in a matter of minutes with XLIB.  Implementation of such
  code will often require no more than placing the code in the proper segment
  and making two calls to XLIB procedures.
       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.
       XLIB procedures handle important tasks such as mode switching between
  real and protected modes, memory management under protected mode, and
  interrupt management under protected mode.  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).  Upon initialization, XLIB
  will examine the operating environment for the presence of these interfaces
  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.
       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.
       The memory model supported by XLIB approximates the flat model of IBM
  OS/2 and Microsoft Windows NT.  Therefore, code written for XLIB will require
  little modification when being transported to these systems.  Indeed, many
  procedures will require no modification whatsoever.  Moreover, XLIB includes
  flat-model descriptors which may be used to execute genuine flat-model code;
  however, it does not include routines to load and relocate such code.
       The following program illustrates the simplicity with which protected-
  mode execution may be initiated and terminated with XLIB.  The program 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.










                                        1






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


       XLIB was developed and tested under Microsoft DOS version 6.0 using
  Microsoft Assembler (MASM) version 6.1a, Microsoft LINK version 5.31.009, and
  Microsoft LIB version 3.20.01.  MASM parameters were set to c, W2, and WX.
  LINK parameters were set to BATCH, CPARM:1, FAR, NOPACKF, and PACKC.  XLIB has
  also been tested under Microsoft Windows 3.1, Qualitas 386MAX version 6.02,
  Quarterdeck QEMM version 6.02, and Quarterdeck QDPMI version 1.01.
       Assembly language programs should use the CPARM:1 parameter because XLIB
  will generally attempt to allocate DOS memory.  The NOPACKC option for LINK
  was found to be problematic for 32-bit segments and should therefore be
  avoided.



                                        2






                        2. XLIB Conventions and Structure


       A summary of most XLIB public data is included in Appendix A.  A summary
  of all XLIB public procedures is included in Appendix B.  This section sets
  forth rules which will be generally applicable to XLIB data and procedures.
  Exceptions to these rules are covered in Appendix H.
       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 XLIB real-mode procedures are located in a 16-bit segment
  called CSEG.  The user may also place code in CSEG but is never required to do
  so.  All public XLIB real-mode routines have far returns.
       All public XLIB protected-mode procedures are located in a 32-bit segment
  called TSEG.  The user must also place all protected-mode code in TSEG.  All
  XLIB protected-mode procedures have near returns.  Likewise, all protected-
  mode procedures called by XLIB routines must have near returns.
       All XLIB procedures may be called with interrupts enabled and will return
  with interrupts enabled provided that they were enabled upon call.
       All XLIB data is contained in a segment called DSEG.  The user may also
  place data in DSEG but is never required to do so.
       XLIB uses the Pascal calling and naming convention.  The Pascal
  convention is equivalent to the BASIC/FORTRAN convention.  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 may possibly encounter error conditions will always
  return error codes in AX (see Appendix C).  In many cases, DX or the high word
  of EAX will be returned with specific information about the error, such as
  XMS, DPMI, or DOS error codes.
       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