Document revision date: 19 July 1999

The debugger assumes that the called routine conforms to the procedure calling standard (see the OpenVMS Calling Standard). However, the debugger does not know about all the argument-passing mechanisms for all supported languages. Therefore, you might need to specify how to pass parameters, for example, use CALL SUB1(%VAL X) rather than CALL SUB1(X). For complete information about how arguments are passed to routines, see your language documentation.

When the current language is C or C++, the CALL command by default now passes arguments by value rather than by reference. In addition, you can now pass the following arguments without using a passing mechanism lexical (such as %REF or %VAL):

• Routine references
• Quoted strings (treated as %REF strings)
• Structures, records, and objects
• Floating-point parameters by value in F_, D_, G_, S_, and T_floating format by dereferencing a variable of that type.

If the routine contains parameters that are not read-only, the values assigned to parameters may not be visible, and access to values is unreliable. This is because the debugger adjusts parameter values in an internal argument list, not the program argument list. To examine changing values, consider using static variables instead of parameters.

The CALL command converts all floating-point literals to F_floating format. Passing a floating-point literal in a format other than F_floating is not supported. (See the example below.)

A common debugging technique at an exception breakpoint (resulting from a SET BREAK/EXCEPTION or STEP/EXCEPTION command) is to call a dump routine with the CALL command. When you enter the CALL command at an exception breakpoint, any breakpoints, tracepoints, or watchpoints that were previously set within the called routine are temporarily disabled so that the debugger does not lose the exception context. However, such eventpoints are active if you enter the CALL command at a location other than an exception breakpoint.

When an exception breakpoint is triggered, execution is suspended before any application-declared condition handler is invoked. At an exception breakpoint, entering a GO or STEP command after executing a routine with the CALL command causes the debugger to resignal the exception (see the GO and STEP commands).

On Alpha processors, you cannot debug routines that are activated before the routine activated by a CALL command. For example, your program is stopped in routine MAIN, and you set a breakpoint in routine SORT. You issue the debugger command CALL SORT. While debugging routine SORT, you cannot debug routine MAIN. You must first return from the call to routine SORT.

If you are using the multiprocess debugging configuration to debug a multiprocess program (if the logical name DBG$PROCESS has the value MULTIPROCESS), the CALL command is executed in the context of the visible process, but images in any other processes that are not on hold (through a SET PROCESS/HOLD command) are also allowed to execute. If you use the DO command to broadcast a CALL command to one or more processes, the CALL command is executed in the context of each specified process that is not on hold, but images in any other processes that are not on hold are also allowed to execute. In all cases, a hold condition in the visible process is ignored.

If you are using the multiprocess debugging configuration to debug a multiprocess program, the way in which execution continues in your process depends on whether you entered a SET MODE [NO]INTERRUPT command. By default (SET MODE INTERRUPT), execution continues until it is suspended in any process. At that point, execution is interrupted in any other processes that were executing images, and the debugger prompts for input.

Related commands:

• GO
• EXIT
• DO
• SET PROCESS
• SET MODE [NO]INTERRUPT
• SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only)
• STEP
• SYNCHRONIZE VECTOR_MODE (VAX only)

Examples

DBG> CALL SUB1(X)
value returned is 19
DBG>
      

This command calls routine SUB1, with parameter X (by default, the address of X is passed). In this case, the routine returns the value 19.

DBG> CALL SUB(%REF 1)
value returned is 1
DBG>
      

This command passes a pointer to a memory location containing the numeric literal 1, into the routine SUB.

DBG> SET MODULE SHARE$LIBRTL
DBG> CALL LIB$SHOW_VM
 1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM, 122216 bytes 
 still allocated, value returned is 00000001
DBG>
      

This example calls Run-Time Library routine LIB$SHOW_VM (in shareable image LIBRTL) to display memory statistics. The SET MODULE command makes the universal symbols (routine names) in LIBRTL visible in the main image. See also the SHOW MODULE/SHARE command.

DBG> CALL testsub (%val 11.11, %val 22.22, %val 33.33)
      

This example passes floating-point parameters by value, to a C subroutine with the function prototype void testsub (float, float, float). The floating-point parameters are passed in F_floating format.

     SUBROUTINE CHECK_TEMP(TEMPERATURE,ERROR_MESSAGE) 
        REAL TOLERANCE /4.7/ 
        REAL TARGET_TEMP /92.0/ 
        CHARACTER*(*) ERROR_MESSAGE 
        IF (TEMPERATURE .GT. (TARGET_TEMP + TOLERANCE)) THEN 
           TYPE *,'Input temperature out of range:',TEMPERATURE 
           TYPE *,ERROR_MESSAGE 
        ELSE 
           TYPE *,'Input temperature in range:',TEMPERATURE 
        END IF 
     RETURN 
     END
DBG> CALL CHECK_TEMP(%REF 100.0, %DESCR 'TOLERANCE-CHECK 1 FAILED')
Input temperature out of range:   100.0000 
TOLERANCE-CHECK 1 FAILED 
value returned is 0
DBG> CALL CHECK_TEMP(%REF 95.2, %DESCR 'TOLERANCE-CHECK 2 FAILED')
Input temperature in range:   95.2000 
value returned is 0
DBG>
      

This Fortran routine (CHECK_TEMP) accepts two parameters, TEMPERATURE (a real number) and ERROR_MESSAGE (a string). Depending on the value of TEMPERATURE, the routine prints different output. Each CALL command passes a temperature value (by reference) and an error message (by descriptor). Because this routine does not have a formal return value, the value returned is undefined, in this case, 0.

Cancels all breakpoints, tracepoints, and watchpoints. Restores the scope and type to their default values. Restores the line, symbolic, and G_floating modes established with the SET MODE command to their default values.

Format

CANCEL ALL

Qualifiers

/PREDEFINED

Cancels all predefined (but no user-defined) breakpoints and tracepoints.

/USER

Cancels all user-defined (but no predefined) breakpoints, tracepoints, and watchpoints. This is the default unless you specify /PREDEFINED.

Description

The CANCEL ALL command does the following:

1. Cancels all user-defined eventpoints (those created with the commands SET BREAK, SET TRACE, and SET WATCH). This is equivalent to entering the commands CANCEL BREAK/ALL, CANCEL TRACE/ALL, and CANCEL WATCH/ALL. Depending on the type of program (for example Ada, multiprocess), certain predefined breakpoints or tracepoints might be set automatically when you start the debugger. To cancel all predefined but no user-defined eventpoints, use CANCEL ALL/PREDEFINED. To cancel all predefined and user-defined eventpoints, use CANCEL ALL/PREDEFINED/USER.
2. Restores the scope search list to its default value (0,1,2,...,n). This is equivalent to entering the CANCEL SCOPE command.
3. Restores the data type for memory locations that are associated with a compiler-generated type to the associated type. Restores the type for locations that are not associated with a compiler-generated type to "longword integer". This is equivalent to entering the CANCEL TYPE/OVERRIDE and SET TYPE LONGWORD commands.
4. Restores the line, symbolic, and G_floating modes established with the SET MODE command to their default values. This is equivalent to entering the following command:

   DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT

The CANCEL ALL command does not affect the current language setting or modules included in the run-time symbol table.

Related commands:

• (CANCEL,DEACTIVATE) BREAK
• CANCEL SCOPE
• (CANCEL,DEACTIVATE) TRACE
• CANCEL TYPE/OVERRIDE
• (CANCEL,DEACTIVATE) WATCH
• (SET,CANCEL) MODE
• SET TYPE

Examples

DBG> CANCEL ALL
      

This command cancels all user-defined breakpoints and tracepoints and all watchpoints, and restores scopes, types, and some modes to their default values. In this example, there are no predefined breakpoints or tracepoints.

DBG> CANCEL ALL
%DEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled
      

This command cancels all user-defined breakpoints and tracepoints and all watchpoints, and restores scopes, types, and some modes to their default values. In this example, there is a predefined breakpoint or tracepoint; this is not canceled by default.

DBG> CANCEL ALL/PREDEFINED
      

This command cancels all predefined breakpoints and tracepoints, and restores scopes, types, and some modes to their default values. No user-defined breakpoints or tracepoints are affected.

Cancels a breakpoint.

Format

CANCEL BREAK [address-expression[,...]]

Parameters

address-expression

Specifies a breakpoint to be canceled. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER.

Qualifiers

/ACTIVATING

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Cancels the effect of a previous SET BREAK/ACTIVATING command.

/ALL

By default, cancels all user-defined breakpoints. When used with /PREDEFINED, cancels all predefined breakpoints but no user-defined breakpoints. To cancel all breakpoints, use CANCEL BREAK/ALL/USER/PREDEFINED.

/BRANCH

Cancels the effect of a previous SET BREAK/BRANCH command.

/CALL

Cancels the effect of a previous SET BREAK/CALL command.

/EVENT=event-name

Cancels the effect of a previous SET BREAK/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET BREAK/EVENT command. To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command.

/EXCEPTION

Cancels the effect of a previous SET BREAK/EXCEPTION command.

/HANDLER

Cancels the effect of a previous SET BREAK/HANDLER command.

/INSTRUCTION

Cancels the effect of a previous SET BREAK/INSTRUCTION command.

/LINE

Cancels the effect of a previous SET BREAK/LINE command.

/PREDEFINED

Cancels a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, cancels all predefined breakpoints.

/SYSEMULATE

(Alpha only) Cancels the effect of a previous SET BREAK/SYSEMULATE command.

/TERMINATING

Cancels the effect of a previous SET BREAK/TERMINATING command.

/UNALIGNED_DATA

(Alpha only) Cancels the effect of a previous SET BREAK/UNALIGNED_DATA command.

/USER

Cancels a specified user-defined breakpoint without affecting any predefined breakpoints. This is the default unless you specify /PREDEFINED. To cancel all user-defined breakpoints, use the /ALL qualifier.

/VECTOR_INSTRUCTION

(VAX only) Cancels the effect of a previous SET BREAK/VECTOR_INSTRUCTION command.

Description

Breakpoints can be user defined or predefined. User-defined breakpoints are set explicitly with the SET BREAK command. Predefined breakpoints, which depend on the type of program you are debugging (for example, Ada or ZQUIT multiprocess), are established automatically when you start the debugger. Use the SHOW BREAK command to identify all breakpoints that are currently set. Any predefined breakpoints are identified as such.

User-defined and predefined breakpoints are set and canceled independently. For example, a location or event can have both a user-defined and a predefined breakpoint. Canceling the user-defined breakpoint does not affect the predefined breakpoint, and conversely.

To cancel only user-defined breakpoints, do not specify /PREDEFINED with the CANCEL BREAK command (the default is /USER). To cancel only predefined breakpoints, specify /PREDEFINED but not /USER. To cancel both predefined and user-defined breakpoints, specify both /PREDEFINED and /USER.

In general, the effect of the CANCEL BREAK command is symmetrical with that of the SET BREAK command (even though the SET BREAK command is used only with user-defined breakpoints). Thus, to cancel a breakpoint that was established at a specific location, specify that same location (address expression) with the CANCEL BREAK command. To cancel breakpoints that were established on a class of instructions or events, specify the class of instructions or events with the corresponding qualifier (/LINE, /BRANCH, /ACTIVATING, /EVENT=, and so on). For more information, see the qualifier descriptions.

If you want the debugger to ignore a breakpoint without your having to cancel it (for example, if you want to rerun the program with and without breakpoints), use the DEACTIVATE BREAK instead of the CANCEL BREAK command. Later, you can activate the breakpoint (with ACTIVATE BREAK).

Related commands:

• (ACTIVATE,DEACTIVATE) BREAK
• CANCEL ALL
• (SET,SHOW) BREAK
• (SET,SHOW) EVENT_FACILITY
• (SET,SHOW,CANCEL) TRACE

Examples

DBG> CANCEL BREAK MAIN\LOOP+10
      

This command cancels the user-defined breakpoint set at the address expression MAIN\LOOP+10.

DBG> CANCEL BREAK/ALL
      

This command cancels all user-defined breakpoints.

DBG> CANCEL BREAK/ALL/USER/PREDEFINED
      

This command cancels all user-defined and predefined breakpoints.

DBG_1> CANCEL BREAK/ACTIVATING
      

This command cancels a previous user-defined SET BREAK/ACTIVATING command. As a result, the debugger does not suspend execution when a new process is brought under debugger control.

DBG> CANCEL BREAK/EVENT=EXCEPTION_TERMINATED/PREDEFINED
      

This command cancels the predefined breakpoint set on task terminations due to unhandled exceptions. This breakpoint is predefined for Ada programs and programs that call DECthreads or Ada routines.

Permanently deletes a screen display.

Note This command is not available in the DECwindows Motif interface to the debugger.

Format

CANCEL DISPLAY [display-name[,...]]

Parameters

display-name

Specifies the name of a display to be canceled. Do not specify the PROMPT display, which cannot be canceled. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify a display name with /ALL.

Qualifiers

/ALL

Cancels all displays, except the PROMPT display.

/SUFFIX[=process-identifier-type]

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Appends a process-identifying suffix to a display name. Use this qualifier only directly after a display name. The suffix denotes the visible process at the time the command was issued.

The /SUFFIX qualifier is used primarily in command procedures when you specify display definitions or key definitions that are bound to display definitions.

Use any of the following process-identifier-type keywords:

PROCESS_NAME	The display-name suffix is the process name.
PROCESS_NUMBER	The display-name suffix is the process number (as shown in a SHOW PROCESS display).
PROCESS_PID	The display-name suffix is the process identifier (PID).

If you specify /SUFFIX without a process-identifier-type keyword, the process identifier type used for the display-name suffix is, by default, the same as that used for the prompt suffix (see the SET PROMPT/SUFFIX command).

Description

When a display is canceled, its contents are permanently lost, it is deleted from the display list, and all the memory that was allocated to it is released.

You cannot cancel the PROMPT display.

Related commands:

• (SHOW) DISPLAY
• (SET,SHOW,CANCEL) WINDOW

Examples

DBG> CANCEL DISPLAY SRC2
      

This command deletes display SRC2.

DBG> CANCEL DISPLAY/ALL
      

This command deletes all displays, except the PROMPT display.

Deletes symbol table information for a shareable image.

Format

CANCEL IMAGE [image-name[,...]]

Parameters

image-name

Specifies a previously set shareable image to be canceled. Do not specify the main image, which cannot be canceled. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an image name with /ALL.

Qualifiers

/ALL

Specifies that all shareable images except the main image are to be canceled.

Description

The CANCEL IMAGE command deallocates the data structures previously built to debug a shareable image by a SET IMAGE command. Use the CANCEL IMAGE command if the debugger performance has slowed down because of many images and modules being set. You can also use the CANCEL MODULE command to delete only certain modules from an image's run-time symbol table (RST) without canceling the entire image. Also, if dynamic mode is enabled (which is the default), you can disable it with the SET MODE NODYNAMIC command. As a result, the debugger does not set images or modules automatically.

If the current image (the image last set with the SET IMAGE command) is canceled, the main image (the image containing the image transfer address) becomes the current image.

Related commands:

• (SET,SHOW) IMAGE
• SET MODE [NO]DYNAMIC
• (SET,SHOW,CANCEL) MODULE

Example

DBG> CANCEL IMAGE SHARE2,SHARE3
      

This command cancels shareable images SHARE2 and SHARE3. If either of these was the current image, the main image becomes the current image.

Restores the line, symbolic, and G_floating modes established by the SET MODE command to their default values. Also restores the default input/output radix.

Note This command is not available in the DECwindows Motif interface to the debugger.

Format

CANCEL MODE

Description

The effect of the CANCEL MODE command is equivalent to the following commands:

DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT DBG> CANCEL RADIX

The default radix for both data entry and display is decimal for most languages.

On VAX processors, the exceptions are BLISS and MACRO--32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO--32, and MACRO--64, which have a default radix of hexadecimal.

Related commands:

• (SET,SHOW) MODE
• (SET,SHOW,CANCEL) RADIX

Example

DBG> CANCEL MODE
      

This command restores the default radix mode and all default mode values.

	privacy and legal statement
4538PRO_040.HTML