Liren Large Software Subsidy 7/07.iso/c/c500/3.ddi/VID_HELP.WPK/WVIDEO.HLP

Text File | 1992-05-28 | 405.3 KB | 10,599 lines

All help topics must be stored in order of the ASCII collating sequence.
Each topic is identified by a header consisting of a string of 4 colons
followed by the topic name.  Any alphabetic characters must be entered in
upper-case.
::::AUTOCAD
Debugging AutoCAD Applications
══════════════════════════════

VIDEO can be used to debug AutoCAD Development System (ADS) and AutoCAD
Device Interface (ADI) applications.  Before running VIDEO, add a line
similar to the following to your "ACAD.ADS" file.  This line specifies the
path to the "ADSHELP.EXP" file.

  C:\WATCOM\BIN\ADSHELP.EXP

The file "ACAD.ADS" contains a list of AutoCAD applications that are loaded
by AutoCAD when AutoCAD is started.  "ADSHELP.EXP" is an AutoCAD application
that is required by VIDEO for debugging AutoCAD applications.

To debug an ADS application, a special trap file "ADS.TRP" must be used.

┌──────────────────────────────────────────────────────────────────────────┐
│ WVIDEO /TRap=ADS                               │
└──────────────────────────────────────────────────────────────────────────┘

If you do not have a two-monitor setup, you should also specify the "swap"
option.

┌──────────────────────────────────────────────────────────────────────────┐
│ WVIDEO /TRap=ADS /Swap                           │
└──────────────────────────────────────────────────────────────────────────┘

Note that we did not specify the AutoCAD executable file; the trap file,
"ADS.TRP", will load AutoCAD automatically.  You should now be in VIDEO.  At
this point, enter the following debugger command specifying the name of the
file containing the symbolic debugging information for your AutoCAD
application.  This is either the executable file or a symbolic debugging
information file if the WATCOM Strip Utility was used.

┌──────────────────────────────────────────────────────────────────────────┐
│ DBG>ads file_spec                               │
└──────────────────────────────────────────────────────────────────────────┘

You should now be in AutoCAD.  When you load your AutoCAD application from
AutoLISP, the debugger will be entered and source for your program should be
displayed in the source window.  The file "ADS.DBG" contains a sequence of
debugger commands that starts AutoCAD, loads the debugging information from
the executable file you specify, and relocates address information based on
the code and data selector values for your application.  You are now ready
to debug your AutoCAD application.

For large AutoCAD applications, you may get an error when the "ADS" debugger
command file is invoked indicating that the debugger was unable to load the
debugging information from the executable file because of memory constraints.
If the error message "no memory for debugging information" or
"no memory for debugging information - increase dynamic memory" is issued,
use the debugger "dynamic" option to increase the amount of dynamic memory
(the default is 40k).  The following example increases the amount of dynamic
memory to 60k.

Example:
  C>wvideo /trap=ads /swap /dynamic=60k
::::BREAK
┌──────────────────────────────────────────────────────────────────────────┐
│ Break                                    │
│     /Activate    "*" | index_expr | "/" addr_expr               │
│     /Deactivate  "*" | index_expr | "/" addr_expr               │
│     [/Set]       addr_expr  [ cmd_list ]                   │
│     /Clear       "*" | index_expr | "/" addr_expr               │
└──────────────────────────────────────────────────────────────────────────┘

A break point defines a place in an application where we would like
execution to suspend so that we might examine the current environment.    A
break point may be defined by using the /Set qualifier or removed by using
the /Clear qualifier, enabled by using the /Activate qualifier or disabled
by using the /Deactivate qualifier.  Up to 7 break points may be defined by
using the /Set qualifier.  /Set is implied when no other qualifiers are
specified.

Example:
  DBG>break/set main_
  DBG>break main_

In the above example, two equivalent commands are shown.  A break point is
defined and automatically activated for the memory location defined by the
global symbol main_.  Only one break point may be specified for a particular
location in memory.  A "set" break point is indicated in the Source and
Assembly windows by a left-pointing arrow ().

A break point may also be specified in terms of the module name and line
number.

Example:
  DBG>break calendar@36

After the command is entered, an arrow (), indicating a break point,
appears at the start of the line.

Line numbers are shown in the Source window.  Source line information must
be available in order to show source line numbers.

  1. Either compiler options "d1" or "d2" must have been specified when the
    module was compiled.
  2. The "debug lines" or "debug all" linker option must have preceded the
    name of the object file containing the module when the application was
    linked.

The module name need not be specified when it is the current module under
examination.

Example:
  DBG>break @36

A break point may be specified in terms of a module name and symbol name.

Example:
  DBG>break calendar@Box

As with line numbers, the module name need not be specified when it is the
current module under examination.

Example:
  DBG>break Box

When specifying the symbol name only, the "@" is not necessary.  The "@" is
always required with line numbers, since this distinguishes them from
constants (e.g., "break 36" is equivalent to "break cs:36").

A break point may also be set or cleared with the mouse.  To set a break
point, double-click the mouse on the desired source line or assembly line.
A subsequent double-click on the same line will clear the break.

When the thread of execution encounters an active break point, application
execution will suspend and the debugger is entered.  If one or more debugger
commands were specified when the break point was defined, the debugger
commands are executed first.  The command list that follows the address
expression in the Break/Set command is defined as follows:

  cmd_list ::= "{" [cmd] { ";" [cmd] } "}"

This is simply a VIDEO command line placed inside of braces.

Notes:

  1. For a complete description of valid address expressions, see the
    chapter entitled "VIDEO Expression Handling".

  2. Execution of the application may be resumed if one of the commands was
    a Go command; otherwise the debugger prompts the user for a new command.

    Example:
      DBG>do look_count = 0
      DBG>break/set lookup { do look_count++; go/keep }

    Each time the "lookup" routine is entered, the debugger will increment
    the user-defined variable look_count and resume execution (keeping any
    user-defined temporary break point).  When execution of the application
    terminates, the current value of look_count may be examined with the
    Print command to determine how many times the "lookup" routine was
    executed.

  3. If no arguments are specified to the Break command, the currently
    defined break points will be displayed.  The first one shown is break
    point number 1, the second one shown is break point number 2, and so on.
    These are called the break point indices.  Active break points are shown
    in "active" attributes, inactive ones are shown in "plain" attributes.
    See the description of the Paint command for a discussion of attributes.

  4. When activating, deactivating or clearing a break point, either the
    break point index or the address must be specified.  If "*" is specified
    as the break point index then all break points are affected.

    Example:
      DBG>break/set main_; break/deactivate 1
      DBG>break/set main_; break/deactivate /main_

    In both examples, a break point is set and then a break point is
    deactivated.  In the first example, the break point set for "main_" is
    deactivated only if no other break points have been set (since it will
    then be break point number 1).  The second example illustrates how the
    break point for main_ will be deactivated under any circumstances.

    Example:
      DBG>break/activate 2; break/deactivate 1

    Breakpoint number 2 is activated and 1 is deactivated.

  5. The specified address need not be the name of a symbol or module name
    and line number.

    Example:
      DBG>break es:di

    A break point is set for the location specified by the contents of the
    ES:DI register pair.

    Example:
      DBG>break/deactivate /bx

    The break point whose address is specified by the contents of the CS:BX
    register pair is deactivated.

  6. The specified address can be "." which corresponds to the line of
    source code or assembly code most recently examined.

  7. All break points may be removed in a single command.

    Example:
      DBG>break/clear *

    The asterisk refers to all break points.
::::CALL
┌──────────────────────────────────────────────────────────────────────────┐
│ Call [/Far | /Interrupt | /Near]                       │
│      start_addr_expr [ "(" [arg_list] ")" [ "/" | print_list ] ]       │
└──────────────────────────────────────────────────────────────────────────┘

The Call command may be used to call any routine present in the system.  The
user specifies a starting address expression for the routine that is to be
called.  The expression must evaluate to the segment and offset of the
routine to be called.  The routine may be one of three types:

  /Far start_addr_expr ["(" [arg_list] ")" [ "/" | print_list ]]

       A "far" routine is one that eventually returns to its caller by
       using a "far return" instruction (RETF).  In 16-bit mode, a
       32-bit return address (segment and offset) is placed on the stack
       by the debugger so that the routine will return to the debugger.
       In 32-bit mode, a 64-bit return address (segment and offset) is
       placed on the stack by the debugger so that the routine will
       return to the debugger.  The "far" call and return mechanism is
       used in the big code models (medium, large, and huge).

  /Interrupt start_addr_expr ["(" [arg_list] ")" [ "/" | print_list ]]

       An "interrupt" routine is one that eventually returns to its
       caller by using an interrupt return instruction (IRET, IRETD).
       In 16-bit mode, a 32-bit return address (segment and offset) and
       the current contents of the flags register are placed on the
       stack by the debugger so that the interrupt routine will return
       to the debugger.  In 32-bit mode, a 64-bit return address
       (segment and offset) and the current contents of the flags
       register are placed on the stack by the debugger so that the
       interrupt routine will return to the debugger.  Note that an
       interrupt routine is called by its address, not an interrupt
       number.

  /Near start_addr_expr ["(" [arg_list] ")" [ "/" | print_list ]]

       A "near" routine is one that eventually returns to its caller by
       using a "near return" instruction (RET).  In 16-bit mode, a
       16-bit return address (offset) is placed on the stack by the
       debugger so that the routine will return to the debugger.  In
       32-bit mode, a 32-bit return address (offset) is placed on the
       stack by the debugger so that the routine will return to the
       debugger.  The "near" call and return mechanism is used in the
       small code models (small, compact, flat).



Call Argument List
══════════════════
An argument list may be specified for the routine to be invoked.  If one is
specified, it takes the following form:

  arg_list ::= [ arg_expr { "," arg_expr } ]
  arg_expr ::= [ "/"reg_name | "/"reg_aggregate | "//" ] expr

Example:
  DBG>call rtn0( )
  DBG>call rtn1( arg1 )
  DBG>call rtn5( arg1, arg2, arg3, arg4, arg5 )

The above examples illustrate how arguments may be specified.  By default,
arguments are passed to the routine using the standard argument passing
convention.  In 16-bit mode, the standard argument passing convention for
16-bit quantities is:

    argument 1 passed in register AX

    argument 2 passed in register DX

    argument 3 passed in register BX

    argument 4 passed in register CX

    argument N passed on the stack (N >= 5).

In 32-bit mode, the standard argument passing convention for 32-bit
quantities is:

    argument 1 passed in register EAX

    argument 2 passed in register EDX

    argument 3 passed in register EBX

    argument 4 passed in register ECX

    argument N passed on the stack (N >= 5).

These defaults may be changed by using the Set Call command.  Alternatively,
if you wish to specify a different argument passing convention then the
"/reg_name" (register), "/reg_aggregate" (group of registers) or "//"
(stack) modifiers may be used.

Example:
  DBG>call stdrtn(/ax p1,/dx p2,/bx p3,/cx p4,// p5)
      or
  DBG>call stdrtn(/eax p1,/edx p2,/ebx p3,/ecx p4,// p5)

The above examples, in effect, illustrate the placement of arguments in
registers and on the stack according to the standard argument passing
conventions for 16-bit and 32-bit modes.

Example:
  DBG>call longtostr( /[dx ax] long_arg )

The above 16-bit example illustrates that a 32-bit argument can be passed in
a register aggregate.  Register aggregates are described in the chapter
entitled "VIDEO Expression Handling".

Example:
  DBG>call printf( //arg1, //arg2, //arg3 )

The above example illustrates how to pass all arguments on the stack.  The
arguments are pushed onto the stack in a right to left order so that
(preceding the actual call) "arg1" will be on the top of the stack, "arg2"
will be next, and so on.

The arguments can be expressions and all expressions are evaluated before
the arguments are assigned to registers or placed on the stack.

Example:
  DBG>call rtn( /ax dx+1, /bx ax-cx, /cx 123)

The expressions "dx+1", "ax-cx" and "123" are evaluated.  The results of
these expressions are then assigned to the AX, BX and CX registers
respectively.  Note that the results would have been quite different if 123
had been assigned to the CX register before the expression "ax-cx" was
evaluated.

All register contents are preserved by the debugger.  Therefore, neither the
choice of argument passing convention nor the called routine can permanently
change the register contents.  The called routine could, however, have side
effects such as modifying memory locations, performing input/output, etc.

Disposition of the Return Value
═══════════════════════════════
One of three possible actions can occur after the called routine returns to
the debugger.

  1. By default, the contents of the AX register (16-bit mode) or EAX
    register (32-bit mode), which is returned by the routine, are printed in
    the Dialogue window.  This default may be changed by using the Set Call
    command.
  2. A "/" may be used to indicate that the routine does not return any
    value in which case nothing is printed.
  3. A formatting string and list of expressions may be specified.  The
    syntax of print_list is similar to that of the Print command.  The
    expressions are evaluated and the results printed in the Dialogue
    window.

Example:
  DBG>call test1() /
  DBG>call test2( s, t ) ax, bx, cx
  DBG>call test3( a,b,c ){Results were %i,%i,%u}dx,ax,tag

In the first line of the above example, the routine does not return any
useful information in the AX register so we suppress the printing of this
register.  In the second line, the contents of the AX, BX and CX registers
are displayed with default formatting.    In the third line, the contents of
the DX and AX registers and the variable "tag" are displayed using the
specified formatting string.  See the description of the Print command for
more information on formatting strings.

Suppose that we want to update some of the registers in our current register
set with values returned by the routine that we call.

Example:
  DBG>call/far test() _ax=ax, _bx=bx;/ax=_ax;/bx=_bx

In the above example, we call the routine "test" using a "far" call.  Since
register contents are unaffected by the call, we assign the values returned
in the AX and BX registers to the variables _ax and _bx.  Subsequent
debugger commands assign these saved values to the AX and BX registers in
our current register set.  VIDEO allows us to define new variables simply by
specifying a unique name and then assigning a value to it.

In the next example, we illustrate how to call a BIOS routine in 16-bit
"real" mode.

Example:
  DBG>c/int %0:(4*0x10) (/ah 3, /bh 0) {ct=%x,rc=%x}cx,dx

In the above example, we call the IBM BIOS "Video I/O" interrupt routine
(INT 0x10) to obtain the current cursor type and position (AH=3) for video
page 0 (BH=0).    The % operator yields the segment:offset pair stored at
locations 0:40 through 0:43.  The cursor type is returned in the "CX"
register and the cursor row and column are returned in the "DX" register;
hence we ask the debugger to display the contents of both registers in
hexadecimal format.
::::COMMAND_FILES
The following sections describe the command files that are provided with
VIDEO.

Under DOS or OS/2 systems, you should ensure that the "BINB" directory of
the WATCOM compiler package is included in the PATH environment variable.
This directory contains the command files provided with VIDEO.    VIDEO uses
the PATH environment variable to locate command files.

Under QNX, the command files provided with VIDEO are usually located in the
"/etc/wvideo" directory.  The search order for command files is as follows:

  1. the current directory,
  2. the paths listed in the WVIDEO_PATH environment variable,
  3. the path listed in the HOME environment variable, and, finally,
  4. the "/etc/wvideo" directory.

The INvoke or < command is used to execute the commands within a command
file.  The Set Implicit command can be used to turn automatic command file
invocation "on" or "off".  When it is "on", VIDEO will attempt to invoke a
command file when the command that is entered does not match one of those in
its command set.  For more information on command file processing, see the
"INVOKE" topic.



Setup for an AutoCAD ADS (or ADI) Application (ads.dbg)
═══════════════════════════════════════════════════════
Syntax:    [INvoke | <] ads <symbol_file_name>

Synopsis:  This command file sets up a debugging session for an AutoCAD ADS
       (or ADI) application.  The symbolic information is stored in
       "symbol_file_name".

       Consult the AutoCAD Development System - Programmer's Reference
       for more information on creating ADS applications.  See also the
       chapter in your WATCOM C/386 or WATCOM FORTRAN 77/386 User's
       Guide entitled "Creating AutoCAD Applications".  See the topic
       "AUTOCAD" for more information.



Create Large Assembly Window (asm.dbg)
══════════════════════════════════════
Syntax:    [INvoke | <] asm

Synopsis:  This command file creates an Assembly window that uses most of
       the screen.    The Register window is placed on the right side of
       the screen.    A Stack window is defined but not placed on the
       screen.  Small Source and Dialogue windows are also created.  The
       debugging level is set to "assembly".



Break on Count (bcnt.dbg)
═════════════════════════
Syntax:    [INvoke | <] bcnt <count> <address>

Synopsis:  This command file is used to break execution after "count"
       iterations at the specified "address".  The break point is
       cleared afterwards.

Example:   bcnt 1000 StageD

       Execution is halted after the routine "StageD" has been called
       1000 times.



Break If (bif.dbg)
══════════════════
Syntax:    [INvoke | <] bif <expr> <address>

Synopsis:  This command file is used to break execution at the specified
       "address" when "expr" is true (non-zero result).

Example:   bif {ax == 0} malloc

       bif {eax == 0} malloc

       Execution is halted whenever the "malloc" routine is called with
       a request for 0 bytes of storage.  Note that the argument is
       passed in register AX in 16-bit mode or EAX in 32-bit mode.



Count Breaks (cntbrks.dbg)
══════════════════════════
Syntax:    [INvoke | <] cntbrks <address>

Synopsis:  Count the number of times <address> is executed.

Example:   cntbrks StageD

       The name of the variable that is created to tabulate the number
       of iterations is displayed on the screen.  This variable can be
       queried at any time with the VIDEO Print command.  When program
       execution is started with the Go command, each break results in
       the message "cnt$xxxx = n" being printed on the program screen.



Setup Window Colours (colours.dbg)
══════════════════════════════════
Syntax:    [INvoke | <] colours

Synopsis:  This command file sets the colours for the various debugger
       windows.  The selection can be tailored to your own needs.  The
       command file is invoked by the start-up "profile.dbg" command
       file whenever the debugger is run on a colour monitor.

See Also:  grays.dbg



Fill Memory (fill.dbg)
══════════════════════
Syntax:    [INvoke | <] fill <address> <value> <length>

Synopsis:  This command file may be used to fill a region of memory with a
       specific value.  The starting address to fill is specified by
       <address>.  The byte value to fill with is specified by <value>.
       The number of bytes to fill is specified by <length>.

Example:   fill es:0 ff 100
       Fill 256 bytes of memory starting at ES:0 with the value 0xFF.  A
       radix of 16 is assumed in this example.



Setup for a FoxPro External Routine (fox.dbg)
═════════════════════════════════════════════
Syntax:    [INvoke | <] fox <symbol_file_name>

Synopsis:  This command file sets up a debugging session for a FoxPro
       External Routine.  The symbolic information is stored in
       "symbol_file_name".

       Make sure that you have coded a call to BreakPoint() in your
       external routine.  This call should be in the first segment.

Example:   Start the external routine (e.g.,?  hello()).  The call to
       BreakPoint() causes entry into debugger.  To start symbolic
       debugging, enter a command similar to the following:

       Example:
         DBG>fox hello.plb

       Consult the FoxPro External Routine API document for more
       information on creating FoxPro External Routines.



Setup Window Colours for a Gray-Scale Monitor
═════════════════════════════════════════════
Syntax:    [INvoke | <] grays

Synopsis:  This command file sets the "colours" for the various debugger
       windows on a gray-scale monitor.  The selection can be tailored
       to your own needs.  The command file should be invoked if you
       have a gray-scale monitor.

See Also:  colours.dbg



Create Assembly and Source Windows (mix.dbg)
════════════════════════════════════════════
Syntax:    [INvoke | <] mix

Synopsis:  This command file creates two evenly-sized Source and Assembly
       windows that use up most of the screen.  The Register window is
       placed on the right side of the screen.  A Stack window is
       defined but not placed on the screen.  A small Dialogue window is
       also created.  The debugging level is set to "mix".



VIDEO Initialization File (profile.dbg)
═══════════════════════════════════════
Syntax:    [INvoke | <] profile

Synopsis:  This is the VIDEO initialization file.  It can be customized for
       your own needs.  As distributed, it performs the following
       initialization.

         1. The menu bar is turned on.

         2. The debugging level is set to "mix" which is source level
           debugging whenever possible and assembly level debugging when
           no source line information is available.

         3. The symbol name matching patterns are set to "*", "*_" and
           "_*".

         4. Automatic command file invocation is enabled.  Any time an
           unrecognized command is entered, the debugger will try to
           execute a command file with the same name and extension
           "DBG".

         5. Radix specifiers for decimal (0n), hexadecimal (0x) and
           octal (0) numbers are defined.

         6. Default colours for various windows are set up.

         7. Command, Register, Stack, Fpu, Dialogue, Memory and Thread
           window sizes are defined.  Window sizes are based upon the
           number of screen lines that are available on the screen.  The
           "SRC" command file is invoked to place Source and Dialogue
           windows on the screen.

         8. "View", "src", "mix", "asm", and "flip" commands are added
           to the user-definable "User" pop-down menu.  Note that "src",
           "mix" and "asm" are the names of VIDEO command files.  For
           FORTRAN applications, "new;go fmain" is also added to the
           menus.  For C applications, "new;go main" is also added to
           the menus.

         9. Function key "F1" is defined such that a press will cause
           the "help" system to be invoked.

           Function key "F4" is defined to add and remove the FPU window
           to and from the screen with alternate presses.

           Function key "F5" is set to issue a "register -1" command
           when pressed.

           Function key "F6" is set to issue a "register +1" command
           when pressed.

           Function key "F7" is defined such that a press will cause an
           invocation of the "WIND" command file.  This key cycles
           through different sizes for the Source and Assembly windows
           by using the "SRC", "MIX" and "ASM" command files.

           Function key "F8" is defined such that alternate presses turn
           the menu bar on and off.

           Function key "F10" is defined to activate menu selection in
           the same way that pressing and releasing the Alt key would.

           Function key "Alt/F9" is defined such that a press will move
           the cursor to the Source window.

           Function key "Alt/F10" is defined such that a press will move
           the cursor to the Assembly window.

         10. Macro hot keys are defined for the Assembly window.  The
           following keys are defined:

           'G'      {g} Resume execution
           'g'      {g dbg$code} Continue execution to the currently
              highlighted line
           'i'      {t/a/i} Single-shot trace "into"
           'n'      {t/a/n} Single-shot trace "next"
           ' '      {t/a/o} Single-shot trace "over"
           'b'      {b dbg$code} Set a break point at the currently
              highlighted line
           'c'      {b/c/dbg$code} Remove a break point at the
              currently highlighted line

         11. Macro hot keys are defined for the Source window.  The
           following keys are defined:

           'v'      {view} View the source code for the current module
           'G'      {g} Resume execution
           'g'      {g dbg$code} Continue execution to the currently
              highlighted line
           'i'      {t/s/i} Single-shot trace "into"
           'n'      {t/s/n} Single-shot trace "next"
           ' '      {t/s/o} Single-shot trace "over"
           'b'      {b dbg$code} Set a break point at the currently
              highlighted line
           'c'      {b/c/dbg$code} Remove a break point at the
              currently highlighted line

         12. Macro hot keys are defined for the FPU window.  The
           following keys are defined:

           'b'      {set fpu binary} Set the display mode to
              hexadecimal
           'd'      {set fpu decimal} Set the display mode to decimal

         13. For MS Windows applications, VIDEO will issue a "go
           WinMain" (C) or "go FWinMain" (FORTRAN) command if one of
           these entry points is defined.

         14. For FORTRAN applications, VIDEO will issue a "go fmain"
           command.  Otherwise, if the "main" entry point is defined
           then VIDEO will issue a "go main" command.



Set DOS Memory Control Block (resize.dbg)
═════════════════════════════════════════
Syntax:    [INvoke | <] resize <new_size>

Synopsis:  (DOS only) This command file sets the DOS memory control block
       containing the PSP to a new size.  The PSP value is recorded in
       the debugger variable _dbg@dbg$psp.    Before an application
       starts, DOS gives it all of the remaining memory.  Normally, the
       application should return to DOS that portion of memory which it
       does not use.  This command file can be used in the event that
       the application does not return unused memory to DOS and you wish
       to start up a subprocess by using the VIDEO SYSTEM command.    In
       this case, memory must be returned to DOS before a subprocess can
       be started.

Example:   resize 0x1000

       Reset the memory control block containing the current PSP to 64K
       bytes.

┌────────────────────────────────────────────────────────────────────────────┐
│ WARNING!  If an incorrect or inappropriate size is specified, the computer │
│ system could hang.  Too small values will cause erratic operation.         │
└────────────────────────────────────────────────────────────────────────────┘



Return from Current Routine (return.dbg)
════════════════════════════════════════
Syntax:    [INvoke | <] return

Synopsis:  This command file may be used to return from the current routine.
       Execution of the application is advanced until a RETURN
       instruction is encountered.    Execution is then advanced by an
       additional instruction in order to return to the calling routine.



Slow Motion Code Animation (slow.dbg)
═════════════════════════════════════
Syntax:    [INvoke | <] slow <delay>

Synopsis:  This command file can be used to perform slow motion execution of
       a program.  The <delay> value must be specified.  The larger the
       value for <delay>, the slower the program will execute.



Save Current Setup (save.dbg)
═════════════════════════════
Syntax:    [INvoke | <] save

Synopsis:  Creates a file called setup.dbg which contains the debugger
       commands required to recreate the current debugger configuration.



Create Large Source Window (src.dbg)
════════════════════════════════════
Syntax:    [INvoke | <] src

Synopsis:  This command file creates a Source window that uses most of the
       screen.  A small Dialogue window is also created.  Any Register
       or Stack windows are removed from the screen.  The Assembly
       window is hidden under the Dialogue window.    The debugging level
       is set to "source".    The command file is invoked by the start-up
       "profile.dbg" command file.



Define Function Key Toggle (toggle.dbg)
═══════════════════════════════════════
Syntax:    [INvoke | <] toggle <pfkey_number> <command_string_1>
       <command_string_2>

Synopsis:  This command file sets up a PF key to alternate between two
       commands.

Example:   toggle 10 {set menu on} {set menu off}

       Function key "F10" is defined to toggle the menu bar on and off.



View Output from CALL Command (vc.dbg)
══════════════════════════════════════
Syntax:    [INvoke | <] vc <call_address_and_arguments>

Synopsis:  This command file uses the View command to examine the standard
       output from a routine called by the Call command.  The file
       "stdout.tmp" is created.

Example:   vc DumpTree( HeadNode )



View Source Code for Routine (vr.dbg)
═════════════════════════════════════
Syntax:    [INvoke | <] vr <routine_name>

Synopsis:  This command file examines the source code for a given routine by
       using the View command.

Example:   vr main



Window Management Utility Function (wind.dbg)
═════════════════════════════════════════════
Syntax:    [INvoke | <] wind

Synopsis:  This command file invokes one of the "SRC", "ASM", or "MIX"
       command files depending on the state of the _dbg@dbg$wind_split
       variable.  It is primarily a utility command file that is invoked
       by other command files or function keys.

::::C_OPERATORS
VIDEO supports most C operators and includes an additional set of operators
for convenience.  The WATCOM C Language Reference manual describes many of
these operators.

The syntax for VIDEO expressions is similar to that of the C programming
language.  Operators are presented in order of precedence, from lowest to
highest.  Operators on the same line have the same priority.

                      Lowest Priority
  Assignment Operators
      =  +=  -=  *=  /=  %=  &=  |=  ^=  <<=  >>=
  Logical Operators
      ||
      &&
  Bit Operators
      |
      ^
      &
  Relational Operators
      ==  !=
      <   <=   <   >=
  Shift Operators
      <<  >>
  Arithmetic Operators
      +  -
      *  /  %
  Unary Operators
      +  -  ~  !  ++  --  &  *    %
      sizeof unary_expr
      sizeof(type_name)
      (type_name) unary_expr
      [type_name] unary_expr
      ?
  Binary Address Operator
      :
                      Highest Priority

Parentheses can be used to order the evaluation of an expression.

In addition to the operators listed above, a number of primary expression
operators are supported.  These operators are used in identifying the object
to be operated upon.

[]       subscripting, substringing

()       function call

.       field selection

->       field selection using a pointer

The following sections describe the operators presented above.



Assignment Operators for the C Grammar
══════════════════════════════════════
=       Assignment:    The value on the right is assigned to the object on
       the left.

+=       Additive assignment:  The value of the object on the left is
       augmented by the value on the right.

-=       Subtractive assignment:  The value of the object on the left is
       reduced by the value on the right.

*=       Multiplicative assignment:  The value of the object on the left
       is multiplied by the value on the right.

/=       Division assignment:  The value of the object on the left is
       divided by the value on the right.

%=       Modulus assignment:    The object on the left is updated with
       MOD(left,right).  The result is the remainder when the value of
       the object on the left is divided by the value on the right.

&=       Bit-wise AND:  The bits in the object on the left are ANDed with
       the bits of the value on the right.

|=       Bit-wise inclusive OR:  The bits in the object on the left are
       ORed with the bits of the value on the right.

^=       Bit-wise exclusive OR:  The bits in the object on the left are
       exclusively ORed with the bits of the value on the right.

<<=       Left shift:    The bits in the object on the left are shifted to
       the left by the amount of the value on the right.

>>=       Right shift:  The bits in the object on the left are shifted to
       the right by the amount of the value on the right.  If the object
       on the left is described as unsigned, the vacated high-order bits
       are zeroed.    If the object on the left is described as signed,
       the sign bit is propagated through the vacated high-order bits.
       VIDEO treats registers as unsigned items.



Logical Operators for the C Grammar
═══════════════════════════════════
&&       Logical conjunction:  The logical AND of the value on the left
       and the value on the right is produced.  If either of the values
       on the left or right is equal to 0 then the result is 0;
       otherwise the result is 1.

||       Logical inclusive disjunction:  The logical OR of the value on
       the left and the value on the right is produced.  If either of
       the values on the left or right is not equal to 0 then the result
       is 1; otherwise the result is 0.  If the value on the left is not
       equal to 0 then the expression on the right is not evaluated
       (this is known as short-circuit expression evaluation).



Bit Operators for the C Grammar
═══════════════════════════════
&       Bit-wise AND:  The bits of the value on the left and the value on
       the right are ANDed.

|       Bit-wise OR:  The bits of the value on the left and the value on
       the right are ORed.

^       Bit-wise exclusive OR:  The bits of the value on the left and the
       value on the right are exclusively ORed.



Relational Operators for the C Grammar
══════════════════════════════════════
==       Equal:  If the value on the left is equal to the value on the
       right then the result is 1; otherwise the result is 0.

!=       Not equal:  If the value on the left is not equal to the value on
       the right then the result is 1; otherwise the result is 0.

<       Less than:  If the value on the left is less than the value on
       the right then the result is 1; otherwise the result is 0.

<=       Less than or equal:    If the value on the left is less than or
       equal to the value on the right then the result is 1; otherwise
       the result is 0.

>       Greater than:  If the value on the left is greater than the value
       on the right then the result is 1; otherwise the result is 0.

>=       Greater than or equal:  If the value on the left is greater than
       or equal to the value on the right then the result is 1;
       otherwise the result is 0.


Arithmetic/Logical Shift Operators for the C Grammar
════════════════════════════════════════════════════
<<       Left shift:    The bits of the value on the left are shifted to the
       left by the amount described by the value on the right.

>>       Right shift:  The bits of the value on the left are shifted to
       the right by the amount described by the value on the right.  If
       the object on the left is described as unsigned, the vacated
       high-order bits are zeroed.    If the object on the left is
       described as signed, the sign bit is propagated through the
       vacated high-order bits.  VIDEO treats registers as unsigned
       items.



Binary Arithmetic Operators for the C Grammar
═════════════════════════════════════════════
+       Addition:  The value on the right is added to the value on the
       left.

_       Subtraction:  The value on the right is subtracted from the value
       on the left.

*       Multiplication:  The value on the left is multiplied by the value
       on the right.

/       Division:  The value on the left is divided by the value on the
       right.

%       Modulus:  The modulus of the value on the left with respect to
       the value on the right is produced.    The result is the remainder
       when the value on the left is divided by the value on the right.



Unary Arithmetic Operators for the C Grammar
════════════════════════════════════════════
+       Plus:  The result is the value on the right.

_       Minus:  The result is the negation of the value on the right.

~       Bit-wise complement:  The result is the bit-wise complement of
       the value on the right.

!       Logical complement:    If the value on the right is equal to 0 then
       the result is 1; otherwise it is 0.

++       Increment:  Both prefix and postfix operators are supported.  If
       the object is on the right, it is pre-incremented by 1 (e.g.,
       ++x).  If the object is on the left, it is post-incremented by 1
       (e.g., x++).

_ _       Decrement:  Both prefix and postfix operators are supported.  If
       the object is on the right, it is pre-decremented by 1 (e.g.,
       --x).  If the object is on the left, it is post-decremented by 1
       (e.g., x--).

&       Address of:    The result is the address (segment:offset) of the
       object on the right (e.g., &main).

*       Points:  The result is the value stored at the location addressed
       by the value on the right (e.g., *(ds:100), *string.loc).  In the
       absence of typing information, a near pointer is produced.  If
       the operand does not have a segment specified, the stack segment
       is assumed.

           (SS:00FE) = FFFF
         var:  (SS:0100) = 0152
           (SS:0102) = 1240
           (SS:0104) = EEEE

       In the following example, memory locations are displayed starting
       at DS:152 for 16-bit mode and at DS:12400152 for 32-bit mode.

       Example:
         DBG>examine/byte *100

%       Value at address:  The result is the value stored at the location
       addressed by the value on the right (e.g., %(ds:100),
       %string.loc).  In the absence of typing information, a far
       pointer is produced.  If the operand does not have a segment
       specified, the stack segment is assumed.

           (SS:00FE) = FFFF
         var:  (SS:0100) = 0152
           (SS:0102) = 1240
           (SS:0104) = EEEE

       In the following example, memory locations are displayed starting
       at 1240:1052 for 16-bit mode and at EEEE:12400152 for 32-bit
       mode.

       Example:
         DBG>examine/byte %100

       Note that this operator is not found in the C programming
       language.



Special Unary Operators for the C Grammar
═════════════════════════════════════════
sizeof unary_expression

       Example:
         DBG>print sizeof tyme
         2 (or 4 in 32-bit mode)
         DBG>print sizeof *tyme
         18

sizeof(type_name)

       Example:
         DBG>print sizeof( struct tm )
         18

(type_name) unary_expression The type conversion operator (type_name) is
       used to convert an item from one type to another.  The following
       describes the syntax of "type_name".

         type_name ::= type_spec { [ "near" | "far" | "huge" ] "*" }
         type_spec ::= typedef_name
                 |     "struct" structure_tag
                 |     "union"  union_tag
                 |     "enum"   enum_tag
                 |     scalar_type { scalar_type }
         scalar_type ::= "char" | "int" | "float" | "double"
                 |     "short" | "long" | "signed" | "unsigned"

       Example:
         DBG>print (float) 4
         4.

         DBG>print (int) 3.1415926
         3

[type_name] unary_expression You can force the debugger to treat a memory
       reference as a particular type of value by using a type coercion
       operator.  A type specification is placed inside brackets as
       shown above.  The basic types are char (character, 8 bits), short
       (short integer, 16 bits), long (long integer, 32 bits), float
       (single-precision floating-point, 32 bits), and double
       (double-precision floating-point, 64 bits).    Unless qualified by
       the short or long keyword, the int type will be 16 bits in 16-bit
       applications and 32 bits in 32-bit applications (386 and 486
       systems).  The character, short integer and long integer types
       may be treated as signed or unsigned items.    The default for the
       character type is unsigned.    The default for the integer types is
       signed.

       Example:
         [char]             (default unsigned)
         [signed char]
         [unsigned char]
         [int]             (default is signed)
         [short]             (default is signed)
         [short int]         (default is signed)
         [signed short int]
         [long]             (default is signed)
         [long int]          (default is signed)
         [signed long]
         [unsigned long int]
         [float]
         [double]

       Note that it is unnecessary to specify the int keyword when short
       or long are specified.

?       Existence test:  The "?" unary operator may be used to test for
       the existence of a symbol.

       Example:
         DBG>print ?id

       The result of this expression is 1 if "id" is a symbol known to
       VIDEO and 0 otherwise.  If the symbol does not exist in the
       current scope then it must be qualified with its module name.
       Automatic symbols exist only in the current function.



Binary Address Operator for the C Grammar
═════════════════════════════════════════
:       Memory locations can be referenced by using the binary ":"
       operator and a combination of constants, register names, and
       symbol names.  In the Intel 80x86 architecture, a memory
       reference requires a segment and offset specification.  A memory
       reference using the ":" operator takes the following form:

         segment:offset

       The elements segment and offset can be expressions.

       Example:
         (ES):(DI+100)
         (SS):(SP-20)



Primary Expression Operators for the C Grammar
══════════════════════════════════════════════
[]       Elements of an array can be identified using subscript
       expressions.  Consider the following 3-dimensional array defined
       in the "C" language.

       Example:
         char *ProcessorType[2][4][2] =
         { { { "Intel 8086",   "Intel 8088"  },
             { "Intel 80186",  "Intel 80188" },
             { "Intel 80286",  "unknown" },
             { "Intel 80386",  "unknown" } },

           { { "NEC V30",      "NEC V20" },
             { "unknown",      "unknown" },
             { "unknown",      "unknown" },
             { "unknown",      "unknown" } } };

       This array can be viewed as two layers of rectangular matrices of
       4 rows by 2 columns.  The array elements are all pointers to
       string values.

       By using a subscript expression, specific slices of an array can
       be displayed.  To see only the values of the first layer, the
       following command can be issued.

       Example:
         DBG>print processortype[0]
         {[0]={[0]=0x0024, [1]=0x002F},
          [1]={[0]=0x003A, [1]=0x0046},
          [2]={[0]=0x0052, [1]=0x005E},
          [3]={[0]=0x0066, [1]=0x005E}}

       The values shown are the addresses of the string values.

       To see only the first row of the first layer, the following
       command can be issued.

       Example:
         DBG>print processortype[0][0]
         {[0]=0x0024, [1]=0x002F}

       To see the second row of the first layer, the following command
       can be issued.

       Example:
         DBG>print processortype[0][1]
         {[0]=0x003A, [1]=0x0046}

       To see the value of a specific entry in a matrix, all the indices
       can be specified.

       Example:
         DBG>print {%s} processortype[0][0][0]
         Intel 8086
         DBG>print {%s} processortype[0][0][1]
         Intel 8088
         DBG>print {%s} processortype[0][1][0]
         Intel 80186

       In the above examples, we use the "%s" format specifier to
       display the string values.

()       The function call operators appear to the right of a symbol name
       and identify a function call in an expression.  The parentheses
       can contain arguments.

       Example:
         DBG>print ClearScreen()
         DBG>print PosCursor( 10, 20 )
         DBG>print Line( 15, 1, 30, '-', '+', '-' )

.       The "." operator indicates field selection in a structure.  In
       the following example, tyme2 is a structure and tm_year is a
       field in the structure.

       Example:
         DBG>print tyme2.tm_year

->       The "->" operator indicates field selection when using a pointer
       to a structure.  In the following example, tyme is the pointer
       and tm_year is a field in the structure to which it points.

       Example:
         DBG>print tyme->tm_year
::::DISPLAY
┌──────────────────────────────────────────────────────────────────────────┐
│ Display                                   │
│     Assembly [status] [title] [window_coord]                   │
│     Command  [status] [title] [window_coord] [cmd_list]           │
│     Dialogue [status] [title] [window_coord]                   │
│     Fpu      [status] [title] [window_coord]                   │
│     Memory   [status] [title] [window_coord] [mem_loc]           │
│     Prompt   [status] [title] [line_number]                   │
│     Register [status] [title] [window_coord]                   │
│     SOurce   [status] [title] [window_coord]                   │
│     STack    [status] [title] [window_coord]                   │
│     Thread   [status] [title] [window_coord]                   │
└──────────────────────────────────────────────────────────────────────────┘

The Display command is used to create or remove output windows for various
displays that the debugger can provide.  For each window, you may specify a
window status, a title, the starting line number of the window and, for
those windows which may vary in size, the ending line number.  VIDEO windows
are described in the "WINDOWS" topic.

When no window name is specified then all windows are updated.    This command
may be used to recreate window displays if the user's application has
overwritten them.  It may also be used in command lists to update the
display.



Window Titles
═════════════
Each window that is created with the Display command may have a title.    The
title is specified by placing a string of characters inside curly braces and
is formally described as follows:

  title ::= "{" text "}"

An asterisk (*) may be specified as part of the string and represents a
place holder for the current module name.

Example:
  DBG>display assembly {Assembly: *}

In the above example, the Assembly window is given the title "Assembly:  *".
If the current module name was "hello" then the title would appear at the
top of the Assembly window as follows:

  ==| Assembly: hello |======================

To remove the title from a window, simply specify a pair of empty braces.

Example:
  DBG>display assembly {}



Window Placement
════════════════
Starting at the top of the screen, output lines are numbered consecutively
starting with 1.  Columns are numbered from left to right starting with 1.
It is possible to define windows that overlap other windows thereby
partially obscuring the contents of the overlapped window.

Window coordinates are specified in terms of a top row, a bottom row, a left
column, and a right column.

  window_coord ::= [top][","[bottom][","[left][","right]]]

The top, bottom, left and right items are expressions which are always
evaluated with a radix of 10, regardless of the current default radix for
numbers.

Example:
  DBG>display assembly 3,20,1,80

In the above example, the Assembly window is defined to occupy lines 3
through 20 and columns 1 through 80.

Example:
  DBG>display assembly {Assembly: *} 3,20,1,80

This example is similar to the previous one but a window title is also
specified.

Example:
  DBG>display assembly ,,8,60

In this example, we redefine the starting and ending columns for the
Assembly window to be 8 and 60.



Window Disposition
══════════════════
The disposition of each window that is created with the Display command may
be specified using one of the following status qualifiers.

/Open       The window is created and placed on the screen.

       Example:
         DBG>dis assembly /open {Asm: *} 13,19,1,71

       This is the default action when creating a window hence it is not
       necessary to specify this qualifier.

/Close       A window that is currently on the screen can be removed by
       specifying the /Close qualifier.  The debugger will not let you
       remove the Dialogue and Prompt windows but they can be moved to
       different positions on the screen.

       Example:
         DBG>display assembly /close

       In the above example, the Assembly window is removed from the
       screen.

       A window can be created but not placed on the screen.

       Example:
         DBG>display fpu /close {FPU} 3,13,1,64

       It may be placed on the screen at a later time using the Display
       command and it will not be necessary to respecify the window
       title or coordinates.

/Zoom       The window is created and immediately displayed on the screen
       using the full dimensions of the screen.

       Example:
         DBG>display source /zoom

       If the window is already on the screen then its size will
       alternate between its defined size and the full dimensions of the
       screen.



Window Attributes
═════════════════
Various items in the window are displayed with special attributes.  See the
description of the Paint command for a discussion of "plain", "active",
"standout", "title" and "gadget" attributes.



The Assembly Window
═══════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display Assembly [status] [title] [window_coord]               │
└──────────────────────────────────────────────────────────────────────────┘

The debugger displays assembly instructions for the current code location in
this window.  If the Code Segment and Instruction Pointer registers (CS:IP
or CS:EIP) point to an instruction visible in the Assembly window then the
line containing that instruction is displayed in "active" attributes.  When
examining assembly instructions, one line is designated as the current line
and is displayed in "standout" attributes.  The Source window, if present,
is kept synchronized with the Assembly window provided that source
information is available.



The Command Window
══════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display Command [status] [title] [window_coord] [cmd_list]           │
└──────────────────────────────────────────────────────────────────────────┘

The Command window can be used to display the results of one or more
commands which you wish to have evaluated each time control returns to the
debugger.

The command list that follows the command is defined as follows:

  cmd_list ::= "{" [cmd] { ";" [cmd] } "}"

Example:
  DBG>display command 3, 8 {e es:bx,.+10,10,4; reg}

The output from commands such as:

Example:
  DBG>e es:bx,.+10,10,4
  DBG>reg

are normally displayed in other windows.  The list of commands that are
specified when the Command window is created is executed and the results are
displayed in the command window.  The commands are re-executed and the
results are displayed in the Command window whenever:

  1. the debugger is entered,
  2. one of the commands Display or Display Command is issued, or
  3. the Command window is selected (by using the mouse or tab keys).

This facility provides a mechanism for watching the values of one or more
variables change (see also the Print /Window command).



The Dialogue Window
═══════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display Dialogue [status] [title] [window_coord]               │
└──────────────────────────────────────────────────────────────────────────┘

By default, the debugger displays responses to commands in this window.
When one of the other windows is not present on the screen, the output
normally destined for that window is displayed in the Dialogue window.



The FPU Window
══════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display Fpu [status] [title] [window_coord]                   │
└──────────────────────────────────────────────────────────────────────────┘

The contents of the 80x87 numeric data processor (math coprocessor)
registers and status flags are displayed in this window.  When the contents
of a register have changed from the last time that the debugger was entered,
it is displayed in "standout" attributes.



The Memory Window
═════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display Memory [status] [title] [window_coord] [mem_loc]           │
└──────────────────────────────────────────────────────────────────────────┘

A portion of memory is displayed in this window.  When the Memory window is
active, the currently selected memory location is displayed in "active"
attributes.  Memory window "hot spots" (e.g., BYTE ) are displayed in
"standout" attributes.    All other items are displayed in "plain" attributes.

Example:
  DBG>display memory /open {Low Mem} 3,9,,,ds:36

In the above example, memory starting at location DS:36 is displayed in a
Memory window that runs from lines 3 through 9 and columns 1 through 80.

Example:
  DBG>display memory /close

In the above example, the Memory window is removed from the screen.



The Prompt Window
═════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display Prompt [status] [title] [line_number]                │
└──────────────────────────────────────────────────────────────────────────┘

The debugger command input prompt "DBG>" is displayed in a window that is
one line high.    The prompt window is used to enter command lines.

In multiple execution thread applications, the "DBG>" prompt is replaced by
a prompt that indicates the current thread.  The form of the prompt is
"ddddd>" where "ddddd" is the thread identification number.

Example:
  00002>



The Register Window
═══════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display Register [status] [title] [window_coord]               │
└──────────────────────────────────────────────────────────────────────────┘

The current contents of the 80x86 registers are displayed in a window.    When
the contents of a register have changed from the last time that the debugger
was entered, it is displayed in "standout" attributes.    An exception to this
rule is the Instruction Pointer (IP, EIP) register which is only displayed
in "standout" attributes when its value changes because some type of branch
or call instruction was executed.

If a register set other than register set 0 is displayed, then the register
set number is displayed in brackets (e.g., [1]) with "active" attributes
(see the description of the Register command).



The Source Window
═════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display SOurce [status] [title] [window_coord]               │
└──────────────────────────────────────────────────────────────────────────┘

If program source code information is available for the current code
location then it will be displayed in this window.  If the Code Segment and
Instruction Pointer registers (CS:IP or CS:EIP) point to a source line
visible in the Source window then the line is displayed in "active"
attributes.  When examining source code, one line is designated as the
current line and is displayed in "standout" attributes.  The Assembly
window, if present, is kept synchronized with the Source window.



The Stack Window
════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display STack [status] [title] [window_coord]                │
└──────────────────────────────────────────────────────────────────────────┘

A portion of the execution stack is displayed in this window.  If the Base
Pointer (BP or EBP) register points to a visible byte, word, or doubleword
on the stack, the byte, word, or doubleword is displayed in "standout"
attributes.  All other words are displayed in "plain" attributes.



The Thread Window
═════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Display Thread [status] [title] [window_coord]               │
└──────────────────────────────────────────────────────────────────────────┘

The Thread window is used to display the identification number, state and
name of all program execution threads.    Whenever the debugger is entered,
the currently executing thread is displayed in "active" attributes.  The
currently selected thread is displayed in "standout" attributes.  All other
items are displayed in "plain" attributes.

There are 3 entries in the Thread window.  The first entry is the thread
identification number or thread ID.  The second entry is the thread state
which may be one of "runnable" or "frozen".  The third entry is the thread
name which is applicable to NetWare 386 server tasks only.

Under DOS, MS Windows or QNX, there is only one execution thread so there is
only one entry in the Thread window.  Under OS/2 or NetWare 386, there may
be several execution threads so there may be be several entries in the
Thread window.

Example:
  DBG>display thread /open {Threads} 14,19,20,50

In the above example, execution thread information is displayed in a Thread
window that runs from lines 14 through 19 and columns 20 through 50.

Example:
  DBG>display thread /close

In the above example, the Thread window is removed from the screen.
::::DO
┌──────────────────────────────────────────────────────────────────────────┐
│ DO      expr                                   │
│ /                                       │
└──────────────────────────────────────────────────────────────────────────┘

The DO or / command evaluates an expression and discards the result.  It is
useful for assigning new values to registers and variables.  The expression
expr can involve registers, application variables and user-defined
variables.  The operations possible are patterned after those available in
the C and FORTRAN 77 programming languages.  Expressions are fully discussed
in the chapter entitled "VIDEO Expression Handling".

Example:
  DBG>do ax=1
  DBG>/ax=1

The above example illustrates two identical ways to set the contents of the
AX register to 1.

Example:
  DBG>/myvar=di-bx+1

The variable myvar is defined with the value resulting from subtracting the
contents of the BX register from the contents of the DI register and then
adding 1.

Example:
  DBG>/oldsi=si++

The variable oldsi is defined with the current contents of the SI register.
The current contents of the SI register are then incremented by 1 (the
C-like "++" operator increments the value of the variable).  Variables such
as oldsi need not be defined within the application.  VIDEO permits the
dynamic creation of new variables which will only exist for the duration of
the debug session.  These user-defined variables can be used to retain
information as we have shown in the above example.
::::DOS_EXTENDER
Debugging 32-bit DOS Extender Applications
══════════════════════════════════════════

Introduction
════════════
Before reading this help text, you should be familiar with the material
presented in the "DOS_STARTUP" topic.  The general command line format
and options for DOS extender systems are presented under that topic.

VIDEO supports debugging of 32-bit applications developed with WATCOM C/386,
WATCOM FORTRAN 77/386, and assembly language.  A DOS extender must be used
to run the application.  The following DOS extenders are supported.

DOS/4GW    a DOS extender from Rational Systems, Inc.  DOS/4GW is a subset
       of Rational Systems' DOS/4G product.  DOS/4GW is customized for
       use with WATCOM C/386 and WATCOM FORTRAN 77/386 and is included
       in these packages.

OS/386       (version 2.1 or later) a DOS extender from ERGO Computing, Inc.

386|DOS-Extender
       (version 2.2d or later) a DOS extender from Phar Lap Software,
       Inc.



VIDEO Command Line Format for DOS Extenders
═══════════════════════════════════════════
The interface between VIDEO and the operating system/DOS extender is
contained in a special "trap" file.  The trap file is specified to VIDEO
using the "TRAP" option.

┌──────────────────────────────────────────────────────────────────────────┐
│ WVIDEO /TRap=trap_file[;trap_parm] [:sym_file] file_spec [cmd_line]       │
└──────────────────────────────────────────────────────────────────────────┘

The TRap option must be specified when debugging applications that require a
32-bit DOS extender.  For convenience, this option can be specified through
use of the WVIDEO environment variable.

┌──────────────────────────────────────────────────────────────────────────┐
│ SET WVIDEO=/TRap#trap_file[;trap_parm]                   │
└──────────────────────────────────────────────────────────────────────────┘

When trap_parm is specified and it contains blank characters, the entire
parameter must be placed within braces (e.g., /trap=pls;{-minr 128}).

You must specify the name of one of the DOS extender "trap" files provided
with VIDEO.  The file extension defaults to ".TRP".

RSI.TRP    This interface module supports debugging on the local computer
       system running the Rational Systems "DOS/4GW" DOS extender (which
       is included in the WATCOM C/386 and WATCOM FORTRAN 77/386
       packages).  The optional "trap_parm" is ignored.

ECS.TRP    This interface module supports debugging on the local computer
       system running the ERGO Computing, Inc.  "OS/386" DOS extender.
       The optional "trap_parm" is ignored.

PLS.TRP    This interface module supports debugging on the local computer
       system running the Phar Lap Software, Inc.  386|DOS-Extender.
       The optional "trap_parm" is passed on to the DOS extender
       "RUN386" as command line switches.

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  If you do not specify a trap file, the default trap file "STD.TRP"  │
│ will be loaded.  This interface module supports debugging on the local     │
│ computer system running DOS.    No 32-bit DOS extender debugging is         │
│ possible.                                     │
└────────────────────────────────────────────────────────────────────────────┘

The following diagram illustrates how memory might be organized when
debugging a 32-bit DOS extender application.

      │           │
      │           │
      ├────────────────┤
      │           │
      │     32─bit    │
      │   Application  │
  109C4   ├────────────────┤
      │           │
      │           │
      │           │
   7E6E   ├────────────────┤
      │  trap handler  │
      │    ECS.TRP<────│──┐
   7B27   ├───────│────────┤  │
      │      │       │  │
      │    WVIDEO       │  │
      │           │  │
   47A4   ├────────────────┤  │
      │           │  │
      │    OS/386       │  │
      │  DOS Extender<─│──┘
      │           │
   262C   │────────────────┤
      │           │
      │           │
      │           │
      │           │
   0000   └────────────────┘

Using the Rational Systems 32-bit DOS Extender
══════════════════════════════════════════════
When using the Rational Systems DOS extender, the "DOS4GW.EXE" or
"DOS4G.EXE" file must be located in one of the directories listed in the DOS
PATH environment variable.  The "DOS4GW.EXE" file will usually be stored in
the "BIN" directory of the WATCOM compiler package.

┌──────────────────────────────────────────────────────────────────────────┐
│ C>WVIDEO/TRap=RSI [:sym_file] file_spec [cmd_line]               │
└──────────────────────────────────────────────────────────────────────────┘

The /TRap=RSI option must be specified when debugging applications that are
to be run under the "DOS/4GW" DOS extender.  The "RSI.TRP" file will usually
be stored in the "BIN" directory of the WATCOM compiler package.  You should
ensure that this "BIN" directory is included in the DOS PATH environment
variable.  Otherwise, you must specify the full path name for the trap file.

The help file "RSIHELP.EXP" must also be located in one of the directories
listed in the DOS PATH environment variable.  It will usually be stored in
the "BIN" directory of the WATCOM compiler package.

Example:
  C>wvideo /trap=rsi hello
    or
  C>set wvideo=/trap#rsi
  C>wvideo hello



Using the ERGO 32-bit DOS Extender
══════════════════════════════════
When using the ERGO Computing, Inc.  DOS extender, the "OS386" program must
be run first.

┌──────────────────────────────────────────────────────────────────────────┐
│ C>OS386                                   │
│ C>WVIDEO/TRap=ECS [:sym_file] file_spec [cmd_line]               │
└──────────────────────────────────────────────────────────────────────────┘

The /TRap=ECS option must be specified when debugging applications that are
to be run under the "OS386" DOS extender.  The "ECS.TRP" file will usually
be stored in the "BIN" directory of the WATCOM compiler package.  You should
ensure that this "BIN" directory is included in the DOS PATH environment
variable.  Otherwise, you must specify the full path name for the trap file.

Example:
  C>wvideo /trap=ecs hello
    or
  C>set wvideo=/trap#ecs
  C>wvideo hello



Using the Phar Lap 32-bit DOS Extender
══════════════════════════════════════
When using the Phar Lap Software, Inc.    DOS extender, the "RUN386.EXE",
"DBGLIB.REX" and "PLSHELP.EXP" files must be located in one of the
directories listed in the DOS PATH environment variable.

┌──────────────────────────────────────────────────────────────────────────┐
│ C>WVIDEO/TRap=PLS[;trap_parm] [:sym_file] file_spec [cmd_line]       │
└──────────────────────────────────────────────────────────────────────────┘

The /TRap=PLS option must be specified when debugging applications that are
to be run under the Phar Lap DOS extender.  The "PLS.TRP" and "PLSHELP.EXP"
files will usually be stored in the "BIN" directory of the WATCOM compiler
package.  You should ensure that this "BIN" directory is included in the DOS
PATH environment variable.  Otherwise, you must specify the full path name
for the trap file.

The optional "trap_parm" is passed on to the DOS extender "RUN386" as
command line switches.    When trap_parm is specified and it contains blank
characters, the entire parameter must be placed within braces (e.g.,
/trap=pls;{-minr 128}).

Example:
  C>wvideo /trap=pls;{-maxreal 512} hello
    or
  C>set wvideo=/trap#pls;{-maxreal 512}
  C>wvideo hello
::::DOS_GRAPHICS_APPLICATIONS
When debugging a graphics application, there are a number of VIDEO options
that could be specified depending on your situation.

  1. If you are debugging the graphics application on the same machine on
    which you start VIDEO and you have only one monitor attached to your
    system then the "Swap" option should be used.  The "Swap" option
    specifies that the application's screen memory and the debugger's screen
    memory are to be swapped back and forth using a single page.

  2. If you are debugging the graphics application on the same machine on
    which you start VIDEO and you have two monitors attached to your system
    then the "Two" and "Monochrome" options should be used.  The "Two"
    option specifies that a second monitor is connected to the system.    Note
    that if the monitor type (Monochrome, Color, Colour, Ega43, Vga50) is
    not specified then the monitor that is not currently being used is
    selected for the debugger's screen.  If you specify "Monochrome" then
    the monochrome monitor will be used for the debugger's screen.

  3. If you are debugging the graphics application using a second personal
    computer and the remote debugging feature of VIDEO then the choice of
    display and operation mode for VIDEO is somewhat irrelevant.  If one
    system is equipped with a graphics display and the other with a
    monochrome display then you will undoubtedly use the system equipped
    with the monochrome display to run VIDEO.
::::DOS_INTERRUPTING_A_PROGRAM
Once a program has been loaded by VIDEO, its execution can be started by the
Go command (this command is described in the "GO" topic).

Example:
  C>wvideo myapp
   .
   .
   .
  DBG>go

As is sometimes the case during the development phase, a program may execute
endlessly.

Under DOS, execution of an application may be interrupted by pressing one of
the Print Screen (PrtSc) or System Request (SysRq) keys.  On some keyboards,
the Shift key must also be pressed to obtain the Print Screen function.

VIDEO will print a message in the "Dialogue" window indicating that the
program's execution has been interrupted.  Execution can be resumed with the
Go command.

The Ctrl/Break key combination may be used to interrupt execution of VIDEO
commands.

It also may be used to interrupt an executing program provided that the
following conditions are met:

  1. The program must not be handling Ctrl/Break interrupts itself, and
  2. the program must issue a DOS request (interrupt 0x21) as it is
    executing.

For information on how to interrupt executing programs when using the remote
debugging facility, see the "REMOTE_DEBUGGING" topic.
::::DOS_REMOTE_DEBUGGING
┌──────────────────────────────────────────────────────────────────────────┐
│ WVIDEO /TRap=trap_file[;trap_parm] [:sym_file] file_spec [cmd_line]       │
└──────────────────────────────────────────────────────────────────────────┘

The VIDEO TRap option must be specified when debugging an application using
a second computer system.  The format of file_spec depends on the target
machine's operating system, be it DOS, OS/2, NetWare 386, or QNX.  Under
QNX, file paths contain slashes ("/") as directory separators.    This brings
up an interesting problem when the debug machine is running DOS or OS/2.
Option specifiers can start with slashes also.    When the task machine is
running QNX and you wish to specify a file path, you must use a pair of
slashes to stop VIDEO from continuing its option scan.

Example:
  C>wvideo /trap=par /reg=4 // /users/fred/fdapp

When trap_parm is specified and it contains blank characters, the entire
parameter must be placed within braces (e.g., /trap=dqv;{WATCOM Server}).

You must specify the name of the "trap" file that corresponds to the Debug
Server that was started on the first computer system (the "task machine").
These files handle the machine-to-machine communication required for remote
debugging of an application.  Servers are described under the topics
"REMOTE_DEBUGGING" and "REMOTE_WIN3".

For DOS, the file extension defaults to ".TRP".  The DOS PATH environment
variable must contain the path of the trap files.  Trap files are usually
located in the "BIN" sub-directory of the directory that VIDEO is installed
in.

STD.TRP    Under DOS, if you do not specify a trap file, the default trap
       file "STD.TRP" will be loaded.  This interface module supports
       debugging on the local computer system running DOS.    No remote
       debugging is possible.  The trap file parameter "d" may be
       specified to disable the use of Debug Registers.

SER.TRP    This communications driver file supports debugging of an
       application running on another computer system using the serial
       ports of the two machines.  It communicates with the "SERSERV"
       Debug Server.  The serial port of the debugger machine is
       connected to the serial port of the task machine.  The
       "trap_parm" value specifies the port number to use and an
       optional maximum BAUD rate (which is separated from the port
       number by a period).  The port number is 1, 2, 3 or 4 (default is
       1).    These numbers correspond to the device number used when
       specifying the serial device "COMx" (as in "COM1", "COM2", etc.).

       Under DOS, the maximum BAUD rate can be one of:

         115200
          57600
          38400
          19200
           9600
           4800
           2400
           1200
          0 (a special case)

       The default maximum BAUD rate is 115,200.

       Except for the special BAUD rate of 0, a minimum of two digits
       must be specified to identify the desired maximum BAUD rate.  The
       maximum BAUD rate is explained in the section "Remote Debugging
       Over the Serial Port" under the topic "REMOTE_DEBUGGING".
       In the following example, port 2 and a maximum BAUD rate of
       19,200 is specified.

       Example:
         /trap=ser;2.19

PAR.TRP    This communications driver file supports debugging of an
       application running on another computer system using the parallel
       ports of the two machines.  It communicates with one of the
       "PARSERV" or "PARSERVW" (Microsoft Windows) Debug Servers.  The
       parallel port of the debugger machine is connected to the
       parallel port of the task machine.  The port number to use is
       specified by "trap_parm".  The port number is 1, 2 or 3 (default
       is 1).  These numbers correspond to the device number used when
       specifying the printer device "LPTx" (as in "LPT1", "LPT2",
       etc.).

NOV.TRP    This communications driver file supports debugging of an
       application running on another computer system that is connected
       to the Novell "NetWare" network (NetWare and Novell are
       trademarks of Novell, Inc.).  It communicates with the "NOVSERV"
       Debug Server.  Version 2.0 or later of NetWare must be used.  The
       server name to use is specified by "trap_parm".  The server name
       must match the name that you specified when starting the server
       on the "task" machine.  The default "server_name" is "NovLink".
       The server name must consist of less than 48 characters.

NET.TRP    This communications driver file supports debugging of an
       application running on another computer system using the NetBIOS
       network programming interface.  It communicates with one of the
       "NETSERV" or "NETSERVW" (Microsoft Windows) Debug Servers.  The
       server name to use is specified by "trap_parm".  The server name
       must match the name that you specified when starting the server
       on the "task" machine.  The default "server_name" is "NetLink".
       The server name may consist of up to 15 alphanumeric characters.

DQV.TRP    This communications driver file supports debugging of an
       application that is run under DESQview on DOS.  It communicates
       with the "DQVSERV" Debug Server.  The server name to use is
       specified by "trap_parm".  The server name must match the name
       that you specified when starting the server in a DESQview window.
       The default "server_name" is "WATCOM Server".

       ┌─────────────────────────────────────────────────────────────────┐
       │  Note:  In order to interrupt the execution of an application   │
       │ using one of the Print Screen (PrtSc) or System Request (SysRq) │
       │ keys, you should have DESQview version 2.26 or later.  Pressing │
       │ one of these keys with earlier versions of DESQview will result │
       │ in the current CS:IP pointing into DESQview code.             │
       └─────────────────────────────────────────────────────────────────┘

WIN.TRP    This communications driver file supports debugging of an
       application that is run in a Microsoft Windows DOS box.  It
       communicates with the "WINSERV" Debug Server.  The server name to
       use is specified by "trap_parm".  The server name must match the
       name that you specified when starting the server in a Microsoft
       Windows DOS box.  The default "server_name" is "WinLink".

       Microsoft Windows must be started in standard or enhanced mode.
       When debugging 32-bit applications, you must include the "device"
       specification listed below in the [386Enh] section of your Windows
       "SYSTEM.INI" file.

         DEVICE=[d:]\WATCOM\BINW\WDEBUG.386

       This device driver can be used when debugging 16-bit applications
       also.
::::DOS_STARTUP
┌──────────────────────────────────────────────────────────────────────────┐
│ WVIDEO [options] [:sym_file] file_spec [cmd_line]               │
└──────────────────────────────────────────────────────────────────────────┘

The square brackets [ ] denote items which are optional.

WVIDEO       is the program name for VIDEO.

options    is a list of valid VIDEO options, each preceded by a dash ("-")
       or a slash ("/").  Options may be specified in any order.

sym_file   is an optional symbolic debugging information file specification.
       The specification must be preceded by a colon (":").  For DOS,
       the syntax of sym_file is:

       [d:][path]filename[.ext]

       The default file extension of the symbol file is ".SYM".

       The symbolic information file can be produced by the WATCOM
       Linker WLINK or by the WATCOM Strip Utility WSTRIP.

file_spec  is the file name of the file to be loaded into memory.  For DOS,
       the syntax of file_spec is:

       [d:][path]filename[.ext]

       d:          is an optional drive specification such as "A:", "B:",
              etc.  If not specified, the default drive is assumed.

       path       is an optional path specification such as
              "\UTILS\BIN\".

       filename   is the file name of the file to be loaded into memory.

       ext          is the file extension of the file to be loaded into
              memory.  A null file extension may be specified by
              typing the period "." but not the extension.  If no
              file extension is specified (i.e., both the period and
              extension are omitted) then VIDEO will attempt to load
              an executable image file using, in succession, the
              following extensions.

              For DOS, the search order is:  .COM, .EXE

              For the ERGO DOS extender, the search order is:  .EXP,
              .PLX, .EXE

              For the Phar Lap DOS extender, the search order is:
              .EXP, .EXE

              For the Rational DOS extender, the search order is:
              .EXE

              For NetWare 386, the search order is:  .NLM, .DSK,
              .LAN

cmd_line   is an optional command line which will be passed on to the
       application.

If both drive and path are omitted, VIDEO will first attempt to locate the
file in the current directory of the default drive.  If this fails, VIDEO
will search for the file in each path listed in the PATH environment string.


Command Line Options
════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│     /Monochrome | /Color | /Colour | /Ega43 | /Vga50               │
│     /Overwrite | /Page | /Swap | /Two                    │
│     /Checksize=space                               │
│     /Dynamic=space                               │
│     /NOFpu                                   │
│     /Invoke=file_spec                            │
│     /NOInvoke                                │
│     /NOMouse                                   │
│     /Registers=number                            │
│     /REMotefiles                               │
│     /SIze=space                               │
│     /NOSNow                                   │
│     /NOSymbols                               │
│     /TRap=trap_file[;trap_parm]                       │
└──────────────────────────────────────────────────────────────────────────┘

Options may be specified in any order.    Short forms may be specified for
options and are shown above in capital letters.  If "space" is suffixed with
the letter "K" then "space" refers to multiples of 1K bytes (1024 bytes).
If "space" is suffixed with the letter "B" then "space" refers to the number
of bytes.  If no suffix is specified and "space" is a number less than 1000
then "space" is assumed to refer to multiples of 1K bytes (1024 bytes);
otherwise it refers to the number of bytes.

Display Selection

/Monochrome When two display devices are present in the system, this option
       indicates that the Monochrome display is to be used as the
       debugger's output device.  This option is used in conjunction
       with the Two option described below.

/Color, /Colour When two display devices are present in the system, this
       option indicates that the Colour display is to be used as the
       debugger's output device.  This option is used in conjunction
       with the Two option described below.

/Ega43       When an Enhanced Graphics Adapter (EGA) is present, 43 lines of
       output are displayed.

/Vga50       When an Video Graphics Array (VGA) is present, 50 lines of output
       are displayed.

Display Operation Modes

/Overwrite specifies that the debugger's output can overwrite program
       output.  In this mode, the application and the debugger are
       forced to share the same display area.

       This option may be used to conserve the amount of memory required
       to run VIDEO.  This option should not be used if you wish to
       debug a screen-oriented application (e.g., a graphics
       application) on the same machine.  See the topic entitled
       "DOS_GRAPHICS_APPLICATIONS".

/Page       specifies that page 0 of screen memory is to be used for the
       application's screen and that page 1 of screen memory should be
       used for the debugger's screen.  This option may be selected when
       using a graphics adapter such as the CGA, EGA or VGA.  Use of the
       Page option results in faster switching between the application
       and debugger screens and makes use of the extra screen memory
       available with the adapter.

       This option should not be used if you wish to debug a graphics
       application on the same machine.  See the topic entitled
       "DOS_GRAPHICS_APPLICATIONS".

/Swap       specifies that the application's screen memory and the debugger's
       screen memory are to be swapped back and forth using a single
       page.  The debugger allocates an area in its own data space for
       the inactive screen.  This reduces the amount of memory available
       to the application.    It also takes more time to switch between
       the application and debugger screens.

       This option MUST be used when debugging a graphics application on
       the same machine and a second monitor is not available.  See the
       topic entitled "DOS_GRAPHICS_APPLICATIONS".

/Two       specifies that a second monitor is connected to the system.    If
       the monitor type (Monochrome, Color, Colour, Ega43, Vga50) is not
       specified then the monitor that is not currently being used is
       selected for the debugger's screen.  If the monitor type is
       specified then the monitor corresponding to that type is used for
       the debugger's screen.

       This option should be used when debugging a graphics application
       on the same machine and a second monitor is available.  See the
       topic entitled "DOS_GRAPHICS_APPLICATIONS".

The default display operation is as follows:

  1. If you have a two display system, VIDEO uses both displays with the
    program output appearing on the active monitor and the debugger output
    appearing on the alternate monitor.  In other words, the Two option is
    selected by default.
  2. If you have one of the CGA, EGA or VGA graphics adapters installed in
    your system then VIDEO will select the Page option by default.
  3. Under all other circumstances, VIDEO will select the Swap option by
    default.

/Checksize=space specifies the minimum amount of storage, in kilobytes, that
       VIDEO is to provide to DOS for the purpose of running a program
       via the debugger's SYstem command (this command is described
       under the topic "SYSTEM").  This option is useful when the
       application that is being debugged uses up most or all of
       available storage, leaving insufficient memory to spawn
       secondary programs.    In order to provide the requested amount of
       free memory to DOS, the debugger will checkpoint as much of the
       application as is required.

       Checkpointing involves temporarily storing a portion of the
       memory-resident application on disk and then reusing the part of
       memory that it occupied for the spawned program.  When the
       spawned program terminates, the checkpointed part of the
       application is restored to memory.

       The default amount is 0K bytes.  In this case, the spawned
       program may or may not be run depending on how much free storage
       is available to DOS to run the program.

       ┌─────────────────────────────────────────────────────────────────┐
       │  WARNING!    If the application being debugged installs one or    │
       │ more interrupt handlers, the use of this option could hang your │
       │ system.  Your system could lock up if the debugger checkpoints  │
       │ a portion of the application's code that contains an interrupt  │
       │ handler.                                 │
       └─────────────────────────────────────────────────────────────────┘

/Dynamic=space specifies the amount of dynamic storage that VIDEO is to
       reserve for items such as windows, user-defined symbols, etc.
       The default amount that is set aside is 40960 bytes (40K bytes).
       The amount, if specified, can exceed 64K bytes.  The larger the
       amount, the less memory will be available for the application to
       be debugged.  If you are using the remote debugging feature,
       VIDEO will utilize as much of available memory as it requires.

/NOFpu       requests that the debugger ignore the presence of a math
       coprocessor.  No memory will be allocated by the debugger for
       saving the context of the 80x87 numeric data processor.  Use this
       option if your application will not use the math coprocessor and
       you wish to reduce the amount of memory required by the debugger.

/Invoke=file_spec may be used to specify an alternate name for the debugger
       command file which is to be automatically invoked at start-up
       time.  The default file name is "PROFILE.DBG".  VIDEO command
       files are found in the current directory or one of the
       directories listed in the DOS PATH environment string.

/NOInvoke  specifies that the default debugger command file is not to be
       invoked.

/NOMouse   requests that the debugger ignore any attached mouse.  This may
       be necessary if the program being debugged also uses the mouse
       and the mouse driver installed on the system does not support two
       applications sharing the mouse at the same time.  The program
       "CHKMOUSE.COM" will inform you if the mouse driver supports this
       function.  To determine the capabilities of your mouse driver,
       run the CHKMOUSE program at the DOS command prompt.

       Example:
         C>chkmouse

       The program displays a single line telling you that either your
       mouse driver supports applications sharing the mouse, that it
       does not support applications sharing the mouse, or that there is
       no mouse driver installed.  This program is provided with VIDEO.

       In order to use a mouse, you must install the IBM Mouse Driver
       program that is supplied with the IBM Mouse.  Alternatively, you
       may use a mouse and mouse driver that are compatible with the IBM
       Mouse and IBM Mouse Driver.    The IBM Mouse Driver is installed by
       running the "MOUSE.COM" program.

       Example:
         C>\dos\mouse

/Registers=number may be used to specify how many register sets to set aside
       for the recording of register contents.  The default number of
       register sets is 2.    See the description of the Register command
       for more information (this command is described under the topic
       "REGISTER").

/REMotefiles may be used in conjunction with the remote debugging
       capabilities of the debugger.  Remote debugging involves using
       two personal computers.  One, called the "task machine", is used
       to run the application; the other, called the "debugger machine",
       is used to run the debugger.  When REMotefiles is specified, all
       debugger files (except "trap" files) and application source files
       are opened on the task machine rather than the debugger machine
       (if you are doing local debugging, these two machines are
       actually the same).    The "trap" file must be located on the
       debugger machine because it contains the code to open files on
       the task machine.

       Note that the PATH environment variable on the task machine is
       always used in locating executable image files.  When REMotefiles
       is specified, the debugger also uses the task machine's PATH
       environment variable to locate debugger command files.

/SIze=space specifies the amount of additional overlay space that VIDEO may
       use for its overlay area.  The larger the area (up to a certain
       amount), the better the performance of VIDEO but less memory will
       be available for your application.  The default amount that is
       set aside is 70K bytes.

/NOSNow    requests that VIDEO omit the vertical retrace delay on CGA
       adapters when writing to video memory directly.  The omission of
       this delay will speed up display output.

/NOSymbols requests that VIDEO omit all debugging information when loading
       an executable image.  Information regarding global and local
       symbol names, data types, and line numbers is not processed.

/TRap=trap_file[;trap_parm] must be specified when debugging an application
       on a remote machine or debugging an application running under a
       32-bit DOS extender.  It may also be used to disable the use of
       386/486 Debug Registers.  You must specify the name of one of the
       "trap" files provided with VIDEO.  Under DOS, the file extension
       defaults to ".TRP".    The "BIN" directory contains the trap files
       provided with VIDEO.

       Under DOS, if you do not specify the TRap option, the default
       trap file "STD.TRP" will be loaded.    This interface module
       supports debugging on the local computer system running DOS.

       Example:
         C>wvideo calendar

       Of course, you may also explicitly name the "standard" trap file
       that you wish VIDEO to use.

       Example:
         C>wvideo /trap=std calendar

       See the topic "REMOTE_DEBUGGING" for more information on the
       TRap option.
::::DOS_WVIDEO_ENVIRONMENT_VARIABLE
The WVIDEO environment variable can be used to specify commonly used VIDEO
options.  If the specification of an option involves the use of an "="
character then the "#" character may be used in its place (this is required
by the syntax of the "SET" command).  These options are processed before
options specified on the command line.

Example:
  C>set wvideo=/swap/vga50/reg#4

The above examples illustrate how to define default options for the
debugger.

Once the WVIDEO environment variable has been defined, those options listed
become the default each time VIDEO is invoked.
::::ERROR
┌──────────────────────────────────────────────────────────────────────────┐
│ ERror  text_string | "{" text_string "}"                   │
└──────────────────────────────────────────────────────────────────────────┘

The Error command may be used to display an error message on the screen
which requires an acknowledgement.  This command can be used most
effectively in VIDEO command files.  Currently executing command files are
terminated when the ERror command is issued.

Example:
  DBG>if ~ dbg$fpu {error No 80x87 processor/emulator!}

The message text is displayed in an Error window.
::::EXAMINE
┌──────────────────────────────────────────────────────────────────────────┐
│ Examine                                   │
│     [/Byte]          exam_data                        │
│     /Word          exam_data                        │
│     /Dword          exam_data                        │
│     /Pointer          exam_data                        │
│     /Assembly       addr_data                        │
│     /Source          addr_data                        │
│     /IOByte          port_data                        │
│     /IOWord          port_data                        │
│     /IODword          port_data                        │
└──────────────────────────────────────────────────────────────────────────┘

The Examine command is used to display the contents of memory and I/O ports
in one of several different ways.



Examining Memory as Data
════════════════════════
/Byte exam_data When this qualifier is used, the output from the Examine
       command is written to the Dialogue window.  The output is
       formatted into 8-bit values (bytes) using hexadecimal (base 16)
       notation.  The default qualifier is /Byte.

/Word exam_data When this qualifier is used, the output from the Examine
       command is written to the Dialogue window.  The output is
       formatted into 16-bit values (words) using hexadecimal (base 16)
       notation.  The most significant byte of each word is shown first.

/Dword exam_data When this qualifier is used, the output from the Examine
       command is written to the Dialogue window.  The output is
       formatted into 32-bit values (doublewords) using hexadecimal
       (base 16) notation.    The most significant byte of each doubleword
       is shown first.

/Pointer exam_data When this qualifier is used, the output from the Examine
       command is written to the Dialogue window.  The output is
       formatted into segment/offset pairs (segment:offset) using
       hexadecimal (base 16) notation.

  exam_data ::= [start_addr_expr]
              [ "," [next_addr_expr]
              [ "," [len_expr]
              [ "," rpt_expr ] ] ]

The starting address start_addr_expr is any expression that defines a
segment and offset of memory to be displayed.  The next address
next_addr_expr is any expression that defines the next segment and offset of
memory to be displayed.  The length value len_expr is any expression that
defines the amount of memory to be displayed.  The repetition count rpt_expr
may be any expression that defines the number of times the command is to be
repeated.

For a complete description of valid expressions, see the chapter entitled
"VIDEO Expression Handling".

Example:
  DBG>examine ds:0x0000
  DBG>examine ds:0x0000,.+0x10,0x10

The above two examples are equivalent.    Memory is displayed as a sequence of
bytes starting at the segment defined by the contents of the DS register and
an offset of 0.

The default next_addr_expr is defined as the current starting address (".")
plus 16 (decimal).  The default len_expr is 16 (decimal).

One of the features of the Examine command is its ability to follow linked
lists.    This can be illustrated with an example from the C programming
language.  Imagine that the following structure was defined.

  typedef struct list_entry
    {
      int        entry_number;
      struct list_entry *next;
      int        flags;
      char        *buff_addr;
    } LIST;

  extern LIST *listhead;  /* start of linked list */

The structure definition indicates that the second item in each entry points
to the next entry in the linked list.  To examine the entries in the linked
list (in 16-bit mode), the following command could be issued.

Example:
  DBG>ex/word *listhead,*(.+2),list_entry
  2134:0100 0001 013C 0774 8B55
  2134:013C 0002 011E 0770 8B97
  2134:011E 0003 0142 0074 8B34
  2134:0142 0004 0000 0070 8B55

We use the pointer operator * to indicate memory indirection.  After the
first line is displayed, the current memory location "." is defined to be
"2134:0100".  Hence, ".+2" is "2134:0102" and "*(2134:0102)" is "013C".
Therefore, the next memory location to be displayed is 2134:013C.  Each time
the space bar is pressed, the next memory location is displayed and the
value for "." is updated.

  1. In the above example, we are using type information when we refer to
    list_entry.  In order to specify a type name such as this, the "d2"
    compiler option must have been specified when the module was compiled.
  2. In addition, the "debug types" or "debug all" linker option must have
    preceded the name of the object file containing the module when the
    application was linked.



Examining Memory as Instructions
════════════════════════════════
/Assembly addr_data When this qualifier is used, the output from the Examine
       command is written to the Assembly window if one is present on
       the screen; otherwise output is written to the Dialogue window.
       The output is formatted into Intel machine language instructions.
       Numeric values are displayed in hexadecimal (base 16) notation.
       For any locations that are displayed as "<symbol_name>+offset",
       the value for "offset" is displayed in the current numeric radix.

/Source addr_data When this qualifier is used, the output from the Examine
       command is written to the Source window if one is present on the
       screen; otherwise output is written to the Dialogue window.    If
       both line number information and the source file are available
       then the source lines are displayed.  If only line number
       information is available then only line numbers are displayed.
       If no information is available then no lines will be displayed in
       the Source window.

       If present, line number information is extracted from the
       executable image file.  Source lines are extracted from a source
       file provided that the file can be located.    For more
       information, see the description of the Set Source command.

  addr_data ::= [start_addr_expr] [ "," rpt_expr ]

The starting address start_addr_expr is any expression that defines a
segment and offset of memory to be displayed in the form of assembly
instructions and source lines.    The repetition count rpt_expr may be any
expression that defines the number of times the command is to be repeated.
A positive repetition count is equivalent to that many presses of the space
bar (next).  A negative repetition count is equivalent to that many presses
of the "P" key (previous).

Example:
  DBG>examine/source main_
  DBG>e/s main_

In the above example, two equivalent commands are shown.  The latter is
simply the short form for the former command.  Source lines corresponding to
the application entry point main_ are displayed.

A starting address may also be specified in terms of the module name and
line number.

Example:
  DBG>ex/source calendar@36

The module name need not be specified when it is the current module under
examination.

Example:
  DBG>ex/source @159

Line numbers are shown in the Source window.  Source line information must
be available in order to show source line numbers.

  1. Either compiler options "d1" or "d2" must have been specified when the
    module was compiled.
  2. The "debug lines" or "debug all" linker option must have preceded the
    name of the object file containing the module when the application was
    linked.



Examining Input/Output Ports
════════════════════════════
/IOByte port_data When this qualifier is used, the specified port is read
       and output from the Examine command is written to the Dialogue
       window.  The output is formatted into an 8-bit value (byte) using
       hexadecimal (base 16) notation.

/IOWord port_data When this qualifier is used, the specified port is read
       and output from the Examine command is written to the Dialogue
       window.  The output is formatted into 16-bit values (words) using
       hexadecimal (base 16) notation.  The most significant byte of
       each word is shown first.

/IODword port_data The IODword qualifier is supported on 386 systems or
       higher.  When this qualifier is used, the specified port is read
       and output from the Examine command is written to the Dialogue
       window.  The output is formatted into 32-bit values (doublewords)
       using hexadecimal (base 16) notation.  The most significant byte
       of each doubleword is shown first.

  port_data ::= [start_addr_expr] [ "," rpt_expr ]

The starting address start_addr_expr is any expression that defines an
input/output port at which to begin reading data.  The repetition count
rpt_expr may be any expression that defines the number of times the command
is to be repeated.  A positive repetition count is equivalent to that many
presses of the space bar (next).
::::F77_OPERATORS
VIDEO supports most FORTRAN 77 operators and includes an additional set of
operators for convenience.  The additional operators are patterned after
those available in the C programming language.

The grammar that VIDEO supports is close to that of the FORTRAN 77 language
but there are a few instances where space characters must be used to clear
up any ambiguities.  For example, the expression

  1.eq.x

will result in an error since VIDEO will form a floating-point constant from
the "1." leaving the string "eq.x".  If we introduce a space character after
the "1" then we clear up the ambiguity.

  1 .eq.x

Unlike FORTRAN, the parser in VIDEO treats spaces as significant characters.
Thus spaces must not be introduced in the middle of symbol names, constants,
multi-character operators like .EQ.  or //, etc.

Operators are presented in order of precedence, from lowest to highest.
Operators on the same line have the same priority.

                      Lowest Priority
  Assignment Operators
      =  +=  -=  *=  /=  %=  &=  |=  ^=  <<=  >>=
  Logical Operators
      .EQV.  .NEQV.
      .OR.
      .AND.
      .NOT.
  Bit Operators
      |
      ^
      &
  Relational Operators
      .EQ.  .NE.  .LT.    .LE.  .GT.  .GE.
  Shift and Concatenation Operators
      <<  >>  //
  Arithmetic Operators
      +  -
      *  /  %
      ** (unsupported)
  Unary Operators
      +  -
      ~  ++  --  &   *     %
      [type_name] unary_expr
      ?
  Binary Address Operator
      :
                      Highest Priority

Parentheses can be used to order the evaluation of an expression.

In addition to the operators listed above, a number of primary expression
operators are supported.  These operators are used in identifying the object
to be operated upon.

()       subscripting, substringing, or function call

.       field selection

->       field selection using a pointer

The following built-in functions may be used to convert the specified
argument to a particular type.

  INT( )      conversion to integer
  REAL( )     conversion to real
  DBLE( )     conversion to double-precision
  CMPLX( )    conversion to complex
  DCMPLX( )   conversion to double-precision complex

The following sections describe the operators presented above.



Assignment Operators for the FORTRAN Grammar
════════════════════════════════════════════
=       Assignment:    The value on the right is assigned to the object on
       the left.

+=       Additive assignment:  The object on the left is augmented by the
       value on the right.

-=       Subtractive assignment:  The object on the left is reduced by the
       value on the right.

*=       Multiplicative assignment:  The object on the left is multiplied
       by the value on the right.

/=       Division assignment:  The object on the left is divided by the
       value on the right.

%=       Modulus assignment:    The object on the left is updated with
       MOD(left,right).  The result is the remainder when the value of
       the object on the left is divided by the value on the right.

&=       Bit-wise AND:  The bits in the object on the left are ANDed with
       the bits of the value on the right.

|=       Bit-wise inclusive OR:  The bits in the object on the left are
       ORed with the bits of the value on the right.

^=       Bit-wise exclusive OR:  The bits in the object on the left are
       exclusively ORed with the bits of the value on the right.

<<=       Left shift:    The bits in the object on the left are shifted to
       the left by the amount of the value on the right.

>>=       Right shift:  The bits in the object on the left are shifted to
       the right by the amount of the value on the right.  If the object
       on the left is described as unsigned, the vacated high-order bits
       are zeroed.    If the object on the left is described as signed,
       the sign bit is propagated through the vacated high-order bits.
       VIDEO treats registers as unsigned items.



Logical Operators for the FORTRAN Grammar
═════════════════════════════════════════
.EQV.       Logical equivalence:  The logical equivalence of the value on the
       left and the value on the right is produced.

.NEQV.       Logical non-equivalence:  The logical non-equivalence of the
       value on the left and the value on the right is produced.

.OR.       Logical inclusive disjunction:  The logical OR of the value on
       the left and the value on the right is produced.

.AND.       Logical conjunction:  The logical AND of the value on the left
       and the value on the right is produced.

.NOT.       Logical negation:  The logical complement of the value on the
       right is produced.



Bit Operators for the FORTRAN Grammar
═════════════════════════════════════
|       Bit-wise OR:  The bits of the value on the left and the value on
       the right are ORed.

^       Bit-wise exclusive OR:  The bits of the value on the left and the
       value on the right are exclusively ORed.

&       Bit-wise AND:  The bits of the value on the left and the value on
       the right are ANDed.



Relational Operators for the FORTRAN Grammar
════════════════════════════════════════════
.EQ.       Equal:  If the value on the left is equal to the value on the
       right then the result is 1; otherwise the result is 0.

.NE.       Not equal:  If the value on the left is not equal to the value on
       the right then the result is 1; otherwise the result is 0.

.LT.       Less than:  If the value on the left is less than the value on
       the right then the result is 1; otherwise the result is 0.

.LE.       Less than or equal:    If the value on the left is less than or
       equal to the value on the right then the result is 1; otherwise
       the result is 0.

.GT.       Greater than:  If the value on the left is greater than the value
       on the right then the result is 1; otherwise the result is 0.

.GE.       Greater than or equal:  If the value on the left is greater than
       or equal to the value on the right then the result is 1;
       otherwise the result is 0.



Arithmetic/Logical Shift Operators for the FORTRAN Grammar
══════════════════════════════════════════════════════════
<<       Left shift:    The bits of the value on the left are shifted to the
       left by the amount described by the value on the right.

>>       Right shift:  The bits of the value on the left are shifted to
       the right by the amount described by the value on the right.  If
       the object on the left is described as unsigned, the vacated
       high-order bits are zeroed.    If the object on the left is
       described as signed, the sign bit is propagated through the
       vacated high-order bits.  VIDEO treats registers as unsigned
       items.



Concatenation Operator for the FORTRAN Grammar
══════════════════════════════════════════════
//       String concatenation:  The concatenation of the character string
       value on the left and right is formed.



Binary Arithmetic Operators for the FORTRAN Grammar
═══════════════════════════════════════════════════
+       Addition:  The value on the right is added to the value on the
       left.

_       Subtraction:  The value on the right is subtracted from the value
       on the left.

*       Multiplication:  The value on the left is multiplied by the value
       on the right.

/       Division:  The value on the left is divided by the value on the
       right.

%       Modulus:  The modulus of the value on the left with respect to
       the value on the right is produced.    The result is the remainder
       when the value on the left is divided by the value on the right.

**       Exponentiation:  This operation is not supported by VIDEO.



Unary Arithmetic Operators for the FORTRAN Grammar
══════════════════════════════════════════════════
+       Plus:  The result is the value on the right.

_       Minus:  The result is the negation of the value on the right.

~       Bit-wise complement:  The result is the bit-wise complement of
       the value on the right.

++       Increment:  Both prefix and postfix operators are supported.  If
       the object is on the right, it is pre-incremented by 1 (e.g.,
       ++x).  If the object is on the left, it is post-incremented by 1
       (e.g., x++).

_ _       Decrement:  Both prefix and postfix operators are supported.  If
       the object is on the right, it is pre-decremented by 1 (e.g.,
       --x).  If the object is on the left, it is post-decremented by 1
       (e.g., x--).

&       Address of:    The result is the address (segment:offset) of the
       object on the right (e.g., &main).

*       Points:  The result is the value stored at the location addressed
       by the value on the right (e.g., *(ds:100), *string.loc).  In the
       absence of typing information, the value on the right is treated
       as a pointer into the stack segment and a near pointer is
       produced.

           (SS:00FE) = FFFF
         var:  (SS:0100) = 0152
           (SS:0102) = 1240
           (SS:0104) = EEEE

       In the following example, memory locations are displayed starting
       at DS:152 for 16-bit mode and at DS:12400152 for 32-bit mode.

       Example:
         DBG>examine/byte *100

%       Value at address:  The result is the value stored at the location
       addressed by the value on the right (e.g., %(ds:100),
       %string.loc).  In the absence of typing information, the value on
       the right is treated as a pointer into the stack segment and a
       far pointer is produced.

           (SS:00FE) = FFFF
         var:  (SS:0100) = 0152
           (SS:0102) = 1240
           (SS:0104) = EEEE

       In the following example, memory locations are displayed starting
       at 1240:0152 for 16-bit mode and at EEEE:12400152 for 32-bit
       mode.

       Example:
         DBG>examine/byte %100

       Note that this operator is not found in the FORTRAN 77
       programming language.



Special Unary Operators for the FORTRAN Grammar
═══════════════════════════════════════════════
?       Existence test:  The "?" unary operator may be used to test for
       the existence of a symbol.

       Example:
         DBG>print ?id

       The result of this expression is 1 if "id" is a symbol known to
       VIDEO and 0 otherwise.  If the symbol does not exist in the
       current scope then it must be qualified with its module name.
       Automatic symbols exist only in the current subprogram.



Binary Address Operator for the FORTRAN Grammar
═══════════════════════════════════════════════
:       Memory locations can be referenced by using the binary ":"
       operator and a combination of constants, register names, and
       symbol names.  In the Intel 80x86 architecture, a memory
       reference requires a segment and offset specification.  A memory
       reference using the ":" operator takes the following form:

         segment:offset

       The elements segment and offset can be expressions.

       Example:
         (ES):(DI+100)
         (SS):(SP-20)

Primary Expression Operators for the FORTRAN Grammar
════════════════════════════════════════════════════
()       Elements of an array can be identified using subscript
       expressions.

.       The "." operator indicates field selection in a structure.  This
       operator is useful in mixed language applications where part of
       the application is written in the C programming language.  In the
       following example, tyme2 is a structure and tm_year is a field in
       the structure.

       Example:
         DBG>print tyme2.tm_year

->       The "->" operator indicates field selection when using a pointer
       to a structure.  This operator is useful in mixed language
       applications where part of the application is written in the C
       programming language.  In the following example, tyme is the
       pointer and tm_year is a field in the structure to which it
       points.

       Example:
         DBG>print tyme->tm_year
::::FLIP
┌──────────────────────────────────────────────────────────────────────────┐
│ Flip    [ ON | OFf | expr]                           │
└──────────────────────────────────────────────────────────────────────────┘

The Flip command is used to display the application's screen.  Under DOS,
the "Page" or "Swap" options must have been specified when the debugger was
invoked.  To return to the VIDEO display screen, any key may be pressed or
the left mouse button may be clicked.  If neither of these options were
specified then this form of the command will have no effect.

The "on" and "off" options are used to turn screen switching "on" or "off".
By default, VIDEO will switch between the application's screen and the
debugger's screen (flip on) unless the remote debugging feature is used.  To
prevent VIDEO from switching between screens, flipping may be turned "off".

If an expression is specified, VIDEO will automatically return to the
debugger screen after that number of seconds have passed.  If you press a
key before the time interval has expired, VIDEO will return to the debugger
screen.  If no expression is specifed, VIDEO will wait indefinitely for a
key to be pressed.
::::GO
┌──────────────────────────────────────────────────────────────────────────┐
│ Go        [ start_addr_expr "," ] [ tmp_brk_addr_expr ]           │
│ Go [/Keep] [ start_addr_expr "," ]                       │
└──────────────────────────────────────────────────────────────────────────┘

The Go command is used to start or continue program execution.    Execution
resumes at the specified starting address start_addr_expr or, in the absence
of one, the location defined by the current contents of the CS:IP or CS:EIP
register pair.

If a starting address is specified, it must be followed by a comma.  In the
following example, VIDEO is instructed to resume execution at the start of
"rtn1".

Example:
  DBG>go rtn1,

The following example instructs VIDEO to resume execution at the start of
"rtn1" and also sets a temporary break point at "rtn1+73" so that execution
is suspended before executing the instruction at "rtn1+73".

Example:
  DBG>go rtn1,rtn1+73

A temporary break point may be specified without a starting address.  A
temporary break point is similar to a normal break point except that only
one of them is permitted.  Every time you issue a new Go command, the
previous temporary break point (if it exists) is discarded unless the /Keep
sub-command is specified.  If you wish to retain the previous temporary
break point then you may not specify a new one (since you can have only
one).

Example:
  DBG>go rtn1
  DBG>go rtn2

In the above example, the temporary break point at "rtn1" is replaced by the
temporary break point at "rtn2" when the second Go command is issued.

Example:
  DBG>go rtn1
  DBG>go

In the above example, the temporary break point at "rtn1" is removed when
the second Go command is issued.

Example:
  DBG>go rtn1
  DBG>go/keep

In the above example, the temporary break point at "rtn1" is kept when the
second Go command is issued.

See the description of the Break command for more information on break
points.

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  Execution of a program may be interrupted and control returned to   │
│ the debugger.  The techniques for interrupting program execution are         │
│ described in the topics entitled "..._INTERRUPTING_A_PROGRAM" in         │
│ the topics dealing with the use of VIDEO under a particular operating      │
│ system.  The techniques for interrupting program execution when using the  │
│ remote debugging feature are described under the topic entitled         │
│ "REMOTE_DEBUGGING".                                 │
└────────────────────────────────────────────────────────────────────────────┘
::::HELP
┌──────────────────────────────────────────────────────────────────────────┐
│ Help     [topic]                               │
└──────────────────────────────────────────────────────────────────────────┘

The Help command may be used to obtain help on a particular topic.  If no
topic is specified then a default topic is displayed.  The default topic
includes a list of topics for which help is available.

Unique short forms may be specified for the desired topic.

Example:
  DBG>help go

The above example requests help on the VIDEO Go command.

Help information is displayed in the View window.  If you position the text
cursor on a word in the window and press the Enter key or double-click on it
with a mouse, VIDEO will search for a topic by that name.  More information
on the manipulation of this window with keys or mouse is presented under the
topic entitled "WINDOWS".
::::IF
┌──────────────────────────────────────────────────────────────────────────┐
│ IF  expr  if_cmd_list  [ else_cmd_list ]                   │
└──────────────────────────────────────────────────────────────────────────┘

The specified expression expr is evaluated and if it results in a non-zero
value then the list of debugger commands contained in if_cmd_list is
executed; otherwise the list of commands contained in else_cmd_list is
executed.  The two command lists are separated from one another by the use
of curly braces ({}).

Example:
  DBG>break/set gorun { if x>100 {print{done}}{go/keep} }

In the above example, a break point will occur each time the "gorun" routine
is entered.  The IF command is evaluated by the debugger and if the result
is "true" (i.e., not zero) then the message "done" will be printed in the
Dialogue window and the debugger will prompt for another command; otherwise
execution is resumed (keeping any temporary break point that we may have
specified).

A command of the sort presented next is very useful in locating a problem in
an application.  Let us assume that we are trying to discover which routine
calls our "gorun" routine such that the variable "x" has a zero value after
the "gorun" routine has executed.  The example assumes a 16-bit application.

Example:
  DBG>br gorun {br %sp {if x==0 {} {br/cl /.;go/k}}; go/k}

In the above example, the commands

  br %sp {if x==0 {} {br/cl /.;go/k}}
  go/k

are executed each time the "gorun" routine is entered.    This first command
defines a break point at the return address of the calling routine.  We are
assuming that "gorun" was invoked by a "far" call; hence the stack top
contains a 32-bit segment:offset return address in our 16-bit example.    The
second command resumes execution of the application.  The command

  if x==0 {} {br/cl /.;go/k}

is executed each time a return is made to the calling routine.    If the value
of "x" is zero then no commands are executed and the debugger is entered
(this may be the error case for which we are searching).  Otherwise the
break point for this location is cleared and execution is resumed (keeping
any temporary break point that we may have specified).
::::INVOKE
┌──────────────────────────────────────────────────────────────────────────┐
│ INvoke  cmd_file { parm | "{" parm "}" }                   │
│ <                                       │
└──────────────────────────────────────────────────────────────────────────┘

The INvoke or < command is used to invoke a file containing a number of
VIDEO commands.  The file specification cmd_file has an operating system
dependent form.  For DOS, MS Windows and OS/2, the format is:

  [d:][path]filename[.ext]

For QNX, the format is:

  [//node][path]filename[.ext]

If no file suffix or extension is specified (i.e., both the period and
extension are omitted) then the default is ".dbg".

Under DOS, MS Windows or OS/2, the search order for command files is as
follows:

  1. If only filename or filename.ext are specified, VIDEO will first
    attempt to locate the file in the current working directory.
  2. It will then search the paths listed in the PATH environment variable.
    You should ensure that the "BINB" directory of the WATCOM compiler
    package is included in the PATH environment variable.  This directory
    contains the command files provided with VIDEO.

Under QNX, the search order for command files is as follows:

  1. If only filename or filename.ext are specified, VIDEO will first
    attempt to locate the file in the current working directory.
  2. the paths listed in the WVIDEO_PATH environment variable,
  3. the path listed in the HOME environment variable, and, finally,
  4. the "/etc/wvideo" directory.  The command files provided with VIDEO are
    usually located in the "/etc/wvideo" directory.

Parameters may be passed to the command file.  If any of the parameters
require the use of a semicolon (";") or a space then you should use "{" and
"}" since the semicolon is interpreted as a command separator and the space
is interpreted as a parameter separator by VIDEO.

The parameters are matched up with sequences of <#> in the command file,
where # is a number from 1 to 9.  The first parameter is substituted for
every occurrence of <1>, the second for every occurrence of <2>, and so on.
Any occurrences of <0> are replaced by a unique integer value which is
supplied by the debugger each time the file is invoked.  This feature
permits the creation of unique variables with each invocation of the command
file.

A number of command files are provided with VIDEO that provide excellent
examples of the power and flexibility of command files.

In the following example, assume that the file "count.dbg" contains the
following two lines:

  /cnt_<1>=0
  break/set <1> {/cnt_<1>++; go/keep}

If you enter one of the commands:

  invoke count printf
  <count printf

then each appearance of "<1>" is replaced by "printf" and the resultant
commands are executed.

Example:
  DBG>/cnt_printf=0
  DBG>break/set printf {/cnt_printf++; go/keep}

Each time the "printf" routine is entered, the debugger will increment the
user-defined variable cnt_printf and resume execution (keeping any temporary
break point that we may have specified).  When execution of the application
terminates, the current value of cnt_printf may be examined by using the
Print command to determine how many times the "printf" routine was executed.

Example:
  set pf <1> {
      if !?_dbg@pf_<1> {/_dbg@pf_<1>=0};
      if (++_dbg@pf_<1>)&1 {<2>} {<3>}
  }

In the above example, taken from "toggle.dbg", three parameters are
specified to the command file.

As shown in the previous example, one VIDEO command line may be split across
several lines of a command file.  A line can be split at an opening brace
("{").    To construct the command line, VIDEO will continue to read in input
lines until the matching closing brace is found ("}").

For additional information on command files, see also the description of the
Set Implicit command.
::::LOG
┌──────────────────────────────────────────────────────────────────────────┐
│ Log      [/Start | /Append | >] file_name                   │
│ >                                       │
└──────────────────────────────────────────────────────────────────────────┘

The Log or > command may be used to log Dialogue window output to a
specified file.

/Start file_name This qualifier is used to start logging to the specified
       file.

       Example:
         DBG>log/start dbg.log
         DBG>>/start dbg.log

       The previous contents of the file are lost (overwritten).  When
       file_name is specified and no qualifier is specified then /Start
       is implied.

       Example:
         DBG>log dbg.log

       When neither the qualifier nor filename is specified then any
       currently opened log file is closed.

       Example:
         DBG>log

/Append file_name This qualifier is used to start logging and append logging
       records to the end of the specified file.

       Example:
         DBG>log/append dbg.log
         DBG>>/app dbg.log

> file_name This operator is a synonym for "/append".  Thus it behaves
       identically to the /Append qualifier

       Example:
         DBG>log > dbg.log
         DBG>>> dbg.log

If a log file is currently open, it must be closed before logging can be
done to a different file.  The current log file is closed if a Log command
is entered with no qualifier and filename.  The log file is automatically
closed when the debugger exits (see the description of the Quit command).

Example:
  DBG>log/start debug.log

Output to the Dialogue window is also written to the file "debug.log".

Example:
  DBG>log/append debug.log
  DBG>log> debug.log
  DBG>>>debug.log
  DBG>>/append debug.log

The above examples are all equivalent forms of the Log/Append command.

Under QNX, a path specification that begins with a "/" could be interpreted
as a qualifier.

Example:
  DBG>log /users/fred/debug.log

In the above example, the "/users" qualifier is not supported and an error
will result.  To resolve this conflict, the /Start or /Append qualifiers can
be used.

Example:
  DBG>log /start /users/fred/debug.log
::::MENUS
VIDEO Menus
═══════════
The Set menu on command may be used to cause a menu bar to appear at the top
of the screen.    Menus are provided as an alternative to some of the more
common VIDEO commands.    In the following sections, we explain how to use
menus and provide a brief synopsis of each menu.



Menu Selection
══════════════
Under DOS and MS Windows, menu selection may be activated by pressing and
releasing the Alt key.    The first menu item name or title is highlighted as
shown in the following illustration.

Under other systems (as well as DOS and Windows), press Alt and the first
letter of one of the menu names to select that menu (e.g., Alt/C for
Control).

The cursor left and right keys may be used to highlight a particular menu
item.  The Enter key may be used to select the highlighted menu item.

In some cases, the menu item opens up and a list of choices is usually
displayed.  In others, the menu item invokes an immediate action.  The
action menu items are identified by the "!" which is appended to the menu
title (e.g., Go!).  When a list of menu entries is displayed, the list may
be closed up by pressing the Escape key.  A second press of the Escape key
will return you to the Prompt window.

Alternately, direct selection of a menu item is possible by pressing both
the Alt key and the first letter shown in the menu name or title.  For
example, the "Control" menu may be activated by pressing both the "Alt" and
"C" keys ("Alt" must already be depressed when you press the "C" key).    If
you have a mouse, you can do the same thing by moving the mouse cursor to
one of the menu items in the menu bar and depressing the left mouse button.
If you then release the button, the currently selected item will be
performed.

Menus to the left or right of the current menu may be selected by using the
cursor left and right keys.  As you move left or right, only one menu is
activated.  With a mouse, you can do the same thing by dragging the mouse
through the various menu items in the menu bar.

If a menu opens up, one of the choices is highlighted.    This indicates the
current choice for that menu.  The cursor up and down keys may be used to
select a different choice.  With a mouse, different choices may be selected
by dragging the mouse to the desired item.  When an item has been picked,
the "Enter" key may be used to select it.  When using a mouse, the left
mouse button may be released.

The "Esc" key may be used to quit from a menu.    To quit from a menu with a
mouse, you can either:

  1. release the left button in an area outside of the menu, or
  2. click in an area outside of the menu.

The choice depends on the type of menu presented.

Some selections result in yet other menus being displayed.  The process for
making selections is the same.    Use the cursor left and right keys to move
left and right to other menus that may be shown.  Use the cursor up and down
keys to make a selection in each menu.    To signal that you have made your
selection, press the "Enter" key.  With a mouse you can use the actions of
dragging and clicking to make your selections.



The Control Menu
════════════════
Help       This entry is used to invoke VIDEO's "Help" system.

System       This entry is used to start the system's command interpreter or
       "shell".  If you are using DOS, for example, then the
       "COMMAND.COM" program is run.  Certain conditions must be met
       before the shell can be run and these are listed in the
       description of the System command.

Restart    This entry is used to restart the current application.  The
       application is reloaded into memory and execution is suspended at
       the program's entry point.  At this point, a VIDEO command such
       as "go main" may be entered.  See the description of the New
       /restart command for more information.

View       This entry is used to select a file for viewing.  See the
       description of the View command for more information.

Log       This entry is used to commence logging of VIDEO commands and
       responses to a file.  See the description of the Log command for
       more information.

Quit       This entry is used to quit from the debugger thereby terminating
       the current application.  See the description of the Quit command
       for more information.



The User Menu
═════════════
This is a user-definable list of menu items.  Each entry is created with the
Set menu add command.  An entry is a list of one or more VIDEO commands.
Each new entry is labelled with a letter from the alphabet.  Thus a
particular entry may be selected quickly by pressing the Alt key and the
letter corresponding to the desired entry.  The mouse can also be used to
select an entry.

Up to 20 items can be added to the "User" menu.



The Display Menu
════════════════
The text cursor can be moved directly to a particular window by using this
menu.  Select the window to which you wish to move the text cursor.  See the
description of the Display command for more information.



The Paint Menu
══════════════
The colours for all windows or a particular window may be selected by using
menus.

When using a mouse, clicking on the "Sample" window is equivalent to
pressing the Enter key.

See the description of the Paint command for more information.



The Break! Menu
═══════════════
Break points may be "set", "cleared", "activated" or "deactivated" when
"Break!" is chosen.  Two windows are displayed, one containing a set of
instructions and one containing a list of the break points currently set.

You may press one of the keys "S", "C", "A" or "D" to select the desired
action.  The cursor up and down keys may be used to highlight individual
break points.

A mouse can be used on the list with the usual actions, clicking or dragging
to select a break point.  Clicking on the instruction box areas acts as if
the appropriate key has been pressed.  For example, clicking on the quadrant
that contains "s = set" acts as if the "S" key had been pressed.  See the
description of the Break command for more information.



The Watch! Menu
═══════════════
Watch points may be "set", "cleared", "activated" or "deactivated" when
"Watch!" is chosen.  Two windows are displayed, one containing a set of
instructions and one containing a list of the watch points currently set.
You may press one of the keys "S", "C", "A" or "D" to select the desired
action.  The cursor up and down keys may be used to highlight individual
watch points.

A mouse can be used on the list by the ordinary actions, clicking or
dragging to select a watch point.  Clicking on the instruction box areas
acts as if the appropriate key has been pressed.  For example, clicking on
the quadrant that contains "s = set" acts as if the "S" key had been
pressed.  See the description of the Watch command for more information.



The Trace! Menu
═══════════════
Selecting the "Trace!" menu causes a Trace command (with default arguments)
to be executed.  Trace prompts appear in the prompt window.  Once the trace
prompts are present, you can leave the mouse cursor pointing at the "Trace!"
menu item and select "trace/over" by pressing the left mouse button, and
"trace/into" by pressing the right mouse button.

If you have a mouse, you can click on the "hot-spots" in this window instead
of pressing a key.  For example, clicking on the "<i>" hot-spot is
equivalent to pressing the "I" key when selecting the "into" option of
trace.    See the description of the Trace command for more information.



The Go! Menu
════════════
Selecting the "Go!" menu causes a Go command to be executed.  Program
execution is resumed at the current CS:IP (16-bit mode) or CS:EIP (32-bit
mode) location.  See the description of the Go command for more information.
::::MODIFY
┌──────────────────────────────────────────────────────────────────────────┐
│ Modify                                   │
│     [/Byte]     [addr_expr] [ "," expr_list ]                   │
│     /Word     [addr_expr] [ "," expr_list ]                   │
│     /Dword     [addr_expr] [ "," expr_list ]                   │
│     /Pointer     [addr_expr] [ "," expr_list ]                   │
│     /IOByte     [port_expr] [ "," expr_list ]                   │
│     /IOWord     [port_expr] [ "," expr_list ]                   │
│     /IODword     [port_expr] [ "," expr_list ]                   │
└──────────────────────────────────────────────────────────────────────────┘

The Modify command is used to modify the contents of memory in one of
several different ways.

/Byte [addr_expr] [ "," expr_list ] The starting address addr_expr
       identifies the beginning of a sequence of 8-bit values (bytes).
       Each value that you specify is stored modulo 256 (0x100).

/Word [addr_expr] [ "," expr_list ] The starting address addr_expr
       identifies the beginning of a sequence of 16-bit values (words).
       Each value that you specify is stored modulo 65,536 (0x10000).

/Dword [addr_expr] [ "," expr_list ] The starting address addr_expr
       identifies the beginning of a sequence of 32-bit values
       (doublewords).  Each value that you specify is stored modulo
       4,294,967,296 (0x100000000).

/Pointer [addr_expr] [ "," expr_list ] The starting address addr_expr
       identifies the beginning of a sequence of segment/offset pairs
       (segment:offset).  In 16-bit mode, each value in the pair that
       you specify is stored modulo 65536 (0x10000).  In 32-bit mode,
       each value in the pair that you specify is stored modulo
       4,294,967,296 (0x100000000).  If you do not specify the segment
       value, the current contents of the DS register is used.

/IOByte [port_expr] [ "," expr_list ] The starting port address port_expr
       identifies the beginning of a sequence of 8-bit ports (bytes).
       Each value that you specify is written to the port modulo 256
       (0x100).

/IOWord [port_expr] [ "," expr_list ] The starting port address addr_expr
       identifies the beginning of a sequence of 16-bit ports (words).
       Each value that you specify is written to the port modulo 65,536
       (0x10000).

/IODword [port_expr] [ "," expr_list ] The IODword qualifier is supported on
       386 systems or higher.  The starting port address addr_expr
       identifies the beginning of a sequence of 32-bit ports
       (doublewords).  Each value that you specify is written to the
       port modulo 4,294,967,296 (0x100000000).

If you do not specify a qualifier, the default is /Byte.  If you do not
specify a list of values, VIDEO will prompt for values until an empty line
is entered.  If you do not want to modify a location but want VIDEO to
continue prompting, you can enter a slash ("/") to indicate that the current
value is to be retained.  When specifying a list of values, a location can
be skipped by omitting the value (i.e., a consecutive pair of commas is
entered).

Example:
  DBG>modify 0x200,1,2,3
  DBG>modify/byte 0x200,1,2,3

In the above equivalent examples, memory locations DS:200, DS:201 and DS:202
are modified with the values 1, 2 and 3.

Example:
  DBG>modify 0x200,1,,3

In the above example, memory locations DS:200 and DS:202 are modified with
the values 1 and 3.

Example:
  DBG>modify/word 304
  2335:0304= 0001 :- 0x100
  2335:0306= 1323 :- 0x101
  2335:0308= 8730 :- 0x102
  2335:030A= 0020 :-

In the above example, VIDEO prompts for new word values to replace memory
locations DS:304, DS:306, DS:308 and DS:30A.  Memory location DS:30A is left
unmodified by simply pressing the Enter key in response to the prompt.

Example:
  DBG>modify/word 0x304
  2335:0304= 0001 :- 0x100
  2335:0306= 1323 :- /
  2335:0308= 8730 :- 0x102
  2335:030A= 0020 :-

In the above example, VIDEO prompts for new word values to replace memory
locations DS:304, DS:306, DS:308 and DS:30A.  Memory location DS:306 is left
unmodified by simply entering a "/" in response to the prompt.

Example:
  DBG>modify/pointer _jmptable
  _jmptable= 2223:0602 :- &test1
  _jmptable+04 = 2223:06BE :- &test2
  _jmptable+08 = 2223:0743 :- &test3
  _jmptable+0A = 2223:07B7 :- &test4
  _CMAIN_ = 5756:5153 :-

In the above 16-bit example, VIDEO prompts for new segment:offset values to
replace consecutive memory locations identified by the label _jmptable.  The
values supplied are the addresses of four different routines (the & operator
yields the segment/offset values for the specified location).  The memory
location identified as _CMAIN_ is left unmodified by simply pressing the
Enter key in response to the prompt.

Example:
  DBG>modify/iobyte 0x3F9,0x0D,0x01,0x03,0x0B

In the above example, ports 3F9, 3FA, 3FB and 3FC are modified with the
hexadecimal values 0D, 01, 03 and 0B.

Example:
  DBG>modify/ioword 0x2f8
  02F8= 000D :- 0x000E
  02FA= 0301 :- 0x0302
  02FC= 630B :- 0x630A
  02FE= 0000 :-

In the above example, VIDEO prompts for new word values to store in ports
2F8, 2FA, 2FC, and 2FE.  Port 2FE is left unmodified by simply pressing the
Enter key in response to the prompt.
::::NEW
┌──────────────────────────────────────────────────────────────────────────┐
│ NEW                                       │
│     [/Restart]      [prog_parms]                       │
│     /Program         [:sym_file] program_name [prog_parms]           │
│     /STDIn          [file_name]                       │
│     /STDOut         [file_name]                       │
│     /SYmbol         sym_file [expr_list]                   │
└──────────────────────────────────────────────────────────────────────────┘

The NEW command is used to initialize various items.

/Restart [prog_parms] This qualifier is used to reload the current
       application and place it into an initial state where execution
       may be started over again.  The application may have undergone
       partial or complete execution.  If desired, a new command line
       may be specified for the application.

         prog_parms ::= prog_cmd_line | "{"prog_cmd_line"}"

       You must use "{" and "}" when you have a ";" in the command line
       since VIDEO uses the semicolon as a command separator.

       Example:
         DBG>new {Today is Tuesday}

       The /Restart qualifier is implied when no other qualifier is
       specified.

       Under QNX, a path specification that begins with a "/" could be
       interpreted as a qualifier.

       Example:
         DBG>new /users/fred/test.dat

       In the above example, the "/users" qualifier is not supported and
       an error will result.  To resolve this conflict, the /Restart
       qualifier must be used.

       Example:
         DBG>new/restart /users/fred/test.dat

/Program [:sym_file] program_name [prog_parms] This qualifier is used to
       load a new application and place it into an initial state where
       execution may be started.

       If the symbolic debugging information for the program has been
       placed in a separate file, this file can be specified.  The
       specification must be preceded by a colon (":").  The default
       file extension or suffix of the symbol file is ".sym".  The
       symbolic information file can be produced by the WATCOM Linker or
       by the WATCOM Strip Utility.

       If desired, a command line may be specified for the new
       application.

         prog_parms ::= prog_cmd_line | "{"prog_cmd_line"}"

       You must use "{" and "}" when you have a ";" in the command line
       since VIDEO uses the ";" as a command separator.

       Example:
         DBG>new/prog echo {Today is Tuesday}

       Any break or watch points which may have been active are
       deactivated.

       The specification program_name has the same format as the VIDEO
       command line.  For DOS, MS Windows, OS/2 and NetWare 386 systems,
       the format is:

         [d:][path]filename[.ext]

       For QNX, the format is:

         [//nid] pid
        or
         [//nid] [//node][path]filename

       The semantics for locating and loading a program are identical to
       that described under the topics dealing with the use of VIDEO
       under a particular operating system.

/STDIn [file_spec] This qualifier can be used to associate the standard
       input file handle with a particular file or device.    This is
       similar to specifying <file_spec on the command line.  When
       file_spec is omitted, the standard input file handle is restored
       to its original state.

       Note that the following command does not produce the effect that
       might be anticipated.

       Example:
         DBG>new/prog testit <input.fil

       Instead, the string "<input.fil" will be passed as a parameter to
       the program.  To accomplish the desired effect, the following two
       commands must be issued.

       Example:
         DBG>new/prog testit
         DBG>new/stdin input.fil

/STDOut [file_spec] This qualifier can be used to associate the standard
       output file handle with a particular file or device.  This is
       similar to specifying >file_spec on the command line.  When
       file_spec is omitted, the standard output file handle is restored
       to its original state.

       Note that the following command does not produce the effect that
       might be anticipated.

       Example:
         DBG>new/prog hello >output.log

       Instead, the string ">output.log" will be passed as a parameter
       to the program.  To accomplish the desired effect, the following
       two commands must be issued.

       Example:
         DBG>new/prog hello
         DBG>new/stdout output.log

/SYmbol sym_file [expr_list] This qualifier is used to load additional
       symbolic debugging information and specify the mapping between
       the linker addresses and the actual execution addresses.  This
       feature is useful when debugging Terminate-and-Stay-Resident
       (TSR) programs under DOS, when debugging FoxPro External
       Routines, when debugging AutoCAD ADS/ADI programs, or other
       similar situations.

       The default file extension or suffix of the symbol file is
       ".sym".  The symbolic information file can be produced by the
       WATCOM Linker or by the WATCOM Strip Utility.

       The specification sym_file is system dependent.  For DOS, MS
       Windows, OS/2 and NetWare 386 systems, the format is:

         [d:][path]filename[.ext]

       For QNX, the format is:

         [//node][path]filename

       The optional expression list expr_list varies according to the
       type of application that you are debugging.    For 16-bit,
       real-mode applications (e.g., DOS):

         new/symbol sym_file seg1

       seg1 is the base address (segment:offset) of the program.

       For 32-bit, protect-mode "flat model" applications (e.g., DOS
       extenders, 32-bit Windows, 32-bit OS/2):

         new/symbol sym_file seg1, seg2

       seg1 is the loaded code segment:offset of the program.  seg2 is
       the data/extra/stack segment alias for the loaded code segment
       (in the "flat" model, segments CS, DS, ES, SS all map to the same
       linear address but will have different selector values).

       For 16- or 32-bit, protect-mode segmented applications (e.g.,
       16-bit Windows, 16-bit OS/2, QNX):

         new/symbol sym_file seg1, seg2, seg3, ...

       segN is the loaded segment:offset value for the N'th segment of
       the program.

       If segN is a simple integer (e.g., 5), it is assumed to represent
       a segment value and the offset portion is assumed to be 0.  If
       seg:off is specified (e.g., 5:100) then "seg" is the loaded
       segment value and "off" is added to all symbol address offsets.

       If you do not specify all the required loaded segment values then
       the debugger will begin prompting for the missing values.

       For examples of the NEW /SYmbol command, see the VIDEO command
       file ADS.DBG or FOX.DBG.

       When debugging DOS applications locally, it may be necessary to
       specify the VIDEO "Dynamic" option when starting up the debugger.
       For example, you may get the message "no memory for symbolic
       information".  This indicates that the option must be specified.
::::NOTATION
The following notation is used to describe the syntax of VIDEO commands.

Abc       The short form for the item abc is a.  For example, if the item
       is "COMPute", the valid forms are "comp", "compu", "comput" and
       "compute".

[abc]       The item abc is optional.

{abc}       The item abc may be repeated zero or more times.

"abc"       The characters abc are required.

a|b|c       One of a, b or c may be specified.

a ::= b    The item a is defined in terms of b.

To test your understanding of the above notation, consider the following
example.

  dec_digit ::= "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"

In the above example, a decimal digit (dec_digit) is defined as one of the
characters "0" through "9" (a "0" or a "1" or a "2", etc.).  We could then
define a decimal number to be

  decimal_number ::= dec_digit {dec_digit}

This is read as "a decimal number is defined to be a decimal digit followed
by zero or more decimal digits".  Clearly, "12345" conforms to our rule
whereas "12ABC" and "Hello" do not.

We also use several abbreviated terms in the description of VIDEO commands.

Short Form Explanation

addr       "address"
arg       "argument"
brk       "break", "break point"
char       "character"
cmd       "command"
expr       "expression"
num       "number"
parm       "parameter"
prog       "program"
reg       "register"
spec       "specifier"
tmp       "temporary"

We also concatenate these abbreviations by using the underscore to define
new abbreviations.

Examples:

addr_expr  "address expression"

cmd_spec   "command specifier"

Several commands may be entered on one line by separating them with
semicolons.

Example:
  DBG>do myvar=var*2;print myvar

In the above example, the first command sets the variable myvar to twice the
value of var and the second command prints this new value.

Using our notation, we define a command line as follows:

  cmd_line ::= [cmd] { ";" [cmd] }

While such definitions may be quite precise, they often tend to be somewhat
more obscure.  If we analyze the definition carefully, we will discover that
an empty line qualifies as a command.  In the following sections, we will
first present the concise command syntax.  This is followed by an
explanation of both the syntax and semantics of the command.  A number of
examples are also presented so that you may get a "feel" for the command's
syntax.
::::OS2_INTERRUPTING_A_PROGRAM
Once a program has been loaded by VIDEO, its execution can be started by the
Go command (this command is described under the topic entitled "GO").

Example:
  [C:\]wvideo myapp
   .
   .
   .
  DBG>go

As is sometimes the case during the development phase, a program may execute
endlessly.

Under OS/2, execution of an application may be interrupted by pressing the
Ctrl/Break key combination in the VIDEO session.

VIDEO will print a message in the "Dialogue" window indicating that the
program's execution has been interrupted.  Execution can be resumed with the
Go command.

Also, execution of VIDEO commands may be interrupted by pressing the
Ctrl/Break key combination in the VIDEO session.

For information on how to interrupt executing programs when using the remote
debugging facility, see the topic entitled "REMOTE_DEBUGGING".
::::OS2_REMOTE_DEBUGGING
┌──────────────────────────────────────────────────────────────────────────┐
│ WVIDEO /TRap=trap_file[;trap_parm] [:sym_file] file_spec [cmd_line]       │
└──────────────────────────────────────────────────────────────────────────┘

The VIDEO TRap option must be specified when debugging an application using
a second computer system.  The format of file_spec depends on the target
machine's operating system, be it DOS, OS/2, NetWare 386, or QNX.  Under
QNX, file paths contain slashes ("/") as directory separators.    This brings
up an interesting problem when the debug machine is running DOS or OS/2.
Option specifiers can start with slashes also.    When the task machine is
running QNX and you wish to specify a file path, you must use a pair of
slashes to stop VIDEO from continuing its option scan.

Example:
  [C:\]wvideo /trap=par /reg=4 // /users/fred/fdapp

When trap_parm is specified and it contains blank characters, the entire
parameter must be placed within braces ({}).

You must specify the name of the "trap" file that corresponds to the Debug
Server that was started on the first computer system (the "task machine").
These files handle the machine-to-machine communication required for remote
debugging of an application.  Servers are described under the topics entitled
"REMOTE_DEBUGGING" and "REMOTE_WIN3".

For OS/2, the file extension defaults to ".DLL".  The OS/2 LIBPATH directive
in the "CONFIG.SYS" file must be used to identify the location of the "DLL"
trap files.  Trap files are usually located in the "BINP\DLL" sub-directory
of the directory that VIDEO is installed in.

STD16.DLL  Under OS/2 version 1.x, if you do not specify a trap file, the
       default trap file "STD16.DLL" will be loaded.  These interface
       modules support debugging on the local computer system running
       OS/2 1.x.  No remote debugging is possible.

       Under OS/2 version 1.x, if you do specify the trap file name
       "STD" then "STD16.DLL" is selected.

STD32.DLL  Under OS/2 version 2.x, if you do not specify a trap file, the
       default trap file "STD32.DLL" will be loaded.  These interface
       modules support debugging on the local computer system running
       OS/2 2.x.  No remote debugging is possible.

       Under OS/2 version 2.x, if you do specify the trap file name
       "STD" then "STD32.DLL" is selected.

SER.DLL    This communications driver file supports debugging of an
       application running on another computer system using the serial
       ports of the two machines.  It communicates with the "SERSERV"
       Debug Server.  The serial port of the debugger machine is
       connected to the serial port of the task machine.  The
       "trap_parm" value specifies the port number to use and an
       optional maximum BAUD rate (which is separated from the port
       number by a period).  The port number is 1, 2, 3 or 4 (default is
       1).    These numbers correspond to the device number used when
       specifying the serial device "COMx" (as in "COM1", "COM2", etc.).

       Under OS/2, the maximum BAUD rate can be one of:

          19200
           9600
           4800
           2400
           1200
          0 (a special case)

       The default maximum BAUD rate is 19,200.

       Except for the special BAUD rate of 0, a minimum of two digits
       must be specified to identify the desired maximum BAUD rate.  The
       maximum BAUD rate is explained in the section "Remote Debugging
       Over the Serial Port" under the topic entitled "REMOTE_DEBUGGING".
       In the following example, port 2 and a maximum BAUD rate of
       19,200 is specified.

       Example:
         /trap=ser;2.19

PAR.DLL    This communications driver file supports debugging of an
       application running on another computer system using the parallel
       ports of the two machines.  It communicates with one of the
       "PARSERV" or "PARSERVW" (Microsoft Windows) Debug Servers.  The
       parallel port of the debugger machine is connected to the
       parallel port of the task machine.  The port number to use is
       specified by "trap_parm".  The port number is 1, 2 or 3 (default
       is 1).  These numbers correspond to the device number used when
       specifying the printer device "LPTx" (as in "LPT1", "LPT2",
       etc.).

NOV.DLL    This communications driver file supports debugging of an
       application running on another computer system that is connected
       to the Novell "NetWare" network (NetWare and Novell are
       trademarks of Novell, Inc.).  It communicates with the "NOVSERV"
       Debug Server.  Version 2.0 or later of NetWare must be used.
       Version 1.3 or later of the NetWare requestor is also required
       and, in turn, this requires OS/2 version 1.2 or later.

       The server name to use is specified by "trap_parm".    The server
       name must match the name that you specified when starting the
       server on the "task" machine.

NET.DLL    This communications driver file supports debugging of an
       application running on another computer system using the NetBIOS
       network programming interface.  It communicates with one of the
       "NETSERV" or "NETSERVW" (Microsoft Windows) Debug Servers.  The
       server name to use is specified by "trap_parm".  The server name
       must match the name that you specified when starting the server
       on the "task" machine.  The server name may consist of up to 15
       alphanumeric characters.
::::OS2_STARTUP
┌──────────────────────────────────────────────────────────────────────────┐
│ WVIDEO [options] [:sym_file] file_spec [cmd_line]               │
└──────────────────────────────────────────────────────────────────────────┘

The square brackets [ ] denote items which are optional.

WVIDEO       is the program name for VIDEO.

options    is a list of valid VIDEO options, each preceded by a dash ("-")
       or a slash ("/").  Options may be specified in any order.

sym_file   is an optional symbolic debugging information file specification.
       The specification must be preceded by a colon (":").  For OS/2,
       the syntax of sym_file is:

       [d:][path]filename[.ext]

       The default file extension of the symbol file is ".SYM".

       The symbolic information file can be produced by the WATCOM
       Linker WLINK or by the WATCOM Strip Utility WSTRIP.

file_spec  is the file name of the file to be loaded into memory.  For OS/2,
       the syntax of file_spec is:

       [d:][path]filename[.ext]

       d:          is an optional drive specification such as "A:", "B:",
              etc.  If not specified, the default drive is assumed.

       path       is an optional path specification such as
              "\UTILS\BIN\".

       filename   is the file name of the file to be loaded into memory.

       ext          is the file extension of the file to be loaded into
              memory.  A null file extension may be specified by
              typing the period "." but not the extension.  If no
              file extension is specified (i.e., both the period and
              extension are omitted), the default is ".EXE".

cmd_line   is an optional command line which will be passed on to the
       application.

If both drive and path are omitted, VIDEO will first attempt to locate the
file in the current directory of the default drive.  If this fails, VIDEO
will search for the file in each path listed in the PATH environment string.



Command Line Options
════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│     /Dynamic=space                               │
│     /NOFpu                                   │
│     /Invoke=file_spec                            │
│     /Lines=number                               │
│     /NOInvoke                                │
│     /NOMouse                                   │
│     /Registers=number                            │
│     /REMotefiles                               │
│     /NOSymbols                               │
│     /TRap=trap_file[;trap_parm]                       │
└──────────────────────────────────────────────────────────────────────────┘

Options may be specified in any order.    Short forms may be specified for
options and are shown above in capital letters.  If "space" is suffixed with
the letter "K" then "space" refers to multiples of 1K bytes (1024 bytes).
If "space" is suffixed with the letter "B" then "space" refers to the number
of bytes.  If no suffix is specified and "space" is a number less than 1000
then "space" is assumed to refer to multiples of 1K bytes (1024 bytes);
otherwise it refers to the number of bytes.

/Dynamic=space specifies the initial amount of dynamic storage that VIDEO is
       to reserve for items such as windows, user-defined symbols, etc.
       The default amount that is set aside is 40960 bytes (40K bytes).
       As additional storage is required, VIDEO will allocate it.

/NOFpu       requests that the debugger ignore the presence of a math
       coprocessor.  No memory will be allocated by the debugger for
       saving the context of the 80x87 numeric data processor.  Use this
       option if your application will not use the math coprocessor and
       you wish to reduce the amount of memory required by the debugger.

/Invoke=file_spec may be used to specify an alternate name for the debugger
       command file which is to be automatically invoked at start-up
       time.  The default file name is "PROFILE.DBG".  VIDEO command
       files are found in the current directory or one of the
       directories listed in the OS/2 PATH environment string.

/Lines=number may be used to specify the number of display lines that VIDEO
       is to use.  If this option is not specified, the default number
       of output lines is selected.  When an Enhanced Graphics Adapter
       (EGA) is present, 43 lines of output may be requested.  When an
       Video Graphics Array (VGA) is present, 28 or 50 lines of output
       may be requested.

/NOInvoke  specifies that the default debugger command file is not to be
       invoked.

/NOMouse   requests that the debugger ignore any attached mouse.

/Registers=number may be used to specify how many register sets to set aside
       for the recording of register contents.  The default number of
       register sets is 2.    See the description of the Register command
       for more information (this command is described under the topic
       entitled "REGISTER").

/REMotefiles may be used in conjunction with the remote debugging
       capabilities of the debugger.  Remote debugging involves using
       two personal computers.  One, called the "task machine", is used
       to run the application; the other, called the "debugger machine",
       is used to run the debugger.  When REMotefiles is specified, all
       debugger files (except "trap" files) and application source files
       are opened on the task machine rather than the debugger machine
       (if you are doing local debugging, these two machines are
       actually the same).    The "trap" file must be located on the
       debugger machine because it contains the code to open files on
       the task machine.

       Note that the PATH environment variable on the task machine is
       always used in locating executable image files.  When REMotefiles
       is specified, the debugger also uses the task machine's PATH
       environment variable to locate debugger command files.

/NOSymbols requests that VIDEO omit all debugging information when loading
       an executable image.  Information regarding global and local
       symbol names, data types, and line numbers is not processed.

/TRap=trap_file[;trap_parm] must be specified when debugging an application
       on a remote machine.  You must specify the name of one of the
       "trap" files provided with VIDEO.  Under OS/2, the file extension
       defaults to ".DLL".    The "BINP\DLL" directory contains the
       dynamic link libraries (DLL) provided with VIDEO.  The OS/2
       LIBPATH directive in the "CONFIG.SYS" file must be used to
       identify the location of the "DLL" trap files.

       If you do not specify the TRap option then VIDEO assumes that the
       application is to be run on the same computer system and it uses
       one of the default trap files described next.

       Example:
         [C:\]wvideo calendar

       Under OS/2 version 1.x, if you do not specify a trap file, the
       default trap file "STD16.DLL" will be loaded.  This interface
       module supports debugging on the local computer system running
       OS/2 1.x.

       Under OS/2 version 2.x, if you do not specify a trap file, the
       default trap file "STD32.DLL" will be loaded.  This interface
       module supports debugging on the local computer system running
       OS/2 2.x.

       If you do specify the trap file name "STD" then "STD16.DLL" is
       selected for OS/2 version 1.x systems and "STD32.DLL" is selected
       for OS/2 version 2.x systems.

       Example:
         [C:\]wvideo /trap=std calendar

       Of course, you may also explicitly name the "standard" trap file
       that you wish VIDEO to use.

       Example:
         [C:\]wvideo /trap=std16 calendar

       See the topic entitled "REMOTE_DEBUGGING" for more
       information on the TRap option.
::::OS2_WVIDEO_ENVIRONMENT_VARIABLE
The WVIDEO environment variable can be used to specify commonly used VIDEO
options.  If the specification of an option involves the use of an "="
character then the "#" character may be used in its place (this is required
by the syntax of the "SET" command).  These options are processed before
options specified on the command line.

Example:
  [C:\]set wvideo=/lines#50/reg#4

The above examples illustrate how to define default options for the
debugger.

Once the WVIDEO environment variable has been defined, those options listed
become the default each time VIDEO is invoked.
::::PAINT
┌──────────────────────────────────────────────────────────────────────────┐
│ PAint (window_name | ["*"]) attr_name [ fg_col ["," bg_col] ]        │
└──────────────────────────────────────────────────────────────────────────┘

The PAint command is used to define the colour composition of windows.    The
valid window names are:

  Assembly
  Command
  Dialogue
  Fpu
  Memory
  Prompt
  Register
  SOurce
  STack
  Thread

An asterisk ("*") may be used to denote all of them.  If a window name is
omitted then "*" is assumed.

Five different attributes of a window may be individually coloured.  The
attribute attr_name may be one of:

  Plain
  Active
  Standout
  Title
  Gadget

Foreground (fg_col) and background (bg_col) colours may be selected from the
following:

  BLAck
  BLUe
  GREEn
  Cyan
  Red
  Magenta
  BROwn
  White

In addition, the following foreground colour variations may be selected:

  BRIght BLAck
  BRIght BLUe
  BRIght GREEn
  BRIght Cyan
  BRIght Red
  BRIght Magenta
  BRIght BROwn
  BRIght White
  GRAy
  GREY
  Yellow

"GRAy" and "GREY" are synonyms for "BRIght BLAck".  "Yellow" is a synonym
for "BRIght BROwn".  The "BLINking" keyword may be also precede a foreground
colour to specify that the item should also blink when it is displayed.
Please note that colour attributes on the IBM Monochrome Display and Printer
Adapter will behave as described in the following table.

Colour       Monochrome

black       (invisible)
blue       underlined white
green       white
cyan       white
red       white
magenta    white
brown       white
white       white
bright black (invisible)
bright blue bright white
bright green white
bright cyan white
bright red white
bright magenta white
bright brown white
bright white white

When specifying colour attributes for a window item, the foreground colour
is specified first and the background colour last.  If one of the foreground
or background colours is omitted, it will remain unchanged.  Note that the
background colour specification is always preceded by a comma.

Attributes: Description:

Plain       Each window displays "plain" text.  This text usually forms the
       greater part of a window.

       Example:
         DBG>paint * plain white,blue

       In the above example, the plain text of all windows is set to
       white characters on a blue background.

       Example:
         DBG>paint assembly plain bright green,red

       In the above example, the plain text of the Assembly window only
       is set to bright green characters on a red background.

Active       Some items in a window may be highlighted in the "active" colour
       combination.  For example, the source line or assembler
       instruction that is about to be executed is displayed in the
       "active" colour attributes.

       Example:
         DBG>paint * active bright white,blue

       In the above example, the "active" text of all windows is set to
       bright white characters on a blue background.

       Example:
         DBG>paint source active cyan,brown

       In the above example, the "active" text of the Source window only
       is set to cyan characters on a brown background.

Standout   Some items in a window may be highlighted with the "standout"
       colour combination.    For example, the source line or assembler
       instruction that is displayed by using the Examine /Source
       command is displayed in the "standout" colour attributes.

       Example:
         DBG>paint * standout red,white

       In the above example, the "standout" text for all windows is set
       to red characters on a white background.

       Example:
         DBG>paint source standout brown,cyan

       In the above example, the "standout" text of the Source window
       only is set to brown characters on a cyan background.

Title       Each window may be titled and the colours for the title line may
       be selected.

       Example:
         DBG>paint * title yellow,magenta

       In the above example, the title lines for all windows bearing
       titles are displayed with yellow characters on a magenta
       background.

       Example:
         DBG>paint assembly title magenta,green

       In the above example, if there is a title line for the Assembly
       window then it will be displayed with magenta characters on a
       green background.

Gadget       Mouse window gadgets are displayed in the "gadget" colour
       combination.

       Example:
         DBG>paint * gadget black, cyan

       In the above example, the "gadget" colours for all windows is set
       to black characters on a cyan background.
::::PRINT
┌──────────────────────────────────────────────────────────────────────────┐
│ Print [/Program] { "{"format_spec"}" expr_list }               │
│ ?                                       │
└──────────────────────────────────────────────────────────────────────────┘

The Print or ?    command evaluates one or more expressions and prints the
results in the Dialogue window, or the application's standard error area
(usually the screen of the task machine) if the /Program qualifier is
specified.  The Print command is useful for examining the values of
variables and expressions.  The expressions can involve registers,
application variables and user-defined debugger variables.  The operations
possible are patterned after those available in the WATCOM C and WATCOM
FORTRAN 77 compilers.  Expressions are fully discussed in the chapter
entitled "VIDEO Expression Handling".

By default, integer values are printed in the current default numeric radix,
pointer values are printed in hexadecimal notation, and floating-point
values are printed in floating-point notation.    In addition, if the
expression is an enumerated type, the name of the enumeration constant
corresponding to the numeric value of the expression is printed.  If the
numeric value does not have a corresponding enumeration constant, the value
is printed in the current default numeric radix.

To print out the value in some other representation, a format string may
also be specified.  Formally, the format specification is defined as
follows:

  format_spec ::= { char | "%"specifier }
  specifier   ::= "i" | "d" | "u" | "x" | "X"
              | "o" | "p" | "c" | "s" | "%"
              | "f" | "g" | "G" | "e" | "E"
              | "r" | "a" | "l"

Text may be included to annotate the output.

Specifiers: Description:

"i"       The corresponding argument is printed out as a signed decimal
       integer value.

"d"       The corresponding argument is printed out as a signed decimal
       integer value.

"u"       The corresponding argument is printed out as an unsigned decimal
       integer value.

"x"       The corresponding argument is printed out as an unsigned
       hexadecimal integer value.  Letter digits are printed in lower
       case (a-f).

"X"       The corresponding argument is printed out as an unsigned
       hexadecimal integer value.  Letter digits are printed in upper
       case (A-F).

"o"       The corresponding argument is printed out as an unsigned octal
       integer value.

"p"       The corresponding argument is printed out as a pointer
       (segment:offset) value in hexadecimal notation.

"c"       The corresponding argument is printed out as a single character
       value.

"s"       The corresponding argument is printed out as a C string value.
       The argument must point to a string of characters terminated by a
       byte whose value is zero.

"%"       To print out a percentage symbol, the "%" must be doubled up
       (i.e.  %%).

"f"       The corresponding argument is printed out in floating-point
       representation.  If the floating-point value has a very large or
       small magnitude, you should use one of "g", "G", "e" or "E"
       formatting.

"g"       The corresponding argument is printed out in floating-point
       representation.  Numbers of very large or small magnitude are
       printed out in scientific "E" notation (e.g., 1.54352e+16).    The
       exponent letter is printed in lower case.

"G"       The corresponding argument is printed out in floating-point
       representation.  Numbers of very large or small magnitude are
       printed out in scientific "E" notation (e.g., 1.54352E+16).    The
       exponent letter is printed in upper case.

"e"       The corresponding argument is printed out in scientific "E"
       notation (e.g., 1.23456e+02).  The exponent letter is printed in
       lower case.

"E"       The corresponding argument is printed out in scientific "E"
       notation (e.g., 1.23456E+02).  The exponent letter is printed in
       upper case.

"r"       The corresponding argument is printed out in the current default
       numeric radix.

"a"       The corresponding argument is printed out as a symbol reference
       (symbol_name+offset) when possible; otherwise it is printed out
       as a pointer (segment:offset) value in hexadecimal notation.

"l"       The corresponding argument is printed out as a line number
       reference (module_name@line_number+offset) when possible;
       otherwise it is printed out as a pointer (segment:offset) value
       in hexadecimal notation.

Example:
  DBG>print ax
  DBG>? ax

The value of the AX register is displayed in hexadecimal format (assuming a
default numeric radix of 16) in the Dialogue window.

Example:
  DBG>? [dx ax]

The contents of the DX and AX registers are treated as a single 32-bit long
integer and displayed in hexadecimal format (assuming a default numeric
radix of 16).  This grouping of registers is called an aggregate.

Example:
  DBG>? {%i} [cx bx]

The aggregate formed by concatenating the CX and BX registers is treated as
a 32-bit long integer and displayed in decimal integer format.

Example:
  DBG>? (float) [ax bx]

By employing type casting, the long integer value in this register aggregate
is converted to a floating-point value and displayed in floating-point
format.

Example:
  DBG>? [float] [ax bx]

By employing the type "pun" operator, the 32-bit value in this register
aggregate is treated as a floating-point value and displayed in
floating-point format.    By default, the 32-bit quantity would have been
treated as a long integer.

Example:
  DBG>? [ax bx cx dx]

The aggregate formed from the AX, BX, CX and DX registers is treated as a
64-bit floating-point entity and displayed in floating-point format.  By
default, 64-bit register aggregates are treated as double precision
floating-point values.

Example:
  DBG>print {The answer is %d (0x%x)} ans=foo/2, ans

The result of dividing the value of foo by 2 is displayed in the Dialogue
window in both decimal and hexadecimal format.

Example:
  DBG>? &main_

The address of main_ (segment:offset) is displayed in the Dialogue window.

Example:
  DBG>? {The address of "main" is %p} &main_

The address of main_ (segment:offset) is displayed as part of a string of
text in the Dialogue window.

Example:
  DBG>? ax=dx

The contents of the DX register are assigned to the AX register and the
result is displayed in the Dialogue window.

Example:
  DBG>print {%c-%c-%c-%c}3,4,5,6

The "heart", "diamond", "club" and "spade" characters are displayed in the
Dialogue window separated by hyphens.

Example:
  DBG>print {%f} flt_val1

The variable flt_val1 is displayed in floating-point notation.

Example:
  DBG>? {%i} (int) 3.1415926

The argument is displayed as the decimal integer value 3.

Example:
  DBG>? (char *) 256

The argument (a pointer) is displayed as a pointer value in hexadecimal
notation (e.g., "0100").  This is the default formatting for pointers.

Example:
  DBG>? {%r} (char *) 256

The argument (a pointer) is displayed in the current default radix ("0256"
if the current default radix is decimal).

Consider the following 16-bit example.

Example:
  DBG>? {%x,%x} 65536, (int) 65536

The first argument, the long integer 65536, is displayed as "10000".  The
second argument is converted to a short integer and is displayed as "0"
since 65536 exceeds the range of 16-bit unsigned values by 1.



Printing Array Slices
═════════════════════
When the appropriate type information is available, VIDEO can print out the
contents of an array.  By default, the debugger will print out the contents
of the entire array.  Consider the following 3-dimensional array defined in
the C programming language.

Example:
  char *ProcessorType[2][4][2] =
      { { { "Intel 8086",   "Intel 8088"  },
      { "Intel 80186",  "Intel 80188" },
      { "Intel 80286",  "unknown" },
      { "Intel 80386",  "unknown" } },

    { { "NEC V30",        "NEC V20" },
      { "unknown",        "unknown" },
      { "unknown",        "unknown" },
      { "unknown",        "unknown" } } };

This array can be viewed as two layers of rectangular matrices of 4 rows by
2 columns.  The array elements are all pointers to string values.

To examine the contents of the array, the following command can be issued.
The response to the command is also shown.

Example:
  DBG>?processortype
  {[0]={[0]={[0]=0x0024, [1]=0x002F},
    [1]={[0]=0x003A, [1]=0x0046},
    [2]={[0]=0x0052, [1]=0x005E},
    [3]={[0]=0x0066, [1]=0x005E}},
   [1]={[0]={[0]=0x0072, [1]= 0x007A},
    [1]={[0]=0x005E, [1]=0x005E},
    [2]={[0]=0x005E, [1]=0x005E},
    [3]={[0]=0x005E, [1]=0x005E}}}

The values shown are the addresses of the string values.

By using dimension specifiers, specific slices of an array can be displayed.
To see only the values of the first layer, the following command can be
issued.

Example:
  DBG>?processortype[0]
  {[0]={[0]=0x0024, [1]=0x002F},
   [1]={[0]=0x003A, [1]=0x0046},
   [2]={[0]=0x0052, [1]=0x005E},
   [3]={[0]=0x0066, [1]=0x005E}}

Note that this corresponds to the first half of the addresses displayed in
the previous example.

To see only the first row of the first layer, the following command can be
issued.

Example:
  DBG>?processortype[0][0]
  {[0]=0x0024, [1]=0x002F}

To see the second row of the first layer, the following command can be
issued.

Example:
  DBG>?processortype[0][1]
  {[0]=0x003A, [1]=0x0046}

To see the value of a specific entry in a matrix, all the indices can be
specified.

Example:
  DBG>?{%s} processortype[0][0][0]
  Intel 8086
  DBG>?{%s} processortype[0][0][1]
  Intel 8088
  DBG>?{%s} processortype[0][1][0]
  Intel 80186

In the above examples, we use the "%s" format specifier to display the
string values.
::::PRINT_WINDOW
┌──────────────────────────────────────────────────────────────────────────┐
│ Print /Window expr                               │
│ ?                                       │
└──────────────────────────────────────────────────────────────────────────┘

The Print /Window command may be used to display the results of a Print
command in a Variable Display window that is created dynamically.

A Variable Display window is placed on the screen showing the variable
including fields if it is a structure.    The window is updated each time the
debugger is entered.  The window may be manipulated in the same manner as
other windows.    When the Variable Display window is created, it inherits the
colour attributes of the Dialogue window.  The Ctrl/P (paint) key may be
used to redefine the window's colour attributes.  It may be resized using
the Ctrl/N (narrow), Ctrl/W (widen), Ctrl/S (shrink), and Ctrl/G (grow) keys
or by manipulating the "resizer" gadget with a mouse.  It may be moved using
the Ctrl/U (up), Ctrl/D (down), Ctrl/L (left) and Ctrl/R (right) keys or by
dragging the title line with a mouse.  The window may be removed using the
Ctrl/E (erase) key or by clicking on the "close" gadget.

If a structure is displayed, the cursor up and down keys may be used to move
up and down through fields.  To display the contents of a field, the Enter
key can be pressed.  To return to the previous level, the Backspace key can
be pressed.  Entries that represent structures are displayed by using
"{...}" and entries that represent arrays are displayed by using "(...)"
Essentially, the Enter key permits you to "descend" to nested structures and
the Backspace key permits you to "ascend" to a previous level.

If an entry represents a string, the "S" key can be used to display the
entry as a string.  The Backspace key can be used to return to the original
display format.

The top entry in the window displays the current structure nesting level.
You can move the cursor to this entry and edit it.  If the entry represents
a field in a structure, you can ascend to the previous level by removing the
trailing field.  By adding new fields, you can descend to nested levels.

A mouse can be used to select and view fields by clicking on them.  If you
click on the line of dashes in the window, you will ascend to previous
levels.

The Escape key or the mouse can be used to move to the Prompt window.
::::QNX_DEBUGGING_USING_POSTMORTEM_DUMP
A limited form of debugging of an application that has terminated and
produced a postmortem dump can be done under QNX.  In order to use this
feature, the QNX "dumper" program must be started.

┌──────────────────────────────────────────────────────────────────────────┐
│ dumper [-d path] &                               │
└──────────────────────────────────────────────────────────────────────────┘

dumper       is the program name for the QNX postmortem dump program.

-d path    is an option to specify the directory in which postmortem dumps
       should be written.  If the -d option is not specified, the
       default directory is /usr/dumps.

&       must be specified so that the shell is rejoined.

Example:
  % dumper &
  % dumper -d /usr/fred/dump_area &

Whenever a program terminates abnormally, a dump of the current state of the
program in memory is written to disk.  The dump file name is the same as the
program name.  For example, if the program name is a.out then the dump will
be written to /usr/dumps/a.out (provided that the default dump directory was
selected when the dumper program was started).    If VIDEO was being used to
debug the program at the time that it abnormally terminated then the dump is
written to /usr/dumps/wvideo (provided that the default dump directory was
selected when the dumper program was started).

To examine the contents of the postmortem dump, VIDEO may be used.  The
interface between VIDEO and the postmortem dump is contained in a special
"trap" file.  The trap file is specified to VIDEO using the "TRAP" option.

┌──────────────────────────────────────────────────────────────────────────┐
│ wvideo -TRap=pmd[;i] [:sym_file] file_spec                   │
└──────────────────────────────────────────────────────────────────────────┘

wvideo       is the program name for VIDEO.

-TRap=pmd[ ;i] must be specified when debugging an application that has
       terminated and produced a postmortem dump.  The optional ";i" is
       specified when the modification date of the original program file
       does not match the information contained in the dumper file.  It
       indicates that the symbolic debugging information in the program
       file may be out-of-date.  It instructs VIDEO to ignore the date
       mismatch.

sym_file   is an optional symbolic information file specification.  The
       specification must be preceded by a colon (":").  When specifying
       a symbol file name, a path such as "//5/etc/" may be included.
       For QNX, the default file suffix of the symbol file is ".sym".

file_spec  is the file name of the dumper file to be loaded into memory.
       When specifying a file name, a path such as "//5/etc/" may be
       included.  If a path is omitted, VIDEO will first attempt to
       locate the file in the current directory and, if not successful,
       attempt to locate the file in the default dumper directory:
       /usr/dumps.

Basically, VIDEO is fully functional when a postmortem dump is examined.
However, there are some operations which are not allowed.  Among these are:

  1. Task execution cannot be restarted using the "GO" command.

  2. A register can be modified for the purposes of expression evaluation.
    The "GO" command can be used to restore the register contents to their
    original postmortem state.

  3. Memory cannot be modified.

  4. Memory outside of regions owned by the program cannot be examined.

  5. I/O ports cannot be examined.
::::QNX_INTERRUPTING_A_PROGRAM
Once a program has been loaded by VIDEO, its execution can be started by the
Go command (this command is described under the topic entitled "GO").

Example:
  % wvideo myapp
   .
   .
   .
  DBG>go

As is sometimes the case during the development phase, a program may execute
endlessly.

Under QNX, execution of an application may be interrupted in a number of
ways.

  1. If the application program has not taken over the SIGINT signal then
    execution may be interrupted by pressing Ctrl/Break or Ctrl/C (settable
    by "stty") at the virtual console of the application program.

  2. When debugging locally, execution may be interrupted by pressing
    Ctrl/Break at the virtual console of the debugger.

  3. Any signal that will kill the executing application program (e.g.,
    SIGSEGV, SIGTERM) may be issued at another virtual console.  You must
    obtain the process-id of the application program and then issue a QNX
    "kill" command.

    Example:
      % kill -term 1423

    You should not use the "SIGKILL" signal if you wish to be able to resume
    execution of the application with the debugger.

    An alternative to the "kill" command is the QNX "slay" command which
    requires a process name.

    Example:
      % slay myapp

    By default, the "slay" command issues the "SIGTERM" signal.

VIDEO will print a message in the "Dialogue" window indicating that the
program's execution has been interrupted.  Execution can be resumed with the
Go command.

Also, execution of VIDEO commands may be interrupted by pressing Ctrl/Break
at the virtual console of the debugger.

For information on how to interrupt executing programs when using the remote
debugging facility, see the topic entitled "REMOTE_DEBUGGING".
::::QNX_REMOTE_DEBUGGING
┌──────────────────────────────────────────────────────────────────────────┐
│ wvideo -TRap=trap_file[;trap_parm] [:sym_file] file_spec [cmd_line]       │
└──────────────────────────────────────────────────────────────────────────┘

The VIDEO TRap option must be specified when debugging an application using
a second computer system.  The format of file_spec depends on the target
machine's operating system, be it DOS, OS/2, NetWare 386, or QNX.  You can
use a pair of dashes to stop VIDEO from continuing its option scan.

Example:
  C>wvideo -trap=par -reg=4 -- --fdap--

When trap_parm is specified and it contains blank characters, the entire
parameter must be placed within braces ({}).

You must specify the name of the "trap" file that corresponds to the Debug
Server that was started on the first computer system (the "task machine").
These files handle the machine-to-machine communication required for remote
debugging of an application.  Servers are described under the topics entitled
"REMOTE_DEBUGGING" and "REMOTE_WIN3".

For QNX, the default file suffix of the trap file is ".trp".  Trap files are
usually located in the "/etc/wvideo" directory.

std.trp    Under QNX, if you do not specify a trap file, the default trap
       file "std.trp" will be loaded.  This interface module supports
       debugging on the local computer system running QNX.    No remote
       debugging is possible.

ser.trp    This communications driver file supports debugging of an
       application running on another computer system using the serial
       ports of the two machines.  It communicates with the "SERSERV"
       Debug Server.  The serial port of the debugger machine is usually
       connected to the serial port of the task machine.  However, the
       serial port of another node can be used by the debugger.  The
       "trap_parm" value specifies the port number to use and an
       optional maximum BAUD rate (which is separated from the port
       number by a period).  The port number is 1, 2, 3, etc.  (default
       is 1).  These numbers correspond to the serial port number used
       when specifying a serial device (as in "/dev/ser1", "/dev/ser2",
       etc.).  When the serial port is on another node, the node id and
       port must be specified.

         [nid,][port_number][.max_baud]

       The node number is specified first, then a comma, and then the
       port number.

       Example:
         -tr=ser;7,2.9600

       Under QNX, the maximum BAUD rate can be one of:

          38400
          19200
           9600
           4800
           2400
           1200
          0 (a special case)

       The default maximum BAUD rate is 38,400.

       Except for the special BAUD rate of 0, a minimum of two digits
       must be specified to identify the desired maximum BAUD rate.  The
       maximum BAUD rate is explained in the section "Remote Debugging
       Over the Serial Port" under the topic entitled "REMOTE_DEBUGGING".
       In the following example, port 2 and a maximum BAUD rate of
       19,200 is specified.

       Example:
         -trap=ser;2.19

par.trp    This communications driver file supports debugging of an
       application running on another computer system using the parallel
       ports of the two machines.  It communicates with one of the
       "PARSERV" or "PARSERVW" (Microsoft Windows) Debug Servers.  The
       parallel port of the debugger machine is connected to the
       parallel port of the task machine.  The port number to use is
       specified by "trap_parm".  The port number is 1, 2 or 3 (default
       is 1).  These numbers correspond to the device number used when
       specifying the parallel port (as in "/dev/par1", "/dev/par2",
       etc.).  Unlike the serial port, the parallel port cannot be on
       another node.
::::QNX_SEARCH_ORDER
There are several supporting files provided with VIDEO.  These files fall
into five categories.

  1. VIDEO command files (files with the ".dbg" suffix).

  2. VIDEO trap files (files with the ".trp" suffix).

  3. VIDEO parser files (files with the ".prs" suffix).

  4. VIDEO help files (files with the ".hlp" suffix).

  5. VIDEO symbolic debugging information files (files with the ".sym"
    suffix).

The search order for VIDEO support files is as follows:

  1. the current directory,
  2. the paths listed in the WVIDEO_PATH environment variable,
  3. the path listed in the HOME environment variable, and, finally,
  4. the "/etc/wvideo" directory.

You should note the following when using the remote debugging feature of
VIDEO.    When the REMotefiles option is specified, the debugger also attempts
to locate VIDEO's support files (command files, trap files, etc.) on the
task machine.
::::QNX_STARTUP
┌──────────────────────────────────────────────────────────────────────────┐
│ wvideo [options] [:sym_file] [//nid] pid                   │
│    or                                    │
│ wvideo [options] [:sym_file] [//nid] file_spec [cmd_line]           │
└──────────────────────────────────────────────────────────────────────────┘

The square brackets [ ] denote items which are optional.

wvideo       is the program name for VIDEO.

options    is a list of valid VIDEO options, each preceded by a dash ("-").
       Options may be specified in any order.

sym_file   is an optional symbolic debugging information file specification.
       The specification must be preceded by a colon (":").  When
       specifying a symbol file name, a path such as "//5/etc/" may be
       included.  For QNX, the default file suffix of the symbol file is
       ".sym".

       The symbolic information file can be produced by the WATCOM
       Linker wlink or by the WATCOM Strip Utility wstrip.

nid       is an optional network node identification (nid) on which to
       locate or run the process.  If omitted, the process will be
       located or run on the current node.

pid       is a process identification number of a currently executing
       process.  If a process id is given then VIDEO will attempt to
       attach the specified process.  If a "nid" was also given then
       VIDEO will attempt to attach the specified process on the
       specified node.

file_spec  is the file name of the file to be loaded into memory.  When
       specifying a file name, a path such as "//5/etc/" may be
       included.  If a path is omitted, VIDEO will first attempt to
       locate the file in the current directory.  If this fails, VIDEO
       will search for the file in each path listed in the PATH
       environment string.

cmd_line   is an optional command line which will be passed on to the
       application.

Example 1:
  % wvideo -reg=4 myapp

VIDEO is invoked with 4 register sets and loads the application called
"myapp".

Example 2:
  % wvideo -reg=4 //5 //7/usr/fred/myapp -x test.dat

VIDEO is invoked with 4 register sets and loads the application called
"myapp", located on node 7 of the network, onto node 5 of the network.    The
command line "-x test.dat" is passed to "myapp".

Example 3:
  % wvideo //5 0342

VIDEO is invoked to attach a process identified by pid "0342" running on
node 5.



Command Line Options
════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│     -Console=number                               │
│     -Dynamic=space                               │
│     -NOFpu                                   │
│     -Invoke=file_spec                            │
│     -Lines=number                               │
│     -NOInvoke                                │
│     -NOMouse                                   │
│     -Registers=number                            │
│     -REMotefiles                               │
│     -NOSymbols                               │
│     -TRap=trap_file[;trap_parm]                       │
└──────────────────────────────────────────────────────────────────────────┘

Options may be specified in any order.    Short forms may be specified for
options and are shown above in capital letters.  If "space" is suffixed with
the letter "K" then "space" refers to multiples of 1K bytes (1024 bytes).
If "space" is suffixed with the letter "B" then "space" refers to the number
of bytes.  If no suffix is specified and "space" is a number less than 1000
then "space" is assumed to refer to multiples of 1K bytes (1024 bytes);
otherwise it refers to the number of bytes.

-Console=number specifies the virtual console number to use for debugger
       windows.  By default, VIDEO will use the first "free" virtual
       console.

-Dynamic=space specifies the initial amount of dynamic storage that VIDEO is
       to reserve for items such as windows, user-defined symbols, etc.
       The default amount that is set aside is 40960 bytes (40K bytes).
       As additional storage is required, VIDEO will allocate it.

-NOFpu       requests that the debugger ignore the presence of a math
       coprocessor or emulator.  No memory will be allocated by the
       debugger for saving the context of the 80x87 numeric data
       processor.  Use this option if your application will not use the
       math coprocessor and you wish to reduce the amount of memory
       required by the debugger.

-Invoke=file_spec may be used to specify an alternate name for the debugger
       command file which is to be automatically invoked at start-up
       time.  The default file name is "profile.dbg".  See the topic
       entitled "QNX_SEARCH_ORDER" for information on how command files
       are located.

-Lines=number may be used to specify the number of display lines that VIDEO
       is to use.  If this option is not specified, the default number
       of output lines is selected.  When an Enhanced Graphics Adapter
       (EGA) is present, 43 lines of output may be requested.  When an
       Video Graphics Array (VGA) is present, 50 lines of output may be
       requested.

-NOInvoke  specifies that the default debugger command file is not to be
       invoked.

-NOMouse   requests that the debugger ignore any attached mouse.

-Registers=number may be used to specify how many register sets to set aside
       for the recording of register contents.  The default number of
       register sets is 2.    See the description of the Register command
       for more information (this command is described under the topic
       entitled "REGISTER").

-REMotefiles may be used in conjunction with the remote debugging
       capabilities of the debugger.  Remote debugging involves using
       two personal computers that are connected by means other than the
       network.  One, called the "task machine", is used to run the
       application; the other, called the "debugger machine", is used to
       run the debugger.  When REMotefiles is specified, all debugger
       files (except "trap" files) and application source files are
       opened on the task machine rather than the debugger machine (if
       you are doing local debugging, these two machines are actually
       the same).  The "trap" file must be located on the debugger
       machine because it contains the code to open files on the task
       machine.

       Note that the PATH environment variable on the task machine is
       always used in locating executable image files.  When REMotefiles
       is specified, the debugger also attempts to locate VIDEO's
       support files (command files, trap files, etc.) on the task
       machine.

-NOSymbols requests that VIDEO omit all debugging information when loading
       an executable image.  Information regarding global and local
       symbol names, data types, and line numbers is not processed.

-TRap=trap_file[;trap_parm] must be specified when debugging an application
       on a remote machine.  You must specify the name of one of the
       "trap" files provided with VIDEO.  For QNX, the default file
       suffix of the trap file is ".trp".  Trap files are usually
       located in the "/etc/wvideo" directory.  See the topic entitled
       "QNX_SEARCH_ORDER" for information on how trap files are located.

       Under QNX, if you do not specify the TRap option, the default
       trap file "std.trp" will be loaded.    This interface module
       supports debugging on the local computer system running QNX.

       Example:
         % wvideo calendar

       Of course, you may also explicitly name the "standard" trap file
       that you wish VIDEO to use.

       Example:
         % wvideo -trap=std calendar

       If trap_parm is specified, it may be necessary to escape the ";"
       depending on the command shell in use.

       See the topic entitled "REMOTE_DEBUGGING" for more information
       on the TRap option.
::::QNX_WVIDEO_ENVIRONMENT_VARIABLE
The WVIDEO environment variable can be used to specify commonly used VIDEO
options.  These options are processed before options specified on the
command line.

Example:
  % export "WVIDEO=-nofpu -reg=4"

The above examples illustrate how to define default options for the
debugger.  Under QNX, care must be taken to specify the environment variable
name entirely in uppercase letters.

Once the WVIDEO environment variable has been defined, those options listed
become the default each time VIDEO is invoked.
::::QUIT
┌──────────────────────────────────────────────────────────────────────────┐
│ QUIT                                       │
└──────────────────────────────────────────────────────────────────────────┘

The QUIT command is used to terminate VIDEO and return to the operating
system.  Any application which may have partially executed is also
terminated.
::::REGISTER
┌──────────────────────────────────────────────────────────────────────────┐
│ Register [expr]                               │
└──────────────────────────────────────────────────────────────────────────┘

The Register command is used to select a VIDEO register set.

Whenever VIDEO is entered, it saves the current register values in a ring of
register sets.    The size of this ring is determined at start-up time with
the Registers option (the default is 2, the maximum is 100).  When the
expression result is negative, a previous register set is selected.  When
the expression result is positive, a more recent register set is selected.
When the expression is omitted, the current register set is selected.

If the Register window is not present on the screen, the register display is
written to the Dialogue window.  A Register window is created by using the
Display Register command.  If you are not at the most recent register set, a
number will appear in square brackets somewhere in the Register window.
This number represents the number of register sets that are more recent than
the one that is currently being displayed.  When you issue a Go or Trace
command, the currently displayed register set becomes the "current" register
values.  This feature provides the user with a "checkpoint/restart"
capability.

Example:
  DBG>register -1

In the above example, we back up to the previous register set.
::::REMARK
┌──────────────────────────────────────────────────────────────────────────┐
│ REMark   comment_line                            │
│ *                                       │
└──────────────────────────────────────────────────────────────────────────┘

The REMark or * command provides a means for documenting VIDEO command
files.

Example:
  * Count the number of times a routine is executed
    /cnt_<1>=0
  * Remove the break point definition
  * just in case one already exists
    break/clear /<1>
  * Set the new break point
    break/set <1> {/cnt_<1>++; go/keep}
::::REMOTE_DEBUGGING
Remote Debugging
════════════════

Remote debugging involves using two computer systems to debug your
application.  One PC, called the "task machine", is used to run the
application; the other PC, called the "debugger machine", is used to run the
debugger.  Remote debugging can be used when there is not enough memory on
one computer system to run both the application and the debugger.

When using the remote debugging feature, the application that is to be
debugged must reside on the task machine so that the operating system can
load it.  The application's source files should be accessible from the
debugger machine so that VIDEO can display source lines for a particular
module.


Let us assume that PC #1 is your primary development machine.  It contains
your application, its data files, its source files, and the programs that
you have been using to develop your application (editor, compiler, linker,
debugger, etc.).  Let us assume that PC #2 is a spare machine that is
available for your use.  Since two computer systems are involved, there are
two possible scenarios.

  1. You could copy the application and any required data files to PC #2.
    In this scenario, your primary development machine (PC #1) will be used
    to run the debugger.  Thus, the source files for your application are
    present on the debugger machine.

  2. You could copy the debugger over to PC #2.  In this scenario, your
    primary development machine (PC #1) will be used to run the application.
    Unless you copy all of the application's source files to PC #2, the
    debugger will not have access to them.  In this case, you can use the
    VIDEO "REMotefiles" option to inform the debugger that source files are
    to be obtained over the communications link from the task machine (PC
    #1).  Another advantage to the "REMotefiles" option is that the debugger
    will also locate debugger command files, by default, on the task
    machine.  If this option is not specified then the debugger command
    files must also be copied over to the debugger machine (PC #2).

The decision as to which machine you should be using for the task and which
for the debugger is up to you.    In certain cases, it may depend on the
amount of available memory on each machine or the speed of their respective
processors.  If a large amount of memory is required for your application
then it makes sense that the task machine be the one with the most memory.
If application execution speed is important then it makes sense that the
task machine be the faster of the two.

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  Under QNX, it is possible to debug a task running on another QNX    │
│ node.  This is an inherent feature of the QNX system and should not be     │
│ considered "remote" debugging.  Remote debugging is most effectively used  │
│ when the computers are on two separate QNX networks, or one computer is    │
│ running QNX and the other is running one of the other operating systems    │
│ supported by VIDEO.                                 │
│                                         │
│ See the topic entitled "QNX_STARTUP".                      │
└────────────────────────────────────────────────────────────────────────────┘

Notes:

  1. Version 2.0 or later of DOS is required to support remote debugging of
    applications.

  2. Version 3.0 or later of Microsoft Windows is required to support remote
    debugging of applications.

  3. Version 1.2 or later of OS/2 is required to support remote debugging of
    applications.

  4. Version 3.1 or later of NetWare 386 is required to support debugging of
    applications running on the NetWare server.  The remote debugging
    facility requires that a server task be run on the task machine (the
    NetWare server) before VIDEO is started on the debugger machine.

  5. Version 4.0 or later of QNX is required to support remote debugging of
    applications.



Communications Servers Under DOS and OS/2
═════════════════════════════════════════
There are several servers provided for use with VIDEO under DOS and OS/2.

SERSERV.EXE
       This program supports remote debugging over the serial port.

PARSERV.EXE
       This program supports remote debugging over the parallel port.

NOVSERV.EXE
       This program supports remote debugging over the Novell "NetWare"
       network.

NETSERV.EXE
       This program supports remote debugging using NetBIOS support.

DQVSERV.EXE
       (DOS Only) This program supports remote debugging using DESQview.
       In the following discussion, the "task machine" is the DESQview
       window in which the server is started and the "debugger machine"
       is the DESQview window in which the debugger is started.

WINSERV.EXE
       (Microsoft Windows 3.x Only) This program supports remote
       debugging using Windows DOS boxes.  In the following discussion,
       the "task machine" is the Windows DOS box in which the server is
       started and the "debugger machine" is the Windows DOS box in
       which the debugger is started.

These programs are described in subsequent sections.  The general syntax of
the command line is shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ server_name [/TRap=trap_file[;trap_parm]] server_specs           │
└──────────────────────────────────────────────────────────────────────────┘

The /TRap option is only specified in three situations:

  1. under DOS, in order to prevent the server task from using the 386/486
    Debug Registers (a hardware feature used to assist debugging),

  2. for 386 applications that require the services of a DOS extender, and

  3. in special applications where more than two computer systems are
    chained together in series.


In general, the server program receives requests from another computer
system (the debugger machine).    It can process these requests locally or
pass them on to a server running on another computer system.

STD.TRP, STD16.DLL, STD32.DLL
       By default, requests will be handled locally by the "STD.TRP"
       file when DOS is running, the "STD16.DLL" file when OS/2 1.x is
       running, or the "STD32.DLL" file when OS/2 2.x is running,

       Under DOS, it may be necessary to prevent the server task from
       using the 386/486 Debug Registers (a hardware feature used to
       assist debugging).  This situation arises with certain DOS
       control programs that do not properly manage Debug Registers.  If
       the server task fails upon startup on a 386/486 system, it is a
       good indication that use of the Debug Registers must be disabled.
       With "STD.TRP", the trap file parameter "d" may be specified to
       disable the use of Debug Registers.    The following example
       illustrates the specification of the "d" trap file parameter.

       Example:
         C>serserv /trap=std;d
         or
         C>parserv /trap=std;d
         etc.

ECS.TRP    When the application is to be run with the ERGO Computing, Inc.
       "OS/386" DOS extender on the task machine, the "ECS.TRP"
       interface module can be used with a communications server.  The
       optional "trap_parm" is ignored.

       Example:
         C>serserv /trap=ecs
         or
         C>parserv /trap=ecs
         etc.

PLS.TRP    When the application is to be run with the Phar Lap Software,
       Inc.  386|DOS-Extender on the task machine, the "PLS.TRP"
       interface module can be used with a communications server.  The
       optional "trap_parm" is passed on to the DOS extender "RUN386" as
       command line switches.

       Example:
         C>serserv /trap=pls
         or
         C>parserv /trap=pls
         etc.

RSI.TRP    When the application is to be run with the Rational Systems, Inc.
       "DOS/4GW" DOS extender on the task machine, the "RSI.TRP"
       interface module can be used with a communications server.  This
       DOS extender is included in the WATCOM C/386 and WATCOM FORTRAN
       77/386 packages.  The optional "trap_parm" is ignored.

       Example:
         C>serserv /trap=rsi
         or
         C>parserv /trap=rsi
         etc.



Communications Servers Under Microsoft Windows
══════════════════════════════════════════════
There are two servers provided for use with VIDEO under Windows 3.x.

PARSERVW.EXE
       This program supports remote debugging over the parallel port.

NETSERVW.EXE
       This program supports remote debugging using NetBIOS support.

These programs are described in subsequent sections.  The general syntax of
the command line is shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ server_name server_specs                           │
└──────────────────────────────────────────────────────────────────────────┘



Communications Servers Under Novell NetWare 386
═══════════════════════════════════════════════
There are three servers provided for use with VIDEO under Novell NetWare
386.

SERSERV.NLM
       This program supports remote debugging over the serial port.

PARSERV.NLM
       This program supports remote debugging over the parallel port.

NOVSERV.NLM
       This program supports remote debugging over the Novell "NetWare"
       network.

These programs are described in the following sections.  The general syntax
of the command line is shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ LOAD server_name server_specs                        │
└──────────────────────────────────────────────────────────────────────────┘

Example:
  : LOAD PARSERV 2

The above example loads the parallel port server which will use parallel
port 2 of the NetWare server for communication.



Communications Servers Under QNX
════════════════════════════════
There are two servers provided for use with VIDEO under QNX.

serserv    This program supports remote debugging over the serial port.

parserv    This program supports remote debugging over the parallel port.

These programs are described in the following sections.  The general syntax
of the command line is shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ server_name [-TRap=trap_file[;trap_parm]] server_specs           │
└──────────────────────────────────────────────────────────────────────────┘

The -TRap option can be specified.  In general, the server program receives
requests from another computer system (the debugger machine).  It can
process these requests locally or pass them on to a server running on
another computer system.  By default, requests will be handled locally by
the "std.trp" file.



Examples of PC to PC Communication Links
════════════════════════════════════════
In the following diagram, we illustrate the use of VIDEO running under DOS
to debug an application running under DOS on another computer system.  In
the example, parallel communications are used.

    PC #1              PC #2
  ┌────────────────┐        ┌────────────────┐
  │Debugger Machine│        │  Task Machine  │
  │     DOS       │        │       DOS         │
  │           │        │             │
  │    WVIDEO       │    ┌───│────>PARSERV    │
  │      │       │    │   │        │         │
  │      V       │    │   │        V         │
  │ trap handler<──│────┘   │  trap handler  │
  │    PAR.TRP       │        │     STD.TRP     │
  └────────────────┘        └────────────────┘


Figure 21. Remote Debugging from DOS to DOS

In the following diagram, we illustrate the use of VIDEO running under DOS
to debug an application running under OS/2 on another computer system.    In
the example, serial communications are used.

    PC #1              PC #2
  ┌────────────────┐        ┌────────────────┐
  │Debugger Machine│        │  Task Machine  │
  │     DOS       │        │     OS/2 1.x    │
  │           │        │             │
  │    WVIDEO       │    ┌───│────>SERSERV    │
  │      │       │    │   │        │         │
  │      V       │    │   │        V         │
  │ trap handler<──│────┘   │  trap handler  │
  │    SER.TRP       │        │     STD16.DLL   │
  └────────────────┘        └────────────────┘

Figure 22. Remote Debugging from DOS to OS/2

In the following diagram, we illustrate the use of VIDEO running under OS/2
to debug an application running under a DOS extender on another computer
system.  In the example, serial communications are used.

    PC #1              PC #2
  ┌────────────────┐        ┌────────────────┐
  │Debugger Machine│        │  Task Machine  │
  │     OS/2       │        │386│DOS─Extender│
  │           │        │             │
  │    WVIDEO       │    ┌───│────>SERSERV    │
  │      │       │    │   │        │         │
  │      V       │    │   │        V         │
  │ trap handler<──│────┘   │  trap handler  │
  │    SER.DLL       │        │     PLS.TRP     │
  └────────────────┘        └────────────────┘

Figure 23. Remote Debugging from OS/2 to DOS Extender

In the following diagram, we illustrate the use of VIDEO running under QNX
to debug an application running under QNX on another computer system.  In
the example, parallel communications are used.

    PC #1              PC #2
  ┌────────────────┐        ┌────────────────┐
  │Debugger Machine│        │  Task Machine  │
  │     QNX       │        │       QNX         │
  │           │        │             │
  │    wvideo       │    ┌───│────>parserv    │
  │      │       │    │   │        │         │
  │      V       │    │   │        V         │
  │ trap handler<──│────┘   │  trap handler  │
  │    par.trp       │        │     std.trp     │
  └────────────────┘        └────────────────┘

Figure 24. Remote Debugging from QNX to QNX

In the following diagram, we illustrate the use of VIDEO running under DOS
to debug an application running under QNX on another computer system.  In
the example, serial communications are used.

    PC #1              PC #2
  ┌────────────────┐        ┌────────────────┐
  │Debugger Machine│        │  Task Machine  │
  │     DOS       │        │       QNX         │
  │           │        │             │
  │    WVIDEO       │    ┌───│────>serserv    │
  │      │       │    │   │        │         │
  │      V       │    │   │        V         │
  │ trap handler<──│────┘   │  trap handler  │
  │    SER.TRP       │        │     std.trp     │
  └────────────────┘        └────────────────┘

Figure 25. Remote Debugging from DOS to QNX

In the following diagram, we illustrate the use of VIDEO running under QNX
to debug an application running under a DOS extender on another computer
system.  In the example, serial communications are used.


    PC #1              PC #2
  ┌────────────────┐        ┌────────────────┐
  │Debugger Machine│        │  Task Machine  │
  │     QNX       │        │386│DOS─Extender│
  │           │        │             │
  │    wvideo       │    ┌───│────>SERSERV    │
  │      │       │    │   │        │         │
  │      V       │    │   │        V         │
  │ trap handler<──│────┘   │  trap handler  │
  │    ser.trp       │        │     PLS.TRP     │
  └────────────────┘        └────────────────┘

Figure 26. Remote Debugging from QNX to DOS Extender

Many other combinations are possible.  In the following diagram, we
illustrate the use of VIDEO running under DOS to debug an application
running under DOS on a third computer system which is connected indirectly
to the first system.  In the example, parallel communications are used to
get from PC #1 to PC #2 and NetWare network communications are used to get
from PC #2 to PC #3.

    PC #1              PC #2             PC #3
  ┌────────────────┐        ┌────────────────┐          ┌────────────────┐
  │Debugger Machine│        │    Go─Between   │          │  Task Machine  │
  │     DOS       │        │       DOS         │          │      DOS       │
  │           │        │             │          │            │
  │    WVIDEO       │    ┌───│────>PARSERV    │      ┌───│────>NOVSERV    │
  │      │       │    │   │        │         │      │   │       │        │
  │      V       │    │   │        V         │      │   │       V        │
  │ trap handler<──│────┘   │ trap handler<──│────┘   │  trap handler  │
  │    PAR.TRP       │        │     NOV.TRP     │          │    STD.TRP     │
  └────────────────┘        └────────────────┘          └────────────────┘

Figure 27. Remote Debugging via an Intermediate

Notes:

  1. You should note the following regarding keyboard input.  Anything that
    is typed to the debugger itself must be typed on the debugger machine.
    As well, anything that is typed to the application being debugged must
    be typed on the task machine.

  2. The same is true of screen output.  All debugger output comes out on
    the debugger machine, while all program output occurs on the task
    machine.

The wiring required for serial and parallel communications is described under
the topic entitled "WIRING".



Remote Debugging Over the Serial Port
═════════════════════════════════════
Remote debugging over the serial port requires that a server task be run on
the task machine before VIDEO is started on the debugger machine.  This is
required since VIDEO will begin to communicate immediately with the task
machine via this special server program.

The wiring required for serial communications is described under the topic
entitled "WIRING" in the section entitled "Serial Port Wiring Considerations".

The debugger and server will automatically synchronize on a communications
speed.    They may communicate at rates as high as 115,200 BAUD.    Since the
BAUD rate, parity, number of data bits and stop bits is automatically
chosen, the DOS or OS/2 "MODE" command or the QNX "stty" command need not be
used.

For DOS and OS/2, the formal serial port debug server command line syntax is
shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ SERSERV [/TRap=trap_file[;trap_parm]] [port_number][.max_baud]       │
└──────────────────────────────────────────────────────────────────────────┘

For NetWare 386, the formal serial port debug server command line syntax is
shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ LOAD SERSERV [port_number][.max_baud]                    │
└──────────────────────────────────────────────────────────────────────────┘

For QNX, the formal serial port debug server command line syntax is shown
below.

┌──────────────────────────────────────────────────────────────────────────┐
│ serserv [-TRap=trap_file[;trap_parm]] [nid,][port_number][.max_baud]       │
└──────────────────────────────────────────────────────────────────────────┘

The "port_number" for the serial server is the serial port number (1, 2, 3,
etc.) that the server should use to communicate with VIDEO running on the
debugger machine.  The default port number is 1.

Under DOS, OS/2 and NetWare 386, these numbers correspond to the device
number used when specifying the serial device "COMx" (as in "COM1", "COM2",
etc.).

Under QNX, these numbers correspond to the serial port number used when
specifying a serial device (as in "/dev/ser1", "/dev/ser2", etc.).  When the
serial port is on another node, the node id must be specified.    If a node id
is specified and the port number is not specified, it defaults to 1.

  [nid,][port_number][.max_baud]

The node number is specified first, then a comma, and then the port number.

Example:
  serserv 7,2.9600

The optional "max_baud" value specifies the maximum BAUD rate.    It is
separated from the port number by a period.

Under DOS, the maximum BAUD rate can be one of:

  115200
   57600
   38400
   19200
    9600
    4800
    2400
    1200
       0 (a special case)

The default maximum BAUD rate is 115,200.

Under OS/2, the maximum BAUD rate can be one of:

   19200
    9600
    4800
    2400
    1200
       0 (a special case)

The default maximum BAUD rate is 19,200.

Under QNX, the maximum BAUD rate can be one of:

   38400
   19200
    9600
    4800
    2400
    1200
       0 (a special case)

The default maximum BAUD rate is 38,400.

Except for the special BAUD rate of 0, a minimum of two digits must be
specified to identify the desired maximum BAUD rate.  Specification of a
maximum BAUD rate is useful when the maximum rate at which the two machines
can communicate effectively is known.  The server and debugger normally
start at the fastest possible speed and work downwards until an effective
(error-free) rate is established.  If the maximum rate is specified ahead of
time, this will help reduce the startup time.  The BAUD rate actually
selected will be the minimum of the maximum rates specified when both the
server and debugger are started and the rate at which the two can
effectively communicate.  An example may help to explain this.

Example:
  Task    machine: serserv 2.38400
  Debug machine: wvideo -trap=ser;1.57600 hello

In the above example, the maximum rate at which the two machines could
communicate is 38,400 BAUD (since it is the minimum of 38,400 and 57,600).
However, the actual rate selected for effective communications may be less
than this.

If 0 is specified for the maximum BAUD rate when both the server and
debugger are started, the process of searching for the maximum rate at which
the two machines can communicate is eliminated.  The BAUD rate for each side
must be established through other means (such as the DOS or OS/2 "MODE"
command or the QNX "stty" command) and the rates must be identical.  The
parity, word length and number of stop bits are selected by the server and
the debugger so you need not specify these parameters.    The BAUD rate value
0 should be specified when modems are employed between the two machines
(yes, you can debug applications over the phone).  The following example
sets the BAUD rate to 2400 using the DOS or OS/2 "MODE" command.  For QNX,
use the appropriate "stty" command.

Example:
  Task    machine: mode com2:2400
  Task    machine: serserv 2.0
  Debug machine: mode com1:2400
  Debug machine: wvideo -trap=ser;1.0 hello

In the above example, the rate at which the two machines can communicate is
2400 BAUD (since it is the specified externally using the DOS or OS/2 "MODE"
command).

When debugging over the serial port, the following files are required on the
task machine:

  1. one of the following serial servers:

    DOS, OS/2  SERSERV.EXE
    NetWare    SERSERV.NLM
    QNX        serserv

  2. one of the following sets of files:

    DOS        STD.TRP
    OS/2 1.x   STD16.DLL
    OS/2 2.x   STD32.DLL and OS2V2HLP.EXE
    QNX        std.trp
    ERGO       ECS.TRP and OS386.EXE
    Phar Lap   PLS.TRP, PLSHELP.EXP, DBGLIB.REX and RUN386.EXE
    Rational Systems RSI.TRP, RSIHELP.EXP and DOS4G[W].EXE

  3. the executable file to be debugged, and

  4. any data files required by the executable.

The following files are required on the debugger machine:

  1. the WATCOM debugger

    DOS, OS/2  WVIDEO.EXE
    QNX        wvideo

  2. one of the following trap files:

    DOS        SER.TRP
    OS/2       SER.DLL
    QNX        ser.trp

The following is a sequence of commands that one might issue to debug an
application remotely over the serial port:

  Task    machine: serserv 2
  Debug machine: wvideo -trap=ser;1 bug
  Debug machine: VIDEO commands such as "go".
  Task    machine: Type any keyboard input that is required
  Debug machine: quit
  Task    machine: q

In the example, serial port 2 is used on the task machine and serial port 1
is used on the debugger machine.  An appropriately-wired cable must run
between serial port 2 of the task machine and serial port 1 of the debugger
machine.  Messages will appear on both the task and debugger machines
indicating the BAUD rate at which the two machines are communicating.

The final "q" typed on the keyboard of the task machine is used to terminate
the server.  If this is not done, the server returns to its start-up state
and you could rerun VIDEO again for further debugging.



Remote Debugging Over the Parallel Port
═══════════════════════════════════════
Debugging over the parallel port is significantly faster than the serial
port.  Remote debugging over the parallel port requires that a server task
be run on the task machine before VIDEO is started on the debugger machine.
This is required since VIDEO will begin to communicate immediately with the
task machine via this special server program.

The wiring required for parallel communications is described under the topic
entitled "WIRING" in the section entitled "Parallel Port Wiring
Considerations".

For DOS and OS/2, the formal parallel port debug server command line syntax
is shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ PARSERV [/TRap=trap_file[;trap_parm]] [port_number]               │
└──────────────────────────────────────────────────────────────────────────┘

For Microsoft Windows, the formal parallel port debug server command line
syntax is shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ PARSERVW [port_number]                           │
└──────────────────────────────────────────────────────────────────────────┘

For NetWare 386, the formal parallel port debug server command line syntax
is shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ LOAD PARSERV [port_number]                           │
└──────────────────────────────────────────────────────────────────────────┘

For QNX, the formal parallel port debug server command line syntax is shown
below.

┌──────────────────────────────────────────────────────────────────────────┐
│ parserv [-TRap=trap_file[;trap_parm]] [port_number]               │
└──────────────────────────────────────────────────────────────────────────┘

The "port_number" for the parallel server is the parallel port number
(between 1 and 3) that the server should use to communicate with VIDEO
running on the debugger machine.  The default port number is 1.

Under DOS, MS Windows, OS/2 and NetWare 386, these numbers correspond to the
device number used when specifying the parallel printer device "LPTx" (as in
"LPT1", "LPT2", etc.).

Under QNX, these numbers correspond to the parallel port number used when
specifying the parallel port (as in "/dev/par1", "/dev/par2", etc.).

When debugging over the parallel port, the following files are required on
the task machine:

  1. one of the following parallel servers:

    DOS, OS/2  PARSERV.EXE
    MS Windows PARSERVW.EXE
    NetWare    PARSERV.NLM
    QNX        parserv

  2. one of the following sets of files:

    DOS        STD.TRP
    MS Windows STD.DLL and WINDEBUG.DLL
    OS/2 1.x   STD16.DLL
    OS/2 2.x   STD32.DLL and OS2V2HLP.EXE
    QNX        std.trp
    ERGO       ECS.TRP and OS386.EXE
    Phar Lap   PLS.TRP, PLSHELP.EXP, DBGLIB.REX and RUN386.EXE
    Rational Systems RSI.TRP, RSIHELP.EXP and DOS4G[W].EXE

  3. the executable file to be debugged, and

  4. any data files required by the executable.

The following files are required on the debugger machine:

  1. the WATCOM debugger

    DOS, OS/2  WVIDEO.EXE
    QNX        wvideo

  2. one of the following trap files:

    DOS        PAR.TRP
    OS/2       PAR.DLL
    QNX        par.trp

The following is a sequence of commands that one might issue to debug an
application remotely over the parallel port:

  Task    machine: parserv 1
  Debug machine: wvideo -trap=par;2 bug
  Debug machine: VIDEO commands such as "go".
  Task    machine: Type any keyboard input that is required
  Debug machine: quit
  Task    machine: q

In the example, parallel port 1 is used on the task machine and parallel
port 2 is used on the debugger machine.  An appropriately-wired cable must
run between parallel port 1 of the task machine and parallel port 2 of the
debugger machine.

The final "q" typed on the keyboard of the task machine is used to terminate
the server.  If this is not done, the server returns to its start-up state
and you could rerun VIDEO again for further debugging.



Remote Debugging Over the Novell "NetWare" Network (DOS, OS/2 Only)
═══════════════════════════════════════════════════════════════════
Remote debugging over the Novell "NetWare" network requires the NetWare
shell.    The Sequenced Packet Exchange (SPX) must be loaded first and the
server task must be run on the task machine before VIDEO is started on the
debugger machine.  This is required since VIDEO will begin to communicate
immediately with the task machine via this special server program.

For DOS and OS/2, the formal NetWare debug server command line syntax is
shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ NOVSERV [/TRap=trap_file[;trap_parm]] [server_name]               │
└──────────────────────────────────────────────────────────────────────────┘

For NetWare 386, the formal NetWare debug server command line syntax is
shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ LOAD NOVSERV [server_name]                           │
└──────────────────────────────────────────────────────────────────────────┘

The "server_name" is case insensitive and it must be unique (you will be
notified if it is not unique).    The name is restricted to less than 48
characters.  It cannot contain the following special characters:

  / \ : ; . , * ? + -

Any invalid characters are removed and any excess characters are dropped
from the name.    The "server_name" uniquely identifies the server to VIDEO
running on the debugger machine.  The default "server_name" is "NovLink".


When debugging over the "NetWare" network, the following files are required
on the task machine:

  1. one of the following NetWare servers:

    DOS, OS/2  NOVSERV.EXE
    NetWare    NOVSERV.NLM

  2. one of the following sets of files:

    DOS        STD.TRP
    OS/2 1.x   STD16.DLL
    OS/2 2.x   STD32.DLL and OS2V2HLP.EXE
    ERGO       ECS.TRP and OS386.EXE
    Phar Lap   PLS.TRP, PLSHELP.EXP, DBGLIB.REX and RUN386.EXE
    Rational Systems RSI.TRP, RSIHELP.EXP and DOS4G[W].EXE

  3. the executable file to be debugged, and

  4. any data files required by the executable.

The following files are required on the debugger machine:

  1. the WATCOM debugger

    DOS, OS/2  WVIDEO.EXE

  2. one of the following trap files:

    DOS        NOV.TRP
    OS/2       NOV.DLL

The following is a sequence of commands that one might issue to debug an
application remotely over the "NetWare" network:

  Task    machine: novserv rmt_dbg
  Debug machine: wvideo -trap=nov;rmt_dbg bug
  Debug machine: VIDEO commands such as "go".
  Task    machine: Type any keyboard input that is required
  Debug machine: quit
  Task    machine: q

In the example, server name "RMT_DBG" is used on the task machine so server
name "RMT_DBG" is also used on the debugger machine.

The final "q" typed on the keyboard of the task machine is used to terminate
the server.  If this is not done, the server returns to its start-up state
and you could rerun VIDEO again for further debugging.



Remote Debugging Using NetBIOS Support (DOS, OS/2 Only)
═══════════════════════════════════════════════════════
Debugging with the NetBIOS network programming interface can also be done.
Remote debugging with this network protocol requires that a server task be
run on the task machine before VIDEO is started on the debugger machine.
This is required since VIDEO will begin to communicate immediately with the
task machine via this special server program.

For DOS and OS/2, the formal NetBIOS debug server command line syntax is
shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ NETSERV [/TRap=trap_file[;trap_parm]] [server_name]               │
└──────────────────────────────────────────────────────────────────────────┘

For Microsoft Windows, the formal NetBIOS debug server command line syntax
is shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ NETSERVW [server_name]                           │
└──────────────────────────────────────────────────────────────────────────┘

The "server_name" is case sensitive and it must be unique (you will be
notified if it is not unique).    The name may be up to 15 alphanumeric
characters.  The "server_name" uniquely identifies the server to VIDEO
running on the debugger machine.  The default "server_name" is "NetLink".


When debugging with the NetBIOS network programming interface, the following
files are required on the task machine:

  1. the NetBIOS server:

    DOS, OS/2  NETSERV.EXE
    MS Windows NETSERVW.EXE

  2. one of the following sets of files:

    DOS        STD.TRP
    MS Windows STD.DLL
    OS/2 1.x   STD16.DLL
    OS/2 2.x   STD32.DLL and OS2V2HLP.EXE
    ERGO       ECS.TRP and OS386.EXE
    Phar Lap   PLS.TRP, PLSHELP.EXP, DBGLIB.REX and RUN386.EXE
    Rational Systems RSI.TRP, RSIHELP.EXP and DOS4G[W].EXE

  3. the executable file to be debugged, and

  4. any data files required by the executable.

The following files are required on the debugger machine:

  1. the WATCOM debugger

    DOS, OS/2  WVIDEO.EXE

  2. one of the following trap files:

    DOS        NET.TRP
    OS/2       NET.DLL

The following is a sequence of commands that one might issue to debug an
application remotely with the NetBIOS network programming interface:

  Task    machine: netserv rmt_dbg
  Debug machine: wvideo -trap=net;rmt_dbg bug
  Debug machine: VIDEO commands such as "go".
  Task    machine: Type any keyboard input that is required
  Debug machine: quit
  Task    machine: q

In the example, server name "rmt_dbg" is used on the task machine so server
name "rmt_dbg" is also used on the debugger machine.

The final "q" typed on the keyboard of the task machine is used to terminate
the server.  If this is not done, the server returns to its start-up state
and you could rerun VIDEO again for further debugging.



Remote Debugging Using DESQview (DOS Only)
══════════════════════════════════════════
Debugging with DESQview windows can also be done.  Remote debugging with
DESQview requires that a server task be run in a window (the "task" window)
before VIDEO is started in another window (the "debugger" window).  This is
required since VIDEO will begin to communicate immediately with the task
window via this special server program.

For DOS, the formal DESQview debug server command line syntax is shown
below.

┌──────────────────────────────────────────────────────────────────────────┐
│ DQVSERV [/TRap=trap_file[;trap_parm]] [server_name]               │
└──────────────────────────────────────────────────────────────────────────┘

The "server_name" is case insensitive and it must be unique (you will be
notified if it is not unique).    The name may be any string of alphanumeric
characters.  The "server_name" uniquely identifies the server to VIDEO
running in the debugger window.  The default "server_name" is "WATCOM
Server".

When debugging with DESQview windows, the following files are required for
the task window:

  1. the DESQview server, DQVSERV.EXE,

  2. one of the following sets of files:

    DOS        STD.TRP
    ERGO       ECS.TRP and OS386.EXE
    Phar Lap   PLS.TRP, PLSHELP.EXP, DBGLIB.REX and RUN386.EXE
    Rational Systems RSI.TRP, RSIHELP.EXP and DOS4G[W].EXE

  3. the executable file to be debugged, and

  4. any data files required by the executable.

The following files are required for the debugger window:

  1. the WATCOM debugger, WVIDEO.EXE, and

  2. the trap file, DQV.TRP.

The following is a sequence of commands that one might issue to debug an
application with DESQview windows:

  Task    window: dqvserv rmt_dbg
  Debug window: wvideo -trap=dqv;rmt_dbg bug
  Debug window: VIDEO commands such as "go".
  Task    window: Type any keyboard input that is required
  Debug window: quit
  Task    window: q

In the example, server name "rmt_dbg" is used in the task window so server
name "rmt_dbg" is also used in the debugger window.

The final "q" typed on the keyboard when the task window is active
terminates the server.    If this is not done, the server returns to its
start-up state and you could rerun VIDEO again for further debugging.



Remote Debugging Using Microsoft Windows DOS Boxes
══════════════════════════════════════════════════
Debugging with a Microsoft Windows DOS box can also be done.  Remote
debugging with Windows requires that a server task be run in a DOS box (the
"task" window) before VIDEO is started in another DOS box (the "debugger"
window).  This is required since VIDEO will begin to communicate immediately
with the task window via this special server program.

Microsoft Windows must be started in standard or enhanced mode.  You must
include the "device" specification listed below in the [386Enh] section of
your Windows "SYSTEM.INI" file.

  DEVICE=[d:]\WATCOM\BINW\WDEBUG.386

This device driver supports debugging of both 16-bit and 32-bit
applications.

The formal Microsoft Windows DOS box debug server command line syntax is
shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ WINSERV [/TRap=trap_file[;trap_parm]] [server_name]               │
└──────────────────────────────────────────────────────────────────────────┘

The "server_name" is case insensitive and it must be unique (you will be
notified if it is not unique).    The name may be any string of alphanumeric
characters.  The "server_name" uniquely identifies the server to VIDEO
running in the debugger window.  The default "server_name" is "WinLink".

When debugging with Windows DOS boxes, the following files are required for
the task window:

  1. the Windows server, WINSERV.EXE,

  2. one of the following sets of files:

    DOS        STD.TRP
    ERGO       ECS.TRP and OS386.EXE
    Phar Lap   PLS.TRP, PLSHELP.EXP, DBGLIB.REX and RUN386.EXE
    Rational Systems RSI.TRP, RSIHELP.EXP and DOS4G[W].EXE

  3. the executable file to be debugged, and

  4. any data files required by the executable.


The following files are required for the debugger window:

  1. the WATCOM debugger, WVIDEO.EXE, and

  2. the trap file, WIN.TRP.

The following is a sequence of commands that one might issue to debug an
application with Windows DOS boxes:

  Task    window: winserv rmt_dbg
  Debug window: wvideo -trap=win;rmt_dbg bug
  Debug window: VIDEO commands such as "go".
  Task    window: Type any keyboard input that is required
  Debug window: quit
  Task    window: q

In the example, server name "rmt_dbg" is used in the task window so server
name "rmt_dbg" is also used in the debugger window.

The final "q" typed on the keyboard when the task window is active
terminates the server.    If this is not done, the server returns to its
start-up state and you could rerun VIDEO again for further debugging.



Specifying Files on Task and Debugger Machines
══════════════════════════════════════════════
When debugging an application with the remote debugging facility, a method
for identifying files on either of the task and debugger machines is
required.  In order to identify files on either the task or debugger
machine, two special prefixes are supported by the debugger:  "@L" and "@R".

The "@L" or "@l" prefix is used to indicate that the file resides on the
local debugger machine.

DOS, OS/2, NetWare
       @L[d:][path]filename[.ext]

       When "[path]" is not specified, the current directory of the
       specified drive of the local machine is assumed.  When "[d:]" is
       not specified, the current drive of the local machine is assumed.

       Example:
         view @loutput.log
         invoke @l\cmds\setup.dbg
         invoke @ld:\cmds\setup.dbg
         log @llpt2

QNX       @L[path]filename

       When "[path]" is not specified, the current working directory of
       the local machine is assumed.

       Example:
         view @loutput.log
         invoke @l/usr/fred/setup.dbg
         invoke @//7/usr/fred/setup.dbg
         log @l/dev/par2

The "@R" or "@r" prefix is used to indicate that the file resides on the
remote task machine.

DOS, OS/2, NetWare
       @R[d:][path]filename[.ext]

       When "[path]" is not specified, the current directory of the
       specified drive of the remote machine is assumed.  When "[d:]" is
       not specified, the current drive of the remote machine is
       assumed.

       Example:
         view @rmyappl.dat
         view @r\programs\src\uilib.c
         view @rd:\programs\exe\myappl.lnk
         log @rlpt1

QNX       @R[path]filename

       When "[path]" is not specified, the current working directory of
       the remote machine is assumed.

       Example:
         view @rmyappl.dat
         view @r/programs/src/uilib.c
         view @r//7/programs/exe/myappl.lnk
         log @r/dev/par1

Thus a file may be identified to the debugger in three different ways:

DOS, OS/2, NetWare
       [d:][path]filename[.ext]

       @L[d:][path]filename[.ext]

       @R[d:][path]filename[.ext]

QNX       [path]filename

       @L[path]filename

       @R[path]filename

A file of the first form resides on the debugger machine unless the
"REMotefiles" option has been specified, in which case, it resides on the
task machine.  A file of the second form always resides on the debugger
machine.  A file of the third form always resides on the task machine.

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  The special drive prefixes "@L" and "@R" cannot be used in your own │
│ application to reference files on two different machines.  These prefixes  │
│ are recognized by VIDEO and the RFX utility only.  Should the situation    │
│ arise where one of your filenames begins with the same prefix ("@L", "@l", │
│ "@R" or "@r") then "@@" can be used.    For example, if your wish to refer   │
│ to the file on disk called "@link@" then you could specify "@@link@".      │
│ Note that ".\@link@" (DOS, OS/2, NetWare) or "./@link@" (QNX) would also   │
│ suffice.                                     │
└────────────────────────────────────────────────────────────────────────────┘



Interrupting an Executing Program on the Task Machine
═════════════════════════════════════════════════════
Once a program has been loaded by VIDEO, its execution can be started by the
Go command (this command is described under the topic entitled "GO").  As is
sometimes the case during the development phase, a program may execute
endlessly.


Interrupting an Executing Program Under DOS
───────────────────────────────────────────
When an application is executing under DOS on the task machine, it may be
interrupted by pressing one of the Print Screen (PrtSc) or System Request
(SysRq) keys on the task machine (the PC that is running the application).
On some keyboards, the Shift key must also be pressed to obtain the Print
Screen function.

The Ctrl/Break key combination may be pressed on the keyboard of the
debugger machine to interrupt execution of VIDEO commands.



Interrupting an Executing Program Under OS/2
────────────────────────────────────────────
When an application is executing under OS/2 on the task machine, it may be
interrupted by pressing the Ctrl/Break key combination in the remote server
session (the session that is running the server program).

The Ctrl/Break key combination may be pressed in the VIDEO session of the
debugger machine to interrupt execution of VIDEO commands.



Interrupting an Executing Program Under QNX
───────────────────────────────────────────
When an application is executing under QNX on the task machine, it may be
interrupted by pressing Ctrl/Break at the application's virtual console
(provided that the application has not taken over the SIGINT signal).  If
the application has taken over the SIGINT signal then the following
technique for interrupting program execution may be used.  Any signal that
will kill the executing application program (e.g., SIGKILL, SIGSEGV) may be
issued at another virtual console.  You must obtain the process-id of the
application program and then issue a "kill" command.

Example:
  % kill -kill 1423

VIDEO will print a message in the "Dialogue" window indicating that the
program's execution has been interrupted.  Execution can be resumed with the
Go command.

The Ctrl/Break key combination may be pressed at the debugger's virtual
console to interrupt execution of VIDEO commands.
::::REMOTE_WIN3
Remote Debugging of MS Windows Applications
═══════════════════════════════════════════

Many of the concepts of remote debugging are presented in the
"REMOTE_DEBUGGING" help topic.    You may wish to refer to this topic for more
detailed explanations.

The personal computer that is used to run the Windows application is called
the "task machine".  Microsoft Windows must be installed on this PC.  One of
the VIDEO server tasks, described below, must be present on the task machine
so that it can be started from Windows.  The application that is to be
debugged must be accessible from the task machine so that it can be loaded
by the server task running under Windows.

The other personal computer, called the "debugger machine", is used to run
the debugger.  It is not necessary for Windows to be installed on this
machine.  This system could be running DOS, OS/2 or QNX.  The application's
source files should be accessible from the debugger machine so that VIDEO
can display source lines for a particular module.

Let us assume that PC #1 is your primary development machine.  It contains
your application, its data files, its source files, and the programs that
you have been using to develop your application (editor, compiler, linker,
debugger, etc.).  It also contains an installed copy of Microsoft Windows.
Let us assume that PC #2 is a spare machine that is available for your use.
Since two computer systems are involved, there are two possible scenarios.

  1. You could copy the application and any required data files to PC #2.
    You would also have to make sure that Microsoft Windows is installed on
    this machine.  In this scenario, your primary development machine (PC
    #1) will be used to run the debugger and your spare machine will be used
    to run your Windows application.  Thus, the source files for your
    application are present on the debugger machine.

  2. You could copy the debugger over to PC #2.  In this scenario, your
    primary development machine (PC #1) will be used to run your Windows
    application.  Unless you copy all of the application's source files to
    PC #2, the debugger will not have access to them.  In this case, you can
    use the VIDEO "REMotefiles" option to inform the debugger that source
    files are to be obtained over the communications link from the task
    machine (PC #1).  Another advantage to the "REMotefiles" option is that
    the debugger will also locate debugger command files, by default, on the
    task machine.  If this option is not specified then the debugger command
    files must also be copied over to the debugger machine (PC #2).

The decision as to which machine you should be using for the task and which
for the debugger is up to you.    In certain cases, it may depend on the
amount of available memory on each machine or the speed of their respective
processors.  If a large amount of memory is required for your application
then it makes sense that the task machine be the one with the most memory.
If application execution speed is important then it makes sense that the
task machine be the faster of the two.


Remote Debugging with Microsoft Windows
═══════════════════════════════════════
To use the remote debugging capabilities of VIDEO, Microsoft Windows must be
started in standard or enhanced mode.  When debugging 32-bit applications,
you must include the "device" specification listed below in the [386Enh]
section of your Windows "SYSTEM.INI" file.

  DEVICE=[d:]\WATCOM\BINW\WDEBUG.386

This device driver can be used when debugging 16-bit applications also.

You must include the Windows SDK file "WINDEBUG.DLL" in your path.  This
file is included in the WATCOM software package.



VIDEO Communications Servers for Windows
════════════════════════════════════════
Version 3.0 or later of Microsoft Windows is required to support debugging
of Windows applications.  A server task must be run on the task machine
before VIDEO is started on the debugger machine.  There are a number of
servers provided for use with VIDEO under Windows.

PARSERVW.EXE
       This program supports Windows debugging over the parallel port.

NETSERVW.EXE
       This program supports Windows debugging using NetBIOS support.

These programs are described in subsequent sections.

In the following diagram, we illustrate the use of VIDEO running on a second
computer system to debug an application running under Windows on the first
computer system.  In the example, parallel communications are used.

    PC #1              PC #2
  ┌────────────────┐        ┌────────────────┐
  │  Task Machine  │        │Debugger Machine│
  │    Windows       │        │       DOS         │
  │           │        │             │
  │    PARSERVW<───│────┐   │      WVIDEO     │
  │      │       │    │   │        │         │
  │      V       │    │   │        V         │
  │  trap handler  │    └───│──>trap handler │
  │    STD.DLL       │        │     PAR.TRP     │
  └────────────────┘        └────────────────┘

Figure 29. MS Windows Debugging using Two Computer Systems

Notes:

  1. You should note the following regarding keyboard input.  Anything that
    is typed to the debugger itself must be typed on the debugger machine.
    As well, anything that is typed to the application being debugged must
    be typed on the task machine.

  2. The same is true of screen output.  All debugger output comes out on
    the debugger machine, while all program output occurs on the task
    machine.

Select the window in which you have installed the VIDEO Debug Server
programs.  Icons are presented for each of the debug servers.  Double-click
on the one that you wish to use.



The Parallel Port Server
════════════════════════
The parallel port server task must be started on the task machine before
VIDEO is started on the debugger machine.  This is required since VIDEO will
begin to communicate immediately with the task machine via this special
server program.

The wiring required for parallel communications is described under the topic
entitled "WIRING" in the section entitled "Parallel Port Wiring
Considerations".

The parallel server task can be told the number (1, 2, 3) of the parallel
port to use.  The default port number is 1.

These numbers correspond to the device number used when specifying the
parallel printer device "LPTx" (as in "LPT1", "LPT2", etc.).

When debugging over the parallel port, the following files are required on
the task machine:

  1. the parallel port server task, "PARSERVW.EXE",

  2. the interface to Microsoft Windows, "STD.DLL",

  3. the Microsoft SDK file, "WINDEBUG.DLL",

  4. the device driver, "WDEBUG.386",

  5. the executable file to be debugged, and

  6. any data files required by the executable.

The following files are required on the debugger machine:

  1. the WATCOM debugger

    DOS, OS/2  WVIDEO.EXE
    QNX        wvideo

  2. one of the following trap files:

    DOS        PAR.TRP
    OS/2       PAR.DLL
    QNX        par.trp



The NetBIOS Server (DOS, OS/2 Only)
═══════════════════════════════════
Debugging with the NetBIOS network programming interface can also be done.
Remote debugging with this network protocol requires that the NetBIOS server
task be run on the task machine before VIDEO is started on the debugger
machine.  This is required since VIDEO will begin to communicate immediately
with the task machine via this special server program.

A "server name" can be specified.  The server name is case sensitive and it
must be unique (you will be notified if it is not unique).  The name may be
up to 15 alphanumeric characters.  The server name uniquely identifies the
server to VIDEO running on the debugger machine.  The default server name is
"NetLink".

When debugging with the NetBIOS network programming interface, the following
files are required on the task machine:

  1. the NetBIOS server task, "NETSERVW.EXE",

  2. the interface to Microsoft Windows, "STD.DLL",

  3. the Microsoft SDK file, "WINDEBUG.DLL",

  4. the device driver, "WDEBUG.386",

  5. the executable file to be debugged, and

  6. any data files required by the executable.

The following files are required on the debugger machine:

  1. the WATCOM debugger

    DOS, OS/2  WVIDEO.EXE

  2. one of the following trap files:

    DOS        NET.TRP
    OS/2       NET.DLL
::::RFX
Remote File Operations (DOS, OS/2 Only)
═══════════════════════════════════════

The Remote File eXchange program, RFX, may be used to manipulate files on a
personal computer which is connected to your personal computer using one of
the connection strategies described later on under this topic.    The types of
file operations that are supported on both local and remote machines
include:

  1. directory creation, listing and removal,

  2. setting of current drive and directory, and

  3. file display, renaming, erasure, and copying (including PC to PC file
    transfers).

The PC to PC links that are currently supported are:

  1. serial port to serial port,

  2. parallel port to parallel port,

  3. the Novell "NetWare" network, and

  4. the NetBIOS network programming interface.

To run the remote file operations utility, RFX, the following syntax is
used.

┌──────────────────────────────────────────────────────────────────────────┐
│ RFX trap_file[;trap_parm] [rfx_cmd]                       │
└──────────────────────────────────────────────────────────────────────────┘

The name of a trap file must be specified when running RFX.  These files
handle the machine-to-machine communication required for remote file
operations.

For DOS, the file extension defaults to ".TRP".  The DOS PATH environment
variable must contain the path of the trap files.  Trap files are usually
located in the "BIN" sub-directory of the directory that VIDEO is installed
in.

For OS/2, the file extension defaults to ".DLL".  The OS/2 LIBPATH directive
in the "CONFIG.SYS" file must be used to identify the location of the "DLL"
trap files.  Trap files are usually located in the "BINP\DLL" sub-directory
of the directory that VIDEO is installed in.

Trap files are described in the next section.

An optional command rfx_cmd may be specified.  RFX commands are described in
the sections following "RFX Commands".    When RFX is run without specifying a
command then RFX may be used in an interactive mode.  A prompt will appear
that resembles your DOS or OS/2 prompt.  Commands will be processed by RFX
until the "EXIT" command is entered.



Trap Files
══════════
The following trap files may be used with RFX to support machine-to-machine
communications.

STD.TRP, STD16.DLL, STD32.DLL
       Under DOS, if you do not specify a trap file, the default trap
       file "STD.TRP" will be loaded.  Under OS/2 1.x, if you do not
       specify a trap file, the default trap file "STD16.DLL" will be
       loaded.  Under OS/2 2.x, if you do not specify a trap file, the
       default trap file "STD32.DLL" will be loaded.  These interface
       modules support file operations on the local personal computer
       only.  No remote file operations are possible.  The optional
       "trap_parm" is ignored.


SER.TRP, SER.DLL
       This communications driver file supports remote file operations
       between two personal computers using the serial ports of the two
       machines.  If RFX is to run under DOS then "SER.TRP" must be
       used.  If RFX is to run under OS/2 then "SER.DLL" must be used.
       The serial port of the local machine is connected to the serial
       port of the remote machine.    The "trap_parm" value specifies the
       port number to use and an optional maximum BAUD rate (which is
       separated from the port number by a period).  The port number is
       1, 2, 3 or 4 (default is 1).  These numbers correspond to the
       device number used when specifying the serial device "COMx" (as
       in "COM1", "COM2", etc.).

       Under DOS, the maximum BAUD rate can be one of:

         115200
          57600
          38400
          19200
           9600
           4800
           2400
           1200
          0 (a special case)

       The default maximum BAUD rate is 115,200.

       Under OS/2, the maximum BAUD rate can be one of:

          19200
           9600
           4800
           2400
           1200
          0 (a special case)

       The default maximum BAUD rate is 19,200.

       Except for the special BAUD rate of 0, a minimum of two digits
       must be specified to identify the desired maximum BAUD rate.  The
       maximum BAUD rate is explained in the section "Remote File
       Operations Over the Serial Port".  In the following example, port
       2 and a maximum BAUD rate of 19,200 is specified.

       Example:
         /trap=ser;2.19

PAR.TRP, PAR.DLL
       This communications driver file supports remote file operations
       between two personal computers using the parallel ports of the
       two machines.  If RFX is to run under DOS then "PAR.TRP" must be
       used.  If RFX is to run under OS/2 then "PAR.DLL" must be used.
       The parallel port of the local machine is connected to the
       parallel port of the remote machine.  The port number to use is
       specified by "trap_parm".  The port number is 1, 2 or 3 (default
       is 1).  These numbers correspond to the device number used when
       specifying the printer device "LPTx" (as in "LPT1", "LPT2",
       etc.).

NOV.TRP, NOV.TRP
       This communications driver file supports remote file operations
       between two personal computers that are connected to the Novell
       "NetWare" network.  Version 2.0 or higher of NetWare must be
       used.  The server name to use is specified by "trap_parm".  The
       server name must match the name that you specified when starting
       the server on the "task" machine.  The notion of a "server" is
       explained in the section "Communications Servers".

NET.TRP, NET.DLL
       This communications driver file supports remote file operations
       between two personal computers using the NetBIOS network
       programming interface.  The server name to use is specified by
       "trap_parm".  The server name must match the name that you
       specified when starting the server on the remote machine.  The
       server name may consist of up to 15 alphanumeric characters.  The
       notion of a "server" is explained in the section "Communications
       Servers".



Communications Servers
══════════════════════
The remote file manipulation facility requires that a server task be run on
the remote machine before RFX is started on the local machine.    There are
four such servers provided for use with RFX.

SERSERV.EXE This program supports remote file operations over the serial
       port.

PARSERV.EXE This program supports remote file operations over the parallel
       port.

NOVSERV.EXE This program supports remote file operations over the Novell
       "NetWare" network.

NETSERV.EXE This program supports remote file operations using NetBIOS
       support.

These programs are described in the following sections.



Remote File Operations Over the Serial Port
═══════════════════════════════════════════
Remote file operations over the serial port require that a server task be
run on the remote machine before RFX is started on the local machine.  This
is required since RFX will immediately begin to communicate with the remote
machine via this special server program.

RFX and the server will automatically synchronize on a communications speed.
They may communicate at rates as high as 115,200 BAUD.    Since the BAUD rate,
parity, number of data bits and stop bits is automatically chosen, the DOS
or OS/2 "MODE" command need not be used.

For DOS or OS/2, the formal serial port server command line syntax is shown
below.

┌──────────────────────────────────────────────────────────────────────────┐
│ SERSERV [/TRap=trap_file[;trap_parm]] [port_number][.max_baud]       │
└──────────────────────────────────────────────────────────────────────────┘

The "port_number" for the serial server is the serial port number (between 1
and 4) that the server should use to communicate with the RFX running on the
local machine.    The default port number is 1.  These numbers correspond to
the device number used when specifying a serial device "COMx" (as in "COM1",
"COM2", etc.).

The optional "max_baud" value specifies the maximum BAUD rate.    It is
separated from the port number by a period.  The maximum BAUD rate can be
one of:

  115200
   57600
   38400
   19200
    9600
    4800
    2400
    1200
       0 (a special case)

The default maximum BAUD rate is 115,200.  Except for the special BAUD rate
of 0, a minimum of two digits must be specified to identify the desired
maximum BAUD rate.  Specification of a maximum BAUD rate is useful when the
maximum rate at which the two machines can communicate effectively is known.
The server and RFX normally start at the fastest possible speed and work
downwards until an effective (error-free) rate is established.    Each trial
speed can require up to 5 seconds to test.  If the maximum rate is specified
ahead of time, this will help reduce the startup time.    The BAUD rate
actually selected will be the minimum of the maximum rates specified when
both the server and RFX are started and the rate at which the two can
effectively communicate.  An example may help to explain this.

Example:
  Remote machine: C>serserv 2.38400
  Local  machine: D>rfx ser;1.57600

In the above example, the maximum rate at which the two machines could
communicate is 38,400 BAUD (since it is the minimum of 38,400 and 57,600).
However, the actual rate selected for effective communications may be less
than this.

If 0 is specified for the maximum BAUD rate when both the server and RFX are
started, the process of searching for the maximum rate at which the two
machines can communicate is eliminated.  The BAUD rate for each side must be
established through other means (such as the DOS or OS/2 "MODE" command) and
the rates must be identical.  The parity, word length and number of stop
bits are selected by the server and RFX so you need not specify these
parameters.  The BAUD rate value 0 should be specified when modems are
employed between the two machines.

Example:
  Remote machine: C>mode com2:2400
  Remote machine: C>serserv 2.0
  Local  machine: D>mode com1:2400
  Local  machine: D>rfx ser;1.0

In the above example, the rate at which the two machines can communicate is
2400 BAUD (since it is the specified externally using the DOS or OS/2 "MODE"
command).

The "TRap" option is only specified in special applications where more than
two personal computers are chained together in series.    "SERSERV" receives
requests over a serial port.  It can process these requests locally or pass
them on to a server running on another computer system.  By default,
requests will be handled locally by the "STD.TRP" file when DOS is running,
the "STD16.DLL" file when OS/2 1.x is running, and the "STD32.DLL" file when
OS/2 2.x is running.

When manipulating files over the serial port, the following files are
required on the remote machine:

  SERSERV.EXE
  STD.TRP, STD16.DLL, or STD32.DLL

The following files are required on the local machine:

  RFX.EXE
  SER.TRP or SER.DLL

The following is a sequence of commands that one might issue on DOS to
manipulate files remotely over the serial port:

  Remote machine: C>serserv 2
  Local  machine: D>rfx ser;1
  Local  machine: commands such as "copy", "dir", etc.
  Local  machine: exit
  Remote machine: q

In the example, serial port 2 is used on the remote machine and serial port
1 is used on the local machine.  An appropriately-wired cable (described
below) runs between serial port 2 of the remote machine and serial port 1 of
the local machine.  Messages will appear on both the remote and local
machines indicating the BAUD rate at which the two machines are
communicating.

The final "q" typed on the keyboard of the remote machine is used to
terminate the server.  If this is not done, the server returns to its
start-up state and you could rerun RFX or run VIDEO.

The wiring required for serial communications is described under the topic
entitled "WIRING" in the section entitled "Serial Port Wiring Considerations".



Remote File Operations Over the Parallel Port
═════════════════════════════════════════════
Remote file operations over the the parallel port are significantly faster
than the serial port.  Remote file operations over the parallel port require
that a server task be run on the remote machine before RFX is started on the
local machine.    This is required since RFX will immediately begin to
communicate with the remote machine via this special server program.

For DOS or OS/2, the formal parallel port server command line syntax is
shown below.

┌──────────────────────────────────────────────────────────────────────────┐
│ PARSERV [/TRap=trap_file[;trap_parm]] [port_number]               │
└──────────────────────────────────────────────────────────────────────────┘

The "port_number" for the parallel server is the parallel port number
(between 1 and 3) that the server should use to communicate with RFX running
on the local machine.  The default port number is 1.  These numbers
correspond to the device number used when specifying the parallel printer
device "LPTx" (as in "LPT1", "LPT2", etc.).

The "TRap" option is only specified in special applications where more than
two personal computers are chained together in series.    "PARSERV" receives
requests over a parallel port.    It can process these requests locally or
pass them on to a server running on another computer system.  By default,
requests will be handled locally by the "STD.TRP" file when DOS is running,
the "STD16.DLL" file when OS/2 1.x is running, and the "STD32.DLL" file when
OS/2 2.x is running.

When manipulating files over the parallel port, the following files are
required on the remote machine:

  PARSERV.EXE
  STD.TRP, STD16.DLL, or STD32.DLL

The following files are required on the local machine:

  RFX.EXE
  PAR.TRP or PAR.DLL

The following is a sequence of commands that one might issue on DOS to
manipulate files remotely over the parallel port:

  Remote machine: C>parserv 1
  Local  machine: D>rfx par;2
  Local  machine: commands such as "copy", "dir", etc.
  Local  machine: exit
  Remote machine: q

In the example, parallel port 1 is used on the remote machine and parallel
port 2 is used on the local machine.  An appropriately-wired cable
(described below) runs between parallel port 1 of the remote machine and
parallel port 2 of the local machine.

The final "q" typed on the keyboard of the remote machine is used to
terminate the server.  If this is not done, the server returns to its
start-up state and you could rerun RFX or run VIDEO.

The wiring required for parallel communications is described under the topic
entitled "WIRING" in the section entitled "Parallel Port Wiring
Considerations".



Remote File Operations Over the Novell "NetWare" Network
════════════════════════════════════════════════════════
Remote file operations over the Novell "NetWare" network requires the
NetWare shell.    The Internetwork Packet Exchange (IPX) must be loaded first
and the server task must be run on the remote machine before RFX is started
on the local machine.  This is required since RFX will immediately begin to
communicate with the remote machine via this special server program.

For DOS or OS/2, the formal NetWare server command line syntax is shown
below.

┌──────────────────────────────────────────────────────────────────────────┐
│ NOVSERV [/TRap=trap_file[;trap_parm]] [server_name]               │
└──────────────────────────────────────────────────────────────────────────┘

The "server_name" is case insensitive and it must be unique (you will be
notified if it is not unique).    The name is restricted to less than 48
characters.  It cannot contain the following special characters:

  / \ : ; . , * ? + -

Any invalid characters are removed and any excess characters are dropped
from the name.    The "server_name" uniquely identifies the server to RFX
running on the local machine.  The default "server_name" is "NovLink".

The "TRap" option is only specified in special applications where more than
two personal computers are chained together in series.    "NOVSERV" receives
requests over the "NetWare" network.  It can process these requests locally
or pass them on to a server running on another computer system.  By default,
requests will be handled locally by the "STD.TRP" file when DOS is running,
the "STD16.DLL" file when OS/2 1.x is running, and the "STD32.DLL" file when
OS/2 2.x is running.

When manipulating files over the "NetWare" network, the following files are
required on the remote machine:

  NOVSERV.EXE
  STD.TRP, STD16.DLL, or STD32.DLL

The following files are required on the local machine:

  RFX.EXE
  NOV.TRP or NOV.DLL

The following is a sequence of commands that one might issue on DOS to
manipulate files remotely over the "NetWare" network:

  Remote machine: C>novserv rmt_dbg
  Local  machine: D>rfx nov;rmt_dbg
  Local  machine: commands such as "copy", "dir", etc.
  Local  machine: exit
  Remote machine: q

In the example, server name "RMT_DBG" is used on the remote machine so
server name "RMT_DBG" is also used on the local machine.

The final "q" typed on the keyboard of the remote machine is used to
terminate the server.  If this is not done, the server returns to its
start-up state and you could rerun RFX or run VIDEO.



Remote File Operations Using NetBIOS Support
════════════════════════════════════════════
Remote file operations using the NetBIOS network programming interface can
also be done.  Remote file operations using this network protocol requires
that a server task be run on the remote machine before RFX is started on the
local machine.    This is required since RFX will immediately begin to
communicate with the remote machine via this special server program.

For DOS or OS/2, the formal NetBIOS server command line syntax is shown
below.

┌──────────────────────────────────────────────────────────────────────────┐
│ NETSERV [/TRap=trap_file[;trap_parm]] [server_name]               │
└──────────────────────────────────────────────────────────────────────────┘

The "server_name" is case sensitive and it must be unique (you will be
notified if it is not unique).    The name may be up to 15 alphanumeric
characters.  The "server_name" uniquely identifies the server to RFX running
on the local machine.  The default "server_name" is "NetLink".

The "TRap" option is only specified in special applications where more than
two personal computers are chained together in series.    "NETSERV" receives
requests over a network using the NetBIOS network programming interface.  It
can process these requests locally or pass them on to a server running on
another computer system.  By default, requests will be handled locally by
the "STD.TRP" file when DOS is running, the "STD16.DLL" file when OS/2 1.x
is running, and the "STD32.DLL" file when OS/2 2.x is running.

When manipulating files with the NetBIOS network programming interface, the
following files are required on the remote machine:

  NETSERV.EXE
  STD.TRP, STD16.DLL, or STD32.DLL

The following files are required on the local machine:

  RFX.EXE
  NET.TRP or NET.DLL

The following is a sequence of commands that one might issue on DOS to
manipulate files remotely with the NetBIOS network programming interface:

  Remote machine: C>netserv rmt_dbg
  Local  machine: D>rfx net;rmt_dbg
  Local  machine: commands such as "copy", "dir", etc.
  Local  machine: exit
  Remote machine: q

In the example, server name "rmt_dbg" is used on the remote machine so
server name "rmt_dbg" is also used on the local machine.

The final "q" typed on the keyboard of the remote machine is used to
terminate the server.  If this is not done, the server returns to its
start-up state and you could rerun RFX or run VIDEO.



Specifying Files on Remote and Local Machines
═════════════════════════════════════════════
When using the remote file operations facility, a method for identifying
files on either of the local or remote machines is required.  In order to
identify files on either the local or remote machine, two special prefixes
are supported by RFX.

@L       The "@L" prefix is used to indicate that the file resides on the
       local machine (the one on which RFX is running).

         @L[d:][path]filename[.ext]

       When "[path]" is not specified, the current directory of the
       specified drive of the local machine is assumed.  When "[d:]" is
       not specified, the current drive of the local machine is assumed.

       Example:
         TYPE @LOUTPUT.LOG
         COPY @LOUTPUT.LOG @LLPT2
         DIR @LD:\CMDS
         ERASE @LD:\CMDS\DATA.TMP

@R       The "@R" prefix is used to indicate that the file resides on the
       remote machine.

         @R[d:][path]filename[.ext]

       When "[path]" is not specified, the current directory of the
       specified drive of the remote machine is assumed.  When "[d:]" is
       not specified, the current drive of the remote machine is
       assumed.

       Example:
         TYPE @RMYAPPL.DAT
         ERASE @RD:\PROGRAMS\EXE\MYAPPL.LNK
         DIR @R\PROGRAMS\SRC
         COPY @R\PROGRAMS\SRC\UILIB.C @RLPT1

Thus a file may be identified to RFX in three different ways.

  [d:][path]filename[.ext]
  @L[d:][path]filename[.ext]
  @R[d:][path]filename[.ext]

A file of the first form resides on either the local or remote machine
depending on whether the current drive is a local or remote drive.  A file
of the second form always resides on the local machine.  A file of the third
form always resides on the remote machine.

Notes:

  1. In the each form, the omission of "[d:]" indicates the current drive.

      [path]filename[.ext]
      @L[path]filename[.ext]
      @R[path]filename[.ext]

  2. In the each form, the omission of "[path]" indicates the current path
    of the specified drive.

      [d:]filename[.ext]
      @L[d:]filename[.ext]
      @R[d:]filename[.ext]

    Observe that if "[d:]" is omitted also then the following forms are
    obtained:

      filename[.ext]
      @Lfilename[.ext]
      @Rfilename[.ext]

  3. The special drive prefixes "@L" and "@R" cannot be used in your own
    application to reference files on two different machines.  These
    prefixes are recognized by RFX and VIDEO only.  Should the situation
    arise where one of your filenames begins with the same prefix ("@L",
    "@l", "@R" or "@r") then "@@" can be used.    For example, if your wish to
    refer to the file on disk called "@link@" then you could specify
    "@@link@".    Note that ".\@link@" would also suffice.



RFX Commands
════════════
When RFX is run without specifying a command, the DOS or OS/2 prompt will
change as illustrated in the following example.

Example:
  Mon  11-06-1989 15:17:05.84 E:\DOC\UG
  E>rfx par
  [RFX] Mon  11-06-1989 15:17:12.75 @LE:\DOC\UG
  [RFX] E>

Note that the current drive specifier "E" in "E:\DOC\UG" has changed to
"@LE" indicating that the current drive is the local "E" drive.

Any command can be typed in response to the prompt.  RFX recognizes a
special set of commands and passes all others on to DOS or OS/2 for
processing.  The following sections describe RFX commands.



Set Current Drive - drive:
══════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ drive:                                   │
└──────────────────────────────────────────────────────────────────────────┘

The current drive and locale can be set using this command.  The "@L" or
"@R" prefix may be used to specify the locale (local or remote).

Example:
  d:

Make the "D" disk of the current locale (local or remote) the current drive.
Since the locale is not specified, it remains unchanged.

Example:
  @rc:

Make the "C" disk of the remote machine the current drive.  Both locale and
disk are specified.

Example:
  @le:

Make the "E" disk of the local machine the current drive.  Both locale and
disk are specified.



Change Directory - CHDIR, CD
════════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ chdir dir_spec                               │
│ cd dir_spec                                   │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to change the current directory of any disk on the
local or remote machine.  CD is a short form for CHDIR.  The "@L" or "@R"
prefix may be used to specify the locale (local or remote).

Example:
  cd \tmp

Make the "TMP" directory of the current drive the current directory.

Example:
  cd d:\etc

Make the "ETC" directory of the "D" disk of the current locale (local or
remote) the current directory of that drive.

Example:
  cd @rc:\demo

Make the "DEMO" directory of the "C" disk of the remote machine the current
directory of that drive.  Both locale and disk are specified.

Example:
  cd @le:test

Make the "TEST" subdirectory of the current directory of the "E" disk of the
local machine the current directory of that drive.  Both locale and disk are
specified.



Copy Files - COPY
═════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ copy [/s] src_spec [dst_spec] [/s]                       │
└──────────────────────────────────────────────────────────────────────────┘

The COPY command operates in a manner very similar to the DOS "COPY" and
"XCOPY" commands.  Files may be copied from the local machine to the local
or remote machine.  Similarly files may be copied from the remote machine to
the local or remote machine.  If /s is specified then subdirectories are
copied as well.  Directories will be created as required for the destination
files.    If dst_spec is not specified then the default destination will be
the current directory of the other locale (i.e., remote, if the file's
locale is local or, local, if the file's locale is remote).

Example:
  copy *.for @rd:\tmp

All files of type "FOR" in the current directory are copied to the "TMP"
directory of the "D" disk on the remote machine.  If the current locale is
the local machine then files are copied from the local machine to the remote
machine.  If the current locale is the remote machine then files are copied
from the remote machine to the remote machine.

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  If your default drive is set to one of the disks on the local         │
│ machine then the locale is local (e.g., @LC:, @LD:, @LE:, etc.).  If your  │
│ default drive is set to one of the disks on the remote machine then the    │
│ locale is remote (e.g., @RC:, @RD:, @RE:, etc.).  If your DOS or OS/2      │
│ prompt contains the current drive and directory then it will be easy to    │
│ identify which locale is current.                         │
└────────────────────────────────────────────────────────────────────────────┘

Example:
  copy @rd:\tmp\*.for

All files of type "FOR" in the "TMP" directory of the "D" disk on the remote
machine are copied to the current directory of the local machine.  Whenever
a destination is not specified, the current directory of the opposite locale
is used.  If the source locale is the remote machine then files are copied
from the remote to the local machine.  If the source locale is the current
machine then files are copied from the local to the remote machine.

Example:
  copy @rc:\watcom\*.* /s

All files and subdirectories of the "WATCOM" directory of the "C" disk on
the remote machine are copied to the current directory of the local machine.
Whenever a destination is not specified, the current directory of the
opposite locale is used.  If the source locale is the remote machine then
files are copied from the remote to the local machine.    If the source locale
is the current machine then files are copied from the local to the remote
machine.  Subdirectories are created as required.

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  The "COPY" command is most effectively used when copying files from │
│ one machine to the other.  Copying of large amounts of files from one      │
│ place on the remote machine to another place on the remote machine could   │
│ be done more effectively using the remote machine's DOS or OS/2.  This     │
│ would eliminate the transfer of data from the remote machine to the local  │
│ machine and back to the remote machine.                     │
└────────────────────────────────────────────────────────────────────────────┘



List Directory - DIR
════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ dir [/w] dir_spec [/w]                           │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to list the directories of any disk on the local or
remote machine.  Any of the DOS or OS/2 "wild card" characters ("?" and "*")
may be used.  If /w is specified then file names are displayed across the
screen ("wide") and the file creation date and time are omitted.

Example:
  dir \tmp

List the names of files in the "TMP" directory of the current drive.

Example:
  dir d:\etc

List the names of files in the "ETC" directory of the "D" disk of the
current locale (local or remote).

Example:
  dir @rc:\demo

List the names of files in the "DEMO" directory of the "C" disk of the
remote machine.  Both locale and disk are specified.

Example:
  dir @le:test

List the names of files in the "TEST" subdirectory of the current directory
of the "E" disk of the local machine.  If no "TEST" subdirectory exists then
the names of all files named "TEST" will be listed.  Both locale and disk
are specified.

Example:
  dir @le:test.*

List the names of all files named "TEST" in the current directory of the "E"
disk of the local machine.  Both locale and disk are specified.



Erase File - ERASE, DEL
═══════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ erase [/s] file_spec [/s]                           │
│ del [/s] file_spec [/s]                           │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to erase files from the directories of any disk on
the local or remote machine.  DEL is a short form for ERASE.  Any of the DOS
or OS/2 "wild card" characters ("?" and "*") may be used.  If /s is
specified then subdirectories are also processed.

Example:
  erase \tmp\*.*

Erase all the files in the "TMP" directory of the current drive.

Example:
  erase d:\etc\*.lst

Erase all files of type "LST" in the "ETC" directory of the "D" disk of the
current locale (local or remote).

Example:
  erase @rc:\demo\*.obj

Erase all files of type "OBJ" in the "DEMO" directory of the "C" disk of the
remote machine.  Both locale and disk are specified.

Example:
  erase @le:trial.*

Erase all files named "TRIAL" of any type in the current directory of the
"E" disk of the local machine.    Both locale and disk are specified.



Exit from RFX - EXIT
════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ exit                                       │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to exit from RFX and return to the invoking
process.



Make Directory - MKDIR, MD
══════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ mkdir dir_spec                               │
│ md dir_spec                                   │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to create a directory on any disk on the local or
remote machine.  MD is a short form for MKDIR.    The "@L" or "@R" prefix may
be used to specify the locale (local or remote).

Example:
  md \tmp

Create a "TMP" directory in the root of the current drive.

Example:
  md d:\etc

Create an "ETC" directory in the root of the "D" disk of the current locale
(local or remote).

Example:
  md @rc:\demo

Create a "DEMO" directory in the root of the "C" disk of the remote machine.
Both locale and disk are specified.

Example:
  md @le:test

Create a "TEST" subdirectory in the current directory of the "E" disk of the
local machine.    Both locale and disk are specified.



Rename - RENAME, REN
════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ rename file_spec new_name                           │
│ ren file_spec new_name                           │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to rename a file in any directory on any disk on
the local or remote machine.  REN is a short form for RENAME.  The "@L" or
"@R" prefix may be used to specify the locale (local or remote).  Unlike the
DOS "RENAME" command, a file can be moved to a different directory if the
directory is specified in new_name.

Example:
  ren test.tmp test1.tmp

Rename the file "TEST.TMP" in the current directory of the current drive to
"TEST1.TMP".

Example:
  ren d:\etc\test.tmp test1.tmp

Rename the file "TEST.TMP" in the "ETC" directory of the "D" disk of the
current locale (local or remote) to "TEST1.TMP".

Example:
  ren @rc:\demo\test.tmp test1.tmp

Rename the file "TEST.TMP" in the "DEMO" directory of the "C" disk of the
remote machine to "TEST1.TMP".    Both locale and disk are specified.

Example:
  ren @le:trial.dat trial1.dat

Rename the file "TRIAL.DAT" in the current directory of the "E" disk of the
local machine to "TRIAL1.DAT".    Both locale and disk are specified.

Example:
  ren @le:trial.dat ..\trial1.dat

Rename the file "TRIAL.DAT" in the current directory of the "E" disk of the
local machine to "TRIAL1.DAT" and move it to the parent directory.  Both
locale and disk are specified.



Remove Directory - RMDIR, RD
════════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ rmdir [/s] dir_spec [/s]                           │
│ rd [/s] dir_spec [/s]                            │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to remove one or more directories on any disk on
the local or remote machine.  RD is a short form for RMDIR.  The "@L" or
"@R" prefix may be used to specify the locale (local or remote).  If /s is
specified then subdirectories are also removed.  Before a directory can be
removed, it must not contain any files.

Example:
  rd \tmp

Remove the "TMP" directory from the root of the current drive.

Example:
  rd d:\etc

Remove the "ETC" directory from the root of the "D" disk of the current
locale (local or remote).

Example:
  rd @rc:\demo

Remove the "DEMO" directory from the root of the "C" disk of the remote
machine.  Both locale and disk are specified.

Example:
  rd @le:test

Remove the "TEST" subdirectory from the current directory of the "E" disk of
the local machine.  Both locale and disk are specified.



Display File Contents - TYPE
════════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ type dir_spec                                │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to list the contents of a file on any disk on the
local or remote machine.  The "@L" or "@R" prefix may be used to specify the
locale (local or remote).  Unlike the DOS "TYPE" command, DOS or OS/2 "wild
card" characters ("?" or "*") may be used.

Example:
  type \tmp\test.dat

List the contents of the file "TEST.DAT" in the "TMP" directory of the
current drive.

Example:
  type d:\etc\*.lst

List the contents of all files of type "LST" in the "ETC" directory of the
"D" disk of the current locale (local or remote).

Example:
  type @rc:\demo\test.c

List the contents of the file "TEST.C" in the "DEMO" directory of the "C"
disk of the remote machine.  Both locale and disk are specified.

Example:
  type @le:trial.*

List the contents of all files named "TRIAL" of any type in the current
directory of the "E" disk of the local machine.  Both locale and disk are
specified.
::::SET
┌──────────────────────────────────────────────────────────────────────────┐
│ Set                                       │
│     Assembly { Lower | Upper | Inside | Outside }               │
│     Bell     ON | OFf                            │
│     Call     [dflt_call] [dflt_parms] [dflt_return]               │
│     Dclick   expr                               │
│     Fpu      Binary | Decimal                        │
│     Implicit ON | OFf                            │
│     INput    window_name                           │
│     LAnguage lang_name                           │
│     Level    Assembly | Mix | Source                       │
│     MAcro    window_name key_expr [cmd_list]                   │
│     Menu     ON | OFf | Add cmd_list | ACtivate               │
│     Pfkey    expr (string | "{" string "}")                   │
│     Radix    expr | ("/"radix_spec [expr])                   │
│     SOurce   [/Add] { "{" {char} "*" {char} "}" }               │
│     SYmbol   [/Add] { [/(Respect | Ignore)] "{" {char} "*" {char} "}" }  │
│     Tab      expr                               │
│     Visible  Assembly | Source [top][,[bot][,bias]]               │
└──────────────────────────────────────────────────────────────────────────┘

The Set command is used to establish operational defaults for other VIDEO
commands.



Disassembly Options
═══════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Assembly { Lower | Upper | Inside | Outside }               │
└──────────────────────────────────────────────────────────────────────────┘

These options control how assembly instructions and operands are displayed.
The "lower" option causes opcodes and registers to be displayed in
lowercase.  The "upper" option causes opcodes and registers to be displayed
in uppercase.  The "inside" option causes register indexing displacements to
be shown inside brackets (e.g., [BP-2], [EBP-2]).  The "outside" option
causes register indexing displacements to be shown outside brackets (e.g.,
-2[BP], -2[EBP]).



Warning Bell
════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Bell ON | OFf                               │
└──────────────────────────────────────────────────────────────────────────┘

The warning beep issued by VIDEO may be turned "on" or "off".  A beep is
issued whenever an error message is printed by the debugger.



Default Call
════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Call [dflt_call] [dflt_parms] [dflt_return]               │
└──────────────────────────────────────────────────────────────────────────┘

The default call type (Far, Interrupt or Near) and the default argument
passing mechanism to be used by the VIDEO Call command may be set.

  dflt_call ::= /(Far | Interrupt | Near)
  dflt_parms ::= "(" [ dflt_loc { "," dflt_loc } ] ")"
  dflt_return ::= "/" | print_list
  dflt_loc ::= reg_name | reg_aggregate

In the following example, we define WATCOM's default calling conventions for
the Call command.

Example:
  DBG>set call /far (ax, dx, bx, cx) ax

To change the default calling convention to one in which "near" calls are
used and all parameters are passed on the stack, we could issue the
following command.

Example:
  DBG>set call /near () ax

See the description of the Call command for more information on argument
passing.



Setting Double-click Rate
═════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Dclick expr                               │
└──────────────────────────────────────────────────────────────────────────┘

This command sets the maximum amount of time, in milliseconds, that is
allowed between two presses of the mouse button, for the two clicks to be
recognized as a double-click and not two single clicks.  The default value
is 250 milliseconds (1/4 of a second).

Example:
  DBG>set dclick 750

The above example will cause two mouse presses separated by more than 750
milliseconds (3/4 of a second) to be regarded as two separate clicks rather
than a double-click.

The command show set dclick will show the current value.



Format of Numeric Data Processor Display
════════════════════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Fpu Binary | Decimal                           │
└──────────────────────────────────────────────────────────────────────────┘

The contents of the 80x87 Numeric Data Processor (NDP, math coprocessor)
registers ST(0), ST(1), etc.  can be displayed in hexadecimal (binary)
format or scientific notation (decimal).  The registers and flags of the
math coprocessor are displayed in the FPU window.

The command show set fpu will show the current setting.



Automatic Command File Invocation
═════════════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Implicit    ON │ OFf                           │
└──────────────────────────────────────────────────────────────────────────┘

When "implicit" is "on", VIDEO will treat an unknown command as the name of
a command file and automatically attempt to invoke it.    When "implicit" is
"off", the INvoke command must be used.

Example:
  DBG>set implicit on
  DBG>* invoke "mix" command file
  DBG>mix

Under QNX, it is possible for a conflict to arise when "implicit" is on.  If
a path is specified for a command file name, it will be confused with the
short form of the DO command which is "/".

Example:
  DBG>/etc=1
  DBG>/etc/wvideo/mix

The first example assigns the value 1 to the variable etc.  The second
example attempts to run the "mix" command file from the "/etc/wvideo"
directory but a syntactical error results.  To resolve this conflict, you
can use either the INvoke command or the local file specifier prefix "@l".

Example:
  DBG>invoke /etc/wvideo/mix
  DBG>@l/etc/wvideo/mix

A similar problem arises under DOS, MS Windows or OS/2 when a drive
specifier forms part of the file name.

Example:
  DBG>d:\\watcom\binb\mix
  DBG>invoke d:\\watcom\binb\mix
  DBG>@ld:\\watcom\binb\mix

The first example results in a syntactical error ("d" is interpreted as the
short form of the Display command).  The second and third examples resolve
the problem.

Local and remote file specifier prefixes are described under the topic
entitled "REMOTE_DEBUGGING".



Current Window
══════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set INput window_name                            │
└──────────────────────────────────────────────────────────────────────────┘

The Set INput command is used to move the text cursor directly to the
specified window.  The valid window names are:

  Assembly
  Command
  Dialogue
  Fpu
  Memory
  Prompt
  Register
  SOurce
  STack
  Thread

The Tab and Shift Tab keys can also be used to move the text cursor to the
following or previous window.  The selected window becomes the active
window.  Keys and the mouse react in the manner described in the sections
"Window Manipulation with Keys" and "Window Manipulation with a Mouse" under
the topic entitled "WINDOWS".

Expression Syntax
═════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set LAnguage lang_name                           │
└──────────────────────────────────────────────────────────────────────────┘

The debugger expression processor can be set to understand the syntax of
certain programming languages.    The operand lang_name represents the name of
an expression syntax or "parse" file.

C       The file "c.prs" describes the ANSI C programming language
       expression syntax supported by VIDEO.

FORTRAN    The file "fortran.prs" describes the ANSI FORTRAN 77 programming
       language expression syntax supported by VIDEO.

Under DOS, MS Windows or OS/2, the "prs" files are usually located in the
"BINB" sub-directory of the directory that VIDEO is installed in.  You
should ensure that the "BINB" directory is included in the PATH environment
variable.

Under QNX, the "prs" files are usually located in the "/etc/wvideo"
directory.  The search order for language parsing files is as follows:

  1. the current directory,
  2. the paths listed in the WVIDEO_PATH environment variable,
  3. the path listed in the HOME environment variable, and, finally,
  4. the "/etc/wvideo" directory.

Example:
  DBG>set language fortran

The debugger will load the expression syntax for FORTRAN 77 from the file
"fortran.prs".

The command show set language will show the current setting.



Debugging Level
═══════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Level Assembly | Mix | Source                       │
└──────────────────────────────────────────────────────────────────────────┘

The Set Level command is used to set the default debugging level.

Assembly   VIDEO will display debugging information at the assembly language
       level.

       Example:
         DBG>set level assembly

Mix       VIDEO will display debugging information at the source language
       level whenever possible, or at the assembly language level when
       no source line information is available.

       Example:
         DBG>set level mix

       This is the default mode of VIDEO.

Source       The source language level is similar to the mix language level
       except that modules for which no source line information is
       available are not traced unless explicitly requested.

       Example:
         DBG>set level source



Macro Hot Keys
══════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set MAcro window_name key_expr [cmd_list]                   │
└──────────────────────────────────────────────────────────────────────────┘

The Set MAcro command may be used to define "hot" keys for various windows.
The valid window names are:

  Assembly
  Command
  Dialogue
  Fpu
  Memory
  Register
  SOurce
  STack
  Thread

The value for key_expr must fall within the range 32 (space) to 126 (tilde).
These are the ASCII printable characters.  One or more debugger commands can
be specified for cmd_list.

Example:
  DBG>set macro source 'v' {view}

In the above example, the command view will be invoked if a lowercase "v" is
pressed when the Source window is active (i.e., when the text cursor is in
the Source window).

Example:
  DBG>set macro assembly 'b' {break dbg$code}

In the above example, the command break dbg$code will be invoked if a
lowercase "b" is pressed when the Assembly window is active (i.e., when the
text cursor is in the Assembly window).  A break point will be set at the
currently highlighted line.

Example:
  DBG>set macro source ' ' {trace/source/over}

In the above example, the command trace/source/over will be invoked if the
space bar is pressed when the Source window is active (i.e., when the text
cursor is in the Source window).  A single-shot trace command will be
executed.

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  The Prompt window is the only window where hot keys cannot be         │
│ defined since text must be entered in this window.                 │
└────────────────────────────────────────────────────────────────────────────┘



Menu Bar
════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Menu ON | OFf | Add cmd_list | ACtivate                   │
└──────────────────────────────────────────────────────────────────────────┘

The Set Menu ON and Set menu OFf commands turn the menu bar display "on" or
"off".

The Set Menu Add command permits the creation of command entries in the
"User" pop-down menu.  An entry is a list of one or more VIDEO commands.
Each new entry is labelled with a letter from the alphabet.  An entry may be
selected by pressing Alt/U to engage the "User" pop-down menu and then
Alt/<letter> where <letter> corresponds to the letter beside the desired
entry.    The mouse can also be used to select an entry.    When an entry is
selected, the commands listed in that entry are executed.  Up to 20 items
can be added to the "User" menu.

The Set Menu ACtivate command emulates the action of pressing and releasing
the Alt key.

Example:
  DBG>set pfkey 10 {set menu activate}

In the above example, we bind the Set Menu ACtivate command to programmable
function key 10.

For a description of VIDEO menus, see the topic entitled "MENUS".



Programmable Function Keys
══════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Pfkey expr (string | "{" string "}")                   │
└──────────────────────────────────────────────────────────────────────────┘

One or more VIDEO commands can be assigned to a programmable function (PF)
key.  Each time that key is pressed, the commands are executed.  You must
use "{" and "}" when you have a ";" in the string since VIDEO uses the
semicolon as a command separator.  If the string is omitted then the current
assignment for the specified PF key is removed.  PF keys are numbered from 1
to 40.

F1-F10       PF keys 1 through 10 are obtained by pressing one of the keys F1
       through F10 (on some keyboards, these may be labeled PF1 through
       PF10).

F11-F20    PF keys 11 through 20 are obtained by pressing both the Shift key
       and one of keys F1 through F10.

F21-F30    PF keys 21 through 30 are obtained by pressing both the Ctrl key
       and one of keys F1 through F10.

F31-F40    PF keys 31 through 40 are obtained by pressing both the Alt key
       and one of keys F1 through F10.

The expression expr is always evaluated with a radix of 10, regardless of
the current default radix for numbers.

Example:
  DBG>set pfkey 1 go/keep

In the above example, function key F1 is defined with a go/keep command.
Each time the F1 key is pressed, VIDEO will execute this command.  This form
of the "go" command keeps any temporary break point that may have been
specified in a previous "go" command.

Example:
  DBG>set pf 1 {go/keep;?ax}

The above example is similar to the previous except that a second command
has been added.  Now, whenever F1 is pressed, two commands will be executed.
When a break point occurs, the contents of the AX register are displayed in
the Dialogue window.  This example demonstrates the importance of the
braces.

Example:
  DBG>set pf 1 go/keep;?ax

If omitted as shown above, VIDEO will first execute a Set command and then
it will execute a Print (?) command.  This is equivalent to issuing the two
commands on two separate command lines.

Example:
  DBG>set pf 1 go/keep
  DBG>?ax

Example:
  DBG>/k1=-1
  DBG>set pf 1 if ++k1%3==0{<src}{if k1%3==1{<asm}{<mix}}

The user-defined symbol k1 is set to -1 and programmable function key 1 is
assigned a command which may be used to cycle through each one of the
"src.dbg", "asm.dbg" and "mix.dbg" command files.

Example:
  DBG>set pf 1

The current assignment to programmable function key 1 is removed.



Default Numeric Radix and Specifiers
════════════════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Radix expr | ("/"radix_spec [expr])                   │
└──────────────────────────────────────────────────────────────────────────┘

This command may be used to define both the default radix of numbers entered
by the user and what character strings are to be interpreted as radix
specifiers.  The expression expr is always evaluated with a radix of 10,
regardless of the current default radix for numbers.



Setting Default Radix
═════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Radix expr                               │
└──────────────────────────────────────────────────────────────────────────┘

Example:
  DBG>set radix 10
  DBG>set radix 16
  DBG>set radix 8

The above examples illustrate the setting of a default radix for numeric
values input by the user.  In the first example, we set the default radix to
decimal (i.e., base 10); in the second example, to hexadecimal (i.e., base
16); and in the third example, to octal (i.e., base 8).  The minimum radix
that you may specify is 2 and the maximum is 36.  The digits that may be
used to form numeric values are taken from the set of digits (0-9) and the
letters of the alphabet (A-Z or a-z).

Suppose that the default radix was set to 36.  In terms of decimal values,
'A' represents the value 10, 'B' represents the value 11, and so on up to
'Z' which represents the value 35.

In the absence of a radix specifier, only characters which are valid for the
default radix may appear in a numeric value.  For example, if the default
radix is 16 then you cannot use the letters 'G' through 'Z'.

When a numeric constant could legitimately be interpreted as a symbol name,
VIDEO will first try to find a symbol by that name and, if the search was
unsuccessful, it will treat the string as a constant.

Example:
  DBG>/abc=1
  DBG>?abc

In the above example, the user defines a variable called "abc" and assigns
it the value 1.  In the second statement, the debugger is asked to print the
value of "abc".  If the default radix was 16, this could represent a numeric
value (10*16**2 + 11*16 + 12).    However, VIDEO will first attempt to locate
the symbol "abc".  Since this will succeed, the value displayed in the
Dialogue window is 1.  Note that we could quite easily form a numeric
constant by preceding the letters by a '0' digit.

Example:
  DBG>?0abc

Any time a constant begins with one of the digits '0' through '9', VIDEO
will interpret the item as a numeric value.  Thus a symbol name must not
begin with one of the numeric digits (0-9).



Setting A Radix Specifier
═════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Radix "/"radix_spec [expr]                       │
└──────────────────────────────────────────────────────────────────────────┘

The second feature of the Set Radix command is the ability to define one or
more radix specifiers.

Example:
  DBG>set radix /0x 16

In the above example, the string "0x" is defined to introduce hexadecimal
(base 16) numbers.  Thus 0x12 represents a hexadecimal constant.

If the expression is omitted then the string is removed from the set of
current defined radix specifiers.

Example:
  DBG>set radix /0x

In the above example, the string "0x" is removed from the set of radix
specifiers.  Now 0x12 is an illegal construct.

Example:
  DBG>set radix /# 10

In the above example, the string "#" is defined to introduce decimal (base
10) numbers.  Thus #12 represents a decimal constant.

By defining a selection of radix specifiers, we can enter numeric values in
any radix of our choosing and remain independent of the current default
radix.



Source File Search Patterns
═══════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set SOurce [/Add] { {char} "*" {char} }                   │
└──────────────────────────────────────────────────────────────────────────┘

This command is used to define patterns to be applied to module names when
VIDEO searches for a corresponding source file.  VIDEO will first attempt to
open the source file by using the file specification used to compile the
file.  We require a mechanism for specifying other candidates for the source
file in the following cases.

  1. A relative path specification was given at compile time and the
    directory from which you are running the program is different from the
    directory from which the file was compiled.
  2. The source file has been moved to a different directory since it was
    compiled.

The following examples use file name specifications from DOS, MS Windows or
OS/2.  To construct equivalent QNX examples, the path separator "\" should
be replaced by "/" and all file specifications should be in lowercase
letters.

Suppose the current directory is "\TEST\O" and the source file ("HELLO.C")
is contained in the directory "\TEST\C".  Suppose we use the following
command to compile "HELLO.C".

Example:
  C>wcc ..\c\hello -d2

The compiler will place the string "..\C\HELLO.C" in the object file.
Suppose that we move up a level in the directory and link our program.    We
then use VIDEO to load and run the program while in the "\TEST" directory.
The debugger will not be able to locate the source file since it will use
the file specification "..\C\HELLO.C".

Example:
  DBG>set source *.c

In the above example, we specify that VIDEO should also try to locate a
source file by appending ".c" to the module name.  The asterisk is used as a
place holder for the module name.  The module name in the previous example
is "HELLO".  Thus, after unsuccessfully trying to locate "..\C\HELLO.C", an
attempt will be made to locate the file "HELLO.C".  This attempt will also
fail.

Example:
  DBG>set source \test\c\*.c

In the above example, we revise the pattern to include the path
specification for the source file.  Now an attempt will be made to locate
the file "\TEST\C\HELLO.C" and this attempt will succeed.

Example:
  DBG>set source *.c \test\c\*.c

In the above example, we add a second pattern to the list of possible names
for the source file.  If VIDEO is unsuccessful at locating the source file
in the current directory as "HELLO.C", it will also try "\TEST\C\HELLO.C" as
a possibility.

To indicate that we wish to add more patterns to the currently defined
pattern set, we can specify the /Add qualifier.  Without this qualifier,
VIDEO will replace the current pattern set with the one that we specify.
The following example is equivalent to the previous one.

Example:
  DBG>set source *.c
  DBG>set source /add \progs\src\*.c

Under QNX, a path specification that begins with a "/" could be interpreted
as a qualifier.

Example:
  DBG>set source /users/fred/*.c

In the above example, the "/users" qualifier is not supported and an error
will result.  To resolve this conflict, the local file specifier prefix "@l"
can be used.

Example:
  DBG>set source @l/users/fred/*.c

Local and remote file specifier prefixes are described under the topic
entitled "REMOTE_DEBUGGING".



Symbol Name Pattern Matching
════════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set SYmbol [/Add] {[/(Respect | Ignore)] {char} "*" {char}}           │
└──────────────────────────────────────────────────────────────────────────┘

This command is used to control the manner in which VIDEO will look up a
symbol.  By default, symbol names match if they agree in case (both upper
and lower case characters) and in spelling.  This command can be used to
loosen those restrictions.

Language compilers often prefix or suffix a user-defined global symbol with
one or more special characters such as underscores "_" or currency symbols
"$".  Sometimes all the characters in the name are converted entirely to
upper case or lower case.  To simplify the specification of symbol names,
you can define a series of patterns which VIDEO will use when looking up a
symbol.

Example:
  DBG>set symbol *_

The above pattern indicates that an underscore could be suffixed to the name
you specify.  For example, main might actually be spelled main_.  The
asterisk is used as a place holder for the user-specified name.

We can specify several patterns.

Example:
  DBG>set symbol *_ _*

In this example, we are stating that possible alternatives for the spelling
of main are main_ and _main.  VIDEO will search for a symbol by using the
specified patterns.  Patterns are processed in the order they were given.
If no patterns exist, VIDEO will look for an exact match.

Curly braces may be used to delimit a pattern.

Example:
  DBG>set symbol {*_} {_*}

Within braces, space characters are significant.  Therefore, you would
normally not include them except in the rare case where symbol names could
contain space characters.

To indicate that we wish to add more patterns to the currently defined
pattern set, we can specify the /Add qualifier.  Without this qualifier,
VIDEO will replace the current pattern set with the one that we specify.

To indicate whether the case of the name is important in the process of
looking up the name, we can specify one of /Respect or /Ignore in front of
the list of patterns.

Example:
  DBG>set symbol /ignore *_ _*

In the above example, we indicate for each pattern substitution that the
case of the name is not important.  In this case, the user-specified name
main could match many possible spellings such as main_, Main_, MAIN_, _MaiN,
and so on.

In the previous example, we did not include MAIN as a possible match for the
user-specified main.  To include this case, we could issue the following
command:

Example:
  DBG>set symbol /add /ignore *

VIDEO will now also look for an exact spelling with no regard to case.

We could invent more complicated rules for pattern matching based on case.

Example:
  DBG>set symbol /ignore * *_ _* /respect _*_

In the above example, we indicate for the first three patterns that the case
of the name is not important but that the case must match for the last
pattern.  If the user-specified name is cmain and the actual spelling is
_CMAIN_ then the debugger will not produce a match.  However, if the user
specified CMAIN then the debugger would match it with _CMAIN_.



Setting the Tab Interval
════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Tab expr                                   │
└──────────────────────────────────────────────────────────────────────────┘

This command controls how the debugger will display text files with embedded
TAB characters.  A TAB character causes the text following it to start at
the next tab stop.  By default, tab stops are set for every 8 columns.    You
can alter this default using the Set Tab command.

Example:
  DBG>set tab 4

The above example will set tab stops for every 4 columns.

The command show set tab will show the current value.



Source and Assembly Window Line Context
═══════════════════════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ Set Visible Source | Assembly [top][,[bot],[bias]]               │
└──────────────────────────────────────────────────────────────────────────┘

This command controls how the debugger will display source text in the
Source window or assembly code in the Assembly window.    In these two
windows, the debugger can be instructed to leave so many lines above (top)
and below (bot) the current line when scrolling text or assembly lines.  The
debugger can also be instructed to display lines beginning at some column
other than 1 (bias).

Example:
  DBG>set visible source 1,2,9

In the above example, the debugger is instructed to display at least one
line above the current line, to display at least 2 lines below the current
line, and to not display the first 8 columns of source text.  If the window
is too small for the debugger to adhere to these constraints, it will do the
best it can.

The command "show set visible" will show the current settings for the Source
and Assembly windows.
::::SHOW
┌──────────────────────────────────────────────────────────────────────────┐
│ SHow                                       │
│     Calls   [expr]                               │
│     Display {window_name}                           │
│     Flip                                   │
│     Modules [name]                               │
│     Paint   {window_name}                           │
│     Set     {Assembly | Bell | Call | Dclick | Fpu | Implicit |       │
│          INput | LAnguage | Level | MAcro | Menu | Pfkey |        │
│          Radix | SOurce | SYmbol | Tab | Visible}               │
└──────────────────────────────────────────────────────────────────────────┘

The SHow command may be used to display information about the currently
executing application and various VIDEO settings.



Show Calling Sequence
═════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ SHow Calls [expr]                               │
└──────────────────────────────────────────────────────────────────────────┘

This command is used to display an execution trace-back of the calling
sequence.  In order to display the execution trace-back, local symbol
information is required for all functions in the trace-back.  VIDEO will
list all functions up to the first for which no local symbol information is
available.  For information on generating local symbol information, see the
book entitled "WATCOM Linker User's Guide" ("The DEBUG Directive").

If an expression is specified, it is evaluated and only that many levels of
the calling sequence are displayed.

In the following example, we show a calling sequence in the C "Calendar"
program.

Example:
  DBG>show calls
  at          PosCursor+32(calendar@160)
  called from Line+68(calendar@147)
  called from Box+39(calendar@121)
  called from Calendar+43(calendar@79)
  called from main+70(calendar@40)

In the following example, we show a calling sequence in the FORTRAN 77
"Calendar" program.

Example:
  DBG>show calls
  at          POSCURSOR+22(calendar@149)
  called from LINE+234(calendar@124)
  called from BOX+65(calendar@101)
  called from CALENDAR+107(calendar@63)
  called from FMAIN+120(calendar@22)
  DBG>log



Show Window Settings
════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ SHow Display {window_name}                           │
└──────────────────────────────────────────────────────────────────────────┘

This command is used to display the settings for all or some windows.  The
valid window names are:

  Assembly
  Command
  Dialogue
  Fpu
  Memory
  Prompt
  Register
  SOurce
  STack
  Thread

Example:
  DBG>show display assembly register
  display assembly /open {Assembly: *} 20,24,1,80
  display register /close {CPU} 3,22,72,80

If no window name is specified then the settings for all windows are
displayed.



Show Flip Setting
═════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ SHow Flip                                   │
└──────────────────────────────────────────────────────────────────────────┘

This command is used to show the current setting for screen flipping.  See
the description of the Flip command for more information.



Show Module Names
═════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ SHow Modules [name]                               │
└──────────────────────────────────────────────────────────────────────────┘

This command is used to display the names of modules in the current
application.  If name is specified, only those module names that begin with
"name" are displayed.

Example:
  DBG>show module fp
  FPRTF FPUTC

In the above example, any module names that begin with the letters "fp" are
displayed in the Dialogue window.



Show Window Attributes
══════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ SHow Paint {window_names}                           │
└──────────────────────────────────────────────────────────────────────────┘

This command is used to display the settings of attributes for all or some
windows.  The valid window names are:

  Assembly
  Command
  Dialogue
  Fpu
  Memory
  Prompt
  Register
  SOurce
  STack
  Thread

If no window name is specified then the settings of attributes for all
windows are displayed.    To display a subset, specify only those window names
in which you are interested.

Example:
  DBG>show paint source dialogue
  paint source    plain cyan,black
  paint source    active black,cyan
  paint source    standout brown,black
  paint source    title bright brown,black
  paint source    gadget black,white
  paint dialogue  plain white,black
  paint dialogue  active bright brown,black
  paint dialogue  standout bright magenta,black
  paint dialogue  title bright brown,black
  paint dialogue  gadget black,white



Show Debugger Settings
══════════════════════
┌──────────────────────────────────────────────────────────────────────────┐
│ SHow Set {item_names}                            │
└──────────────────────────────────────────────────────────────────────────┘

This command is used to display the current settings of various VIDEO
parameters.  Valid item names are:

  Assembly
  Bell
  Call
  Dclick
  Fpu
  Implicit
  INput
  LAnguage
  Level
  MAcro
  Menu
  Pfkey
  Radix
  SOurce
  SYmbol
  Tab
  Visible

If no argument is specified then all settings are displayed.  To display a
subset, specify only those items in which you are interested.

Example:
  DBG>show set pfkey radix
  set pfkey 1 {help}
  set pfkey 4 {if !?_dbg@pf_4 {/_dbg@pf_4=0};
      if (++_dbg@pf_4)&1 {disp fpu /o} {disp fpu /c}}
  set pfkey 5 {reg -1}
  set pfkey 6 {reg +1}
  set pfkey 7 {/++_dbg@dbg$wind_split;<wind}
  set pfkey 8 {if !?_dbg@pf_8 {/_dbg@pf_8=0};
      if (++_dbg@pf_8)&1 {set menu off;<wind}
      {set menu on;<wind}}
  set pfkey 9 {set input source}
  set pfkey 10 {set input assembly}
  set radix /0n 10
  set radix /0x 16
  set radix /0 8
  set radix 10

In the above example, the current settings of the programmable function keys
and the default radix and radix specifiers are displayed.

::::SUMMARY
BREAK       - set a break point
CALL       - call a routine
DISPLAY    - create and remove VIDEO windows
DO       - assign values to variables, registers, etc.
ERROR       - report an error to the screen
EXAMINE    - examine memory contents
FLIP       - flip to the application's output screen
GO       - resume execution
HELP       - request the interactive help facility
IF       - conditionally execute one or more VIDEO commands
INVOKE       - execute a VIDEO command file
LOG       - log VIDEO output to a file
MODIFY       - modify memory locations
NEW       - reload a task, respecify the command line, or redirect the
       standard input and output files
PAINT       - establish colour attributes for VIDEO windows
PRINT       - display variable contents
QUIT       - quit debugging the application and leave VIDEO
REGISTER   - restore a specific register set
REMARK       - document a VIDEO command file
SET       - establish various VIDEO operating parameters (disassembly
       format, warning bell, "Call" command conventions, mouse double
       click rate, math coprocessor display, command file invocation,
       current window, expression grammar, language level, macro hot
       keys, menu display, programmable function keys, numerical radix,
       source file location and naming patterns, symbol name case
       sensitivity and naming conventions, source file tab expansion
       factor, source and assembly window text display boundaries)
SHOW       - show various VIDEO operating parameters
SYSTEM       - invoke a subprocess from within VIDEO
THREAD       - manipulate the threads of execution of a multi-threaded
       application under OS/2 or NetWare 386
TRACE       - trace program execution one statement at a time
VIEW       - examine the contents of a file
WATCH       - request VIDEO to watch for changes to a variable or memory
       location
WHILE       - execute one or more VIDEO commands while an expression is true
::::SYMBOLS
VIDEO defines a number of symbols which have special meaning.  Each of the
registers is designated by a special name.

eax       32-bit EAX register (32-bit mode only)
ax       16-bit AX register
al       8-bit AL register
ah       8-bit AH register
ebx       32-bit EBX register (32-bit mode only)
bx       16-bit BX register
bl       8-bit BL register
bh       8-bit BH register
ecx       32-bit ECX register (32-bit mode only)
cx       16-bit CX register
cl       8-bit CL register
ch       8-bit CH register
edx       32-bit EDX register (32-bit mode only)
dx       16-bit DX register
dl       8-bit DL register
dh       8-bit DH register
eip       Instruction pointer register (32-bit mode only)
ip       Instruction pointer register
esi       Source index register (32-bit mode only)
si       Source index register
edi       Destination index register (32-bit mode only)
di       Destination index register
esp       Stack pointer register (32-bit mode only)
sp       Stack pointer register
ebp       Base pointer register (32-bit mode only)
bp       Base pointer register
cs       Code segment register
ds       Data segment register
es       Extra segment register
fs       Segment register (32-bit mode only)
gs       Segment register (32-bit mode only)
ss       Stack segment register
fl       Flags register
efl       Flags register (32-bit mode only)
fl.flg_bit_name Individual bits in Flags register

         flg_bit_name ::= "c" | "p" | "a" | "z" | "s" | "i" | "d" | "o"

efl.flg_bit_name Individual bits in Flags register

         flg_bit_name ::= "c" | "p" | "a" | "z" | "s" | "i" | "d" | "o"

       The following table lists the full name for each of the flags
       register bits:

       fl.o, efl.o overflow flag
       fl.d, efl.d direction flag
       fl.i, efl.i interrupt flag
       fl.s, efl.s sign flag
       fl.z, efl.z zero flag
       fl.a, efl.a auxiliary carry flag
       fl.p, efl.p parity flag
       fl.c, efl.c carry flag

st0 - st7  Numeric Data Processor registers (math coprocessor registers)
cw       NDP control word (math coprocessor control word)
cw.cw_bit_name Individual bits in the control word

         cw_bit_name ::= "ic" | "rc" | "pc" | "iem" | "pm" |
                     "um" | "om" | "zm" | "dm" | "im"

       The following table lists the full name for each of the control
       word bits:

       cw.ic      infinity control

            0 = projective
            1 = affine

       cw.rc      rounding control (2 bits)

            00 = round to nearest or even
            01 = round down (towards negative infinity)
            10 = round up (towards positive infinity)
            11 = chop (truncate toward zero)

       cw.pc      precision control (2 bits)

            00 = 24 bits
            01 = reserved
            10 = 53 bits
            11 = 64 bits

       cw.iem     interrupt enable mask (8087 only)

            0 = interrupts enabled
            1 = interrupts disabled (masked)

       cw.pm      precision (inexact result) mask
       cw.um      underflow mask
       cw.om      overflow mask
       cw.zm      zero-divide mask
       cw.dm      denormalized operand mask
       cw.im      invalid operand mask

sw       NDP status word (math coprocessor status word)
sw.sw_bit_name Individual bits in the status word

         sw_bit_name ::=  "b" | "c3" | "st" | "c2" | "c1" |
                     "c0" | "es" | "sf" | "pe" | "ue" |
                     "oe" | "ze" | "de" | "ie"

       The following table lists the full name for each of the status
       word bits:

       sw.b       busy
       sw.c3      condition code bit 3
       sw.st      stack stop pointer (3 bits)

            000 = register 0 is stack top
            001 = register 1 is stack top
            010 = register 2 is stack top
                .
                .
                .
            111 = register 7 is stack top

       sw.c2      condition code bit 2
       sw.c1      condition code bit 1
       sw.c0      condition code bit 0
       sw.es      error summary (287, 387 only)
       sw.sf      stack fault (387 only)
       sw.pe      precision (inexact result) exception
       sw.ue      underflow exception
       sw.oe      overflow exception
       sw.ze      zero-divide exception
       sw.de      denormalized operand exception
       sw.ie      invalid operation exception

VIDEO permits the manipulation of register contents using any of the
operators described under the topics "C_OPERATORS" or "F77_OPERATORS".    By
default, these predefined names are accessed just like any other variables
defined by the user or the application.  Should the situation ever arise
where the application defines a variable whose name conflicts with that of
one of these debugger variables, the module specifier _dbg may be used to
resolve the ambiguity.    For example, if the application defines a variable
called cs then _dbg@cs can be specified to resolve the ambiguity.  The
"_dbg@" prefix indicates that we are referring to a VIDEO defined symbol
rather than an application defined symbol.

The flags register, the NDP control word, and the NDP status word can be
accessed as a whole or by its component status bits.

Example:
  /fl.c=0
  /cw.um=0
  ?sw.oe

In the above example, the "carry" flag is cleared, the NDP underflow mask of
the control word is cleared, and the NDP overflow exception bit of the
status word is printed.

The low order bit of the expression result is used to set or clear the
specified flag.

Example:
  fl.c=0x03a6

In the above example, the "carry" flag is cleared since the low order bit of
the result is 0.

VIDEO also defines some other special names.

dbg$32       This debugger symbol represents the mode in which the processor
       is running.

       0          16-bit mode
       1          32-bit mode

dbg$bottom This debugger symbol represents the number of the last line on
       the screen which may be used for windows (see also dbg$top,
       dbg$left, dbg$right).

dbg$bp       This debugger symbol represents the register pair SS:BP (16-bit
       mode) or SS:EBP (32-bit mode).

       Example:
         ? dbg$bp

dbg$code   This debugger symbol represents the current code location under
       examination.  The dot address "." is either set to dbg$code or
       dbg$data, depending on whether you were last looking at code or
       data.

dbg$cpu    This debugger symbol represents the type of central processing
       unit which is in your personal computer system.

       0          Intel 8088, 8086 or compatible processor
       1          Intel 80188, 80186 or compatible processor
       2          Intel 80286 or compatible processor
       3          Intel 80386 or compatible processor
       4          Intel 80486 or compatible processor

dbg$ctid   This debugger symbol represents the identification number of the
       current execution thread.  Under DOS and QNX, the current thread
       ID is always 1.  The current execution thread can be selected
       using the Thread window or the Thread command.

dbg$data   This debugger symbol represents the current data location under
       examination.  The dot address "." is either set to dbg$code or
       dbg$data, depending on whether you were last looking at code or
       data.

dbg$etid   This debugger symbol represents the identification number of the
       thread that was executing when the debugger was entered.  Under
       DOS and QNX, the executing thread ID is always 1.

dbg$fpu    This debugger symbol represents the type of numeric data
       processor (math coprocessor) that is installed in your personal
       computer system.

       -1          An 80x87 emulator is installed
       0          No coprocessor is installed
       1          An Intel 8087 is installed
       2          An Intel 80287 is installed
       3          An Intel 80387 is installed
       4          An Intel 80486 processor, supporting coprocessor
              instructions, is installed

dbg$ip       This debugger symbol represents the register pair CS:IP (16-bit
       mode) or CS:EIP (32-bit mode).

       Example:
         ? dbg$ip

dbg$left   This debugger symbol represents the number of the first column on
       the screen which may be used for windows (see also dbg$right,
       dbg$top, dbg$bottom).

dbg$monitor This debugger symbol represents the type of monitor adapter
       which is in use.

       0          IBM Monochrome Adapter
       1          IBM Colour Graphics Adapter (CGA)
       2          IBM Enhanced Graphics Adapter (EGA)
       3          IBM Video Graphics Array (VGA)

dbg$os       This debugger symbol represents the operating system that is
       currently running the application.

       1          DOS
       2          OS/2
       3          386|DOS-Extender from Phar Lap Software, Inc.
       4          OS/386 from ERGO Computing, Inc.
       5          NetWare 386 from Novell, Inc.
       6          QNX from Quantum Software Systems Ltd.
       7          DOS/4GW from Rational Systems, Inc.  (included in the
              WATCOM C/386 and WATCOM FORTRAN 77/386 packages)
       8          Microsoft Windows from Microsoft Corporation
       9          PenPoint from GO Corporation

dbg$pid    (OS/2, NetWare 386, QNX only) This debugger symbol contains the
       process identification value for the program being debugged.

dbg$psp    (DOS only) This debugger symbol contains the segment value for
       the DOS "program segment prefix" of the program being debugged.

dbg$radix  This debugger symbol represents the current default numeric
       radix.

dbg$remote This debugger symbol is 1 if the "REMotefiles" option was
       specified and 0 otherwise.

dbg$right  This debugger symbol represents the number of the last column on
       the screen which may be used for windows (see also dbg$left,
       dbg$top, dbg$bottom).

dbg$sp       This debugger symbol represents the register pair SS:SP (16-bit
       mode) or SS:ESP (32-bit mode).

       Example:
         ? dbg$sp

dbg$top    This debugger symbol represents the number of the first line on
       the screen which may be used for windows (see also dbg$left,
       dbg$right, dbg$bottom).

dbg$view   This debugger symbol is set by the View command.  It represents
       the segment and offset of the code corresponding to the line
       where the cursor was last positioned when viewing a module of the
       current application.  This variable has several uses.  For
       example, it can be used in a Break command to set a break point.

       Example:
         break dbg$view
::::SYSTEM
┌──────────────────────────────────────────────────────────────────────────┐
│ SYstem[/(Remote | Local)] [ system_cmd | "{" system_cmd "}" ]        │
│ !                                       │
└──────────────────────────────────────────────────────────────────────────┘

The SYstem or !  command may be used to run other commands or programs
without destroying the debugging environment.  If system_cmd is entered,
that command is executed by the operating system and control returns to
VIDEO.

If system_cmd is omitted, the operating system command interpreter or shell
is invoked.  Commands may be entered until an "exit" command is entered.
The shell is terminated and control returns to the debugger.

The /Remote and /Local qualifiers may be specified when using the remote
debugging feature.  If the /Remote qualifier is specified, the command is
run on the task machine.  If the /Local qualifier is specified, the command
is run on the debugger machine.  If neither qualifier is specified then
"local" is assumed unless the Remotefiles option was specified on the
command line.  For more information on remote debugging, see the topic
entitled "REMOTE_DEBUGGING".

Under QNX, a path specification that begins with a "/" could be interpreted
as a qualifier.

Example:
  DBG>system /users/fred/myapp

In the above example, the "/users" qualifier is not supported and an error
will result.  To resolve this conflict, the /Local qualifier must be used.

Example:
  DBG>system/local /users/fred/myapp

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  There must be enough unused memory in the computer to run the         │
│ specified program or shell.  Under DOS, the program being debugged must    │
│ have released some memory back to the system so that there is room to load │
│ system_cmd.  For DOS, you can use the "RESIZE" command file to set the     │
│ size of the memory control block containing the Program Segment Prefix     │
│ (PSP) of the program being debugged.    See the topic entitled             │
│ "COMMAND_FILES" for more information on this command file.             │
│                                         │
│ You can also use the VIDEO "Checksize" option.  See the topic entitled     │
│ "DOS_STARTUP" for more information on this option.                 │
└────────────────────────────────────────────────────────────────────────────┘

Example:
  DBG>system c:\cmds\cset.com

In the above DOS example, the program "CSET.COM" is invoked from the "C"
disk and directory "\CMDS".

Example:
  DBG>system

The command shell is invoked.  The shell will not return to the debugger
until an "exit" command is executed.

Example:
  DBG>sys chdir \asmsrc

For DOS only, the shell is invoked to change the current directory to
"\ASMSRC".  Control is then immediately returned to VIDEO.

Example:
  DBG>! edit hello.c

An editor is invoked to edit the file "hello.c".  Corrections to the C
source code could be applied while the "HELLO" program is being debugged.
When the editor exits, control is returned to VIDEO.

Example:
  DBG>! edit fftc.for

An editor is invoked to edit the file "fftc.for".  Corrections to the
FORTRAN source code could be applied while the "FFTC" program is being
debugged.  When the editor exits, control is returned to VIDEO.
::::THREAD
┌──────────────────────────────────────────────────────────────────────────┐
│ THread                                   │
│ ~                                       │
│      /Change   [id_num]                           │
│      /Freeze   [id_num] | ["*"]                       │
│      /Show     [id_num] | ["*"]                       │
│      /Thaw     [id_num] | ["*"]                       │
└──────────────────────────────────────────────────────────────────────────┘

The THread or ~ command is used to manipulate the threads of execution of a
multi-threaded application under OS/2 or NetWare 386.  An execution thread
may be selected for examination by VIDEO (/Change), an execution thread may
be made not runnable (/Freeze), an execution thread may be made runnable
(/Thaw), or the status of execution threads may be displayed (/Show).

In an application that has multiple threads of execution, a particular
thread may be selected for examination by specifying its thread
identification number or thread ID using the Change option.

Example:
  00001>thread/change 2

In the above example, execution thread "2" is selected using the Change
option.  The debugger prompt will change to "00002" if an execution thread,
whose ID is "2", exists.  Other windows on the screen will change to reflect
the selection of another execution thread.  In particular, any Assembly,
Source, FPU, and Register windows that are present on the screen will
change.

The Change option need not be specified since it is the default when only a
thread ID is specified.

Example:
  00001>thread 2

In the above example, execution thread "2" is selected.

A particular thread may be "frozen" (i.e., made not runnable) by specifying
its thread ID using the Freeze option.

Example:
  00002>thread/freeze 3

In the above example, execution thread "3" is made not runnable.

All threads may be frozen by specifying "*" for the thread ID.

Example:
  00002>~/f *

The current thread may be frozen by omitting the thread ID.

Example:
  00002>thread/freeze

A particular thread may be "thawed" (i.e., made runnable) by specifying its
thread ID using the Thaw option.

Example:
  00002>thread/thaw 3

In the above example, execution thread "3" is made runnable.

All threads may be thawed by specifying "*" for the thread ID.

Example:
  00002>thread/thaw *

The current thread may be thawed by omitting the thread ID.

Example:
  00002>~/th

The status of a particular thread may be displayed by specifying its thread
ID using the Show option.

Example:
  00002>thread/show 1

In the above example, the status of execution thread "1" is displayed.

The status of all threads may be displayed by specifying "*" for the thread
ID.

Example:
  00002>th/sh *

Alternately, the status of all threads may be displayed by specifying the
Thread command without any arguments.

Example:
  00002>thread

The status of the current thread may be displayed by specifying Show and
omitting the thread ID.

Example:
  00002>~/s
::::TRACE
┌──────────────────────────────────────────────────────────────────────────┐
│ Trace                                    │
│     [/Assembly] [/Over | /Into | /Next] [start_addr_expr]           │
│     [/Mix]        [/Over | /Into | /Next] [start_addr_expr]           │
│     [/Source]   [/Over | /Into | /Next] [start_addr_expr]           │
└──────────────────────────────────────────────────────────────────────────┘

The Trace command is used to step through the execution of a program.
Execution may be viewed one source line at a time (/Source), one assembly
instruction at a time (/Assembly), or a combination of both source and
assembly lines (/Mix).    The latter mode will display source lines when they
are available and switch to assembly instructions when source line
information is not available.

Source line numbers are displayed in the Source window when source line
information is included in the executable image (for additional information,
see the description of the compiler's "d1" option and the WATCOM Linker
"DEBUG" directive).  If the source file can be accessed then the
corresponding source text is also displayed.  For a discussion of how VIDEO
locates the source files that correspond to the modules in your application,
see the description of the Set Source command.

Assembly instructions are displayed in the Assembly window.

When source line information is available, both the Source and Assembly
windows are synchronized.

/Assembly [/Over | /Into | /Next] [start_addr_expr]
       VIDEO will trace execution of the application one assembly
       instruction at a time.

       Example:
         DBG>trace /assembly

/Mix [/Over | /Into | /Next] [start_addr_expr]
       VIDEO will trace execution of the application one source
       statement at a time, or one instruction at a time when no source
       text is available.

       Example:
         DBG>trace /mix

/Source [/Over | /Into | /Next] [start_addr_expr]
       VIDEO will trace execution of the application one source
       statement at a time.  Source line information must be available
       at the time that this command is issued.

       Example:
         DBG>trace /source

When none of the /Assembly, /Mix or /Source qualifiers is specified, VIDEO
will use a default trace mode.    Initially, the default is /Mix but this
default can be set with Set Level command.

By default, VIDEO will enter a tracing mode in which one source statement or
assembly instruction is executed each time one of the SPACE bar or "I" or
"N" keys is pressed.

If the SPACE bar is used to advance execution, the tracing of called
routines is skipped.  Tracing continues with the statement or instruction
following the routine invocation.

Example:
  C Programming Example
     8 int main()
     9   {
    10    printf( "Hello world\n" );
    11    return( 0 );
    12   }

  FORTRAN Programming Example
     8     PROGRAM DEMO
     9     EXTERNAL PRINTF
    10     CALL PRINTF( 'Hello world' )
    11     END

In the above example, we skip the trace of the execution of the "printf"
routine by pressing the SPACE bar when the "printf" statement is about to be
executed.

If the "I" or "into" key is used to advance execution, the execution of
called routines is traced.

Example:
  main_     mov    AX,0002
  main_+03    push   AX
  main_+04    call   printf
  main_+07    add    SP,2
  main_+0A    xor    AX,AX

In the above example, we can trace the execution of the "printf" routine by
pressing the "I" key when the "call" instruction at "main_+04" is about to
be executed.

The "N" or "next" key may be used to advance tracing to the next sequential
statement or instruction immediately following the current statement or
instruction.  In situations where you are at the bottom of a loop, this
permits you to skip over the tracing of statements or instructions which
might be repeated many times.

Example:
  _CSTART_+66    sub    SI,SI
  _CSTART_+68    cmp    BYTE PTR [SI],00
  _CSTART_+6B    movsb
  _CSTART_+6C  *jne    _CSTART_+68
  _CSTART_+6E    cmp    BYTE PTR [SI],00

In the above example, we can skip tracing of the loop from "_CSTART_+68" to
"_CSTART_+6C" by pressing the "N" key when the "jne" instruction at
"_CSTART_+6C" is about to be executed.    The "*" preceding the "jne"
indicates that the branch to "_CSTART_+68" will be taken.  The next
instruction to be traced will be the "cmp" at "_CSTART_+6E".

When using the "N" key, care must be taken to ensure that the execution path
will eventually reach the next statement or instruction.  If execution fails
to reach this point then the program may continue to execute until
completion.  This situation is akin to setting a break point at a statement
or assembly instruction which will never be executed and then issuing a Go
command.  In this situation, the application would execute to completion.

Tracing can be discontinued by pressing any other key.

The /Over, /Into and /Next modifiers may be used to continue execution to
the "next" statement or instruction after which VIDEO will prompt for
another command.  This is often referred to as "single-step" mode.

/Over       This qualifier may be used to continue execution to the "next"
       statement or assembly instruction.  If the current statement or
       instruction invokes a routine then the "next" statement or
       instruction is the one which follows the invocation of the
       routine.

/Into       This qualifier may be used to continue execution to the "next"
       statement or assembly instruction.  If the current statement or
       instruction invokes a routine then the "next" statement or
       instruction is the first one in the called routine.

/Next       This qualifier may be used to continue execution to the "next"
       statement or assembly instruction which immediately follows the
       current statement or instruction in memory.    If the current
       statement or instruction is one that branches, care must be taken
       to ensure that the execution path will eventually reach the
       statement or instruction which follows.  If execution fails to
       reach this point then the program may continue to execute until
       completion.
::::VIEW
┌──────────────────────────────────────────────────────────────────────────┐
│ View[/Binary]  [module_or_file_spec]                       │
└──────────────────────────────────────────────────────────────────────────┘

The View command invokes a simple file browser (i.e., you cannot make
changes to the file, only look at it).    If module_or_file_spec is not
specified then the current module name is assumed.

The argument module_or_file_spec is treated first as a possible module name
and then as a file name.  The debugger attempts to locate the source file
that corresponds to the module in the same manner as that used when
displaying source lines in the Source window.  VIDEO searches for the file
in the devices and paths that you specify in the Set Source command.

In cases where there is a conflict between a module name and a file name, a
drive (DOS, MS Windows, OS/2), path or file extension can be specified to
resolve the ambiguity.    For example, suppose that you had a data file called
"printf".  If you entered the command view printf then VIDEO would attempt
to locate the file "printf.c".    On the other hand, if you entered the
command view printf.  then VIDEO would attempt to locate the file "printf"
under DOS, MS Windows or OS/2.    Under QNX, you would enter the command view
./printf to view the file "printf".

If /Binary is specified then the file contents are displayed in hexadecimal
notation.  A file name must be specified when this qualifier is used.

The manipulation of the View window with keys and a mouse is described under
the topic entitled "WINDOWS".

Under QNX, a path specification that begins with a "/" could be interpreted
as a qualifier.

Example:
  DBG>view /users/fred/test.dat

In the above example, the "/users" qualifier is not supported and an error
will result.  To resolve this conflict, the local file specifier prefix "@l"
can be used.

Example:
  DBG>view @l/users/fred/test.dat

Local and remote file specifier prefixes are described under the topic
entitled "REMOTE_DEBUGGING".
::::WATCH
┌──────────────────────────────────────────────────────────────────────────┐
│ Watch                                    │
│     [/Set]       addr_expr [ cmd_list ]                   │
│     /Byte       addr_expr [ cmd_list ]                   │
│     /Word       addr_expr [ cmd_list ]                   │
│     /DWord       addr_expr [ cmd_list ]                   │
│     /Activate    "*" | index_expr | "/" addr_expr               │
│     /Deactivate  "*" | index_expr | "/" addr_expr               │
│     /Clear       "*" | index_expr | "/" addr_expr               │
└──────────────────────────────────────────────────────────────────────────┘

A watch point defines a memory location which, if modified, causes execution
of the application to suspend.    A watch point may be defined for:

/Byte       a byte (8 bits)

/Word       a word (16 bits), and

/DWord       a doubleword (32 bits)

/Set is implied when no other qualifier is specified.  If /Set or no
qualifier is specified, a watchpoint is set for a word or doubleword
depending on whether you are debugging a 16-bit or 32-bit application.    A
watchpoint may be removed with the /Clear qualifier.  Watchpoints may be
enabled with the /Activate qualifier or disabled with the /Deactivate
qualifier.  Up to 7 watch points may be defined.  When an instruction
modifies a location guarded by an active watch point, application execution
is suspended and the debugger is entered.

Example:
  DBG>watch/set _listhead
  DBG>watch _listhead

In the above example, two equivalent commands are shown.  A watch point is
defined and automatically activated for the 16-bit memory location defined
by the global symbol _listhead.  Only one watch point may be specified for a
particular location in memory.

A watch point may be specified in terms of a module name and symbol name.

Example:
  DBG>watch sort@_listhead

When the executing application modifies a memory location guarded by an
active watch point, application execution is suspended and the debugger is
entered.  If one or more debugger commands were specified when the watch
point was defined, the debugger commands are executed first.  The command
list that follows the address expression in the /Set, /Byte, /Word, or
/DWord qualifiers is defined as follows:

  cmd_list ::= "{" [cmd] { ";" [cmd] } "}"

This is simply a VIDEO command line placed inside of braces.

Notes:

  1. For a complete description of valid address expressions, see the
    chapter entitled "VIDEO Expression Handling".

  2. Execution of the application may be resumed if one of the commands was
    a Go command; otherwise the debugger prompts the user for a new command.

    Example:
      DBG>watch _listhead {if _listhead != 0 {go/keep}}

    Each time the "listhead" variable is modified, its value is compared
    with zero and execution is resumed only if the value is not zero.

  3. If no arguments are specified to the "Watch" command, the currently
    defined watch points will be displayed.  The first one shown is watch
    point number 1, the second one shown is watch point number 2, and so on.
    These are called the watch point indices.  Active watch points are shown
    in "active" attributes, inactive ones are shown in "plain" attributes.
    See the description of the Paint command for a discussion of attributes.

  4. When activating, deactivating or clearing a watch point, either the
    watch point index or the address must be specified.  If "*" is specified
    as the watch point index then all watch points are affected.

    Example:
      DBG>watch/set _listhead; watch/deac 1
      DBG>watch/set _listhead; watch/deac /_listhead

    In both examples, a watch point is set and then a watch point is
    deactivated.  In the first example, the watch point set for _listhead is
    deactivated only if no other watch points have been set (since it will
    then be watch point number 1).  The second example illustrates how the
    watch point for _listhead will be deactivated under any circumstances.

    Example:
      DBG>watch/activate 2; watch/deactivate 1

    Watch point number 2 is activated and 1 is deactivated.

  5. The specified address need not be the name of a symbol.

    Example:
      DBG>watch/byte es:di

    A watch point is set for the 8-bit location specified by the contents of
    the ES:DI register pair.

    Example:
      DBG>watch/deactivate /bx

    The watch point whose address is specified by the contents of the DS:BX
    register pair is deactivated.

  6. All watch points may be removed in a single command.

    Example:
      DBG>watch/clear *

    The asterisk refers to all watch points.
::::WHILE
┌──────────────────────────────────────────────────────────────────────────┐
│ WHile <expr> cmd_list                            │
└──────────────────────────────────────────────────────────────────────────┘

The WHile command permits execution of a list of commands while the
specified expression is true (i.e., evaluates to a non-zero result).  The
command list that follows the command is defined as follows:

  cmd_list ::= "{" [cmd] { ";" [cmd] } "}"

Example:
  DBG>/ax=0; while ax!=25 {/ax++;print ax}

The above example prints the numbers from 1 to 25 in the Dialogue window.
It first sets the AX register to 0.  While the content of the AX register is
not equal to 25, the debugger will increment the value in the AX register
and print the new value.

There are more complex scenarios in which the WHile command can be put to
good use.  For example, it could be used to follow a linked list which is
terminated by a NULL pointer.
::::WIN3_STARTUP
Debugging an application that is to run under Microsoft Windows can be done
in either of two ways.    You can run VIDEO on the same computer system that
will be used to run the application or you can use a second computer system.
This latter choice uses the "remote debugging" feature of VIDEO.  This is
described under the topic entitled "REMOTE_WIN3".



Installing the Windows Version of VIDEO
═══════════════════════════════════════
To use VIDEO, Microsoft Windows must be started in standard or enhanced mode.
When debugging 32-bit applications, you must include the "device"
specification listed below in the [386Enh] section of your Windows
"SYSTEM.INI" file.

  DEVICE=[d:]\WATCOM\BINW\WDEBUG.386

This device driver supports debugging of both 16-bit and 32-bit
applications.

You must include the Windows SDK file "WINDEBUG.DLL" in your path.  This
file is included in the WATCOM software package.

The following procedures will install VIDEO and the remote debugging servers
in the currently selected program group.  If you wish, you can create a new
program group for VIDEO and the remote debugging servers.

To install the Windows version of VIDEO, select the "New" entry of the
"File" menu of the Windows "Program Manager".  Select the "Program Item"
option.  For the "Description" field of the "Properties" window, enter the
name "VIDEO".  For the "Command Line" field, enter the full path
specification for "WVIDEOW.EXE".  Sample entries for the "Description" and
"Command Line" fields of the "Properties" window are shown in the following
illustration.

┌────────────────────────────────────────────────────────────────────────────┐
│ Description:      VIDEO                              │
│ Command Line:   E:\WATCOM\BINW\WVIDEOW.EXE                     │
└────────────────────────────────────────────────────────────────────────────┘

A lightning bolt icon for VIDEO will appear in the currently selected
program group.

The remote debugging servers, "PARSERVW.EXE" and "NETSERVW.EXE", can also be
installed at this time.

To install the parallel remote debugging server, select the "New" entry of
the "File" menu of the Windows "Program Manager".  Select the "Program Item"
option.  Sample entries for the "Description" and "Command Line" fields of
the "Properties" window are shown in the following illustration.

┌────────────────────────────────────────────────────────────────────────────┐
│ Description:      ParServer                             │
│ Command Line:   E:\WATCOM\BINW\PARSERVW.EXE                     │
└────────────────────────────────────────────────────────────────────────────┘

A lightning bolt icon for the parallel debugging server will appear in the
currently selected program group.

To install the NetBIOS remote debugging server, select the "New" entry of
the "File" menu of the Windows "Program Manager".  Select the "Program Item"
option.  Sample entries for the "Description" and "Command Line" fields of
the "Properties" window are shown in the following illustration.

┌────────────────────────────────────────────────────────────────────────────┐
│ Description:      NetServer                             │
│ Command Line:   E:\WATCOM\BINW\NETSERVW.EXE                     │
└────────────────────────────────────────────────────────────────────────────┘

A lightning bolt icon for the NetBIOS debugging server will appear in the
currently selected program group.


Local Debugging of Windows Applications
═══════════════════════════════════════
To start VIDEO, select the window in which you have installed VIDEO.  One of
the icons presented is used to start the debugger.  Double-click on the
VIDEO icon.

A prompt window will appear in which you will be required to enter a command
line that will be used to start the application.  The format of the command
line is described under the topic entitled "DOS_STARTUP".

You can make special versions of the VIDEO icon using the "Copy" and
"Properties" entries of the "File" menu of the Windows "Program Manager".
For example, you can add any options you wish to the "Command Line" field of
the "Properties" window.  Sample entries for the "Description" and "Command
Line" fields of the "Properties" window are shown in the following
illustration.

┌────────────────────────────────────────────────────────────────────────────┐
│ Description:      VIDEO/Custom                             │
│ Command Line:   E:\WATCOM\BINW\WVIDEOW.EXE /swap /reg=4             │
└────────────────────────────────────────────────────────────────────────────┘

When you click on the newly created icon, the options specified in the
"Command Line" field will be taken as defaults.  As long as no executable
file name was specified in the "Command Line" field, VIDEO will present its
prompt window.    In the prompt window, you can specify more options and an
executable file name.

If you are debugging the same program over and over again, you might wish to
create an icon that includes the name of the file you wish to debug in the
"Command Line" field.  Each time you click on that icon, VIDEO is started
and it automatically loads the program you wish to debug.
::::WIN3_WVIDEOW_ENVIRONMENT_VARIABLE
The WVIDEOW environment variable can be used to specify commonly used VIDEO
options.  If the specification of an option involves the use of an "="
character then the "#" character may be used in its place (this is required
by the syntax of the "SET" command).  These options are processed before
options specified on the command line.

Example:
  C>set wvideow=/swap/vga50/reg#4

The above examples illustrate how to define default options for the
debugger.

Once the WVIDEOW environment variable has been defined, those options listed
become the default each time VIDEO is invoked.
::::WINDOWS
Types of Windows
════════════════
Windows are rectangular areas on the screen which are devoted to displaying
a particular type of debugging information such as source lines, machine
language instructions, and register contents.  Not all windows need be
present on the screen.    Windows are placed on the screen with the VIDEO
Display command.  The same command can be used to remove windows from the
screen.  The attributes of lines displayed in a window are defined with the
VIDEO Paint command.

In the preceding illustration only the Source, Dialogue and Prompt windows
are shown.  The top line is the menu line.  The various types of windows are
described later under this topic.



Window Manipulation with Keys
═════════════════════════════
The window which contains the text cursor is called the "active" window.
The active window is the window that will respond to keystrokes.  In
general, keys such as the Cursor Up and Down keys perform similar functions
in all windows.  The following keys perform identical functions in all
windows.

Ctrl/Enter may be used to start a text selection process which will be
       concluded by the appearance of the Action window.  When text
       selection is started, a block cursor will appear on the screen.
       The cursor keys may be used to stretch the block cursor to the
       left, right, up and down, thereby highlighting a portion of the
       text visible on the screen.    The Ctrl/Cursor Left and Ctrl/Cursor
       Right keys extend the block cursor to the left or right by a
       token at a time.  A second press of the Ctrl/Enter key causes the
       Action window to pop up on the screen.

The following keys perform identical functions in all windows except the
View and Error windows.

Tab       may be used to move the text cursor to the next window on the
       screen.

Shift/Tab  (Backtab) may be used to move the text cursor to the previous
       window on the screen.

Escape       may be used to move directly to the Prompt window.

Ctrl/D       may be used to shift the entire active window down on the screen.

Ctrl/U       combination may be used to shift the entire active window up on
       the screen.

Ctrl/P       may be used to invoke the Paint menu for the active window.

Ctrl/Q       may be used to update the contents of the active window.

The following keys perform identical functions in all windows except the
Prompt, View and Error windows.

Ctrl/L       may be used to move the active window to the left.

Ctrl/R       may be used to move the active window to the right.

Ctrl/G       may be used to grow the size of the active window.

Ctrl/S       may be used to shrink the size of the active window.

Ctrl/N       may be used to narrow the size of the active window.

Ctrl/W       may be used to widen the size of the active window.

Ctrl/E       may be used to erase the active window from the display.

Ctrl/Z       may be used to zoom the active window between its normal size and
       the size of the entire screen.

Later sections describe in detail the responses to various keys when a
particular window is active.



Window Manipulation with a Mouse
════════════════════════════════
In order to use a mouse with VIDEO, you must install a mouse driver program.

Under DOS, you must install the IBM Mouse Driver program that is supplied
with the IBM Mouse.  Alternatively, you may use a mouse and mouse driver
that are compatible with the IBM Mouse and IBM Mouse Driver.  The IBM Mouse
Driver is installed by running the "MOUSE.COM" program.

Example:
  C>\dos\mouse

See your QNX manuals for further information on mouse installation.

VIDEO supports the use of a mouse in many ways.  Most actions are selected
by "clicking" the mouse at the desired location.  This is done by moving the
mouse cursor, the solid rectangle on the screen, to a place on the screen
and then pressing the left button on the mouse.

The mouse cursor can be positioned to any window.  In some windows, such as
the "Source" and "Assembly" windows, text may be scrolled up or down, left
or right, by "dragging" the mouse.  This is done by moving the mouse cursor
to a line in the window and, while pressing down the left button on the
mouse, repositioning the mouse cursor to another place in the window.

To scroll text up or down by dragging the mouse, vertical scrolling must be
enabled.  This is done by clicking the mouse on the scroll bar at the right
side of the window where the word "Locked" appears.  If the word "Locked"
does not appear then vertical scrolling is already enabled.  Vertical
scrolling can be enabled/disabled by clicking on the scroll bar again.

To scroll text left or right by dragging the mouse, horizontal scrolling
must be enabled.  This is done by clicking the mouse on the scroll bar at
the bottom of the window where the word "Locked" appears.  If the word
"Locked" does not appear then horizontal scrolling is already enabled.
Horizontal scrolling can be enabled/disabled by clicking on the scroll bar
again.

The entire window can be repositioned on the screen by dragging the window's
title line to a new place on the screen.

Some actions are accomplished by "double-clicking" the left mouse button.
Double-clicking is done by rapidly pressing the left mouse button twice at
the same location without moving the mouse cursor.  These actions are
described in subsequent sections.

Text selection may be started by pressing the right-hand mouse button.
Without releasing the button, the mouse cursor may be moved about the screen
to highlight a sequence of text (characters, words, expressions, etc.).
When the right-hand mouse button is released, the Action window appears on
the screen.  If the right-hand mouse button is pressed and released without
moving the mouse, the "item" under the mouse cursor is selected in its
entirety and the Action window appears on the screen.

When using a mouse, many windows have "gadgets".

  1. The "scroll up" () and "scroll down" () gadgets may be used to scroll
    text vertically.

  2. The "scroll left" () and "scroll right" () gadgets may be used to
    scroll text horizontally.

  3. The "page up" and "page down" gadgets (small triangle shapes at the
    right of the window) perform different actions depending on the window.

  4. The "page left" and "page right" gadgets (small triangle shapes at the
    bottom of the window) perform different actions depending on the window.

  5. The "window zoom" gadget (the  symbol, in the top, right corner
    of the window) may be used to zoom the active window between its normal
    size and the size of entire screen.

    If you place the mouse cursor on the "zoom" gadget and press the
    right-hand mouse button, the window will temporarily zoom to full size.
    When you release the button, the window will return to its normal size.

  6. The "window resize" gadget (double arrow, in the bottom, right corner)
    may be used to enlarge or shrink a window.

  7. The "window close" gadget (triple bar, in the top, left corner) may be
    used to remove a window from the screen.

If you click on a "scroll" or "page" gadget, the associated action is
performed once.  If you hold the left mouse button down while positioned on
one of these gadgets, the associated action is performed repeatedly.  If you
drag the "window resize" gadget, the window to which it belongs is grown or
shrunk.

Double-clicking on the title bar will cause the contents of the window to be
updated.



Action Window
═════════════
The debugger places this window on the screen after a text selection
sequence has been completed.  Using the keyboard, text selection is started
using the Ctrl/Enter key.  When the Ctrl/Enter key is pressed a second time,
the Action window appears on the screen.

Using the mouse, text selection is started when the right-hand mouse button
is pressed.  When the right-hand mouse button is released, the Action window
appears on the screen.

The entries in the Action window allow you to

  1. show the source code pertaining to the selected text,
  2. display the contents of the variable represented by the selected text,
  3. evaluate the selected text as an expression,
  4. examine the memory location represented by the selected text,
  5. set a break point at the location represented by the selected text,
  6. set a watch point on the location represented by the selected text, or
  7. copy the selected text to the Prompt window where it can be manipulated
    as part of some command.

When the "Show source" entry is selected, the source/assembly code
corresponding to the selected text is displayed in the Source and Assembly
windows (if present on the screen).

A line appears in the Dialogue window that indicates the address of the
previous source/assembly code and the new source/assembly code under
examination.

Example:
  0x65CB:0x0012 => ClearScreen

You can use this entry to return to the previous location by moving the text
cursor to the Dialogue window using the Tab keys and highlighting the
address that is displayed on the left of the "=>" using the Ctrl/Enter and
cursor keys.  You can also do this by pressing the right-hand mouse button,
highlighting the address that is displayed on the left of the "=>", and then
releasing the right-hand mouse button.    In the above example, this would be
the entry "0x65CB:0x0012" (the segment and offset of the previous location
under examination).



Assembly Window
═══════════════
The debugger displays assembly instructions for the current code location in
this window.  If the Code Segment and Instruction Pointer registers (CS:IP,
CS:EIP) point to an instruction visible in the Assembly window then the line
containing that instruction is displayed in "active" attributes.  When
examining assembly instructions, one line is designated as the current line
and is displayed in "standout" attributes.  The Source window, if present,
is kept synchronized with the Assembly window provided that source
information is available.



Manipulating the Assembly Window with Keys
──────────────────────────────────────────
When the text cursor is positioned in the Assembly window, the Cursor
Left/Right, Cursor Up/Down, Page Up/Down, Home, End, and Enter keys may be
used to move about.

Cursor Left/Right
       may be used to scroll the text in the window left or right when
       the cursor moves to the left or right edge of the window.

Ctrl/Cursor Left/Right
       may be used to scroll the text in the window left or right
       without moving the cursor.

Cursor Up/Down
       may be used to scroll up and down through assembly instructions.

Page Up/Down
       may be used to scroll up and down through assembly instructions
       in increments of the number of lines in the window minus two.

Home       may be used to move to the beginning of the current compilation
       unit.

End       may be used to move to the end of the current module (compilation
       unit).

Enter       may be used to move directly to the assembly instruction
       referenced by the CS:IP (16-bit mode) or CS:EIP (32-bit mode)
       register pair.



Manipulating the Assembly Window with a Mouse
─────────────────────────────────────────────
  1. Clicking in the Assembly window causes the text cursor to move to this
    window.  It becomes the "active" window.

  2. Assembly instructions may be scrolled up or down by dragging the mouse.
    To do this, the right-side scrolling bar must be unlocked.

  3. Assembly instructions may be scrolled left or right by dragging the
    mouse.  To do this, the bottom scrolling bar must be unlocked.

  4. Gadgets are provided for scrolling, resizing, zooming and closing the
    Assembly window.

  5. The "scroll up" and "scroll down" gadgets may be used to move up and
    down through text lines.  When the text cursor moves to the top or
    bottom of the window, text will be scrolled down or up.

  6. The "scroll left" and "scroll right" gadgets move the cursor one
    character left or right.  When the text cursor moves to the left or
    right edge of the window, text will be scrolled to the right or left.

  7. The "page up" and "page down" gadgets may be used to scroll up and down
    through assembly instructions in increments of the number of lines in
    the window minus two.

  8. Clicking on an assembly instruction in the Assembly window makes it the
    current assembly instruction.  This line is displayed in "standout"
    attributes.  The value of the VIDEO variable dbg$code changes to reflect
    the change in the current assembly instruction.  This variable reflects
    the segment:offset of the most recent code location to be examined.  In
    addition, the "." address is changed to point to the assembly
    instruction.  The "." address is used in many VIDEO commands.

    Example:
      do [CS IP] = .
      or
      do [CS EIP] = .

    In the above example, the contents of the CS:IP or CS:EIP register pair
    are modified to point to the current assembly instruction.

  9. Double-clicking on a line will set or clear a breakpoint at the
    assembly instruction.



Command Window
══════════════
The debugger will display output from one or more commands that can be bound
to this window.  In the illustration above, the sample command window is
titled "date/time structure".


Manipulating the Command Window with Keys
─────────────────────────────────────────
When the text cursor is positioned in the Command window, the Enter key may
be used to refresh the window.



Manipulating the Command Window with a Mouse
────────────────────────────────────────────
Clicking in the Command window causes the text cursor to move to the window
and the window to be refreshed.  It becomes the "active" window.



Dialogue Window
═══════════════
By default, the debugger displays responses to commands in this window.
When one of the other windows is not present on the screen, the output
normally destined for that window is displayed in the Dialogue window.



Manipulating the Dialogue Window with Keys
──────────────────────────────────────────
When the text cursor is positioned in the Dialogue window, the Cursor
Up/Down, Page Up/Down, Home, End, and Enter keys may be used to move about.

Cursor Left/Right
       may be used to scroll the text in the window left or right when
       the cursor moves to the left or right edge of the window.

Ctrl/Cursor Left/Right
       may be used to scroll the text in the window left or right
       without moving the cursor.

Cursor Up/Down
       may be used to scroll up and down through Dialogue window output,
       one line at a time.

Page Up/Down
       may be used to scroll up and down through Dialogue window output
       in increments of the number of lines in the window minus two.

Home       may be used to move to the beginning of Dialogue window output.

End       may be used to move to the end of Dialogue window output.

Enter       may be used to move to the end of Dialogue window output.

When the text cursor is positioned in the Prompt window, the Page Up, Page
Down, Ctrl/Page Up and Ctrl/Page Down keys may be used to scroll the
Dialogue window.


Page Up/Down
       may be used to scroll up and down through Dialogue window output,
       one line at a time.

Ctrl/Page Up and Ctrl/Page Down
       may be used to scroll up and down through Dialogue window output
       in increments of the number of lines in the window minus two.



Manipulating the Dialogue Window with a Mouse
─────────────────────────────────────────────
  1. Clicking in the Dialogue window causes the text cursor to move to this
    window.  It becomes the "active" window.

  2. Text may be scrolled up or down by dragging the mouse.  To do this, the
    right-side scrolling bar must be unlocked.

  3. Text may be scrolled left or right by dragging the mouse.    To do this,
    the bottom scrolling bar must be unlocked.

  4. Gadgets are provided for scrolling, resizing, and zooming the Dialogue
    window.

  5. The "scroll up" and "scroll down" gadgets may be used to move up and
    down through text lines.  When the text cursor moves to the top or
    bottom of the window, text will be scrolled down or up.

  6. The "scroll left" and "scroll right" gadgets move the cursor one
    character left or right.  When the text cursor moves to the left or
    right edge of the window, text will be scrolled to the right or left.

  7. The "page up" and "page down" gadgets may be used to scroll up and down
    through Dialogue window output in increments of the number of lines in
    the window minus two.



FPU Window
══════════
The contents of the 80x87 numeric data processor (math coprocessor)
registers and status flags are displayed in this window.  When the FPU
window is active, the currently selected item is displayed in "active"
attributes.  When the contents of a register have changed from the last time
that the debugger was entered, it is displayed in "standout" attributes.



Manipulating the FPU Window with Keys
─────────────────────────────────────
When the text cursor is positioned in the FPU window, the cursor and Enter
keys may be used to position to register (ST(0), ST(1), etc.) or flag
displays and modify register or flag contents.    The Home, End, Page Up, and
Page Down keys may be used to display register sets.  See the description of
the Register command for more information on register sets.

Cursor Up, Down, Left and Right
       keys may be used to move the text cursor to register/flag content
       displays.

Enter       may used to modify register contents.  If the text cursor is
       positioned on a register when the Enter key is pressed, a
       register modification window is displayed on the screen and a new
       value may be entered.  The register may be left unmodified by
       just pressing the Enter key in response to the prompt for a new
       value.

       If the text cursor is positioned on a flag when the Enter key is
       pressed then its value is complemented.

Home       may be used to move to the oldest register set.

End       may be used to move to the most recent register set.

Page Up    may be used to move backwards through register sets to the oldest
       register set.

Page Down  may be used to move forwards through register sets to the most
       recent register set.

Insert       may be used to switch between binary and decimal display formats.



Manipulating the FPU Window with a Mouse
────────────────────────────────────────
  1. Clicking in the FPU window causes the text cursor to move to this
    window.  It becomes the "active" window.  The text cursor may be
    positioned to any register contents or flag bits display.

  2. Double-clicking on a register display (ST(0), ST(1), etc.) will cause a
    register modification window to be displayed on the screen.  A new value
    may be entered or the register may be left unmodified by just pressing
    the Enter key in response to the prompt.

    Double clicking on a flag causes its value to be complemented.

  3. The "scroll up" gadget may be used to move backwards through register
    sets to the oldest register set.

  4. The "scroll down" gadget may be used to move forwards through register
    sets to the most recent register set.

  5. The "page up" gadget may be used to move backwards through register
    sets to the oldest register set.

  6. The "page down" gadget may be used to move forwards through register
    sets to the most recent register set.



Memory Window
═════════════
A portion of memory is displayed in this window.  When the Memory window is
active, the currently selected memory location is displayed in "active"
attributes.  Memory window "hot spots" (e.g., BYTE ) are displayed in
"standout" attributes.    All other items are displayed in "plain" attributes.



Manipulating the Memory Window with Keys
────────────────────────────────────────
When the text cursor is positioned in the Memory window, the cursor, Home,
Page Up, Page Down and Enter keys may be used to position to memory entries
and modify their contents.

Cursor Up, Down, Left and Right
       may be used to move the text cursor to individual memory
       locations.

Insert       may be used to modify the way in which memory locations are
       displayed.  Each subsequent press of the Insert key cycles the
       display through 8-bit bytes, 16-bit words, and 32-bit
       doublewords.  When 8-bit bytes are displayed, their ASCII
       equivalents are also displayed on the right-hand side of the
       window.

Delete       may be used to select a new memory location to be displayed.  A
       prompt window appears for the new memory location.

Home       may be used to move directly to the original location of memory
       that was requested to be displayed.

Page Up/Down
       may be used to scroll up and down through the memory window in
       increments of the number of lines in the window minus two.

Enter       may used to modify the contents of the memory location upon which
       the text cursor is positioned.  When pressed, a memory
       modification window is displayed on the screen and a new value
       may be entered.  The entry may be left unmodified by just
       pressing the Enter key in response to the prompt for a new value.
       Bytes, words or doublewords may be entered, depending on the way
       in which memory is being displayed.



Manipulating the Memory Window with a Mouse
───────────────────────────────────────────
  1. Clicking in the Memory window causes the text cursor to move to this
    window.  It becomes the "active" window.  The text cursor may be
    positioned to any memory entry shown in the window.

  2. Memory entries may be scrolled up or down by dragging the mouse.  To do
    this, the right-side scrolling bar must be unlocked.

  3. The "scroll up" and "scroll down" gadgets may be used to scroll up and
    down through memory.

  4. The "page up" and "page down" gadgets may be used to scroll up and down
    through memory in increments of the number of lines in the window minus
    two.

  5. Clicking on the "(Ins)" entry will cause the display to change between
    8-bit bytes, 16-bit words, and 32-bit doublewords.    When 8-bit bytes are
    displayed, their ASCII equivalents are also displayed on the right-hand
    side of the window.

  6. Clicking on the "(Del)" entry may be used to select a new memory
    location to be displayed.  A prompt window appears for the new memory
    location.  A new value may be entered or the memory address may be left
    unmodified by just pressing the Enter key in response to the prompt.

  7. Clicking on the "HOME" entry may be used to move directly to the
    original location of memory that was requested to be displayed.

  8. Double-clicking on a memory location will cause a memory modification
    window to be displayed on the screen.  A new value may be entered or the
    memory location may be left unmodified by just pressing the Enter key in
    response to the prompt.



Prompt Window
═════════════
The debugger command input prompt "DBG>" is displayed in a window that is
one line high.    The prompt window is used to enter command lines.

In multiple execution thread applications, the "DBG>" prompt is replaced by
a prompt that indicates the current thread.  The form of the prompt is
"ddddd>" where "ddddd" is the thread identification number.

Example:
  00002>



Manipulating the Prompt Window with Keys
────────────────────────────────────────
VIDEO commands are entered at the "DBG>" input prompt.

  DBG>

In multiple execution thread applications, the "DBG>" prompt is replaced by
a prompt that indicates the current thread.  The form of the prompt is
"ddddd>" where "ddddd" is the thread identification number.

Example:
  00002>

When the text cursor is positioned in the Prompt window, the cursor, Home,
End, Ins, Del, Backspace and Enter keys may be used to recall, edit and
submit commands.

Cursor Up/Down
       may be used to scroll through previously entered commands.

Cursor Left/Right
       may be used to move the cursor left or right through a command
       line to make changes.

Ctrl/Cursor Left and Right
       keys may be used to move the cursor left or right one word at a
       time.

Home       may be used to move to the beginning of the command line.

End       may be used to move to the end of the command line.

Insert       key may be used to flip between character insertion and
       overtyping modes.

Delete       may be used to remove the character under the cursor.

Backspace  (or Rubout) may be used to erase the character to the left of the
       cursor.

Enter       may be used to submit the command.

Ctrl/F       may be used to finish a partially entered symbol name.  Pressing
       Ctrl/F again will find the next symbol name that has the same
       initial sequence.

Ctrl/B       may be used to backup to the previous symbol name found with the
       Ctrl/F keys.

Command lines that exceed the screen width may be entered.  The command line
will scroll left or right depending on the cursor placement and direction.

When the text cursor is positioned in the Prompt window, the Page Up, Page
Down, Ctrl/Page Up and Ctrl/Page Down keys may be used to scroll the
Dialogue window (see the earlier section describing Dialogue window
manipulation).



Manipulating the Prompt Window with a Mouse
───────────────────────────────────────────
Clicking in the Prompt window causes the text cursor to move to this window.
It becomes the "active" window and VIDEO commands may be entered.



Register Window
════════════════
In 16-bit mode, the current contents of the 8086 registers are displayed in
the Register window.

In 32-bit mode, the current contents of the 32-bit registers are displayed
in the Register window.

When the Register window is active, the currently selected item is displayed
in "active" attributes.  When the contents of a register have changed from
the last time that the debugger was entered, it is displayed in "standout"
attributes.  An exception to this rule is the Instruction Pointer (IP, EIP)
register which is only displayed in "standout" attributes when its value
changes because some type of branch or call instruction was executed.

If a register set other than register set 0 is displayed, then the register
set number is displayed in brackets (e.g., [1]) with "active" attributes
(see the description of the Register command).



Manipulating the Register Window with Keys
──────────────────────────────────────────
When the text cursor is positioned in the Register window, the cursor and
Enter keys may be used to position to register displays and modify register
contents.  The Home, End, Page Up, and Page Down keys may be used to display
register sets.    See the description of the Register command for more
information on register sets.

Cursor Up, Down, Left and Right
       may be used to move the text cursor to register/flag content
       displays.

Enter       may used to modify register contents.  If the text cursor is
       positioned on a register when the Enter key is pressed, a
       register modification window is displayed on the screen and a new
       value may be entered.  The register may be left unmodified by
       just pressing the Enter key in response to the prompt for a new
       value.

       If the text cursor is positioned on a flag when the Enter key is
       pressed then its value is complemented.

Home       may be used to move to the oldest register set.

End       may be used to move to the most recent register set.

Page Up    may be used to move backwards through register sets to the oldest
       register set.

Page Down  may be used to move forwards through register sets to the most
       recent register set.



Manipulating the Register Window with a Mouse
─────────────────────────────────────────────
  1. Clicking in the Register window causes the text cursor to move to this
    window.  It becomes the "active" window.  The text cursor may be
    positioned to any register contents or flag bits display.

  2. Double-clicking on a register display will cause a register
    modification window to be displayed on the screen.    A new value may be
    entered or the register may be left unmodified by just pressing the
    Enter key in response to the prompt.

    Double clicking on a flag causes its value to be complemented.

  3. The "scroll up" gadget may be used to move backwards through register
    sets to the oldest register set.

  4. The "scroll down" gadget may be used to move forwards through register
    sets to the most recent register set.

  5. The "page up" gadget may be used to move backwards through register
    sets to the oldest register set (same as "scroll up").

  6. The "page down" gadget may be used to move forwards through register
    sets to the most recent register set (same as "scroll down").



Source Window
═════════════
If program source code information is available for the current code
location then it will be displayed in this window.  If the Code Segment and
Instruction Pointer registers (CS:IP, CS:EIP) point to a source line visible
in the Source window then the line is displayed in "active" attributes.
When examining source code, one line is designated as the current line and
is displayed in "standout" attributes.    The Assembly window, if present, is
kept synchronized with the Source window.



Manipulating the Source Window with Keys
────────────────────────────────────────
When the text cursor is positioned in the Source window, the Cursor Up/Down,
Page Up/Down, Home, End, and Enter keys may be used to move about.

Cursor Left/Right
       may be used to scroll the text in the window left or right when
       the cursor moves to the left or right edge of the window.

Ctrl/Cursor Left/Right
       may be used to scroll the text in the window left or right
       without moving the cursor.

Cursor Up/Down
       may be used to scroll up and down through source lines.

Page Up/Down
       may be used to scroll up and down through source lines in
       increments of the number of lines in the window minus two.

Home       may be used to move to the beginning of the current module
       (compilation unit).

End       may be used to move to the end of the current module (compilation
       unit).

Enter       may be used to move directly to the source line referenced by the
       CS:IP (16-bit mode) or CS:EIP (32-bit mode) register pair.



Manipulating the Source Window with a Mouse
───────────────────────────────────────────
  1. Clicking in the Source window causes the text cursor to move to this
    window.  It becomes the "active" window.

  2. Source lines may be scrolled up or down by dragging the mouse.  To do
    this, the right-side scrolling bar must be unlocked.

  3. Source lines may be scrolled left or right by dragging the mouse.    To
    do this, the bottom scrolling bar must be unlocked.

  4. Gadgets are provided for scrolling, resizing, zooming and closing the
    Source window.

  5. The "scroll up" and "scroll down" gadgets may be used to move up and
    down through text lines.  When the text cursor moves to the top or
    bottom of the window, text will be scrolled down or up.

  6. The "scroll left" and "scroll right" gadgets move the scroll one
    character left or right.  When the text cursor moves to the left or
    right edge of the window, text will be scrolled to the right or left.

  7. The "page up" and "page down" gadgets may be used to scroll up and down
    through source lines in increments of the number of lines in the window
    minus two.

  8. Clicking on a source line in the Source window makes it the current
    line.  This line is displayed in "standout" attributes.  The value of
    the VIDEO variable dbg$code changes to reflect the change in the current
    line.  This variable reflects the segment:offset of the most recent code
    location to be examined.  In addition, the "." address is changed to
    point to the first assembly instruction for the source line.  If there
    are no assembly instructions for the source line (as in lines or
    declarative lines) then the "." address is positioned to an earlier line
    (or the first line) in the module which has assembly instructions.    The
    "." address is used in many VIDEO commands.

    Example:
      do [CS IP] = .
      or
      do [CS EIP] = .

    In the above example, the contents of the CS:IP or CS:EIP register pair
    are modified to point to the current source line.

  9. Double-clicking on a line will set or clear a breakpoint at the first
    assembly instruction for the source line.



Stack Window
════════════
A portion of the execution stack is displayed in this window.  If the Base
Pointer (BP, EBP) register points to a visible byte, word or doubleword on
the stack, that item is displayed in "standout" attributes.  When the Stack
window is active, the currently selected stack location is displayed in
"active" attributes.  All other items are displayed in "plain" attributes.



Manipulating the Stack Window with Keys
───────────────────────────────────────
When the text cursor is positioned in the Stack window, the cursor, Home,
End, Page Up, Page Down and Enter keys may be used to position to stack
entries and modify their contents.

Cursor Up, Down, Left and Right
       may be used to move the text cursor to individual stack entries.

Insert       may be used to modify the way in which stack entries are
       displayed.  Each subsequent press of the Insert key cycles the
       display through 8-bit bytes, 16-bit words, and 32-bit
       doublewords.  When 8-bit bytes are displayed, their ASCII
       equivalents are also displayed on the right-hand side of the
       window.

Home       may be used to move directly to the stack entry referenced by
       SS:SP (16-bit mode) or SS:ESP (32-bit mode).

End       may be used to move directly to the stack entry referenced by
       SS:BP (16-bit mode) or SS:EBP (32-bit mode).

Page Up/Down
       may be used to scroll up and down through the stack in increments
       of the number of lines in the window minus two.

Enter       may used to modify the contents of the stack entry upon which the
       text cursor is positioned.  When pressed, a stack modification
       window is displayed on the screen and a new value may be entered.
       The entry may be left unmodified by just pressing the Enter key
       in response to the prompt for a new value.



Manipulating the Stack Window with a Mouse
──────────────────────────────────────────
  1. Clicking in the Stack window causes the text cursor to move to this
    window.  It becomes the "active" window.  The text cursor may be
    positioned to any stack entry.

  2. Stack entries may be scrolled up or down by dragging the mouse.  To do
    this, the right-side scrolling bar must be unlocked.

  3. The "scroll up" and "scroll down" gadgets may be used to scroll up and
    down through the stack.

  4. The "page up" and "page down" gadgets may be used to scroll up and down
    through the stack in increments of the number of lines in the window
    minus two.

  5. Clicking on the "(Ins)" entry will cause the display to change between
    8-bit bytes, 16-bit words, and 32-bit doublewords.    When 8-bit bytes are
    displayed, their ASCII equivalents are also displayed on the right-hand
    side of the window.

  6. Clicking on the "HOME" entry may be used to move directly to the stack
    entry referenced by SS:SP (16-bit mode) or SS:ESP (32-bit mode).

  7. Double-clicking on a stack entry will cause a stack modification window
    to be displayed on the screen.  A new value may be entered or the stack
    entry may be left unmodified by just pressing the Enter key in response
    to the prompt.



Thread Window
═════════════
The Thread window is used to display the identification number, state and
any additional pertinent information of all program execution threads.
Whenever the debugger is entered, the currently executing thread is
displayed in "active" attributes.  When a new thread entry has been
selected, it is displayed in "active" attributes.

Each entry in the Thread window has a number of fields.  The first field is
the thread identification number or thread ID.    The second field is the
thread state which may be one of "runnable" or "frozen".  Under NetWare, the
third field will contain the thread name which is applicable to NetWare 386
server tasks only.  The currently selected field is displayed in "standout"
attributes.  All other items are displayed in "plain" attributes.

Under DOS and QNX, there is only one execution thread so there is only one
entry in the Thread window.  Under OS/2 and NetWare 386, there may be
several execution threads so there may be be several entries in the Thread
window.



Manipulating the Thread Window with Keys
────────────────────────────────────────
When the text cursor is positioned in the Thread window, the cursor, Page
Up, Page Down and Enter keys may be used to position to thread entries and
modify their contents.

Cursor Up, Down, Left and Right
       may be used to move the text cursor to thread fields.

Page Up/Down
       may be used to scroll up and down through the thread window in
       increments of the number of lines in the window minus two.

Enter       may be used to modify the contents of the thread field upon which
       the text cursor is positioned.  When pressed on an "id" field,
       the selected thread becomes the current thread.  The other
       windows on the screen will change to reflect the selection of
       another execution thread.

       When pressed on a "state" field, the selected thread's state is
       changed to either "frozen" or "runnable".



Manipulating the Thread Window with a Mouse
───────────────────────────────────────────
  1. Clicking in the Thread window causes the text cursor to move to this
    window.  It becomes the "active" window.  The text cursor may be
    positioned to any thread entry.

  2. The "scroll up" and "scroll down" gadgets may be used to scroll up and
    down through thread entries.

  3. The "page up" and "page down" gadgets may be used to scroll up and down
    through thread entries in increments of the number of lines in the
    window minus two.

  4. Double-clicking on a thread "id" field will cause that thread to become
    the current thread.  The other windows on the screen will change to
    reflect the selection of another execution thread.

    Double-clicking on a "state" field will cause that thread's state to
    become either "frozen" or "runnable".



Variable Window
═══════════════
This window is created by the Print /Window command.  The debugger will
display output from a Print command in this window.  The window is updated
each time the debugger is entered or a VIDEO command is executed.  In the
illustration above, the sample Variable window is titled "Variable Display".



Manipulating the Variable Window with Keys
──────────────────────────────────────────
When the text cursor is positioned in the Variable window, the Cursor
Up/Down, Enter, Backspace and "S" keys may be used.

Cursor Up/Down
       may be used to move up and down through the fields of a
       structure.  Entries that represent structures are displayed by
       using "{...}".  Entries that represent arrays are displayed by
       using "(...)".

Page Up/Down
       may be used to scroll up and down through the Variable window in
       increments of the number of lines in the window.

Enter       can be used to display the contents of a field.

Backspace  can be used to return to the previous level.

"S"       can be used to display an entry as a string.  The Backspace key
       can be used to return to the original display format.



Manipulating the Variable Window with a Mouse
─────────────────────────────────────────────
  1. Clicking in the Variable window causes the text cursor to move to this
    window.  It becomes the "active" window.

  2. Fields can be selected and viewed by clicking on them.

  3. If you click on the line of dashes in the window, you will ascend to
    previous levels.

  4. Gadgets are provided for scrolling, resizing, zooming and closing the
    Variable window.

  5. The "scroll up" and "scroll down" gadgets may be used to move up and
    down through the fields of a structure.  Entries that represent
    structures are displayed by using "{...}".    Entries that represent
    arrays are displayed by using "(...)".

  6. The "page up" and "page down" gadgets may be used to scroll up and down
    through the Variable window in increments of the number of lines in the
    window.



View Window
═══════════
This window is created by the Help and View commands.  The View window
occupies the entire display area when it is active.  When the command
completes, the View window is removed and other windows are redisplayed.



Manipulating the View Window with Keys
──────────────────────────────────────
When the text cursor is positioned in the View window, the cursor, Page
Up/Down, Home, End, and Enter keys may be used to move about.  The /, ?, ',
and " keys may be used to search for text.

Cursor Up/Down
       may be used to move up and down through text lines.    Text lines
       will scroll when the text cursor is moved into the top or bottom
       areas of the window.

Cursor Left/Right
       move the cursor one character left or right.  When the cursor
       moves to the left or right edge of the window, text will be
       scrolled to the right or left.

Ctrl/Cursor Left/Right
       may be used to scroll the text in the window left or right
       without moving the cursor.

Page Up/Down
       may be used to scroll up and down through source lines in
       increments of the number of lines in the window minus two.

Home       may be used to move to the first line of the text being viewed.

Ctrl/Home  (Help window only) may be used to return to the main help index.

End       may be used to move to the last line of the text being viewed.

Enter       may be used to move the text cursor to the start of the next line
       of text.

       (Help window only) If you position the text cursor on a word in
       the window and press the Enter key, VIDEO will search for a topic
       by that name.

"/"       may be used to search forwards for a string of text.  A prompt is
       displayed for the string to search.    The Cursor Up key may be
       used to fill in the previous search string.

"?"       may be used to search backwards for a string of text.  A prompt
       is displayed for the string to search.  The Cursor Up key may be
       used to fill in the previous search string.

"'"       (apostrophe) may be used to search forwards for the previously
       specified search string.

"          (quote) may be used to search backwards for the previously
       specified search string.

"."       (period) may be used to repeat the last action.

Escape       may be used to terminate the viewing function.

"0" through "9"
       may be used to enter a number.  This number is used to repeat the
       next action the specified number of times.  For example, entering
       the number 20 followed by Cursor Down moves the cursor down 20
       lines rather than one.  For the Home and End keys, the number
       moves to "number" lines from the beginning of file and end of
       file, respectively.    To cancel a number without executing a
       command, press the Delete key.

Pressing one of the search keys causes a prompt for a search string to
appear.  If a previous string had been entered, this string may be recalled
using the Cursor Up key.  The recalled string will appear in the prompt
area.  Pressing the Escape key at this point will cancel the search command.
The Cursor Left and Right keys and the Home, End, Delete and Backspace keys
may be used to edit the search string.    After the search string has been
entered, pressing the Enter key will begin the search.    The search is done
case insensitively, with the file considered as a ring of text (e.g., if
searching forwards and the end of the file is reached without finding the
text, the search continues from the beginning of the file).  If the string
is found, the cursor is placed under the first matched character and the
matched string is highlighted.



Manipulating the View Window with a Mouse
─────────────────────────────────────────
  1. Clicking in the View window causes the text cursor to move to the mouse
    cursor.

  2. (Help window only) If you position the text cursor on a word in the
    window and double-click on it with a mouse, VIDEO will search for a
    topic by that name.  If you double-click on the title line, VIDEO will
    return to the main help index.

  3. Text lines may be scrolled up or down by dragging the mouse.  To do
    this, the right-side scrolling bar must be unlocked.

  4. Text lines may be scrolled left or right by dragging the mouse.  To do
    this, the bottom scrolling bar must be unlocked.

  5. Gadgets are provided for scrolling and closing the View window.

  6. The "scroll up" and "scroll down" gadgets may be used to move up and
    down through text lines.  When the text cursor moves to the top or
    bottom of the window, text will be scrolled down or up.

  7. The "scroll left" and "scroll right" gadgets move the scroll one
    character left or right.  When the text cursor moves to the left or
    right edge of the window, text will be scrolled to the right or left.

  8. The "page up" and "page down" gadgets may be used to scroll up and down
    through source lines in increments of the number of lines in the window
    minus two.



Error Window
════════════
In addition to the windows described in earlier sections, an "error" window
may appear in the middle of the screen when VIDEO wishes to issue an error
message.  This window will disappear when any key is pressed.
::::WIRING
Serial Port Wiring Considerations
═════════════════════════════════
If you plan to use the serial port Debug Server "SERSERV", a cable must
connect the serial ports of the two computer systems.  The following diagram
illustrates the wiring between the two serial ports.  If your computer
systems have more than one serial port, any serial port may be used.

      Task Machine        Debugger Machine
    Serial            Serial
       Connector           Connector

       Pin #          Pin #
       1 (PG) <──────────>1 (PG)

       2 (TxD)<──────────>3 (RxD)

       3 (RxD)<──────────>2 (TxD)

  ┌─────── 4 (RTS)          4 (RTS) ───────┐
  │                         │
  └──────> 5 (CTS)          5 (CTS) <──────┘

  ┌──────> 6 (DSR)          6 (DSR) <──────┐
  │                         │
  │       7 (SG) <──────────>7 (SG)         │
  │                         │
  ├──────> 8 (DCD)          8 (DCD) <──────┤
  │                         │
  └──────>20 (DTR)         20 (DTR) ───────┘

Figure 76. Serial Port Wiring Scheme

Note that the wiring is symmetrical (i.e., either end of the cable can be
plugged into either PC).  This particular arrangement of the wiring is
sometimes called a "null modem" (since pins 2 and 3 are crossed and no modem
is involved).



Parallel Port Wiring Considerations
═══════════════════════════════════
If you plan to use the parallel port Debug Server "PARSERV" or "PARSERVW", a
cable must connect the parallel ports of the two computer systems.  Three
cabling methods are supported - the LapLink cable, the Flying Dutchman
cable, and WATCOM's own design.  There are two advantages to using the
LapLink or Flying Dutchman cable:

  1. They are commercially available (you may already own one).

  2. They may work with more PC "compatibles" than WATCOM's cable.  WATCOM's
    cabling requires 8 bi-directional data lines in the parallel port and
    some PC "compatibles" do not support this.

The disadvantage with the LapLink and Flying Dutchman cables is that they
are slower than WATCOM's cable since only 4 bits are transmitted in parallel
versus 8 bits for WATCOM's.  Thus WATCOM's cable is faster but it will have
to be custom made.

The LapLink cable is available from:

  Travelling Software, Inc.
  18702 North Creek Parkway
  Bothell, Washington,
  U.S.A. 98011
  Telephone: [phone]

The Flying Dutchman cable is available from:

  Cyco,
  Adm. Banckertweg 2a,
  2315 SR Leiden,
  The Netherlands.

The following diagram illustrates WATCOM's cable wiring between the two
parallel ports.

     Task Machine       Debugger Machine
      Parallel              Parallel
      Connector           Connector

       Pin #          Pin #
       1 <──────────────> 2
       2 <──────────────> 1
       3 <──────────────> 14
       4 <──────────────> 16
       5 <──────────────> 15
       6 <──────────────> 13
       7 <──────────────> 12
       8 <──────────────> 10
       9 <──────────────> 11
      10 <──────────────> 8
      11 <──────────────> 9
      12 <──────────────> 7
      13 <──────────────> 6
      14 <──────────────> 3
      15 <──────────────> 5
      16 <──────────────> 4
      17 <──────────────> 17
      18 <──────────────> 18

Figure 77. Parallel Port Wiring Scheme

For the IBM PC and PS/2, the connectors are standard "male" DB-25
connectors.  Note that the wiring is symmetrical (i.e., either end of the
cable can be plugged into either PC).

┌────────────────────────────────────────────────────────────────────────────┐
│ Note:  Although the wiring is different for all three cables, WATCOM's     │
│ parallel communications software can determine which one is in use.         │
└────────────────────────────────────────────────────────────────────────────┘
::::~~~DEFAULT
      ┌──────────────────────────────────────────────────────────┐
      │              W V I D E O             │
      │  WATCOM Visual Interactive Debugging Execution Overseer  │
      └──────────────────────────────────────────────────────────┘

To obtain help on the desired <topic>, position the cursor on it using the
cursor keys and press Enter or double-click on it with a mouse.  For more
topics, scroll this window using the cursor or PgUp/PgDn keys or the mouse.
Use Ctrl/Home or double-click on the title line to return to this index.

Help is available on the following topics.

Commands & General Information:

<BREAK>         <CALL>        <COMMAND_FILES>     <C_OPERATORS>
<DISPLAY>        <DO>        <ERROR>         <EXAMINE>
<F77_OPERATORS>     <FLIP>        <GO>            <HELP>
<IF>            <INVOKE>        <LOG>            <MENUS>
<MODIFY>        <NEW>        <NOTATION>        <PAINT>
<PRINT>         <PRINT_WINDOW>    <QUIT>            <REGISTER>
<REMARK>        <REMOTE_DEBUGGING>    <REMOTE_WIN3>        <RFX>
<SET>            <SHOW>        <SUMMARY>        <SYMBOLS>
<SYSTEM>        <THREAD>        <TRACE>         <VIEW>
<WATCH>         <WHILE>        <WINDOWS>        <WIRING>

Systems:

<AUTOCAD>

<DOS_STARTUP>                <DOS_EXTENDER>
<DOS_GRAPHICS_APPLICATIONS>        <DOS_INTERRUPTING_A_PROGRAM>
<DOS_REMOTE_DEBUGGING>            <DOS_WVIDEO_ENVIRONMENT_VARIABLE>

<WIN3_STARTUP>                <WIN3_WVIDEOW_ENVIRONMENT_VARIABLE>

<OS2_STARTUP>                <OS2_INTERRUPTING_A_PROGRAM>
<OS2_REMOTE_DEBUGGING>            <OS2_WVIDEO_ENVIRONMENT_VARIABLE>

<QNX_STARTUP>                <QNX_DEBUGGING_USING_POSTMORTEM_DUMP>
<QNX_INTERRUPTING_A_PROGRAM>        <QNX_REMOTE_DEBUGGING>
<QNX_SEARCH_ORDER>            <QNX_WVIDEO_ENVIRONMENT_VARIABLE>

Short forms for the topic name may be specified.