HP OpenVMS Systems Documentation

The new Multipath system services provide the capability to return path information and allow you to enable, disable, and switch specific I/O paths to any device.

The concept of multiple I/O paths to storage devices was introduced in OpenVMS Version 7.2-1. It is now possible to select more than one I/O path to a device in the event that the path in use should fail.

To assist in decision making when configuring a system's I/O structure, the following DCL commands were made available to allow you to display I/O path information and change the current settings affecting these paths:

• SET DEVICE device-name/PATH=path-description-string/SWITCH
• SET DEVICE device-name/PATH=path-description-string/[NO]ENABLE
• SHOW DEVICE/MULTIPATH device-name

In OpenVMS Version 7.3, the capability to return path information and allow you to enable, disable, and switch specific I/O paths to any device is now implemented in the following new system services:

• SYS$DEVICE_PATH_SCAN
  This service returns path information for a given Multipath I/O device. Each call to the service returns the name of one of the paths to the device. A context argument is used to maintain continuity between calls. This mechanism is similar to the one currently used for SYS$GETDVI.
• SYS$SET_DEVICE[W]
  Use this service to switch the selected path that handles I/O to a device, or to enable or disable a path for future use in the event of failover. When switching a path, the path change is initiated at the time the request is made by the system service.
  The current functions of this service include forcing an immediate path switch and enabling or disabling paths.
  A synchronous version of this service, SYS$SET_DEVICEW, is also provided. This service returns to the caller only after the path switch attempt has been made. Should the path switch fail, an error condition is returned to the caller.
  Currently, $SET_DEVICE allows only one valid item list entry.

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

5.8 Multiprocess Debugging (Alpha)

For Version 7.3, debugger support for multiprocess programs has been extensively overhauled. Problems have been corrected and the user interface has been improved.

The multiprocess debugging enhancements include the following features:

• Greater control over individual process and groups of processes, including:

  Execution of processes (or groups of processes)
  Suspension of processes (or groups of processes)
  Exiting processes (or groups of processes), with or without exit handler execution

• Ability to create user-defined groups of processes
• Easier to start a multiprocess debugging session; the default configuration of the kept debugger is for a multiprocess session
• Applications that use $HIBER WAIT (LIB$WAIT, $SCHDWK, and so on) can now be debugged in a multiprocess debugging session

These enhancements make it much easier to debug multiprocess programs.

5.9 Performance Application Programming Interface (API)

The Performance Application Programming Interface (API) provides a documented functional interface---the $GETRMI system service---that allows performance software engineers to access a predefined list of performance data items.

For more information about $GETRMI, refer to the OpenVMS System Services Manual.

5.10 POLYCENTER Software Installation Utility Enhancements

Table 5-1 shows the changes made to the product description language (PDL) for the POLYCENTER Software Installation utility.

The POLYCENTER Software Installation Utility Developer's Guide has been extensively revised for this release. Major improvements include:

• Updated descriptions for most PDL statements.
• A comprehensive presentation on using custom command procedures with execute statements (added to the Advanced Topics chapter).
• New tables, diagrams, and examples.

OpenVMS Version 7.3 contains new tools for processing dump files. Note that these new-style process dump and process dump analysis tools are not compatible with the old-style process dumps. That is, if you have a problem you want to analyze with the new tools, you must generate a new process dump using the new process dump image.

The following sections describe the new tools.

5.11.1 DCL ANALYZE/PROCESS_DUMP Command

The DCL ANALYZE/PROCESS_DUMP command invokes the OpenVMS debugger to analyze a process dump, giving you access to debugger commands for your analysis. In OpenVMS Version 7.3, most of the old DCL ANALYZE/PROCESS_DUMP qualifiers have no effect. Only the /FULL and /IMAGE qualifiers are still valid. Both these qualifiers are still optional.

/FULL now causes the debugger to execute the debugger SHOW IMAGE, SHOW CALL, and SHOW THREAD/ALL commands after a process dump file has been opened.

/IMAGE has been renamed to /IMAGE_PATH, and is now a directory specification, rather than a file specification. /IMPAGE_PATH specifies a directory in which to look for the debug symbol information files (.DSF or .EXE files, in that order) that belong to the process dump file. The name of the symbol file must be the same as the image name in the process dump file. For example, for MYIMAGE.DMP, the debugger searches for file MYIMAGE.DSF or MYIMAGE.EXE.

Version 7.3 and later debuggers check for dumpfile image specification and DST file link date-time mismatches and issue a warning if one is discovered.

For more information about the DCL ANALYZE/PROCESS_DUMP command, refer to the OpenVMS DCL Dictionary: A--M.

5.11.2 Debugger ANALYZE/PROCESS_DUMP Command

The debugger has a new command:

This command is available only in the kept debugger. The kept debugger is the image you invoke with the command DEBUG/KEEP, which allows you to run and rerun programs from the same debugging session.

The qualifier /PROCESS_DUMP is required.

For more information, refer to the OpenVMS Debugger Manual.

5.11.3 Debugger SDA Command

The new debugger SDA command invokes the System Dump Analyzer (SDA) to allow you to look at a process dump from within the OpenVMS debugger. For example:

 DBG> SDA

 OpenVMS (TM) Alpha process dump analyzer

 SDA> ..
 .
 .
 SDA> EXIT
 DBG>

This allows you to use SDA to analyze a process dump without terminating a debugger session.

For more information, refer to the OpenVMS Debugger Manual.

5.11.4 Analyzing Process Dumps on Different Systems

You can analyze a process dump file on a system different from the one on which it was generated. However, if there is a base image link date/time mismatch between the generating system and analyzing system, you must copy SYS$BASE_IMAGE.EXE from the generating system and point to it with the SDA$READ_DIR logical name. For example:

$ COPY other_node::SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE my_disk$:[my_dir]
$ DEFINE/USER SDA$READ_DIR my_disk$:[my_dir],SYS$SYSROOT:[SYS$LDR],SYS$SYSROOT:[SYSLIB]
$ ANALYZE/PROCESS_DUMP mycrash.dmp

For threaded process dump analysis on a system different from the one on which it was generated, it may also be necessary to copy and logically point to the generating system's PTHREAD$RTL and PTHREAD$DBGSHR (POSIX Threads Library debug assistant). For example:

$ COPY other_node::SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE my_disk$:[my_dir]
$ COPY other_node::SYS$SHARE:PTHREAD$RTL.EXE my_disk$:[my_dir]
$ COPY other_node::SYS$SHARE:PTHREAD$DBGSHR.EXE my_disk$:[my_dir]
$ DEFINE/USER SDA$READ_DIR my_disk$:[my_dir],SYS$SYSROOT:[SYS$LDR],SYS$SYSROOT:[SYSLIB]
$ DEFINE/USER PTHREAD$RTL my_disk$:[my_dir]PTHREAD$RTL.EXE
$ DEFINE/USER PTHREAD$DBGSHR my_disk$:[my_dir]PTHREAD$DBGSHR.EXE
$ ANALYZE/PROCESS_DUMP mycrash.dmp

You can force a process dump with the DCL command SET PROCESS/DUMP=NOW process-spec. This command causes the contents of the address space occupied by process-spec to be written immediately to the file named image-name.DMP in the current directory (image-name is the same as the file name).

For more information about the DCL SET PROCESS/DUMP command, refer to the OpenVMS DCL Dictionary: N--Z.

5.11.6 Process Dumps: Security and Diskquota Guidelines

A process dump is either complete or partial. A complete process dump contains all of process space and all process-pertinent data from system space. A partial process dump contains only user-readable data from process space and only those data structures from system space that are not deemed sensitive. Privileged or protected data, such as an encryption key in third-party software, might be considered sensitive.

In general, nonprivileged users should not be able to read complete process dumps, and by default they cannot do so. However, certain situations require nonprivileged users to be able to read complete process dumps. Other situations require enabling a user to create a complete process dump while at the same time preventing that user from being able to read the complete process dump.

By default, process dumps are written to the current default directory of the user. The user can override this by defining the logical name SYS$PROCDMP to identify an alternate directory path. Note that the name of the process dump file is always the same as the name of the main image at the time the process dump is written, with the file extension .DMP.

5.11.6.1 Special Rights Identifiers

You can use the new rights identifier IMGDMP$READALL to allow a nonprivileged user to read a complete process dump. You can use the new rights identifier IMGDMP$PROTECT to protect a complete process dump from being read by the user that created the process dump. These rights identifiers are created during the installation of OpenVMS Version 7.3 by the image SYS$SYSTEM:IMGDMP_RIGHTS.EXE, which is also run automatically during system startup to ensure that these rights identifiers exist with the correct values and attributes.

If these rights identifiers have been deleted, you can run SYS$SYSTEM:IMGDMP_RIGHTS.EXE to recreate them. For example:

    $ RUN SYS$SYSTEM:IMGDMP_RIGHTS
    %PROCDUMP-I-CREATED, rights identifier IMGDMP$READALL successfully created
    %PROCDUMP-I-CREATED, rights identifier IMGDMP$PROTECT successfully created

Note that IMGDMP$READALL has no attributes, but IMGDMP$PROTECT is created with the RESOURCE attribute.

5.11.6.2 Privileged Users and Process Dumps

For this discussion, a privileged user is one who satisfies one of the following conditions:

• Has one or more of the privileges CMKRNL, CMEXEC, SYSPRV, READALL, or BYPASS
• Is a member of a system UIC group (by default [10,n] or lower). Such users are treated as though they hold SYSPRV privilege.

Holders of CMKRNL or CMEXEC can write complete process dumps. Holders of any of the other privileges can read a process dump wherever it has been written.

5.11.6.3 Nonprivileged Users and Process Dumps

To allow a nonprivileged user to write and read complete process dumps, grant the rights identifier IMGDMP$READALL to the user. If the IMGDMP$READALL rights identifier does not exist, run the image SYS$SYSTEM:IMGDMP_RIGHTS.EXE to create it (see Section 5.11.6.1). Then use AUTHORIZE to grant the rights identifier to the user. For example:

    $ DEFINE /USER SYSUAF SYS$SYSTEM:SYSUAF.DAT  !if necessary
    $ RUN SYS$SYSTEM:AUTHORIZE
    UAF> GRANT /IDENTIFIER IMGDMP$READALL <user>
    UAF> EXIT

Note that the user must log out and log in again to be able to receive the rights identifier. A nonprivileged user with rights identifier IMGDMP$READALL can read and write complete process dumps without restriction.

5.11.6.4 Protecting Process Dumps

You can allow a nonprivileged user to write a complete process dump and at the same time prevent the user from reading the process dump just written. To do so, perform the following procedure:

1. If the IMGDMP$PROTECT rights identifier does not exist, run the image SYS$SYSTEM:IMGDMP_RIGHTS.EXE to create it (see Section 5.11.6.1).
2. Create a protected directory with rights identifier IMGDMP$PROTECT. For example:

   $ CREATE /DIRECTORY DKA300:[PROCDUMPS] - /PROTECTION=(S:RWE,O:RWE,G,W) /OWNER_UIC=IMGDMP$PROTECT $ SET SECURITY DKA300:[000000]PROCDUMPS.DIR - /ACL=((DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD:), - (IDENTIFIER=IMGDMP$PROTECT,ACCESS=READ+WRITE), - (IDENTIFIER=IMGDMP$PROTECT,OPTIONS=DEFAULT, - ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL), - (CREATOR,ACCESS=NONE))

3. Define protected logical name SYS$PROTECTED_PROCDMP to point to the protected directory. For example:

   $ DEFINE /SYSTEM /EXECUTIVE_MODE SYS$PROTECTED_PROCDMP DKA300:[PROCDUMPS]

   
   If DISKQUOTA is to be used on the disk containing the protected directory, specify the maximum disk space to be used for process dumps. For example:

   $ RUN SYS$SYSTEM:SYSMAN SYSMAN> DISKQUOTA CREATE /DEVICE=DKA300 ! if necessary SYSMAN> DISKQUOTA ENABLE /DEVICE=DKA300 ! if necessary SYSMAN> DISKQUOTA ADD IMGDMP$PROTECT /DEVICE=DKA300 /PERMQUOTA=10000 SYSMAN> DISKQUOTA REBUILD /DEVICE=DKA300 ! if necessary SYSMAN> EXIT

You can choose to set up additional ACLs on the protected directory to further control which users are allowed to read and write process dumps there.

Note that to take a process dump when the image is installed with elevated privileges or belongs to a protected subsystem, the user must hold CMKRNL privilege, and is by definition a privileged user (see Section 5.11.6.2).

5.12 RMS Locking Enhancements

This section introduces the new Record Management Services (RMS) enhancements provided in this release.

5.12.1 RMS Locking Performance Enhancements (Alpha)

The following sections describe RMS locking performance enhancements that are in OpenVMS Alpha Version 7.2-1H1 and in OpenVMS Version 7.3.

5.12.1.1 RMS Global Buffer Read-Mode Locking

• Allows concurrent read access to the global buffers. Accesses are no longer serialized, waiting to acquire an exclusive lock for a read access.
• Caches the read-mode lock as a system lock, which is retained over accesses and only lowered to null when the lock is blocking an exclusive write request. This functionality significantly reduces both local and remote lock request traffic (the number of $ENQ and $DEQ system service calls) as well as associated IPL-8 spinlock activity and System Communications Services (SCS) messages for a cluster.
• Does not increase lock resource names or the number of active system or process locks on the system.
• Is functionally compatible in mixed version clusters that include both Alpha and VAX computers.

This new functionality applies to read operations (using the $GET and $FIND services) for all three file organizations: sequential, relative, and indexed. It also applies to a write operation (using the $PUT service) for the read accesses used for index buckets the first time through an index tree for the write.

You do not need to make changes to existing applications to implement the read-only global bucket locks. However, global buffers must be set on a data file to take advantage of the enhancement. Use the following DCL command, where n is the number of buffers:

$ SET FILE/GLOBAL_BUFFER=n <filename>

For information about specifying the number of buffers, refer to the OpenVMS DCL Dictionary. For general information about using global buffers, refer to the section entitled Using Global Buffers for Shared Files in the Guide to OpenVMS File Applications.

In a mixed cluster environment where there may be high contention for specific buckets, the Alpha nodes that are using read-mode global bucket locking may dominate accesses to write-shared files, thereby preventing timely access by other nodes.

With the new /CONTENTION_POLICY=keyword qualifier to the SET RMS_DEFAULT command, you can specify the level of locking fairness at the process or system level for environments that experience high contention conditions.

For more information about using the /CONTENTION_POLICY=keyword qualifier, refer to the SET RMS_DEFAULT section of the OpenVMS DCL Dictionary.

5.12.1.2 No Query Record Locking Option

This release introduces new functionality that can minimize record locking for read accesses to shared files, thereby avoiding the processing associated with record locking calls to the Lock Manager.

In previous releases, if a file is opened allowing write sharing, an exclusive record lock is taken out for all record operations (both read and write). Applications may obtain record locking modes other than the exclusive lock (default) by specifying certain options to the RAB$L_ROP field. However, all the options involve some level of record locking. That is, the options require $ENQ or $DEQ system service calls to the Lock Manager.

The user record locking options include the RAB$V_NLK (no lock) query locking option, which requests that RMS take out a lock to probe for status and not hold the lock for synchronization. If the lock is not granted (exclusive lock held) and the read-regardless (RAB$V_RRL) option is not set, the record access fails with an RMS$_RLK status. Otherwise, the record is returned with one of the following statuses:

• RMS$_SUC --- No other writers
• RMS$_OK_RLK --- Record can be read but not written
• RMS$_OK_RRL --- Exclusive lock is held (lock request denied) but the read-regardless (RAB$V_RRL) option is set

When only the RAB$V_NLK option is specified, record access can be denied. When both the RAB$V_NLK and RAB$V_RRL options are specified, an application can guarantee the return of any record with a success or alternate success status.

This release introduces the no query record locking option, which allows applications to read records (using $GET or $FIND services) without any consideration of record locking. This option:

• Does not make a call to the Lock Manager
• Is equivalent to both RAB$V_NLK and RAB$V_RRL being set except that the RMS$_OK_RLK or RMS$_OK_RRL status will not be returned

This functionality is independent of bucket locks. It applies to both local and global buffers and to all three file organizations (sequential, relative, and indexed).

Three alternate methods for specifying the no query record locking option are outlined in Table 5-2.

Note the following:

• The first method allows the option to be enabled externally, potentially without any application change.
• You should use any of the methods only as appropriate for the application. In particular, you should check for any dependency in an existing application on the alternate success status RMS$_OK_RLK or RMS$_OK_RRL.

$ SET RMS_DEFAULT/QUERY_LOCK=DISABLE[/SYSTEM]

RMS precedence for the no query record locking option is as follows:

• The RAB$V_NQL option set in the RAB$W_ROP_2 field
• At file open (and applied, if RAB$V_NLK and RAB$V_RRL are set for the read operation):
  • The FAB$V_NQL option set in the FAB$B_SHR field
  • The SET RMS_DEFAULT/QUERY_LOCK=DISABLE setting at the process level
  • The SET RMS_DEFAULT/QUERY_LOCK=DISABLE setting at the system level. If the process /QUERY_LOCK setting equals SYSTEM_DEFAULT (the default when the process is created), RMS uses the system specified value.

For more information, see OpenVMS Record Management Services Reference Manual.