Document revision date: 30 March 2001

## OpenVMS Version 7.3
New Features and Documentation Overview

Previous | Contents | Index

#### 5.14.2.11 SHOW RESOURCE

The SHOW RESOURCE command has the following new qualifier:

Qualifier | Meaning
--- | ---
/OWNED | Causes SDA to only display owned resources

#### 5.14.2.12 SHOW SPINLOCKS

The SHOW SPINLOCKS command has the following new qualifier:

Qualifier | Meaning
--- | ---
/COUNTS | Produces a display of Acquire, Spin, and Wait counts for each spinlock

#### 5.14.2.13 SHOW SUMMARY

The SHOW SUMMARY command has the following new qualifier:

Qualifier | Meaning
--- | ---
/PROCESS_NAME= process_name | Displays only processes with the specified process name. Wildcards can be used in process_name, in which case SDA displays all matching processes. The default action is for SDA to display data for all processes, regardless of process name.

## 5.15 New SDA Commands for the Spinlock Tracing Utility

The OpenVMS Version 7.3 software release includes the new Spinlock Tracing utility. With the implementation of this utility, you can now tell which spinlock is heavily used, and who is acquiring and releasing the contended spinlocks. The Spinlock Tracing utility allows a characterization of spinlock usage, as well as collection of performance data for a given spinlock on a per-CPU basis. The tracing ability can be enabled or disabled while the system is running, allowing the collection of spinlock data for a given period of time without system interruption.

To use the Spinlock Tracing utility, SDA has implemented new commands and qualifiers. These SDA commands and qualifiers are described as follows:

### 5.15.1 SPL LOAD

This command loads the SPL$DEBUG execlet. This must be done prior to starting spinlock tracing. It has no qualifiers.

### 5.15.2 SPL SHOW COLLECT

This command displays the data collected for a specific spinlock. It has no qualifiers.

### 5.15.3 SPL SHOW TRACE

This command displays spinlock tracing information. Table 5-3 shows the qualifiers for this command.

Table 5-3 Qualifiers for the SPL SHOW TRACE Command
Qualifier | Meaning
--- | ---
/SPINLOCK= spinlock | Specifies the display of a specific spinlock, for example, /SPINLOCK=LCKMGR or /SPINLOCK=SCHED.
/NOSPINLOCK | Specifies that no spinlock trace information be displayed. If omitted, all spinlock trace entries are decoded and displayed.
/FORKLOCK= forklock | Specifies the display of a specific forklock, for example, /FORKLOCK=IOLOCK8 or /FORKLOCK=IPL8.
/NOFORKLOCK | Specifies that no forklock trace information be displayed. If omitted, all fork trace entries are decoded and displayed.
/ACQUIRE | Displays any spinlock acquisitions.
/NOACQUIRE | Ignores any spinlock acquisitions.
/RELEASE | Displays any spinlock releases.
/NORELEASE | Ignores any spinlock releases.
/WAIT | Displays any spinwait operations.
/NOWAIT | Ignores any spinwait operations.
/FRKDSPTH | Displays all invocations of fork routines within the fork dispatcher. This is the default.
/NOFRKDSPTH | Ignores all of the operations of the /FRKDSPTH qualifier.
/FRKEND | Displays all returns from fork routines within the fork dispatcher. This is the default.
/NOFRKEND | Ignores all operations of the /FRKEND qualifier.
/SUMMARY | Stops the entire trace buffer and displays a summary of all spinlock and forklock activity. It also displays the top ten callers.
/CPU= n | Specifies the display of information for a specific CPU only, for example, /CPU=5 or /CPU=PRIMARY. By default, all trace entries for all CPUs are displayed.
/TOP= n | Displays a different number other than the top ten callers or fork PC. By default, the top ten are displayed. This qualifier is only useful when you also specify the /SUMMARY qualifier.

### 5.15.4 SPL START COLLECT

This command accumulates information for a specific spinlock. Table 5-4 shows the qualifiers for this command:

Table 5-4 Qualifiers for the SPL START COLLECT Command
Qualifier | Meaning
--- | ---
/SPINLOCK= spinlock | Specifies the tracing of a specific spinlock, for example, /SPINLOCK=LCKMGR or /SPINLOCK=SCHED
/ADDRESS= n | Specifies the tracing of a specific spinlock by address

### 5.15.5 SPL START TRACE

This command enables spinlock tracing. Table 5-5 shows the qualifiers for this command.

Table 5-5 Qualifiers for the SPL START TRACE Command
Qualifier | Meaning
--- | ---
/SPINLOCK= spinlock | Specifies the tracing of a specific spinlock.
/NOSPINLOCK | Disables spinlock tracing and does not collect any spinlock data. If omitted, all spinlocks are traced.
/FORKLOCK= forklock | Specifies the tracing of a specific forklock, for example, /FORKLOCK=IOLOCK8 or /FORKLOCK=IPL8.
/NOFORKLOCK | Disables forklock tracing and does not collect any forklock data. If omitted, all forks are traced.
/BUFFER= pages | Specifies the size of the trace buffer (in Alpha page units). It defaults to 128 pages, which is equivalent to 1MB, if omitted.
/ACQUIRE | Traces any spinlock acquisitions. This is the default.
/NOACQUIRE | Ignores any spinlock acquisitions.
/RELEASE | Traces any spinlock releases. This is the default.
/NORELEASE | Ignores any spinlock releases.
/WAIT | Traces any spinwait operations. This is the default.
/NOWAIT | Ignores any spinwait operations.
/FRKDSPTH | Traces all invocations of fork routines within the fork dispatcher. This is the default.
/NOFRKDSPTH | Ignores all of the /FRKDSPTH operations.
/FRKEND | Traces all returns from fork routines within the fork dispatcher. This is the default.
/NOFRKEND | Ignores all of the operations of the /FRKEND qualifier.
/CPU= n | Specifies the tracing of a specific CPU only, for example, /CPU=5 or /CPU=PRIMARY. By default, all CPUs are traced.

### 5.15.6 SPL STOP COLLECT

This command stops the spinlock collection, but does not stop spinlock tracing. It has no qualifiers.

### 5.15.7 SPL STOP TRACE

This command disables spinlock tracing, but it does not deallocate the trace buffer. It has no qualifiers.

### 5.15.8 SPL UNLOAD

This command unloads and cleans up the SPL$DEBUG execlet. Tracing is automatically disabled and the trace buffer deallocated. It has no qualifiers.

For more information, refer to the OpenVMS Alpha System Analysis Tools Manual.

## 5.16 System Services

The following table describes new and updated system services for OpenVMS Version 7.3.

For additional information, refer to the OpenVMS System Services Reference Manual.

System Service | Documentation Update
--- | ---
$CHECK_PRIVILEGES | The description of the 'prvadr' argument has been updated.
$CLRAST | This service has been documented for Version 7.3.
$DCLEXH | The description has been updated, and a BASIC example has been added.
$DELETE_INTRUSION | This service has been updated in support of Clusterwide Intrusion.
$DEVICE_PATH_SCAN | This is a new service in support of Multipath.
$DISMOU | The following item codes have been added: DMT$M_MINICOPY_REQUIRED, DMT$M_MINICOPY_OPTIONAL, and DMT$M_FORCE.
$EXPREG | The text for condition value, SS$_ILLPAGCNT, has been updated.
$GETDVI | The item codes, MT3_DENSITY and MT3_SUPPORTED, have been added. The item codes, DVI$_FC_NODE_NAME, DVI$_FC_PORT_NAME, and DVI$_WWID, have been added. The description for the DVI$_MOUNTCNT item code has been updated.
$GETJPI | The following item codes have been added: JPI$_RMS_DFMBC, JPI$_RMS_DFMBFIDX, JPI$_RMS_DFMBFREL, JPI$_RMS_DFMBFSDK, JPI$_RMS_DFMBFSMT, JPI$_RMS_DFMBFSUR, JPI$_RMS_DFNBC, JPI$_RMS_EXTEND_SIZE, JPI$_RMS_FILEPROT, and JPI$_RMS_PROLOGUE. The following item codes have been added for Multithreads support: JPI$_INITIAL_THREAD_PID, JPI$_KT_COUNT, JPI$_MULTITHREAD, and JPI$_THREAD_INDEX. The code example has been updated for VAX and Alpha usage.
$GETRMI | This is a new service in support of Performance API.
$GETQUI | The item code, QUI$V_JOB_REQUEUE, has been added.
$GETSYI | The item code, SYI$_SERIAL_NUMBER, has been added.
$IO_PERFORM | The 'porint' argument in the format section has been changed to 'devdata, to match the C prototype.
$MGBLSC | The text for the 'inadr' argument has been updated, and the SS$_INVARG condition value has been added.
$MOUNT | The following item codes have been added: MNT$M_MINICOPY_OPTIONAL, MNT$M_MINICOPY_REQUIRED, MNT$M_REQUIRE_MEMBERS, and MNT$M_VERIFY_LABELS.
$PERSONA_QUERY | Tables for Common, General, and NT item codes have been added.
$PROCESS_SCAN | The following item codes have been added for Multithreads support: PSCAN$_KT_COUNT and PSCAN$_MULTITHREAD.
$REGISTRY | This service is now documented in the OpenVMS System Services Reference Manual: GETUTC--Z and online help.
$SCAN_INTRUSION | This service has been updated in support of Clusterwide Intrusion.
$SCHED | The condition value, SS$_INCLASS, has been added, and SS$_ILLSER has been deleted.
$SET_DEVICE | This is a new service in support of Multipath.
$SET_SECURITY | The condition value, SS$_INVFILFOROP, has been added.
$SET_SYSTEM_EVENT | A new item code, SYSEVT$C_TDF_CHANGE, has been added.
$SHOW_INTRUSION | This service has been updated in support of Clusterwide Intrusion.
$WAKE | This service now accepts 64-bit addresses.

## 5.17 TCP/IP Files for SDA READ Command That Contain Global Symbols and Locations

Table 5-6 shows the TCP/IP files that contain global symbols for the VAX and Alpha SDA READ commands.

Table 5-6 Modules Containing Global Symbols and Data Structures Used by SDA
File | Contents
--- | ---
TCPIP$NET_GLOBALS.STB | Contains data structure definitions for TCP/IP Internet driver, execlet, and ACP data structures
TCPIP$NFS_GLOBALS.STB | Contains data structure definitions for TCP/IP NFS server
TCPIP$PROXY_GLOBALS.STB | Contains data structure definitions for TCP/IP proxy execlet
TCPIP$PWIP_GLOBALS.STB | Contains data structure definitions for TCP/IP PWIP driver, and ACP data structures
TCPIP$TN_GLOBALS.STB | Contains data structure definitions for TCP/IP TELNET/RLOGIN server driver data structures

These files are only available if TCP/IP services has been installed. They are found in SYS$SYSTEM, and are not automatically read in when you issue a READ/EXEC command.

Table 5-7 shows the TCP/IP files that define global locations within the Executive Image for the VAX SDA command.

Table 5-7 Modules Defining Global Locations Within the Executive Image
File | Contents
--- | ---
TCPIP$BGDRIVER.STB | TCP/IP Internet driver
TCPIP$INETACP.STB | TCP/IP Internet ACP
TCPIP$INTERNET_SERVICES.STB | TCP/IP Internet execlet
TCPIP$NFS_SERVICES.STB | Symbols for the TCP/IP NFS server
TCPIP$PROXY_SERVICES.STB | Symbols for the TCP/IP proxy execlet
TCPIP$PWIPACP.STB | TCP/IP PWIP ACP
TCPIP$PWIPDRIVER.STB | TCP/IP PWIP driver
TCPIP$TNDRIVER.STB | TCP/IP TELNET/RLOGIN server driver

These files are only available if TCP/IP services has been installed. They are found in SYS$SYSTEM, and are not automatically read in when you issue a READ/EXEC command.

For more detailed information, refer to the OpenVMS VAX System Dump Analyzer Utility Manual and the OpenVMS Alpha System Analysis Tools Manual.

## 5.18 Visual Threads Version 2.1 (Alpha)

Visual Threads is a unique tool that lets you debug and analyze multithreaded applications. You can use Visual Threads to automatically diagnose common problems associated with multithreading including deadlock, mutex, and thread usage errors. Also, you can use Visual Threads to monitor the thread-related performance of an application, helping you to identify bottlenecks or locking granularity problems. Visual Threads helps you identify problem areas in an application even if the application does not show specific symptoms.

Visual Threads includes the following features:

- Collects detailed information about significant thread-related state changes ("events").
- Analyzes common threading problems automatically based on predefined rules applied to the event stream.
- Rule customization for application-specific parameters and actions.
- Automatic statistics gathering, by sampling the event stream.
- Categories of analysis: data protection errors (race conditions), deadlocks, programming errors, lock activity, performance.
- Graphical visualization of the frequency of thread-related events and thread state, snapshots of historical program state, and object-specific graphs for each collected statistic.
- Lock activity profiling to reveal where various types of lock activity are occurring in your application, including: Number of Locks, Contended Locks, Locked Time, and Wait Time. Lock activity is collected and displayed for individual locks.
- Summarizes the program run and provides reports.
- Threads Snapshot view displays the historical state of threads represented at specific times in the main thread overview graph.
- Find and Filter support in the Event Window to allow you to quickly locate particular events.
- CPU Utilization Window shows the CPU percentage used by each thread.
- Thread Transitions Window depicts each state change for a detailed view.

For more information about these features, refer to the Visual Threads product documentation, which is available on the OpenVMS Alpha CD-ROM in directory [VISUAL_THREADS_021], or by using the online Help system.

Previous | Next | Contents | Index

| privacy and legal statement |
6620PRO_007.HTML