 |
OpenVMS Debugger Manual
This command causes the debugger to execute the program to the next
instruction when a STEP command is entered, and not to display lines of
source code with each STEP command.
| #2 |
DBG> SET STEP LINE,INTO,NOSYSTEM,NOSHARE
|
This command causes the debugger to execute the program to the next
line when a STEP command is entered, and to step into called routines
in user space only. The debugger steps over routines in system space
and in shareable images.
SET TASK|THREAD
Changes characteristics of one or more tasks of a tasking program (also
called a multithread program).
Format
SET TASK [task-spec[,...]]
Parameters
task-spec
Specifies a task value. Use any of the following forms:
- When the event facility is THREADS:
- A task (thread) ID number as declared in the program, or a
language expression that yields a task ID number.
- A task ID number (for example, 2), as indicated in a SHOW TASK
display.
- When the event facility is ADA:
- A task (thread) name as declared in the program, or a language
expression that yields a task value. You can use a path name.
- A task ID (for example, %TASK 2), as indicated in a SHOW TASK
display.
- One of the following task built-in symbols:
|
%ACTIVE_TASK
|
The task that runs when a GO, STEP, CALL, or EXIT command executes.
|
|
%CALLER_TASK
|
(Applies only to Ada programs.) When an accept statement executes, the
task that called the entry associated with the accept statement.
|
|
%NEXT_TASK
|
The task after the visible task in the debugger's task list. The
ordering of tasks is arbitrary but consistent within a single run of a
program.
|
|
%PREVIOUS_TASK
|
The task previous to the visible task in the debugger's task list.
|
|
%VISIBLE_TASK
|
The task whose call stack and register set are the current context for
looking up symbols, register values, routine calls, breakpoints, and so
on.
|
Do not use the asterisk (*) wildcard character. Instead, use the /ALL
qualifier. Do not specify a task with /ALL or /TIME_SLICE. If you do
not specify a task or /ALL with /ABORT, /[NO]HOLD, /PRIORITY, or
/RESTORE, the visible task is selected.
Qualifiers
/ABORT
Marks the specified tasks for termination. Termination occurs at the
next allowable point after a specified task resumes execution.
For Compaq Ada tasks, the effect is identical to executing an Ada abort
statement for the tasks specified and causes these tasks to be marked
as abnormal. Any dependent tasks are also marked for termination.
For POSIX Threads threads, use the following command:
PTHREAD tset -c thread-number
|
/ACTIVE
Makes the specified task the active task, which is the task that runs
when a STEP, GO, CALL, or EXIT command executes. This causes a task
switch to the new active task and makes that task the visible task. The
specified task must be in either the RUNNING or READY state. When using
/ACTIVE, you must specify one task.
The SET TASK/ACTIVE command is supported for Compaq Ada on VAX only.
For POSIX Threads programs or Compaq Ada on Alpha programs, use one of
the following alternatives:
- For query-type actions, use the SET TASK/VISIBLE command.
- To gain control of execution, use a strategic placement of
breakpoints.
- Use the PTHREAD tset -a thread-number command.
/ALL
Applies the SET TASK command to all tasks.
/HOLD
/NOHOLD (default)
When the event facility is THREADS, use the PTHREAD tset -h
thread-number or the PTHREAD tset -n thread-number command.
Controls whether a specified task is put on hold. The /HOLD qualifier
puts a specified task on hold.
Putting a task on hold prevents a task from entering the RUNNING state.
A task put on hold is allowed to make other state transitions; in
particular, it can change from the SUSPENDED to the READY state.
A task already in the RUNNING state (the active task) can continue to
execute as long as it remains in the RUNNING state, even though it is
put on hold. If the task leaves the RUNNING state for any reason
(including expiration of a time slice, if time slicing is enabled), it
will not return to the RUNNING state until released from the hold
condition.
You can override the hold condition and force a task into the RUNNING
state with the SET TASK/ACTIVE command even if the task is on hold.
The /NOHOLD qualifier releases a specified task from hold.
/PRIORITY=n
When the event facility is THREADS, use the PTHREAD tset -s
thread-number command.
Sets the priority of a specified task to n, where n
is a decimal integer from 0 to 15. This does not prevent the priority
from later changing in the course of execution, for example, while
executing an Ada rendezvous or POSIX Threads synchronization event.
This qualifier does not affect a task's scheduling policy.
/RESTORE
(Compaq Ada on VAX only) Restores the priority of a specified task to
the priority it had when it was created. Does not affect the scheduling
priority of the task.
/TIME_SLICE=t
Supported for Compaq Ada on VAX only. Sets the time-slice duration to
the value t, where t is a decimal integer or real
value representing seconds. The set value overrides the time-slice
value specified in the program, if any. To disable time slicing, use
/TIME_SLICE=0.0. /TIME_SLICE is valid only when the event facility is
ADA.
/VISIBLE
Makes the specified task the visible task, which is the task whose call
stack and register set are the current context for looking up symbols,
register values, routine calls, breakpoints, and so on. Commands such
as EXAMINE are directed at the visible task. The /VISIBLE qualifier
does not affect the active task. When using /VISIBLE, you must specify
one task.
Description
Note
SET TASK and SET THREAD are synonymous commands. They perform
identically.
|
The SET TASK command enables you to establish the visible task and the
active task, control the execution of tasks, and cause task state
transitions, directly or indirectly.
To determine the current state of a task, use the SHOW TASK command.
The possible states are RUNNING, READY, SUSPENDED, and TERMINATED.
Related commands:
DEPOSIT/TASK
EXAMINE/TASK
SET BREAK/EVENT
SET TRACE/EVENT
(SET, SHOW) EVENT_FACILITY
SHOW TASK|THREAD
Examples
| #1 |
DBG> SET TASK/ACTIVE %TASK 3
|
(Event facility = ADA) This command makes task 3 (task ID = 3) the
active task.
| #2 |
DBG> PTHREAD tset -a 3
|
(Event facility = THREADS) This command makes task 3 (task ID = 3) the
active task.
| #3 |
DBG> SET TASK %NEXT_TASK
|
This command makes the next task in the debugger's task list the
visible task. (The /VISIBLE qualifier is a default for the SET TASK
command.)
| #4 |
DBG> SET TASK/HOLD/ALL
DBG> SET TASK/ACTIVE %TASK 1
DBG> GO
...
DBG> SET TASK/ACTIVE %TASK 3
DBG> STEP
...
|
In this example, the SET TASK/HOLD/ALL command freezes the state of all
tasks except the active task. Then, SET TASK/ACTIVE is used selectively
(along with the GO and STEP commands) to observe the behavior of one or
more specified tasks in isolation.
SET TERMINAL
Sets the terminal-screen height or width that the debugger uses when it
formats screen and other output.
Note
This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to
the debugger.
|
Format
SET TERMINAL
Qualifiers
/PAGE:n
Specifies that the terminal screen height should be set to n
lines. You can use any value from 18 to 100.
/WIDTH:n
Specifies that the terminal screen width should be set to n
columns. You can use any value from 20 to 255. For a VT100-, VT200-, or
VT300 series terminal, n is typically either 80 or 132.
/WRAP
Tells the debugger to wrap output text in predefined display OUT at the
column specified by the /WIDTH qualifier. If you do not specify /WIDTH
in the current command, /WRAP defaults to the %WIDTH setting.
Description
The SET TERMINAL command enables you to define the portion of the
screen that the debugger has available for formatting screen output.
This command is useful with VT100-, VT200-, or VT300-series terminals,
where you can set the screen width to typically 80 or 132 columns. It
is also useful with workstations, where you can modify the size of the
terminal-emulator window that the debugger uses.
You must specify at least one qualifier. You can specify all. The /PAGE
and /WIDTH qualifiers each require a value.
When you enter the SET TERMINAL command, all display window definitions
are automatically adjusted to reflect the new screen dimensions. For
example, RH1 changes dimensions proportionally to remain in the top
right half of the screen.
Similarly, all "dynamic" display windows are automatically
adjusted to maintain their relative proportions. Note that all display
windows are dynamic unless referenced with the DISPLAY/NODYNAMIC
command. In that case, the display window retains its current
dimensions after subsequent SET TERMINAL commands. However, you can use
the DISPLAY command to reconfigure the display window (you can also use
keypad-key combinations, such as BLUE-MINUS, to enter predefined
DISPLAY commands).
Related commands:
DISPLAY/[NO]DYNAMIC
EXPAND
(SET,SHOW,CANCEL) WINDOW
SHOW TERMINAL
Example
|
DBG> SET TERMINAL/WIDTH:132
|
This command specifies that the terminal screen width be set to 132
columns.
SET TRACE
Establishes a tracepoint at the location denoted by an address
expression, at instructions of a particular class, or at the occurrence
of specified events.
Format
SET TRACE [address-expression[,...]]
[WHEN(conditional-expression)]
[DO(command[;...])]
Parameters
address-expression
Specifies an address expression (a program location) at which a
tracepoint is to be set. With high-level languages, this is typically a
line number, a routine name, or a label, and can include a path name to
specify the entity uniquely. More generally, an address expression can
also be a memory address or a register and can be composed of numbers
(offsets) and symbols, as well as one or more operators, operands, or
delimiters. For information about the operators that you can use in
address expressions, type Help Address_Expressions.
Do not specify the asterisk (*) wildcard character. Do not specify an
address expression with the following qualifiers:
/ACTIVATING
/BRANCH
/CALL
/EXCEPTION
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/INTO
/[NO]JSB (VAX only)
/LINE
/OVER
/[NO]SHARE
/[NO]SYSTEM
/TERMINATING
/VECTOR_INSTRUCTION (VAX only)
The /MODIFY and /RETURN qualifiers are used with specific kinds of
address expressions.
If you specify a memory address or an address expression whose value is
not a symbolic location, check (with the EXAMINE command) that an
instruction actually begins at the byte of memory so indicated. If an
instruction does not begin at this byte, a run-time error can occur
when an instruction including that byte is executed. When you set a
tracepoint by specifying an address expression whose value is not a
symbolic location, the debugger does not verify that the location
specified marks the beginning of an instruction.
On VAX processors, CALLS and CALLG routines start with an entry mask.
conditional-expression
Specifies a conditional expression in the currently set language that
is to be evaluated whenever execution reaches the tracepoint. (The
debugger checks the syntax of the expressions in the WHEN clause when
execution reaches the tracepoint, not when the tracepoint is set.) If
the expression is true, the debugger reports that a tracepoint has been
triggered. If an action (DO clause) is associated with the tracepoint,
it will occur at this time. If the expression is false, a report is not
issued, the commands specified by the DO clause (if one was specified)
are not executed, and program execution is continued.
command
Specifies a debugger command to be executed as part of the DO clause
when trace action is taken. The debugger checks the syntax of the
commands in a DO clause when it executes the DO clause, not when the
tracepoint is set.
Qualifiers
/ACTIVATING
Causes the debugger to trace when a new process comes under debugger
control. See also the /TERMINATING qualifier.
/AFTER:n
Specifies that trace action not be taken until the nth time
the designated tracepoint is encountered (n is a decimal
integer). Thereafter, the tracepoint occurs every time it is
encountered provided that conditions in the WHEN clause (if specified)
are true. The SET TRACE/AFTER:1 command has the same effect as SET
TRACE.
/BRANCH
Causes the debugger to trace every branch instruction encountered
during program execution. See also the /INTO and /OVER qualifiers.
/CALL
Causes the debugger to trace every call instruction encountered during
program execution, including the return instruction. See also the /INTO
and /OVER qualifiers.
/EVENT=event-name
Causes the debugger to trace the specified event (if that event is
defined and detected by the current event facility). If you specify an
address expression with /EVENT, causes the debugger to trace whenever
the specified event occurs for that address expression. You cannot
specify an address expression with certain event names.
Event facilities are available for programs that call Ada or SCAN
routines or that use POSIX Threads services. To identify the current
event facility and the associated event names, use the SHOW
EVENT_FACILITY command.
/EXCEPTION
Causes the debugger to trace every exception that is signaled. The
trace action occurs before any application-declared exception handlers
are invoked.
As a result of a SET TRACE/EXCEPTION command, whenever your program
generates an exception, the debugger reports the exception and
resignals the exception, thus allowing any application-declared
exception handler to execute.
/INSTRUCTION
/INSTRUCTION[=(opcode[,...])] (VAX only)
When you do not specify an opcode, causes the debugger to trace every
instruction encountered during program execution.
(VAX only) If you specify one or more opcodes, causes the debugger to
trace every instruction whose opcode is in the list.
If you specify a vector instruction, do not include an instruction
qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION, /MODIFY, /0, or /1)
with the instruction mnemonic.
See also the /INTO and /OVER qualifiers.
/INTO
(Default) Applies only to tracepoints set with the following qualifiers
(that is, when an address expression is not explicitly specified):
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
When used with those qualifiers, /INTO causes the debugger to trace the
specified points within called routines (as well as within the routine
in which execution is currently suspended). The /INTO qualifier is the
default and is the opposite of /OVER.
When using /INTO, you can further qualify the trace action with the
/[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers.
/JSB
/NOJSB
(VAX only) Qualifies /INTO. Use with /INTO and one of the following
qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...])
/LINE
/VECTOR_INSTRUCTION
The /JSB qualifier is the default for all languages except DIBOL. It
lets the debugger set tracepoints within routines that are called by
the JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default)
specifies that tracepoints not be set within routines called by JSB
instructions. In DIBOL, application-declared routines are called by the
CALL instruction and DIBOL Run-Time Library routines are called by the
JSB instruction.
/LINE
Causes the debugger to trace the beginning of each source line
encountered during program execution. See also the /INTO and /OVER
qualifiers.
/MODIFY
Causes the debugger to trace when an instruction writes to and changes
the value of a location indicated by a specified address expression.
The address expression is typically a variable name.
The SET TRACE/MODIFY X command is equivalent to SET WATCH X DO(GO). The
SET TRACE/MODIFY command operates under the same restrictions as SET
WATCH.
If you specify an absolute address for the address expression, the
debugger might not be able to associate the address with a particular
data object. In this case, the debugger uses a default length of 4
bytes. You can change this length, however, by setting the type to
either WORD (SET TYPE WORD, which changes the default length to 2
bytes) or BYTE (SET TYPE BYTE, which changes the default length to 1
byte). The SET TYPE LONGWORD command restores the default length of 4
bytes.
/OVER
Applies only to tracepoints set with the following qualifiers (that is,
when an address expression is not explicitly specified):
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
When used with those qualifiers, /OVER causes the debugger to trace the
specified points only within the routine in which execution is
currently suspended (not within called routines). The /OVER qualifier
is the opposite of /INTO (which is the default).
/RETURN
Causes the debugger to break on the return instruction of the routine
associated with the specified address expression (which can be a
routine name, line number, and so on). Breaking on the return
instruction enables you to inspect the local environment (for example,
obtain the values of local variables) while the routine is still
active. Note that the view of a local environment may differ depending
on your architecture. On VAX processors, this qualifier can only be
applied to routines called with a CALLS or CALLG instruction; it cannot
be used with JSB routines. On Alpha processors, this qualifier can be
applied to any routine.
The address-expression parameter is an instruction
address within a routine. It can simply be a routine name, in which
case it specifies the routine start address. However, you can also
specify another location in a routine, so you can see only those
returns that are taken after a certain code path is followed.
A SET TRACE/RETURN command cancels a previous SET TRACE if you specify
the same address expression.
/SHARE (default)
/NOSHARE
Qualifies /INTO. Use with /INTO and one of the following qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
The /SHARE qualifier permits the debugger to set tracepoints within
shareable image routines as well as other routines. The /NOSHARE
qualifier specifies that tracepoints not be set within shareable images.
/SILENT
/NOSILENT (default)
Controls whether the "trace..." message and the source line
for the current location are displayed at the tracepoint. The /NOSILENT
qualifier specifies that the message is displayed. The /SILENT
qualifier specifies that the message and source line are not displayed.
The /SILENT qualifier overrides /SOURCE.
/SOURCE
/NOSOURCE (default)
Controls whether the source line for the current location is displayed
at the tracepoint. The /SOURCE qualifier specifies that the source line
is displayed. The /NOSOURCE qualifier specifies that the source line is
not displayed. The /SILENT qualifier overrides /SOURCE. See also the
SET STEP [NO]SOURCE command.
/SYSTEM (default)
/NOSYSTEM
Qualifies /INTO. Use with /INTO and one of the following qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
The /SYSTEM qualifier permits the debugger to set tracepoints within
system routines (P1 space) as well as other routines. The /NOSYSTEM
qualifier specifies that tracepoints not be set within system routines.
/TEMPORARY
Causes the tracepoint to disappear after it is triggered (the
tracepoint does not remain permanently set).
/TERMINATING
(Default) Causes the debugger to trace when a process does an image
exit. The debugger gains control and displays its prompt when the last
image of a one-process or multiprocess program exits. See also the
/ACTIVATING qualifier.
/VECTOR_INSTRUCTION
(VAX only) Causes the debugger to trace every vector instruction
encountered during execution. See also the /INTO and /OVER qualifiers.
Description
When a tracepoint is triggered, the debugger takes the following
actions:
- Suspends program execution at the tracepoint location.
- If you specified /AFTER when you set the tracepoint, checks the
AFTER count. If the specified number of counts has not been reached,
execution is resumed and the debugger does not perform the remaining
steps.
- Evaluates the expression in a WHEN clause, if you specified one
when you set the tracepoint. If the value of the expression is false,
execution is resumed and the debugger does not perform the remaining
steps.
- Reports that execution has reached the tracepoint location by
issuing a "trace..." message, unless you specified /SILENT.
- Displays the line of source code corresponding to the tracepoint,
unless you specified /NOSOURCE or /SILENT when you set the tracepoint
or entered a previous SET STEP NOSOURCE command.
- Executes the commands in a DO clause, if you specified one when you
set the tracepoint.
- Resumes execution.
You set a tracepoint at a particular location in your program by
specifying an address expression with the SET TRACE command. You set a
tracepoint on consecutive source lines, classes of instructions, or
events by specifying a qualifier with the SET TRACE command. Generally,
you must specify either an address expression or a qualifier, but not
both. Exceptions are /EVENT and /RETURN.
The /LINE qualifier sets a tracepoint on each line of source code.
The following qualifiers set tracepoints on classes of instructions.
Using these qualifiers and /LINE causes the debugger to trace every
instruction of your program as it executes and thus significantly slows
down execution.
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/RETURN
/SYSEMULATE (Alpha only)
/VECTOR_INSTRUCTION (VAX only)
The following qualifiers set tracepoints on classes of events:
/ACTIVATING
/EVENT=event-name
/EXCEPTION
/TERMINATING
The following qualifiers affect what happens at a routine call:
/INTO
/[NO]JSB (VAX only)
/OVER
/[NO]SHARE
/[NO]SYSTEM
The following qualifiers affect what output is displayed when a
tracepoint is reached:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect the timing and duration of tracepoints:
/AFTER:n
/TEMPORARY
Use the /MODIFY qualifier to monitor changes at program locations
(typically changes in the values of variables).
If you set a tracepoint at a location currently used as a breakpoint,
the breakpoint is canceled in favor of the tracepoint, and conversely.
Tracepoints can be user defined or predefined. User-defined tracepoints
are set explicitly with the SET TRACE command. Predefined tracepoints,
which depend on the type of program you are debugging (for example, Ada
or multiprocess), are established automatically when you start the
debugger. Use the SHOW TRACE command to identify all tracepoints that
are currently set. Any predefined tracepoints are identified as such.
User-defined and predefined tracepoints are set and canceled
independently. For example, a location or event can have both a
user-defined and a predefined tracepoint. Canceling the user-defined
tracepoint does not affect the predefined tracepoint, and conversely.
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) TRACE
CANCEL ALL
GO
SET BREAK
(SET,SHOW) EVENT_FACILITY
SET STEP [NO]SOURCE
SET WATCH
Examples
|
