Click above to get retro games delivered to your door ever month!

Remote debugging allows you to run the debugger on one side of a
communication link and the application being debugged on the other.  Remote
debugging is required when there is not enough memory to run both the
debugger and the application on the same machine.

The DOS debugger runs in protected mode (above the 1M mark), with a small
memory footprint in the first 640k.  Newer operating systems such as OS/2
and Windows NT/95 have eliminated the 640k barrier, so there is little need
for remote debugging.  Remote debugging is also required to debug Novell
NetWare applications.

There are many different communication links supported.  Some communicate
between two machines.  In this case an external communication medium is
used.  Some links communicate between two operating systems shells on the
same machine.  In either case, the concepts are the same.

While remote debugging, you may want to reference a file that is found on
one machine or the other.  See the section entitled
Specifying Files on Remote and Local Machines for details about remote and
local file names.

The debugger is broken down into 4 parts.

The Debugger
    This is the portion of the debugger that contains the user interface.
     It is the largest part of the debugger.  Its name is WD.EXE or WDW.EXE.

The Debug Kernel
    The debugger interprets your requests and sends low level requests to
    the debug kernel.  It is a small executable that is dynamically loaded
    by the debugger or a remote debug server and used to control your
    application.  It can be called STD.TRP, STD.DLL, RSI.TRP, ADS.TRP or
    PLS.TRP

Remote Trap Files-
    These are versions of the debug kernel file that take requests and send
    them across a communications link to a remote debug server.  You choose
    a trap file using the debugger's "trap" option.  See Common Switches.
     Trap files have a 3 letter file name that represents the name of the
    communications layer being used.  The file extension is TRP or DLL.

Remote Debug Servers-
    These executable files receive requests from a communications link and
    pass them to a debug kernel.  Remote debug server names all start with
    ???SERV.  The first 3 letters represent the communication layer being
    used and correspond to the trap file that is used on the other side of
    the link.

In the following examples,


     A>cmd1
     B>cmd2

indicates that cmd1 is to be run on one machine and cmd2 is to be run on the
other.

A normal non-remote debugging session just uses the user interface and the
debug kernel.  All components run on the same machine.  This simple
debugging session would be started with the command:


     A>wd app

     +-----------+ +----------+     +----------+
     |  WD.EXE   | | STD.TRP  |     | APP.EXE  |
     |          / /           |     |          |
     |          \ \           |     |          |
     |           | |          |     |          |
     +-----------+ +----------+     +----------+

Debugging a Tenberry Software DOS/4GW (32-bit extended DOS) application is
the same except you must use a different trap file to control the
application.


     A>wd /trap=rsi app

     +-----------+ +----------+     +----------+
     |  WD.EXE   | | RSI.TRP  |     | APP.EXE  |
     |          / /           |     |          |
     |          \ \           |     |          |
     |           | |          |     |          |
     +-----------+ +----------+     +----------+

A remote debugging session adds a remote debug server and a remote trap file
as well.  For example, using the parallel port to debug between two machines
would be accomplished using the following components:


     A>parserv
     B>wd /tr=par app

     +-----------+ +----------+
     |  WD.EXE   | | PAR.TRP  |
     |          / /           |
     |          \ \           |
     |           | |          |
     +-----------+ +----------+
                       |
        +-- parallel --+
        |   cable
        |
     +-----------+ +----------+     +----------+
     |  PARSERV  | | STD.TRP  |     | APP.EXE  |
     |  .EXE    / /           |     |          |
     |          \ \           |     |          |
     |           | |          |     |          |
     +-----------+ +----------+     +----------+

In order to start the above remote debugging session, you must follow these
steps.

 1. Connect the two machines with a parallel cable.  See
    Wiring For Remote Debugging.

 2. Start the remote debug server (PARSERV) on one machine.

 3. Start the debugger with the option "/trap=PAR" on the other machine.
     This causes the debugger to load the remote trap file (PAR).  This will
    communicate across the remote link to PARSERV.EXE, which will in turn
    communicate with the debug kernel (STD) in order to debug the
    application.

The rest of the debugger command line is identical to the command you would
type if you were debugging the application locally.

You must start the remote debug server first.  If you do not, the remote
trap file will not be able to establish a communication link and the
debugger will refuse to start.

It is important to realize that the application to be debugged must reside
on the debug server machine.  It must be possible for the debug server to
locate the application to be debugged.  It can be in the current working
directory of the debugger server machine, or in the PATH, or a path to
locate the application on the debug server machine can be specified on the
debugger command line.  Alternatively, you can ask the debugger to download
the application to the debug server machine if the application resides on
the debugger machine.


     A>parserv
     B>wd /down /tr=par app

See the description of the "download" option in the section entitled
Common Switches.

If you are remote debugging a 32-bit application, you must use the correct
trap file on the remote debug server side of the link.  The trap file
specification must come first before any other arguments on the command
line.


     A>serserv /tr=rsi
     B>wd /tr=ser app

     +-----------+ +----------+
     |  WD.EXE   | | SER.TRP  |
     |          / /           |
     |          \ \           |
     |           | |          |
     +-----------+ +----------+
                       |
        +--- serial ---+
        |    cable
        |
     +-----------+ +----------+     +----------+
     |  SERSERV  | | RSI.TRP  |     | APP.EXE  |
     |  .EXE    / /           |     |          |
     |          \ \           |     |          |
     |           | |          |     |          |
     +-----------+ +----------+     +----------+

Following is an example of an internal remote link.  This example shows you
how to use the OS/2 version of the debugger to debug a DOS application.


     +-----------+ +----------+
     |  WD.EXE   | | NMP.DLL  |
     |          / /           |
     |          \ \           |
     |           | |          |
     +-----------+ +----------+
                          |
        +-- OS/2 NP API --+
        |
     +-----------+ +----------+     +----------+
     |  NMPSERV  | | STD.DLL  |     | APP.EXE  |
     |  .EXE    / /           |     |          |
     |          \ \           |     |          |
     |           | |          |     |          |
     +-----------+ +----------+     +----------+

The communication medium employed in this case is OS/2 Named Pipes.

The debugger provides the following remote link capabilities:

NOV
    This link uses Novell's SPX layer for communication.  Supported under
    DOS, OS/2, Windows 3.x, Windows NT and NetWare.

NET
    This link uses NetBIOS to communicate.  If your network software
    supports NetBIOS, you can use this link.  Supported under DOS, OS/2,
    Windows 3.x, and NetWare.

PAR
    This link supports communication using the parallel or printer port.
     Several different cable configurations are supported.  See
    Wiring For Remote Debugging.  Supported under DOS, OS/2, Windows 3.x,
    NetWare and QNX.

SER
    This link uses a serial port to communicate.  Rates of up to 115K BAUD
    are supported.  See Wiring For Remote Debugging.  Supported under DOS,
    OS/2 and QNX.

WIN
    This link will communicate between two Windows DOS boxes.  Supported
    under Windows 3.x and Windows 95 (for DOS applications only).

NMP
    This link will use Named Pipes to communicate internally between OS/2
    sessions.  OS/2, DOS and Win-OS/2 sessions are supported.  If your
    network supports Named Pipes, and you have at least one OS/2 machine on
    the network, you can communicate between OS/2, DOS and Windows 3.x
    machines on the network.  Supported under OS/2 (DOS, OS/2 and Windows
    3.x applications).

VDM
    This link is a subset of the NMP link.  It is supported under OS/2 and
    Windows NT.  The application being debugged must be a DOS or seamless
    Win-OS/2 application.  Supported under OS/2 and Windows NT (DOS, OS/2
    and Windows 3.x applications).

TCP
    This link will use TCP/IP to communicate internally or over a network
    between sessions.  Supported under OS/2, Windows NT, Windows 95 and QNX.

Communication parameters may be passed to the remote trap file and the
remote server.  They are passed to the remote trap file by following the
name of the trap file with a semi-colon and the parameter.  For example:


     A>serserv 2.4800

passes the parameter 2.4800 to the remote debug server.  To pass the same
parameter to the remote trap file, use:


     B>wd /tr=ser;2.4800 app

These link parameters are specific to each remote link and are described in
the following section.

Each of the debug servers can accept an optional "Once" parameter.  The