Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Debugger Manual


Previous Contents Index

In this example, the SET SOURCE command specifies that the debugger should search directories [PROJA], [PROJB], and [PETER.PROJC], in that order, for the latest version of source files.
#2

DBG> SET SOURCE/MODULE=CTEST/EXACT [],SYSTEM::DEVICE:[PROJD]
DBG> SHOW SOURCE
   source directory search list for CTEST, 
    match the exact source file version: 
        [] 
        SYSTEM::DEVICE:[PROJD] 
    source directory list for all other modules, 
    match the latest source file version: 
        [PROJA] 
        [PROJB] 
        [PETER.PROJC]
      

In this continuation of the previous example, the SET SOURCE/MODULE=CTEST command specifies that the debugger should search the current default directory ([]) and SYSTEM::DEVICE:[PROJD], in that order, for source files to use with the module CTEST. The /EXACT qualifier specifies that the search will try to locate the exact version of the CTEST source files found in the debug symbol table.

#3

DBG> SET SOURCE /EXACT
DBG> SHOW SOURCE
    no directory search list in effect, 
     match the exact source file
DBG> SET SOURCE [JONES]
DBG> SHOW SOURCE
    source directory list for all modules, 
     match the exact source file version: 
         [JONES]
DBG> CANCEL SOURCE /EXACT
DBG> SHOW SOURCE 
     source directory list for all modules, 
     match the latest source file version: 
         [JONES]
      

In this example, the SET SOURCE/EXACT command establishes a search method (exact version) that remains in effect for the SET SOURCE [JONES] command. The CANCEL SOURCE/EXACT command not only cancels SET SOURCE/EXACT command, but also affects the SET SOURCE [JONES] command.


SET STEP

Establishes default qualifiers (/LINE, /INTO, and so on) for the STEP command.

Format

SET STEP step-default[,...]


Parameters

step-default

Specifies a default to be established for the STEP command. Valid keywords (which correspond to STEP command qualifiers) are as follows:
BRANCH Subsequent STEP commands are treated as STEP/BRANCH (step to the next branch instruction).
CALL Subsequent STEP commands are treated as STEP/CALL (step to the next call instruction).
EXCEPTION Subsequent STEP commands are treated as STEP/EXCEPTION (step to the next exception).
INSTRUCTION Subsequent STEP commands are treated as STEP/INSTRUCTION (step to the next instruction).

On VAX processors, you can also specify one or more instructions ( opcode[,...]). The debugger then steps to the next instruction in the specified list.

On VAX processors, if you specify a vector instruction, do not include an instruction qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION, /MODIFY, /0, or /1) with the instruction mnemonic.

INTO Subsequent STEP commands are treated as STEP/INTO (step into called routines) rather than STEP/OVER (step over called routines). When INTO is in effect, you can qualify the types of routines to step into by using the [NO]JSB, [NO]SHARE, and [NO]SYSTEM parameters, or by using the STEP/[NO]JSB, STEP/[NO]SHARE, and STEP/[NO]SYSTEM command/qualifier combinations (the latter three take effect only for the immediate STEP command).
JSB (VAX only) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/JSB (step into routines called by a JSB instruction as well as those called by a CALL instruction). This is the default for all languages except DIBOL.
NOJSB (VAX only) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/NOJSB (step over routines called by a JSB instruction, but step into routines called by a CALL instruction). This is the default for DIBOL.
LINE (Default) Subsequent STEP commands are treated as STEP/LINE (step to the next line).
OVER (Default) Subsequent STEP commands are treated as STEP/OVER (step over all called routines) rather than STEP/INTO (step into called routines).
RETURN Subsequent STEP commands are treated as STEP/RETURN (step to the return instruction of the routine that is currently executing---that is, up to the point just prior to transferring control back to the calling routine).
SEMANTIC_EVENT (Alpha only) Subsequent STEP commands are treated as STEP/SEMANTIC_EVENT (step to the next semantic event). This simplifies debugging optimized programs (see Chapter 14 for more information).
SHARE (Default) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/SHARE (step into called routines in shareable images as well as into other called routines).
NOSHARE If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/NOSHARE (step over called routines in shareable images, but step into other routines).
SILENT Subsequent STEP commands are treated as STEP/SILENT (after a step, do not display the "stepped to..." message or the source line for the current location).
NOSILENT (Default) Subsequent STEP commands are treated as STEP/NOSILENT (after a step, display the "stepped to..." message).
SOURCE (Default) Subsequent STEP commands are treated as STEP/SOURCE (after a step, display the source line for the current location). Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands are treated as SET BREAK/SOURCE, SET TRACE/SOURCE, and SET WATCH/SOURCE, respectively (at a breakpoint, tracepoint, or watchpoint, display the source line for the current location).
NOSOURCE Subsequent STEP commands are treated as STEP/NOSOURCE (after a step, do not display the source line for the current location). Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands are treated as SET BREAK/NOSOURCE, SET TRACE/NOSOURCE, and SET WATCH/NOSOURCE, respectively (at a breakpoint, tracepoint, or watchpoint, do not display the source line for the current location).
SYSTEM (Default) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/SYSTEM (step into called routines in system space (P1 space) as well as into other called routines).
NOSYSTEM If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/NOSYSTEM (step over called routines in system space, but step into other routines).
VECTOR_INSTRUCTION (VAX only) On VAX processors, subsequent STEP commands are treated as STEP/VECTOR_INSTRUCTION (step to the next vector instruction).

Description

The SET STEP command establishes default qualifiers for subsequent STEP commands. The parameters that you specify in the SET STEP command have the same names as the qualifiers for the STEP command. The following parameters affect where the STEP command suspends execution after a step:

The following parameters affect what output is seen when a STEP command is executed:

The following parameters affect what happens at a routine call:

You can override the current STEP defaults for the duration of a single STEP command by specifying other qualifiers. Use the SHOW STEP command to identify the current STEP defaults.

Enabling screen mode by pressing PF1-PF3 enters the SET STEP NOSOURCE command as well as the SET MODE SCREEN command. Therefore, any display of source code in output and DO displays that would result from a STEP command or from a breakpoint, tracepoint, or watchpoint being triggered is suppressed, to eliminate redundancy with the source display.

On VAX systems, the STEP/OVER command may sometimes result in stepping into, not over, Fortran Run-Time Library routines. For more information, see Chapter 14.

Related commands:


Examples

#1

DBG> SET STEP INSTRUCTION,NOSOURCE
      

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:

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 DEC 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 DECthreads 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 DEC Ada on VAX only. For DECthreads programs or DEC Ada on Alpha programs, use one of the following alternatives:

/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 DECthreads synchronization event. This qualifier does not affect a task's scheduling policy.

/RESTORE

(DEC 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 DEC 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:


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 DECwindows Motif 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:


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:

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

(Default) Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). 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 DECthreads 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):


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4538PRO_056.HTML