hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems

Jump to content

HP OpenVMS System Analysis Tools Manual

HP OpenVMS System Analysis Tools Manual

Previous Contents Index


Formats and types a single line to SYS$OUTPUT.


int sda$type (char *ctrstr, __optional_params);



OpenVMS usage char_string
type character-coded text string
access read only
mechanism by reference

Address of a zero-terminated FAO control string.


OpenVMS usage varying_arg
type quadword (signed or unsigned)
access read only
mechanism by value

Optional FAO parameters. All arguments after the control string are copied into a quadword parameter list, as used by $FAOL_64.


Formats and prints a single line to the terminal. This is unaffected by the use of the SDA commands SET OUTPUT or SET LOG.

Condition Values Returned

SDA$_SUCCESS Indicates a successful completion.
SDA$_CNFLTARGS Indicates more than twenty FAO parameters given.
Other Returns from the $PUT issued by SDA$TYPE (the error is also signaled). If the $FAOL_64 call issued by SDA$TYPE fails, the control string is output.


int status; 
status = sda$type ("Invoking SHOW SUMMARY to output file..."); 

This example displays the message "Invoking SHOW SUMMARY to output file..." to the terminal.


Validates queue structures.


void sda$validate_queue (VOID_PQ queue_header, __optional_params);



OpenVMS usage address
type quadword (unsigned)
access read only
mechanism by value

Address from which to start search.


OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by value

The following table shows the flags that indicate the type of queue:
Flag Meaning
None Defaults to doubly-linked longword queue
SDA_OPT$M_QUEUE_BACKLINK Validates the integrity of a doubly-linked queue using the back links instead of the forward links
SDA_OPT$M_QUEUE_LISTQUEUE Displays queue elements for debugging
SDA_OPT$M_QUEUE_QUADLINK Indicates a quadword queue
SDA_OPT$M_QUEUE_SELF Indicates a self-relative queue
SDA_OPT$M_QUEUE_SINGLINK Indicates a singly-linked queue


You can use this routine to validate the integrity of doubly-linked, singly-linked or self-relative queues either with longword or quadword links. If you specify the option SDA_OPT$M_QUEUE_LISTQUEUE, the queue elements are displayed for debugging. Otherwise a one-line summary indicates how many elements were found and whether the queue is intact.

Condition Values Returned


If an error occurs, it is signaled by SDA$VALIDATE_QUEUE.


int64 temp; 
int64 *queue; 
sda$symbol_value ("EXE$GL_NONPAGED", &temp); 
temp += 4; 
sda$reqmem ((VOID_PQ)temp, &queue, 4); 
sda$validate_queue (queue, SDA_OPT$M_QUEUE_SINGLINK); 

This sequence validates the nonpaged pool free list, and outputs a message of the form:

        Queue is zero-terminated, total of 204 elements in the queue 

Part 2
OpenVMS Alpha System Code Debugger and System Dump Debugger

Part II describes the System Code Debugger (SCD) and the System Dump Debugger (SDD). It presents how to use SCD and SDD by doing the following:

Chapter 11
OpenVMS System Code Debugger

This chapter describes the OpenVMS System Code Debugger (SCD) and how it can be used to debug nonpageable system code and device drivers running at any interrupt priority level (IPL).

You can use SCD to perform the following tasks:

The use of SCD requires two systems:

SCD is a symbolic debugger. You can specify variable names, routine names, and so on, precisely as they appear in your source code. SCD can also display the source code where the software is executing, and allow you to step by source line.

SCD recognizes the syntax, data typing, operators, expressions, scoping rules, and other constructs of a given language. If your code or driver is written in more than one language, you can change the debugging context from one language to another during a debugging session.

To use SCD, you must do the following:

The following sections cover these tasks in more detail, describe the available user-interface options, summarize applicable OpenVMS Debugger commands, and provide a sample SCD session.

11.1 User-Interface Options

SCD has the following user-interface options:

For more information about using the OpenVMS DECwindows Motif interface and OpenVMS Debugger commands with SCD, see the HP OpenVMS Debugger Manual.

11.2 Building a System Image to Be Debugged

  1. Compile the sources you want to debug, and be sure to use the /DEBUG and /NOOPT qualifiers.


    Debugging optimized code is much more difficult and is not recommended unless you know the Alpha or I64 architecture well. The instructions are reordered so much that single-stepping by source line will look like you are randomly jumping all over the code. Also note that you cannot access all variables. SCD reports that they are optimized away.
  2. Link your image using the /DSF (debug symbol file) qualifier. Do not use the /DEBUG qualifier, which is for debugging user programs. The /DSF qualifier takes an optional filename argument similar to the /EXE qualifier. For more information, see the HP OpenVMS Linker Utility Manual. If you specify a name in the /EXE qualifier, you will need to specify the same name for the /DSF qualifier. For example, you would use the following command:


    The .DSF and .EXE file names must be the same. Only the extensions will be different, that is .DSF and .EXE.
    The contents of the .EXE file should be exactly the same as if you had linked without the /DSF qualifier. The .DSF file will contain the image header and all the debug symbol tables for .EXE file. It is not an executable file, and cannot be run or loaded.

  3. Put the .EXE file on your target system.
  4. Put the .DSF file on your host system, because when you use SCD to debug code in your image, it will try to look for a .DSF file first and then look for an .EXE file. The .DSF file is better because it has symbols in it. Section 11.4 describes how to tell SCD where to find your .DSF and .EXE files.

11.3 Setting Up the Target System for Connections

The target kernel is controlled by flags and devices specified when the system is booted, by XDELTA commands, by a configuration file, and by several system parameters. The following sections contain more information about these items.

Boot Flags

You can specify flags on the boot command line. Boot flags are specified as a hex number; each bit of the number represents a true or false value for a flag. The following flag values are relevant to the system code debugger.

Boot Command

The form of the boot command varies depending on the platform and type OpenVMS system. However, all SCD boot commands have the concept of boot flags, boot device, and dedicated Ethernet device. In all environments, you must specify an Ethernet device on the target system to use to communicate with the host debugger. It is currently a restriction that this device must not be used for anything else (either for booting or network software such as DECnet, TCP/IP products, and LAT products).

To use Alpha SCD, you must specify the Ethernet device with boot command. In this example, we are using DEC 3000 Model 400 Alpha Workstation syntax. We are booting from the DKB100 disk and using the ESA0 Ethernet device. We are also setting the SCD, XDELTA, and initial (earliest) breakpoint flags:

        >>> show device 
        >>> boot dkb100,esa0 -fl 0,8006 

You can set these devices and flags to be the default values so that you will not have to specify them each time you boot:

        >>> set bootdef_dev dkb100,esa0 
        >>> set boot_osflags 0,8006 

To use I64 SCD, you can specify an Ethernet device (debug_dev) BEFORE loading the Operating System and AFTER you have selected the device/partition. Setting debug_dev is sticky. That is, you only need to set it once. Using a HP rx2600 syntax:

A sample I64 Boot Menu follows.

                Please select a boot option 
            EFI Shell [Built-in] 
            PESOS - X8.2-AHI (Topaz BL2) on $1$DGA3890:[SYS2.] 
            PESOS - X8.2-AHI (Topaz BL2) on $1$DGA3890:[SYS2.] sysboot 
            PESOS - E8.2-ADH (Topaz BL1) on $1$DGA3891:[SYS2.] 
            PESOS - E8.2-ADH (Topaz BL1) on $1$DGA3891:[SYS2.] sysboot 
            Boot Option Maintenance Menu 
            System Configuration Menu 

Select the EFI Shell [Built-in].

        Loading.: EFI Shell [Built-in] 
        EFI Shell version 1.10 [14.61] 
        Device mapping table 
          fs0   : Acpi(HWP0002,100)/Pci(1|0)/Scsi(Pun0,Lun0)/HD(Part1,SigA02952 
          fs1   : Acpi(HWP0002,300)/Pci(1|0)/Fibre(WWN50001FE10011B15D,Lun2200) 
          fs2   : Acpi(HWP0002,300)/Pci(1|0)/Fibre(WWN50001FE10011B15D,Lun2200) 
          fs3   : Acpi(HWP0002,300)/Pci(1|0)/Fibre(WWN50001FE10011B15D,Lun2300) 

Select the desired device/partition:

        Shell> fs1: 

Use the utilities in \efi\vms. Use vms_show to list the devices and vms_set to set Ethernet device (debug_dev), if necessary.

fs1:\> \efi\vms\vms_show device 
EFI: Acpi(000222F0,0)/Pci(3|0)/Mac(00306E39F77B) 
VMS: DKB200 
EFI: fs1: Acpi(000222F0,100)/Pci(1|1)/Scsi(Pun2,Lun0) 
EFI: fs0: Acpi(000222F0,100)/Pci(1|1)/Scsi(Pun0,Lun0) 
EFI: Acpi(000222F0,100)/Pci(2|0)/Mac(00306E3977C5) 

Set the Ethernet device.

fs1:\> \efi\vms\vms_set debug_dev eia0 
VMS: EIA0               0-30-6E-39-F7-CF 
EFI: Acpi(000222F0,0)/Pci(3|0)/Mac(00306E39F7CF) 

Finally, load the OS. In this example, the boot is with the SCD and initial (earliest) breakpoint flags using root 2 (SYS2), that will vary with system setups.

        fs1:\> \efi\vms\vms_loader -flags "2,8004" 

You can set the flags to be the default value instead of specifying them for each and every OS load:

        fs1:\> set vms_flags "2,8004" 

You can also build the entire boot device, OS load command with flags setting as a Boot Option. See the Boot Option Maintenance Menu.

SCD Configuration File

The SCD target system reads a configuration file in SYS$SYSTEM named DBGTK$CONFIG.SYS. The first line of this file contains a default password, which must be specified by the host debug system to connect to the target. The default password may be the null string; in this case the host must supply the null string as the password (/PASSWORD="") on the connect command as described in Section 11.5, or no password at all. Other lines in this file are reserved by HP. Note that you must create this file because HP does not supply it. If this file does not exist prior to booting with SCD enabled, you can only run SCD by specifying a default password with the XDELTA ;R command described in the following section.

XDELTA Commands

When the system is booted with both the XDELTA boot flag and the SCD boot flag, the following two additional XDELTA commands are enabled:

SYSTEM Parameters

11.3.1 Making Connections Between the Target Kernel and the System Code Debugger

It is always SCD on the host system that initiates a connection to the target kernel. When SCD initiates this connection, the target kernel accepts or rejects the connection based on whether the remote debugger presents it with a node name and password that matches the password in the target system (either the default password from the SYS$SYSTEM:DBGTK$CONFIG.SYS file, or a different password specified via XDELTA). SCD obtains the node name from the SCSNODE system parameter.

The target kernel can accept a connection from SCD any time the system is running below IPL 22, or if XDELTA is in control (at IPL 31). However, the target kernel actually waits at IPL 31 for a connection from the SCD host in two cases: when it has no existing connection to an SCD host and (1) it receives a breakpoint caused by a call to INI$BRK (including either of the initial breakpoints), or (2) when you enter a 1;R or -1;R command to XDELTA.

Previous Next Contents Index