1 INTRODUCTION
This set of release notes describes the current restrictions, and
new and changed features for VAX DEBUG Version V5.0 MP. It has
been extracted from the complete release notes which are in the
VAX DEBUG HELP file. The HELP file release notes cover all
releases since Version 4.2, and include detailed descriptions of
all new and changed features.
The release note subtopics describe the following:
1. Changes in the debugger configuration from the V5.0 or
earlier debugger.
2. Compatibility between the new default and multiprocess
debugging configurations.
3. How the debugger automatically uses the single-process (V5.0
and earlier) debugger configuration if a separate process
cannot be created for the main debugger image, and what to do
in this case.
4. Changes in the use of CTRL/Y and CTRL/C
5. Changes in debugger predefined keypad key definitions.
6. Changes in the use of debugger commands in DCL command
procedures
7. System management considerations for multiprocess debugging.
8. Any known restrictions
1.1 Debugging Configurations
Starting with this version, the debugger consists of two parts:
1. A relatively small kernel debugger image (DEBUG.EXE) that
runs in the same process as the image being debugged
2. A larger main debugger image (DEBUGSHR.EXE) that contains
most of the debugger code and runs in a subprocess.
This separation enables you to have two debugging configurations:
1. The default (non-multiprocess) configuration. The program
being debugged (which may consist of several images) runs in
one process along with the kernel debugger. The main
debugger runs in a subprocess.
2. The multiprocess configuration. The multiprocess debugging
configuration enables you to interact with several processes
from one debugging session. This configuration is achieved
when the definition of DBG$PROCESS is MULTIPROCESS.
$ DEFINE/JOB DBG$PROCESS MULTIPROCESS
The program being debugged (which may consist of several
images) runs in several processes. Each process that is
running an image under debugger control is also running a
local copy of the kernel debugger. One main debugger runs in
a separate subprocess and communicates with the other
processes through their kernel debuggers.
The new default configuration replaces the V5.0 (and earlier)
configuration, whereby the debugger and the program being
debugged ran in the same process. The default configuration
provides the following advantages over the single-process
configuration:
1. The main debugger and program run entirely in separate
processes, with very little interference.
2. Within a debugging session, you can interrupt program
execution or the execution of a debugger command without
aborting the debugging session. By default, this is achieved
by pressing CTRL/C. However, if your program already has a
CTRL/C AST service routine enabled, you can reassign the
abort function to another CTRL-key sequence with the command
SET ABORT_KEY.
1.2 Compatibility
All of the commands, qualifiers, and built-in symbols that are
provided for multiprocess debugging are also understood in the
default debugging configuration and have analogous behaviors
(where applicable). For example:
1. The EXIT command without a parameter specified terminates a
debugging session in both configurations.
2. A DO command without the /PROCESS qualifier executes the
commands specified in all processes.
3. In the default configuration, the "visible" process is the
process that runs the entire program, and it is identified as
process 1 in a SHOW PROCESS display.
4. Built-in symbols such as %PROCESS_NUMBER and %VISIBLE_PROCESS
are interpreted correctly in the default configuration.
This compatibility is especially useful in that command
procedures used for multiprocess debugging can also be used for
debugging programs that run in only one process.
1.2.1 Single Process Configuration -
When you invoke the debugger in either the default or
multiprocess configuration, if a separate process cannot be
created to run the main debugger image, the debugger issues the
following messages and automatically uses the single-process
(V5.0 and earlier) configuration:
%DEBUG-E-CANTCREATEMAIN, could not create the VAX DEBUG subprocess
-SYSTEM-F-EXQUOTA, exceeded quota
%DEBUG-I-SHRPRC, VAX DEBUG will share user process
Under these conditions, you should be aware of the following
differences compared to the new default or multiprocess
configurations:
1. Although you can use the debugger to debug a program that
normally runs in only one process, you cannot use the
additional debugger features that enable you to debug a
multiprocess program.
2. To abort a debugger command or program execution from within
a debugging session, do not use CTRL/C. Instead, as for the
V5.0 or earlier debugger, use the CTRL/Y -- DEBUG sequence.
CTRL/Y returns you to DCL level. The DCL command DEBUG
invokes the debugger, which then displays its prompt. Also,
you cannot use the SET ABORT_KEY command to reassign the
abort function to another CTRL-key sequence.
1.3 CTRL-Y Changes
Starting with this version of the debugger, use CTRL/C rather
than CTRL/Y from within a debugging session to interrupt program
execution or the execution of a debugger command. Using CTRL/C
enables you to abort these operations without exiting the
debugger (the debugger prompt is displayed after you enter
CTRL/C).
If your program already has a CTRL/C AST routine enabled, use the
SET ABORT_KEY command to reassign the abort function to another
control-key sequence. The SHOW ABORT_KEY identifies the CTRL-key
sequence that is currently assigned the abort function.
As with previous versions of the debugger, you can use the
sequence CTRL/Y - DEBUG to interrupt a program running without
debugger control and then invoke the debugger. Do not use CTRL/Y
for other purposes when using the debugger.
1.4 Keypad Changes
Several previously unused keypad key combinations now enable you
to display process specific source and instruction displays.
Also note that, for symmetry, the command string that was
previously assigned to the sequence BLUE-KP3 (SELECT/SOURCE
%NEXT_SOURCE) has been moved to the previously unused sequence
GOLD-COMMA.
The following table summarizes the new and changed functions.
Key: State: Command Invoked or Function:
COMMA GOLD SELECT/SOURCE %NEXT_SOURCE. Selects
the next source display in the display
list as the current source display.
This function was previously assigned
to KP3 in the BLUE state.
KP9 GOLD SET PROCESS/VISIBLE %NEXT_PROCESS.
Makes the next process in the process
list the visible process.
KP9 BLUE Displays two predefined process
specific source displays, SRC_n.
These are located at Q1 and Q2,
respectively, for the visible process
and for the next process on the
process list.
KP7 BLUE Displays two sets of predefined
process specific source and
instruction displays, SRC_n and
INST_n. These consist of source and
instruction displays for the visible
process at Q1 and RQ1, respectively,
and source and instruction displays
for the next process on the process
list at Q2 and RQ2, respectively.
KP3 BLUE Displays three predefined process
specific source displays, SRC_n.
These are located at S1, S2, and
S3, respectively, for the previous,
current (visible), and next process on
the process list.
KP1 BLUE Displays three sets of predefined
process specific source and
instruction displays, SRC_n and
INST_n. These consist of source and
instruction displays for the visible
process at S2 and RS2, respectively;
source and instruction displays for
the previous process on the process
list at S1 and RS1, respectively; and
source and instruction displays for
the next process on the process list
at S3 and RS3, respectively.
1.5 DCL_Command_Procedures
With previous versions of the debugger, you could use a DCL
command procedure to invoke the debugger and issue debugger
commands contained in that command procedure. For example:
$ ! Procedure to run PROG2 under debugger
$ ! control and issue debugger commands
$ !
$ RUN PROG2
SET BREAK %LINE 17
GO
EXIT
$ SHOW SYSTEM
$ LOGOUT
Starting with this version of the debugger, you can no longer put
debugger commands directly into a command procedure. Instead,
you must create a temporary file containing the debugger commands
and assign the logical name DBG$INPUT to point to that file. For
example:
$ CREATE DEBUG_COMMANDS.TMP
SET BREAK %LINE 17
GO
EXIT
$ DEFINE/USER DBG$INPUT DEBUG_COMMANDS.TMP
$ RUN PROG2
$ DELETE DEBUG_COMMANDS.TMP;*
$ SHOW SYSTEM
$ LOGOUT
This change applies to both the default configuration and the
multiprocess configuration.
1.6 System Management
Having several users debugging programs which occupy several
processes can place a load on a system. The subtopics describes
the resources used by the multiprocess debugger, so that you can
tune your system for this activity. Note that the subtopics
cover only the resources used by the debugger. You may have to
tune your system to support the multiprocess programs themselves.
1.6.1 User Quotas -
To do multiprocess debugging, each user needs sufficient PRCLM
quota to create an additional subprocess for the debugger, beyond
the number of processes needed for the multiprocessing program.
BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may
need to be increased to account for the debugger subprocess.
o Each user's ENQLM quota should be increased by at least the
number of processes being debugged.
o Each user's PGFLQUOTA may need to be increased. If a user
has insufficient PGFLQUOTA, the debugger may fail to
activate, or produce "virtual memory exceeded" errors during
execution.
o Each user's BYTLM and FILLM quotas may need to be increased.
The debugger requires enough BYTLM and FILLM quotas to open
each image file being debugged, the corresponding source
files, and the DEBUG input, output, and log files. The DEBUG
SET MAX_SOURCE_FILES command can be used to limit the number
of source files kept open by the debugger at any one time.
1.6.2 System Resources -
The kernel and main debugger communicate through global sections.
The main debugger communicates with up to 8 kernel debuggers
through a 65-page global section. Therefore, the SYSGEN
parameters GBLPAGES and GBLSECTIONS may need to be increased.
For example, if there are 10 users using the debugger
simultaneously, 10 global sections (GBLSECTIONS) using a total of
650 global pages (GBLPAGES) are required by the debugger.
1.7 Restrictions
1.7.1 Abort Key disabled after SPAWN -
If you use the SPAWN command to create a subprocess or invoke a
spawned editor from the debugger, the debugger's abort key is
disabled and remains disabled after you return to the debugger
prompt. The only way to re-enable the abort key is to log out
and log back in (and re-invoke the debugger)
1.7.2 Debugging installed writeable images -
If you attempt to DEBUG an image that is installed (using the
Install Utility) /WRITEABLE/SHARED, then you will get an error
similar to:
VAX DEBUG Version V5.0-00 MP
%DEBUG-I-CANTOPNIMG, cannot open image WRTSHR
-RMS-E-FLK, file currently locked by another user
-SYSTEM-W-ACCONFLICT, file access conflict
This error occurs because DEBUG is unable to open an image file
that is installed /WRITEABLE when it is running in a separate
process. One workaround for this problem is to not install the
image. If this isn't possible, another workaround is to make the
following logical name assignment:
$ DEFINE DBG$PROCESS NONE
This definition causes the debugger to share the same process as
the user program rather than running in a subprocess. Digital
encourages you to use this unsupported configuration only when
necessary, since it may not be provided in future releases of VAX
DEBUG. While this workaround may also correct other problems, you
are strongly encouraged to submit an SPR if you encounter any such
problems.