


                                  REALMODE.TXT
                           
                           The Real-Mode ADS Interface

                                  June 19, 1992


    TABLE OF CONTENTS
    =================

    1.0 INTRODUCTION
        1.1 Upward Compatibility
    2.0 HOW TO USE REAL-MODE ADS APPLICATIONS
        2.1 Memory Usage
        2.2 Configuring AutoCAD to Run Real-Mode Applications
    3.0 DEVELOPING REAL-MODE ADS APPLICATIONS
        3.1 Programming Guidelines
            3.1.1 Header Files
            3.1.2 Memory Allocation
            3.1.3 File Handling
            3.1.4 Memory Model and Layout
            3.1.5 Parameter Passing
            3.1.6 Structure Packing
            3.1.7 Invoking Other Applications
        3.2 Compiling and Linking 
            3.2.1 Compiling with Microsoft C
            3.2.2 Compiling with Borland Turbo C
    4.0 DEBUGGING REAL-MODE ADS APPLICATIONS



    1.0 INTRODUCTION
    ================

    Real-Mode ADS is an implementation of the AutoCAD Development
    System(TM) (ADS) that compiles and executes in "real mode"--as
    opposed to "protected mode"--on MS-DOS(R) platforms with 80386(TM)
    or 80486(TM) processors.  The real-mode implementation of ADS lets
    you use the Microsoft(R) C or Borland Turbo C(R) compiler without
    your having to purchase additional development tools. (For example,
    to build protected-mode ADS applications on 386 platforms, you must
    acquire the Phar Lap(R) 386|LINK(TM) linker and other tools.) Also,
    these real-mode compilers may be available in countries where
    protected-mode compilers, such as WATCOM(TM) and MetaWare(TM)
    products, are not.

    Real-Mode ADS is fully compatible with protected-mode ADS. Except for
    some particular requirements described in this document, the features of
    the Real-Mode ADS library are identical to those of the protected-mode
    library. For general information on using and developing ADS applications,
    please see the "AutoCAD Development System Programmer's Reference,"
    which is provided with each copy of AutoCAD(R) (Release 11 or later).


    1.1 Upward Compatibility
    ========================

    Applications developed with Release 11 Real-Mode ADS (which required
    the (pwedge) application) should be recompiled and relinked to
    exploit the improved, transparent real-mode support offered by Release 12.

    The (xload) function in Release 12 does *not* support real-mode
    applications developed under Release 11. However, the application
    pwedge.exp is still supported. If you continue to use pwedge.exp and
    its functions (rload), (runload), and (rads), you don't have to
    recompile your Release 11 real-mode applications. For more
    information on these functions, see the documentation for the
    Autodesk(R) Software Developer's Kit (SDK 2.0).


    2.0 HOW TO USE REAL-MODE ADS APPLICATIONS
    =========================================

    To load, unload, and execute Real-Mode ADS applications, you use the
    AutoLISP(R) (xload) function. For example:

        Command: (xload "testme.exe")

    If you specify the .exe filename extension, the (xload) function
    searches only for a real-mode application with the specified name. If you 
    omit the extension, (xload) searches first for a protected-mode
    (.exp) application. If it can't find a protected-mode version of
    the program, it then searches for a real-mode version.

    In all other respects, the functions to handle real-mode ADS
    applications behave just as they do with protected-mode
    applications. The (ads) function lists all currently loaded external
    applications, including real-mode applications, and the (xunload)
    function unloads an external application.  For more information, see
    either the descriptions of (xload), (ads), and (xunload) in the
    "AutoLISP Programmer's Reference," or the introduction to the
    "AutoCAD Development System Programmer's Reference."

    The ADS functions ads_xload() and ads_xunload() also load and unload
    external applications. The ads_xload() function treats real-mode
    applications the same way (xload) does. If the filename extension is
    explicitly specified, ads_xload() searches only for a real-mode
    (.exe) or protected-mode (.exp) application. If the extension is
    omitted, ads_xload() searches first for a protected-mode
    application, then for a real-mode application of the same name. The
    ads_loaded() function, like (ads), returns a list of all currently
    loaded external applications, including both protected-mode and
    real-mode applications. These functions are described in the
    "AutoCAD Development System Programmer's Reference." 


    2.1 Memory Usage
    ================

    Because real-mode applications must execute in conventional memory (the
    first 640K of RAM), when AutoLISP loads a real-mode application it
    frees as much of this space as possible. (Some executable portions
    of AutoCAD and the DOS extender it's using, as well as some
    terminate-and-stay-resident [TSR] programs, including ADI drivers,
    cannot be moved out of this space.) You can check the amount of
    conventional memory available by using the AutoCAD Status command.
    Besides room to load the application itself, conventional memory must
    have enough room to accommodate any AutoCAD data structures
    (entities, tables, etc.) that the Real-Mode ADS application
    accesses. AutoLISP copies these objects from extended memory down 
    to conventional memory where the Real-Mode ADS application can
    access them. It converts their addresses as necessary.

    For more information about a Real-Mode ADS application's memory
    usage, see the section "Memory Model and Layout," below.


    2.2 Configuring AutoCAD To Run Real-Mode Applications
    =====================================================

    If you attempt to load a real-mode application and receive the
    following error message:

        Unable to load application due to insufficient stack buffers.

    you must adjust the value of the DOS Extender switch NISTACK.
    AutoCAD is configured for 10 stack buffers and requires three of
    them itself, so if you need to load more than seven Real-Mode ADS
    applications at the same time, you must use the Phar Lap cfig386
    command to increase the value of NISTACK to its maximum of 16. For
    example:

        cfig386 acad.exe -NISTACK 16 

    This enables you to load up to 13 Real-Mode ADS applications at the
    same time, provided they can all fit in conventional memory. You
    must exit AutoCAD before you invoke the CFIG386 command, then
    restart AutoCAD.

    If you plan to use a symbolic debugger to debug Real-Mode
    ADS applications, you must configure AutoCAD to save all registers
    when switching from protected mode to real mode. Do this by
    specifying the cfig386 SAVER switch:

        cfig386 acad.exe -SAVER

    The following invocation of cfig386 specifies both options at once:

        cfig386 acad.exe -SAVER -NISTACK 16

    If you develop Real-Mode ADS applications regularly, set both these
    switches as shown before you start AutoCAD.

    NOTE: The -SAVER switch imposes some overhead whenever AutoCAD turns
    control over to a Real-Mode ADS application, and vice versa, so if
    you aren't debugging any real-mode applications, you might want to
    turn it off again (possibly resetting the NISTACK switch, as shown):

        cfig386 acad -CLEAR -MINSWFSIZE 400000 -SWAPDEFDISK -SWAPCHK OFF
            -DEMANDLOAD -VSCAN 20000 -NISTACK 16

    NOTE: You must enter the cfig386 instructions on a single command
    line.


    3.0 DEVELOPING REAL-MODE ADS APPLICATIONS
    =========================================

    This section describes how to compile and build Real-Mode ADS
    applications. The first subsection describes general programming
    considerations and caveats; the second describes how to compile
    Real-Mode ADS applications by using particular compilers.


    3.1 Programming Guidelines
    ==========================

    The notes in this section describe how to write a program that runs
    successfully as a Real-Mode ADS application. Information not
    specifically covered here is described in the ADS manual.


    3.1.1 Header Files
    ==================

    The header files for Real-Mode ADS are the same as those for
    protected-mode ADS: adslib.h, ads.h, and adscode.h.  An application
    needs to include only adslib.h: this header file contains #include
    directives for the other two files.


    3.1.2 Memory Allocation
    =======================

    Your application should always free the memory it allocates, but if for
    some reason it exits without doing so, Real-Mode ADS automatically frees
    any memory allocated by the (standard library) C functions malloc(),
    calloc(), and realloc().

    CAUTION: Do not allocate any memory before you call ads_init(). The
    call to ads_init() should be the first line of code in your
    application's main() function. This caution applies to protected-
    mode ADS as well, but it is particularly important to the memory
    management provided by Real-Mode ADS.

    Real-Mode ADS tries to safeguard against unfreed memory by
    maintaining a separate Program Segment Prefix (PSP) for each Real-
    Mode ADS application (this is a change from Release 11). All memory
    occupied by an ADS application is recorded in a list of Memory
    Control Blocks (MCB). The PSP for each application contains a
    pointer to the first MCB. This enables Real-Mode ADS to traverse the
    MCB list and release any memory allocated by the Real-Mode ADS
    application. 

    Real-Mode ADS does this cleanup ("garbage collection") when it traps
    a fatal error in a Real-Mode ADS application or receives an
    (xunload) or ads_xunload() request for the application.

    Memory allocated by children of the Real-Mode ADS application must
    be released by the child application. Otherwise, it remains in
    conventional memory when the application exits, creating a "memory
    leak" that can potentially bring your system to a halt.


    3.1.3 File Handling
    ===================

    Your application should always close the files it has opened.
    Otherwise, the file handle continues to take up space in the file
    handle table and becomes unavailable to other programs.

    Real-Mode ADS tries to safeguard against unfreed file handles by
    maintaining a separate Program Segment Prefix (PSP) for each 
    Real-Mode ADS application. All file handles reserved by an ADS
    application are recorded in a table pointed to by the PSP. This
    enables Real-Mode ADS to close open files and to free their handles.

    Real-Mode ADS cleans up open files and frees file handles when it
    traps a fatal error in a Real-Mode ADS application or receives an
    (xunload) or ads_xunload() request for the application.


    3.1.4 Memory Model and Layout
    =============================

    Real-Mode ADS applications must be Large Model.

    If you intend to load more than one Real-Mode ADS application at a
    time or to use the AutoCAD Shell command while your Real-Mode ADS
    application is loaded, the memory layout of your application must
    conform to the layout required for a TSR. This means putting a
    fixed-size stack on top of the code and data, with a dynamically
    allocatable heap on top of the stack. For Microsoft C, this layout
    is the default; you *cannot* use the Microsoft linker switch /HIGH,
    because it alters this layout.

    After your application is loaded, Real-Mode ADS calculates its size
    in memory by subtracting the address of the PSP from the address of
    the top of the stack. This value is counted in 16-byte "paragraphs."


    3.1.5 Parameter Passing
    =======================

    Your application must pass parameters on the stack, not through registers.
    Microsoft C uses the stack by default (as do most C compilers).

    CAUTION: Trying to use a NULL or invalid pointer returned by the Real-Mode
    ADS library can *crash* *the* *system*. Your application should always
    check that a pointer returned by a Real-Mode ADS library function is not
    NULL. If the pointer was returned via a parameter, *always* check the
    function result code to be sure that the call was successful (RTNORM)
    before you try to use the pointer.


    3.1.6 Structure Packing
    =======================

    Structure packing must be turned *off*. This is the default for
    Microsoft C.


    3.1.7 Invoking Other Applications
    =================================

    You can use the ads_invoke() function to invoke functions in other ADS
    applications. The other applications can be either protected-mode or Real-
    Mode ADS applications. (As always, the other application must have been
    loaded first.)


    3.2 Compiling and Linking
    =========================

    This section describes how to compile and link a Real-Mode ADS application.
    For full details, refer to the documentation supplied with the
    compiler (in particular, the command options might be different if your
    system has an 80486 processor instead of an 80386).

    Your link instructions must always specify one of the following
    files, as appropriate:

      mscads6.lib   This is the Microsoft C Real-Mode ADS library.
      tbcads3.lib   This is the Turbo C Real-Mode ADS library.


    3.2.1 Compiling with Microsoft C
    ================================

    You can compile Real-Mode ADS applications by using the Microsoft C
    compiler, version 5.1 or later. (The compiler must be version 6.0AX
    or later if you want to use the Microsoft CodeView(R) debugger.)

    The compiler command is called cl. It can be used to link the
    application as well as compile it. For example, if your application
    is named test.c, the following command compiles it, links it, and
    produces the executable file test.exe:

        cl /AL /EM /DADS /FPi87 /Zi /Fetest test.c /link llibc7
            mscads6.lib /NOE /NOI /CO

    NOTE: You should enter this command on a single command line.

    The command options have the following meanings (see the Microsoft C doc-
    umentation for full details):

      /AL        Specifies the large model, which is the only memory model
                 that Real-Mode ADS supports.

      /EM        Specifies that the compiler is to use extended memory
                 while trying to compile the specified source file. This
                 option is only available for version 6.0AX (and later
                 versions). You can't use it with an earlier version or
                 if the system you're compiling on doesn't have extended
                 memory.

                 NOTE: Some of the sample ADS applications shipped with
                 AutoCAD won't compile without extended memory.

      /DADS      Defines the symbol ADS for the use of the ADS header file
                 adslib.h. (One or more spaces can precede the symbol name.)

      /FPi87     Generates in-line floating-point instructions.

      /Zi        Instructs the compiler to include line-number and
                 complete symbolic information in the object file.

      /Fetest    Names the executable file test.exe (a space must not
                 precede the filename).

      test.c     Names the source file.

      /link      Tells the compiler to invoke the linker after compilation and
                 that options for the linker follow:

                 llibc7       Says to include llibc7, which is the real-
                              mode run-time library.

                 mcsads6.lib  Includes the Real-Mode ADS library.

                 /NOE         Prevents the linker from searching the
                              extended dictionary, which is an internal
                              list of symbol locations maintained by
                              the linker.

                 /NOI         Preserves case sensitivity. By default,
                              LINK maps all names to uppercase
                              characters. Because many C function names
                              are a mix of upper- and lowercase letters,
                              it is important to use this option.

                 /CO          Tells the linker to include debugging
                              information in the executable file.

    After you have debugged your program, it's a good idea to compile with the
    following optimization options:

      /Oailt     Specifies several options: ignore aliasing, enable intrinsic
                 functions, optimize loops, and optimize for speed
                 rather than size.

      /Gs        Removes stack probes.

    SUGGESTION: For complex applications and applications that must be main-
    tained over a long period of time, the Microsoft makefile facility (make)
    can help keep sources organized and up to date. Again, refer to system-
    specific documentation for details on using this facility.


    3.2.2 Compiling with Borland Turbo C
    ====================================

    You can compile Real-Mode ADS applications with the Turbo C
    compiler, version 2.0 or later. The compiler command is called bccx.
    You can link the application by using the tlink command. For
    example, if your application is named test.c, the following two
    command lines compile it, link it, and produce the executable file
    test.exe:

        bccx -I\ads;\borlandc\include -AT -1 -ml -v -f287 -N- -G
             -DPROTOTYPES -c -test.c

        tlink /x /d /c /Tde /v c0l.obj
            test.obj,test.exe,,tbcads3.lib FP87 mathl cl

    NOTE: You should enter each of these commands on a single command
    line.

    The command options for the compiler, bccx, are as follows:

      -I\ads;\borlandc\include
                 Specifies that the compiler is to search for include
                 files in the directories \ads and \borlandc\include.

      -AT        Specifies that the compiler is to recognize the Turbo C
                 reserved words, such as cdecl, near, far _asm, and any
                 other keywords that are unique to Turbo C.

      -1         Specifies that the compiler is to generate 80186 and
                 80286 instructions.

      -ml        Specifies that the compiler is to generate far code and
                 data pointers. This is required for Real-Mode ADS
                 applications.

      -v         Specifies that the compiler is to generate in-line
                 debug information in the object files. This is needed
                 if you intend to run the application under the source-
                 level debugger.

      -f287      Specifies that the compiler is to generate in-line
                 80287 floating-point instructions.

      -N-        Specifies that the compiler should not generate stack-
                 checking code.

      -G         Specifies that the compiler should optimize code
                 generation for speed.

      -DPROTOTYPES
                 Defines the symbol PROTOTYPES.

      -c         Specifies that the compiler should compile the file to
                 an object file and not automatically invoke the linker.

      test.c     Names the source file to compile.

    The command options for the linker, tlink, are as follows:

      /x         Specifies that the linker should not create a map file.

      /d         Specifies that the linker should display warnings on
                 duplicate symbol names.

      /c         Specifies that the linker treat symbols as case
                 sensitive.

      /Tde       Specifies that the linker is to create an executable
                 for the DOS .exe format.

      /v         Specifies that the linker is to include full symbolic
                 debug information.

      c0l.obj    Specifies that the startup code supplied with Turbo C
                 should be used for this application.

      test.obj   Names the compiled object file, test.obj.

      test.exe   Names the executable file test.exe.

      tbcads3.lib FP87 mathl cl
                 Specifies that the libraries tbcads3.lib, FP87, mathl,
                 and cl should be linked into the application.


    4.0 DEBUGGING REAL-MODE ADS APPLICATIONS
    ========================================

    Real-Mode ADS applications compiled under Release 12 using 
    Microsoft C 6.0 (or a later version) can be debugged with the
    Microsoft CodeView debugger. Applications compiled under Release 12
    using Borland Turbo C can use the Turbo C debugger.

    REMINDER: Before you use CodeView or the Turbo C debugger, you must
    configure AutoCAD to save all registers when switching from
    protected mode to real mode. Do this by specifying the cfig386
    SAVER switch:

        cfig386 acad.exe -SAVER

    For more details, see section 2.2, "Configuring AutoCAD To Run
    Real-Mode Applications," above.

    The new environment variable EXEDEBUG has been created to indicate
    which debugger is to be placed between AutoLISP and the Real-Mode
    ADS application. The name of this variable is similar to EXPDEBUG
    (an environment variable used in debugging protected-mode ADS
    applications, as described in the file pharlap.txt), but its meaning
    is different, as explained in this section.

    The value of EXEDEBUG specifies the full pathname of the debugger
    and any parameters that will be passed. As an example, consider a
    value of EXEDEBUG used to debug a real-mode ADS application compiled
    under Microsoft C with debugging information turned on:

        set EXEDEBUG = C:\C600\BIN\CV.EXE /2 /43

    The values specified by EXEDEBUG are as follows:

      c:\c600\bin\cv.exe
                 The full pathname of the debugger (in this example, the
                 CodeView executable).

      CodeView command-line arguments:

      /2         Tells CodeView to use two monitors.

      /43        Sets the number of lines displayed by CodeView to 43.
                 If your display cannot handle this many lines, CodeView
                 displays 25 lines.

    If you're using the Turbo C debugger, set EXEDEBUG to specify the
    full pathname of the debugger executable, and any command-line
    options you choose. For example:

        set EXEDEBUG=C:\BIN\TD286.EXE

        set EXEDEBUG=C:\BIN\TD286.EXE -DO

    Setting EXEDEBUG to nothing disables debugging on all subsequent
    loading of real-mode applications via (xload), ads_xload(), or the
    ACAD.ADS file. You can continue to debug an application that was
    loaded while EXEDEBUG was set.

    The following command line sets EXEDEBUG to nothing:

        set EXEDEBUG=

    CAUTION: Using CodeView, you can debug only one Real-Mode ADS
    application at a time.  This limitation is imposed by the limited
    amount of conventional memory that is available for Real-Mode ADS
    applications. CodeView is itself a real-mode application, and as a
    result it consumes a significant amount of conventional memory.
    Real-Mode ADS does not allow more than one copy of CodeView in
    memory at a time. If an application is already being debugged under
    CodeView, then all subsequent requests to load Real-Mode ADS
    applications load the application without loading CodeView (provided
    there is still enough conventional memory to load the application at
    all). 


    Copyright 1991, 1992 Autodesk, Inc.

    All Rights Reserved

    AUTODESK, INC. MAKES NO WARRANTY, EITHER EXPRESSED OR IMPLIED,
    INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY
    OR FITNESS FOR A PARTICULAR PURPOSE, REGARDING THESE MATERIALS AND MAKES
    SUCH MATERIALS AVAILABLE SOLELY ON AN "AS-IS" BASIS.

    IN NO EVENT SHALL AUTODESK, INC. BE LIABLE TO ANYONE FOR SPECIAL,
    COLLATERAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH OR
    ARISING OUT OF PURCHASE OR USE OF THESE MATERIALS. THE SOLE AND
    EXCLUSIVE LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION,
    SHALL NOT EXCEED THE PURCHASE PRICE OF THE MATERIALS DESCRIBED HEREIN.

    For conditions of use and permission to use these materials for
    publication in other than the English language, contact Autodesk, Inc.

    Autodesk, Inc. reserves the right to revise and improve its products as
    it sees fit. This publication describes the state of this product at
    the time of its publication, and may not reflect the product at all
    times in the future.

    Autodesk Trademarks

    The following are registered trademarks of Autodesk, Inc.: ADI, ATC,
    Autodesk, Autodesk Animator, the Autodesk logo, AutoCAD, AutoCAD
    Training Center, AutoLISP, AutoShade, AutoSketch, and AutoSolid.

    The following are trademarks of Autodesk, Inc.: ACAD, Advanced Modeling
    Extension, Advanced User Interface, AME, AME Link, Animator Pro,
    Animator Pro Player, Animation Player, ATLAST, AUI, AutoCAD Development
    System, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL
    Interface, Autodesk Animator Clips, Autodesk Animator Theatre,
    Autodesk Device Interface, Autodesk Multimedia Training Center,
    Autodesk Software Developer's Kit, Autodesk Training Center,
    AutoFlix, CA Lab, Cyberized, cyberParts, DXF, FLI, HyperChem, James
    Gleick's CHAOS: The Software, MTC, Multimedia Explorer, SketchTools,
    SmartCursor, 3D Studio, and World-Creating Toolkit.

    The following are service marks of Autodesk, Inc.: Autodesk
    Strategic Developer, Autodesk Strategic Developer logo, Autodesk
    Registered Developer, Autodesk Registered Developer logo,
    TinkerTech.

    Third Party Trademarks

    All other brand and product names are trademarks or registered
    trademarks of their respective holders.

    GOVERNMENT USE

    Use, duplication, or disclosure by the U.S. Government is subject to
    restrictions as set forth in FAR 52.227-19 (Commercial Computer
    Software-Restricted Rights) and DFAR 252.227-7013(c) (1) (ii) (Rights
    in Technical Data and Computer Software), as applicable.

    Program Credits

    AutoCAD 386 incorporates licensed, run-time versions of 386|DOS-
    Extender and 386|VMM from Phar Lap Software, Inc., Cambridge,
    Massachusetts.

