


                           ZTC.TXT

                Using the Zortech C++ Compiler

                        June 19, 1992


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

    1.0 INTRODUCTION
    2.0 SETTING UP THE COMPILATION ENVIRONMENT
    3.0 COMPILING THE APPLICATION WITH Zortech C++
    4.0 ASSEMBLING MODULES WITH Phar Lap 386|ASM
    5.0 LINKING OBJECT MODULES WITH Phar Lap 386|LINK
        5.1 Building an API Application
    6.0 NOTES ON DEBUGGING
    7.0 THE zcmaphys ASSEMBLY MODULE



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

    The Zortech C++ compiler can be used in the DOS-Extender(TM) (386)
    environment. The executable ADS library to use with Zortech C++ V3.0
    is called ztcads30.lib. This file can be found in the \ads
    directory. Using this compiler requires the following tools:

      Compiler   Zortech C++ Compiler V3.0

                 IMPORTANT: You must use either the Developer's Edition
                 or the Engineering and Science Edition of the Zortech
                 compiler. These editions produce 32-bit, protected-mode
                 executables. You can't use the Standard Edition, as
                 this produces only 16-bit applications.

      Linker     Phar Lap(R) 386|LINK(TM)

    The following tools are optional. You might want to use them for
    debugging your applications or assembling your own 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, release 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(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.


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

    The following environment variables are used with Zortech C++:

      ZORTECH    Pathname of the directory where the Zortech C++
                 compiler is installed. If you install the compiler with
                 the Zortech installation program, this directory
                 contains several subdirectories, including the following:

                 \bin         Contains binary executables.

                 \include     Contains system header files.

                 \lib         Contains the Zortech C++ library zps.lib.

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

      LIB        Pathname of the Zortech C++ library directory. For
                 example:
                 set LIB=\zortech\lib.

      PATH       The DOS search path must include the Zortech bin
                 directory.  For example:
                 set PATH=\zortech\bin.

      CFLAGS     Compilation flags used by the Zortech C++ compiler.
                 The following settings are recommended:

                 -c           Compile without linking.

                 -O           Generate Phar Lap OBJ format.

                 -o           Optimize using the Global Optimizer.

                 -3           Generate instructions for the 80386(TM).

                 -bx          Use protected-mode (DOS-extended)
                              executables.

                 -A           Enforce compatibility with ANSI C.

                 -a4          This is the default alignment within
                              structures for the 32-bit compiler
                              (4-byte boundary) and is required for some
                              members within structs and classes.

                 -f           Generate in-line floating-point
                              instructions.

                 -mp          Use the Phar Lap memory model.

                 For example: set CFLAGS= -c -O -o -3 -bx -A -a4 -f -mp

                 See the Zortech "Compiler Guide" for additional details
                 about these and other command-line options.

    NOTE: The ADS library is distributed along with a sample batch file,
    z30samp.bat, that contains the commands for setting these variables
    and for building the sample applications. To use the batch file to
    build all of the sample applications, invoke it as follows:

        z30samp

    or invoke it as follows to build one sample application at a time:

        z30samp <filename>

    where <filename> is the name of a sample source file (without the .c
    or .cpp filename extension).  You can edit this file to match your
    environment, if necessary.


    3.0 COMPILING THE APPLICATION WITH Zortech C++
    ==============================================

    To compile C++ source code, invoke the ztc command. For example (this
    example assumes that the compiler flags have been set by using the
    CFLAGS variable, as described in the previous section):

        ztc jane -I.\;ZORTECH\include -ojane.obj

    In this example, the arguments to the ztc command are:

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

      -I.\;ZORTECH\include
                 Specify the search path. In this case, the path is the
                 current directory (.\) and the directory that contains
                 the Zortech include files (ZORTECH\include).

      -ojane.obj
                 Specifies a name for the object file (in this example,
                 jane.obj). The default is the source file name with a
                 .obj extension. This option can also be used to
                 redirect the object file to another directory.

    See the Zortech "Compiler Guide" for additional information about 
    invoking the compiler.

    There is a clash between the alignment required within structures
    for ADS and that required for members within Zortech structs and
    classes. ADS requires byte alignment (-a1), while 32-bit Zortech
    requires 4-byte alignment (-a4). To work around this clash, the ADS
    header ads.h contains two pragmas that set the alignment to 1 at the
    top and restore it to 4 at the bottom, so that ADS structures are
    byte-aligned. If you include adslib.h (which includes ads.h) but
    require an alignment other than 4 for your code, then you need to
    set the alignment to the desired byte boundary after including
    adslib.h.

    The last pragma restoring the 4-byte alignment in ads.h is not used
    if "P386" is defined in order to use 1-byte alignment when building
    the Zortech ADS library. This information is provided in the
    unlikely case you should wish to define P386 yourself for use as a
    compiler switch.


    4.0 ASSEMBLING MODULES WITH Phar Lap 386|ASM
    ============================================

    To assemble code modules, the 386|ASM assembler can be invoked by the
    386asm command. For example (you don't need to enter the .asm filename
    extension):

        386asm doe -twoc

    Various command-line options control the assembler. See the "386|ASM
    Reference Manual" for details.

    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 try to
    run AutoCAD.


    5.0 LINKING OBJECT MODULES WITH Phar Lap 386|LINK
    =================================================

    Object modules are linked by 386|LINK, which is invoked by the 386link
    command. For example:

      386link ztcads30.lib jane.obj -lib \zortech\lib\zps -dosorder
              -exe jane

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

    This example creates an executable file called jane.exp. The arguments
    to 386link are:

      ztcads30.lib jane.obj
                 The names of the object modules.

    IMPORTANT: The first module passed to the linker *must* be the ADS
    library ztcads30.lib because the library contains initialization code
    that must replace the default initialization code in the Zortech
    run-time library (zps.lib).

      -lib \zortech\lib\zps
                 Specifies names of library files. In the example,
                 \zortech\lib\zps is the library that accompanies the
                 Zortech C++ compiler.

      -dosorder  Use DOS rules for ordering segments.

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

    The stack size of an ADS application has a minimum size of 16384
    (4000h) and can be increased by using the Phar Lap linker switch
    -STACK. This differs from non-ADS applications built with Zortech,
    which increase the stack size by either declaring a global variable
    _stack or by using the =nnnn command-line parameter. ADS
    applications ignore _stack, except to set it to the stack size set
    by the linker, and ignore the command-line parameter =nnnn.


    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 Zortech version of the
    API library is called ztcapi30.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 ztcads30.lib \acad\api\ztcapi30.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
    ======================

    The environment variable DOSX can be used to set the level of
    debugging messages from the DOS Extender. For example:

        SET DOSX=DEBUG <y>

    Where <y> is an integer in the range 1 to 5, with 5 being the most
    verbose debugging mode. A debug level of 3 is usually useful; 5 is
    overkill.

    While you're using the debugger, the environment variable EXPDEBUG
    should be set to ADS. For example:

        SET EXPDEBUG=ADS

    When you invoke 386|DEBUG, specify the AutoCAD executable
    (acad.exe), and use the -SYMFILE switch (which can be abbreviated to
    -SF) to specify your application. The -SYMFILE switch tells
    386|DEBUG to use the symbol table from a .exp file. Like all other
    switches to 386|DEBUG, this switch must precede the name of the
    executable file (you don't have to enter the .exp extension). For
    example, to debug an application called adsapp.exp, enter:

        386debug -sf adsapp acad.exe

    Use one of the following methods to debug with the same
    386|DOS-Extender switches used by AutoCAD:

        * Place the switches in the environment variable DOSX, which is
          always read by 386|DOS-Extender. Be sure to remove the
          switches from the environment variable after the debug
          session. The following line shows the switches used by AutoCAD:

          set dosx=-vm vmmdrv -minswfsize 400000 -swapdefdisk
                  -swapchk off -demandload -vscan 20000

        * Configure the switches into 386|DEBUG itself with the cfig386
          utility. After the debug session is complete, remove the
          configured switches or they will apply to all programs being
          debugged. For example:

          cfig386 386debug -vm vmmdrv -minswfsize 400000 -swapdefdisk
                  -swapchk off -demandload -vscan 20000
          386debug -sf adsapp acad.exe
          cfig386 -clear 386debug

        * Use the cfig386 utility to configure the switches directly
          into the 386|DOS-Extender file run386.exe.

    See the documentation of 386|DEBUG for the meaning of these
    switches.
 
    If EXPDEBUG has been set to ADS, then a breakpoint (INT 3) will
    occur in AutoLISP(R) before your ADS application is initialized. To
    get past the INT 3 breakpoint and enter the application, use the
    following command:

        - r eip eip+1

    At this point, the code and data selector values for your ADS
    application will be displayed (typically in the upper-left corner of
    the screen, though this can vary depending on your screen settings).
    Use the debugger's xr command to relocate the segment selector
    values so they are relative to the application (rather than to the
    AutoCAD executable). This command has the following form:

        xr <oldsel> <newsel>

    where <oldsel> is the original selector value, and <newsel> is its
    new value; for <newsel>, use the values displayed for the
    application. For example, by entering the following two commands,
    you would relocate the code selector from f to 97, and the data
    selector from 17 to 9f:

        - xr f 97
        - xr 17 9f

    You can use the xs command to view the segment selector values that
    are current.

    To set a breakpoint in the application, use the bp command in the
    following form:

        bp <codesel>:<symbol>

    Where <codesel> is the current value of the code segment selector,
    and <symbol> is a symbol in your program. For example:

        -bp 97:main

    The g command, which runs up to the specified symbol, takes the same
    form. For example:

        - g 97:sin

    Once you are executing within the ADS application, you no longer
    need to preface symbol names with the code selector value.


    7.0 THE zcmaphys ASSEMBLY MODULE
    ================================

    Some applications need to map physical memory into the application's
    own linear address space. The assembly-language source file
    zcmaphys.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 zcmaphys -twoc -d ADS

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

        386lib ztcads30.lib -r zcmaphys

    Use this new library with the modified zcmaphys 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 zcmaphys.asm.


    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.

