OpenVMS Version 7.3 New Features and Documentation Overview

Document revision date: 30 March 2001

OpenVMS Version 7.3
New Features and Documentation Overview

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

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

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

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.

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.

**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

**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.

**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.

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

**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

**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.

Contents

Index

privacy and legal statement

6620PRO_007.HTML