       Copyright (C) 1995 MetaWare Incorporated; All Rights Reserved.

                          High C/C++ Version 3.31
                       Globally Optimizing Compiler
                   for 32-Bit Extended DOS and Windows
                               January 1995

                    +---------------------------------+
                    |  Developing an ADS Application  |
                    +---------------------------------+


Table of Contents
-----------------
1.  ADS Development
2.  Building Sample ADS Programs with MAKESAMP.BAT
3.  Debugging Your ADS Application with ADSDB.BAT and MDB
4.  For AutoCAD Releases with M30ADS.LIB
5.  AutoCAD R13 Applications:  Debugging Difficulties
6.  Technical Details for Debugging ADS Applications
6.1   Need for Breakpoint Protocol
6.2   Effect of INT 3
6.3   Determining the ADS Code Selector
6.4   Getting to ADS with AutoCAD Release 11
6.5   Getting to ADS with AutoCAD Release 12
6.6   MDB Commands Generated by ADSDB
6.7   Loading Multiple Applications
6.8   Use Current Versions of ADSDB.BAT and COUNTAPP.COM
6.9   Multiple ADS Applications that Interact


1. ADS Development
------------------
The driver command-line switches for using the AutoCAD ADS.LIB library are 
as follows:

  -Hads     -  Automatically links with the Autodesk-modified initializers
               HIGHC\SMALL\INITADS.OBJ and HIGHC\SMALL\MWINTADS.OBJ.  
               (If you use this option with option -Hloclib, the LOC-
               compatible initializers HIGHC\V1X\SMALL\INITADS.OBJ and 
               HIGHC\V1X\SMALL\DOSADS.OBJ are linked in instead.)

  -Hloclib  -  Use this option only if you are linking third-party LOC-compiled 
               libraries, or if you have existing code compiled with the 
               High C 1.x compiler and are having trouble getting it to 
               recompile with a later version.  This option causes the 
               compiler to use the High C Version 1.x calling convention 
               and alignment.  It uses 1.x-compatible headers from 
               HIGHC\V1X\INC and libraries from HIGHC\V1X\SMALL.  It also 
               uses HIGHC\V1X\SMALL\LDSTUB.LIB, which takes care of how the 
               long doubles are treated (a long double is 12 bytes in High C 
               Version 3.x compilers and 10 bytes in High C Version 1.x
               compilers).

To help you develop ADS applications, two batch files, MAKESAMP.BAT and
ADSDB.BAT, are included in the HIGHC\BIN directory.

NOTE:  If you are using option -Hloclib, you must remove the old initializer 
       from ADS.LIB and modify the scripts before you use these batch files.  
       Follow these steps:

       (1) Save ADS.LIB somewhere for safety.  ADS.LIB is in your ACAD\ADS 
           directory.

       (2) Copy the file FIXADS.BAT from your HIGHC\V1X directory to your 
           ACAD\ADS directory.

       (3) Go to the ACAD\ADS directory and type:

              FIXADS

           FIXADS removes the old initializer from the ADS.LIB library.


2.  Building Sample ADS Programs with MAKESAMP.BAT.
---------------------------------------------------
MAKESAMP.BAT builds all the sample programs in the ACAD\ADS directory.
Follow these steps:

(1) Copy MAKESAMP.BAT from the BIN subdirectory to your working directory.

(2) Edit MAKESAMP.BAT to provide the correct settings for your AutoCAD release
    and for optional debugging.  (See the comments in MAKESAMP.BAT for what
    each section does.)

(3) To compile all the examples type:

       MAKESAMP

    To compile a specific example type:

       MAKESAMP <filename>


3.  Debugging your ADS application with ADSDB.BAT and MDB.
----------------------------------------------------------
Use batch file ADSDB.BAT to debug your ADS application.  You must:

* edit ADSDB.BAT to provide the correct setting for your AutoCAD release.
  (See the comments in ADSDB.BAT for what each section does.)

* compile your application for debugging.

Follow these steps:

(1) Modify MAKESAMP.BAT to select the command line for debugging.  Uncomment
    the following line in MAKESAMP.BAT:

    If you are compiling C programs
    -------------------------------
    :: hc386 -g %ADS_COMP% -f387 %1.c -Hkeep -Hpro=sample.pro

    If you are compiling C++ programs
    ---------------------------------
    :: hc386 -g %ADS_COMP% -f387 %1.cpp -Hkeep -Hpro=sample.pro

(2) Run MAKESAMP.BAT to compile your program for debugging:

        MAKESAMP yourapp

(3) Copy ADSDB.BAT to the directory that contains the application you are
    debugging.

(4) Edit ADSDB.BAT to provide the correct values for ADS_VERSION and ACADPATH
    variables.

(5) Assuming that AutoCAD is installed in C:ACAD, set the following DOS
    environment variables, depending on which AutoCAD release you are using:

    AutoCAD Release 11
    ------------------
    SET ACAD=C:\ACAD;C:\ACAD\SAMPLE;C:\ACAD\ADS
    SET ACADCFG=C:\ACAD

    AutoCAD Release 12
    ------------------
    SET ACAD=C:\ACAD\SUPPORT;C:\ACAD\FONTS;C:\ACAD\ADS;
    SET ACADCFG=C:\ACAD
    SET ACADDRV=C:\ACAD\DRV

(6) Debug the application:

       ADSDB yourapp


4. For AutoCAD Releases with M30ADS.LIB
---------------------------------------
If you have a version of AutoCAD R12 that includes M30ADS.LIB you can develop
ADS applications in both C and C++.

To use M30ADS.LIB you must modify the MAKESAMP.BAT file to select the proper
ADS_COMP variable; see MAKESAMP.BAT for details.  The ADS_COMP variable looks
like this:

    set ADS_COMP=-Hads -L%ADSPATH%\ads -lm30ads

NOTE:  M30ADS.LIB is not compatible with LOC-compiled code.  If you are
       compiling with -Hloclib, use the default setting of the ADS_COMP 
       variable, which links in ADS.LIB instead of M30ADS.LIB:

          set ADS_COMP=-Hads -Hloclib -L%ADSPATH%\ads -lads

NOTE:  If you are using the Phar Lap 386|LINK Version 5.0 or later, you
       must also use the Phar Lap linker option -nostub to generate a
       .EXP file instead of a .EXE file.


5.  AutoCAD R13 Applications:  Debugging Difficulties
-----------------------------------------------------
Because ACAD.EXE for AutoCAD R13 is in Microsoft Windows NT Portable-
Executable (PE) file format, and the MetaWare MDB debugger accepts only 
Protected-Mode Executable (EXP) format, you cannot use MDB to debug 
AutoCAD R13 ADS applications.

The Phar Lap 386|SRCBug debugger is compatible with ACAD.EXE, and you can
use it to debug C code, but it cannot debug C++ code.

You cannot use the Phar Lap CodeView 386 debugger (CV386) to debug code
compiled with High C/C++, because High C/C++ does not generate CodeView 4
symbols.


6.  Technical Details for Debugging ADS Applications
----------------------------------------------------
MetaWare's debugger, MDB, is a full-featured general-purpose debugger you can
use for all your High C/C++ programs.  Although not tailored specifically to
AutoCAD ADS applications, once the AutoCAD environment has been set up for
MDB, you can proceed with debugging as usual.  MDB has no intrinsic knowledge
about specific applications such as ADS.  To MDB, AutoCAD is an application,
and an ADS application is another application that is loaded from within
AutoCAD.


6.1 Need for Breakpoint Protocol
--------------------------------
The ADS application's environment (which is AutoCAD) must set up a protocol
for establishing breakpoints in the ADS application.  Because an ADS
application is loaded from within AutoCAD, to get access to the ADS code MDB
must first load AutoCAD.  Getting from there into the ADS application code is
difficult without the help of the ADS's application environment (AutoCAD).


6.2 Effect of INT 3
-------------------
AutoCAD inserts an INT 3 debug-break machine instruction in its XLOAD command.
Under normal operating conditions this has no effect on AutoCAD behavior,
because INT 3 simply responds with a return.  However, inside the debugger
environment, MDB traps this instruction, and thus gains control of the CPU.
So an ADS application can be debugged by first loading and running AutoCAD
within MDB.  As soon as you type XLOAD to load the ADS application into
AutoCAD, MDB receives an INT 3 trap and control is passed back to MDB.


6.3 Determining the ADS Code Selector
-------------------------------------
An ADS application resides in a different code and data segment from AutoCAD.
Immediately after INT 3, control is still in the AutoCAD code and data
segment.  To set a breakpoint in the ADS application, you must know the ADS
application code segment (sometimes called "code selector") assigned by
AutoCAD.

AutoCAD Release 11 (and prior) displays the code and data selector to be
assigned to the ADS application immediately after the XLOAD command is issued.
Getting the code-selector value from the screen is inconvenient from the
application developer's point of view, and this value may no longer be
available beginning with AutoCAD Release 12.  So, you need another way to get
to the code selector value.


6.4 Getting to ADS with AutoCAD Release 11
------------------------------------------
In AutoCAD Release 11, transfer is passed to the ADS application's initializer
after AutoCAD executes two or three instructions past INT 3.  You can set a
breakpoint in your ADS application simply by executing MDB's STEP IN command
three or four times after INT 3, and execution will be at the ADS application
code and data segment.

At this point you can type GO MAIN to get directly to the ADS application main
(this is equivalent to setting a breakpoint at main and typing GO).  Remember:
the purpose of setting this breakpoint is to skip AutoCAD code that is not
part of the ADS application, and get to the ADS application's main.  From
there you can set further breakpoints or single steps through the code as
desired, just like debugging any program.  (Simply typing GO without setting
further breakpoints would defeat the whole purpose of setting the first
breakpoint, because AutoCAD would regain control of the CPU and there is no
way to get back to MDB's interactive mode.)

For AutoCAD Release 11, MDB's commands to set a breakpoint at main are:

   eip++         // to skip over INT 3
   step in       // to skip over one instruction
   step in       // to skip over another instruction
   step in       // to skip over yet another instruction (now you have
                 //  switched to the ADS code segment)
   go main       // go to the ADS main

If you use the latest version of the ADSDB.BAT script, these MDB commands are
automatically entered for you via MDB's journal file.


6.5 Getting to ADS with AutoCAD Release 12
------------------------------------------
In AutoCAD release 12, about 100 AutoLISP instructions are executed after the
INT 3, before you get into the ADS initializer (that is, the point where
AutoCAD switches the code and data segments to the ADS application 
initializer).  The code sequence between INT 3 and the transfer to an ADS 
application consists of several instructions followed by a call to some address, 
then several more instructions, followed by a far call to the ADS application 
(be aware that MDB mistakenly displays it as near call).

The sequence of MDB commands to set a breakpoint at ADS's main is:

   eip++         // to skip over INT 3
   go till call  // to skip over to first call
   go till call  // to skip over to second call
   step in       // to step to the call
   step in       // to step into the initializer
   go main       // go to the ADS main

Pre-release versions of AutoCAD Release 12 may have a different instruction
sequence before the transfer of control to the ADS application.  If you are
using a pre-release version, you must modify the ADSDB.BAT script (see file
ADSDB.BAT for guidelines).


6.6 MDB Commands Generated by ADSDB
-----------------------------------
If you look at the MDB journal file (yourapp.jou) generated by the ADSDB.BAT
script, for AutoCAD Release 11 the following MDB commands are issued:

   main off
   flip on
   load yourapp nocode
   go

"main off" prevents MDB from skipping main.

"flip on" causes MDB to flip and refresh the graphics screen every time an
instruction is executed.  This is necessary for debugging graphics applications.

"load yourapp nocode" loads your application symbols information, but without
the code (your application must be loaded from AutoCAD via the XLOAD command).

"go" loads and runs AutoCAD.  When AutoCAD is loaded and running, you can
issue the XLOAD command to load your ADS application at any time.  Control is
passed to MDB via the INT 3 instruction trap after XLOAD.  At this point, the
remaining journal file's commands are executed, and execution is transferred
automatically into the application's main, where normal debugging can take
place.


6.7 Loading Multiple Applications
---------------------------------
AutoCAD Release 12 can load multiple applications.  Look in the AutoCAD
directory for a file called ACAD.ADS that contains a list of the applications
to be loaded after AutoCAD is loaded.  Because AutoCAD uses XLOAD to load
these applications, the debugger receives an INT 3 for each application
loaded.  To skip over breaks for applications you are not trying to debug, you
must issue the following MDB commands:

   eip++         // Skip over INT 3
   go            // Continue from here

INT 3 can be skipped only with MDB's eip++ command.  The COUNTAPP.COM program
in your distribution generates as many "eip++" "go" sequences as there are
applications listed in the ACAD.ADS file.  Make sure you have version 1.02 or
later of COUNTAPP.COM; earlier versions treated every blank line in ACAD.ADS
as an ADS application name.  To see what version of COUNTAPP.COM you have,
invoke COUNTAPP.COM; it should display the version number.  For example:

   C:> countapp
   Program: countapp (Ver 1.02) Copyright (C) MetaWare Incorporated 1991-1992
   Utility : Counts the number of ADS applications in acad.ads, and generates
              MDB commands for ADSDB.BAT script.
    Usage: your_application acad_version

6.8 Use Current Versions of ADSDB.BAT and COUNTAPP.COM
------------------------------------------------------
With the versions of ADSDB.BAT and COUNTAPP.COM you receive with this
document, you no longer have to look at AutoCAD's screen for the ADS
application code selector to set a breakpoint to main.  Control is
automatically directed to your application's main when you invoke ADSDB.

WARNING:  Due to possible differences in AutoCAD releases, the automatic
          scheme to get to the application main with ADSDB.BAT script may be
          off by a few commands.  If you understand the details described
          above, modifying the ADSDB.BAT to suit your environment may not
          be as difficult or complicated as it seems.

6.9 Multiple ADS Applications that Interact
-------------------------------------------
The information described in this document may be essential in debugging
multiple ADS applications interacting with each other.  Currently, there is no
easy way to debug multiple ADS applications simultaneously.  You cannot use
ADSDB.BAT; instead you must follow the steps described in this document to set
a breakpoint at each application, and load each application with no code at
the appropriate point.  Applications developed this way require more effort to
debug.



Document number:  RM-4702-002