                                   
     +==========================================================+
              READDEV.TXT - R13c4 ADS and ARX Information
     +==========================================================+
                                   
                            30 November 1995



This file includes documentation for supported compilers and other
development tools for ADS and ARX for the Windows, Windows NT, DOS386,
and UNIX platforms.

=====================================================================-
CONTENTS
========-

  - General Information/Warnings
  - Supported Compilers
  - Sample Files Supplied
  - Rebinding MSVC++ 2.x to Work Under DOS
  - Building and Debugging ADS Programs for DOS386
  - Building and Debugging ARX Programs for DOS386
  - Building and Debugging ADS Programs for Windows
  - Building and Debugging ARX Programs for Windows
  - Building and Debugging ADS Programs for Windows NT
  - Building and Debugging ARX Programs for Windows NT
  - Building and Debugging ADS Programs for Solaris
  - Building and Debugging ARX Programs for Solaris
  - Building and Debugging ADS Programs for HP-UX
  - Building and Debugging ARX Programs for HP-UX
  - Building and Debugging ADS Programs for SGI
  - Building and Debugging ARX Programs for SGI
  - Building and Debugging ADS Programs for IBM
  - Building and Debugging ARX Programs for IBM
  - General Notes for Debugging on UNIX Platforms
  - Unlocking ARX Applications
  - WHIP Driver Considerations

The following list describes the R13c4 readme files:

README         Contains general information related to all platforms.
READPC         Contains DOS-specific and Windows-specific information.
READDOC        Contains documentation updates and revisions.
READDEV        Describes the text files that explain how to compile,
               link, and debug ADS and ARX applications, and tells
               where to find them.
READHIST       Describes the history of enhancements, fixes, and
               information related to each of the R13 update releases.



=====================================================================-
GENERAL INFORMATION/WARNINGS
============================-

Warning: adsdef.h (#included in ADS.H which is in turn #included in
ADSLIB.H) and WINUSER.H (#included in WINDOWS.H) both define X and Y,
but differently. To avoid any problems, ADSDEF.H (or any header file
that directly or indirectly #includes it) should be #included after
any header files that directly or indirectly #include WINUSER.H. This
will ensure that the correct X and Y definitions are used in all
situations.

For the Windows and NT platforms there are debuggers available that
are not documented in this file, but that may work for debugging ADS
programs in these environments. The following are some debuggers that
have been used successfully at times during the AutoCAD development
cycle. Autodesk does not in any way endorse these debuggers nor does
it supply any help in using them.

    BoundsChecker from Nu-Mega (NT and Windows)
    Win-Ice from Nu-Mega (Windows only)
    wdeb386 from Microsoft (Windows only)
    windbg and ntsd from Microsoft

The Microsoft Visual C++ 32-bit version 2.x compiler and linker, and
other tools, as shipped, can only be used under the NT operating
system environment. The Phar Lap TNT SDK version 7.x provides a
mechanism to modify these programs so that they can be used in the DOS
environment. See the section entitled "Rebinding MSVC++ 2.x to Work
Under DOS" for more information on the modification process.

AutoCAD's ADS code must have byte structure alignment. In all the
sample makefiles and batch files, as well as the MSVC++ IDE setup in
this document file, this is accomplished by explicitly setting
structure alignment to 1 globally for all code compiled.

There is a #define available called "RADPACK" which, when set, causes
all AutoCAD ADS specific code that needs to be byte aligned to be made
so. Using this #define on the compile line allows you to use other
alignment for non-ADS portions of your code while retaining byte
alignment where needed by ADS.


=====================================================================-
SUPPORTED COMPILERS
===================-

  - ADS Compilers
  - ARX-ADS Compilers

ADS Compilers
=============-
The following compilers are supported for DOS386:

+   Microsoft Visual C++ (MSVC++) 32-bit Version 2.1 and 2.2
+   MetaWare High C/C++ Version 3.21
+   Watcom C/C++ Version 10.0

MetaWare High C/C++ requires the use of the linker provided in the
Phar Lap TNT DOS-Extender SDK 6.1 (or newer).

MSVC++ 2.x requires the use of the linker provided in the Phar Lap TNT
DOS-Extender SDK 7.0 (or newer).

The following compilers are supported for Windows and Windows NT(TM)

+   Microsoft Visual C++ (MSVC++) 32-bit Version 2.1
+   Microsoft Visual C++ (MSVC++) 32-bit Version 2.2

The following compiler is supported for the Solaris platform:

+   Solaris Workshop 1.1 (C 3.0.1/C++ 4.0.1) Tools

The following compiler is supported for the Hewlett Packard HP-UX
platform:

+   Hewlett Packard A.09.69 C/Hewlett Packard A.03.50 C++ Compiler

The following compiler is supported for the SGI platform:

+   SGI C++ 4.0/C 3.19 Compiler

The following compiler is supported for the IBM platform:

+   IBM C Set++ for AIX, Version 3 Compiler


ARX-ADS Compilers
=================-
The following compilers are supported for ARX-ADS on DOS, Windows, and
Windows NT:

+   Microsoft Visual C++ (MSVC++) 32-bit Version 2.1
+   Microsoft Visual C++ (MSVC++) 32-bit Version 2.2

For ARX ADS the Phar Lap TNT DOS-Extender SDK is not required.

The following compiler is supported for the Solaris platform:

+   Solaris Workshop 1.1 (C++ 4.0.1) Tools

The following compiler is supported for the Hewlett Packard HP-UX
platform:

+   Hewlett Packard A.03.50 C++ Compiler

The following compiler is supported for ARX-ADS on the SGI platform:

+   SGI C++ 4.0/C 3.19 Compiler

The following compiler is supported for ARX-ADS on the IBM platform:

+   IBM C Set++ for AIX, Version 3 Compiler


=====================================================================-
SAMPLE FILES SUPPLIED
=====================-

  - Sample ADS Files
  - Sample ARX Files

Sample ADS Files
================-

DOS386
------
The batch and make files are distributed in the directory
DOS\ADS\SAMPLE\. This directory currently contains the following
files:

VC2SAMP.BAT    Builds the R13 DOS ADS sample programs using the 32-bit
               MSVC++ 2.1 or 2.2 compiler (see third note in the
               section entitled "General Information/Warnings" for
               information on how to modify this compiler to work
               under DOS), Phar Lap TNT SDK 7.x, and the updated
               DOSADS.LIB supplied in the ADS subdirectory.

MSVCDBG.BAT    Uses Phar Lap's SB386.EXE debugger to debug an R13 ADS
               application built with 32-bit MSVC++

HC3XSAMP.BAT   Builds the R13 DOS ADS sample programs, or a single
               program of your choice, using MetaWare High C/C++ 3.x
               and Phar Lap 6.1 (or 7.x) TNT SDK.

HC3XDBG.BAT    Uses Phar Lap's SB386.EXE debugger to debug an R13 ADS
               application built with MetaWare High C/C++ 3.x.

MKWC100.BAT    Demonstrates how to build an R13 ADS program using the
               Watcom C/C++ 10.0 compiler and linker.

W100SAMP.BAT   Builds the R13 DOS ADS sample programs, or a single
               program of your choice, using the Watcom C/C++ 10.0
               compiler and linker.


Windows/NT
----------
The batch and make files are distributed in the directory
WIN\ADS\SAMPLE\. This directory currently contains the following
files:

MKSAMP.BAT     Batch file to set up environment for building Windows
               ADS sample programs with the 32-bit MSVC++ command-line
               compiler. Requires NMAKE and the make file MKSAMP.NT.

MKSAMP.NT      Make file which uses the 32-bit MSVC++ 2.1 or 2.2
               command-line compiler to build the Windows ADS sample
               executables. Use MKSAMP.BAT to run this make file. This
               make file includes the MSVC++ standard make file for
               Win32s, NTWIN32.MAK.

WINADS.BAT     Batch file to set up environment for building Windows
               ADS programs with the 32-bit MSVC++ command-line
               compiler. Requires NMAKE and the make file WINADS.MAK.

WINADS.MAK     Make file which uses the 32-bit MSVC++ 2.1 or 2.2
               command-line compiler to build a Windows ADS
               executable. Use WINADS.BAT to run this make file. This
               make file does *not* include NTWIN32.MAK.


Unix
----
The ADS make file included with the Unix platforms can be found in the
ads/sample directory with the sample ADS programs. To build the
samples simply run the make program and it will use the supplied
makefile.


Sample ARX Files
================-

DOS386, Windows, and NT
-----------------------
The batch and make files are distributed in the directory
COM\ARX\SAMPLE\. This directory currently contains the following batch
and make files:

MKARX.BAT      Batch file to set up environment for building ARX
               programs with the 32-bit MSVC++ 2.1 or 2.2 command-line
               compiler. Requires NMAKE and the make file MKARX.MAK.

MKARX.MAK      Make file which uses the 32-bit MSVC++ 2.1 or 2.2
               command- line compiler to build an ARX program as a
               Dynamic Link Library. Use MKARX.BAT to run this make
               file. This make file does *not* include NTWIN32.MAK.

MKSAMP.BAT     Batch file to set up environment for building the ARX
               sample programs with the 32-bit MSVC++ 2.1 or 2.2
               command- line compiler. Requires NMAKE and the make
               file MKSAMP.MAK.

MKSAMP.NT      Make file which uses the 32-bit MSVC++ 2.1 or 2.2
               command- line compiler to build the ARX sample programs
               as Dynamic Link Libraries with an extension of .ARX.
               Use MKSAMP.BAT to run this make file. This make file
               includes the MSVC++ standard make file for Win32s,
               NTWIN32.MAK.

Note: ARX DLLs built on the DOS platform will also work on the Windows
and NT platforms. The reverse is also true.


Unix
----
The ARX make file included with the Unix platforms can be found in the
acrx/sample directory with the sample ADS programs. To build the
samples simply run the make program and it will use the supplied
makefile.


=====================================================================-
REBINDING MSVC++ 2.X TO WORK UNDER DOS
======================================-

To set up MSVC++ for use in DOS or a DOS window of Windows, you will
need to create a directory that will be the head of the MSVC++ tree.
For example we'll call it MSVC20 as it is on the MSVC++ CD and we'll
put it on the C drive.

Now use xcopy to copy over the full INCLUDE and LIB trees from the CD:

        xcopy /s /e g:\msvc20\include\*.* c:\msvc20\include\
        xcopy /s /e g:\msvc20\lib\*.* c:\msvc20\lib\

where g: is the CD ROM drive with the MSVC++ 2.x CD in place.

Now you'll need to copy over a few files into a BIN subdirectory:

        xcopy g:\msvc20\bin\cl.exe  c:\msvc20\bin\
        xcopy g:\msvc20\bin\cl.err  c:\msvc20\bin\
        xcopy g:\msvc20\bin\c1.exe  c:\msvc20\bin\
        xcopy g:\msvc20\bin\c1.err  c:\msvc20\bin\
        xcopy g:\msvc20\bin\c1xx.exe  c:\msvc20\bin\
        xcopy g:\msvc20\bin\c2.exe  c:\msvc20\bin\
        xcopy g:\msvc20\bin\c23.err  c:\msvc20\bin\
        xcopy g:\msvc20\bin\cl32.msg  c:\msvc20\bin\
        xcopy g:\msvc20\bin\lib.exe  c:\msvc20\bin\
        xcopy g:\msvc20\bin\link.exe  c:\msvc20\bin\
        xcopy g:\msvc20\bin\link.err  c:\msvc20\bin\
        xcopy g:\msvc20\bin\nmake.exe  c:\msvc20\bin\
        xcopy g:\msvc20\bin\nmake.err  c:\msvc20\bin\
        xcopy g:\msvc20\redist\msvcrt20.dll  c:\msvc20\bin\

In addition you will need to have the Phar Lap TNT SDK 7.x's BIN
subdirectory on your DOS path.

Now you must do a one time modification to some of the MSVC++ files.
To do this you need to add the Phar Lap BIN subdirectory to the path
long enough to do the modification. Once the path is set, run the
following at the DOS command line:

      bindvc2 c:\msvc20

If C:\MSVC20 is not the location of the root of the tree just made
above then change the command line accordingly.

You now have an MSVC++ tool set that will run under DOS.


=====================================================================-
BUILDING AND DEBUGGING ADS PROGRAMS FOR DOS386
==============================================-

  - Building ADS with Microsoft Visual C++ 2.1 or 2.2
  - Debugging ADS Programs built with MSVC++ 2.1 or 2.2
  - Building ADS using MetaWare High C/C++ 3.2x
  - Debugging ADS built with MetaWare High C/C++ 3.2x
  - Building ADS Programs using Watcom 10.0
  - Debugging ADS built with Watcom C/C++

Building ADS with Microsoft Visual C++ 2.1 or 2.2
=================================================-
Files for MSVC++ 32-bit 2.1 or 2.2:
VC2ADS13.LIB   DOS386 ADS library for MSVC++ 32-bit version 2.x and
               Phar Lap 7.x
DOSADS.LIB     Updated Phar Lap library -- see note below
DOSADS20.LIB   Phar Lap library for MSVC++ 2.x support
VC2ADS13.LNK   386LINK indirect command file
VC2SAMP.BAT    Sample batch file to build the sample ADS programs

R13 DOS386 ADS using the MSVC++ 32-bit compiler is essentially the
same as the method used by Phar Lap for R12. The only difference is
that the ADS library and linker response file names are different. So,
for more information take a look at the documentation on building ADS
programs with MSVC++ that comes with the Phar Lap TNT SDK (just
remember the file name changes for R13).

In order to use the MSVC++ 2.1 or 2.2 compiler under DOS, it must be
modified with Phar Lap's TNT SDK version 7.x (see the section entitled
"Rebinding MSVC++ 2.x to Work Under DOS" for more information about
the modification).

To use the VC2SAMP.BAT file to build an ADS program, you will need to
edit the batch file to set the paths to match your particular
machine's environment. The batch file is documented, so changing the
settings should be fairly straight forward.

To use the VC2SAMP.BAT file to build all the sample programs, at the
DOS command line type:

      VC2SAMP

To use the VC2SAMP.BAT file to build a single sample program, at the
DOS command line type:

      VC2SAMP <filename>

where <filename> is the name of desired sample file without the .C
extension.

For more information take a look at the batch file.

Note: For MSVC++ ADS the Phar Lap library DOSADS.LIB is used. This
library comes with the Phar Lap TNT SDK but the version of this
library that comes with Phar Lap TNT SDK 7.0 has a problem that causes
errors when multiple ADS programs are (xunload)ed in an order other
than the reverse of the order they were (xload)ed. Phar Lap has fixed
this problem and the fixed DOSADS.LIB is included with this AutoCAD
release.

The DOSADS.LIB file is located in the LIB subdirectory of the Phar Lap
TNT SDK directory tree. For TNT 7.0 you will need to copy the newer
file supplied with AutoCAD over the file already present in this
directory. Phar Lap TNT SDK version 7.0_ACAD1 (which is the version
used to build AutoCAD R13c2) already has the "fixed" DOSADS.LIB file.


Debugging ADS Programs built with MSVC++ 2.1 or 2.2
===================================================-
Debugging an MSVC++ ADS program in AutoCAD R13 DOS386 is essentially
the same as the technique described in the Phar Lap document
"Developing AutoCAD ADS Applications with Microsoft Visual C++, 32-Bit
Edition". However, you will need to use the MSVCDBG.BAT file supplied
with AutoCAD instead of the DBGADS.BAT file supplied with Phar Lap.
The MSVCDBG.BAT file will use the ads.cmd file in the Phar Lap BIN
directory.

First you will need to modify the MSVCDBG.BAT file to set the DOS
environment variables to match your system.

Now you are ready to start up the MSVCDBG.BAT file. The normal syntax
to start this batch file is:

      msvcdbg [appname] [add'l SB386 switches]

If you have a dual screen monitor setup you should also use the -
SWAPMON switch to tell SB386 to use both monitors:

      msvcdbg [appname] -swapmon [add'l SB386 switches]

If you do this, be sure that you have AutoCAD configured to use only a
single monitor.

Once you have started the MSVCDBG.BAT file you should see AutoCAD
start up on the primary monitor. At the AutoCAD "Command:" prompt, you
should (xload) your ADS program.

Warning: If you are using the Vibrant display driver that ships with
AutoCAD, be sure you do NOT have the text screen up in its "dialog"
mode when you (xload) your program. If you do, the debugger's screen
may be completely corrupted, preventing you from properly using the
debugger.

As the ADS program is (xload)ed, an int 3 will be triggered in the ADS
program's startup code and the debugger will gain control. The source
window will show the assembly code for the ADS program's startup code.
At this point you are in your ADS program so you can use debugger
commands to set breakpoints, watch points etc. Most likely, though,
you will want to execute a little more code to get to some point where
you can see your program's source. To do this you will need to use the
'g' command with the name of some function or other symbol in your
source.

For example, FACT.C has a function called "funcload". The debugger
command "g funcload" will cause a temporary breakpoint to be set at
the start of the function "funcload" and then start FACT going again
until the temporary breakpoint at the start of funcload is triggered.
At this point you should see the source of FACT.C in the source window
of the debugger with the current line being the last line to be
executed before the funcload function is entered.

Now you can set break points and watch points based on line numbers as
well as symbol names. If you elected to use the -HOTKEY debugger
switch (described in the MSVCDBG.BAT files as well as the SB386
manual), then you can also use the <CTRL>-<ALT> key combination to
return control to the debugger at any time at which point you can set
break points, watch points, etc.


Building ADS using MetaWare High C/C++ 3.2x
===========================================-
Files:
ADS.LIB        R13 DOS386 ADS library for MetaWare High C/C++
HC3XSAMP.BAT   Sample batch file to build an ADS program

The batch file HC3XSAMP.BAT in the SAMPLES directory shows the proper
environment and switch settings to build an ADS program for AutoCAD
DOS386 using MetaWare High C/C++ 3.2x and Phar Lap 7.x.

The batch file will build all the sample files or a single user
specified file if the file name (with no extension) is fed to the
batch file as the first parameter.

You will need to edit the batch file to set the paths to match your
particular machine's environment. The batch file is documented, so
changing the settings should be fairly straightforward.

For more information take a look at the batch file.


Debugging ADS built with MetaWare High C/C++ 3.2x
=================================================-
You may need to use Phar Lap's SB386.EXE debugger since MetaWare's
debugger may not work with this version AutoCAD Release 13. Contact
MetaWare for more information on their debugger.

To debug an ADS program with SB386.EXE, first build the program with
full debug information. The sample batch file HC3XSAMP.BAT has a
compile/link line that includes the -g compiler switch and the -
fullsym linker switch that will build a program with full debug
information:

      hc386 %1.c %hcopts% -Hpro=hcsamp.pro -g -Hkeep -Hldopt=-fullsym

This line is commented out in the batch file so if you wish to use it
you will need to comment out the standard build line:

      hc386 %1.c %hcopts% -Hpro=hcsamp.pro -Hkeep

and then uncomment the debug compile line.

Once the program is built, you can use the HC3XDBG.BAT batch file to
start up the debugger and AutoCAD with the symbol table of your ADS
program. The HC3XDBG.BAT batch file will need to be edited to update
the paths to fit your machine's environment. For more information on
this take a look in the batch file.

Once the settings are correct, you can execute the batch file with the
name of your program (without the extension) as the first parameter.
This will start up the debugger; tell it to load your program's symbol
table, and launch AutoCAD.

Once started, the debugger will come up and stop, waiting for input.
Type "g" followed by <CR> to get it started loading AutoCAD. Execution
will again stop when the ACADAPP.EXP ADS program is loaded via the
ACAD.ADS autoload mechanism triggering an int 3. At this point type "r
eip eip+1" followed by <CR>. This will step past the int 3. Now type
"g" and press <CR> to continue loading AutoCAD.

When AutoCAD is fully loaded and at the "Command:" prompt you may
(xload) your ADS program.

Warning: If you are using the Vibrant display driver that ships with
AutoCAD, be sure you do NOT have the text screen up in its "dialog"
mode when you (xload) your program. If you do, the debugger's screen
may be completely corrupted, preventing you from properly using the
debugger.

When your ADS program xloads, it will trigger an int 3 which will pass
control back to the debugger. At the debugger command line, you must
execute the command "r eip eip+1" to step past the int 3. At this
point you will need to use the debugger's "t" command to step through
the code one line at a time until you are in your ADS program's
startup code. This will take about 54 "t"s. The number may be
different for different revisions of the ADS startup code so it would
be best to execute the "t" commands manually once to determine the
exact number of executions of "t" required. Once you know the exact
number, you can use "t xx" where "xx" is the number of "t" commands
you wish to have executed.

To do this manually:

1.  Execute "t" commands until you get to the first "CALL"
    instruction in the code shown in the debugger's source window.
    This should take about six "t" commands.
2.  Execute more "t" commands until you get to the first "CALLF"
    instruction. This should take about forty-seven "t" commands.
3.  Execute one "t" command to step into the "CALLF".

At this point, you are inside the startup code of your ADS program.

Now you need to reset the locations of the code and data segment
selectors for the symbol table for your program. To do this:

1.  Type in "xr c cs" followed by <CR> to relocate the code segment
    selector.
2.  Type in "xr 14 ds" followed by <CR> to relocate the data segment
    selector.

At this point you can set break points, watch points, etc. You must
set at least one breakpoint in your code that will be triggered in
order to allow the debugger to regain control at some point. If you
elected to use the -HOTKEY debugger switch (described in the
HC3XDBG.BAT file as well as the SB386 manual), then you can also use
the <CTRL>-<ALT> key combination to return control to the debugger at
any time at which point you can set break points, watch points, etc.


Building ADS Programs using Watcom 10.0
=======================================-
Files:
WCADS100.LIB   R13 DOS386 ADS library for Watcom 10.0
MKWC100.BAT    Sample batch file to build an ADS program

Using the Watcom compiler to build ADS programs for R13 DOS386 is the
same as it was in R12. What's supplied with AutoCAD is the library
file and a sample batch file that will build an ADS program. This
batch file is very simple, but it does demonstrate the commands and
switches.

You will need to edit the MKWC100.BAT file to set the DOS environment
variables to match your system.

To use the mkwc100.bat file, at the DOS command line type:

      MKWC100 <filename>

where <filename> is the name of your source file without the .C
extension.

If you are working with C++, the WPP386 compiler must be used instead
of WCC386 so you will need to change this in the MKWC100.BAT file.


Debugging ADS built with Watcom C/C++
=====================================-
Note: With earlier versions of AutoCAD, the "DOSX" environment
variable was required to be set to "-priv" in order to debug with the
Watcom debugger. This should not be done with Release 13.

You will need to have at least the 'A' level patches applied to the
Watcom compiler and linker. You will also need the updated ADSHELP.EXP
file available from Watcom. The A and B level patch files do *not*
contain the ADSHELP.EXP file necessary to use the Watcom debugger with
AutoCAD R13.

Make sure the ADSHELP.EXP file is called out in the ACAD.ADS file
(with appropriate path if the directory containing the ADSHELP.EXP
file is not on the ACAD search path).

Set the necessary DOS environment variables (such as ACAD and ACADCFG)
and add the Watcom BIN directory and the location of the ACAD.EXE file
to the path so that the debugger and acad can be found to be executed.

Now start the Watcom Debugger.  For single monitor systems use:

      wd /tr=ads /swap

for dual monitor systems you can use:

      wd /tr=ads /two /monochrome

There are other switches that might be useful. See the Watcom
documentation for more information.

When the debugger screen appears it should display a dialog box
prompting for the filename of an executable to debug. You do not want
this, so either press ESC or select the CANCEL button to close down
the dialog box.

Now Select "Command" from the File pulldown menu and enter the
following in the dialog box that comes up:

      ads <fullpath>\<filename>

where <fullpath> is the path to your program file and <filename> is
the name of the program including the .EXP extension.

AutoCAD will now start. At the Command: prompt type

      (xload "<fullpath>/<filename>")

<fullpath> is the same as before,  but you must use "/" instead of "\"
as the directory separators (this is LISP after all).

This should trigger the debugger and place you at the main() function
in your source code. You are now free to set break points, watches,
etc.


=====================================================================-
BUILDING AND DEBUGGING ARX PROGRAMS FOR DOS386
==============================================-

  - Building ARX .DLLs using MSVC++ 32-bit under DOS
  - Debugging ARX Programs using Codeview(TM)

Building ARX .DLLs using MSVC++ 32-bit under DOS
================================================-
Files:
RXAPI.LIB      Essential ARX management functions
ACAD.LIB       ARX library of ADS functions
MKARX.BAT      Sample batch file to build an ARX program
MKARX.MAK      Make file used by mkarx.bat

It is possible to build working ARX DLLs outside of the NT
environment. You will need to use the MSVC++ 2.1 or 2.2 compiler and
linker modified with Phar Lap's TNT SDK version 7.x (see the section
entitled "Rebinding MSVC++ 2.x to Work Under DOS" for more information
about the modification).

The batch file MKARX.BAT will set the necessary DOS environment
variables and then launch nmake.exe telling it to use the mkarx.mak
make file. You will need to change the mkarx.bat file so that the PATH
and SET statements are correct for your machine before you use it.

To use mkarx.bat you need to provide it with one parameter which is
the filename of the .CC file (or .CPP if you've changed the "EXT"
variable in the mkarx.mak file) you wish to compile into an ARX .DLL.
For example, to build FACT.CC type "MKARX FACT" at the DOS command
line.

For more information take a look at the comments in the mkarx.bat and
mkarx.mak files.


Debugging ARX Programs using Codeview(TM)
=========================================-
Currently the Phar Lap version of Codeview will not work with
AutoCAD(R) Release 13. Phar Lap is working on this problem. Contact
them for more information.


=====================================================================-
BUILDING AND DEBUGGING ADS PROGRAMS FOR WINDOWS
===============================================-

  - Building ADS using MSVC++ 32-bit
  - Debugging ADS using 32-bit Codeview

Building ADS using MSVC++ 32-bit
================================-
Files:
WINADS.BAT     Sample batch file to build a Windows ADS program.
               Requires WINADS.MAK.
WINADS.MAK     Sample makefile for Windows ADS.

To Build a Windows ADS program in Windows, you will need the MSVC++
2.1 or 2.2 compiler and linker modified with Phar Lap's TNT SDK
version 7.x (see the section entitled "Rebinding MSVC++ 2.x to Work
Under DOS" for more information about the modification).

You will need to edit the DOS environment variable settings in the
WINADS.BAT file so that they are properly initialized for your system.

Unless your ADS program contains Windows specific code that requires a
.DEF and/or .RC file, you will not need any .DEF or .RC files as was
necessary in AutoCAD Release 12 for Windows.

To build your program:
1.   Open a DOS window (or work directly from DOS).
2.  At the DOS command prompt, execute the WINADS batch file with the
    name of your source file as a parameter.

For example, to build FACT.C you would use:

      WINADS fact


Debugging ADS using 32-bit Codeview
===================================-
First, build your ADS program with full debug information.

Now start up AutoCAD.

Now, start up Codeview. You can create an icon in one of your Program
Manager groups that executes the command:

      CVW.EXE

If this executable is not in your path, then you will also need to
include the path to its location:

      <path>\CVW.EXE

You can add a "/50" to the command line to get 50 line VGA display in
the Codeview window. If you have a dual monitor system a /2 on the
command line will cause Codeview to use the monochrome screen for its
display with AutoCAD on the color screen.

You might also wish to specify the working directory to be the
location of your ADS program's source code and executable.

Once Codeview is running, it will bring up a dialog that allows you to
choose the .EXE you wish to run and debug. Once you have made your
selection, the dialog will go away and Codeview will halt waiting for
input from you. At this point you need to open a source window from
Codeview with your ADS program's source file in it. Within the source
window you can select lines to be breakpoints and select variables to
view.

Once you have set your breakpoints, type "G" in the command window or
pick "Go" from the "Run" pulldown or just press the "F5" key. When you
do this Codeview will start up your application.

Now switch back to the AutoCAD window and (XLOAD) your ADS program.
When your program has loaded and AutoCAD is back at the "Command:"
prompt, go ahead and execute your program so that one of the
breakpoints you set is triggered. When the breakpoint is triggered,
the Codeview window should come to the front sitting at the breakpoint
you've set. You're on your way.


=====================================================================-
BUILDING AND DEBUGGING ARX PROGRAMS FOR WINDOWS
===============================================-

  - Building ARX with MSVC++ 2.1 or 2.2
  - Debugging ARX with Codeview

Building ARX with MSVC++ 2.1 or 2.2
===================================-
To build an ARX program in the Windows environment you must use the
DOS command line version of the MSVC++ 2.1 or 2.2 compiler and linker
modified with Phar Lap's TNT SDK version 7.x (see the section entitled
"Rebinding MSVC++ 2.x to Work Under DOS" for more information about
the modification).

The method is the same as that used in the DOS environment (see the
section entitled "Building ADS with Microsoft Visual C++ 2.1 or 2.2").
In order to get a DOS prompt, you must work in a DOS window.


Debugging ARX with Codeview
===========================-
First, build your ARX program with full debug information.

Now we run into an interesting problem with Win32s and Codeview. If
the program being debugged (ACAD.EXE in this case) starts up a second
program (in this case any ADS program in the ACAD.ADS file), Codeview
will lockup and so will ACAD.EXE. If the ADS programs specified in the
ACAD.ADS file are already running when AutoCAD tries to (xload) them,
AutoCAD will just attach to the running ADS programs rather than
trying to start them up again.

So, using File manager (or icons you create yourself), you need to
execute all the programs specified in the ACAD.ADS file. An unmodified
ACAD.ADS will have the file ACADAPP.EXE specified in it. So, at the
very least you will need to execute this ADS program.

Now, start up Codeview with the following command line:

      CVW.EXE /L <path and name of ARX DLL>.DLL <path to
ACAD.EXE>\ACAD.EXE

The /L tells Codeview to load debug information for the .DLL named.
The last file name on the command line is the application that
Codeview will actually launch when you tell it to "Go". For a 50-line
VGA display in the Codeview window, you can add a "/50" to the command
line. If you have a dual monitor setup you can add a "/2" to make
Codeview use the monochrome monitor for its text display.

To run Codeview you can create an icon with the command line above and
specify the working directory to be the location of your ARX program's
source code and .dll.

Once Codeview is running and has loaded the DLL's debug info, it will
halt, waiting for input from you. At this point you need to open a
source window from Codeview with your ARX program's source file in it.
Within the source window you can select lines to be breakpoints and
select variables to view.

Once you have set your breakpoints, type "G" in the command window or
pick "Go" from the "Run" pulldown or just press the "F5" key. When you
do this Codeview will start up AutoCAD.

Once AutoCAD has initialized and is at the "Command:" prompt, you can
(ARXLOAD) your ARX program. Don't forget to specify the .dll
extension. When your program has loaded and AutoCAD is back at the
"Command:" prompt, go ahead and execute your program so that one of
the breakpoints you set is triggered. When the breakpoint is
triggered, the Codeview window should come to the front located at the
breakpoint you've set.


=====================================================================-
BUILDING AND DEBUGGING ADS PROGRAMS FOR WINDOWS NT
==================================================-

  - Building ADS with the MSVC++ 2.x IDE
  - Debugging ADS with the MSVC++ 2.x IDE

Building ADS with the MSVC++ 2.x IDE
====================================-
Create a Project containing the .C or (.CPP), RC, and .def files for
your program and the WINADS.LIB file provided in the ADS directory of
AutoCAD. Standard ADS apps are Windows EXEs.

Note: Unless your ADS program contains Windows specific code that
requires a .DEF and/or .RC file, you will not need any .DEF or .RC
files.

To create a project:
1.  From the "File" pulldown, select "New".
2.  Select "Project" in the dialog that appears.
3.  In the next dialog, enter your desired project name in the
    appropriate edit box. Select "Application" as the project type.
    Fill in the directory information as you desire. Then select
    "Create".
4.  The "Project files" dialog appears next. Here you select the
    source (.C, .CPP, etc.), definition (.DEF), resource (.RC), and
    library (.LIB) files to use in your project.
    For a standard "plain" ADS program you shouldn't need any .def or
    .rc files, but you will need to include your source files and the
    WINADS.LIB file in the WIN\ADS directory.
5.  When selection is done select "Close" to close this dialog box.

Now it's time to set up the build environment.
6.  In the "Project" pulldown, select "Settings" to bring up the
    "Project Settings" dialog. Initially the "Settings for:" list box
    should have both "Win32 Debug" and "Win32 Release" highlighted so
    all setting changes will apply to both.
7.  Select the "C/C++" tab to bring forward the compiler settings.
    Here are the categories and appropriate settings. Settings not
    shown can be left as the default values. Other settings may work,
    but these have been tested:

General
  Preprocessor Definitions
    -> add "WIN, ADS" to the list
Code Generation
  Struct Member Alignment -> 1 byte
Precompiled Headers -> defaults are adequate
Optimizations -> defaults are adequate
C Language -> defaults are adequate
C++ Language -> defaults are adequate
Preprocessor
  Additional Include Directories -> add in the path to the
    \common\ads directory and any others you may wish
Listing Files -> defaults are adequate

    You may also add the COMMON\ADS\ directory path to the general
    MSVC++ IDE include search paths and leave it out of "Additional
    Include Directories" edit box.

    If your code requires structure alignment other than 1 byte, you
    can use the following settings instead of the same lines shown
    above:

General
  Preprocessor Definitions
    -> add "WIN, ADS, RADPACK" to the list
Code Generation
  Struct Member Alignment -> <any value you want>

    This will force single byte alignment for the AutoCAD code that
    requires it while allowing other code in the program to use a
    different alignment.

8.  Now select the "Link" tab to bring forward the linker settings.
    Here are the categories and appropriate settings. Settings not
    shown can be left as the default values. Other settings may work,
    but these have been tested:

General
  Output File Name -> If you want a name other than the project
    name then enter it here.

Note: If you do specify a file name,  you *must* include an ".exe"
extension. MSVC++ 2.x will not do this automatically.

Output -> defaults are adequate
Input -> defaults are adequate
Customize -> defaults are adequate
Debug -> defaults are adequate

9.  That does it for the settings, so select the "OK" button to close
    the dialog.

Now you're ready to build.


Debugging ADS with the MSVC++ 2.x IDE
=====================================-
Build your ADS program with full debug information.

Now set your breakpoints. To do this you need to have your source in
the edit window (use File/Open to access the necessary source files).
You then set the cursor on the line where you want a break point and
then use the "Breakpoints" option in the "Debug" pulldown (or press
the F9 key) to set the breakpoint.

Now, Use the "Go" option in the "Debug" pulldown to launch your ADS
program. In the lower left corner of the MSVC++ window you should see
the message that symbols are being loaded, the "Locals for" window
should appear, and the "debug" toolbar should appear. At this point
the program is loaded, but it uses a hidden window so you can't see
anything.

Now start up AutoCAD (if it's not already running) and (xload) your
program. Once AutoCAD is loaded do whatever is necessary to run your
application.

When code execution reaches a breakpoint in your program, the MSVC++
IDE window should come to the top, and the line with the breakpoint
should have a yellow arrow to the left of it, indicating a triggered
breakpoint.

You can now set watches and do whatever else you wish for debugging.


=====================================================================-
BUILDING AND DEBUGGING ARX PROGRAMS FOR WINDOWS NT
==================================================-

  - Building ARX with the MSVC++ 2.x IDE
  - Debugging ARX with the MSVC++ 2.x IDE

Building ARX with the MSVC++ 2.x IDE
====================================-
Create a Project containing the .CPP and .DEF files for your program
and the RXAPI.LIB and ACAD.LIB files provided in the ACRX\LIB\
directory of AutoCAD. ARX applications are Dynamic-link libraries.

To create a project:
1.  From the "File" pulldown, select "New".
2.  Select "Project" in the dialog that appears.
3.  In the next dialog, enter your desired project name in the
    appropriate edit box. Select "Dynamic Link Library" as the
    project type. Fill in the directory information as you desire.
    Then select "Create".
4.  The "Project files" dialog appears next. Here you select the
    source (.CPP), definition (.DEF), resource (.RC), and library
    (.LIB files to use in your project.
    For a "plain" ARX ADS program you shouldn't need any .RC files,
    but you will need to include your source files, a .DEF file (take
    a look at the sample RXADS files for examples of source and .DEF
    files), and the RXAPI.LIB file in the COMMON\ADSRX\LIB\
    directory.
5.  When selection is done select "Close" to close this dialog box.

Now it's time to set up the build environment.
6.  In the "Project" pulldown, select "Settings" to bring up the
    "Project Settings" dialog. Initially the "Settings for:" list box
    should have both "Win32 Debug" and "Win32 Release" highlighted so
    all setting changes will apply to both.
7.  Select the "C/C++" tab to bring forward the compiler settings.
    Here are the categories and appropriate settings. Settings not
    shown can be left as the default values. Other settings may work,
    but these have been tested:

General
  Preprocessor Definitions -> add "RADPACK, ACRXAPP" to
    the list
Code Generation -> defaults are adequate
Precompiled Headers -> defaults are adequate
Optimizations -> defaults are adequate
C Language -> defaults are adequate
  C++ Language -> defaults are adequate
Preprocessor
  Additional Include Directories -> add in the path to the
    \common\ads and \common\adsrx\inc directories and any
    others you may wish
Listing Files -> defaults are adequate

8.    Now select the "Link" tab to bring forward the linker settings.
Here are the categories and appropriate settings. Settings not shown
can be left as the default values. Other settings may work, but these
have been tested:

General
  Output File Name -> enter the desired name. If you use an
    extension other than .dll,  MSVC++ 2.x will use it. We
    recommend that you use the extension .ARX because this
    is the default extension that AutoCAD will use for ARX
    applications.

Note: MSVC++ 2.x may not automatically place an extension on the final
DLL file. So, if you do not include an extension then there will be no
extension on the final DLL file.

Output
  Base Address -> 1c000000
  Entry-Point Symbol -> DllEntryPoint@12
Input -> defaults are adequate
Customize -> defaults are adequate
Debug -> defaults are adequate

9.  That does it for the settings, so select "OK" to close the
    dialog.

Now you're ready to build.


Debugging ARX with the MSVC++ 2.x IDE
=====================================-
Create the ARX .DLL with full debug information in the compile and
link.

In the "Project" pulldown select "Settings" to bring up the "Project
Settings" dialog. Click on the "Debug" tab to bring the debug settings
forward. Here are the three important settings:

Executable For Debug Session -> This needs to be set to the path and
  file name of the acad.exe file (for example f:\r13\win\acad.exe).

Working Directory -> This needs to be set to the path to the directory
  you want to be current during the debugging session.

  Program Arguments -> This is where you specify any AutoCAD command
    line arguments (for example, a drawing file name and/or a script
    file name or perhaps the /c argument with the location of your
    acad.cfg and acad.ini files).
When you are done, select "OK" to close the dialog.

Now set your breakpoints. To do this you need to have your source in
an edit window (use File/Open to access the necessary source files).
You then set the cursor on the line you want a breakpoint and then use
the "Breakpoints" option in the "Debug" pulldown (or press the F9 key)
to set the breakpoint.

Now, Use the "Go" option in the "Debug" pulldown to launch AutoCAD. A
dialog will appear informing you that ACAD.EXE doesn't contain debug
information and asking if you want to continue. You do, so select
"Yes". Once AutoCAD has fully initialized to its "Command:" prompt,
you can (arxload "<myapp>") to load your application.

Note: If your ARX DLL has a file extension other than .arx then you
will need to specify the extension in the (ARXLOAD) function call. For
example, if your program is myapp.dll then you would need to use

      (arxload "myapp.dll")

to load the program in AutoCAD.

At this point, if you have no breakpoints in your program's
initialization code, AutoCAD should load your program and come back to
the "Command:" prompt. Now do whatever you normally would to execute
your program. When code execution reaches your program the MSVC++ IDE
should come to the top and you should be at your first breakpoint.
You can now set watches and do whatever else you wish for debugging.


=====================================================================-
BUILDING AND DEBUGGING ADS PROGRAMS FOR SOLARIS
===============================================-

  - Building ADS with the Solaris Workshop 1.1 (C 3.0.1/C++ 4.0.1)
               Tools
  - Debugging ADS with the Solaris Workshop DBX Debugger

Building ADS with the Solaris Workshop 1.1 (C 3.0.1/C++ 4.0.1) Tools
====================================================================-
The supplied makefile in the ads/sample directory will build the
example ADS programs. The suggested compile statement for ADS programs
is:

      cc -g <source>.c -o <output> -I<incdir> <adslib> -lm

where:
      <source> is the ADS program
      <output> is the output file name
      <incdir> is the include directory (usually /opt/acad13/ads)
      <adslib> is ads.a (usually /opt/acad13/ads/ads.a)

The -g option includes debug information in the executable and is
optional. It is only required if there is a need to debug the ADS
program. See the next section for more information on debugging.


Debugging ADS with the Solaris Workshop DBX Debugger
====================================================-
To debug ADS applications, first build the executable with debug
information. Other debuggers will likely work, but this example uses
the default Solaris Workshop DBX debugger.

Follow these steps to get AutoCAD and the application running under
the debugger.

1.  Build the application with debug information.

      % cc -g fact.c -o fact -I<incdir> ads.a -lm

2.  Start AutoCAD and xload the ADS program

3.  Since ADS uses IPC (interprocess communication), the ADS
    application will have it's own Process id (PID). Get the PID of
    the ADS application. A common way to find the PID of a running
    process is to use the ps command while greping for the ADS
    application name.

      % ps -ef | grep -i fact

4.  Attach dbx to the running ADS application by specifying the name
    and the PID.

      % dbx fact 1687

5.  The debugger should now be running. The following is an example
    debug session using the ADS sample program called fact.

The Solaris Workshop debugger honors the scope of variables, so to set
a break point on a variable within a function, you will have to "stop
in" that function first. Then execute the program to that point and
then finally set the "stop" statement. This example will show how to
set a break point to view the contents of the variable ans. This
variable is used to total the factorial in the sample application.

Use the "stop in" statement to stop in the rfact function.

      (dbx) stop in rfact

In the AutoCAD window run the program.

      Command: (fact 3)

Use "cont" to execute into the rfact function. Set a "stop" for the
variable ans. AutoCAD will now be waiting, since the debugger has
trapped execution of the program. Switch back to the dbx window. To
run  the program to the first occurrence of the variable ans use the
cont  command. The debugger will stop at ans and print the contents.
It is also possible to explicitly look at the contents with the
"print" statement.

      (dbx) cont
      stopped in rfact at line 214 in file "fact.c"
        214       ads_real ans = 1.0;
      (dbx) stop ans
      (3) stop ans -in `fact`fact.c`rfact

Now run to the next occurrence of ans. Since ans is used in a loop to
total the factorial, you can see the variable ans change every time
you run to the next occurrence.

      (dbx) cont
      stopped in rfact at line 217 in file "fact.c"
        217           ans *= n--;
      (dbx) print ans
      ans = 3.0
      (dbx) cont
      stopped in rfact at line 217 in file "fact.c"
        217           ans *= n--;
      (dbx) print ans
      ans = 6.0
      (dbx) cont

After the last time through the loop, the program will finish
execution and the answer will be printed at the AutoCAD command  line.
At this point control has returned to AutoCAD.

Occasionally it is necessary to send an interrupt to the debugger  in
order to quit without exiting AutoCAD. This is because when  AutoCAD
is running, the debugger is not really in control.


=====================================================================-
BUILDING AND DEBUGGING ARX PROGRAMS FOR SOLARIS
===============================================-

  - Building ARX with the Solaris Workshop 1.1 (C++ 4.0.1) Tools
  - Debugging ARX with the Solaris Workshop DBX Debugger

Building ARX with the Solaris Workshop 1.1 (C++ 4.0.1) Tools
============================================================-
The supplied makefile in the acrx/sample directory will build the
example ARX programs. The suggested compile and link statement for ARX
programs is:

      CC -g -KPIC +p -DACRXAPP -I<adsincdir> -I<arxincdir> -c
<source>.cc
      ld -G -o <output>.arx <output>.o <arxlib>

where:
      <source> is the ARX program
      <output> is the output file name (should always be .arx
        extension)
      <arxincdir> is the ARX include directory (usually
        /opt/acad13/acrx/inc)
      <adsincdir> is the ADS include directory (usually
        /opt/acad13/ads)
      <arxlib> is the rxapi.a (usually /opt/acad13/acrx/lib/rxapi.a)

The -g option includes debug information in the executable and is
optional. It is only required if there is a need to debug the ADS
program. See the next section for more information on debugging.


Debugging ARX with the Solaris Workshop DBX Debugger
====================================================-
To debug ARX applications, first build the executable with debug
information. Other debuggers will likely work, but this example uses
the default Solaris Workshop DBX debugger.

Follow these steps to get AutoCAD and the application running under
the debugger.

1.  Build the application with debug information.

      CC -g -KPIC +p -DACRXAPP -I<adsincdir> -I<arxincdir> -c fact.cc
      ld -G -o fact.arx fact.o rxapi.a

2.  Start AutoCAD and arxload the ARX program

3.  Get the process id (PID) of AutoCAD. Since ARX programs are
    shared libraries and become part of the running AutoCAD process
    it is necessary to get the PID of AutoCAD. Use the ps command to
    find the PID of AutoCAD.

      % ps -ef | grep -i acad

4.  Attach dbx to the running AutoCAD application.

      % dbx /opt/acad/acad 2642

5.  The debugger should now be running, but on the entire AutoCAD
    process. In order to get the debugger to find the ARX
    application, a "stop in" statement needs to be set for the
    acrxEntryPoint function. The following is an example debug
    session using the ARX sample program called fact.

      (dbx) stop in acrxEntryPoint

      (dbx) cont

Next go back to the AutoCAD window and run the program.

      Command: fact

Now that the acrxEntryPoint function is found, a "stop in" statement
is required to stop upon entering the function that contains the ans
variable.

      (dbx) stop in rfact

In the debugger window execute the program up to the program prompt
with a "cont" statement.

      (dbx) cont

The fact ARX program will be prompting for an integer value.

      Enter a value of 3.

In the debugger window use a "cont" statement to enter the rfact
function and then put in a "stop" for the ans variable.

      (dbx) stop ans

The debugger will now have control. You can now print the contents and
continue through the end of execution.

      (dbx) cont
      stopped in rfact at line 333 in file "fact.cc"
        333       while (n)
      (dbx) print ans
      ans = 3.0
      (dbx) cont
      stopped in rfact at line 333 in file "fact.cc"
        333       while (n)
      (dbx) print ans
      ans = 6.0
      (dbx) cont

After the last time through the loop, the program will finish
execution and the answer will be printed at the AutoCAD command line.
Control has returned to AutoCAD.

To exit AutoCAD properly, QUIT from the AutoCAD command line. Since
the debugger is in control still, enter "cont" statements until
AutoCAD exits.


=====================================================================-
BUILDING AND DEBUGGING ADS PROGRAMS FOR HP-UX
=============================================-

  - Building ADS with the HP A.09.69 C/ HP A.03.50 C++ Compiler
  - Debugging ADS with the Hewlett Packard XDB Debugger

Building ADS with the HP A.09.69 C/ HP A.03.50 C++ Compiler
===========================================================-
The supplied makefile in the ads/sample directory will build the
example ADS programs. The suggested compile statement for ADS programs
is:

      cc -g  -Ae <source>.c -o <output> -I<incdir> <adslib> -lm

where:
      <source> is the ADS program
      <output> is the output file name
      <incdir> is the include directory (usually /opt/acad13/ads)
      <adslib> is ads.a (usually /opt/acad13/ads/ads.a)

The -g option includes debug information in the executable and is
optional. It is only required if there is a need to debug the ADS
program. See the next section for more information on debugging.


Debugging ADS with the Hewlett Packard XDB Debugger
===================================================-
To debug ADS applications, first build the executable with debug
information. Other debuggers will likely work, but this example uses
the default HP-UX XDB debugger.

Follow these steps to get AutoCAD and the application running under
the debugger.

1.  Build the application with debug information.

      % cc -g -Ae fact.c -o fact -I<incdir> ads.a -lm

2.  Start AutoCAD and xload the ADS program

3.  Since ADS uses IPC (interprocess communication), the ADS
    application will have it's own process id (PID). Get the PID of
    the ADS application. A common way to find the PID of a running
    process is to use the ps command while greping for the ADS
    application name. With the SGI debugger you can also start up dbx
    on the ADS application name.

      % ps -ef | grep -i fact

4.  Attach xdb to the running ADS application.

      % xdb fact -P 1687

5.  The debugger should now be running. The following is an example
    debug session using the ADS sample program called fact.

The HP-UX xdb debugger honors the scope of variables, so to set a
break point on a variable within a function, you will have to set a
break point for that function first. Then execute the program to that
point and then finally set the break point for the variable. This
example will show how to set a break point to view the contents of the
variable ans. This variable is used to total the factorial in the
sample program.

Use the "stop in" statement to stop in the rfact function.

      > b rfact

In the AutoCAD window run the program.

      Command: (fact 3)

Use "c" to continue into the rfact function.

      > c

AutoCAD will now be waiting, since the debugger has trapped execution
of the program. Switch back to the dbx window. To run  the program to
the first occurrence of the variable ans use the "s" command to single
step through the function. Use print to see the contents of ans
change. Since ans is used in a loop to total the factorial, you can
see the variable ans change every time  you run to the next
occurrence.

      breakpoint at 0x0000594c
      fact.c: rfact: 214: ads_real ans = 1.0;
      >s
      fact.c: rfact: 216: while (n)
      >s
      fact.c: rfact: 217: ans *= n--;
      >print ans
      ans = 1
      >s
      fact.c: rfact: 217: ans *= n--;
      >print ans
      ans = 3
      >s
      fact.c: rfact: 217: ans *= n--;
      >print ans
      ans = 6
      >c

After the last time through the loop, the program will finish
execution and the answer will be printed at the AutoCAD command  line.
At this point control has returned to AutoCAD.

Occasionally it is necessary to send an interrupt to the debugger in
order to quit without exiting AutoCAD. This is because when  AutoCAD
is running, the debugger is not really in control.


=====================================================================-
BUILDING AND DEBUGGING ARX PROGRAMS FOR HP-UX
=============================================-

  - Building ARX with the HP A.03.50 C++ Compiler
  - Debugging ARX with the Hewlett Packard XDB Debugger

Building ARX with the HP A.03.50 C++ Compiler
=============================================-
The supplied makefile in the acrx/sample directory will build the
example ARX programs. The suggested compile and link statement for ARX
programs is:

      CC -g +z +p -DACRXAPP -I<adsincdir> -I<arxincdir> -c <source>.cc
      ld -b -c export.sym -o <output>.arx <output>.o <arxlib>

where:
      <source> is the ARX program
      <output> is the output file name (should always be .arx
        extension)
      <arxincdir> is the ARX include directory (usually
        /opt/acad13/acrx/inc)
      <adsincdir> is the ADS include directory (usually
        /opt/acad13/ads)
      <arxlib> is the rxapi.a (usually /opt/acad13/acrx/lib/rxapi.a)

The -g option includes debug information in the executable and is
optional.


Debugging ARX with the Hewlett Packard XDB Debugger
===================================================-
Unfortunately the HP xdb debugger will fail on a program that does not
include a symbol table, which is the case for AutoCAD. You can build
and run ARX applications, but debugging will not work. At the moment
ARX debugging is not supported. Hewlett Packard may have other tools
that will work, but none have been tested at this time.


=====================================================================-
BUILDING AND DEBUGGING ADS PROGRAMS FOR SGI
===========================================-

  - Building ADS with the SGI C++ 4.0/C 3.19 Compiler
  - Debugging ADS with the SGI DBX Debugger
  - Debugging ADS with the SGI CaseVision Debugger

Building ADS with the SGI C++ 4.0/C 3.19 Compiler
=================================================-
The supplied makefile in the ads/sample directory will build the
example ADS programs. The suggested compile statement for ADS programs
is:

      cc -g <source>.c -o <output> -I<incdir> <adslib> -lm

where:
      <source> is the ADS program
      <output> is the output file name
      <incdir> is the include directory (usually /opt/acad13/ads)
      <adslib> is ads.a (usually /opt/acad13/ads/ads.a)

The -g option includes debug information in the executable and is
optional. It is only required if there is a need to debug the ADS
program. See the next section for more information on debugging.


Debugging ADS with the SGI DBX Debugger
=======================================-
To debug ADS applications, first build the executable with debug
information. Other debuggers will likely work, but this example uses
the default SGI DBX debugger.

Follow these steps to get AutoCAD and the application running under
the debugger.

1.  Build the application with debug information.

      % cc -g fact.c -o fact -I<incdir> ads.a -lm

2.  Start AutoCAD and xload the ADS program

3.  Since ADS uses IPC (interprocess communication), the ADS
    application will have it's own PID. Get the process id (PID) of
    the ADS application. A common way to find the PID of a running
    process is to use the ps command while greping for the ADS
    application name. With the SGI debugger you can also start up dbx
    on the ADS application name.

      % ps -ef | grep -i fact

4.  Attach dbx to the running ADS application.

      % dbx -p 1687

      - or -

      % dbx -P fact

5.  The debugger should now be running. The following is an example
    debug session using the ADS sample program called fact.

The SGI debugger honors the scope of variables, so to set a break
point on a variable within a function, you will have to "stop in" that
function first. Then execute the program to that point and then
finally set the "stop" statement. This example will show how to set a
break point to view the contents of the variable ans. This variable is
used to total the factorial.

Use the "stop in" statement to stop in the rfact function.

      (dbx) stop in rfact

In the AutoCAD window run the program.

      Command: (fact 3)

Use "cont" to execute into the rfact function.
Set the "stop" for the variable ans.

      (dbx) cont
      (dbx) stop ans

AutoCAD will now be waiting, since the debugger has trapped execution
of the program. Switch back to the dbx window. To run  the program to
the first occurrence of the variable ans use the cont  command. The
debugger will stop at ans and print the contents. It is also possible
to explicitly look at the contents with the "print" statement.

      (dbx) cont
      (dbx) print ans
      1.0

Now run to the next occurrence of ans. Since ans is used in a loop to
total the factorial, you can see the variable ans change every time
you run to the next occurrence.

      (dbx) cont
      after line 217: ans = 3.0
      stopped in rfact at line 216
       216       while (n)
      (dbx) cont
      after line 217: ans = 6.0
      stopped in rfact at line 216
       216       while (n)
      (dbx) cont

After the last time through the loop, the program will finish
execution and the answer will be printed at the AutoCAD command  line.
At this point control has returned to AutoCAD.

Occasionally it is necessary to send an interrupt to the debugger  in
order to quit without exiting AutoCAD. This is because when  AutoCAD
is running, the debugger is not really in control.


Debugging ADS with the SGI CaseVision Debugger
==============================================-
To debug ADS applications, first build the executable with debugging
information, as described above in the 'dbx' section. Then follow
these steps to attach the CaseVision debugger to the ADS application.

1.  Start AutoCAD and 'xload' the ADS application.

2.  Start the CaseVision debugger (cvd) and provide it with the name
    of the ADS process, for example:

      % cvd -P fact

3.  The debugger will now start and attach itself to the already
    running ADS process. The instructions for the 'dbx' debugger
    apply equally well to the CaseVision debugger. In addition, the
    CaseVision debugger offers a number of additional features not
    found in the base 'dbx' debugger, namely:

    + A graphical user-interface.
    + A suite of debugging tools, like structure browsers and
      kernel-supported watchpoints.
    + Multi-process capability, which allows you run simultaneous
      debug sessions on multi-process ADS applications.
    + Detailed code analysis tools.
    + Performance and memory analysis tools.


=====================================================================-
BUILDING AND DEBUGGING ARX PROGRAMS FOR SGI
===========================================-

  - Building ARX with the SGI C/C++ Compiler
  - Debugging ARX with the SGI DBX Debugger
  - Debugging ARX with the SGI CaseVision Debugger

Building ARX with the SGI C/C++ Compiler
========================================-
The supplied makefile in the acrx/sample directory will build the
example ARX programs. The suggested compile and link statement for ARX
programs is:

      CC -g -KPIC +p -DACRXAPP -I<adsincdir> -I<arxincdir> -c
<source>.cc
      CC -shared -B symbolic -o <output>.arx <output>.o <arxlib>

where:
      <source> is the ARX program
      <output> is the output file name (should always be .arx
        extension)
      <arxincdir> is the ARX include directory (usually
        /opt/acad13/acrx/inc)
      <adsincdir> is the ADS include directory (usually
        /opt/acad13/ads)
      <arxlib> is the rxapi.a (usually /opt/acad13/acrx/lib/rxapi.a)

The -g option includes debug information in the executable and is
optional. It is only required if there is a need to debug the ADS
program. See the next section for more information on debugging.


Debugging ARX with the SGI DBX Debugger
=======================================-
To debug ARX applications, first build the executable with debug
information. Other debuggers will likely work, but this example uses
the default SGI DBX debugger.

Follow these steps to get AutoCAD and the application running under
the debugger.

1.  Build the application with debug information.

      CC -g -KPIC +p -DACRXAPP -I<adsincdir> -I<arxincdir> -c fact.cc
      CC -shared -B symbolic -o fact.arx fact.o rxapi.a

2.  Start AutoCAD and arxload the ARX program

3.  Get the process id (PID) of AutoCAD. Since ARX programs are
    shared libraries and become part of the running AutoCAD process
    it is necessary to get the PID of AutoCAD. Use the ps command to
    find the PID of AutoCAD.

      % ps -ef | grep -i acad

4.  Attach dbx to the running AutoCAD application.

      % dbx -p 15410

      - or -

      % dbx -P acad

5.  The debugger should now be running, but on the entire AutoCAD
    process. In order to get the debugger to find the ARX
    application, a "stop in" statement needs to be set for the
    acrxEntryPoint function. The following is an example debug
    session using the ARX sample program called fact.

      (dbx) stop in acrxEntryPoint

Now that the acrxEntryPoint function is found, a "stop in" statement
is required to stop upon entering the function that contains the ans
variable.

      (dbx) stop in rfact

Next go back to the AutoCAD window and run the program.

      Command: fact

In the debugger window enter execute the program up to the prompt with
a "cont" statement.

      (dbx) cont

The fact ARX program will be prompting for an integer value.

      Enter a value of 3.

In the debugger window use a "cont" statement to enter the rfact
function and then put in a "stop" for the ans variable.

      (dbx) cont
      (dbx) stop ans

The debugger will now have control. You can now print the contents and
continue through the end of execution.

      (dbx) cont
      [5] ans changed before [rfact(int): line 331]:
                     new value = 1.0;
      [5] Process  2540 (acad) stopped on watchpoint
       331  ads_real ans = 1.0;
      (dbx) cont
      [5] ans changed before [rfact(int): line 334]:
                      old value = 1.0;
                      new value = 3.0;
      [5] Process  2540 (acad) stopped on watchpoint
       334  ans *= (ads_real)n--;
      (dbx) cont
      [5] ans changed before [rfact(int): line 334]:
                      old value = 3.0;
                      new value = 6.0;
      [5] Process  2540 (acad) stopped on watchpoint
       334  ans *= (ads_real)n--;
      (dbx) cont
      [5] ans changed before [<stripped>: line 0]:
                      old value = 6.0;
                      new value = 6.0000000118788037;
      [5] Process  2540 (acad) stopped on watchpoint
      (dbx) cont

After the last time through the loop, the program will finish
execution and the answer will be printed at the AutoCAD command line.
Control has returned to AutoCAD.

To exit AutoCAD properly, QUIT from the AutoCAD command line. Since
the debugger is in control still, enter "cont" statements until
AutoCAD exits.


Debugging ARX with the SGI CaseVision Debugger
==============================================-
To debug ARX applications, first build the executable with debugging
information, as described above in the 'dbx' section. Then follow
these steps to attach the CaseVision debugger to the ARX application.

1.  Start AutoCAD and optionally 'arxload' the ARX application.
    Optionally, you may start AutoCAD under 'cvd' control directly.

2.  Start the CaseVision debugger (cvd) and provide it with the name
    of the AutoCAD process, for example:

      % cvd -P acad

      - or -

      % cvd acad (to start AutoCAD under cvd control)
3.  Since ARX applications are implemented as dynamic shared objects
    (DSO's) on IRIX, you may actually set breakpoints in the ARX
    application before it is actually loaded. The debugger with then
    'remember' the breakpoint and when the DSO is ultimately loaded,
    a breakpoint will automatically be set for you at that time. This
    is very useful for debugging program startup problems. This is
    also handy when running multiple ARX applications, where one
    breakpoint set at, for example, acrxEntryPoint, will appear in
    each ARX application as it is loaded. The instructions for the
    'dbx' debugger apply equally well to the CaseVision debugger. In
    addition, the CaseVision debugger offers a number of additional
    features not found in the base 'dbx' debugger, namely:

      + A graphical user-interface.
      + A suite of debugging tools, like structure browsers and kernel-
        supported watchpoints.
      + Detailed code analysis tools.
      + Performance and memory analysis tools.

    Additionally, if you are using the SGI 'Delta C++' compiler, you
    can also take advantage of the 'Fix and Continue' feature in the
    CaseVision debugger. With this powerful feature, you can actually
    fix bugs in your ARX process from inside a running debug session
    and then continue execution without having to re-compile the
    application. This feature, combined with the CaseVision Static
    Analyzer will greatly assist your C++ and ARX application
    development process.


=====================================================================-
BUILDING AND DEBUGGING ADS PROGRAMS FOR IBM
===========================================-

  - Building ADS with the IBM C/C++ Compiler
  - Debugging ADS with the IBM DBX Debugger

Building ADS with the IBM C/C++ Compiler
========================================-
The supplied makefile in the ads/sample directory will build  the
example ADS programs. The suggested compile statement  for ADS
programs is:

   cc -g <source> -o <output> -I<incdir> <adslib> -lm -DPROTOTYPES

where:
      <source> is the ADS program
      <output> is the output file name
      <incdir> is the include directory (usually /usr/lpp/acad13/ads)
      <adslib> is ads.a (usually /usr/lpp/acad13/ads/ads.a)

The -g option includes debug information in the executable and is
optional. It is only required if there is a need to debug the  ADS
program. See the next section for more information on debugging.


Debugging ADS with the IBM DBX Debugger
=======================================-
To debug ADS applications, first build the executable with debug
information. Other debuggers will likely work, but this example uses
the default IBM DBX debugger.

Follow these steps to get AutoCAD and the application  running under
the debugger.

1.  Build the application with debug information.

      % cc -g fact.c -o fact -I<incdir> ads.a -lm -DPROTOTYPES

2.  Start AutoCAD and xload the ADS program

3.    Since ADS uses IPC (interprocess communication), the ADS
application will have it's own PID. Get the process id (PID) of the
ADS application. A common way to find the PID of a running process is
to use the ps command while greping for the ADS application name.

      % ps -ef | grep -i fact

4.  Start dbx with the process id (PID) of the ADS application.

      % dbx -a 6464

5.  The debugger should now be running. Break points can now be set
    in the program. The following is an example debug session using
    the ADS sample program called fact. First set a break point to
    view the contents of the variable ans. This variable is used to
    total the factorial.

      (dbx) stop ans

    Next go back to the AutoCAD window and run the program.

      Command: (fact 3)

    AutoCAD will now be waiting, since the debugger has trapped
    execution of the program. Switch back to the dbx window. To run
    the program to the first occurrence of the variable ans use the
    cont  command. The debugger will stop at ans.

      (dbx) cont

    To view the contents of the variable ans, use the print command.

      (dbx) print ans
      1.0

    Now run to the next occurrence of ans. Since ans is used in a
    loop to total the factorial, you can see the variable ans change
    every time you run to the next occurrence.

      (dbx) cont
      after line 217: ans = 3.0
      stopped in rfact at line 216
       216       while (n)
      (dbx) cont
      after line 217: ans = 6.0
      stopped in rfact at line 216
       216       while (n)
      (dbx) cont

    After the last time through the loop, the program will finish
    execution and the answer will be printed at the AutoCAD command
    line. At this point control has returned to AutoCAD.


=====================================================================-
BUILDING AND DEBUGGING ARX PROGRAMS FOR IBM
===========================================-

  - Building ARX with the IBM C/C++ Compiler
  - Debugging ARX with the IBM DBX Debugger

Building ARX with the IBM C/C++ Compiler
========================================-
The supplied makefile in the acrx/sample directory will build the
example ARX programs. The suggested compile and link statement for ARX
programs is:

   xlC -g -DACRXAPP -I<arxincdir> -I<adsincdir> -c <source>
   xlC -o <output>.arx <source>.o bimport:acad.exports -e
        acrxEntryPoint

where:
      <source> is the ARX program
      <output> is the output file name (should always be .arx
        extension)
      <arxincdir> is the ARX include directory
            (usually /usr/lpp/acad13/acrx/inc)
      <adsincdir> is the ADS include directory
            (usually /usr/lpp/acad13/ads)
      <adslib> is ads.a (usually /usr/lpp/acad13/ads/ads.a)

      bimport:acad.exports tells the linker to include the acrx
            symbols from the file acad.exports. This file is located
            in /opt/acad13/acrx/lib by default.

The -g option includes debug information in the executable and is
optional. It is only required if there is a need to debug the ADS
program. See the next section for more information on debugging.


Debugging ARX with the IBM DBX Debugger
=======================================-
To debug ARX applications, first build the executable with debug
information. Other debuggers will likely work, but this example uses
the default IBM DBX debugger. Follow these steps to get AutoCAD and
the application running under the debugger.

1.  Build the application with debug information.

   % xlC -g -DACRXAPP -I<arxincdir> -I<adsincdir> -c fact.cc
   % xlC -o fact.arx fact.o bimport:acad.exports -e acrxEntryPoint

2.  Start AutoCAD and arxload the ARX program

3.  Get the process id (PID) of AutoCAD. Since ARX programs are
    shared libraries and become part of the running AutoCAD process
    it is necessary to get the PID of AutoCAD. Use the ps command to
    find the PID of AutoCAD.

      % ps -ef | grep -i acad

4.  Start dbx with the process id (PID) of AutoCAD.

      % dbx -a 15410

5.  The debugger should now be running, but on the entire AutoCAD
    process. In order to get the debugger to find the ARX
    application, a stop in statement needs to be set for the
    acrxEntryPoint function. The following is an example debug
    session using the ARX sample program called fact.

      (dbx) stop in acrxEntryPoint

    Now that the acrxEntryPoint function is found, set a break point
    to view the contents of the variable ans. This variable is used
    to total the factorial.

      (dbx) stop ans

    The debugger is controlling AutoCAD, so a "cont" statement must
    be entered. This will tell the debugger to continue execution
    which allows the AutoCAD command line to become active.

      (dbx) cont

    Next go back to the AutoCAD window and run the program.

      Command: fact

    AutoCAD will now be waiting, since the debugger has trapped
    execution of the program. Switch back to the dbx window and
    exectute another "cont" statement to get the prompt to display.

      (dbx) cont

    The fact ARX program will be prompting for an integer value.

      Enter a value of 3.

    The debugger will now have control. You can now print the
    contents and continue through the end of execution.

      (dbx) print ans
      1.0
      (dbx) cont
      after line 334: ans = 3.0
      stopped in rfact(int) at line 333
        333       while (n)
      (dbx) cont
      after line 334: ans = 6.0
      stopped in rfact(int) at line 333
        333       while (n)
      (dbx) cont

After the last time through the loop, the program will finish
execution and the answer will be printed at the AutoCAD command line.
Control has returned to AutoCAD.

To exit AutoCAD properly, QUIT from the AutoCAD command line. Since
the debugger is in control, enter "cont" statements until the program
exits.


=====================================================================-
GENERAL NOTES FOR DEBUGGING ON UNIX PLATFORMS
=============================================-

During the ADS debugging process it is suggested to avoid using the
ads_regfunc function. Since ads_regfunc will cause functions to be
called via a function pointer, the debugger may not be able to follow.
Symptoms will usually be that the ADS program can only be executed
once.

Standard printf statements can be very useful when performing debug
tasks. Output from printf appears on standard output which, for an ADS
application, will be in the shell that AutoCAD was started from.

From the debugger a function can be invoked manually. Such functions
need to be included in the link commands. A good example would be to
use the printdxf function documented in the Developer's Guide for
displaying the contents of the resbuf linked lists.

Occasionally there can be errors caused by debugging that will corrupt
the current AutoCAD session. In these cases it is best to simply
restart AutoCAD and the debugger.


=====================================================================-
UNLOCKING ARX APPLICATIONS
==========================-

Starting with R13c4, ARX applications will include a locking mechanism
to prevent their being unloaded. Whenever an ARX application is loaded
it is loaded as a locked application which means that it cannot be
unloaded. In order to unlock an ARX application so that it can be
unloaded, the ARX program must make a call to the new function
acrxUnlockApplication().

The signature for this new function is:

    extern int acrxUnlockApplication(void* appId);

The appId argument is the void* passed into the acrxEntryPoint()
function during the AcRx::kInitAppMsg call when the ARX program is
loaded.

A return value of non-zero means success.

Here's an example of using this new function:

AcRx::AppRetCode acrxEntryPoint(AcRx::AppMsgCode msg, void* ptr)
{
    switch(msg) {
    case AcRx::kInitAppMsg:
        acrxUnlockApplication(ptr);
        break;
    case AcRx::kInvkSubrMsg:
        dofun();
        break;
    case AcRx::kLoadADSMsg:
        funcload();
        break;
    case AcRx::kUnloadADSMsg:
        funcunload();
        ads_printf(/*MSG2*/"Unloading.\n");
        break;
    default:
        break;
    }
    return AcRx::kRetOK;
}

In addition, there are two more new functions that are related to the
unlocking of ARX applications.

The following is used to lock an application so it cannot be unloaded:

    extern int acrxLockApplication(void* appId);

The appId argument and return value are the same as for
acrxUnlockApplication().

The following is used to find out if an application is currently
locked or unlocked:

    extern int acrxApplicationIsLocked(const char* modulename)

The modulename argument is the name of the ARX program you wish to
check on. It returns a non-zero value if the modulename application is
locked.


=====================================================================-
WHIP DRIVER CONSIDERATIONS
==========================-

The WHIP driver is different from earlier ADI display drivers in a
number of ways. WHIP is sensitive to many application "misbehaviors"
that most other drivers can tolerate. The purpose of this section is
to describe these limitations.

  - WHIP Driver Overview
  - Programming Tips
  - ADS-ADI Link Users

WHIP Driver Overview
====================-
There are several features of the WHIP driver that it may be helpful
to understand. The specific implications of these features will be
discussed later.

1.  WHIP maintains "short-term" or non-drawing display lists as well
    as the normal "long term" or drawing display lists. Together
    these are used to do damage repair after Windows expose events.
    As far as we know, all other drivers use a backing bitmap
    instead.

    The short term display lists do not preserve drawing order (for
    the sake of performance). Instead, whole classes of things are
    drawn as groups. For example, unhilighted short terms are drawn
    after hilighted short terms. Drawing order is maintained for long
    term entities.

    The short term display lists are discarded on every redraw
    (PREDRAW) request.

    Each display list is maintained on a per-viewport basis.

2.  In the default "frame buffer" mode, the picture on the screen is
    updated only when AutoCAD asks the driver to "synchronize" the
    display, and then only if we think the screen has changed since
    it was last updated. Thus it is very important for AutoCAD or any
    ADS, AutoLISP or ARX application to cause a "synchronize" request
    to be sent when the picture MUST be updated. This can be done by
    asking for user input or by printing a prompt string.

3.  WHIP uses a special physical palette to optimize the speed of
    blitting the frame buffer to the screen. It translates from
    AutoCAD's logical palette to the physical palette as entities are
    added to its display list. Changing the AutoCAD palette is
    relatively expensive since we have to go back through the display
    list and update this translation.


Programming Tips
================-

Match up number of drawing and non-drawing erasing operations
-------------------------------------------------------------
If you draw a non-drawing entity twice and erase it once (in the same
viewport), WHIP will either fail to properly erase both copies or slow
down greatly due to its need to search all of its lists for
duplicates.


Match up highlighting and dehighlighting operations
---------------------------------------------------
If you highlight an entity twice and it dehighlight once (in the same
viewport), WHIP may fail to erase both highlights.


Dehighlight/erase exactly what you highlighted
----------------------------------------------
If you draw a polyline with vertices A, B, C, D, and E and then you
draw a highlighted polyline B, C, D, and then erase the highlighting
by drawing A, B, C, D and E, WHIP will fail because it won't be able
to match the endpoints of the erasing/dehighlighting polyline with the
endpoints of the highlighting polyline.

Note that in this example, DR_DHILIT should be set on the erasing
(dehighlighting) polyline.


ADS-ADI Link Users
==================-
The ads_adistart(), ads_adiend() bookend calls are fairly expensive
for WHIP - don't use them between minor operations such as setting a
single palette entry out of a list of hundreds.


