


                                 WATCOM.TXT

                       Using the WATCOM(TM) C/386 Compiler

                                June 19, 1992



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

    1.0 INTRODUCTION
    2.0 SETTING UP THE COMPILATION ENVIRONMENT
    3.0 COMPILING THE APPLICATION WITH WATCOM C
    4.0 ASSEMBLING MODULES
    5.0 LINKING OBJECT MODULES
        5.1 Building an API Application
    6.0 NOTES ON DEBUGGING
    7.0 THE wcmaphys ASSEMBLY MODULE



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

    The WATCOM(TM) C compiler can be used in the 386|DOS-Extender(TM)
    environment. The executable ADS library to use with WATCOM C9.0/386
    is called wcads90.lib.  Using the WATCOM C/386 compiler requires
    the following tool:

      Compiler    WATCOM C9.0/386

    WATCOM C/386 doesn't require additional tools to produce and debug
    an ADS executable. You have the option of using the Phar Lap(R)
    tools. For example, for assembling your own code you might want to
    use:

      Assembler  Phar Lap 386|ASM(TM)

    The assembler is part of the Phar Lap 386|DOS-Extender
    Developer's Kit, version 4.1. The compiler is available as a
    separate product.

    IMPORTANT: AutoCAD 386 uses a special version of the DOS-Extender,
    called 4.1-ACAD. If you are using the Phar Lap 4.1 tools you should
    apply a patch to them so they work correctly with AutoCAD. At
    present, you can obtain this patch from Phar Lap. In the future, the
    patch might become available through the ADESK forum on the
    CompuServe(R) network: check this forum for more current
    information.

    NOTE: For AutoCAD(R) 386, the linker builds ADS applications as .exp
    files (protected-mode executables). To build real-mode executables,
    you must use the Real-Mode ADS Interface described in realmode.txt.

    For more information, see the "WATCOM C/386 User's Guide" provided
    with WATCOM C9.0/386.

    NOTE: Although the "WATCOM C/386 User's Guide" states that it's
    necessary to convert wcads.lib into a format compatible with the
    WATCOM linker by running it through wlib.exe, this is no longer
    necessary with wcads90.lib. The WATCOM ADS library provided with
    AutoCAD 386 Release 12 was built using wlib.exe, and you don't have
    to convert it.

    WATCOM produces a FORTRAN 77/386 compiler that can compile ADS
    applications. For documentation and examples of ADS development using
    FORTRAN, contact WATCOM.


    2.0 SETTING UP THE COMPILATION ENVIRONMENT
    ==========================================

    The following environment variables are used with the WATCOM
    compiler:

      INCLUDE    Path to the compiler's include files. For example:
                 set include=\watcom\h

      WATCOM     Pathname of the directory where the WATCOM compiler is
                 installed.

      PATH       Be sure to add the WATCOM binary directories to your
                 PATH.  For example:
                 set PATH=\watcom\bin;\watcom\binb;...

    NOTE: The ADS library is distributed along with a sample batch file
    that contains the commands for setting these variables, invoking the
    compiler, and linking the object code.  The file is called
    w90samp.bat. To use the batch file, invoke it as follows:

        w90samp <filename>

    where <filename> is the name of your source file (without the .c
    filename extension). You can edit the file to match your
    environment, if necessary.  If you don't invoke it with the
    <filename> argument, w90samp.bat builds all of the sample
    applications.

    The default floating-point precision for WATCOM C/386 is 53 bits.
    However, AutoCAD uses a precision of 64 bits. To change the
    precision of WATCOM, modify their 8087cw.c file and link it in to
    your application. The 8087cw.c source is provided in the WATCOM
    subdirectory \watcom\src\startup. (WATCOM chose 53 bits as a default
    to "generate reproducible floating-point results regardless of the
    level of optimization chosen for the compiler.")


    3.0 COMPILING THE APPLICATION WITH WATCOM C
    ===========================================

    To compile C source code, invoke the wcc386p command. Compiling an ADS
    application requires you to specify certain options. For example:

        wcc386p jane -fpi287 -3s -s -oailt -zq

    In this example, the options are:

      jane       The name of the source file. You don't have to enter the
                 filename extension (.c).

      -fpi287    Generates inline 80287 instructions.  This option is
                 used to accommodate those few 386 systems that use
                 an 80287 coprocessor.

      -3s        Generates 80386 instructions using stack-based argument
                 passing conventions. (Required)

      -s         Removes stack overflow checks.

      -oailt     Optimizations for speed.

      -zq        Causes the compiler to operate quietly.

    Applications built with the WATCOM compiler must be compiled using
    the default memory model, which is *flat*. See the WATCOM C/386
    manual for additional details about these and other command line
    options.


    4.0 ASSEMBLING MODULES
    ======================

    To assemble code modules, invoke the 386|ASM assembler via the
    386asm command. For more information, see the pharlap.txt document
    in this directory. For full details, see the "386|ASM Reference
    Manual."

    CAUTION: If you use assembly-language modules, be sure that code
    segments have a class specifier of CODE, and that data segments have
    a class specifier of DATA. Any other class names can cause segments
    to be loaded in the middle of the heap, with unpleasant results when
    you attempt to run AutoCAD.


    5.0 LINKING OBJECT MODULES
    ==========================

    You can link your application using the WATCOM linker, wlinkp.exe.
    By using the SYSTEM ADS directive, the WATCOM linker will
    automatically replace the startup module contained in the
    WATCOM C/386 run-time library clib3s.lib with a special version
    required for ADS. This special version, adsstart.obj, is located
    in the directory \watcom\lib386\dos. The following is an example of
    using the link command for ADS:

       wlinkp system ads file jane library wcads90 option quiet

    In this example, the directives are:

      system ads        Gives the linker information needed to build an
                        ADS application.

      file jane         Specifies the application object file.

      library wcads90   Includes the ADS libary for WATCOM C9.0/386.

      option quiet      Tells the linker to operate quietly.


    5.1 Building an API Application
    ===============================

    To build an application that uses the Application Programming
    Interface (API) of the AutoCAD Advanced Modeling Extension(TM)
    (AME), you need to link the API library as well as the ADS library. 
    (For more information about API, see the "Advanced Modeling
    Extension Release 2.1 Reference Manual.") The WATCOM version of the
    API library is called wcapi90.lib. This file is installed in the
    directory \acad\api.

    For example, the linking command shown in the previous section would
    be as follows:

       wlinkp system ads file jane library wcads90 \acad\api\wcapi90.lib
              option quiet

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

    The command is the same except for the additional library
    specification.


    6.0 NOTES ON DEBUGGING
    ======================

    Use the WVIDEO debugger from WATCOM to debug your ADS application.
    The use of WVIDEO is described in the "WATCOM VIDEO User's Guide".

    Be sure to place the WATCOM C/386 .\bin and .\binb directories in
    your PATH.

    Because AutoCAD 386 Release 12 is linked as UNPRIVILEGED, you will
    have to set the environment variable DOSX to PRIVILEGED:

        set DOSX=-priv

    Otherwise, you won't be able to load adshelp.exp. This program is an
    ADS application provided by WATCOM in their .\bin directory. WVIDEO
    requires it for debugging ADS applications and it should be loaded
    by AutoCAD before you load your own application. You can use (xload)
    to load adshelp.exp, or you can include its name in the file
    acad.ads so AutoCAD will load adshelp.exp automatically, at
    initialization time.

    7.0 THE wcmaphys ASSEMBLY MODULE
    ================================
 
    Some applications need to map physical memory into the application's
    own linear address space. The assembly-language source file
    wcmaphys.asm demonstrates how to do this. To use this file, you must
    modify the map_phys_mem function to specify the location (base
    address) and number of pages you want to map, then assemble the code
    using the Phar Lap assembler:

        386asm wcmaphys -twoc -d ADS

    Save a backup copy of the ADS library (wcads90.lib), then use 386|LIB
    to replace the wcmaphys module in the ADS library with the new module.
    For example:

        386lib wcads90.lib -r wcmaphys

    Use this new library with the modified wcmaphys when you link your
    ADS application, as described above in section 5.0.

    For more information about memory mapping, see the comments in the
    source file wcmaphys.asm.


    Copyright 1990, 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.

