Summary of DCL Commands

This section lists the DCL commands that support file shelving. The PRESHELVE, SHELVE and UNSHELVE commands are part of the HSM for OpenVMS product.

The DIRECTORY command includes two additional qualifiers that select files based on shelving attributes and display the shelved state of files. These qualifiers are described here for reference.

Format

DIRECTORY [file_spec[,...]]

Parameters

[file_spec[,...]]

Specifies one or more files. To specify two or more files, separate them with commas. Wildcard characters are allowed.

Qualifiers

/SELECT=keyword

The /SELECT qualifier accepts the following additional keywords:

[NO]ONLINE The ONLINE keyword selects files that are online or preshelved.
The NOONLINE keyword selects files that are shelved.

[NO]SHELVABLE The SHELVABLE keyword selects files that are shelvable.
The NOSHELVABLE keyword selects files that are not
shelvable, as set by the SET FILE /NOSHELVABLE command.

/SHELVED_STATE

Displays the state of the file as shelved or online. Preshelved files are displayed as online.

Example

The following example shows the DIRECTORY /SHELVED_STATE command:

$ DIRECTORY /SHELVED_STATE

DIRECTORY MYDISK:[SMITH]

MYFILE.TXT;2 Online
NOT_SHELVED.TXT;1 Online
SHELVED.TXT;1 Shelved

The HSM$BACKUP command is a special version of OpenVMS BACKUP that supports consolidated Backup with HSM.

HSM$BACKUP is enabled with the SET COMMAND as shown in the set of examples below.

Format

HSM$BACKUP input_spec output_spec

Parameters

input_spec

Specifies files to be backed up, or source saveset for a restore operation.

output_spec

Specifies destination output spec for files to be backed up, or destination location for files on a restore.

Qualifiers

/PRESHELVED (default)

/NOPRESHELVED

/NOPRESHELVED backs up only the headers of preshelved files. /PRESHELVED (default) backs up the data of preshelved files. This is applicable to IMAGE and file backup operations and not applicable to restore.

/SHELVED (default)

/NOSHELVED

/NOSHELVED

/NOSHELVED backs up only the headers of shelved files. SHELVED (default) unshelves the file and backs up the data. Applicable to non-image backup operations; not applicable to restore.

Examples

The following example shows how to use HSM$BACKUP to perform image and incremental backups, which back up only the headers of shelved and preshelved files.

$ SET COMMAND SYS$SYSTEM:HSM$BACKUP.CLD
$ HSM$BACKUP/IMAGE/IGNORE=INTERLOCK/RECORD/LOG/NOPRESHELVED - $ $1$DKA100: $1$MUA100:DKA100_AUG23_IMAGE.BCK/SAVESET
$ HSM$BACKUP/RECORD/SINCE=BACKUP/LOG/NOSHELVED/NOPRESHELVED - $ $1$DKA100: $1$MUA100:DKA100_AUG24.BCK/SAVESET

The following example shows how to use HSM$BACKUP to copy shelved file data from one disk to a saveset on another using /IMAGE. The /INITIALIZE qualifier on the output disk is required.

$ MOUNT/FOREIGN $12$DKA400:
$ HSM$BACKUP/IMAGE/IGNORE=INTERLOCK/RECORD/NOPRESHELVED/LOG - $ $1$DKA100: $12$DKA400:DKA100_AUG30_IMAGE.BCK/SAVESET/INITIALIZE

The PRESHELVE command copies file data from online storage to shelf storage or cache, but leaves the original file data online and accessible.

The PRESHELVE command requires READ and WRITE access to the file, or an appropriate file access privilege.

Format

PRESHELVE file_spec[,...]

Parameters

file_spec[,...]

Specifies one or more files to be preshelved. If two or more files are specified, separate them with commas. Wildcard characters are allowed.

Qualifiers

/BACKUP

Uses the backup date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers. If a file has no backup date, it is not selected for the operation.

/BEFORE[=time]

Selects only those files dated prior to the specified time. Specify the time as an absolute time, a delta time, or a combination time, or as one of the following keywords:

TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

Time must be specified using the OpenVMS formats for absolute and delta times.

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process. If not specified, all UICs are eligible.

/CANCEL

Cancels any outstanding command requests for the files.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a question is asked before each PRESHELVE 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

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/CREATED

Uses the creation date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers.

/ELAPSED=[ delta time]

Selects only those files for which the specifed time has elapsed after the file was subjected to any one of the file events. Specify any one of the following qualifiers with /ELAPSED to indicate the file event that is to be used for selection of the files: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED

The file modification time is considered for selection as default when /ELAPSED is specifed without any of the file event qualifiers.

The default time for /ELAPSED qualifier is 30 days. /ELAPSED qualifier is mutually exclusive with qualifers /BEFORE and /SINCE.

Time must be specified using the OpenVMS format for delta times.

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

Excludes the specified files from the command operation. Wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you provide only one file specification, you can omit the parentheses.

/EXPIRED

Uses the expiration date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers. The file expiration date is used in conjunction with the volume retention functionality.
When volume retention has been enabled for a volume, the expiration date is updated whenever a file is accessed (read or write). Each time a file is accessed, the current time is added to the minimum retention time. If the sum is greater than the current expiration date, a new expiration date is computed. Updating the expiration date depends on the settings of the retention time for the volume.

Refer the OpenVMS SET VOLUME/RETENTION command for further details.

If a file has no expiration date, it is not selected for the operation.

/KEEP[=number_of_versions]

Specifies that the latest n versions of the file are not processed. If /KEEP is specified without a number of versions value, then all versions of the file except the highest version are processed.

/LOG

/NOLOG (Default)

Specifies that a command acknowledgment is displayed. If the command is specified with the
/WAIT qualifier or if the shelf handler can process the command immediately, the log output contains the final result of the operation. If the command is specified with the /NOWAIT qualifier, a message indicating that the request is queued may be displayed on success for long-running operations.

/MODIFIED (Default)

Uses the modification date for selection criteria when using the /BEFORE, /SINCE or
/ELAPSED qualifiers.

/NOTIFY

/NONOTIFY (Default)

Specifies whether a message is sent to the user upon completion of the command operation for each file in the request. The message is sent to all terminals on which the user is logged-in that have BROADCAST enabled.

/SAVE

When issued with the shelve command, HSM will not allow the save sets to span from one tape to another on encountering an end of tape during the BACKUP operation.

/SELECT=(keyword[,...])

Allows selection of files according to size or shelved state. Choose one of the following keywords:

SIZE=MAXIMUM=n Selects files that have fewer blocks than the value of n,
which defaults to 1,073,741,823. Use with MINIMUM=n to
specify a size range for files to be selected.

SIZE=MINIMUM=n Selects files that have blocks equal to or greater than the value
of n, which defaults to 0. Use with MAXIMUM=n to
specify a size range for files to be selected.

NOONLINE Selects only files that are shelved. Use this keyword
to copy shelved file data to additional archive classes.

ONLINE (Default) Selects only files that are online or preshelved. This is the
default file selection.

(ONLINE, NOONLINE) Selects files regardless of their shelved state.

By default, file selection is not based on file size criteria.

/SINCE[=time]

Selects only those files dated after the specified time. Specify the time as an absolute time, a delta time, or a combination time, or as one of the following keywords:

• TODAY (default),
• TOMORROW, or
• YESTERDAY.

Specify one of the following qualifiers with /SINCE to indicate the time attribute to be used as the basis for selection:

/BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

Time must be specified using the OpenVMS formats for absolute and delta times.

/WAIT (Default)

/NOWAIT

Specifies whether to wait for the operation to complete. The default is /WAIT. Files moved to the cache typically take the same amount of time as a similar COPY command. Files shelved directly to nearline/offline storage may take anywhere from tens of seconds to tens of minutes. Multiple files take correspondingly longer.

Example

The following example shows the PRESHELVE/NOTIFY command:

$ PRESHELVE/NOTIFY JLRM_DATA.DAT
%HSM-S-PRESHELVED, file $1$DKA0:[BUTLER.DB_FILES]JLRM_DATA.DAT;1 preshelved

FILE

The SET FILE command includes an additional qualifier to control the eligibility of a file for shelving. This qualifier is described here for reference. For a full description of the SET FILE command, refer the OpenVMS DCL Dictionary or online help.

Format

SET FILE file_spec[,...]

Parameters

file_spec[,...]

Specifies one or more files to be modified. If two or more files are specified, separate them with commas. Wildcard characters are allowed.

Qualifiers

/SHELVABLE

/NOSHELVABLE

The /SHELVABLE qualifier sets the file named by file_spec to be shelvable. By default, all user files are shelvable. Use the /NOSHELVABLE qualifier to prevent the file from being shelved or preshelved.

Example

The following example shows the SET FILE /NOSHELVABLE command, which ensures that the file cannot be shelved or preshelved:

$ SET FILE /NOSHELVABLE AARDVARKS.TXT;3

PROCESS

The SET PROCESS command includes an additional qualifier that specifies the default action to be taken when a shelved file is accessed by the process. This qualifier is described here.

Format

SET PROCESS process-name[,...]

Parameters

process-name[,...]

Specifies the name of the process that will have its characteristics changed. You must own the process or have GROUP privileges to use this command.

Qualifiers

/AUTO_UNSHELVE (default)

/NOAUTO_UNSHELVE

The /AUTO_UNSHELVE qualifier enables the process to generate a file fault upon read, write, extend or truncate access to a shelved file. The process stalls while the file is unshelved, then proceeds normally.
The /NOAUTO_UNSHELVE qualifier disables file faults: accessing a shelved file returns an error message instead. By default, all processes are started with /AUTO_UNSHELVE enabled.

Example

The following example shows the SET PROCESS /AUTO_UNSHELVE command:

$ SET PROCESS /AUTO_UNSHELVE SMITH_1

The SHELVE command copies file data from online storage to the shelf or the online cache, and deletes the online file data.
Once the file is shelved either to the cache or the shelf, the user cannot read, write, extend, or truncate the file without causing a file fault. However, the user retains access to the file header, and can enter commands such as DIRECTORY and SET FILE without causing a file fault.
The user does not have direct access to either the cache or shelf version of the file.

The SHELVE command requires READ and WRITE access to the file, or an appropriate file access privilege.

Format

SHELVE file_spec[,...]

Parameters

file_spec[,...]

Specifies one or more files to be shelved. If two or more files are specified, separate them with commas. Wildcard characters are allowed.

Qualifiers

/BACKUP

Uses the backup date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers.
If a file has no backup date, it is not selected for the operation.

/BEFORE[=time]

Selects only those files dated prior to the specified time. Specify the time as an absolute time, a delta time, or a combination time, or as one of the keywords: TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process. If not specified, all UICs are eligible.

/CANCEL

Cancels any outstanding command requests for the files.

/CONFIRM
/NOCONFIRM (Default)

Controls whether a request is issued before each SHELVE 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

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/CREATED

Uses the creation date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers.

/ELAPSED=[ delta time]

Selects only those files for which the specifed time has elapsed after the file was subjected to any one of the file events. Specify any one of the following qualifiers with /ELAPSED to indicate the file event that is to be used for selection of the files: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED

The file modification time is considered for selection as default when /ELAPSED is specifed without any of the file event qualifiers.

The default time for /ELAPSED qualifier is 30 days. /ELAPSED qualifier is mutually exclusive with qualifers /BEFORE and /SINCE.

Time must be specified using the OpenVMS format for delta times.

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

Excludes the specified files from the command operation. Wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you provide only one file specification, you can omit the parentheses.

/EXPIRED

Uses the expiration date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers. The file expiration date is used in conjunction with the volume retention functionality.
When volume retention has been enabled for a volume, the expiration date is updated whenever a file is accessed (read or write).
Each time a file is accessed, the current time is added to the minimum retention time. If the sum is greater than the current expiration date, a new expiration date is computed. Updating the expiration date depends on the settings of the retention times for the volume. Refer the OpenVMS SET VOLUME/RETENTION command for further details.
If a file has no expiration date, it is not selected for the operation.

/HIGH_PRIORITY

Specifies a request priority as HIGH. HSM pushes the request to the top of the queue of requests at that time. In case of multiple /HIGH requests, each request is moved to the top of the queue and execution starts with the latest /HIGH request. This prioritizing of requests does not affect urgent requests like:

• file faults
• make space requests

/KEEP[=number_of_versions]

Specifies that the latest n versions of the file are not processed. If /KEEP is specified without a number of versions value, then all versions of the file except the highest version are processed.

/LOG

/NOLOG (Default)

Specifies that a command acknowledgment is displayed. If the command is specified with the
/WAIT qualifier or if the shelf handler can process the command immediately, the log output contains the final result of the operation. If the command is specified with the /NOWAIT qualifier, a message indicating that the request is queued may be displayed on success for long-running operations.

/MODIFIED (Default)

Uses the modification date for selection criteria when using the /BEFORE, /SINCE or
/ELAPSED qualifiers.

/NOTIFY

/NONOTIFY (Default)

Specifies whether a message is sent to the user upon completion of the command operation for each file in the request. The message is sent to all terminals on which the user is logged-in that have BROADCAST enabled.

/SAVE

When issued with the shelve command, HSM will not allow the save sets to span from one tape to another on encountering an end of tape during the BACKUP operation.

/SELECT=(keyword[,...])

Allows selection of files according to size or shelved state. Choose one of the following keywords:

SIZE=MAXIMUM=n Selects files that have fewer blocks than the value of n,
which defaults to 1,073,741,823. Use with MINIMUM=n to
specify a size range for files to be selected.

SIZE=MINIMUM=n Selects files that have blocks equal to or greater than the
value of n, which defaults to 0. Use with MAXIMUM=n to
specify a size range for files to be selected.

NOONLINE Selects only files that are shelved. Use this keyword
to copy shelved file data to additional archive classes.

ONLINE (Default) Selects only files that are online or preshelved. This is the
default file selection.

(ONLINE, NOONLINE) Selects files regardless of their shelved state.

By default, file selection is not based on file size criteria.

/SINCE

/SINCE[=time]

Selects only those files dated after the specified time.

Specify the time as an absolute time, a delta time, or a combination time, or as one of the keywords: TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /SINCE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

Time must be specified using the OpenVMS formats for absolute and delta times.

/WAIT (Default)

/NOWAIT

Specifies whether to wait for the operation to complete. The default is /WAIT. Files moved to the cache typically take the same amount of time as a similar COPY command. Files shelved directly to nearline/offline storage may take anywhere from tens of seconds to tens of minutes. Multiple files take correspondingly longer.

Example

The following example shows the SHELVE/NOTIFY command:

$ SHELVE/NOTIFY JLRM_DATA.DAT
%HSM-S-SHELVED, file $1$DKA0:[BUTLER.DB_FILES]JLRM_DATA.DAT;1 shelved

Converts a formerly shelved or preshelved file to an online file and optionally deletes the cache file and removes the file's HSM cache catalog entry if /NOHOLD is set on the cache.
If the file is subsequently preshelved or shelved, a new copy is made to the HSM subsystem.
The UNPRESHELVE command can be issued on preshelved files only; shelved files cannot be explicitly unpreshelved unless an unshelve is performed first.

This function is automatically invoked if a preshelved file is modified, invalidating its HSM copy of the data.

The UNPRESHELVE command requires READ and WRITE access to the file, or an appropriate file access privilege.

Format

UNPRESHELVE file_spec[,...]

Parameters

file_spec[,...]

Specifies one or more files to be unshelved. If two or more files are specified, separate them with commas. Wildcard characters are allowed.

Qualifiers

/BACKUP

Uses the backup date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers.
If a file has no backup date, it is not selected for the operation.

/BEFORE[=time]

Selects only those files dated prior to the specified time. Specify the time as an absolute time, a delta time, or a combination time, or as one of the keywords: TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED.
Time must be specified using the OpenVMS formats for absolute and delta times.

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process. If not specified, all UICs are eligible.

/CANCEL

/CANCEL

Cancels any outstanding command requests for the files.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a request is issued before each UNSHELVE 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

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/CREATED

Uses the creation date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers.

/ELAPSED=[ delta time]

Selects only those files for which the specifed time has elapsed after the file was subjected to any one of the file events. Specify any one of the following qualifiers with /ELAPSED to indicate the file event that is to be used for selection of the files: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED

The file modification time is considered for selection as default when /ELAPSED is specifed without any of the file event qualifiers.

The default time for /ELAPSED qualifier is 30 days. /ELAPSED qualifier is mutually exclusive with qualifers /BEFORE and /SINCE.

Time must be specified using the OpenVMS format for delta times.

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

Excludes the specified files from the command operation. Wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you provide only one file specification, you can omit the parentheses.

/EXPIRED

Uses the expiration date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers. The file expiration date is used in conjunction with the volume retention functionality. When volume retention has been enabled for a volume, the expiration date is updated whenever a file is accessed (read or write). Each time a file is accessed, the current time is added to the minimum retention time. If the sum is greater than the current expiration date, a new expiration date is computed. Updating the expiration date depends on the settings of the retention times for the volume. Refer the OpenVMS SET VOLUME/RETENTION command for further details.

If a file has no expiration date, it is not selected for the operation.

/LOG

/NOLOG (Default)

Specifies that a command acknowledgment is displayed. If the command is specified with the
/WAIT qualifier or if the shelf handler can process the command immediately, the log output contains the final result of the operation. If the command is specified with the /NOWAIT qualifier, a message indicating that the request is queued may be displayed on success for long-running operations.

/MODIFIED (Default)

Uses the modification date for selection criteria when using the /BEFORE, /SINCE or
/ELAPSED qualifiers.

/NOTIFY

/NONOTIFY (Default)

Specifies whether a message is sent to the user upon completion of the command operation for each file in the request. The message is sent to all terminals on which the user is logged-in that have BROADCAST enabled.

/SELECT=keyword[,...]

Allows selection of files according to size or shelved state. Choose one of the following keywords:

SIZE=MAXIMUM=n Selects files that have fewer blocks than the value of n, which
defaults to 1,073,741,823. Use with MINIMUM=n to
specify a range for files to be selected.

SIZE=MINIMUM=n Selects files that have blocks equal to or greater than the
value of n, which defaults to 0. Use with MAXIMUM=n to
specify a size range for files to be selected.

By default, file selection is not based on file size criteria.

/SINCE[=time]

Selects only those files dated after the specified time. Specify the time as an absolute time, a delta time, or a combination time, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /SINCE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

Time must be specified using the OpenVMS formats for absolute and delta times.

/WAIT (Default)

/NOWAIT

Specifies whether to wait for the operation to complete. The default is /WAIT. Files moved from the cache typically take the same amount of time as a similar COPY command. Files unshelved from nearline/offline storage may take anywhere from tens of seconds to tens of minutes. Multiple files take correspondingly longer.

Example

The following example shows the UNPRESHELVE/NOTIFY command:

$ UNPRESHELVE/NOTIFY JLRM_DATA.DAT
%HSM-S-UNPRESHELVED, file $1$DKA0:[BUTLER.DB_FILES]JLRM_DATA.DAT;1 unpreshelved

Restores a file's data from the shelf to the online disk and makes the file accessible to user operations.

Modifications to the file header may take place between the shelve and unshelve operations.
If this occurs, the current (potentially modified) online file header is in effect when the file is unshelved. If, for example, the access protection is changed, the same user that shelved the file may not be able to unshelve it.

Once a file is unshelved, the user may read, write, extend, or truncate the file as usual.

After a file is unshelved, it is left in the preshelved state. If a subsequent request to shelve the file is received and the file has not been modified since the unshelve operation, it is reshelved without data movement.

The UNSHELVE command requires READ and WRITE access to the file, or an appropriate file access privilege.

Format

UNSHELVE file_spec[,...]

Parameters

file_spec[,...]

Specifies one or more files to be unshelved. If two or more files are specified, separate them with commas. Wildcard characters are allowed.

Qualifiers

/BACKUP

Uses the backup date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers. If a file has no backup date, it is not selected for the operation.

/BEFORE[=time]

Selects only those files dated prior to the specified time. Specify the time as an absolute time, a delta time, or a combination time, or as one of the keywords: TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

Time must be specified using the OpenVMS formats for absolute and delta times.

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process. If not specified, all UICs are eligible.

/CANCEL

Cancels any outstanding command requests for the files.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a request is issued before each UNSHELVE 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

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/CREATED

Uses the creation date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers.

/ELAPSED=[ delta time]

Selects only those files for which the specifed time has elapsed after the file was subjected to any one of the file events. Specify any one of the following qualifiers with /ELAPSED to indicate the file event that is to be used for selection of the files: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED

The file modification time is considered for selection as default when /ELAPSED is specifed without any of the file event qualifiers.

The default time for /ELAPSED qualifier is 30 days. /ELAPSED qualifier is mutually exclusive with qualifers /BEFORE and /SINCE.

Time must be specified using the OpenVMS format for delta times.

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

Excludes the specified files from the command operation. Wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you provide only one file specification, you can omit the parentheses.

/EXPIRED

Uses the expiration date for selection criteria when using the /BEFORE, /SINCE or /ELAPSED qualifiers. The file expiration date is used in conjunction with the volume retention functionality. When volume retention has been enabled for a volume, the expiration date is updated whenever a file is accessed (read or write). Each time a file is accessed, the current time is added to the minimum retention time. If the sum is greater than the current expiration date, a new expiration date is computed. Updating the expiration date depends on the settings of the retention times for the volume. Refer the OpenVMS SET VOLUME/RETENTION command for further details.

If a file has no expiration date, it is not selected for the operation.

/HIGH_PRIORITY

Specifies a request priority as HIGH. HSM pushes the request to the top of the queue of requests at that time. In case of multiple /HIGH requests, each request is moved to the top of the queue and execution starts with the latest /HIGH request. This prioritizing of requests does not affect urgent requests like:

• file falults
• make space requests

/KEEP[=number_of_versions]

Specifies that the latest n versions of the file are not processed. If /KEEP is specified without a number of versions value, then all versions of the file except the highest version are processed.

/LOG

/NOLOG (Default)

Specifies that a command acknowledgment is displayed. If the command is specified with the
/WAIT qualifier or if the shelf handler can process the command immediately, the log output contains the final result of the operation. If the command is specified with the /NOWAIT qualifier, a message indicating that the request is queued may be displayed on success for long-running operations.

/MODIFIED (Default)

Uses the modification date for selection criteria when using the /BEFORE, /SINCE or
/ELAPSED qualifiers.

/NOTIFY

/NONOTIFY (Default)

Specifies whether a message is sent to the user upon completion of the command operation for each file in the request. The message is sent to all terminals on which the user is logged-in that have BROADCAST enabled.

/OVERRIDE

Overrides the consistency checking performed by HSM and forces the file(s) to be unshelved. This qualifier requires BYPASS privilege on files with inconsistent HSM metadata.

Following an UNSHELVE/OVERRIDE, the file's data should be carefully checked for accuracy, because HSM detected an inconsistency between the online file state and the contents of the HSM catalog, and the file data may not be correct.

/SELECT=keyword[,...]

Allows selection of files according to size or shelved state. Choose one of the following keywords:

SIZE=MAXIMUM=n Selects files that have fewer blocks than the value of n,
which defaults to 1,073,741,823. Use with MINIMUM=n
to specify a size range for files to be selected.

SIZE=MINIMUM=n Selects files that have blocks equal to or greater than the
value of n, which defaults to 0. Use with MAXIMUM=n to
specify a size range for files to be selected.

By default, file selection is not based on file size criteria.

/SINCE[=time]

Selects only those files dated after the specified time. Specify the time as an absolute time, a delta time, or a combination time, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /SINCE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

Time must be specified using the OpenVMS formats for absolute and delta times.

/WAIT (Default)

/NOWAIT

Specifies whether to wait for the operation to complete. The default is /WAIT. Files moved from the cache typically take the same amount of time as a similar COPY command. Files unshelved from nearline/offline storage may take anywhere from tens of seconds to tens of minutes. Multiple files take correspondingly longer.

Example

The following example shows the UNSHELVE/NOTIFY command:

$ UNSHELVE/NOTIFY JLRM_DATA.DAT
%HSM-S-UNSHELVED, file $1$DKA0:[BUTLER.DB_FILES]JLRM_DATA.DAT;1 unshelved

The Shelf Management Utility (SMU) is the component of HSM that gives you control over shelving operations. SMU supports SET and SHOW operations for the following managed entities:

• Archive
• Cache
• Device
• Facility
• Policy
• Schedule
• Shelf
• Volume

SMU provides additional commands to control and monitor the HSM environment.

Online help is available for all SMU commands.

SMU commands may be entered directly on the DCL command line using the SMU keyword. Alternatively, a set of commands may be entered from an SMU prompt after entering SMU on the command line.

Use of SMU commands requires SYSPRV, TMPMBX, and SYSLCK privileges for all commands. Additional privileges required for specific commands are noted under that command description.

ANALYZE

The SMU ANALYZE command compares the online file metadata for shelved and preshelved files on the specified volume(s) with the information in the catalog, and optionally repairs the catalog to reflect the online information. When a file is found that is of interest, it's HSM metadata (ACE information) is compared against entries in the catalog and any discrepancies are reported. If the /REPAIR qualifier is used, the discrepancy can be repaired. If /CONFIRM is not used, then the default repair action will be applied.

Format

SMU ANALYZE volume_name[,...]

Parameters

volume_name[,...]

This specifies the volume name of an online disk volume. Wildcards are not allowed, but logical names are supported. The volume can be a member of a volume set. If it is, all volumes in the set will be analyzed.

Qualifiers

/CACHE={CACHE_DEVICE_LIST}

The /CACHE qualifier specifies that the SMU ANALYZE operation should run only on those files of the specified input volume that were cached to the device specified in /CACHE.
Different cache devices can be used at different points of time for a given volume.
For Analyze to run, files that have been cached to devices in the volume set list specified with the /CACHEqualifier, should be present in the device specified as the volume list.
/CACHE supports a comma separated volumeset list. A single volume is treated as a volumeset with one volume.

/CONFIRM

/NOCONFIRM (Default)

When the /REPAIR option is given, /CONFIRM prompts the user to allow repair of each file.
A default of "YES" or "NO" is provided for each confirmation, and this varies on the type of repair. The user can confirm each operation with (YES, 1, TRUE) to proceed for the specific repair, (NO, 0, FALSE) to inhibit the specific repair, (ALL) to proceed with the repair and subsequent repairs with the default confirm answer, and (^Z, QUIT) to stop the analysis/repair.
/NOCONFIRM does not prompt the user on repair and applies repairs with a default confirmation answer of "YES", and does not apply repairs with a default confirmation of "NO". The default is /NOCONFIRM. The following responses are valid:

YES NO QUIT
TRUE FALSE Crtl/Z
1 0 ALL

/OUTPUT[=file_specification]

The /OUTPUT qualifier specifies where to write the output of the command.
The default is /OUTPUT=SYS$OUTPUT. The output can optionally be sent to a file.
If /REPAIR/CONFIRM is specified with /OUTPUT=file_spec, the output is also sent to SYS$OUTPUT in order for the system manager perform the confirmation.
/CONFIRM questions are not sent to the output file, but always to SYS$OUTPUT.

By default, the output is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

/REPAIR

/NOREPAIR (Default)

The /REPAIR qualifier repairs the catalog entries and/or HSM metadata for consistency. Repairs are applied when the user specifies "YES" to a repair confirm question, or according to the default confirm answer when /NOCONFIRM or /CONFIRM answer "ALL" is entered. /NOREPAIR simply scans the files and reports errors, but no updates are made. The default is /NOREPAIR.

SMU ANALYZE/REPAIR command now repairs entries corresponding to PRESHELVED files whose online allocation size and the allocation size in the catalog do not match. If there is an allocation size mismatch and if the revision date of the online file and that recorded in the catalog are same then a new entry with the online allocation size is created for the file. Else the entry is marked unrepairable.

Examples

This example analyses volume $1$DKB500 with no repair:

$ SMU ANALYZE $1$DKB500:

This example analyses volume $1$DKB500 and applies the default repair. Note that this means that some errors are not repaired.

$ SMU ANALYZE/REPAIR $1$DKB500:

This example analyses volume $1$DKB500 and prompts the user for each repair. The default repair can be applied by entering <return> to each prompt. This is the only way that non-default repairs can be applied.

$ SMU ANALYZE/REPAIR/CONFIRM $1$DKB500:

The following examples demonstrate the use of /cache qualifier with SMU ANALYZE.

$ SMU ANALYZE dkb200,dka0 /cache=(dka100,dkb300)

$ smu show cache
Cache device _$1$DUA15: is enabled, Cache flush is held until after
07-Jan-2005 16:30:52.70, Backup is performed at flush intervals,
Cached files are held on delete of online file
Block size: 50000
Highwater mark: 80%
Flush interval: <none>
Cache device _$1$DUA17: is enabled, Cache flush is held until after
07-Jan-2005 16:28:28.64, Backup is performed at flush intervals,
Cached files are held on delete of online file
Block size: 50000
Highwater mark: 80%
Flush interval: <none>
$ shelve Y.Y;1
$ smu locate y.y;1/full
$1$DUA15:[000000]

Y.Y;1 (21,2,0)
File Shelved:
Y.Y;1 5/0 07-Jan-2005 19:23:50.19
Cache copy: _$1$DUA17:
Y.Y$9291950631;1 5/8 07-Jan-2005 19:23:50.19
Shelved on 07-Jan-2005 13:44:28.83

In the above example the file y.y;1 is cached in $1$dua17:

In the following example SMU ANALYZE without /CACHE is used if the header
information for this file is corrupted.

$ smu analyze $1$dua15
%SMU-I-PROCESSING, processing input device $1$DUA15
%SMU-I-STARTSCAN, scanning for shelved files on disk volume _$1$DUA15:
File (19,2,0) "$1$DUA15:[000000]Z.Z;16"
No catalog entry found - file not repairable
File (21,2,0) "$1$DUA15:[000000]Y.Y;1"
Allocation size mismatch - entry not repairable
Current: 0
Catalog: 8
%SMU-I-ENDSCAN, completed scan for shelved files on disk volume _$1$DUA15:
%SMU-I-ERRORS, 2 error(s) detected, 0 error(s) repaired
$ smu analyze $1$dua15/cache=$1$dua15
%SMU-I-PROCESSING, processing input device $1$DUA15
%SMU-I-STARTSCAN, scanning for shelved files on disk volume _$1$DUA15:
No catalog entry for Cached file...$1$DUA15:[000000]Z.Z;16
%SMU-I-ENDSCAN, completed scan for shelved files on disk volume _$1$DUA15:
%SMU-I-ERRORS, 0 error(s) detected, 0 error(s) repaired

Also note that in the above case y.y;1 is not analyzed since it is not cached in $1$dua15:

$ smu analyze $1$dua15/cache=($1$dua15,$1$dua17)
SMU-I-PROCESSING, processing input device $1$DUA15
%SMU-I-STARTSCAN, scanning for shelved files on disk volume _$1$DUA15:
No catalog entry ...$1$DUA15:[000000]Z.Z;16
File $1$DUA15:[000000]Y.Y;1 is cached in _$1$DUA17: will be analyzed
File (21,2,0) "$1$DUA15:[000000]Y.Y;1"
Allocation size mismatch - entry not repairable
Current: 0
Catalog: 8
%SMU-I-ENDSCAN, completed scan for shelved files on disk volume _$1$DUA15:
%SMU-I-ERRORS, 1 error(s) detected, 0 error(s) repaired

In the above example y.y;1 is analyzed since it is present in one of the cache devices specified in the list.

CHECKPOINT

The SMU CHECKPOINT command allows system managers to use the next tape volume for subsequent shelving operations in an archive class, so that the current volume can be stored, possibly in a remote location. Invoking this command executes a DISMOUNT/UNLOAD command on a tape device if the device contains the current shelving volume. The checkpoint operation can be confirmed using an SMU SHOW ARCHIVE command.

Format

SMU CHECKPOINT archive_id[,...]

Parameters

archive_id[,...]

A comma-separated list of the identifiers of the archive classes.

Restrictions

The SMU CHECKPOINT command should not be entered during a repack operation, since the repack is controlling the archive class shelving volume. An attempt to do so results in an error on the checkpoint.

Examples

The following example shows the SMU CHECKPOINT command used for HSM Basic mode. Assuming that the current shelving volume label is HS1005 for archive class 2, the command directs future (pre)shelve operations to volume HS1006, and dismounts and unloads the volume HS1005 from any device on which it is loaded.

$ SMU SHOW ARCHIVE 2

HSM$ARCHIVE02 has been used
Identifier: 2
Media type: CompacTape III
Label: HS1005
Position: 1293
Device refs: 1
Shelf refs: 2

$ SMU CHECKPOINT 2

$ SMU SHOW ARCHIVE 2

HSM$ARCHIVE02 has been used
Identifier: 2
Media type: CompacTape III
Label: HS1006
Position: 0
Device refs: 1
Shelf refs: 1

The following example shows the SMU CHECKPOINT command as used for HSM Plus mode.

$ SMU SHOW ARCHIVE 1

HSM$ARCHIVE01 has been used
Identifier: 1
Media type: TZ87
Density: <NONE>
Label: PLS400
Position: 963
Device refs: 1
Shelf refs: 1
Current pool: HSM-POOL
Enabled pools: HSM-POOL

$ SMU CHECKPOINT 1

$ SMU SHOW ARCHIVE 1

HSM$ARCHIVE01 has been used
Identifier: 1
Media type: TZ87
Density: <NONE>
Label: PLS500
Position: 0
Device refs: 1
Shelf refs: 1
Current pool: HSM-POOL
Enabled pools: HSM-POOL

COPY

The SMU COPY command copies files, including shelved files, from one location to another without unshelving the files, and updates the appropriate HSM catalog to reflect the new location. The input files can be optionally deleted after a successful copy.

The SMU COPY command requires SYSPRV, TMPMBX, SYSLCK, and BYPASS privileges.

Format

SMU COPY source destination

Parameters

source

A full file specification (including disk and directory) of files to be copied.

• Wildcards are allowed
• A file list is not allowed

destination

A disk and directory optional specification for the output location of the files. The original filenames are preserved. If wildcards are used in the destination directory, the semantics of processing are the same as BACKUP, rather than OpenVMS COPY. In particular, if a whole disk is being copied, the output directory specification should be [*...] rather than [000000...].

Restrictions

• The source and destination devices must be difference devices. Attempts to SMU COPY files to the same device will fail. Use the DCL RENAME command to "copy" files on the same device without unshelving files.
• Nodenames are not allowed in the source or destination specifications.
• The source and destination devices must exist.
• You cannot specify a filename or extension in the destination specification, just the device and directory.
• If the catalog server is enabled on the facility, then the SMU COPY command must be entered from the shelf server node. Use the SMU SHOW FACILITY command to determine the current server node before entering SMU COPY.

Qualifiers

/DELETE

/NODELETE

Specifies whether the input file(s) should be deleted after the copy. If so, deleted shelved files are marked in the catalog for later delete.

/LOG

/NOLOG

Specifies if a log of each file copied is made to SYS$OUTPUT.

Examples

The following example shows how to perform a group move of files from one location to another while preserving shelved files across the move. The source files are deleted after the copy.

$ SMU COPY/DELETE DISK$USER1:[JONES...]*.*;* DISK$USER10:[JONES...]

The following example copies all files from one disk to another, and retains the original files.

$ SMU COPY $1$DKA100:[000000...]*.*;* $12$DKA400:[*...]

This command has been provided to deallocate a volume set that has been allocated to HSM.

Format

SMU DEALLOCATE TAPE_VOLUME_ID

Description

This will deallocate the specified tape volume from MDMS database, after scanning through the HSM catalog for any reference of this tape volume. It will NOT deallocate the volume, if any catalog reference is found. This will help in recycling any old volumes that are not currently used by HSM, but allocated to HSM . The state of the volume, after the deallocate operation, will depend on the /deallocate_state specified in the MDMS domain.

Example

The following example performs the deallocate operation of the Tape volume TEST01.

SMU DEALLOCATE TEST01

This command has been provided to detect if files were not properly archived as a result of the occurrenceof a potential shelving error during use of the following versions of HSM:

• HSM 3.0
• HSM 3.0A
• HSM 3.1

The following is an indication of Potential Shelving Errors:

• NULL ACE, on the file header accompanied with an absence of catalog entry, for the file.
  For more information on Interpretation of Log files, please read the DESCRIPTION.
  
  FORMAT
  
  SMU DETECT VOLUME_NAME[,...]

DESCRIPTION

The SMU DETECT command compares the online file's metadata for shelved and preshelved files on the specified volume(s). It checks for the above condition and reports the affected files.

It also checks for shelved/preshelved files with a missing ACE, and suggests to run the command SMU ANALYZER/REPAIR.

Interpretation of Log file:

Message 1:

<File Specification>

"No catalog entry found - file not repairable - Check Possible DATA LOSS"

The above message indicates a possible data loss i.e. possible loss of file.

Message 2:

<File Specification>

"ACE corrupted, Catalog Entry found"

The above message is generated for a file, with a NULL ACE, but a proper catalog entry.

Such files should be recoverable with an Unshelve command.

Message 3:

<File Specification>

"ACE corrupted, Catalog Entry found - Possible Manual Recovery"

The above message is generated for files with a NULL ACE, and a catalog entry with some discrepancy. These files require a manual recovery.

Message 4:

"Error ACE not found for"

<File Specification>

"Run SMU ANALYZE/REPAIR to fix catalog entry"

The above message is generated for files that do not have an ACE. SMU ANALYZE/REPAIR will add an ACE for these files, if a catalog entry is found.

Qualifiers

/OUTPUT

/OUTPUT[=file_specification]

The /OUTPUT qualifier specifies where to write the output of the command. The default is
/OUTPUT=SYS$OUTPUT. The output can optionally be sent to a file. By default, the output is written to the current SYS$OUTPUT device. No wildcard characters are allowed.

EXAMPLE

The following example performs a DETECT on the specified device and directs the output to the LOG file:

$SMU DETECT $1$DK100:/OUTPUT=EXAMPLE.LOG

EXIT

The SMU EXIT command exits the SMU utility. Alternatively, Ctrl/Z or the QUIT command can be used to exit.

Format

SMU EXIT

Example

The following example shows the SMU EXIT command:

SMU> EXIT
$

HELP

The SMU HELP command displays information about an SMU command or topic. In response to the "Topic?" prompt, you can perform the following:

• Enter the name of the command or topic for which you need help.
• Enter HINTS if you are not sure of the name of the command or topic for which you need help.
• Enter a question mark (?) to redisplay the most recently requested text.
• Press the Return key one or more times to exit from Help.

You can abbreviate any topic name, although ambiguous abbreviations result in all matches being displayed. You also can enter HELP SMU from the DCL command line.

Format

SMU HELP

Example

The following example shows the SMU HELP command:

$ SMU HELP SHOW CACHE

SHOW

CACHE

The SHOW CACHE subcommand displays the configuration associated with the cache on the specified volumes.

Note:
The SMU SHOW CACHE command requires SYSPRV privilege.

Format

SMU SHOW CACHE [volume_name,...]

Additional information available:

Additional information available:

Parameters Qualifiers
/OUTPUT

SMU SHOW CACHE Subtopic?

LOCATE

The SMU LOCATE command finds information on shelved files and can be used when the normal unshelve command does not work. Usually, the file to be located cannot be found due to one of the following reasons:

• disk crash
• deleted file
• corrupted file header

It summarizes the information at the end of the output as follows:

$ SMU LOCATE
.
.
.
Total of 16766 entries found
Total of 10522 files found

Entries refer to the catalog entries and files refer to the unique filenames. Hence there may be a difference in these numbers. A Single file can have multiple catalog entries.

SMU LOCATE accepts standard RMS file specification conventions. You can specify either Wildcard characters or, when known, the file identifier (FID). When specifying a FID, any file specification entered as a parameter is ignored.

When entering file specifications, these apply to the file at the time of shelving. If the file has been renamed since the time of shelving, the online filename will not match the name in the catalog, and will not be located. In these situations, you may wish to search by FID instead.

If you use this command and do not provide a file specification, it displays the entire contents of the catalog.

Format

SMU LOCATE [file_spec[,...]]

Parameters

[file_spec[,...]]

Specifies one or more files to locate. If two or more files are specified, separate them with commas. Wildcard characters are allowed.

The file specifications (including wildcards) apply to the file names as they are stored in the catalog at the time of shelving, which is not necessarily the same as the current online file name.

If you do not provide a file specification, the default *:[000000...]*.*;* is used. Any part of a file specification limits the Wildcard specification from *:[000000...]*.*;*. The concept of default device and directory do not apply.

Restrictions

• NODE specifications are ignored because this information is not stored in the HSM catalog.
• Version specifications for latest versions or related versions do not work. For example, [mydir]*.*; or [mydir]*.*;-1 do not work.

Qualifiers

/ARCHIVE=archive_id[,...]

Displays catalog entries of the specified archive_id(s).

/BRIEF (Default)

Displays the catalog file name and file identifier (FID) of the specified files.

/CACHE=device_name[,...]

Displays catalog entries of the specified device name(s).

/CATALOG=file_spec[,...]

Displays catalog entries of the specified catalog file name(s).

/DUMP

Displays all fields of the catalog entries.

/FID=file_identifier

Locates a file by file identifier instead of file specification. The /FID qualifier overrides any file specification on the command line. The specified FID may find a match on more than one file if the files are located on different devices.

/FULL

Displays a complete list of information about the specified file. Once the file is located, it can be restored manually using a BACKUP command.

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

/VOLUME=volume_label [,...]

Displays catalog entries of the specified tape volume label(s).

Examples

The following example shows how to display the contents of the entire HSM catalog using the SMU LOCATE command:

$ SMU LOCATE

$1$DKA0:[000000]
CF5.DAT;1 (6542,14636,0)
CF6.DAT;1 (6542,14637,0)
FURROW.DAT;1 (5989,24877,0)
FOOL.DAT;1 (7293,49830,0)

$1$DKA0:[HSM]
LAURA.TXT;1 (6386,55397,0)

$1$DKA100:[BAILEY.CODE.EXE]
BIG.DAT;1 (503,99,0)
F10.DAT;1 (265,56,0)
F11.DAT;1 (267,76,0)
F12.DAT;1 (269,41,0)
F15.DAT;1 (276,72,0)

$1$DKA100:[SAMPLE]
X.C;1 (1435,38,0)

$1$DKA200:[BUCKLEY]
LOGIN.COM;1 (2316,1,0)
MYFILE.TXT;1 (18117,25594,0)
X.TXT;1 (18051,5,0)
X.X;1 (18116,25591,0)

$1$DKA200:[JENSEN.HSM.CLASS]
SHP_REQUEST.LIS;2 (18600,1,0)

$1$DKA200:[JENSEN.HSM]
X.X;4 (18792,1,0)

$1$DKA200:[JENSEN]
TESTFILE.TXT;1 (12551,9,0)
X.X;3 (18539,1,0)
X.X;7 (18119,25600,0)

$1$DKA200:[WELLS.HSM.WORK]
LOGIN.COM;83 (5038,5,0)
LOGIN.COM;84 (13147,1,0)
UNSHELVE_FILE.TMP;1 (108,270,0)
UNSHELVE_FILE.TMP;1 (102,150,0)
UNSHELVE_FILE.TMP;2 (173,42,0)
UNSHELVE_FILE.TMP;3 (241,44,0)

The following example shows how use SMU LOCATE to locate and recover a deleted file from the shelf copy:

$ DIRECTORY SMU_SRC.MMS
%DIRECT-W-NOFILES, no files found

$ SMU LOCATE SMU_SRC.MMS/FULL

$1$DKA200:[WELLS.HSM.WORK.TEMP]

SMU_SRC.MMS;1 (2538,39,0)
<online file not found>
Shelf copy:
Volume: HS0001 Saveset: 2DDB74A67.BCK Position: 4116
14/15 07-Jan-2005 14:11:53.16
Media type: CompacTape III, Loader
Shelved on 07-Jan-2005 14:11:53.16

$ MOUNT/FOREIGN $1$MUA0: HS0001
%MOUNT-I-MOUNTED, HS0001 mounted on _$1$MUA0:
$ BACKUP $1$MUA0:2DDB74A67.BCK/SAVE_SET SMU_SRC.MMS
$ DIRECTORY SMU_SRC.MMS

Directory $1$DKA200:[WELLS.HSM.WORK.TEMP]

SMU_SRC.MMS

Total of 1 file.

The following examples show how SMU LOCATE interprets file specifications with respect to the Wildcard default.

1.

$ SMU LOCATE X.TMP

Is interpreted as:

$ SMU LOCATE *:[000000...]X.TMP;*

2.

$ SMU LOCATE DISK1:X.TMP;5

Is interpreted as:

$ SMU LOCATE DISK1:[000000...]X.TMP;5

3.

$ SMU LOCATE [DIR1]X

Is interpreted as:

$ SMU LOCATE *:[DIR1]X.*;*

HSM officially supports logical names as follows:

• HSM$BLOCK_SIZE - can be defined to the block size that can be used by HSM$BACKUP. Users should use a block size that is supported by all tape drives in their environment. This will be made an attribute of a device in the next version of HSM.
• HSM$CACHE_FILE_THRESHOLDSIZE - Defining this logical to some numeric value, would by-pass shelving of files with size less than the value specified to the cache and would get directly shelved to tape.
• HSM$CATALOG - Points to the device and directory that contain the default HSM catalog. This logical is not used for shelf catalogs that are defined in the SMU SHELF database.
  Required.
• HSM$CACHE_RENAME - This logical when set to 1 in the system table will allow SMU ANALYZE/RENAME to remove the name discrepancy for files shelved only to cache.
• HSM$FAULT_AFTER_OPEN - When defined to a list of process names, the shelf handler initiates a "background" restore request for the file when an informational request (on file open) is issued from one of the listed processes - it then waits 3 seconds and either completes the request as a file fault normally (e.g after a restore from cache), or returns Designed for use with PATHWORKS.
• HSM$FAULT_ON_OPEN - When defined to a list of process names, the shelf handler performs a file fault on Open when the request is issued from one of the listed processes - Designed for NFS access.
• HSM$INIT_TAPE - On defining this logical to anything system wide, HSM will initialize the newly allocated tape, before writing to it. The logical should be defined in the HSM server node for internal checkpoint to initialize the tapes. In an cluster environment, the logical should also be defined in the client node if the user wishes to give the SMU CHECKPOINT<archive> from the client node.
• HSM$LOG - Points to the device and directory that contain the HSM startup, audit and error logs, and the location of the activity log generated by SMU SHOW REQUESTS/FULL.
  Required.
• HSM$MANAGER - Points to the device and directory that contain the SMU database files, the (Basic Mode) tape device/magazine database and the request log files.
  Required.
• HSM$NO_FAST_TAPE - When defined to anything, indicates that the shelf handler uses OpenVMS skipfile functions for tape positioning, rather than fast SCSI and DSSI positioning algorithms.
• HSM$POLICY_PFQUOTA - This logical can be used to specify the page file quota for the detached process created for executing the primary and secondary policy script files. In the absence of this logical HSM uses the system default page file quota as specified in by the system parameter PQL_DPFLQUOTA. In the following example HSM will set 200000 pages in VAX and 200000 pagelets in ALPHA/I64 as the pagefile quota for the newly created process.

DEFINE/SYS HSM$POLICY_PFQUOTA 200000

• HSM$TEMP_RESTORE_DISK - is introduced to enable users to select the device where the temporary files are created during an unshelve operation.
• HSM$VMS_BACKUP - This logical is applicable only from OpenVMS 7.3-2 onwards. From OpenVMS 7.3-2 onwards, HSM will use only OpenVMS BACKUP for its shelving/unshelving activities. HSM will make use of OpenVMS BACKUP only when the system wide logical HSM$VMS_BACKUP is defined to "1". Based on the version of OpenVMS, HSM startup will define this logical automatically. On versions lower than
  OpenVMS 7.3-2,HSM will use HSM$BACKUP for its shelving/unshelving activities.

RANK

The SMU RANK command displays an ordered list of files that would be shelved if the specified policy were to run on the specified volume. Use this command to analyze the impact of specifying various policy attributes, the amount of shelving for each policy run, or detect files that should not be shelved in advance. You can apply the RANK command to both preventative and reactive policies. The RANK command does not actually shelve any files.

Format

SMU RANK volume_name policy_name

Parameters

volume_name

Specifies the online disk volume on which the policy would be applied. You can specify only one volume, and no wildcards are allowed.

policy_name

policy_name

Specifies the preventative or reactive policy to run on the volume. You can specify only one policy, and no wildcards are allowed.

Qualifiers

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

/UIC=[uic]

Selects only those files belonging to the specified owner user identification code (UIC).
You must specify a valid UIC qualifier value, enclosed in brackets, as described in the VMS DCL Concepts Manual. Use this qualifier to emulate a policy triggered by an exceeded quota event.

Examples

The following examples show usage of the SMU RANK command.
The first example shows the /UIC qualifier:

$ SMU RANK SYS$DISK HSM$DEFAULT_OCCUPANCY/UIC=[SMITH]

Volume capacity: 649040 blocks
Current utilization: 396380 blocks
Volume lowwater mark: 324520 blocks
Blocks to be reclaimed: 71860

Executing primary policy definition
DISK$USER1:[SMITH.V12]TEST.EXE;1
date: 07-Jan-2005 size: 13281

DISK$USER1:[SMITH]LSTARV032.A;1
date: 07-Jan-2005 size: 3564

DISK$USER1:[JONES.TMS.LIB]TEST.OLB;1

DISK$USER1:[SMITH.CODE.LIB]PROD_V2.OLB;1
date: 07-Jan-2005 size: 16218

DISK$USER1:[SMITH.CHECKOUT]TMSA012.B;1
date: 07-Jan-2005 size: 7020
date: 07-Jan-2005 size: 7020

DISK$USER1:[JONES.LST]LST$MAIN_DEBUG.EXE;1
date: 07-Jan-2005 size: 3306

DISK$USER1:[SMITH]TMSA012.C;1
date: 07-Jan-2005 size: 10386

Total of 8 files ranked which will recover 80205 blocks

The following example shows the SMU RANK command with no qualifiers:

$ SMU RANK SYS$DISK HSM$DEFAULT_OCCUPANCY

Policy HSM$DEFAULT_OCCUPANCY is enabled for shelving
Policy History:
Created: 07-Jan-2005 11:01:56.85
Revised: 07-Jan-2005 11:01:56.85
Selection Criteria: State: Enabled
Action: Shelving
File Event: Modification date
Elapsed time: 180 00:00:00
Before time: <none>
Since time: <none>
Low Water Mark: 80 %
Primary Policy: Space Time Working Set (STWS)
Secondary Policy: Least Recently Used (LRU)
Verification:
Mail notification: <none>
Output file: <none>

Quota capacity: 10000 blocks
Current utilization: 5745 blocks
Quota lowwater mark: 5000 blocks
Blocks to be reclaimed: 745

Executing primary policy definition
DISK$USER2:[SMITH]AUDIT.C960214-390;1
date: 07-Jan-2005 size: 20568

Total of 1 files ranked which will recover 20568 blocks

Quota lowwater mark can be reached

REPACK

The SMU REPACK command copies valid shelved file data from one shelf volume to another, while eliminating deleted or obsolete data. It can also be used to recover lost or destroyed shelf volumes. The appropriate catalog(s) are updated to reflect the file data's new shelf location.
Use SMU REPACK in one of the following ways:

• To repack volumes in the same archive class to eliminate obsolete data and recycle the original volumes, specify the archive class in the archive_id parameter, and omit both the
  /TO_ARCHIVE and /FROM_ARCHIVE qualifiers.
• To repack volumes from one archive class to a new archive class, specify the original archive class in the archive_id parameter, and the /TO_ARCHIVE qualifier to specify the new archive class.
• To recover lost shelving volumes using data from another archive class, specify the archive class to recover in the archive_id parameter, and use the /FROM_ARCHIVE to specify the class from which to retrieve the data.

In each case, you may restrict the repack to a set of input volumes using the /VOLUME qualifier. If you do not specify volumes using the /VOLUME qualifier, all volumes in the archive class are repacked.

HSM does not repack obsolete files. Obsolete files are determined by the SHELF attributes previously set. For example, if the SHELF /SAVE_TIME was previously set to 60 days, HSM does not repack any files for which it has been longer than 60 days since the online file was deleted. Similarly, if the SHELF attribute was set to /UPDATES=5, HSM will not repack any file updates that are not among the latest 5 file updates.
If /UPDATES=0 was previously set, it specifies that all file updates or file revisions, will be retained during repack. For further clarification on obsolete files refer to the SMU SET SHELF command and its /UPDATES qualifier.

SMU REPACK requires a disk staging area of at least 100,000 blocks in order to consolidate savesets. You may define a system-wide logical name of HSM$REPACK to point to a device and directory containing this amount of space. If this logical name is not defined, the staging area will be HSM$MANAGER instead. You should ensure that sufficient staging space is available prior to starting the repack. The staging area is cleaned up following the repack.

Repack also requires the use of two tape drives, compatible with the archive class(es) specified in the repack command. One drive must be compatible with the archive_id parameter, and the second must be compatible with any /TO_ARCHIVE or /FROM_ARCHIVE specified, or with the archive_id parameter if neither are specified.

The repack operation starts writing savesets to either the current shelving volume for the output archive class, or to a new shelving volume. A new volume is needed only for the case where the current shelving volume itself is eligible to be repacked, either explicitly or implicitly.

The repack function is performed on the shelf server node, but the command may be entered from any node.

The following are the logical names under REPACK.

• HSM$F_ARP_ERROR_LIMIT - While performing repack,if the volume from which repack is being performed is corrupt, the repack process would abort after a definite number of retries to read the volume. The number of retries it should make can be set by defining the system wide logical HSM$F_ARP_ERROR_LIMIT to an integer. The default is 3.
• HSM$F_ARP_PRINT_DEBUG - Controls the output of repack debug and tracing information. It must be defined as either a valid file specification or as SYS$OUTPUT.
• HSM$F_SHP_BYPASS_REPACK_CONFIG - When defined to anything, causes the shelf handler to disregard any drive deficiencies during Repack configuration validation.
• HSM$REPACK - Points to a device and directory used as a staging area for a repack operation. It is recommended that at least 100,000 blocks are available on the HSM$REPACK disk. If not defined, HSM uses HSM$MANAGER for this purpose.
  The logicals HSM$CATALOG, HSM$LOG and HSM$MANAGER must be correctly defined for HSM to operate. All other logical names are optional.

Format

SMU REPACK archive_identifier

Parameters

archive_identifier

This specifies the identifier of the archive class to repack. Only one archive class can be re-packed at a time.

Restrictions

This command requires BYPASS privilege. The /FROM_ARCHIVE and /TO_ARCHIVE qualifiers are mutually exclusive. If the /FROM_ARCHIVE qualifier is specified, the /THRESHOLD qualifier is ignored.

Qualifiers

/CANCEL

Cancels the current repack operation.

/CORRUPT

This qualifier has been added to the repack command and is used in conjunction with /FROM. It takes the name of a tape as input and deletes all catalog entries pertaining to this tape volume. This helps in removing unwanted references for a corrupt tape.

Example:

If tape1 belonging to archive 1 is corrupt and if its contents need to be repacked from tape2, belonging to archive 2, then the catalog entries for tape1 remain useless in the HSM catalog after the repack is done. These entries can now be removed from the HSM CATALOG by adding the corrupt qualifier with the corrupt tape's name whose corresponding entries need to be purged.

Example:

$ SMU REPACK 1/FROM 2/VOL=TAPE1/NOTHRESHOLD/CORRUPT=TAPE1

/FROM_ARCHIVE=archive_id

You can repack an archive class using the data from a different (but duplicate) archive class.
Use this option to restore lost or destroyed shelf volumes.

/LIST[=file_specification]

/NOLIST

List all files repacked in the specified file, or to the default HSM$LOG:HSM$REPACK.LIS if no file specification is supplied. The supplied file specification must not exceed 140 characters.

/PURGE

This new to the repack command deletes all obsolete entries with reference to the archive class specified. Actual repack operation is not attempted with this operation and only the HSM catalog is cleaned of obsolete entries.

Example:

$ SMU REPACK 1 /PURGE

/REPORT

If REPORT option is specified, Repack will only perform the analysis phase of a repack and not actual repacking. This feature would be extremely useful for a system manager to:

• analyze repacking requirements/benefits
• select the most useful threshold values
• and schedule repacks at convenient times

If used with the /SAVE option, the resultant candidates file will be saved and can be used in subsequent repack/s if the system manager wants the entire repack, as analyzed, to proceed.

/RESTART

Since repacks can take several hours/days to complete, it would be useful to allow the continuation of a repack that had been interrupted for any reason. The /RESTART qualifier would utilize the current candidates file and restart the repack from where it left off, without a further analysis or repacking files/volumes that had already been repacked.

/SAVE

Repack deletes the candidates file when it completes normally and in case of error (or on /CANCEL). With a /SAVE qualifier, the candidates file would be retained, and a subsequent repack could continue the repack from where it left off with a REPACK/RESTART. In addition, the candidates file could be retained from a REPACK/REPORT/SAVE command, which performs just the analysis phase. Subsequently the data moving phase could be initiated by a
REPACK/RESTART.

/THRESHOLD[=percent]

/NOTHRESHOLD

Defines a threshold of deleted and obsolete data for consideration on whether to repack a particular volume or volume set. The default is a threshold of 50%, meaning that a volume (set) will only be repacked if its percentage of obsolete data (determined by the number of obsolete files) is 50% or more of the total number of files on the tapes.
The /NOTHRESHOLD qualifier (or /THRESHOLD=0) repacks all associated volumes in the archive class. A threshold of 100% repacks only volumes that contain no valid data.

/TO_ARCHIVE=archive_id

Defines a different archive class, possibly containing different media types, as the output of the repack. Use this qualifier to copy data from one archive class to another, or to upgrade to new tape technology.

/VOLUME[=volume_name[,...]]

Specifies specific volumes in an archive class to be repacked. A volume list is supported but wildcards are not allowed. If a specified volume is a member of a volume set, the entire volume set is eligible for packing. The volume list can contain up to 9 volumes.

Examples

In this example, perform a repack of volumes containing files shelved to archive class 1. Select from all volumes in the archive class, and repack only those in which the percentage of records belonging to obsolete files exceeds the default threshold of 50%. New volumes are allocated to the archive class and repacked volumes are released from the archive class automatically.

$ SMU REPACK 1

In this example, perform a repack of volumes containing files shelved to archive class 2. Select from all volumes in the archive class, and repack only those in which the percentage of obsolete files exceeds 80%. New volumes are allocated to the archive class and repacked volumes are released from the archive class automatically. List all files which are moved to new volumes in HSM$LOG:HSM$REPACK.LIS.

$ SMU REPACK 2/THRESHOLD=80/LIST

In this example, perform a repack of volumes containing files shelved to archive class 11. Select from volumes in the volume set which contains volume AFA200, and repack all volumes in the volume set, regardless of the percentage of records that belong to obsolete files. New volumes are allocated to the archive class and repacked volumes are released from the archive class automatically.

$ SMU REPACK 11/VOLUME=AFA200/NOTHRESHOLD

In this example perform a repack of volumes containing files shelved to archive class 21 onto volumes compatible with those in archive class 22. Repack all volumes in the archive class, regardless of the percentage of records which belong to obsolete files. New volumes are allocated to archive class 22 while repacked volumes are released from the archive class 21 automatically. List all files which are moved to new volumes in REPACK_21.LOG in the current directory.

$ SMU REPACK 21/TO_ARCHIVE=22/LIST=REPACK_21.LOG/NOTHRESHOLD

In this example, replace the non-obsolete shelved file data on volumes in archive class 16 which are members of the volume set which contains volume HSM001, using shelved file data on volumes in archive class 32. New volumes are allocated to the destination archive class; no volumes are released from the archive class.

$ SMU REPACK 16/FROM_ARCHIVE=32/VOLUME=HSM001

SET

ARCHIVE

The SMU SET ARCHIVE command defines and modifies information about an archive class. You must use this command to tell HSM Basic mode what archive classes are available and to associate archive classes with media type definitions for HSM Plus mode.

Format

SMU SET ARCHIVE archive_id[,...]

Parameters

archive_id[,...]

Specifies the archive classes to be set.

Qualifiers

/ADD_POOL=(pool_name[,...]) (Plus mode only)

Adds a volume pool to the list of pools for the archive class. The pool_name must be assigned in MDMS. This qualifier is valid only for HSM Plus mode.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a question is asked before each SET ARCHIVE operation to confirm that the operation should be performed on that archive class. The following responses are valid:

YES NO QUIT
TRUE FALSE Ctrl/Z
1 0 ALL

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/DELETE

Deletes an archive class. This qualifier is valid only if no files have been shelved to this archive class.

/DENSITY=density (Plus mode only)

If a value is assigned to the DENS_n value in TAPESTART.COM for the media type to be used for this archive class, then you must use this qualifier and specify the exact same string as is specified in TAPESTART.COM. This qualifier is valid only for HSM Plus mode.

Once an archive class has been used, you cannot modify the density.

/LABEL=volume_label (Basic mode only)

Explicitly sets the desired volume label for the HSM Basic mode archive class. Use this command only if there has been a system failure, or if HSM cannot determine the correct volume label. This command provides an emergency reset for recovery purposes only. The next shelve operation for the archive class is performed on the specified volume. The volume label must conform to the HSM Basic mode volume label convention of HSxnnn.

HP recommends you use the SMU CHECKPOINT command instead of
SET ARCHIVE /LABEL for removal of shelving volumes under normal circumstances.
When you reset the volume label with SET ARCHIVE /LABEL, the shelving tape position is reset to zero.

/LOG

/NOLOG (Default)

Specifies that a command acknowledgment is displayed. If the command is specified with the
/WAIT qualifier or if the shelf handler can process the command immediately, the log output contains the final result of the operation. If the command is specified with the /NOWAIT qualifier, a message indicating that the request is queued may be displayed on success for long-running operations.

/MEDIA_TYPE=media_type (Plus mode only)

Required qualifier for HSM Plus mode that identifies the media type defined in TAPESTART.COM to use for this archive class. The media type must exactly match a defined media type in TAPESTART.COM. This qualifier is valid only for HSM Plus mode.

Once an archive class has been used, you cannot modify the media type.

/REMOVE_POOL=pool_name (Plus mode only)

Removes a volume pool from the list of pools for the archive class. This qualifier is valid only for HSM Plus mode.

/SAVESET_SIZE=Saveset_size in MB

Specifies the maximum SAVESET_SIZE that will be used in a shelving operation. Multiple files upto the maximum SAVESET_SIZE specified or 1000 files will be combined to make a single saveset to improve performance.

Examples

The following example shows the SMU SET ARCHIVE command for HSM Basic mode:

$ SMU SHOW ARCHIVE 1

%SMU-W-ARCHID_NF, archive class id 1 not found
%RMS-E-RNF, record not found

$ SMU SET ARCHIVE 1

$ SMU SHOW ARCHIVE 1

HSM$ARCHIVE01 has not been used
Identifier: 1
Media type: Unknown Type
Label: HS0001
Position: 0
Device refs: 0
Shelf refs: 0
SAVESET_SIZE:40 MB

The following example shows the SMU SET ARCHIVE command for HSM Plus mode:

$ SMU SHOW ARCHIVE 2

%SMU-W-ARCHID_NF, archive class id 2 not found
%RMS-E-RNF, record not found

$ SMU SET ARCHIVE 2 /MEDIA_TYPE=TZ87

$ SMU SHOW ARCHIVE 2

HSM$ARCHIVE02 has not been used

Identifier: 2
Media type: TZ87
Density: <NONE>
Label: <NONE>
Position: 0
Device refs: 0
Shelf refs: 0
Current pool: <NONE>
Enabled pools: <NONE>

SET

CACHE

The SMU SET CACHE command creates or modifies an existing HSM cache volume or a magneto-optical volume. Any device that appears as a system-mounted FILES-11 disk volume can be used as a cache volume, including magneto-optical devices.

You can use cache volumes for one of two purposes:

• As a temporary online staging area to speed shelving operations. A cache used for this purpose is set up with a limited block size, and a regular flush interval. Shelving operations are initially directed to the cache and complete in a similar amount of time as a normal file copy. At a later time, the cache is flushed to the archive classes defined for nearline or offline storage, and files in the cache are deleted.
• As an alternative shelf, using magneto-optical devices or excess online disk devices.
  A cache used for this purposes usually uses the entire device for caching, but does not flush the files to nearline or offline storage. Rather, additional copies are made to the nearline or offline archive classes at shelving time, using the /BACKUP qualifier.
• HSM optionally periodically flushes the cache to the shelf archive classes. The interval at which the flush occurs is controlled by the /INTERVAL and /AFTER qualifiers.

By default, caching is disabled.

Format

SMU SET CACHE device_name[,...]

Parameters

device_name[,...]

Specifies the online system-mounted devices that are to be used as shelf cache. If two or more devices are specified, separate them with commas. Wildcard characters are only allowed for updates to existing cache devices.

Qualifiers

/AFTER[time]

Requests that the cache flush operation be held until after a specific time. If no time value is specified, an immediate cache flush begins. Use this qualifier without a value to trigger an immediate cache flush at any time.

Specify the time as either an absolute time, a delta time, or a combination time. For more information on specifying time values, see the OpenVMS DCL Concepts Manual.

/BACKUP

/NOBACKUP (Default)

Controls whether copies to the shelf archive classes are made when the file is moved to the cache at shelving time (/BACKUP), or when the cache is flushed at a later time (/NOBACKUP). The default is /NOBACKUP, which provides fast shelving and unshelving, but only provides one copy of the shelved data until a cache flush is performed.

The /BACKUP qualifier creates the shelf copies concurrently with the cache copy, resulting in slow shelving but fast unshelving. The shelve operation is not completed until all copies are made. Use this option when a cache device is used as a permanent repository rather than a staging area.

/BLOCK_SIZE[=BLOCK_SIZE]

The maximum number of blocks HSM can use for caching on the volume. The default is 50,000 blocks. If any shelve operation would exceed the block size of the cache, the file is shelved directly to the shelf archive classes instead.

If the /BLOCK_SIZE is set to zero the entire disk may be used for the cache.

/CONFIRM (Default)

/NOCONFIRM

Controls whether a request is issued before each SET CACHE operation to confirm that the operation should be performed on that disk volume. The following responses are valid:

YES NO QUIT
TRUE FALSE Ctrl/Z
1 0 ALL

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/DELETE

Removes the cache entry from the database and causes an immediate flush of any files in the cache to the shelf archive classes.

/DISABLE

Disables the devices for use as an online shelf cache. However, no cache flush is triggered when a device is disabled.

/ENABLE (Default)

Enables the devices for use as an online shelf cache.

/HIGHWATER_MARK=percentage

Specifies a high water mark usage capacity for the cache, at which point cache flushing is initiated. Files can continue to be shelved to the cache above the high water mark as long as the
/BLOCK_SIZE value is not exceeded. The default for the /HIGHWATER_MARK qualifier for the cache is 80 percent of the block size.

If you wish to disable cache flushing based upon capacity, set the high water mark to 100 percent.

/HOLD (Default)

/NOHOLD

Specified whether the cache file is deleted when the online file is deleted or modified. /HOLD is the default and keeps the file in the cache when the online file is deleted or modified. /NOHOLD allows the file to be deleted from cache when the online file is deleted or modified. This reduces cache space in permanent caches and avoids unnecessary flushes of deleted or modified files.
If you use the /NOHOLD option, HSM cannot recover deleted or modified files from cache.

/INTERVAL[=delta_time]

/NOINTERVAL

Requests that the cache flush operation be performed at regular intervals. If no interval qualifier or value is specified, the default interval is six hours.

If /NOINTERVAL is specified, the cache is not flushed at regular intervals.
If a /HIGHWATER_MARK value of less than 100 percent is specified, the cache is flushed based on usage only.

If the high water mark is set to 100 percent and /NOINTERVAL is specified, the cache is never flushed. Use this option when using the cache as an alternative shelf.

Delta time is expressed as dddd-hh:mm:ss.cc. The value used cannot be less than one minute.

/LOG

/NOLOG (Default)

Displays the device specification of each cache device modified as the command executes.

Examples

The following examples show the SMU SET CACHE command.

The first command sets up an online disk volume as a staging area, with a maximum usage of 100,000 blocks, and a flush interval of one day to begin at 4:00 am. By default, the cache is enabled, and a high water mark of 80 percent applies.

$ SMU SET CACHE _$15$DKA100: /BLOCK=100000/INTERVAL=1-
$ /AFTER=04:00:00
$ SMU SHOW CACHE _$15$DKA100:

Cache device _$15$DKA100: is enabled, Cache flush is held until
after 07-Jan-2005 04:00:00.00, Backup is performed at flush
intervals, Cached files are held on delete of online file
Block size: 100000
Highwater mark: 80%
Flush interval: 1 00:00:00.00

The second example sets up a magneto-optical volume as an alternative shelf. Shelf archive copies are made at shelving time, the entire volume may be used for caching, and there is no flushing.

$ SMU SET CACHE _$1$JKA0: /BLOCK=0/BACKUP/NOINTERVAL -
$ /HIGHWATER_MARK=100
$ SMU SHOW CACHE _$1$JKA0:

Cache device _$1$JKA0: is enabled, Cache flush is held until
after 07-Jan-2005 09:53:42.55, Backup is performed at
shelving time, Cached files are held on delete of online
file Block size: 0 Highwater mark: 100%
Flush interval: <none>

SET

DEVICE

The SMU SET DEVICE command specifies the nearline or offline storage devices that HSM can use to perform copies to and from the shelf archive classes. Devices specified in SET DEVICE must be tape devices, and must not be allocated or mounted by any user while HSM is using them. Devices can include tape magazine loaders, or large tape jukeboxes for HSM Plus mode. HSM uses OpenVMS BACKUP on foreign-mounted volumes for all shelf copy operations.

The devices can be either shared with other users, or exclusively dedicated to HSM. When a device is shared, HSM relinquishes control of the device after a short period of inactivity after the last shelving operation and no pending operations for the device.

Each device supports one or more archive classes, which must be associated with the device by using this command. Devices can be associated with any archive class with a compatible media type. For HSM Basic mode, the media type for an archive class is established implicitly when the first device is associated with it, and assumes the media type of that device. For HSM Plus mode, the media type and density are assigned explicitly to the archive classes which are associated with the device. Once a media type is established, a device with an incompatible media type cannot be associated with the archive class, unless both of the following are true:

• The archive class has not been used (no shelf copies have ever been made)
• No other device is associated with the archive class (device reference count is zero)

You can use the SMU SHOW ARCHIVE command to verify these conditions.

In addition, devices associated with an archive class must all be magazine loaders, or not be magazine loaders, at any one time.

Each device can be enabled for shelving, unshelving, or both operations. Assigning specific operations for a device can result in more optimal operations, fewer tape mounts and operator interaction, at the expense of hardware resources.

When specified for unshelving only, the association of device with archive class additionally includes media types that can read (but not write) the device. For example, a TK70 device (media CompacTape II) can be specified for unshelving an archive class written by a TK50 device (media CompacTape I), but not vice versa.

Refer the HSM Guide to Operations for a complete discussion of magazine loaders and compatible media types for HSM Basic mode.

When you set a device and do not use either the /SHARE or the /DEDICATE qualifiers, HSM defaults the device to be shared with other applications (/SHARE=ALL). If you want HSM to dedicate use of the device for shelving or unshelving operations, you must specify the
/DEDICATE qualifier.

HP recommends you use the SMU SHOW DEVICE command after you input an SMU SET DEVICE command to confirm your device definitions.

Format

SMU SET DEVICE device_name[,...]

Parameters

device_name[,...]

Specifies the nearline or offline devices that are to be used. If two or more devices are specified, separate them with commas. Wildcard characters are only allowed for updates to existing shelf devices.

If specifying a remote device in Plus mode, a node name or a logical that maps to a node name must precede the device name.

Restrictions

In HSM Plus mode, for any devices that are not visible across the VMScluster (for example, SCSI devices that are not TMSCP served), SMU SET DEVICE must be entered on the node from which the devices are visible.

Qualifiers

/ARCHIVE_ID=(archive_id[,...])

/NOARCHIVE_ID

Defines the identifiers for archive classes that are supported by this device. Up to 36 archive class identifiers may be listed. If only one archive class identifier is provided, you can omit the parentheses. The archive classes must already be defined prior to entering this qualifier.

The /NOARCHIVE_ID qualifier means there are no archive classes defined for the device.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a request is issued before each SET DEVICE operation to confirm that the operation should be performed on that device. The following responses are valid:

YES NO QUIT
TRUE FALSE Ctrl/Z
1 0 ALL

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/DEDICATE=keyword

Allows you to dedicate a nearline or offline device exclusively to HSM. A device can be selected to service shelve, unshelve, or all operations. The possible keywords are as follows:

ALL Dedicates the device for shelve, (Default) preshelve and unshelve
operations.
This is the default if you do not specify either /DEDICATE or
/SHARE.

SHELVE Dedicates the device exclusively for shelve and preshelve operations.

UNSHELVE Dedicates the device exclusively for unshelve operations.

The /DEDICATE and /SHARE qualifiers are mutually exclusive.
The /DEDICATE qualifier cannot be used with the /REMOTE qualifier.

/DEFAULT

Updates the default device record HSM$DEFAULT_DEVICE.

/DELETE

Removes the storage device entry from the database. Pending requests for the device are requeued to other devices. If a volume is mounted on the device, it will take about one minute for that volume to be dismounted after you issue this directive.

/DISABLE

Disables the devices for use by HSM.

/ENABLE (Default)

Enables the devices for use by HSM.

/LOG

/NOLOG (Default)

Displays the device specification of each device modified as the command executes.

/REMOTE (Plus Mode only)

Required to tell HSM the device is remote (not directly connected to the VMScluster).
The device specification must include the node name or the node name must be included in a logical name assignment for the device. The device must be identified through MDMS with the same exact specification as is used here.

The /DEDICATE qualifier cannot be used with the /REMOTE qualifier. You cannot dedicate remote devices for HSM use.

/ROBOT_NAME=robot_name (Basic mode only)

/NOROBOT_NAME (default)

In Basic mode, if the device is a robot-controlled loader (for example, a TZ877 loader), you must specify a robot name for the device to be treated as a loader.

The robot name must be specified for the loader to be robotically controlled.
If /NOROBOT_NAME (the default) is specified, any loaders will be treated as sequentially loadable stackers. Only non-loader standalone tapes should be specified with
/NOROBOT_NAME.

This qualifier is not supported in Plus mode.

/SHARE=keyword

Allows the system administrator to share a nearline or offline device between HSM and other users. A device can be selected to share shelve, unshelve, or all operations with system users. Sharing devices with HSM allows the system administrator to allow multiuser access to the device. When enabled, the shelf handler relinquishes control of the device after the series of operations is completed.

The possible keywords are as follows:

ALL (Default) Shares the device on shelve, preshelve, and unshelve
operations with other system users.

SHELVE Shares the device on shelve and preshelve operations with
other system users.

UNSHELVE Shares the device on unshelve operations with other system
users.

The /DEDICATE and /SHARE qualifiers are mutually exclusive.

Examples

The following example sets the device $11$MUA0:, a magazine loader, for shared use with archive classes HSM$ARCHIVE01 and HSM$ARCHIVE02 for HSM Basic mode. The device is connected to an HSJ controller with the robot name equal to the HSJ command disk name:

$ SMU SET DEVICE/ARCHIVE_ID=(1,2)/LOG/SHARE=ALL $11$MUA0:-
/ROBOT_NAME=$1$DUA204:
%SMU-I-DEVICE_CREATED, device _$11$MUA0: created
$ SMU SHOW DEVICE

HSM drive _$11$MUA0: is enabled.
Shared access: < shelve, unshelve >
Drive status: Configured
Media type: CompacTape III, Loader
Robot name: _$1$DUA204:
Enabled archives: HSM$ARCHIVE01 id: 1
HSM$ARCHIVE02 id: 2

The following Plus mode example sets the device NODE1$MKB300 for dedicated shelving and unshelving, using archive classes 4 and 5:

$ SMU SET DEVICE/ARCHIVE_ID=(4,5)
/DEDICATE=ALL NODE1$MKB300:
$ SMU SHOW DEVICE NODE1$MKB300:

HSM drive _NODE1$MKB300: is enabled.
Dedicated access: <shelve, unshelve>
Drive status: Configured
Enabled archives: HSM$ARCHIVE04 id: 4
HSM$ARCHIVE05 id: 5

The following Plus mode example sets the remote device $1$MUA23 on a remote node for shared shelving and unshelving, using archive classes 2 and 3.

$ SMU SET DEVICE/ARCHIVE_ID=(2,3)/REMOTE YOURNODE::$1$MUA23:
$ SMU SHOW DEVICE YOURNODE::$1$MUA23:

HSM remote drive YOURNODE::_$1$MUA23: is enabled.
Shared access: < shelve, unshelve >
Drive status: Configured
Enabled archives: HSM$ARCHIVE02 id: 2
HSM$ARCHIVE03 id: 3

SET

FACILITY

The SMU SET FACILITY command controls HSM operations on a VMScluster-wide basis, allows specification of designated shelf servers, controls event logging, and allows you to convert from HSM Basic mode to HSM Plus mode without reinstalling the HSM software.

Format

SMU SET FACILITY

Qualifiers

/CATALOG_SERVER

/NOCATALOG_SERVER (Default)

Determines whether all cache operations and catalog updates are performed by the shelf server node. /CATALOG_SERVER restricts all cache operations and catalog updates to the current shelf server node. /NOCATALOG_SERVER (default) allows cache operations and catalog updates to be performed by the requesting client node. This does not affect tape operations which are always performed on the shelf server node.

/DISABLE=keyword

Disables HSM from performing specified operations on the VMScluster. The command applies to all volumes on all shelves on all nodes. This qualifier also disables in- progress cache flushing.
ALL Disables the facility for preshelve, shelve, unshelve and cache flush operations.
SHELVE Disables the facility for preshelve, shelve, and cache flush operations.
UNSHELVE Disables the facility for unshelve operations.

/ENABLE=keyword

Enables HSM to perform specified shelving operations. If neither /ENABLE nor /DISABLE are specified, HSM defaults to /ENABLE=ALL. The possible keywords are as follows:

ALL Enables the facility for preshelve, shelve, unshelve and cache flush
operations.
SHELVE Enables the facility for preshelve, shelve and cache flush operations.
UNSHELVE Enables the facility for unshelve operations.

/EVENT_LOGGING=keyword

Enables and disables HSM event logging. The possible keywords are as follows:
[NO]ALL Enables/disables the facility for all types of logging.
[NO]AUDIT Enables/disables audit logging.
[NO]ERROR Enables/disables error logging.
[NO]EXCEPTION Enables/disables exception logging.
By default, all logging is enabled.

/NOLOG (Default)

Displays the facility that was modified as the command executes.

/MODE=mode_type

Tells HSM the mode in which to operate. Valid keywords for this qualifier are:
Basic Operate HSM in Basic mode, which provides limited device support.

Plus Operate HSM in Plus mode, which provides enhanced device support
through the Media, Device and Management Services for Open VMS (MDMS)
software.

The initial default value for the mode depends on the mode in which HSM is installed. Once you run in HSM Plus mode, you cannot go back to HSM Basic mode. For information on converting from HSM Basic mode to HSM Plus mode, see HSM for OpenVMS Guide to Operations.

/REENABLE

Reenables all operations for the facility. If the shelf handler is failing too often, HSM may disable the facility for shelving, unshelving, disk full, or quota error conditions. This command can be used to reenable the facility once the error condition is corrected.

/RESET_LOGS

Closes the current audit and error logs, then starts writing to a new version. The closed logs can be subsequently reviewed, shelved or deleted.

/SERVER=(server_name[,...])

/NOSERVER

Specifies which nodes can function as shelf servers.

Nodes are entered as a comma-separated list. Up to ten nodes can be entered as potential servers. Shelf server nodes must have access to all nearline/offline tape devices in Basic mode.

If /NOSERVER is entered, all nodes in the VMScluster are eligible to be a shelf server.

Example

The following example enables HSM for all error logging, and designates nodes SYS001 and SYS004 as shelf servers:

$ SMU SET FACILITY/EVENT_LOGGING=ALL/SERVER=(SYS001,SYS004)

$ SMU SHOW FACILITY

HSM for OpenVMS is enabled for Shelving and Unshelving
Facility History:
Created: 07-Jan-2005 10:36:34.96
Revised: 07-Jan-2005 13:49:37.50
Designated servers: SYS001
SYS004
Current server: SYS001
Catalog server: Disabled
Event logging: Audit
Error
Exception
HSM mode: Basic
Remaining license: 500 gigabytes

SET

POLICY

The SMU SET POLICY command defines a preventative or reactive policy that can be executed to maintain a desired capacity usage on online disk volumes.

Format

SMU SET POLICY policy_name[,...]

Parameters

policy_name[,...]

Specifies one or more policy names. If two or more policy names are specified, separate them with commas. Wildcard characters are allowed.

Policy names are limited to 31 alphanumeric characters, including the hyphen and underscore.

Qualifiers

/BACKUP

Uses the backup date for selection criteria when using the /BEFORE and /SINCE qualifiers and the STWS and LRU policy algorithms. If a file has no backup date, it is not selected for the operation.

The /BACKUP, /CREATED, /EXPIRED, and /MODIFIED qualifiers are mutually exclusive. The default is /EXPIRED if none of the above are entered. If you specify one of these qualifiers without the /BEFORE, /ELAPSED, or /SINCE qualifiers, /BEFORE, /ELAPSED, and /SINCE values are unaffected.

If a file has no backup date, it is not selected for shelving by the predefined algorithms.

/BEFORE[=time] /NOBEFORE

Selects only those files dated prior to the specified time. Specify the time as an absolute time, a combination time, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection:

/BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

Time must be specified using the OpenVMS formats for absolute and delta times.

The values specified by the /BEFORE qualifier are translated to absolute values that do not change between policy runs. To specify a relative before time, use the /ELAPSED qualifier instead. The /BEFORE qualifier is mutually exclusive of the /ELAPSED qualifier.

The /NOBEFORE qualifier clears any previously issued SET POLICY/BEFORE values.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a request is issued before each SET POLICY operation to confirm that the operation should be performed on that policy.

The following responses are valid:

YES NO QUIT
TRUE FALSE Ctrl/Z
1 0 ALL

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/CREATED

Uses the creation date for selection criteria when using the /BEFORE and /SINCE qualifiers and the STWS and LRU policy algorithms.

The /BACKUP, /CREATED, /EXPIRED, and /MODIFIED qualifiers are mutually exclusive. The default is /EXPIRED if none of the above are entered. If you specify one of these qualifiers without the /BEFORE, /ELAPSED, or /SINCE qualifiers, /BEFORE, /ELAPSED, and /SINCE values are unaffected.

/DEFAULT

Sets or modifies the system policy defaults. When a new volume definition is created, all default attributes are set from this default volume definition.

The /DEFAULT qualifier cannot be used with a parameter value.

/DELETE

Deletes the entry from the policy database.

/DISABLE

The policy is disabled from execution until it has been reactivated by the /ENABLE qualifier.

/ELAPSED=delta_time

/NOELAPSED

Selects only those files that are equal to or older than the specified delta time. The time is expressed as a relative value and applied as such at each policy run.

Delta time is an offset (a time interval) from the current date and time to a time in the past.
The general format for a delta time is as follows:

"[dddd-][hh:mm:ss.cc]"

The fields are as follows:

dddd Number of days an integer in the range 0 to 9999
hh Number of hours an integer in the range 0 to 23
mm Number of minutes an integer in the range 0 to 59
ss Number of seconds an integer in the range 0 to 59
cc Number of hundredths of seconds in the range 0-99

The following table shows some examples of delta time specifications:

The /ELAPSED qualifier is mutually exclusive of the /SINCE and /BEFORE qualifiers.
The /NOELAPSED qualifier clears any previously issued SET POLICY/ELAPSED values.

/ENABLE (Default)

The policy is enabled for execution. The policy remains enabled until it is explicitly disabled.

/EXPIRED (Default)

Uses the effective date of last access for selection criteria when using the /BEFORE, /SINCE and /ELAPSED qualifiers, and the STWS and LRU policy algorithms. This qualifier uses the file's expiration date and the volume's retention time to determine the date of last access according to the following formula:

date_of_last_access = expiration_date - maximum_volume_retention

While specifying date and time values in the associated /BEFORE, /SINCE and /ELAPSED qualifiers, you should specify the date of last access rather than simply the expiration date, which is likely to be in the future.

If volume retention is not enabled on the volume, HSM will select no files for shelving when the policy is run. Therefore, to use file selection based on expiration date (the default), you must first enable volume retention on the volume (see HSM for OpenVMS Guide to Operations).
HSM will automatically initialize expiration dates on all files on the volume to the current date plus the maximum retention time when the policy is first run.

The /BACKUP, /CREATED, /EXPIRED, and /MODIFIED qualifiers are mutually exclusive. The default is /EXPIRED if none of the above is entered. If you specify one of these qualifiers without the /BEFORE, /ELAPSED, or /SINCE qualifiers, /BEFORE, /ELAPSED, and /SINCE values are unaffected.

/LOG

/NOLOG (Default)

Displays a message for each schedule definition as the command executes.

/LOWWATER_MARK=[percentage]

The /LOWWATER_MARK qualifier establishes a threshold where policy execution terminates. It is set to the desired percentage of volume capacity that HSM attempts to reach while executing a policy.
Possible percentages range from zero to 100 percent. The shelving policy continues to shelve dormant files until the low water mark is reached.
For instance, if the low water mark is set to 20 percent, then HSM shelves dormant files until the disk usage is 20 percent or less. The default low water mark is 80 percent.

/MAIL=destination

/NOMAIL (Default)

Sets notification upon completion of the operation through user mail. The destination can be a specific user, such as SOCCR::SMITH, or a distribution list contained in a command procedure, such as @POLICY.DIS.

The mail header indicates success or failure. The message body contains a brief summary of shelving operations that were executed.

/MODIFIED

Uses the modification date for selection criteria when using the /BEFORE and /SINCE qualifiers and the STWS and LRU policy algorithms.

The /BACKUP, /CREATED, /EXPIRED, and /MODIFIED qualifiers are mutually exclusive. The default is /EXPIRED if none of the above are entered. If you specify one of these qualifiers without the /BEFORE, /ELAPSED, or /SINCE qualifiers, the /BEFORE, /ELAPSED, and
/SINCE values are unaffected.

/OUTPUT[=file_spec]

/NOOUTPUT (Default)

Records all shelving activities caused by the execution of the volume policy definition.

The /OUTPUT qualifier controls where the output record of the volume policy execution is sent. By default, no output file is created. No Wildcard characters are allowed.
If you enter the /OUTPUT qualifier with a partial file specification (for example, /OUTPUT=[JONES]), the policy_ name parameter is used as the file name with a default file extension of .LOG. The output is suppressed if you enter the /NOOUTPUT qualifier.

/PRESHELVE

/NOPRESHELVE

If /PRESHELVE is specified, the LRU and STWS algorithms preshelve files instead of shelving them. The /PRESHELVE qualifier is applicable only to periodically scheduled policies and should not be applied to volume occupancy full, high water mark exceeded or exceeded disk quota policies, as preshelving does not make disk space available.

/PRIMARY_POLICY=keyword

/NOPRIMARY_POLICY

The /PRIMARY_POLICY qualifier sets the primary policy for selecting dormant files to be shelved. The primary policy is executed until the low water mark is reached or until no further candidates are found. If the low water mark is not reached, then the secondary policy is executed to select additional candidates. Typically, the secondary policy is set to a different algorithm than the primary. This algorithm is then executed until the low water mark is reached.

Setting the /NOPRIMARY_POLICY qualifier effectively disables policy execution. For example, this can be used to disable any action on volume occupancy full or disk quota exceeded events.

The possible policy keywords are as follows:

STWS Space-Time Working Set-Selects files based on the time since the
last reference and the size of the file. Large files are selected with a
higher priority than small files.

LRU Least Recently Used-Selects files with the greatest time since
the last reference.

SCRIPT=filename A filename containing DCL shelving commands. This file is
then used to select files for shelving, preshelving or unshelving.
Note that scripts are run to completion and are not terminated
when the low water mark has been reached.

When you use a script, HSM ignores the file selection qualifiers /BACKUP,
/CREATED, /MODIFIED, or /EXPIRED, /BEFORE, /ELAPSED, or /SINCE.

SMU does not check for the existence of the script file until the policy execution time is reached.

If the specified date field has no value (for example, no backup or expiration date), the STWS and LRU algorithms do not select the file for shelving.

/SECONDARY_POLICY=keyword

/NOSECONDARY_POLICY

Secondary policy is used whenever the primary policy fails to reach the low water mark for the volume. It should be set to a different policy algorithm than the primary so different file selection criteria are used.

If no secondary policy is specified, the secondary policy from the default periodic policy is used.

The keywords for the /SECONDARY_POLICY qualifier are the same as those used for the /PRIMARY_POLICY qualifier.

/SINCE=time

/NOSINCE

Selects only those files dated after the specified time. Specify the time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY.

Specify one of the following qualifiers with /SINCE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED, /EXPIRED, or /MODIFIED.

Time must be specified using the OpenVMS formats for absolute and delta times.

The /SINCE qualifier is mutually exclusive of the /ELAPSED qualifier.

The /NOSINCE qualifier clears any previously issued SET POLICY/SINCE values.

The /BACKUP, /CREATED, /EXPIRED, and /MODIFIED qualifiers are mutually exclusive. The default is /EXPIRED if none of the above are entered. If you specify one of these qualifiers without the /BEFORE, /ELAPSED, or /SINCE qualifiers, /BEFORE, /ELAPSED, and /SINCE values are unaffected.

Example

The following example changes the default occupancy policy to shelve files that have not been accessed for read or write for 100 days. The shelving algorithms to be used are STWS as the primary policy and a user-defined script as the secondary policy, with a low water mark goal of 70 percent. At completion of the policy, mail confirmation is sent to the SYSTEM account. The example also illustrates that the attributes can be specified in multiple commands, as well as in a single command.

$ SMU SET POLICY HSM$DEFAULT_OCCUPANCY - _
$ /ELAPSED=100-0 -
$ /MAIL=SYSTEM -
$ /LOWWATER_MARK=70 -
$ /EXPIRED

$ SMU SET POLICY HSM$OCCUPANCY_POLICY -
$ /PRIMARY_POLICY=STWS -
$ /SECONDARY_POLICY=SCRIPT=DISK$USER1:[SMITH]SECPOL.COM -

$ SMU SHOW POLICY HSM$DEFAULT_OCCUPANCY
Policy HSM$DEFAULT_OCCUPANCY is enabled for shelving
Policy History:
Created: 07-Jan-2005 10:36:36.45
Revised: 07-Jan-2005 11:26:21.09
Selection Criteria:
State: Enabled
Action: Shelving
File Event: Expiration date
Elapsed time: 100 00:00:00
Before time: <none>
Since time: <none>
Low Water Mark: 70 %
Primary Policy: Space Time Working Set(STWS)
Secondary Policy: SCRIPT
DISK$SLOPER1:[SMITH]SECPOL.COM;
Verification:
Mail notification:
SYSTEM
Output file: <none>

SET

SCHEDULE

The SMU SET SCHEDULE command is used to schedule preventative policy execution for a volume. The policy can be scheduled to execute immediately or at periodic intervals.

Format

SMU SET SCHEDULE volume_name[,...], policy_name

Parameters

volume_name[,...]

The name of one or more online volumes on which the shelving policy is to be executed.

If two or more volumes are specified, separate them with commas.

policy_name

The name of an existing policy definition.

Qualifiers

/ALL

Used in conjunction with wildcard volume names to select all matching volumes found on the system. If /ALL is not specified, Wildcard matching applies only to volumes defined with SET VOLUME in the SMU database.

/AFTER[=time]

Requests that the shelving policy execution be held until after a specific time. If no time value is specified, execution begins immediately.

Specify the time as either an absolute time or as a combination of absolute and delta times. For more information on specifying time values, see the OpenVMS DCL Concepts Manual.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a request is issued before each schedule operation to confirm that the operation should be performed. The following responses are valid:

YES NO QUIT
TRUE FALSE Ctrl/Z
1 0 ALL

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/DELETE

Deletes the entry from the scheduling database.

/INTERVAL=delta_time

Requests that the shelving policy be executed at regular intervals. This qualifier specifies the minimum time between shelving policy executions for the online volume. Delta time is expressed as dddd-hh:mm:ss.cc. If no interval value is specified, the default interval is one day.

If the /AFTER qualifier is specified with the /INTERVAL qualifier, the first shelving policy execution begins at or after the /AFTER time. All subsequent policy executions occur at the specified time.

Specify the time as either an absolute time or as a combination of absolute and delta times. For more information on specifying time values, see the OpenVMS DCL Concepts Manual.

The policy can be executed only if the policy definition has been enabled.

/ENTRY=number

When a policy is scheduled for execution, an entry number is associated with it. Use the entry number when modifying an existing policy schedule event. Use SHOW SCHEDULE to determine the entry number.

/LOG

/NOLOG (Default)

Displays the policy specification of each policy modified as the command executes.

/OUTPUT[=filespec]

/NOOUTPUT (Default)

The /OUTPUT qualifier controls where the output record of the set schedule activity is sent. By default, no output file is created. No Wildcard characters are allowed.

/REQUEUE=server_name

In conjunction with the /ENTRY qualifier, the /REQUEUE qualifier requeues the policy for execution on a different shelf server node.

/SERVER=node_name

Specify the node name of the HSM shelf server on which to execute the policy. This does not have to be the current shelf server, but any eligible shelf server. If you do not specify a server node name, the default server becomes the first entry listed under Designated Servers in the SHOW FACILITY command display.

Example

The following example shows the SMU SET SCHEDULE command. In this example, a preventative policy DAILY_OCCUPANCY is run on a daily basis on volumes $1$DKA100: and $1$DKA200:, starting at 2:00 am, on shelf server node SYS001.

$ SMU SET SCHEDULE $1$DKA100:, $1$DKA200: DAILY_OCCUPANCY -
$ /INTERVAL=1-0/AFTER=02:00:00/SERVER=SYS001

$ SMU SHOW SCHEDULE/FULL

Volume Policy Entry Status
_$1$DKA100: DAILY_OCCUPANCY 517 PENDING
Server node: SYS001
Scheduled after: 07-Jan-2005 02:00:00.00
Scheduled interval: 1 00:00:00.00
Output file <none>

Volume Policy Entry Status
_$1$DKA200: DAILY_OCCUPANCY 517 PENDING
Server node: SYS001
Scheduled after: 07-Jan-2005 02:00:00.00
Scheduled interval: 1 00:00:00.00
Output file <none>

SET

SHELF

The SMU SET SHELF command creates a new shelf configuration or modifies an existing shelf configuration. A shelf describes the set of attributes associated with a set of online volumes, including the number of shelf data copies and the archive classes to be used. HSM operations also can be enabled and disabled on a per-shelf basis, affecting all volumes associated with the shelf.

HSM provides predefined default shelf definitions that are used when no shelf definitions are associated with a volume.

If the shelf definition already exists, it is modified with the new definition. When a new shelf is created, all default attributes are set from the default shelf definition. The default shelf definition can be modified by using the /DEFAULT qualifier.

Online disk volumes are associated with the shelf using the SMU SET VOLUME command.

Format

SMU SET SHELF shelf_name[,...]

Parameters

shelf_name

One or more shelf names. A shelf name can be a user-defined name, or the default shelf name HSM$DEFAULT_SHELF.

Qualifiers

/ARCHIVE_ID=(archive_id[,...])

/NOARCHIVE_ID

Identifies archive class identifiers to be used by this shelf. Archive classes must be defined using SMU SET ARCHIVE before they can be identified for use with the shelf. HSM transfers the file's data to each archive class in the list. This can be used to create multiple copies of the shelved file's data content.

This archive list specifies the archive classes to be written during shelving operations. The restore archive list specifies the archive classes to be read during unshelving operations. When a shelf is first created, the restore archive list is initialized to the archive list specified by this qualifier. Thereafter, the two lists are maintained separately.

Up to ten archive classes may be specified in this list.

/NOARCHIVE_ID removes all existing archive class references.

/CANCEL

Cancels a split-merge operation for the specified catalog.

/CATALOG=file_spec

Specifies the file specification of the catalog file to be used for this shelf. A full specification can be supplied, otherwise default elements are taken from the logical name HSM$CATALOG. A logical name may also be supplied.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a request is issued before each SET SHELF operation to confirm that the operation should be performed on that shelf. The following responses are valid:

YES NO QUIT
TRUE FALSE Ctrl/Z
1 0 ALL

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/DEFAULT

Sets or modifies the system shelf defaults. When a new shelf definition is created, all default attributes are set from this default shelf definition.

The /DEFAULT qualifier cannot be used with a parameter value.

/DELETE

Deletes the entry from the shelf database.

/DISABLE=keyword

Disables shelving operations on all volumes associated with the shelf. The shelf can be configured to perform individual or all shelving operations. The possible keywords are as follows:

ALL Disables the shelf for shelve, preshelve, and unshelve
opera tions.

SHELVE Disables the shelf for shelve and preshelve operations.

UNSHELVE Disables the shelf for unshelve operations.

/ENABLE[=keyword]

Enables operations on volumes associated with the shelf. The shelf can be configured to perform only individual or all shelving operations. By default, the shelf is enabled for all shelve, preshelve, and unshelve operations. The possible keywords are as follows:

ALL (Default) Enables the shelf for shelve, preshelve, and unshelve operations
(Default).

SHELVE Enables the shelf for shelve and preshelve operations.

UNSHELVE Enables the shelf for unshelve operations.

/LOG

/NOLOG (Default)

Displays the shelf specification of each shelf modified as the command executes.

/RESTORE_ARCHIVE=(archive_id[,...])

/NORESTORE_ARCHIVE

Identifies which archive classes are used by HSM on a restore operation. Archive classes must be defined using SMU SET ARCHIVE before they can be identified for use with the shelf. The order of this list is significant. On an UNSHELVE operation the first archive class in restore list is used to attempt to unshelve the file. If the restore attempt in unsuccessful, the next archive class in the restore list is attempted, and so on. Up to 36 archive classes may be specified in this list. This list should normally include the current archive list, plus any archive classes that have ever been defined for this shelf.

If you don't specify a restore archive ID when the shelf is created, the save archive class specified by the /ARCHIVE_ ID command is used as the restore archive. Thereafter, the two lists must be maintained separately.

/NORESTORE_ARCHIVE

removes all restore archive class references.

/SAVE_TIME[=delta_time]
NOSAVE_TIME

Specifies that the shelf file data and catalog entries are saved in the HSM subsystem for the specified delta_ time after the online file is deleted. If no delta_time is specified, a default value of 30 days is applied. With /NOSAVE_TIME, no delay is applied.

While repacking obsolete files are determined based on the value of SAVE_TIME.

When a delete is attempted on a cache file if cache is set as /NOHOLD, the catalog entry is always deleted irrespective of SAVE_TIME. Similarly, if the cache is set as /HOLD, the catalog entry is not deleted irrespective of SAVE_TIME.

During a preshelve operation, if /HOLD is set on the Cache and /SAVE_TIME is used

If /HOLD is set:
and /SAVETIME is used: The entry is not deleted
and /NOSAVE is used: The entry is not deleted.

If /NOHOLD is set:
and /SAVETIME is used: The entry is deleted
and /NOSAVE is used: The entry is deleted.

/VERIFY

/NOVERIFY (Default)

Specifies whether shelving and unshelving operations to tape volumes are performed using BACKUP/VERIFY. The /VERIFY option slows down shelving operations, but provides increased reliability for shelving.

/UPDATES=n

Specifies the number of updates of a shelved file that should be saved on shelf media and in the catalog. For example, for /UPDATES=2, a file that has been:
shelved /unshelved/modified/shelved 10 times will retain the latest two updates on shelf media and in the catalog.
Use /UPDATES=0 to specify that all updates should be retained. Note that this has nothing to do with the OpenVMS version of the file, but rather files that are updated in place.

Example

The following example creates the shelf named CRITICAL_SHELF for use with archive classes 1 and 2, and associates a separate catalog with the shelf.

$ SMU SET SHELF CRITICAL_SHELF -
_$ /ARCHIVE_ID=(1,2) -
_$ /CATALOG=DISK$USER1:[HSM.CATALOG]HSM$CAT1.SYS
$ SMU SHOW SHELF CRITICAL_SHELF

Shelf CRITICAL_SHELF is enabled for Shelving and Unshelving
Catalog File: DISK$USER1:[HSM.CATALOG]HSM$CAT1.SYS
Shelf history:
Created: 07-Jan-2005 12:32:24.70
Revised: 07-Jan-2005 12:32:24.70

Backup Verification: Off
Save Time <none>
Updates Saved: All
Archive Classes:
Archive list: HSM$ARCHIVE01 id: 1
HSM$ARCHIVE02 id: 2
Restore list: HSM$ARCHIVE01 id: 1
HSM$ARCHIVE02 id: 2

SET

VOLUME

The SMU SET VOLUME command defines shelving attributes for a specific online disk volume. This command controls HSM operations on the volume, associates the volume with a shelf, defines operations on certain types of files, and defines the reactive policies for the volume.

If an online disk volume does not have a specific entry in the SMU database, the attributes defined in the default volume HSM$DEFAULT_VOLUME are applied to it.

Specific HSM operations can be enabled or disabled on a per-volume basis using this command. For an operation to be performed on the volume, it must be enabled on the volume, the associated shelf, and the facility.

Each volume must be associated with exactly one shelf. By default, volumes are associated with the default shelf HSM$DEFAULT_SHELF.

The SET VOLUME command also defines the reactive shelving policy for the online volume. This policy is executed by HSM when the device's high water mark has been reached, the volume maximum occupancy has been reached (device full), or a process disk quota exceeded error. Files are then selected by using the criteria defined by this policy.

When a new volume definition is created, all attributes not entered in the command line are set from the default volume definition HSM$DEFAULT_VOLUME. The default volume definition itself may be modified using the SMU SET VOLUME /DEFAULT command.

If the volume definition already exists, it is modified with the new attributes entered on the command line.

Format

SMU SET VOLUME volume_name[,...]

Parameters

volume_name[,...]

Sets the attributes for the specified online volume or volumes. Either the logical name for the disk device or the physical device name can be used. If two or more volumes are specified, separate them with commas.

Wildcard characters are allowed for updates to volumes that exist in the database, unless used with the /ALL qualifier. Wildcard applies only to the physical device

Qualifiers

/CANCEL

Cancels a split-merge operation for the specified shelf.

/ALL

Used in conjunction with wildcard volume names to match with all online disks on the system.
If /ALL is not specified, the wildcard only matches with the volumes already defined in the SMU database.

/CONFIRM

/NOCONFIRM (Default)

Controls whether a request is issued before each SET VOLUME operation to confirm that the operation should be performed on that volume. The following responses are valid:

YES NO QUIT
TRUE FALSE Ctrl/Z
1 0 ALL

Refer the OpenVMS DCL Concepts Manual for more information on the /CONFIRM qualifier.

/CONTIGUOUS

/NOCONTIGUOUS (Default)

Controls the eligibility of files marked contiguous on the volume to be shelved. The default is /NOCONTIGUOUS, meaning that contiguous files are never shelved. If /CONTIGUOUS is specified and contiguous files are shelved, then they are always restored contiguously. If a file cannot be restored contiguously, an error occurs. This qualifier does not affect preshelving.

/DEFAULT

Sets or modifies the system volume defaults. When a new volume definition is created, all default attributes are set from this default volume definition.
This qualifier cannot be used with a volume_name parameter value.

/DELETE

Deletes the entry from the volume database. HSM attributes for the specified online disk volume reverts to those defined in the default volume record HSM$DEFAULT_VOLUME. The volume must be first set to use the shelf specified by the default volume before a delete is allowed.

/DISABLE [=keyword]

The volume is disabled from specified HSM operations until it is reactivated by the /ENABLE qualifier. The volume can be configured to disable individual or all shelving operations.

By default, the volume is enabled for preshelving, shelving and unshelving operations, and disabled for high water mark detection, occupancy full and exceeded quota events.

The possible keywords are as follows:

ALL Disables the volume for all HSM operations.
HIGHWATER_MARK Disables the volume for handling high water mark
conditions.
OCCUPANCY Disables the volume for handling volume occupancy full
conditions.
QUOTA Disables the volume for handling disk quota exceeded
conditions.
UNSHELVE Disables the volume for UNSHELVE operations.

/ENABLE[=keyword]

Enables HSM operations on the volume. The volume can be configured to perform individual or all shelving operations. By default, the volume is enabled for preshelving, shelving and unshelving operations, and disabled for high water mark detection, occupancy full and exceeded quota events.

The possible keywords are as follows:

HIGHWATER_MARK Enables the volume for handling high water mark conditions.
OCCUPANCY Enables the volume for handling volume occupancy full
conditions.
QUOTA Enables the volume for handling disk quota exceeded
conditions.
SHELVE Enable the volume for SHELVE and PRESHELVE
operations.
UNSHELVE Enables the volume for UNSHELVE operations.
ALL Enables the volume for all HSM operations.

/HIGHWATER_MARK=percent

The /HIGHWATER_MARK qualifier establishes a threshold where reactive occupancy policy execution is triggered. It is set to a usage percentage of the volume capacity. Possible percentages range from 0 to 100 percent. HSM periodically checks the device capacity and compares it to the high water mark. If it has been exceeded, and high water mark operations are enabled, a volume occupancy full event is triggered, and the volume's occupancy policy is executed.
If no high water mark processing is desired, specify the high water mark as 100 percent, or disable high water mark operations.

/LOG

/NOLOG (Default)

Displays the volume specification of each volume modified as the command executes.

/OCCUPANCY[=policy_name]

/NOOCCUPANCY

This policy is executed whenever the online device has insufficient allocatable space or the volume high water mark has been exceeded. HSM then executes this occupancy policy.
Policy execution is terminated when enough space has been freed to satisfy the request, or no candidates were found.

• If no occupancy full policy name is specified, HSM applies a predefined default occupancy policy definition (HSM$DEFAULT_OCCUPANCY).
• If /NOOCCUPANCY is specified, then no policy is run on volume occupancy full and high water mark conditions.

/PLACEMENT (Default)

/NOPLACEMENT

Defines the eligibility of files marked with placement attributes to be shelved.
The default is /PLACEMENT, meaning that placed files can be shelved. Files that have been shelved are not guaranteed to be restored with identical placement as before. This qualifier does not affect preshelving.

/QUOTA[=policy_name]

/NOQUOTA

This policy is executed whenever a disk quota exceeded event is encountered. When a disk quota exceeded event is encountered, HSM then executes the volume's quota policy.

If no quota policy name is specified, HSM applies a predefined default quota policy definition (HSM$DEFAULT_QUOTA).

If /NOQUOTA is specified, then no policy is run on disk quota exceeded conditions.

/SHELF_NAME=shelf_name

The shelf to associate the volume with. If no shelf qualifier is entered, the default shelf HSM$DEFAULT_SHELF is used. The shelf must exist prior to associating a volume with it.

Example

The following example shows the SMU SET VOLUME command. In this example, volumes $1$DKA100: and $1$DKA200: are assigned to the default shelf. All operations are enabled for the volume, and user-defined reactive policies are set up. The high water mark is set to 95 percent.

$ SMU SET VOLUME $1$DKA100:,$1$DKA200: - $ /ENABLE=ALL /HIGHWATER_MARK=95 -
$ /OCCUPANCY_POLICY = CRITICAL_OCC_POL - $ /QUOTA_POLICY = CRITICAL_QUOT_POL

$ SMU SHOW VOLUME $1$DKA100:, $1$DKA200 /FULL

Volume _$1$DKA100: on Shelf HSM$DEFAULT_SHELF, Shelving is enabled,
Unshelving is enabled, Highwater mark detection is enabled, Occupancy full detection is enabled, Disk quota exceeded detection is enabled
Created: 07-Jan-2005 12:37:07.50
Revised: 07-Jan-2005 12:37:07.50
Ineligible files: <CONTIGUOUS>
High Water Mark: 95%
OCCUPANCY Policy: CRITICAL_OCC_POL
QUOTA Policy: CRITICAL_QUOT_POL

Volume _$1$DKA200: on Shelf HSM$DEFAULT_SHELF, Shelving is enabled,
Unshelving is enabled, Highwater mark detection is enabled, Occupancy full
detection is enabled, Disk quota exceeded detection is enabled
Created: 07-Jan-2005 12:37:07.64
Revised: 07-Jan-2005 12:37:07.64
Ineligible files: <CONTIGUOUS>
High Water Mark: 95%
OCCUPANCY Policy: CRITICAL_OCC_POL
QUOTA Policy: CRITICAL_QUOT_POL

SHOW

ARCHIVE

The SMU SHOW ARCHIVE command displays information associated with archive classes. The displayed information includes:

• The archive class name
• An indication whether the archive class has been used - it is flagged as used after the first shelving operation on the archive class
• The archive class identifier from 1 to 36 for HSM Basic mode or 1 to 9999 for HSM Plus mode - used in archive commands
• For HSM Basic mode, the media type used to write the archive class, and an indication whether a magazine loader is used
• For HSM Plus mode, the media type used to write the archive class, as defined in TAPESTART.COM
• For HSM Plus mode, the density for the media type, as defined in TAPESTART.COM
• The tape volume label of the current shelving volume
• The tape position of the next file to be shelved on the current shelving volume
• For HSM Plus mode, the pools associated with the archive class and the current pool being used
• The number of devices associated with this archive class (device refs)
• The number of shelves associated with this archive class (shelf refs)

Format

SMU SHOW ARCHIVE archive_id[,...]

Parameters

archive_id[,...]

Specifies the archive classes to be displayed. If two or more archive identifiers are specified, separate them with commas. If no archive identifiers are specified, HSM lists all defined archive classes.

Qualifiers

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

Examples

The following example shows the SMU SHOW ARCHIVE command for Basic mode on a system where only two archive classes are defined:

$ SMU SHOW ARCHIVE
HSM$ARCHIVE01 has been used
Identifier: 1
Media type: CompacTape III, Loader
Label: HS0004
Position: 1350
Device refs: 1
Shelf refs: 1

HSM$ARCHIVE02 has not been used
Identifier: 2
Media type: CompacTape III,
Loader Label: HS1001
Position: 0
Shelf refs: 0
SAVESET_SIZE: 40 MB

The following example shows the SMU SHOW ARCHIVE command for a specific archive class for Plus mode:

$ SMU SHOW ARCHIVE 1

HSM$ARCHIVE01 has been used
Identifier: 1
Media type: TK85K
Density: COMP
Label: ACW401
Position: 21
Device refs: 2
Shelf refs: 3
Current pool: HSM-POOL
Enabled pools: HSM-POOL

SHOW

CACHE

The SMU SHOW CACHE command displays the configuration associated with an online cache disk volume or magneto- optical device. The displayed information includes:

• The cache volume name and an indication whether it is currently enabled
• The time set in the SMU SET CACHE command for cache flush to occur; this is not necessarily the next cache flush time
• An indication whether copies to the shelf archive classes are made at shelving time or at cache flush time
• The maximum block size available for caching (a 0 means the entire volume may be used)
• The high water mark percentage of the block size, which if exceeded causes a cache flush
• The cache flush interval

Format

SMU SHOW CACHE volume_name[,...]

Parameters

volume_name[,...]

Specifies the online system mounted volumes that are specified as shelf cache devices.
If no volumes are entered, all cache volumes are displayed.

If two or more volumes are specified, separate them with commas. Wildcard characters are allowed.

Qualifiers

/OUTPUT[=file_spec]

/NOOUTPUT (Default)

Controls where to write the output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

If you enter the /OUTPUT qualifier with a partial file specification (for example, /OUTPUT=[JONES]), HSM$CACHE is the default file name and .LIS is the default file extension. The output is suppressed if you enter the /NOOUTPUT qualifier.

Example

The following example shows the SMU SHOW CACHE command display.

$ SMU SHOW CACHE _$15$DKA100:

Cache device _$15$DKA100: is enabled, Cache flush is held until
after 07-Jan-2005 04:00:00.00, Backup is performed at flush
intervals, Cached files are held on delete of online file
Block size: 100000
Highwater mark: 80%
Flush interval: 1 00:00:00.00

SHOW

DEVICE

The SMU SHOW DEVICE command displays the information associated with the specified nearline or offline device. The displayed information includes:

• The device name
• An indication of whether the device is currently enabled for HSM use
• Shared or dedicated access indication
• The operations that are supported by the device
• An indication of whether the device is correctly configured and usable by HSM
• If the information displayed is Not configured, this means one of the following things:
• The media type defined for the SMU SET DEVICE command does not match any of the media types defined in TAPESTART.COM (Plus mode).
• The device does not match the DRIVES_n specification in TAPESTART.COM for the identified media type (Plus mode).
• MDMS is not running, so HSM cannot verify the information provided (Plus mode).
• The robot name is not specified, or the specified robot name does not exist or is not accessible (Basic mode).
• The default device is being displayed.
• The media type the device supports in Basic mode
• The robot name controlling a loader device in Basic mode, or <none> for a non-loader device
• The archive classes supported by the device

Format

SMU SHOW DEVICE device_name[,...]

Parameters

device_name[,...]

Specifies the nearline/offline devices to be displayed. If two or more devices are specified, separate them with commas. Wildcard characters are allowed. If no device name is specified, information about all devices is displayed.

Qualifiers

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

Examples

The following example shows the SMU SHOW DEVICE display for Basic mode:

$ SMU SHOW DEVICE _$10$MIA5:

HSM drive _$10$MIA5: is enabled.
Shared access: < shelve, unshelve >
Drive status: Configured
Media type: CompacTape III, Loader
Robot name: _$1$DUA406:
Enabled archives: HSM$ARCHIVE01 id: 1
HSM$ARCHIVE02 id: 2

The following example shows the SMU SHOW DEVICE display for Plus mode:

$ SMU SHOW DEVICE _NODE2$MKA500:
HSM drive _NODE2$MKA500: is enabled.
Shared access: <shelve, unshelve>
Drive status: Configured
Enabled archives: HSM$ARCHIVE01 id: 1
HSM$ARCHIVE03 id: 3

SHOW

FACILITY

The SMU SHOW FACILITY command displays information about the HSM facility, whose attributes have VMScluster-wide impact on all shelves, volumes and nodes. The displayed information includes:

• Operations that are enabled across the HSM facility
• The list of designated shelf servers
• The current shelf server node
• An indication of whether cache operations and all catalog updates are performed by the shelf server node
• The state of individual types of event logging
• The HSM operations mode (Plus or Basic)
• The amount of shelving storage capacity remaining; if you have acquired the unlimited license, this shows as "unlimited".

Format

SMU SHOW FACILITY

Qualifiers

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

If you enter the /OUTPUT qualifier with a partial file specification
(for example, /OUTPUT=[JONES]), HSM$FACILITY is the default file name and .LIS is the default file extension. The output is suppressed if you enter the /NOOUTPUT qualifier.

Example

The following example shows the SMU SHOW FACILITY command display.

$ SMU SHOW FACILITY

HSM for OpenVMS is enabled for Shelving and Unshelving
Facility history:
Created: 07-Jan-2005 10:36:34.96
Revised: 07-Jan-2005 12:27:51.87
Designated servers: SYS001
SYS002
Current server: SYS001
Catalog server: Disabled
Event logging: Audit
Error
Exception
HSM mode: Plus
Remaining license: 500 gigabytes

SHOW

POLICY

The SMU SHOW POLICY command displays a shelving policy definition. The displayed information includes:

• The name of the policy
• An indication of whether the policy is currently enabled
• The action to be taken by the policy: either shelving or preshelving
• The creation and modification dates of the record (/FULL only)
• The date used for selecting files for shelving: either the Backup, Creation, Modification, or Expiration dates (/FULL only)
• The period of relative elapsed time at policy execution that files will not be selected for shelving, applied to the specified date field (/FULL only)
• A before or since absolute time that files will not be selected for shelving, applied to the specified date field (/FULL only)
• The low water mark capacity goal that the policy attempts to reach before completing execution (/FULL only)
• The policy algorithms used for primary and secondary policy, or the locations of script files (/FULL only)
• Account to which mail is delivered on policy completion (/FULL only)
• File to which policy information is logged (/FULL only)

Format

SMU SHOW POLICY [policy_name[,...]]

Parameters

[policy_name[,...]]

Specifies one or more policy names. If two or more policy names are specified, separate them with commas. Wildcard characters are allowed.

If no policy_name is specified, all policy definitions are displayed.

Qualifiers

/BRIEF (Default)

Displays one line of information for each specified policy.

/DEFAULT

Shows the default policy record HSM$DEFAULT_POLICY. When a new policy definition is created, all default attributes are set from this default policy definition.

The /DEFAULT qualifier cannot be used with a parameter value.

/FULL

Displays complete information about each specified policy.

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

If you enter the /OUTPUT qualifier with a partial file specification
(for example, /OUTPUT=[JONES]), HSM$POLICY is the default file name and .LIS is the default file extension. The output is suppressed if you enter the /NOOUTPUT qualifier.

Examples

The following examples show the SMU SHOW POLICY display.

$ SMU SHOW POLICY

Policy HSM$DEFAULT_OCCUPANCY is enabled for shelving
Policy HSM$DEFAULT_POLICY is enabled for shelving
Policy HSM$DEFAULT_QUOTA is enabled for shelving

$ SMU SHOW POLICY/FULL HSM$DEFAULT_QUOTA

Policy HSM$DEFAULT_QUOTA is enabled for shelving
Policy History:
Created: 07-Jan-200510:36:36.47
Revised: 07-Jan-2005 10:36:36.47
Selection Criteria:
State: Enabled
Action: Shelving
File Event: Expiration date
Elapsed time: 180 00:00:00
Before time: <none>
Since time: <none>
Low Water Mark: 80 %
Primary Policy: Space Time Working Set (STWS)
Secondary Policy: Least Recently Used (LRU)
Verification:
Mail notification: <none>
Output file: <none>

SHOW

REQUESTS

The SMU SHOW REQUESTS command displays the number of HSM operations in progress, and optionally dumps information about the requests to an activity log. The log is located at HSM$LOG:HSM$SHP_ACTIVITY.LOG.

The SMU SHOW REQUESTS command will only display the requests on the current node you are using. To show the requests on all nodes in the cluster, use the OpenVMS SYSMAN command as shown in the example below.

Format

SMU SHOW REQUESTS

Qualifiers

/BRIEF (Default)

Writes a line to the display device to indicate the number of requests in progress.

/FULL

Writes a line to the display device to indicate the number of requests in progress. In addition, if there is at least one active request, the requests are dumped to the file HSM$LOG:HSM$SHP_ACTIVITY.LOG.

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

Example

The following example shows the SMU SHOW REQUESTS command:

$ SMU SHOW REQUESTS/FULL
%HSM-S-DMPACTREQS, shelving facility active with 3 requests
%HSM-I-DMPFILE, active requests dumped to file
HSM$LOG:HSM$SHP_ACTIVITY.LOG

The following example shows how to use the OpenVMS SYSMAN command to show the requests on all nodes in the cluster.

$ MCR SYSMAN SYSMAN> SET ENVIRONMENT/CLUSTER
%SYSMAN-I-ENV, current command environment:
Clusterwide on local cluster
Username PETER will be used on nonlocal nodes

SYSMAN> DO SMU SHOW REQUESTS
%SYSMAN-I-OUTPUT, command execution on node HERSHY
%HSM-S-DMPACTREQS, shelving facility active with 1 requests
%SYSMAN-I-OUTPUT, command execution on node MINT
%HSM-S-DMPACTREQS, shelving facility active with 1 requests
%SYSMAN-I-OUTPUT, command execution on node CHOCO
%HSM-S-DMPACTREQS, shelving facility active with 4 requests

SHOW

SCHEDULE

The SMU SHOW SCHEDULE command displays information about existing preventative policy schedules. The displayed information includes:

• The volume name for which the policy is scheduled - each volume is listed separately
• The policy name
• The entry number, which can be used in subsequent modifications to the schedule entry
• The status of the schedule - the status values are the same as those for OpenVMS batch queue entries
• The server node on which the policy is scheduled (/FULL only)
• The scheduled time of the policy execution (/FULL only)
• The scheduling interval (/FULL only)
• The output file containing the policy execution information (/FULL only)

The SMU SHOW SCHEDULE command may be entered with no parameters to show all HSM schedules or to show a particular entry using /ENTRY. For all other cases, at least one volume name must be entered.

Format

SMU SHOW SCHEDULE [volume_name[,...] [policy_name]]

Parameters

volume_name[,...]

The name of the online volume(s) on which the scheduling information is to be displayed. If no volume names and policy names are entered, the schedule for all volumes is displayed, unless the /ENTRY qualifier is specified.

If two or more volumes are specified, separate them with commas. Wildcard characters are not allowed.

[policy_name]

The name of an existing policy definition. If no policy name is entered, the schedules for all policies are displayed.

Qualifiers

/BRIEF (Default)

Displays a one-line summary for each scheduled entry.

/ENTRY=entry_number

Displays a specific scheduled entry only, and should be entered with no parameters on the command line.

/FULL

Displays complete information for each scheduled entry.

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

/SERVER=server_name

Displays only those entries scheduled on a specific server node.

Examples

The following examples show the SMU SHOW SCHEDULE command:

$ SMU SHOW SCHEDULE _$1$DKA100:, _$1$DKA200:

Volume Policy Entry status
------ ------ ----- ------
_$1$DKA100: HSM$DEFAULT_OCCUPANCY 517 PENDING

Volume Policy Entry status
------ ------ ----- ------
_$1$DKA200: HSM$DEFAULT_OCCUPANCY 518 PENDING

$ SMU SHOW SCHEDULE/ENTRY=518/FULL

Volume Policy Entry status
------ ------ ----- ------
_$1$DKA200: HSM$DEFAULT_OCCUPANCY 518 PENDING
Server node: SLIPPER
Scheduled after: 07-Jan-2005 02:00:00.00
Scheduled interval: 1 00:00:00.00
Output file <none>

SHOW

SHELF

The SMU SHOW SHELF command displays information about a shelf object. The displayed information includes:

• The shelf name and enabled operations
• The name of the catalog supporting this shelf
• The creation and modification date of the shelf record
• An indication whether verification operations are to be performed on BACKUP operations
• The amount of time to wait before a REPACK operation removes shelf data after a file is deleted
• The number of in-place updates that can be performed on a file before a REPACK operation removes shelf data for the file
• The archive classes defined for the shelf - both the archive classes used for shelving, and those used for unshelving

Format

SMU SHOW SHELF shelf_name[,...]

Parameters

shelf_name[,...]

The name of the shelf. Wildcard characters are allowed.
If no shelf name is specified, all shelves are displayed.

Qualifiers

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

If you enter the /OUTPUT qualifier with a partial file specification
(for example, /OUTPUT=[JONES]), HSM$SHELF is the default file name and .LIS is the default file extension. The output is suppressed if you enter the /NOOUTPUT qualifier.

Example

The following example shows the SMU SHOW SHELF command display.

$ SMU SHOW SHELF HSM$DEFAULT_SHELF

Shelf HSM$DEFAULT_SHELF is enabled for Shelving and Unshelving
Catalog File:$1$DKA0:[HSM$SERVER.CATALOG]HSM$CATALOG.SYS
Shelf history:
Created: 07-Jan-2005 12:39:30.86
Revised: 07-Jan-2005 13:17:58.87
Backup Verification: Off
Save Time <none>
Updates Saved: All
Archive Classes:
Archive list: HSM$ARCHIVE01 id: 1
HSM$ARCHIVE02 id: 2
Restore list: HSM$ARCHIVE01 id: 1
HSM$ARCHIVE02 id: 2

SHOW

VERSION

The SMU SHOW VERSION command displays the version information about the various HSM components. The displayed information includes:

• The HSM component name
• The version and interval base level of the component
• The date on which the component was built

In a properly configured system, all version attributes should be the same for all components.

Format

SMU SHOW VERSION

Qualifiers

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

If you enter the /OUTPUT qualifier with a partial file specification (for example, /OUTPUT=[JONES]), HSM$VERSION is the default file name and .LIS is the default file extension. The output is suppressed if you enter the /NOOUTPUT qualifier.

Example

The following example shows the SMU SHOW VERSION command display.

$ SMU SHOW VERSION

HSM Shelf Handler version - V4.3(BL46), 04 Oct 2004
HSM Shelving Driver version - V4.3(BL46), 07 Oct 2004
HSM Policy Execution version - V4.3(BL46), 07 Oct 2004
HSM Shelf Management version - V4.3(BL46), 07 Oct 2004

SHOW

VOLUME

The SMU SHOW VOLUME command displays the shelving attributes of an online disk volume. The displayed information includes:

• The volume name
• The shelf with which the volume is associated
• Operations that are enabled on the volume
• Creation and revision date of the volume record (/FULL only)
• Specific files types ineligible for shelving (contiguous and placement)
• The high water mark capacity for the volume (/FULL only)
• The name of the reactive policy to be executed when a volume (/FULL only) occupancy full or high water mark exceeded event occurs (/FULL only)
• The name of the reactive policy to be executed when an exceeded disk quota event occurs
  (/FULL only)

Format

SMU SHOW VOLUME volume_name[,...]

Parameters

volume_name[,...]

Shows the event policy for the online volume or volumes. Specify the logical volume name.
If two or more volumes are specified, separate them with commas. Wildcard characters are allowed.

If no volume_name is specified, all volumes are displayed.

Qualifiers

/BRIEF (Default)

Displays brief information about the specified volume.

/DEFAULT

Shows the system volume defaults. When a new volume definition is created, all default attributes are set from this default volume definition.

The /DEFAULT qualifier cannot be used with a parameter value.

/FULL

Displays a complete list of information about the volume.

/OUTPUT[=filespec]

/NOOUTPUT

Controls where to write output of the command. By default, the display is written to the current SYS$OUTPUT device. No Wildcard characters are allowed.

If you enter the /OUTPUT qualifier with a partial file specification
(for example, /OUTPUT=[JONES]), HSM$VOLUME is the default file name and .LIS is the default file extension. The output is suppressed if you enter the /NOOUTPUT qualifier.

Examples

The following examples show the SMU SHOW VOLUME command display.

$ SMU SHOW VOLUME

Volume HSM$DEFAULT_VOLUME on Shelf HSM$DEFAULT_SHELF, Shelving is enabled, Unshelving is enabled, Highwater mark detection is disabled,Occupancy full
detection is disabled, Disk quota exceeded detection is disabled

Volume _$1$DKA100: on Shelf HSM$DEFAULT_SHELF, Shelving is enabled,
Unshelving is enabled, Highwater mark detection is enabled, Occupancy full detection is enabled, Disk quota exceeded detection is enabled

Volume _$1$DKA200: on Shelf HSM$DEFAULT_SHELF, Shelving is enabled,
Unshelving is enabled, Highwater mark detection is enabled, Occupancy full detection is enabled, Disk quota exceeded detection is enabled

$ SMU SHOW VOLUME /DEFAULT /FULL

Volume HSM$DEFAULT_VOLUME on Shelf HSM$DEFAULT_SHELF, Shelving is enabled, Unshelving is enabled, Highwater mark detection is disabled, Occupancy full
detection is disabled, Disk quota exceeded detection is disabled
Created: 07-Jan-2005 12:39:33.07
Revised: 07-Jan-2005 12:39:33.07
Ineligible files: <CONTIGUOUS>
High Water Mark: 90%
OCCUPANCY Policy: HSM$DEFAULT_OCCUPANCY
QUOTA Policy: HSM$DEFAULT_QUOTA

SHUTDOWN

The SMU SHUTDOWN command disables and shuts down HSM in an orderly fashion. SMU SHUTDOWN and SMU SHUTDOWN/NOW take effect on all nodes in the VMScluster, whereas SMU SHUTDOWN /FORCE affects only the issuing node.

This command is typically executed during SYSTEM shutdown (SMU SHUTDOWN/FORCE). It should be placed in the appropriate command files for the system. The other two variants are used to shut down the HSM subsystem across the VMScluster, for perhaps an HSM upgrade or some other reason.

SMU SHUTDOWN waits for all pending requests to complete, whereas SMU SHUTDOWN/NOW and SMU SHUTDOWN/FORCE shut down immediately; any pending requests are recovered when HSM is restarted.

In any variant of SMU SHUTDOWN, there may be a delay of up to five minutes if a BACKUP or tape positioning operation is in progress.

The SMU SHUTDOWN command requires SYSPRV, TMPMBX, and WORLD privileges.

Format

SMU SHUTDOWN

Qualifiers

/FORCE

/FORCE

Shut down HSM immediately on the requesting node only. HSM will continue to run on other nodes in the VMScluster. Pending requests are not processed but will be recovered when HSM starts up later.

/NOW

/NOW

Shut down HSM immediately across the VMScluster. Pending requests are not processed but will be recovered when HSM starts up later.

Example

The following example shows the SMU SHUTDOWN command as should be applied in the system shutdown command procedure, to shut HSM down on one node:

$ SMU SHUTDOWN/FORCE

SPAWN

The SMU SPAWN command creates a subprocess to execute DCL commands without leaving the SMU session.

SPAWN returns you to the DCL level in a subprocess. You can then enter DCL commands. To terminate the subprocess and resume the SMU session, log out of the subprocess.

Alternatively, you can enter a single DCL command line as a parameter to the spawn command.

Format

SMU SPAWN

Examples

The following examples show the SMU SPAWN command:

$ SMU
SMU> SPAWN SET PROCESS/NOAUTO_UNSHELVE
SMU>

alternatively, you could use the following commands:

S SMU
SMU> SPAWN
$ SET PROCESS/NOAUTO_UNSHELVE
$ LOGOUT
SMU>

STARTUP

The SMU STARTUP command starts up HSM.

This command is typically executed during SYSTEM startup. It should be placed in the appropriate command files for the system.

The SMU STARTUP command requires the following privileges:

BYPASS CMKRNL DETACH
DIAGNOSE EXQUOTA LOG_IO
NETMBX OPER PHY_IO
PRMMBX SHARE SYSLCK
SYSNAM SYSPRV TMPMBX
VOLPRO WORLD

Format

SMU STARTUP

Examples

The following example shows the SMU STARTUP command:

$ SMU STARTUP
%SMU-S-SHP_STARTED, shelf handler process started 22E0193B
%SMU-S-PEP_STARTED, policy execution process started 22E011BC