


                                 HIGHC.TXT

                     Using the MetaWare(TM) High C(TM)
                        or High C/C++(TM) Compiler


                               Aug. 13, 1992



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

    1.0 INTRODUCTION
    2.0 SETTING UP THE COMPILATION ENVIRONMENT
    3.0 BUILDING THE APPLICATION WITH High C or High C/C++
        3.1 Creating a Profile
        3.2 Opening Files with the Correct Access Mode
    4.0 ASSEMBLING MODULES
    5.0 LINKING OBJECT MODULES
        5.1 Building an API Application
    6.0 NOTES ON DEBUGGING USING High C 1.7x
    7.0 NOTES ON DEBUGGING USING High C/C++ 3.0
    8.0 THE mapphys ASSEMBLY MODULE



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

    The MetaWare(TM) High C(TM) or High C/C++(TM) compiler can be used
    in the DOS-Extender(TM) (386) environment. The executable ADS library
    to use with High C 1.73 or lower is called ads.lib. The executable
    ADS library to use with High C/C++ 3.0 is m30ads.lib.  Using either
    compiler requires the following tools:

      Compiler   MetaWare High C Compiler for 32-bit systems,
                 Version 1.5, 1.62, 1.71, or 1.73 (latest product)

                            or

      Compiler   MetaWare High C/C++ Compiler for 32-bit systems,
                 Version 3.0 (3.03 is the latest product - earlier
		 versions of 3.0 may have a bug in the ADS runtime
		 initializer distributed with the compiler.  For-
		 tunately the correct initializer is provided in
		 the library, m30ads.lib, so for versions 3.02 and
		 earlier do not use the -Hads switch since it includes
		 the initializer from the MetaWare distribution.)

      Linker     Phar Lap(R) 386|LINK(TM), Version 4.1 or later

    NOTE: If MetaWare provides a file called readme.ads then the
    information it contains will be more current, and should supersede
    the information in this document.

    You may also require the following tools if you are not using the
    MetaWare source-level debugger MDB, if you are debugging and do
    not have enough RAM to hold all of the application, or if you
    need to build any assembly code:

      Debugger   Phar Lap 386|DEBUG(TM)

      Virtual memory manager
                 Phar Lap 386|VMM(TM)

      Assembler  Phar Lap 386|ASM(TM)

    The linker and assembler are part of the Phar Lap 386|DOS-Extender
    Developer's Kit, version 4.1; the virtual memory manager and
    debugger are optional components of that kit. 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 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.

    IMPORTANT: MetaWare High C 386, version 1.73, requires you to update
    the ADS library (ads.lib) by first copying it into the High C direc-
    tory .\small\ads and then running the batch file fixlib.bat (provided
    by MetaWare).  This batch file requires the Phar Lap librarian,
    386lib.exe.


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

    The following environment variables apply to the High C and High C/C++
    compiler:

      IPATH      Path to the compiler's include files. For example:
                 set ipath=\highc\inc

      HIGHC      Pathname of the directory where the High C compiler is
                 installed.

      PATH       Be sure to add the High C binary directory to your
                 PATH.  For example:
                 set PATH=\highc\bin;...

    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. For High C, the file is
    called makesamp.bat. To use the batch file, invoke it as follows:

        makesamp <filename>

    For High C/C++ 3.0, the file is called m30samp.bat.  To use the batch
    file, invoke it as follows:

        m30samp <filename>

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

    If you are using High C/C++ 3.02 or lower then modify the "m30opts"
    variable in m30samp.bat so that it does NOT use the -Hads switch.


    3.0 BUILDING THE APPLICATION WITH High C or High C/C++
    ======================================================

    To build an ADS application, invoke the hc386 command. Building an
    ADS application requires you to specify certain options. As a
    minimal example (for High C 1.71):

        hc386 -Hads jane.c -f287 -I\highc\inc -Hpro=sample.pro -lads.lib

    In this example, the options are:

      -Hads      Automatically links to the correct initializer.

      jane.c     The name of the source file.

      -f287      Generates code for the 80287 coprocessor. This option
                 is used to accommodate those few 386 systems that use
                 an 80287 coprocessor.

      -I\highc\inc
                 Tells the compiler where to search for include files.
                 In this case, the include files are on the current
                 drive in the \highc\inc directory. (This option is not
                 required if the IPATH environment variable is set, as
                 previously described.)

      -Hpro=sample.pro
                 Specifies a profile file, sample.pro, that contains
                 pragmas defining the compilation environment (see
                 section 3.1).

      -lads.lib
                 Specifies the ADS library to be included in the link.

    For High C/C++ 3.03 and greater, a minimal example for building an
    application (written in C):

        hc386 jane.c -Hads -f287 -O3 -Hpro=m30samp.pro -lm30ads.lib

    In this example, the options are:

      jane.c     The name of the source file.

      -Hads      Automatically links to the correct initializer.

      -f287      Generates code for the 80287 coprocessor. This option
                 is used to accommodate those few 386 systems that use
                 an 80287 coprocessor.

      -O3        Optimization.  This is a reasonably safe level, but you
                 may want to either increase or decrease your level of
                 optimization depending on you coding style.

      -Hpro=m30samp.pro
                 Specifies a profile file, m30samp.pro, that contains
                 pragmas defining the compilation environment (see
                 section 3.1).

      -lm30ads.lib
                 Specifies the ADS library to be included in the link.

    IMPORTANT NOTE: For High C/C++ 3.02 and lower use the same command
    line as specified for 3.03 but omit the switch -Hads.  This switch
    causes the ADS-modified runtime initializer from the MetaWare distri-
    bution to be linked into the ADS application but for versions 3.00
    through 3.02 this distributed initializer is incorrect.  The correct
    initializer for these earlier versions is provided in the ADS library
    m30ads.lib.

    Please also note that High C/C++ 3.0 provides, in addition to -Hads,
    the switch -Hloclib.  Using these two switches together provides,
    according to MetaWare, a High C 1.73 environment for ADS development
    using High C/C++ 3.0.  Since High C/C++ 3.0 can be used in it's native
    mode using the ADS library m30ads.lib, the use of these two switches
    together to emulate the 1.73 environment for ADS development should
    no longer be necessary.

    See the MetaWare High C or High C/C++ 386 manuals for additional details
    about these and other command line options.


    3.1 Creating a Profile
    ======================

    If present, the profile file specified by the compiler's -Hpro
    option is read by the compiler before it reads the source file.
    Generally, the profile is used for definitions and pragmas that
    set the conditions of compilation. The makesamp.bat file, for
    versions 1.71 or 1.73, creates a profile called sample.pro and the
    m30samp.bat file for version 3.0 creates a profile called
    m30samp.pro -- see these files for an example of typical profile
    settings.


    3.2 Opening Files with the Correct Access Mode
    ==============================================

    If your application opens files for either reading or writing, it
    must include the header file system.cf:

        #include <system.cf>

    This header file declares a global variable called Sharing_mode,
    which controls file access. The default value of this variable is
    Compatibility. If Sharing_mode equals Compatibility when you open a
    file (by calling fopen()), the file is opened in shared mode and is
    accessible to all programs. Your application must not open files in
    shared mode, as explained in chapter 5 of the ADS manual. Instead,
    you must open a file for exclusive reading or writing. To do so,
    change the value of Sharing_mode immediately before you call
    fopen(). For example, to open a file for writing or appending, set
    Sharing_mode to Deny_read_write:

        Sharing_mode = Deny_read_write;
        status = fopen( . . . );

    To open a file for reading, set Sharing_mode to Deny_write:

        Sharing_mode = Deny_write;

    When you are through using a file, reset Sharing_mode to its default
    value:

        Sharing_mode = Compatibility;


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

    Object modules are linked by 386|LINK, which is invoked by the
    hc386 command. You can link by using 386|LINK directly.  For
    example (using High C 1.7x):

        386link ads.lib jane1.obj doe.obj -lib \highc\hcc \highc\na
                -exe janedoe

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

    In this example, the linker creates an executable file called
    janedoe.exp. The arguments to 386link are as follows (.obj files are
    created by using the -c option with hc386):

      ads.lib jane1.obj doe.obj
                 The names of the object modules.

    IMPORTANT: The first module passed to the linker must be ads.lib,
    because the library contains initialization code that must be
    included from ads.lib rather than from the MetaWare run-time library.

      -lib \highc\hcc \highc\na
                 Specifies names of library files. In the example,
                 \highc\hcc and \highc\na are libraries that accompany
                 the High C compiler.

      -exe janedoe
                 The name of the executable file. 386|LINK automatically
                 appends the .exp extension to the specified filename.


    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 High C version of the
    API library is called ameapi.lib. This file is installed in the
    directory \acad\api.

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

        386link ads.lib \acad\api\ameapi.lib jane1.obj doe.obj -lib
                \highc\hcc \highc\na -exe janedoe

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

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


    6.0 NOTES ON DEBUGGING USING High C 1.7x
    ========================================

    You can debug your application with 386|DEBUG, as described in the
    file pharlap.txt, or you can use the MDB debugger from MetaWare.

    Compile your modules with the compiler command-line option -g. This
    option directs the compiler to place debugger information in the
    object files and turns off many optimizations to make debugging a
    little easier.

    IMPORTANT: The MDB debugger doesn't use the DOS-Extender bound into
    AutoCAD, so any settings you have defined with the cfig386 command
    have no effect. To configure the DOS-Extender switches to take
    effect during a debugging session, set the Phar Lap environment
    variable DOSX to the values you need. In general, you should use the
    same settings AutoCAD does: see the file pharlap.txt. You can also
    configure the switches you need into run386.exe. (MDB requires you
    to have a copy of run386.exe.)

    If you use 386|LINK directly, link your application with the switch
    -CVSYM.

    Be sure your DOS-Extender run-time file (run386.exe) is in your PATH
    and that it precedes the path for any High C directories. Follow the
    DOS-Extender run-time directory on your PATH with the .\bin
    directory of wherever you installed High C. Set the environment
    variable EXPDEBUG to ADS before starting your debugging session and
    set the environment variable DOSX to PRIVILEGED:

        set DOSX=-priv

    This step is required because AutoCAD 386 Release 12 is linked as an
    UNPRIVILEGED application and will not works with MDB otherwise.

    Start debugging with the following command:

        mdb acad

    To load the symbols of the ADS program while retaining the AutoCAD
    code, enter the MDB LOAD command:

        ->LOAD ads_app NOCODE

    If the source code for the ADS application is not in your current
    directory, enter the MDB SPATH command:

        ->SPATH = D:\what\ever

    Start the debugging with GO:

        ->GO

    AutoCAD loads the ADS applications placed in the file acad.ads at
    startup time, so with EXPDEBUG set to ADS you will hit an INT 3
    breakpoint, activated by setting EXPDEBUG, for each of these
    applications. Just use "eip++" to get around these breaks. Your
    application will reach the INT 3 breakpoint for your debugging
    session after you type "(xload "yourapp")" at the AutoCAD Command:
    prompt.

    Once you hit the breakpoint, step over the INT 3 with eip++ and then
    enter the USC command:

        ->USC

    to get the code and data selector values for your ADS application.

    To find the offset of "main", enter "main" at the MDB prompt:

        ->main

    You can now set the breakpoint in your ADS application by entering
    the B command:

        ->B 0 = 0xXX:0xYYYY

    where XX is the code selector of your ADS application and YYYY is
    the offset of main.

    Now enter GO again and you'll execute to the breakpoint in your ADS
    application.

    See the ADS appendix in the "Debugger User's Guide and Reference
    Manual" for details on debugging ADS applications with MDB.


    7.0 NOTES ON DEBUGGING USING High C/C++ 3.0
    ===========================================

    Use the batch file ADSDB.BAT provided by MetaWare to debug your ADS
    application.  You must edit this batch file to provide the correct
    setting for your AutoCAD release.  For more information see the ADS
    appendix to the MetaWare Debugger User's Guide and Reference Manual.

    AutoCAD automatically loads applications listed in the file ACAD.ADS.
    MetaWare's debugger takes care of this in the ADSDB batch file by
    executing COUNTAPP, which echos "go" and "eip++" for each application
    that is automatically loaded (before yours).


    8.0 THE mapphys ASSEMBLY MODULE
    ===============================

    Some applications need to map physical memory into the application's
    own linear address space. The assembly-language source file
    mapphys.asm for High C 1.x or m30maphy.asm for High C/C++ 3.x
    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 mapphys -twoc -i \highc\lib\src\ -d ADS

    where \highc should be replaced with the path to your installed
    High C (use m30maphy for High C/C++ 3.0).  Save a backup copy of the
    ADS library ads.lib (or m30ads.lib), then use 386|LIB to replace the
    mapphys (or m30maphy) module in the ADS library with the new module.
    For example:

        386lib ads.lib -r mapphys 

		 or

	386lib m30ads.lib -r m30maphy

    Use this new library with the modified mapphys (or m30maphy) 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 mapphys.asm (or m30maphy.asm).


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

