Document revision date: 30 March 2001

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

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

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

> #### /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.

> #### /ABORT_VIRTUAL_UNIT DSAnnnn:

> Aborts mount verification.

> To use this qualifier, the shadow set must be in mount verification. When you specify this qualifier, the shadow set aborts mount verification immediately on the node from which the qualifier is issued. Use this qualifier when it is known that the unit cannot be recovered.

> Note that after this command completes, the shadow set must still be dismounted. Use the following command to dismount the shadow set:

>     $ DISMOUNT/ABORT DSAnnnn:

> #### /COPY_SOURCE (ddcu:,DSAnnnn:)

> Controls whether one or both source members of a shadow set are used as the source for read data during full copy operations, when a third member is added to the shadow set. This only affects copy operations that do not use DCD operations.

> HSG80 controllers 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 allows you to force all reads from a single source member for a copy operation.

> If the shadow set is specified, then 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 member of the shadow set is specified, then 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:

> Expels a named 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 device specified 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:

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

> 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 16,777,215 seconds.

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

> #### /MVTIMEOUT=n DSAnnnn:

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

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

> The valid range for n is 1 to 16,777,215 seconds.

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

> #### /PATH=path-description-string

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

> This qualifier applies only to multipath devices.

> #### /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 DEVICES/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 OpenVMS I/O User's Reference Manual.

> #### /READ_COST=n ddcu:

> Allows you to modify the default "cost" assigned to each member of a shadow set, so that reads are biased or prioritized toward one member versus another.

> The valid range for n is 1 to 65,535 units.

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

> 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. There are default values for a DECRAM device; a directly connected device in the same physical location; a directly connected device in a remote location; a DECram served device; and a default value for other served devices.

> The value supplied by this 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.

> If the /SITE command qualifier has been specified, the shadowing driver will take site values into account when it assigns default READ_COST values. Note that 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 individual device.

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

> #### /READ_COST=n DSAnnnn:

> Switches the read cost setting for all shadow set members back to the default read cost settings established automatically by the shadowing software. DSAnnnn: must be a shadow set that is mounted on the node from which this command is issued.

> The valid range for n is any nonzero number. The value supplied has no inherent meaning.

> #### /SITE=(n, logical_name) (ddcu: DSAnnnn:)

> Indicates to the shadowing driver the site location of the shadow set member or of the shadow set (represented by its virtual unit name). Prior to using this qualifier, you can define the site location in the SYLOGICALS.COM command procedure to simplify its use.

> The valid range for the site location designator, n, is 1 through 255.

> The following example shows the site locations defined, followed by the use of the /SITE qualifier:

>     $ DEFINE/SYSTEM/EXEC ZKO 1
>     $ DEFINE/SYSTEM/EXEC LKG 2
>     $!
>     $! At the ZKO site ...
>     $ MOUNT/SYSTEM DSA0/SHAD=($1$DGA0:,$1$DGA1:) TEST
>     $ SET DEVICE/SITE=ZKO  DSA0:
>     $!
>     $! At the LKG site ...
>     $ MOUNT/SYSTEM DSA0/SHAD=($1$DGA0,$1$DGA1) TEST
>     $ SET DEVICE/SITE=LKG  DSA0:
>     $!
>     $! At both sites, the following would be used:
>     $ SET DEVICE/SITE=ZKO  $1$DGA0:
>     $ SET DEVICE/SITE=LKG  $1$DGA1:

> #### /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.

### 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 $10$DKA1001:/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 $10$DKA1001:/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 $10$DKA1001:/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.

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

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

> #### /STYLE=keyword

> Specifies the file name format for display purposes.

> The valid keywords for this qualifier are CONDENSED and EXPANDED. Descriptions are as follows:

> Keyword | Explanation
> --- | ---
> CONDENSED (default) | Displays the file name representation of what is generated to fit into a 255-length character string. This file name may contain a DID or FID abbreviation in the file specification.
> EXPANDED | Displays the file name representation of what is stored on disk. This file name does not contain any DID or FID abbreviations.

> The keywords CONDENSED and EXPANDED are mutually exclusive. This qualifier specifies which file name format is displayed in the output message, along with the confirmation if requested.

> File errors are displayed with the CONDENSED file specification unless the EXPANDED keyword is specified.

> Refer to the OpenVMS Guide to Extended File Specifications for more information.

> #### /VERSION_LIMIT[=n]

> Specifies the total number of versions that a file in the specified directory can have. If you do not specify a version limit, a value of 0 is used, indicating that the number of versions of a file is limited only to the Files-11 architectural limit---32,767. If you change the version limit for the directory, the new value applies only to files created after the change has been made.

> The SET DIRECTORY version limit value refers to the number of files with the same file name and type that can exist in the directory at one time. It has no effect on the version number field of a particular file specification. Use the SET FILE command to set limits on file version numbers.

> To find out the current version limit for a directory, use the DIRECTORY/FULL command on a directory file and look at the File Attributes component of the output.

###

#### Examples

#1
    $ SET DIRECTORY/VERSION_LIMIT=5/CONFIRM [VERCAMMEN...]

> The SET DIRECTORY command in this example sets a version limit of five for all files in the VERCAMMEN directory and all subdirectories of [VERCAMMEN]. The /CONFIRM qualifier requests that you confirm whether the specified directory should actually be modified. Note that it affects only the files created after the command is entered.

#2
    $ SET DIRECTORY/OWNER_UIC=[360,020] [WOERTMAN],[MOSER]

> The SET DIRECTORY command in this example modifies both the [WOERTMAN] and [MOSER] directories, changing their owner UICs. Using the OWNER_UIC qualifier requires SYSPRV (system privilege).

Previous | Next | Contents | Index

| privacy and legal statement |
9996PRO_051.HTML