VMS Version 5.4 allows you to select a preferred disk path at mount 
time or force a preferred disk path (move a disk that is already 
mounted to its preferred path) through the use of a new $QIO function 
called IO$_SETPRFPATH and its function modifier IO$M_FORCEPATH.  This 
applies to RA series disks and disks accessed through the MSCP server.  

Although VMS does not provide preferred path functionality at the 
command line level, this article contains a MACRO program called 
PREFER.MAR and its DCL command line interface PREFER.CLD which provide
access to the IO$_SETPRFPATH QIO.  Future versions of VMS will contain 
these programs in SYS$EXAMPLES.  

For convenience, the executable version of PREFER and PREFER.CLD are 
also included on the HSC distribution medium.  The programs can be 
uploaded from the RX33 to your VMS system and used there.  Instructions 
on uploading PREFER.EXE and PREFER.CLD from the HSC diskette are included
in the "HSC V6.0 Software Release Notes".

Note that this example program uses only the subset of new functionality 
which applies to disks accessed through an HSC.

DOCUMENTATION NOTE:

For more information on the IO$_SETPRFPATH QIO, its function modifier 
IO$M_FORCEPATH and the MSCP server implementation, please see the 
"VMS I/O User's Reference Manual: Part I", (AA-LA84B-TE), June 1990, 
section 3.4.11.  Information is also available in the "VMS Version 5.4 
New Features Manual", (AA-LA97C-TE), June 1990, section 11.3.

Note however, that both of the manuals listed above incorrectly spell 
the name of the new QIO function as IO$_SETPRFPTH.  The correct spelling 
is IO$_SETPRFPATH.  These spelling errors will be corrected in future
versions of the manuals.


RESTRICTIONS:

Note that only devices mounted through the DU driver will respond to this 
QIO. Specifically, devices shadowed using the DUS driver with Volume 
Shadowing Phase I (controller-based shadowing) cannot be failed over using 
this QIO. The member drives can have the preferred path selected before 
they are mounted into a Phase I shadow set. For Phase II (host-based) 
shadowing, the member drives can be moved between HSC controllers without 
dissolving the shadow set.


PROGRAM NOTES:

The following DCL command procedure will compile and link the program.
 
 $ IF F$SEARCH("PREFER.MAR") .NES. "" THEN -
     MACRO/LIST/CROSS'p1' PREFER 
 $ IF F$SEARCH("PREFER.OBJ") .NES. "" THEN -
     LINK/MAP/CROSS'p1' PREFER 
 $ PURGE/LOG
 $ IF F$SEARCH("PREFER.CLD") .NES. "" THEN -
     SET COMMAND PREFER
 $ EXIT

   NOTE:  PHYS_IO privilege is required for IO$_SETPRFPATH 
          and IO$M_FORCEPATH. 


*** CAUTION ***                                                               

Because this sample program will be included in SYS$EXAMPLES in a 
future release of VMS, it is provided here on an "as is" basis.  
No programming support by Digital is implied.

This sample program has been tested using VAX MACRO on VMS V5.4.
However, DIGITAL cannot guarantee its effectiveness because of 
the possibility of error in transmitting or implementing it.  
It is meant to be used as a template for writing your own 
program, and it may require modification for use on your system. 

HOW TO USE PREFER:

To set up the preferred path functionality for use:

   1. Place the PREFER.EXE executable image in SYS$COMMON:[SYSEXE]
      or some other location of your choice.

   2. Define the DCL command verb PREFER using the PREFER.CLD
      command definition file.

If the executable image is not in SYS$COMMON:[SYSEXE], then edit 
PREFER.CLD to reflect the proper location.

To define PREFER as a DCL command verb in your local process command 
table, enter the following command:

    $ SET COMMAND PREFER

To define PREFER as a DCL command verb in the system-wide DCL command 
table, enter the following command from an account with CMKRNL privilege:

    $ SET COMMAND /TABLE=SYS$LIBRARY:DCLTABLES -
    _$ /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES PREFER

To make the new command available to other users, use the VMS Install 
Utility.  Verify that your systems have sufficient unused global pages 
and global sections to accommodate the modified command table.  From an 
account with CMKRNL privilege, enter the following commands:

     $ INSTALL
     INSTALL> REPLACE SYS$LIBRARY:DCLTABLES
     INSTALL> EXIT

                            NOTE

     The Install utility commands must be executed from all
     nodes in a VAXcluster system. If your system configuration 
     deviates from the standard usage of DCLTABLES, modify the 
     above commands to suit your site. For further information 
     on defining command verbs or using the Install utility, 
     consult the VMS documentation set.

Next, to use the preferred path functionality, enter the command:

    $ PREFER device/HOST=hsc[/FORCE]

where

    hsc is the name of the HSC controller that is the preferred path.
    /FORCE is an optional switch.

For example, device $10$DUA10: has a primary path through HSC015 and a 
secondary path through HSC014. To select HSC014 as the primary path, 
enter the following command:

    $ PREFER $10$DUA10:/HOST=HSC014

This command will set the preferred path on the local node so that the 
next mount will use the selected path. If the /CLUSTER qualifier is used 


on the MOUNT command, all nodes in the cluster will use the selected path. 
Note that no change is made to the SHOW DEVICE output.

The /FORCE qualifier is used to select a preferred path for mounted disks. 
If the disk is mounted (not /FOREIGN), then the IO$M_FORCEPATH modifier 
will be used to force the drive into mount verification and move it to 
the new HSC controller. For example:

    $ PREFER $10$DUA10:/HOST=HSC014/FORCE

The path used to remount the disk will be the preferred path of the node 
that performs the mount verification. No other nodes in the VAXcluster 
system will alter their paths to the device. For proper operation, the 
/FORCE qualifier should be issued only from a host on which the device 
is mounted.

To select a preferred path for all nodes in the VAXcluster system, use 
the VMS SYSMAN Utility to set the preferred path on all nodes in the 
cluster before executing the PREFER command with the /FORCE qualifier.

    SYSMAN> SET ENVIRONMENT/CLUSTER
    SYSMAN> DO PREFER $10$DUA10:/HOST=HSC014
    SYSMAN> EXIT
    $ PREFER $10$DUA10:/HOST=HSC014/FORCE

                               NOTE

      The PREFER command must be defined as a DCL command
      verb on all nodes in the VAXcluster system before
      using it within SYSMAN.

The SYSMAN PREFER command sets the preferred path on all nodes so that 
the next mount command from any node will use the selected path. The DCL 
PREFER command using the /FORCE qualifier causes the device to enter mount 
verification.  After mount verification completes, the device will be 
remounted by all nodes through the preferred path, HSC014.