[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here HP OpenVMS DCL Dictionary

HP OpenVMS DCL Dictionary


Previous Contents Index


SET DEVICE

Establishes a print device or terminal as a spooled device or establishes the operational status for a device.

Requires OPER (operator) privilege.

PHY_IO (physical I/O) privilege is required when specifying the Alpha-only qualifiers that change the characteristics of shadow sets. These qualifiers also can be specified using the SET SHADOW command, which provides additional options for controlling shadow sets. Qualifier settings for shadow sets remain in effect until they are changed using either SET DEVICE or SET SHADOW or until the shadow set or shadow set member is dismounted. If the shadow set is remounted or a shadow set member is returned to the shadow set from which it was dismounted, the settings must be specified again. For more information about volume shadowing, refer to HP Volume Shadowing for OpenVMS.


Format

SET DEVICE [device-name[:]]


Parameter

device-name[:]

Specifies the name of the device whose spooling or operational status is to change. The device must be a print device or a terminal if you want to change the spooling status; the device must be a disk or magnetic tape if you want to change the operational status.

When you specify qualifiers that act on shadow sets, the device might be a shadow set member (ddcu:) or the whole shadow set (DSAnnnn:), as noted in the qualifier format. Depending on the qualifier, if no device name is supplied, the qualifier applies to all shadow sets mounted on the node from which the command is executed.


Description

When you specify any of the following qualifiers, the operational status of the drive is changed: /ABORT_VIRTUAL_UNIT, /AVAILABLE, /COPY_SOURCE, /DUAL_PORT, /ENABLE, /ERROR_LOGGING, /FORCE_REMOVAL, /MEMBER_TIMEOUT, /MVTIMEOUT, /POLL, /READ_COST, /SITE, or /SWITCH.

When you specify the /SPOOLED qualifier, program output that uses OpenVMS Record Management Services (RMS) or file control system (FCS) and that specifies the print device name is written onto an intermediate disk rather than written directly to the print device or terminal.


Qualifiers

/ABORT_VIRTUAL_UNIT DSAnnnn: (Alpha only)

Aborts mount verification on a shadow set.

Use this qualifier when you know that the unit cannot be recovered. When you use this qualifier, the shadow set must be in mount verification. The shadow set aborts mount verification immediately on the node from which the command is issued. If the shadow set is not in mount verification, this command returns the error %SYSTEM-E-UNSUPPORTED, unsupported operation or function.

After this command completes, the shadow set still must be dismounted. Use the following command to dismount the shadow set:


$ DISMOUNT/ABORT DSAnnnn:

/AVAILABLE

/NOAVAILABLE

Controls whether the specified disk or magnetic tape is to be considered available. You must dismount the specified disk or magnetic tape before entering the SET DEVICE/[NO]AVAILABLE command. If you specify the /NOAVAILABLE qualifier, any attempt to allocate or mount the specified disk or magnetic tape is prevented. Devices are automatically set /AVAILABLE when brought online even if the device had been previously set /NOAVAILABLE.

/COPY_SOURCE {ddcu: | DSAnnnn:} (Alpha only)

Specifies which source member of a shadow set will be used as the source for read data during full copy operations when a third member is added to the shadow set. This qualifier affects only copy operations that do not use disk copy data (DCD) commands.

Some storage controllers, such as the HSG80, have a read-ahead cache, which significantly improves single-disk read performance. Copy operations normally alternate reads between the two source members, which effectively nullifies the benefits of the read-ahead cache. This qualifier lets you force all reads from a single, specified source member for a copy operation.

If only a shadow set (DSAnnnn:) is specified, all reads for full copy operations will be performed from the disk that is the current "master" member, regardless of physical location of the disk.

If a shadow set member (ddcu:) is specified, that member will be used as the source of all copy operations. This allows you to choose a local source member, rather than a remote master member.

/DUAL_PORT

/NODUAL_PORT

Controls whether the port seize logic in the device driver of the specified disk is to be enabled. This qualifier should be used only on disks that contain a dual port kit and have been dismounted.

/ENABLE

/NOENABLE

Enables or disables a path to a multipath device; the affected path is the one named in the /PATH qualifier. All paths are initially enabled; the current path cannot be disabled.

/ERROR_LOGGING

/NOERROR_LOGGING

Controls whether device errors are logged in the error log file. When you specify the /ERROR_LOGGING qualifier, all error messages reported by the device on which error logging is enabled are recorded in the error log file. Use the SHOW DEVICE/FULL command to find out the current status.

/FORCE_REMOVAL ddcu: (Alpha only)

Expels the specified shadow set member from the shadow set.

If connectivity to a device has been lost and the shadow set is in mount verification, this qualifier causes the member to be expelled from the shadow set immediately.

If the shadow set is not currently in mount verification, no immediate action is taken. If connectivity to a device has been lost but the shadow set is not in mount verification, this qualifier lets you flag the member to be expelled from the shadow set, as soon as it does enter mount verification.

The specified device must be a member of a shadow set that is mounted on the node where the command is issued.

/LOG

/NOLOG (default)

Controls whether log information is displayed at the terminal.

/MEMBER_TIMEOUT=n ddcu: (Alpha only)

Specifies the timeout value to be used for a shadow set member.

The value supplied by this qualifier overrides the system parameter SHADOW_MBR_TMO for this specific device. Each member of a shadow set can be assigned a different MEMBER_TIMEOUT value.

The valid range for n is 1 to 16777215 seconds.

The specified device must be a member of a shadow set that is mounted on the node where the command is issued.

/MV_INTVL=n

Overrides the system-wide setting of the MVSUPMSG_INTVL system parameter with the value specified by n (seconds) for the specified device only. If /MV_INTVL=0, the value for MVSUPMSG_INTVL is used instead. If MVSUPMSG_INTVL=0 or MVSUPMSG_NUM=0, all mount verifications are announced. For more information about MVSUPMSG_INTVL, refer to the HP OpenVMS System Management Utilities Reference Manual.

/MV_NUM=n

Overrides the system-wide setting of the MVSUPMSG_NUM system parameter with the value specified by n (seconds) for the specified device only. If /MV_NUM=0, the value for MVSUPMSG_NUM is used instead. If MVSUPMSG_NUM=0 or MVSUPMSG_INTVL=0, all mount verifications are announced. For more information about MVSUPMSG_NUM, refer to the HP OpenVMS System Management Utilities Reference Manual.

/MVTIMEOUT=n DSAnnnn: (Alpha only)

Specifies the mount verification timeout value to be used for the shadow set specified by its virtual unit name (DSAnnnn:).

The value supplied by this qualifier overrides the value specified by the system parameter MVTIMEOUT for this specific shadow set.

The valid range for n is 1 to 16777215 seconds.

The specified shadow set must be mounted on the node where the command is issued.

/PATH=path-description-string

(For multipath devices only) Specifies a particular route to the device. The path description string identifies a path from the host to the device (for example, PGA0.2343-A855-BC99-876F or PKC0.5). Wildcard characters have no special meaning. The path description can be abbreviated to the minimum unique string.

Note that this qualifier does not imply that any action be taken. To take action, you must also specify one of the following qualifiers: /(NO)ENABLE, /(NO)POLL, or /SWITCH.

/POLL

/NOPOLL

Specifies that the path specified by the /PATH qualifier is to be polled for continued availability as a path switch destination. This does not affect any attempt to switch to this path. Its purpose is only to inform an operator that a path may or may not be viable as a path switch destination. By default, all device paths are enabled for polling when they are discovered. Note that this qualifier applies only to multipath devices.

/PREFERRED_CPUS=cpu-a[,cpu-b,cpu-c,...]

/NOPREFERRED_CPUS

Allows you to specify a CPU or a set of candidate CPUs from which the operating system chooses the CPU to assign to the Fast Path port. The chosen CPU is called the preferred CPU for this Fast Path port. The Fast Path port's interrupt I/O completion processing and I/O initiation processing are performed on this preferred CPU.

In addition to selecting the preferred CPU, the User Preferred CPU is set for this port. Setting the User Preferred CPU prevents the port from being reassigned to another CPU unless the User preferred CPU is being stopped. The qualifier can be negated. When the /NOPREFERRED_CPUS qualifier is specified, the User Preferred CPU is cleared for the port, but it remains a Fast Path port, and the current preferred CPU is not changed.

If both /PREFERRED_CPUS and /NOPREFERRED_CPUS are specified on the same command line, /NOPREFERRED_CPUS is ignored.

If Fast Path is enabled, you can use the DCL command, SHOW DEVICE/FULL, to display the current preferred CPU and the User Preferred CPU.

For more information about using Fast Path features to improve I/O performance, refer to the HP OpenVMS I/O User's Reference Manual.

/READ_COST=n {ddcu: | DSAnnnn:} (Alpha only)

Enables you to modify the default cost assigned to each shadow set member (ddcu:). By modifying the assignments, you can bias the reads in favor of one member of a two-member shadow set, or, in the case of three-member shadow sets, in favor of one or two members of the set over the remaining members. The device specified must be a shadow set or member of a shadow set that is mounted on the node where the command is issued.

The valid range for the specified cost is 1 to 65,535 units.

The shadowing driver assigns default READ_COST values to shadow set members when each member is initially mounted. The default value depends on the device type and its configuration relative to the system mounting it. The following list of device types is ordered by the default READ_COST assignments, from the lowest cost to the highest cost:

  • DECram device
  • Directly connected device in the same physical location
  • Directly connected device in a remote location
  • DECram served device
  • Default value for other served devices

The value supplied by the /READ_COST qualifier overrides the default assignment. The shadowing driver adds the value of the current queue depth of the shadow set member to the READ_COST value and then reads from the member with the lowest value.

Different systems in the cluster can assign different costs to each shadow set member.

When this qualifier specifies a shadow set (DSAnnnn:) instead of a shadow set member, the /READ_COST qualifier switches the read cost setting for all shadow set members back to the default read cost settings established automatically by the shadowing software. The specified shadow set must be mounted on the node where the command is issued. In this case, the value specified for the cost can be any number because it will be ignored.

If the /SITE command qualifier has been specified, the shadowing driver takes site values into account when it assigns default READ_COST values. In order for the shadowing software to determine whether a device is in the category of "directly connected device in a remote location," the /SITE command qualifier must have been applied to both the shadow set and the shadow set member.

Reads requested for a shadow set from a system at site 1 are performed from a shadow set member that is also at site 1. Reads requested for the same shadow set from site 2 can read from the member located at site 2.

/RESET=(keyword[,keyword])

Requires CMKRNL and DIAGNOSE privileges.

Resets either or both the error count and the operation count for a device. You must specify one or both of the following keywords:

ERROR_COUNT Resets the error count.
OPERATION_COUNT Resets the operation count.

When either count is reset, a message is sent to the error log. The message indicates that the count was reset and includes the value of the counter before the reset.

/SITE=n {DSAnnnn: | ddcu:} (Alpha only)

Indicates to the shadowing driver the site location of the specified shadow set (DSAnnnn:) or shadow set member (ddcu:). If the member is removed from the shadow set and later is returned, this qualifier must be specified again.

The SHADOW_SITE_ID system parameter defines the default site location of the shadow set. You can override the default location of the shadow set with the /SITE qualifier.

The valid range for the site location, represented by n, is 1 through 255.

After you apply this qualifier, the setting remains in effect until you change it either with this command or with the SET SHADOW/SITE command.

This qualifier can improve read performance because the member that is physically local to the system will be the preferred disk from which to read, provided that you specify the /SITE qualifier for each shadow set member and for the shadow set. (In a Fibre Channel configuration, shadow set members at different sites are directly attached to the system. For the Volume Shadowing and cluster software, there is no distinction between local and remote in multiple-site Fibre Channel configurations.)

/SPOOLED[=(queue-name[:],intermediate-disk-name[:])]

/NOSPOOLED

Controls whether files are spooled to an intermediate disk.

The queue name indicates the printer queue to which a file is queued. If a queue name is not supplied, the default is the name of either the printer or terminal.

The intermediate disk name identifies the disk to which the spooled files are written. If the intermediate disk name is not supplied, the default is SYS$DISK (the current default disk). The intermediate disk must be mounted before files can be written to it.

Once the device has been set spooled to a disk, that disk cannot be dismounted until the spooled device is set to /NOSPOOLED. All channels must be deassigned from a print device before its spooling characteristics can be changed. Also, the queue that is assigned to the device must be stopped.

/SWITCH

Attempts to switch from the current path of a multipath device to the path named in the /PATH qualifier. The path switch is attempted only if the path has not been disabled by SET DEVICE/NOENABLE. The path switch is initiated but not completed before returning control to the user; use SHOW DEVICE/MULTIPATH to verify that the path switching has completed successfully.

This command requires the OPER privilege. Additionally, if the device is currently allocated by another process, as tape devices often are, the SHARE privilege is needed.


Examples

#1

$ SET DEVICE/SPOOLED=(LPA0)  LPA0:
      

In this example, the /SPOOLED qualifier requests that the printer queue LPA0 be spooled to an intermediate disk before files directed to the disk are printed. Because no intermediate disk was specified, the intermediate disk defaults to SYS$DISK.

#2

$ SET DEVICE/ERROR_LOGGING  DKB2:
      

The SET DEVICE command in this example requests that all device errors reported on device DKB2 be logged in the error log file.

#3

$ SET DEVICE/NOAVAILABLE DRA0:
      

The SET DEVICE command in this example prevents any attempt to mount a disk on device DRA0.

#4

$ SET DEVICE/DUAL_PORT DRA0:
      

The SET DEVICE command in this example enables the dual port seize logic in device DRA0.

#5

$ SET DEVICE/PREFERRED_CPU=1 PNA0
      

The Fast Path port PNA0 is assigned to CPU 1, and the User Preferred CPU is set to 1.

#6

$ SET DEVICE/NOPREFERRED_CPU  PNA0
      

The port PNA0 will have the User Preferred CPU cleared, but will remain a Fast Path port, with CPU 1 as its current preferred CPU.

#7

$ SET DEVICE/PREFERRED_CPU=(0,1,2)  PNA0
      

The operating system selects CPU 0,1, or 2 as the preferred CPU for Fast Path port PNA0, and sets its User Preferred CPU to the selected CPU.

#8

$ SET DEVICE $1$DGA1001:/PATH=PGB0.0123-4567-89AB-CDEF/ENABLE
      

In this example, a request is made to enable path PGB0.0123-4567-89AB-CDEF as a switch path destination. No error is indicated if the path was in the enabled state prior to the request. Had the /NOENABLE option been used, the path would have been removed from switch path consideration.

#9

$ SET DEVICE $1$DGA1001:/PATH=PGB0.0123-4567-89AB-CDEF/POLL
      

In this example, a request is made to enable path PGB0.0123-4567-89AB-CDEF for polling of its continued availability as a path switch destination. Had the /NOPOLL option been used, the path would have been removed from path availability polling consideration.

#10

$ SET DEVICE $1$DGA1001:/PATH=PGB0.0123-4567-89AB-CDEF/SWITCH
      

In this example, a request is made to switch from the current path to path PGB0.0123-4567-89AB-CDEF. Should the path fail, the switch algorithm of the unspecified path is used.

#11

$ ! Command sequence used on system 1 at site 1:
$ MOUNT/SYSTEM DSA0:/SHADOW=($1$DGA0:,$1$DGA1:) TEST
$ SET DEVICE/SITE=1  DSA0:
$ !
$ ! Command sequence used on system 2 at site 2:
$ MOUNT/SYSTEM DSA0:/SHADOW=($1$DGA0:,$1$DGA1:) TEST
$ SET DEVICE/SITE=2  DSA0:
$ !
$ ! Commands used on both system 1 and system 2:
$ SET DEVICE/SITE=1  $1$DGA0:
$ SET DEVICE/SITE=2  $1$DGA1:

      

In this example, the system at site 1 will perform all reads from $1$DGA0, which is the physically local disk, while the system at site 2 will perform all reads from its physically local disk, $1$DGA1.


SET DEVICE/SERVED

Makes a disk on a local node available to all the nodes in an OpenVMS Cluster.

Applies only to OpenVMS Cluster environments.


Format

SET DEVICE/SERVED node-name$DDcu:


Parameter

node-name$DDcu:

Specifies the device name of the device that you want to make available to the cluster.

Description

The SET DEVICE/SERVED command is used in conjunction with the mass storage control protocol (MSCP) server to make a disk on a local node available to all nodes on the cluster. The local node must be a member of an OpenVMS Cluster, and the local MSCP server must have been invoked by the System Generation utility (SYSGEN).

You cannot use the SET DEVICE/SERVED command under the following conditions:

  • In service of a Phase II shadow set virtual unit
  • On devices that are already mounted
  • On system disks
  • On quorum disks

The SET DEVICE/SERVED command string can be included as part of the local startup command file and entered before the Mount utility mounts the disk to be served (made available to the entire cluster).


Example


$ SET DEVICE/SERVED DRA4:
      

The SET DEVICE/SERVED command in this example instructs the MSCP server to make the disk device DRA4 on your local node available to all other processors on your cluster.


SET DIRECTORY

Modifies the characteristics of one or more directories.

See the qualifier descriptions for restrictions.


Format

SET DIRECTORY [device-name[:]]directory-spec[,...]


Parameters

device-name[:]

Specifies the device on which the directory that you want to modify is located. The device name parameter is optional.

directory-spec[,...]

Specifies one or more directories to be modified. If you specify more than one directory, separate the directory specifications with commas. The asterisk (*) and the percent sign (%) wildcard characters are allowed.

Qualifiers

/BACKUP

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier selects directories according to the dates of their most recent backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select directories according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/BEFORE[=time]

Selects only those directories dated prior to the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

For complete information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

/BY_OWNER[=uic]

Selects only those directories whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.

Specify the UIC by using standard UIC format as described in the HP OpenVMS Guide to System Security.

The /OWNER_UIC qualifier requires control access, a system UIC, or privilege.

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each SET DIRECTORY operation to confirm that the operation should be performed on that file. The following responses are valid:
YES NO QUIT
TRUE FALSE Ctrl/Z
1 0 ALL
  [Return]  

You can use any combination of uppercase and lowercase letters for word responses. Word responses can be abbreviated to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing Return. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.

/CREATED (default)

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects directories based on their dates of creation. This qualifier is incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select directories according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/EXCLUDE=(filespec[,...])

Excludes the specified directories from the SET DIRECTORY operation. You can include a directory but not a device in the file specification. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification; however, you cannot use relative version numbers to exclude a specific version. If you specify only one directory, you can omit the parentheses.

/EXPIRED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier selects directories according to their expiration dates. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow you to select directories according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/LOG

/NOLOG (default)

Controls whether the system displays the directory specification of each directory that is modified as the command executes.

/MODIFIED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier selects directories according to the dates on which they were last modified. This qualifier is incompatible with the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to select directories according to time attributes. If you specify none of these four time modifiers, the default is the /CREATED qualifier.

/OWNER_UIC[=uic]

Requires control access, a system UIC, or privilege.

Specifies an owner UIC for the directory. The default UIC is that of the current process.

/SINCE[=time]

Selects only those directories dated on or after the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /SINCE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.


Previous Next Contents Index