HP OpenVMS Systems Documentation

Displays information concerning the use of AUTHORIZE, including formats and explanations of commands, parameters, and qualifiers.

Format

HELP [keyword[,...]]

Parameter

keyword[,...]

Specifies one or more keywords that refer to the topic, command, qualifier, or parameter on which you want information from the AUTHORIZE HELP command.

Qualifiers

None.

Description

If you do not specify a keyword, HELP displays information about the topics and commands for which help is available. It then prompts you with "Topic?". You can supply a topic or a command name, or press Return. When you specify a command name and qualifiers, you get detailed information about that command. If you respond by pressing Return, you exit from help. You can also exit from help by pressing Ctrl/Z.

If the command you request accepts qualifiers, the display of the help information about the command is followed by the prompt "Subtopic?". Respond to this prompt with a qualifier name, or press Return. If you respond by pressing Return, HELP prompts with "Topic?". If you want to exit from help directly from this level, press Ctrl/Z.

Examples

UAF> HELP ADD
      

The HELP command in this example displays information about the ADD command:

ADD Adds a user record to the SYSUAF and corresponding identifiers to the rights database. Format ADD newusername Additional information available: Parameter Qualifiers /ACCESS /ACCOUNT /ADD_IDENTIFIER /ALGORITHM /ASTLM /BATCH /BIOLM /BYTLM /CLI /CLITABLES /CPUTIME /DEFPRIVILEGES /DEVICE /DIALUP /DIOLM /DIRECTORY /ENQLM /EXPIRATION /FILLM /FLAGS /GENERATE_PASSWORD /INTERACTIVE /JTQUOTA /LGICMD /LOCAL /MAXACCTJOBS /MAXDETACH /MAXJOBS /NETWORK /OWNER /PASSWORD /PBYTLM /PGFLQUOTA /PRCLM /PRIMEDAYS /PRIORITY /PRIVILEGES /PWDEXPIRED /PWDLIFETIME /PWDMINIMUM /REMOTE /SHRFILLM /TQELM /UIC /WSDEFAULT /WSEXTENT /WSQUOTA Examples /IDENTIFIER /PROXY ADD Subtopic?

UAF> HELP MODIFY/WSDEFAULT
      

The command in this example displays information about the /WSDEFAULT qualifier:

MODIFY /WSDEFAULT=value Specifies the default working set size. This represents the initial limit to the number of physical pages the process can use. (The user can alter the default quantity up to WSQUOTA with the DCL command SET WORKING_SET.) The minimum value is 50 pages (on VAX systems) and 150 pagelets (on Alpha systems). By default, a user has 150 pages (on VAX systems) and 150 pagelets (on Alpha systems).

LIST

Writes reports for selected UAF records to a listing file, SYSUAF.LIS, which is placed in the current default directory.

Note LIST/IDENTIFIER, LIST/PROXY, and LIST/RIGHTS are documented as separate commands.

Format

LIST [user-spec]

Parameter

user-spec

Specifies the user name or UIC of the requested UAF record. Without the user-spec parameter, AUTHORIZE lists the user records of all users. The asterisk (*) and percent sign (%) wildcards are permitted in the user name.

Qualifiers

/BRIEF

Specifies that a brief report be written to SYSUAF.LIS. The /BRIEF qualifier is the default qualifier. SYSUAF.LIS is placed in the default directory.

/FULL

Specifies that a full report be written to SYSUAF.LIS, including identifiers held by the user. SYSUAF.LIS is placed in the SYS$SYSTEM directory.

Description

The LIST command creates a listing file of reports for selected UAF records. Print the listing file, SYSUAF.LIS, with the DCL command PRINT.

Specification of a user name results in a single-user report. Specification of the asterisk wildcard character following the LIST command results in reports for all users in ascending sequence by user name. Specification of a UIC results in reports for all users with that UIC. (HP recommends that you assign each user a unique UIC, but if users share a UIC, the report will show all users with that UIC.) You can use the asterisk wildcard character to specify the UIC.

The following table shows how to specify a UIC with the LIST command and use the asterisk wildcard character with the UIC specification to produce various types of reports:

Command	Description
LIST [14,6]	Lists a full report for the user (or users) with member number 6 in group 14.
LIST [14,*] /BRIEF	Lists a brief report for all users in group 14, in ascending sequence by member number.
LIST [*,6] /BRIEF	Lists a brief report for all users with a member number of 6.
LIST [*,*] /BRIEF	Lists a brief report for all users, in ascending sequence by UIC.

Although you must provide separate UICs for each user, the LIST command reports users with the same UIC in the order in which they were added to the SYSUAF. Full reports list the details of the limits, privileges, login flags, and command interpreter. Brief reports do not include the limits, login flags, or command interpreter, nor do they summarize the privileges. AUTHORIZE never displays the password for an account.

See the SHOW command for examples of brief and full reports.

Examples

UAF> LIST ROBIN/FULL
%UAF-I-LSTMSG1, writing listing file
%UAF-I-LSTMSG2, listing file SYSUAF.LIS complete
      

This command lists a full report for the user record ROBIN.

UAF> LIST *
%UAF-I-LSTMSG1, writing listing file
%UAF-I-LSTMSG2, listing file SYSUAF.LIS complete
      

This command results in brief reports for all users in ascending sequence by user name. Note, however, that this is the same result you would produce had you omitted the asterisk wildcard.

UAF> LIST [300,*]
%UAF-I-LSTMSG1, writing listing file
%UAF-I-LSTMSG2, listing file SYSUAF.LIS complete
      

This command lists a brief report for all user records with a group UIC of 300.

LIST/IDENTIFIER

Creates a listing file (RIGHTSLIST.LIS) in which identifier names, attributes, values, and holders are written.

Format

LIST/IDENTIFIER [id-name]

Parameter

id-name

Specifies an identifier name. You can specify the asterisk wildcard character (*) to list all identifiers. If you omit the identifier name, you must specify /USER or /VALUE.

Qualifiers

/BRIEF

Specifies a brief listing in which only the identifier name, value, and attributes appear.

/FULL

Specifies a full listing, in which the names of the identifier's holders are displayed along with the identifier's name, value, and attributes. The /FULL qualifier specifies the default listing format.

/USER=user-spec

Specifies one or more users whose identifiers are to be listed. The user-spec can be a user name or UIC. You can use the asterisk wildcard character (*) to specify multiple user names or UICs. UICs must be in the form [*,*], [n,*], [*,n], or [n,n]. A wildcard user name specification (*) lists identifiers alphabetically by user name; a wildcard UIC specification ([*,*]) lists them numerically by UIC.

/VALUE=value-specifier

Specifies the value of the identifier to be listed. The following formats are valid for the value-specifier:

IDENTIFIER:n	An integer value in the range 65,536 to 268,435,455. You can also specify the value in hexadecimal (precede the value with %X) or octal (precede the value with %O). To differentiate general identifiers from UIC identifiers, %X80000000 is added to the value you specify.
GID:n	GID is the POSIX group identifier. It is an integer value in the range 0 to 16,777,215 (%XFFFFFF). The system will add %XA400.0000 to the value you specify and then enter this new value into the system RIGHTSLIST as an identifier.
UIC:uic	A UIC value in the standard UIC format.

Description

The LIST/IDENTIFIER command creates a listing file in which identifier names, attributes, values, and holders are displayed in various formats depending on the qualifiers specified. Two of these formats are illustrated in the description of the SHOW/IDENTIFIER command.

Print the listing file named RIGHTSLIST.LIS with the DCL command PRINT.

Examples

UAF> LIST/IDENTIFIER INVENTORY
%UAF-I-LSTMSG1, writing listing file
%UAF-I-RLSTMSG, listing file RIGHTSLIST.LIS complete
      

The command in this example generates a full listing for the identifier INVENTORY, including its value (in hexadecimal), holders, and attributes.

UAF> LIST/IDENTIFIER/USER=ANDERSON
%UAF-I-LSTMSG1, writing listing file
%UAF-I-RLSTMSG, listing file RIGHTSLIST.LIS complete
      

This command lists an identifier associated with the user ANDERSON, along with its value and attributes. Note, however, that this is the same result you would produce had you specified ANDERSON's UIC with the following forms of the command:

UAF> LIST/IDENTIFIER/USER=[300,015]

UAF> LIST/IDENTIFIER/VALUE=UIC:[300,015]

LIST/PROXY

Creates a listing file of the network proxy database entries from the network database file NET$PROXY.DAT.

Format

LIST/PROXY

Parameters

None.

Qualifiers

/OLD

Directs AUTHORIZE to display information from the NETPROXY.DAT file rather than from the default file NET$PROXY.DAT.

If someone modifies the proxy database on a cluster node that is not running the current OpenVMS VAX system, then you can use the /OLD qualifier to list the contents of the old database: NETPROXY.DAT.

Description

Use the DCL command PRINT to print the listing file, NETPROXY.LIS. The output assumes the same format as that of the SHOW/PROXY command. For an example of the output format, see the description of the SHOW/PROXY command.

Example

UAF> LIST/PROXY/OLD
%UAF-I-LSTMSG1, writing listing file
%UAF-I-NETLSTMSG, listing file NETPROXY.LIS complete
      

The command in this example creates a listing file of all the entries in the network proxy database NETPROXY.DAT.

LIST/RIGHTS

Lists identifiers held by the specified identifier or, if /USER is specified, all identifiers held by the specified users.

Format

LIST/RIGHTS [id-name]

Parameter

id-name

Specifies the name of the identifier associated with the user. If you omit the identifier name, you must specify the /USER qualifier.

Qualifier

/USER=user-spec

Specifies a user whose identifiers are to be listed. The user-spec can be a user name or UIC. You can use the asterisk wildcard character (*) to specify multiple UICs or all user names. UICs must be in the form [*,*], [n,*], [*,n], or [n,n]. A wildcard user name specification (*) or wildcard UIC specification ([*,*]) lists all identifiers held by users. The wildcard user name specification lists holders' user names alphabetically; the wildcard UIC specification lists them in the numerical order of their UICs.

Description

Use the DCL command PRINT to print the listing file (RIGHTSLIST.LIS) produced by the LIST/RIGHTS command. For an example of the output format, see the description of the SHOW/RIGHTS command.

Example

UAF> LIST/RIGHTS PAYROLL
%UAF-I-LSTMSG1, writing listing file
%UAF-I-RLSTMSG, listing file RIGHTSLIST.LIS complete
      

The command in this example lists identifiers held by PAYROLL, providing PAYROLL is the name of a UIC format identifier.

MODIFY

Changes values in a SYSUAF user record. Qualifiers not specified in the command remain unchanged.

Note MODIFY/IDENTIFIER, MODIFY/PROXY, and MODIFY/SYSTEM_PASSWORD are documented as separate commands.

Format

MODIFY username /qualifier[,...]

Parameter

username

Specifies the name of a user in the SYSUAF. The asterisk (*) and percent sign (%) wildcard characters are permitted in the user name. When you specify a single asterisk for the user name, you modify the records of all users.

Qualifiers

/ACCESS[=(range[,...])]

/NOACCESS[=(range[,...])]

Specifies hours of access for all modes of access. The syntax for specifying the range is:

/[NO]ACCESS=([PRIMARY], [n-m], [n], [,...],[SECONDARY], [n-m], [n], [,...])

Specify hours as integers from 0 to 23, inclusive. You can specify single hours (n) or ranges of hours (n-m). If the ending hour of a range is earlier than the starting hour, the range extends from the starting hour through midnight to the ending hour. The first set of hours after the keyword PRIMARY specifies hours on primary days; the second set of hours after the keyword SECONDARY specifies hours on secondary days. Note that hours are inclusive; that is, if you grant access during a given hour, access extends to the end of that hour.

By default, a user has full access every day. See the DCL command SET DAY in the HP OpenVMS DCL Dictionary for information about overriding the defaults for primary and secondary day types.

All the list elements are optional. Unless you specify hours for a day type, access is permitted for the entire day. By specifying an access time, you prevent access at all other times. Adding NO to the qualifier denies the user access to the system for the specified period of time. See the following examples.

/ACCESS	Allows unrestricted access
/NOACCESS=SECONDARY	Allows access on primary days only
/ACCESS=(9-17)	Allows access from 9 A.M. to 5:59 P.M. on all days
/NOACCESS=(PRIMARY, 9-17, SECONDARY, 18-8)	Disallows access between 9 A.M. to 5:59 P.M. on primary days but allows access during these hours on secondary days

To specify access hours for specific types of access, see the /BATCH, /DIALUP, /INTERACTIVE, /LOCAL, /NETWORK, and /REMOTE qualifiers.

Refer to HP OpenVMS Guide to System Security for information about the effects of login class restrictions.

/ACCOUNT=account-name

Specifies the default name for the account (for example, a billing name or number). The name can be a string of 1 to 8 alphanumeric characters. By default, AUTHORIZE does not assign an account name.

/ALGORITHM=keyword=type [=value]

Sets the password encryption algorithm for a user. The keyword VMS refers to the algorithm used in the operating system version that is running on your system, whereas a customer algorithm is one that is added through the $HASH_PASSWORD system service by a customer site, by a layered product, or by a third party. The customer algorithm is identified in $HASH_PASSWORD by an integer in the range of 128 to 255. It must correspond with the number used in the AUTHORIZE command MODIFY/ALGORITHM. By default, passwords are encrypted with the VMS algorithm for the current version of the operating system.

Keyword	Function
BOTH	Set the algorithm for primary and secondary passwords.
CURRENT	Set the algorithm for the primary, secondary, both, or no passwords, depending on account status. CURRENT is the default value.
PRIMARY	Set the algorithm for the primary password only.
SECONDARY	Set the algorithm for the secondary password only.

The following table lists password encryption algorithms:

Type	Definition
VMS	The algorithm used in the version of the operating system that is running on your system.
CUSTOMER	A numeric value in the range of 128 to 255 that identifies a customer algorithm.

The following example selects the VMS algorithm for Sontag's primary password:

UAF> MODIFY SONTAG/ALGORITHM=PRIMARY=VMS

If you select a site-specific algorithm, you must give a value to identify the algorithm, as follows:

UAF> MODIFY SONTAG/ALGORITHM=CURRENT=CUSTOMER=128

/ASTLM=value

Specifies the AST queue limit, which is the total number of asynchronous system trap (AST) operations and scheduled wake-up requests that the user can have queued at one time. The default is 40 on VAX systems and 250 on Alpha systems.

/BATCH[=(range[,...])]

Specifies the hours of access permitted for batch jobs. For a description of the range specification, see the /ACCESS qualifier. By default, a user can submit batch jobs any time.

/BIOLM=value

Specifies a buffered I/O count limit for the BIOLM field of the UAF record. The buffered I/O count limit is the maximum number of buffered I/O operations, such as terminal I/O, that can be outstanding at one time. The default is 40 on VAX systems and 150 on Alpha systems.

/BYTLM=value

Specifies the buffered I/O byte limit for the BYTLM field of the UAF record. The buffered I/O byte limit is the maximum number of bytes of nonpaged system dynamic memory that a user's job can consume at one time. Nonpaged dynamic memory is used for operations such as I/O buffering, mailboxes, and file-access windows. The default is 32768 on VAX systems and 64000 on Alpha systems.

/CLI=cli-name

Specifies the name of the default command language interpreter (CLI) for the CLI field of the UAF record. The cli-name is a string of 1 to 31 alphanumeric characters and should be DCL, which is the default. This setting is ignored for network jobs.

/CLITABLES=filespec

Specifies user-defined CLI tables for the account. The filespec can contain 1 to 31 characters. The default is SYS$LIBRARY:DCLTABLES. Note that this setting is ignored for network jobs to guarantee that the system-supplied command procedures used to implement network objects function properly.

/CPUTIME=time

Specifies the maximum process CPU time for the CPU field of the UAF record. The maximum process CPU time is the maximum amount of CPU time a user's process can take per session. You must specify a delta time value. For a discussion of delta time values, refer to the OpenVMS User's Manual. The default is 0, which means an infinite amount of time.

/DEFPRIVILEGES=([NO]privname[,...])

Specifies default privileges for the user; that is, those enabled at login time. A NO prefix removes a privilege from the user. By specifying the keyword [NO]ALL with the /DEFPRIVILEGES qualifier, you can disable or enable all user privileges. The default privileges are TMPMBX and NETMBX. Privname is the name of the privilege.

/DEVICE=device-name

Specifies the name of the user's default device at login. The device-name is a string of 1 to 31 alphanumeric characters. If you omit the colon from the device-name value, AUTHORIZE appends a colon. The default device is SYS$SYSDISK.

If you specify a logical name as the device-name (for example, DISK1: for DUA1:), you must make an entry for the logical name in the LNM$SYSTEM_TABLE in executive mode by using the DCL command DEFINE/SYSTEM/EXEC.

/DIALUP[=(range[,...])]

Specifies hours of access permitted for dialup logins. For a description of the range specification, see the /ACCESS qualifier. The default is full access.

/DIOLM=value

Specifies the direct I/O count limit for the DIOLM field of the UAF record. The direct I/O count limit is the maximum number of direct I/O operations (usually disk) that can be outstanding at one time. The default is 40 on VAX systems and 150 on Alpha systems.

/DIRECTORY=directory-name

Specifies the default directory name for the DIRECTORY field of the UAF record. The directory-name can be 1 to 39 alphanumeric characters. If you do not enclose the directory name in brackets, AUTHORIZE adds the brackets for you. The default directory name is [USER].

/ENQLM=value

Specifies the lock queue limit for the ENQLM field of the UAF record. The lock queue limit is the maximum number of locks that can be queued by the user at one time. The default is 200 on VAX systems and 2000 on Alpha systems.

/EXPIRATION=time (default)

/NOEXPIRATION

Specifies the expiration date and time of the account. The /NOEXPIRATION qualifier removes the expiration date on the account. If you do not specify an expiration time when you add a new account, AUTHORIZE copies the expiration time from the DEFAULT account. (The expiration time on the DEFAULT account is "none" by default.)

/FILLM=value

Specifies the open file limit for the FILLM field of the UAF record. The open file limit is the maximum number of files that can be open at one time, including active network logical links. The default is 300 on VAX systems and 100 on Alpha systems.

/FLAGS=([NO]option[,...])

Specifies login flags for the user. The prefix NO clears the flag. The options are as follows:

AUDIT	Enables or disables mandatory security auditing for a specific user. By default, the system does not audit the activities of specific users (NOAUDIT).
AUTOLOGIN	Restricts the user to the automatic login mechanism when logging in to an account. When set, the flag disables login by any terminal that requires entry of a user name and password. The default is to require a user name and password (NOAUTOLOGIN).
CAPTIVE	Prevents the user from changing any defaults at login, for example, /CLI or /LGICMD. It prevents the user from escaping the captive login command procedure specified by the /LGICMD qualifier and gaining access to the DCL command level. Refer to "Guidelines for Captive Command Procedures" in the HP OpenVMS Guide to System Security. The CAPTIVE flag also establishes an environment where Ctrl/Y interrupts are initially turned off; however, command procedures can still turn on Ctrl/Y interrupts with the DCL command SET CONTROL=Y. By default, an account is not captive (NOCAPTIVE).
DEFCLI	Restricts the user to the default command interpreter by prohibiting the use of the /CLI qualifier at login. By default, a user can choose a CLI (NODEFCLI).
DISCTLY	Establishes an environment where Ctrl/Y interrupts are initially turned off and are invalid until a SET CONTROL=Y is encountered. This could happen in SYLOGIN.COM or in a procedure called by SYLOGIN.COM. Once a SET CONTROL=Y is executed (which requires no privilege), a user can enter a Ctrl/Y and reach the DCL prompt ($). If the intent of DISCTLY is to force execution of the login command files, then SYLOGIN.COM should issue the DCL command SET CONTROL=Y to turn on Ctrl/Y interrupts before exiting. By default, Ctrl/Y is enabled (NODISCTLY).
DISFORCE_PWD_CHANGE	Removes the requirement that a user must change an expired password at login. By default, a person can use an expired password only once (NODISFORCE_PWD_CHANGE) and then is forced to change the password after logging in. If the user does not select a new password, the user is locked out of the system. To use this feature, set a password expiration date with the /PWDLIFETIME qualifier.
DISIMAGE	Prevents the user from executing RUN and foreign commands. By default, a user can execute RUN and foreign commands (NODISIMAGE).
DISMAIL	Disables mail delivery to the user. By default, mail delivery is enabled (NODISMAIL).
DISNEWMAIL	Suppresses announcements of new mail at login. By default, the system announces new mail (NODISNEWMAIL).
DISPWDDIC	Disables automatic screening of new passwords against a system dictionary. By default, passwords are automatically screened (NODISPWDDIC).
DISPWDHIS	Disables automatic checking of new passwords against a list of the user's old passwords. By default, the system screens new passwords (NODISPWDHIS).
DISPWDSYNCH	Suppresses synchronization of the external password for this account. See bit 9 in the SECURITY_POLICY system parameter for systemwide password synchronization control.
DISRECONNECT	Disables automatic reconnection to an existing process when a terminal connection has been interrupted. By default, automatic reconnection is enabled (NODISRECONNECT).
DISREPORT	Suppresses reports of the last login time, login failures, and other security reports. By default, login information is displayed (NODISREPORT).
DISUSER	Disables the account so the user cannot log in. For example, the DEFAULT account is disabled. By default, an account is enabled (NODISUSER).
DISWELCOME	Suppresses the welcome message (an informational message displayed during a local login). This message usually indicates the version number of the operating system that is running and the name of the node on which the user is logged in. By default, a system login message appears (NODISWELCOME).
EXTAUTH	Considers user to be authenticated by an external user name and password, not by the SYSUAF user name and password. (The system still uses the SYSUAF record to check a user's login restrictions and quotas and to create the user's process profile.)
GENPWD	Restricts the user to generated passwords. By default, users choose their own passwords (NOGENPWD).
LOCKPWD	Prevents the user from changing the password for the account. By default, users can change their passwords (NOLOCKPWD).
PWD_EXPIRED	Marks a password as expired. The user cannot log in if this flag is set. The LOGINOUT.EXE image sets the flag when both of the following conditions exist: a user logs in with the DISFORCE_PWD_CHANGE flag set, and the user's password expires. A system manager can clear this flag. By default, passwords are not expired after login (NOPWD_EXPIRED).
PWD2_EXPIRED	Marks a secondary password as expired. Users cannot log in if this flag is set. The LOGINOUT.EXE image sets the flag when both of the following conditions exist: a user logs in with the DISFORCE_PWD_CHANGE flag set, and the user's password expires. A system manager can clear this flag. By default, passwords are not set to expire after login (NOPWD2_EXPIRED).
PWDMIX	Enables case-sensitive and extended-character passwords. After PWDMIX is specified, you can then use mixed-case and extended characters in passwords. Be aware that before the PWDMIX flag is enabled, the system stores passwords in all upper-case. Therefore, until you change passwords, you must enter your pre-PWDMIX passwords in upper-case. To change the password after PWDMIX is enabled: You (the user) can use the DCL command SET PASSWORD, specifying the new mixed-case password (omitting quotation marks). You (the system manager) can use the AUTHORIZE command MODIFY/PASSWORD, and enclose the user's new mixed-case password in quotation marks " " .
RESTRICTED	Prevents the user from changing any defaults at login (for example, by specifying /LGICMD) and prohibits user specification of a CLI with the /CLI qualifier. The RESTRICTED flag establishes an environment where Ctrl/Y interrupts are initially turned off; however, command procedures can still turn on Ctrl/Y interrupts with the DCL command SET CONTROL=Y. Typically, this flag is used to prevent an applications user from having unrestricted access to the CLI. By default, a user can change defaults (NORESTRICTED).
VMSAUTH	Allows account to use standard (SYSUAF) authentication when the EXTAUTH flag would otherwise require external authentication. This depends on the application. An application specifies the VMS domain of interpretation when calling SYS$ACM to request standard VMS authentication for a user account that normally uses external authentication.

/GENERATE_PASSWORD[=keyword]

/NOGENERATE_PASSWORD (default)

Invokes the password generator to create user passwords. Generated passwords can consist of 1 to 10 characters. Specify one of the following keywords:

BOTH	Generate primary and secondary passwords.
CURRENT	Do whatever the DEFAULT account does (for example, generate primary, secondary, both, or no passwords). This is the default keyword.
PRIMARY	Generate primary password only.
SECONDARY	Generate secondary password only.

When you modify a password, the new password expires automatically; it is valid only once (unless you specify /NOPWDEXPIRED). On login, users are forced to change their passwords (unless you specify /FLAGS=DISFORCE_PWD_CHANGE).

Note that the /GENERATE_PASSWORD and /PASSWORD qualifiers are mutually exclusive.

/INTERACTIVE[ =(range[,...])]

/NOINTERACTIVE

Specifies the hours of access for interactive logins. For a description of the range specification, see the /ACCESS qualifier. By default, there are no access restrictions on interactive logins.

/JTQUOTA=value

Specifies the initial byte quota with which the jobwide logical name table is to be created. By default, the value is 4096 on VAX systems and 4096 on Alpha systems.

/LGICMD=filespec

Specifies the name of the default login command file. The file name defaults to the device specified for /DEVICE, the directory specified for /DIRECTORY, a file name of LOGIN, and a file type of .COM. If you select the defaults for all these values, the file name is SYS$SYSTEM:[USER]LOGIN.COM.

/LOCAL[=(range[,...])]

Specifies hours of access for interactive logins from local terminals. For a description of the range specification, see the /ACCESS qualifier. By default, there are no access restrictions on local logins.

/MAXACCTJOBS=value

Specifies the maximum number of batch, interactive, and detached processes that can be active at one time for all users of the same account. By default, a user has a maximum of 0, which represents an unlimited number.

/MAXDETACH=value

Specifies the maximum number of detached processes with the cited user name that can be active at one time. To prevent the user from creating detached processes, specify the keyword NONE. By default, a user has a value of 0, which represents an unlimited number.

/MAXJOBS=value

Specifies the maximum number of processes (interactive, batch, detached, and network) with the cited user name that can be active simultaneously. The first four network jobs are not counted. By default, a user has a maximum value of 0, which represents an unlimited number.

/MODIFY_IDENTIFIER (default)

/NOMODIFY_IDENTIFIER

Specifies whether the identifier associated with the user is to be modified in the rights database. This qualifier applies only when you modify the UIC or user name in the UAF record. By default, the associated identifiers are modified.

/NETWORK[=(range[,...])]

Specifies hours of access for network batch jobs. For a description of how to specify the range, see the /ACCESS qualifier. By default, network logins have no access restrictions.

/OWNER=owner-name

Specifies the name of the owner of the account. You can use this name for billing purposes or similar applications. The owner name is 1 to 31 characters. No default owner name exists.

/PASSWORD=(password1[,password2])

/NOPASSWORD

Specifies up to two passwords for login. Passwords can be from 0 to 32 alphanumeric characters in length. The dollar sign ($) and underscore (_) are also permitted.

Uppercase and lowercase characters are equivalent. All lowercase characters are converted to uppercase before the password is encrypted. Avoid using the word password as the actual password.

Use the /PASSWORD qualifier as follows:

• To set only the first password and clear the second, specify /PASSWORD=password.
• To set both the first and second password, specify /PASSWORD=(password1, password2).
• To change the first password without affecting the second, specify /PASSWORD=(password, "").
• To change the second password without affecting the first, specify /PASSWORD=("", password).
• To set both passwords to null, specify /NOPASSWORD.

When you modify a password, the new password expires automatically; it is valid only once (unless you specify /NOPWDEXPIRED). On login, the user is forced to change the password (unless you specify /FLAGS=DISFORCE_PWD_CHANGE).

Note that the /GENERATE_PASSWORD and /PASSWORD qualifiers are mutually exclusive.

/PBYTLM

This flag is reserved for HP.

/PGFLQUOTA=value

Specifies the paging file limit. This is the maximum number of pages that the person's process can use in the system paging file. By default, the value is 32768 pages on VAX systems and 50000 pagelets on Alpha systems.

If decompressing libraries, make sure to set PGFLQUOTA to twice the size of the library.

/PRCLM=value

Specifies the subprocess creation limit. This is the maximum number of subprocesses that can exist at one time for the specified user's process. By default, the value is 2 on VAX systems and 8 on Alpha systems.

/PRIMEDAYS=([NO]day[,...])

Defines the primary and secondary days of the week for logging in. Specify the days as a list separated by commas, and enclose the list in parentheses. To specify a secondary day, prefix the day with NO (for example, NOFRIDAY). To specify a primary day, omit the NO prefix.

By default, primary days are Monday through Friday and secondary days are Saturday and Sunday. If you omit a day from the list, AUTHORIZE uses the default value. (For example, if you omit Monday from the list, AUTHORIZE defines Monday as a primary day.)

Use the primary and secondary day definitions in conjunction with such qualifiers as /ACCESS, /INTERACTIVE, and /BATCH.

/PRIORITY=value

Specifies the default base priority. The value is an integer in the range of 0 to 31 on VAX systems and 0 to 63 on Alpha systems. By default, the value is set to 4 for timesharing users.

/PRIVILEGES=([NO]privname[,...])

Specifies which privileges the user is authorized to hold, although these privileges are not necessarily enabled at login. (The /DEFPRIVILEGES qualifier determines which ones are enabled.) A NO prefix removes the privilege from the user. The keyword NOALL disables all user privileges. Many privileges have varying degrees of power and potential system impact (see the HP OpenVMS Guide to System Security for a detailed discussion). By default, a user holds TMPMBX and NETMBX privileges. Privname is the name of the privilege.

/PWDEXPIRED (default)

/NOPWDEXPIRED

Specifies the password is valid for only one login. A user must change a password immediately after login or be locked out of the system. The system warns users of password expiration. A user can either specify a new password, with the DCL command SET PASSWORD, or wait until expiration and be forced to change. By default, a user must change a password when first logging in to an account. The default is applied to the account only when the password is being modified.

/PWDLIFETIME=time (default)

/NOPWDLIFETIME

Specifies the length of time a password is valid. Specify a delta time value in the form [dddd-] [hh:mm:ss.cc]. For example, for a lifetime of 120 days, 0 hours, and 0 seconds, specify /PWDLIFETIME="120-". For a lifetime of 120 days 12 hours, 30 minutes and 30 seconds, specify /PWDLIFETIME="120-12:30:30". If a period longer than the specified time elapses before the user logs in, the system displays a warning message. The password is marked as expired.

To prevent a password from expiring, specify the time as NONE. By default, a password expires in 90 days.

/PWDMINIMUM=value

Specifies the minimum password length in characters. Note that this value is enforced only by the DCL command SET PASSWORD. It does not prevent you from entering a password shorter than the minimum length when you use AUTHORIZE to create or modify an account. By default, a password must have at least 6 characters. The value specified by the /PWDMINIMUM qualifier conflicts with the value used by the /GENERATE_PASSWORD qualifier or the DCL command SET PASSWORD/GENERATE, the operating system chooses the lesser value. The maximum value for generated passwords is 10.

/QUEPRIO=value

Reserved for future use.

/REMOTE[=(range[,...])]

Specifies hours during which access is permitted for interactive logins from network remote terminals (with the DCL command SET HOST). For a description of the range specification, see the /ACCESS qualifier. By default, remote logins have no access restrictions.

/SHRFILLM=value

Specifies the maximum number of shared files that the user can have open at one time. By default, the system assigns a value of 0, which represents an infinite number.

/TQELM

Specifies the total number of entries in the timer queue plus the number of temporary common event flag clusters that the user can have at one time. By default, a user can have 10.

/UIC=value

Specifies the user identification code (UIC). The UIC value is a group number in the range from 1 to 37776 (octal) and a member number in the range from 0 to 177776 (octal), which are separated by a comma and enclosed in brackets. HP reserves group 1 and groups 300--377 for its own use.

Each user must have a unique UIC. By default, the UIC value is [200,200].

/WSDEFAULT=value

Specifies the default working set limit. This represents the initial limit to the number of physical pages the process can use. (The user can alter the default quantity up to WSQUOTA with the DCL command SET WORKING_SET.) By default, a user has 256 pages on VAX systems and 2000 pagelets on Alpha systems.

The value cannot be greater than WSMAX. This quota value replaces smaller values of PQL_MWSDEFAULT.

/WSEXTENT=value

Specifies the working set maximum. This represents the maximum amount of physical memory allowed to the process. The system provides memory to a process beyond its working set quota only when it has excess free pages. The additional memory is recalled by the system if needed.

The value is an integer equal to or greater than WSQUOTA. By default, the value is 1024 pages on VAX systems and 16384 pagelets on Alpha systems. The value cannot be greater than WSMAX. This quota value replaces smaller values of PQL_MWSEXTENT.

/WSQUOTA=value

Specifies the working set quota. This is the maximum amount of physical memory a user process can lock into its working set. It also represents the maximum amount of swap space that the system reserves for this process and the maximum amount of physical memory that the system allows the process to consume if the systemwide memory demand is significant.

The value cannot be greater than the value of WSMAX and cannot exceed 64K pages. This quota value replaces smaller values of PQL_MWSQUOTA.

Description

The MODIFY command changes values in a SYSUAF user record. Most values not in the command remain unchanged. If the UIC is changed, the value of the corresponding identifier is also changed.

Modifications to the user record are not retroactive; thus, any changes to quota values apply to the next process that is created but not to the current one.

Examples

UAF> MODIFY ROBIN /PASSWORD=SP0172
%UAF-I-MDFYMSG, user record(s) updated
      

The command in this example changes the password for user ROBIN without altering any other values in the record.

UAF> MODIFY ROBIN/FLAGS=RESTRICTED
%UAF-I-MDFYMSG, user record(s) updated
      

The command in this example modifies the UAF record for user ROBIN by adding the login flag RESTRICTED.

MODIFY/IDENTIFIER

Modifies an identifier name, its associated value, or its attributes in the rights database.

Format

MODIFY/IDENTIFIER id-name

Parameter

id-name

Specifies the name of an identifier to be modified.

Qualifiers

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

Specifies attributes to be associated with the modified identifier. The following keywords are valid:

DYNAMIC	Allows unprivileged holders of the identifier to remove and to restore the identifier from the process rights list by using the DCL command SET RIGHTS_LIST.
HOLDER_HIDDEN	Prevents people from getting a list of users who hold an identifier, unless they own the identifier themselves.
NAME_HIDDEN	Allows holders of an identifier to have it translated, either from binary to ASCII or from ASCII to binary, but prevents unauthorized users from translating the identifier.
NOACCESS	Makes any access rights of the identifier null and void. If a user is granted an identifier with the No Access attribute, that identifier has no effect on the user's access rights to objects. This attribute is a modifier for an identifier with the Resource or Subsystem attribute.
RESOURCE	Allows holders of an identifier to charge disk space to the identifier. Used only for file objects.
SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem. Used only for file objects.

To remove an attribute from the identifier, add a NO prefix to the attribute keyword. For example, to remove the Resource attribute, specify /ATTRIBUTES=NORESOURCE.

Note If you specify the NORESOURCE keyword without naming any holder with the /HOLDER qualifier, all holders lose the right to charge resources.

/HOLDER=username

Specifies the holder of an identifier whose attributes are to be modified. The /HOLDER qualifier is used only in conjunction with the /ATTRIBUTES qualifier.

If you specify /HOLDER, the /NAME and /VALUE qualifiers are ignored.

/NAME=new-id-name

Specifies a new identifier name to be associated with the identifier.

/VALUE=value-specifier

Specifies a new identifier value. Note that an identifier value cannot be modified from a UIC to a non-UIC format or vice versa. The following formats are valid for the value-specifier:

IDENTIFIER:n	An integer value in the range of 65,536 to 268,435,455. You can also specify the value in hexadecimal (precede the value with %X) or octal (precede the value with %O). To differentiate general identifiers from UIC identifiers, %X80000000 is added to the value you specify.
GID:n	GID is the POSIX group identifier. It is an integer value in the range 0 to 16,777,215 (%XFFFFFF). The system will add %XA400.0000 to the value you specify and then enter this new value into the system RIGHTSLIST as an identifier.
UIC:uic	A UIC value in the standard UIC format.

Description

The MODIFY/IDENTIFIER command changes identifier names, associated values, and attributes in the rights database. Values not specified in the command remain unchanged.

Examples

UAF> MODIFY/IDENTIFIER OLD_ID /NAME=NEW_ID
%UAF-I-RDBMDFYMSG, identifier OLD_ID modified
      

The command in this example changes the name of the OLD_ID identifier to NEW_ID.

UAF> MODIFY/IDENTIFIER/VALUE=UIC:[300,21] ACCOUNTING
%UAF-I-RDBMDFYMSG, identifier ACCOUNTING modified
      

The command in this example changes the old UIC value of the identifier ACCOUNTING to a new value.

UAF> MODIFY/IDENTIFIER/ATTRIBUTES=NORESOURCE-
_UAF> /HOLDER=CRAMER ACCOUNTING
%UAF-I-RDBMDFYMSG, identifier ACCOUNTING modified
      

The command in this example associates the attribute NORESOURCE with the identifier ACCOUNTING in CRAMER's holder record. The identifier ACCOUNTING is not changed.

MODIFY/PROXY

Modifies an entry in the network proxy authorization file to specify a different local account as the default proxy account for the remote user or to specify no default proxy account for the remote user.

The command modifies an entry in the network proxy authorization file NET$PROXY.DAT and, to maintain compatibility with other systems, modifies an entry in NETPROXY.DAT.

Note You must modify the proxy database from a system running the current OpenVMS system.

Format

MODIFY/PROXY node::remote-user

Parameters

node

Specifies a node name. If you specify an asterisk wildcard character (*), the specified remote user on all nodes is served by the local user.

remote-user

Specifies the user name of a user at a remote node. If you specify an asterisk wildcard character, all users at the specified node are served by the local user.

For systems that are not OpenVMS systems that implement DECnet, specifies the UIC of a user at a remote node. You can specify an asterisk wildcard in the group and member fields of the UIC.

Qualifier

/DEFAULT[=local-user]
/NODEFAULT

Designates the default user name on the local node through which proxy access from the remote user is directed. If /NODEFAULT is specified, removes the default designation.

Description

Use the MODIFY/PROXY command to specify a different local account as the default proxy account for the remote user or to specify that there is no default proxy account for the remote user. Whenever you modify user entries, AUTHORIZE signals DECnet to update its volatile database. Proxy modifications take effect immediately on all nodes in a cluster that share the proxy database.

The first command in the following example grants remote user STIR::YETTA proxy access to the PROXY1 and PROXY2 local accounts. The default proxy account is PROXY1. The second command changes the default proxy account to PROXY2.

UAF> ADD/PROXY STIR::YETTA PROXY1/DEFAULT, PROXY2 . . . UAF> MODIFY/PROXY STIR::YETTA /DEFAULT=PROXY2

The next example shows the command used to remove the default proxy designation.

UAF> MODIFY/PROXY STIR::YETTA /NODEFAULT

If you remove the default proxy designation as shown in the last command, remote user STIR::YETTA must include the name of the proxy account (PROXY1 or PROXY2) in the access control string of each network operation to gain proxy access to the local system.

If no default proxy account is specified either in the network proxy database or in the access control string of the DCL command, the system attempts to perform the network operation using the default DECnet account.

Example

UAF> MODIFY/PROXY MISHA::MARCO /DEFAULT=JOHNSON
%UAF-I-NAFADDMSG, record successfully modified in NETPROXY.DAT
      

The command in this example changes the default proxy account for user MARCO on the remote node MISHA to the JOHNSON account.

MODIFY/SYSTEM_PASSWORD

Changes the systemwide password.

Note The systemwide password is different from the password for the SYSTEM user name. See the note in the Description.

This command operates similarly to the DCL command SET PASSWORD/SYSTEM.

Format

MODIFY/SYSTEM_PASSWORD= system-password

Parameter

system-password

Specifies the new systemwide password.

Qualifiers

None.

Description

For a detailed description of the effects of this command, refer to the discussion of the SET PASSWORD/SYSTEM command in the HP OpenVMS Guide to System Security.

Example

UAF> MODIFY/SYSTEM_PASSWORD=ABRACADABRA
UAF>
      

This command changes the systemwide password to ABRACADABRA.

REMOVE

Deletes a SYSUAF user record and corresponding identifiers in the rights database. The DEFAULT and SYSTEM records cannot be deleted.

Note REMOVE/IDENTIFIER and REMOVE/PROXY are documented as separate commands.

Format

REMOVE username

Parameter

username

Specifies the name of a user in the SYSUAF.

Qualifier

/REMOVE_IDENTIFIER (default)

/NOREMOVE_IDENTIFIER

Specifies whether the user name and account name identifiers should be removed from the rights database when a record is removed from the UAF. If two UAF records have the same UIC, the user name identifier is removed only when the second record is deleted. Similarly, the account name identifier is removed only if there are no remaining UAF records with the same group as the deleted record.

Description

If you remove a SYSUAF record for a user who also appears as a local user in the network user authorization file, every network authorization record for that user is also removed.

Example

UAF> REMOVE ROBIN
%UAF-I-REMMSG, record removed from SYSUAF.DAT
%UAF-I-RDBREMMSGU, identifier ROBIN value: [000014,000006] removed from
  RIGHTSLIST.DAT
      

The command in this example deletes the record for user ROBIN from the SYSUAF and ROBIN's UIC identifier from RIGHTSLIST.DAT.

REMOVE/IDENTIFIER

Removes an identifier from the rights database.

Format

REMOVE/IDENTIFIER id-name

Parameter

id-name

Specifies the name of an identifier in the rights database.

Qualifiers

None.

Example

UAF> REMOVE/IDENTIFIER Q1SALES
%UAF-I-RDBREMMSGU, identifier Q1SALES value %X80010024 removed from
  RIGHTSLIST.DAT
      

The command in this example removes the identifier Q1SALES from the rights database. All of its holder records are removed with it.

REMOVE/PROXY

Deletes network proxy access for the specified remote user.

Format

REMOVE/PROXY node::remote-user [local-user,...]

Parameters

node

Specifies the name of a network node in the network proxy authorization file.

remote-user

Specifies the user name or UIC of a user on a remote node. The asterisk wildcard character (*) is permitted in the remote-user specification.

local-user

Specifies the user name of from 1 to 16 users on the local node. If no local user is specified, proxy access to all local accounts is removed.

Qualifiers

None.

Example

UAF> REMOVE/PROXY MISHA::MARCO
%UAF-I-NAFREMMSG, proxy from MISHA::MARCO to * removed

      

The command in this example deletes the record for MISHA::MARCO from the network proxy authorization file, removing all proxy access to the local node for user MARCO on node MISHA.

RENAME

Changes the user name of the SYSUAF record (and, if specified, the corresponding identifier) while retaining the characteristics of the old record.

Note RENAME/IDENTIFIER is documented as a separate command.

Format

RENAME oldusername newusername

Parameters

oldusername

Specifies the current user name in the SYSUAF.

newusername

Specifies the new name for the user. It can contain 1 to 12 alphanumeric characters and underscores. Although dollar signs are permitted, they are usually reserved for system names.

Qualifiers

/GENERATE_PASSWORD[=keyword]

/NOGENERATE_PASSWORD (default)

Invokes the password generator to create user passwords. Generated passwords can consist of 1 to 10 characters. Specify one of the following keywords:

BOTH	Generate primary and secondary passwords.
CURRENT	Do whatever the DEFAULT account does (for example, generate primary, secondary, both, or no passwords). This is the default keyword.
PRIMARY	Generate primary password only.
SECONDARY	Generate secondary password only.

When you modify a password, the new password expires automatically; it is valid only once (unless you specify /NOPWDEXPIRED). On login, users are forced to change their passwords (unless you specify /FLAGS=DISFORCE_PWD_CHANGE).

Note that the /GENERATE_PASSWORD and /PASSWORD qualifiers are mutually exclusive.

/MODIFY_IDENTIFIER (default)

/NOMODIFY_IDENTIFIER

Specifies whether the identifier associated with the user is to be modified in the rights database. This qualifier applies only when you modify the UIC or user name in the UAF record. By default, the associated identifiers are modified.

/PASSWORD=(password1[,password2])

/NOPASSWORD

Specifies up to two passwords for login. Passwords can be from 0 to 32 alphanumeric characters in length. The dollar sign ($) and underscore (_) are also permitted.

Uppercase and lowercase characters are equivalent. All lowercase characters are converted to uppercase before the password is encrypted. Avoid using the word password as the actual password.

Use the /PASSWORD qualifier as follows:

• To set only the first password and clear the second, specify /PASSWORD=password.
• To set both the first and second password, specify /PASSWORD=(password1, password2).
• To change the first password without affecting the second, specify /PASSWORD=(password, "").
• To change the second password without affecting the first, specify /PASSWORD=("", password).
• To set both passwords to null, specify /NOPASSWORD.

When you modify a password, the new password expires automatically; it is valid only once (unless you specify /NOPWDEXPIRED). On login, the user is forced to change the password (unless you specify /FLAGS=DISFORCE_PWD_CHANGE).

Note that the /GENERATE_PASSWORD and /PASSWORD qualifiers are mutually exclusive.

When you create a new UAF record with the RENAME command, you must specify a password.

Description

The RENAME command renames a SYSUAF record. It changes the user name of the SYSUAF record (and, if specified, the corresponding identifier) while retaining the characteristics of the old record. Retention of these characteristics can be particularly helpful when a user's name changes.

Note that because password verification includes the user name as well as the password, an attempted login will fail when the user whose name has been changed attempts to log in with an old password. (Only null passwords can be effectively transferred from one user record to another by the RENAME command.) Make it a practice to include a new password when you use the RENAME command, and notify the user of the change. If you omit the /PASSWORD qualifier, you receive a warning message reminding you that the old password must be changed.

The user's network authorization records are automatically changed to the new name.

Examples

UAF> RENAME HAWKES KRAMERDOVE/PASSWORD=MARANNKRA
%UAF-I-PRACREN, proxies to HAWKES renamed
%UAF-I-RENMSG, user record renamed
%UAF-I-RDBMDFYMSG, identifier HAWKES modified
      

The command in this example changes the name of the account Hawkes to Kramerdove, modifies the user name identifier for the account, and renames all proxies to the account.

UAF> RENAME HAWKES KRAMERDOVE
%UAF-I-PRACREN, proxies to HAWKES renamed
%UAF-I-RENMSG, user record renamed
%UAF-W-DEFPWD, Warning: copied or renamed records must receive
  new password
%UAF-I-RDBMDFYMSG, identifier HAWKES modified
      

This example shows the warning message that the system displays if you fail to specify a new password with the RENAME command.

RENAME/IDENTIFIER

Renames an identifier in the rights database.

Format

RENAME/IDENTIFIER current-id-name new-id-name

Parameters

current-id-name

Specifies the name of an identifier to be renamed.

new-id-name

Specifies the new name for the identifier.

Qualifiers

None.

Description

The RENAME/IDENTIFIER command is functionally equivalent to the following AUTHORIZE command:

MODIFY/IDENTIFIER/NAME=new-id-name id-name

Example

UAF> RENAME/IDENTIFIER Q1SALES Q2SALES
%UAF-I-RDBMDFYMSG, identifier Q1SALES modified
      

The command in this example renames the identifier Q1SALES to Q2SALES.

REVOKE/IDENTIFIER

Takes an identifier away from a user.

Format

REVOKE/IDENTIFIER id-name user-spec

Parameters

id-name

Specifies the identifier name. The identifier name is a string of 1 to 31 alphanumeric characters. The name can contain underscores and dollar signs. It must contain at least one nonnumeric character.

user-spec

Specifies the UIC identifier that uniquely identifies the user on the system. This type of identifier appears in alphanumeric format, not numeric format; for example, [GROUP1,JONES].

Description

The REVOKE/IDENTIFIER command edits RIGHTSLIST.DAT, removing the user's name from the list of those who hold a given identifier. The change does not affect the process rights list of any current processes.

Example

UAF> REVOKE/IDENTIFIER INVENTORY CRAMER
%UAF-I-REVOKEMSG, identifier INVENTORY revoked from CRAMER
      

The command in this example revokes the identifier INVENTORY from the user Cramer. Cramer loses the identifier and any resources associated with it.

Note that because rights identifiers are stored in numeric format, it is not necessary to change records for users holding a renamed identifier.

SHOW

Displays reports for selected UAF records on the current SYS$OUTPUT device.

Note SHOW/IDENTIFIER, SHOW/PROXY, and SHOW/RIGHTS are documented as separate commands.

Format

SHOW user-spec

Parameter

user-spec

Specifies the user name or UIC of the requested UAF record. If you omit the user-spec parameter, the UAF records of all users are listed. The asterisk (*) and percent sign (%) wildcard characters are permitted in the user name.

Qualifiers

/BRIEF

Specifies that a brief report be displayed. In the report, the Directory field displays one of the following items:

• Disuser---The account has been disabled.
• Expired---The account has expired.
• A device and directory name---The login device and directory for the account (for example, DOCD$:[SMITH]).

If you omit the /BRIEF qualifier, AUTHORIZE displays a full report.

/FULL

Specifies that a full report be displayed, including identifiers held by the user. Full reports include the details of the limits, privileges, login flags, and the command interpreter as well as the identifiers held by the user. The password is not listed.

/EXACT

Controls whether the SHOW command matches the search string exactly or treats uppercase and lowercase letters as equivalents. Enclose the specified string within quotation marks (" "). Use /EXACT with the /PAGE=SAVE and /SEARCH qualifiers.

/HIGHLIGHT[=keyword]

/NOHIGHLIGHT (default)

Identifies how to display the line that contains a string once it is found. The following keywords are valid:

BLINK
BOLD (default)
REVERSE
UNDERLINE

Use the /HIGHLIGHT qualifier with the /PAGE=SAVE and /SEARCH qualifiers.

/PAGE[=keyword]

/NOPAGE (default)

Controls the information display on a screen. The following keywords are valid:

CLEAR_SCREEN	Clear the screen before displaying the next page.
SCROLL	Display a continuous stream of information.
SAVE[= n]	Store information and enable the navigational keys listed in Table 5-1. By default, the command saves 5 pages. The maximum page width is 255 columns.

Table 5-1 Screen Control Keys

Key or Key Sequence	Action Taken When Key or Key Sequence Is Pressed
DOWN ARROW KEY	Scroll the display down one line
LEFT ARROW KEY	Scroll the display one column to the left
RIGHT ARROW KEY	Scroll the display one column to the right
UP ARROW KEY	Scroll the display up one line
Find (E1)	Search for a new string in the information being displayed
Insert Here (E2)	Move the display to the right by half a screen
Remove (E3)	Move the display to the left by half a screen
Select (E4)	Switch from 80-column displays to 132-column displays
Prev Screen (E5)	Return to the previous page
Next Screen (E6)	Display the next page
CTRL/Z	Return to the UAF> prompt
Help	Display AUTHORIZE help text
F16 (Do)	Switch from the oldest to the newest page
Ctrl/W	Refresh the display

/SEARCH=string

Used with the /PAGE=SAVE qualifier to specify a string to find in the information being displayed. You can dynamically change the search string by pressing the Find key (E1) while the information is being displayed.

/WRAP

/NOWRAP (default)

Used with the /PAGE=SAVE qualifier to limit the number of columns to the width of the screen and wrap lines that extend beyond the width of the screen to the next line.

The /NOWRAP qualifier extends lines beyond the width of the screen. Use the /PAGE=SAVE qualifier and the screen control keys listed in Table 5-1 to view the entire screen.

Description

The SHOW command produces reports on user authorization records. You can select the reports to be displayed, as follows:

• To display a single-user report, specify a user name.
• To display reports for all users in ascending sequence by user name, specify an asterisk wildcard character (*).
• To display reports for all users with a common UIC, specify the UIC. Users with the same UIC are listed in the order in which they were added to the SYSUAF.
  You can also use the asterisk wildcard character to specify all or part of the UIC, as shown in the following examples:

  Command	Description
  SHOW [14,*] /BRIEF	Displays a brief report for all users in group 14, in ascending sequence by member number.
  SHOW [*,6] /BRIEF	Displays a brief report for all users with a member number of 6.
  SHOW [*,*] /BRIEF	Displays a brief report for all users, in ascending sequence by UIC.

Examples

UAF> SHOW ROBIN
      

The command in this VAX example displays a full report for the user ROBIN. The display corresponds to the first example in the description of the ADD command. Most defaults are in effect.

Username: ROBIN Owner: JOSEPH ROBIN Account: VMS UIC: [14,6] ([INV,ROBIN]) CLI: DCL Tables: DCLTABLES Default: SYS$USER:[ROBIN] LGICMD: Login Flags: Primary days: Mon Tue Wed Thu Fri Secondary days: Sat Sun No access restrictions Expiration: (none) Pwdminimum: 6 Login Fails: 0 Pwdlifetime: (none) Pwdchange: 15-JAN-2000 14:08 Last Login: (none) (interactive), (none) (non-interactive) Maxjobs: 0 Fillm: 300 Bytlm: 32768 Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0 Maxdetach: 0 BIOlm: 40 JTquota: 4096 Prclm: 2 DIOlm: 40 WSdef: 256 Prio: 4 ASTlm: 40 WSquo: 512 Queprio: 0 TQElm: 10 WSextent: 1024 CPU: (none) Enqlm: 200 Pgflquo: 32768 Authorized Privileges: TMPMBX NETMBX Default Privileges: TMPMBX NETMBX Identifier Value Attributes CLASS_CA101 %X80010032 NORESOURCE NODYNAMIC CLASS_PY102 %X80010049 NORESOURCE NODYNAMIC

Note The quotas Pbytlm and Queprio are placeholders only.

UAF> SHOW [360,*] /BRIEF
      

The command in this example displays a brief report for every user with a group UIC of 360.

Owner Username UIC Account Privs Pri Default Directory JOHN JAMES JAMES [360,201] USER Normal 4 DOCD$:[JAMES] SUZY JONES JONES [360,203] DOC Devour 4 DOCD$:[JONES] CLIFF BROWN BROWN [360,021] DOC All 4 disuser JOY CARTER CARTER [360,005] DOCSEC Group 4 expired

UAF> SHOW WELCH
      

This command displays a full report for the restricted user WELCH. This display corresponds to the second example in the description of the ADD command.

Username: WELCH Owner: ROB WELCH Account: INV UIC: [14,51] ([14,51]) CLI: DCL Tables: DCLTABLES Default: SYS$USER:[WELCH] LGICMD: SECUREIN Login Flags: Restricted Diswelcome Disnewmail ExtAuth Primary days: Mon Tue Wed Thu Fri Secondary days: Sat Sun Primary 000000000011111111112222 Secondary 000000000011111111112222 Day Hours 012345678901234567890123 Day Hours 012345678901234567890123 Network: ----- No access ------ ##### Full access ###### Batch: #########--------####### ---------#########------ Local: #########--------####### ---------#########------ Dialup: ##### Full access ###### ----- No access ------ Remote: #########--------####### ---------#########------ Expiration: (none) Pwdminimum: 6 Login Fails: 0 Pwdlifetime: (none) Pwdchange: (pre-expired) Last Login: (none) (interactive), (none) (non-interactive) Maxjobs: 0 Fillm: 300 Bytlm: 32768 Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0 Maxdetach: 0 BIOlm: 40 JTquota: 4096 Prclm: 2 DIOlm: 40 WSdef: 256 Prio: 4 ASTlm: 40 WSquo: 512 Queprio: 4 TQElm: 10 WSextent: 1024 CPU: (none) Enqlm: 200 Pgflquo: 32768 Authorized Privileges: TMPMBX NETMBX Default Privileges: TMPMBX NETMBX

Note that WELCH is a captive user who does not receive announcements of new mail or the welcome message when logging in. His login command file, SECUREIN.COM, is presumably a captive command file that controls all of his operations. (Such a command file never exits, but performs operations for its user and logs him out when appropriate.) The CAPTIVE flag prevents WELCH from escaping control of the command file by using Ctrl/Y or other means. Furthermore, he is restricted to logging in between the hours of 5:00 P.M. and 8:59 A.M. on weekdays and 9:00 A.M. and 5:59 P.M. on weekends. Although he is allowed to use dial-up lines at all times during the week, he is not allowed to log in over the network. On weekends, he is further restricted so that he cannot dial in at any time or use the DCL command SET HOST between the hours of 6:00 P.M. and 8:59 A.M.

SHOW/IDENTIFIER

Displays information about an identifier, such as its name, value, attributes, and holders, on the current SYS$OUTPUT device.

Format

SHOW/IDENTIFIER [id-name]

Parameter

id-name

Specifies an identifier name. The identifier name is a string of 1 to 31 alphanumeric characters. The name can contain underscores and dollar signs. It must contain at least one nonnumeric character. If you omit the identifier name, you must specify /USER or /VALUE.

Qualifiers

/BRIEF

Specifies a brief listing in which only the identifier name, value, and attributes are displayed. The default format is /BRIEF.

/FULL

Specifies a full listing in which the names of the identifier's holders are displayed along with the identifier's name, value, and attributes.

/USER=user-spec

Specifies one or more users whose identifiers are to be displayed. The user-spec can be a user name or a UIC. You can use the asterisk wildcard character (*) to specify multiple UICs or all user names. UICs must be in the form [*,*], [n,*], [*,n], or [n,n]. A wildcard user name specification (*) displays identifiers alphabetically by user name; a wildcard UIC specification ([*,*]) displays them numerically by UIC.

/VALUE=value-specifier

Specifies the value of the identifier to be listed. The following formats are valid for the value-specifier:

IDENTIFIER:n	An integer value in the range of 65,536 to 268,435,455. You can also specify the value in hexadecimal (precede the value with %X) or octal (precede the value with %O). To differentiate general identifiers from UIC identifiers, %X80000000 is added to the value you specify.
GID:n	GID is the POSIX group identifier. It is an integer value in the range 0 to 16,777,215 (%XFFFFFF). The system will add %XA400.0000 to the value you specify and then enter this new value into the system RIGHTSLIST as an identifier.
UIC:uic	A UIC value in the standard UIC format.

See also the screen control qualifiers listed under the SHOW command:

/EXACT

/HIGHLIGHT[=keyword]

/NOHIGHLIGHT (default)

/PAGE[=keyword]

/NOPAGE (default)

/SEARCH=string

/WRAP

/NOWRAP (default)

Description

The SHOW/IDENTIFIER command displays identifier names, values, attributes, and holders in various formats depending on the qualifiers specified. Two of these formats are illustrated in the following examples.

Examples

UAF> SHOW/IDENTIFIER/FULL INVENTORY
      

This command would produce output similar to the following example:

Name Value Attributes INVENTORY %X80010006 NORESOURCE NODYNAMIC Holder Attributes ANDERSON NORESOURCE NODYNAMIC BROWN NORESOURCE NODYNAMIC CRAMER NORESOURCE NODYNAMIC

UAF> SHOW/IDENTIFIER/USER=ANDERSON
      

This command displays the identifier associated with the user ANDERSON, as follows:

Name Value Attributes ANDERSON [000300,000015] NORESOURCE NODYNAMIC

The identifier is shown, along with its value and attributes. Note, however, that this is the same result you would produce had you specified ANDERSON's UIC with the following forms of the command:

UAF> SHOW/IDENTIFIER/USER=[300,015]

UAF> SHOW/IDENTIFIER/VALUE=UIC:[300,015]

SHOW/PROXY

Displays all authorized proxy access for the specified remote user.

Format

SHOW/PROXY node::remote-user

Parameters

node

Specifies the name of a network node in the network proxy authorization file. The asterisk wildcard character (*) is permitted in the node specification.

remote-user

Specifies the user name or UIC of a user on a remote node. The asterisk wildcard character (*) is permitted in the remote-user specification.

Qualifiers

/OLD

Directs AUTHORIZE to display information from NETPROXY.DAT rather than the default file NET$PROXY.DAT.

If someone modifies the proxy database on a cluster node that is running an OpenVMS system prior to Version 6.1, you can use the /OLD qualifier to display the contents of the old database, NETPROXY.DAT.

See also the screen control qualifiers listed under the SHOW command:

/EXACT

/HIGHLIGHT[=keyword]

/NOHIGHLIGHT (default)

/PAGE[=keyword]

/NOPAGE (default)

/SEARCH=string

/WRAP

/NOWRAP (default)

Description

The SHOW/PROXY command displays the first 255 characters of a node name although the command can handle a maximum of 1024 characters.

Examples

UAF> SHOW/PROXY SAMPLE::[200,100]

 Default proxies are flagged with an *

SAMPLE::[200,100]
     MARCO *                              PROXY2
     PROXY3
      

The command in this example displays all authorized proxy access for the user on node SAMPLE with a UIC of [200,100]. The default proxy account can be changed from MARCO to PROXY2 or PROXY3 with the MODIFY/PROXY command.

UAF> SHOW/PROXY *::*

 Default proxies are flagged with (D)

TAO:.TWA.RANCH::MARTINEZ
    MARTINEZ (D)                        SALES_READER

UAF> show/proxy/old *::*

 Default proxies are flagged with (D)

RANCH::MARTINEZ
    MARTINEZ (D)                        SALES_READER
      

The command in this example displays information about local authorized proxy access on a system running DECnet-Plus. The first command draws information from the file NET$PROXY.DAT. By including the /OLD qualifier on the SHOW/PROXY command, AUTHORIZE displays information from the file NETPROXY.DAT.

SHOW/RIGHTS

Displays the identifiers held by the specified identifiers or, if /USER is specified, all identifiers held by the specified users.

Format

SHOW/RIGHTS [id-name]

Parameter

id-name

Specifies the name of the identifier associated with the user. If you omit the identifier name, you must specify the /USER qualifier.

Qualifier

/USER=user-spec

Specifies one or more users whose identifiers are to be listed. The user-spec can be a user name or a UIC. You can use the asterisk wildcard character (*) to specify multiple UICs or all user names. UICs must be in the form [*,*], [n,*], [*,n], or [n,n]. A wildcard user name specification (*) or wildcard UIC specification ([*,*]) displays all identifiers held by users. The wildcard user name specification displays holders' user names alphabetically; the wildcard UIC specification displays them in the numerical order of their UICs.

See also the screen control qualifiers listed under the SHOW command:

/EXACT

/HIGHLIGHT[=keyword]

/NOHIGHLIGHT (default)

/PAGE[=keyword]

/NOPAGE (default)

/SEARCH=string

/WRAP

/NOWRAP (default)

Description

Output displayed from the SHOW/RIGHTS command is identical to that written to RIGHTSLIST.LIS when you use the LIST/RIGHTS command.

Example

UAF> SHOW/RIGHTS ANDERSON
      

This command displays all identifiers held by the user ANDERSON. For example:

Name Value Attributes INVENTORY %X80010006 NORESOURCE NODYNAMIC PAYROLL %X80010022 NORESOURCE NODYNAMIC

Note that the following formats of the command produce the same result:

SHOW/RIGHTS/USER=ANDERSON

SHOW/RIGHTS/USER=[300,015]

6.1 AUTOGEN Description

In addition, you can use AUTOGEN to reset system parameter values, system file sizes, or both. The new values and file sizes take effect the next time the system is booted.

HP recommends that you run AUTOGEN on a weekly basis to adjust system parameters according to your system's work load. For a list and description of all system parameters, refer to Appendix J

AUTOGEN executes in phases, with each phase performing a separate task. You control which tasks AUTOGEN performs by specifying a start phase and an end phase when you invoke AUTOGEN. For more information about the AUTOGEN phases, see Section 6.4.

You can add commands to the file SYS$SYSTEM:MODPARAMS.DAT to control the system parameter values and file sizes that AUTOGEN sets. AUTOGEN uses the information in this file to determine final values for system parameters or page, swap or dump file sizes. For more information, refer to the chapter about managing system parameters in the HP OpenVMS System Manager's Manual.

AUTOGEN can improve system performance by using dynamic information, called feedback, which is gathered from the running system.

The following sections explain how AUTOGEN uses NEWPARAMS.DAT and how layered product installation procedures can use it.

The basic reason for developing NEWPARAMS.DAT has been to provide a way for layered product installation procedures to easily supply AUTOGEN with the necessary parameter changes for the product. NEWPARAMS.DAT greatly reduces (if not eliminates) the need to modify MODPARAMS.DAT after installing a new layered product and avoids having installation procedures attempt to edit MODPARAMS.DAT.

NEWPARAMS.DAT does not replace or make MODPARAMS.DAT obsolete, and it does not remove the requirement to run AUTOGEN after installing a layered product. (AUTOGEN can, however, process several versions of NEWPARAMS.DAT, which you might have if you install several layered products without running AUTOGEN between installations).

6.1.1.1 How NEWPARAMS.DAT Works

Three files are involved in the operation of NEWPARAMS.DAT:

• NEWPARAMS.DAT
  This file contains the parameter requirements for a particular layered product.
• NEWPARAMS.DONE
  AUTOGEN renames each NEWPARAMS.DAT to NEWPARAMS.DONE as soon as it has finished processing the file.

  Note If AUTOGEN finds three versions of NEWPARAMS.DAT, it processes version 3, then version 2, and then version 1. After AUTOGEN has renamed the files to NEWPARAMS.DONE, their version numbers ARE reversed, reflecting the fact that the oldest file was processed and renamed the most recently. The system manager can purge these files at any time. AUTOGEN, however, does not delete these files immediately so that you can examine them if some problem occurs with the layered product installation or with a subsequent run of AUTOGEN.

• CLU$PARAMS.DAT
  This file receives the parameter values of the NEWPARAMS.DAT files that AUTOGEN processes.

In NEWPARAMS.DAT the AUTOGEN code expects to find records that are comments (which are not passed to CLU$PARAMS.DAT), and parameter assignments very much like those in MODPARAMS.DAT. These are usually assignments similar to ADD_parameter and MIN_parameter:

• The first setting, ADD_parameter, defines the amount of a particular resource (for example, NPAGEDYN, GBLPAGES) the layered product requires.
• The second setting, MIN_parameter, provides floor for the calculation of a parameter (for example, PQL_DWSDEFAULT).

The parameter settings in NEWPARAMS.DAT are integrated into CLU$PARAMS.DAT. This file is then used, along with MODPARAMS.DAT and the feedback and hardware configuration data, to calculate parameter values in the GENPARAMS phase. System managers do not need to modify CLU$PARAMS.DAT; MODPARAMS.DAT continues to be the proper file to contain system-specific parameter changes.

6.1.1.2 What Goes into NEWPARAMS.DAT

The following sections describe what is placed in the NEWPARAMS.DAT file.

6.1.1.2.1 Product Name

A very important difference between the parameter assignments in MODPARAMS.DAT, which is familiar to most system managers, and those in NEWPARAMS.DAT: the name of the layered product that makes the assignments.

You can pass the layered product name to AUTOGEN in either of the following ways:

• Prepend the name and a dollar-sign ($) to each parameter name; for example:

  DW-MOTIF$ADD_GBLPAGES=28000

• Include the name as a comment, which must begin as follows:

  !Set by

  
  The entire remainder of the comment is used as the product name for example:

  MIN_GBLPAGES=62000 !Set by DW-MOTIF

  
  In this example, DW-MOTIF becomes the product name.

The first method takes precedence over the second method. For example, someone might enter a value like the following:

 ABBOTT$add_npagedyn=1000000 !Set by COSTELLO

In this example, the prefix (ABBOTT) will be used, and the product name specified in the comment (COSTELLO) will be ignored.

HP recommends that you use one method or the other to avoid confusion.

6.1.1.2.2 Parameter Assignment

Except for specifying the product name, parameter assignment with NEWPARAMS.DAT works the same as it does in MODPARAMS.DAT, where you can set values, floors and ceilings, and specify amounts to add to a parameter; for example:

        WINDOW_SYSTEM = 1
        MIN_GBLSECTIONS = 600
        MAX_WSMAX = 250000
        ADD_GBLPAGES = 25000

You might want to remove one or more parameter assignments from CLU$PARAMS.DAT for a number of reasons. A layered product might no longer need to use a value other than the default value of a parameter. Also, occasionally OpenVMS Engineering makes a parameters obsolete (for example, VIRTUALPAGECNT), and layered product kits need to include a way to remove these parameters from a system.

To remove an assignment from CLU$PARAMS.DAT, create a NEWPARAMS.DAT that includes either of the following syntaxes:

   AGEN$REMOVE_PARAM  <parameter>  !Set by <product>
   AGEN$REMOVE_PARAM  <product>$<parameter>

The rules explained in Section 6.1.1.2.1 for specifying product names also apply here. Also, you can mix such removals with assignments in a single NEWPARAMS.DAT file. Use removals to remove assignments of parameters that will no longer be needed; to change a parameter value, simply assign the new value to the parameter in NEWPARAMS.DAT, and the new value will replace the old value.

Note that AUTOGEN does not parse anything between the parameter name and the !Set by comment. This allows the kit producer to use NEWPARAMS.DAT for installation and to create a NEWPARAMS.DAT for deinstallation by prepending "AGEN$REMOVE_PARAM " to the beginning of each line.

6.1.1.3 What CLU$PARAMS.DAT Looks Like

The format of CLU$PARAMS.DAT, which is used to define layered- product-driven parameter modifications, is as follows:

!   The file contains parameters supplied by layered products.
!  It should not be modified.  Customer parameters should be placed in
!  SYS$SYSTEM:MODPARAMS.DAT.
!=================================================================
!
DW_MOTIF$MIN_CHANNELCNT = 255                     !Set by DW-MOTIF
DW_MOTIF$ADD_GBLPAGES = 28000                     !Set by DW-MOTIF
DW_MOTIF$MIN_GBLPAGES = 62000                     !Set by DW-MOTIF
DW_MOTIF$ADD_GBLPAGFIL = 5000                     !Set by DW-MOTIF
DW_MOTIF$MIN_GBLPAGFIL = 6024                     !Set by DW-MOTIF
DECNET_PLUS$MIN_GBLPAGES = 55000                  !Set by DECnet-Plus
DECNET_PLUS$ADD_GBLPAGES = 24000                  !Set by DECnet-Plus

This example shows two layered product installations that use NEWPARAMS.DAT: one is DW-MOTIF (the DECWindows kit), and the other is DECnet-Plus.

A subsequent installation of DW-MOTIF replaces the value of each parameter assignment in CLU$PARAMS.DAT with the value found in NEWPARAMS.DAT. Whether the new kit has 255, 200 or 300 for MIN_CHANNELCNT, the value that is supplied is the value found in the new copy of CLU$PARAMS.DAT.

Similarly, the new value that DW_MOTIF provides for ADD_GBLPAGES replaces the 28000 in the assignment of ADD_GBLPAGES shown in the last example. These values are not cumulative for a given product; they do, however, accumulate across layered products; therefore, the total ADD_GBLPAGES value are as follows:

 28000 + 24000, or 52000

Both NEWPARAMS.DAT and CLU$PARAMS.DAT are ordinary text files created by text editors. HP does not recommend editing these files.

6.2 AUTOGEN Usage Summary

HP recommends that you run AUTOGEN in the following circumstances:

• During a new installation or upgrade.
• Whenever your work load changes significantly.
• When you add an optional (layered) software product. Certain layered products might require you to execute AUTOGEN to adjust parameter values and page and swap file sizes. (For information about using AUTOGEN to modify page and swap files, refer to the chapter on managing page, swap, and dump files in the HP OpenVMS System Manager's Manual.) Refer to specific product documentation for installation requirements.
• When you install images with the /SHARED attribute. The GBLSECTIONS and GBLPAGES parameters might need to be increased to accommodate additional use of global pages and global sections.
• During normal operation, as part of a batch-oriented command procedure that runs AUTOGEN on a regular basis and automatically sends a report to an appropriate Mail account. The recommended procedure is described in the chapter on managing system parameters in the HP OpenVMS System Manager's Manual.

After a new operating system installation or upgrade, examine the results of calculations that AUTOGEN made to determine whether AUTOGEN has set system parameter values that are appropriate for your workload requirements.

Table 6-1 lists the system parameters affected by AUTOGEN calculations. AUTOGEN calculations also affect the size of page, swap and dump files. Table 6-2 lists the system parameters affected by AUTOGEN feedback.

AUTOGEN feedback minimizes the necessity to modify parameter values or system file sizes. Feedback allows AUTOGEN to automatically size the operating system based on your actual work load. Sizing is the process of matching the allocation of system resources (memory and disk space) with the workload requirements of your site.

Feedback is information about how various resources are used by the system's work load. This information is continuously collected by the operating system executive. Because the system collects feedback when exception events occur, feedback collection does not affect system performance.

You control how AUTOGEN uses feedback by specifying an execution mode when you invoke AUTOGEN. When run in feedback mode, AUTOGEN analyzes this information and adjusts any related parameter values. For information about controlling AUTOGEN's use of feedback, see Section 6.5.

AUTOGEN collects feedback during the SAVPARAMS phase by executing the image SYS$SYSTEM:AGEN$FEEDBACK.EXE. AUTOGEN writes feedback information to the file SYS$SYSTEM:AGEN$FEEDBACK.DAT. This file is then read during the GETDATA phase. For more information about AUTOGEN phases, see Section 6.4.

Table 6-2 lists the system parameters affected by AUTOGEN feedback. Feedback also affects the size of page and swap files.

AUTOGEN executes in phases. You control which tasks AUTOGEN performs by specifying a start phase and an end phase when you invoke AUTOGEN. Table 6-3 lists the phases AUTOGEN can execute in order.

The following sections describe each phase in detail.

6.4.1 SAVPARAMS

The SAVPARAMS phase records feedback in the file AGEN$FEEDBACK.DAT, which can be used in subsequent AUTOGEN phases. If you specify NOFEEDBACK as the execution-mode parameter, the information collected is not used.

The SAVPARAMS phase is valid as a start phase and end phase. SAVPARAMS requires the SYSPRV and CMKRNL privileges.

The GETDATA phase collects the following information required for AUTOGEN calculations and places it in the file PARAMS.DAT:

• Hardware configuration data
• HP-supplied data from CLU$PARAMS.DAT
• Feedback from AGEN$FEEDBACK.DAT (if run in feedback mode)
• User-supplied data from MODPARAMS.DAT

The GETDATA phase also attempts to configure devices on the system, by executing the following procedure and command:

• The command procedure SYS$MANAGER:SYCONFIG.COM. (For more information about this procedure, refer to the chapter on managing devices in the HP OpenVMS System Manager's Manual.)
• The SYSGEN command AUTOCONFIGURE ALL (unless the symbol STARTUP$AUTOCONFIGURE_ALL is set to 0 in SYCONFIG.COM).

The GETDATA phase is valid as a start phase and an end phase. GETDATA requires the SYSPRV and CMKRNL privileges.

6.4.3 GENPARAMS

In the GENPARAMS phase, AUTOGEN calculates the parameter values based on data stored in PARAMS.DAT and produces SETPARAMS.DAT as output. AUTOGEN checks to see if feedback is included, and if so, uses it in the calculations unless the NOFEEDBACK execution mode was specified when AUTOGEN was invoked. Also during this phase, AUTOGEN generates the known image file list (VMSIMAGES.DAT).

The GENPARAMS phase is valid as a start phase and an end phase. GENPARAMS requires the SYSPRV and OPER privileges.

6.4.4 TESTFILES

The TESTFILES phase displays system page, swap, and dump file sizes calculated by AUTOGEN. (This phase does not change the file sizes.)

File sizes for all currently installed primary and secondary page and swap files are displayed. The information is directed to SYS$OUTPUT and the AGEN$PARAMS.REPORT file by default.

Specify the TESTFILES phase to display AUTOGEN's file size calculations; to generate new sized files, specify the GENFILES phase. You cannot specify both of these phases when invoking AUTOGEN. HP recommends that you use TESTFILES to display the file size changes before actually generating new sized files on your system.

The TESTFILES phase is valid only as an end phase. TESTFILES requires the SYSPRV privilege.

6.4.5 GENFILES

The GENFILES phase generates the new page, swap, and dump files on the system. This phase changes the file sizes based on AUTOGEN's calculations.

The GENFILES phase does not modify a file if the calculated size change is within ten percent of the existing file size. The following files are affected: PAGEFILE.SYS, SWAPFILE.SYS, SYSDUMP.DMP, and all other currently installed page and swap files. For more information, refer to the chapter on managing page, swap and dump files in the HP OpenVMS System Manager's Manual.

GENFILES is valid only as an end phase. GENFILES requires the SYSPRV privilege.

6.4.6 SETPARAMS

The SETPARAMS phase uses as its input the SETPARAMS.DAT file created during the GENPARAMS phase. In this phase, AUTOGEN runs SYSMAN to update the system parameter values in the default parameter file.

On VAX systems, the default parameter file is SYS$SYSTEM:VAXVMSSYS.PAR. AUTOGEN saves the current system parameters in the file SYS$SYSTEM:VAXVMSSYS.OLD before updating these parameters in SYS$SYSTEM:VAXVMSSYS.PAR. The new values are also saved in SYS$SYSTEM:AUTOGEN.PAR.

On Alpha systems, SYS$SYSTEM:ALPHAVMSSYS.PAR is the default parameter file. AUTOGEN saves the current system parameters in the file SYS$SYSTEM:ALPHAVMSSYS.OLD before updating these parameters in SYS$SYSTEM:ALPHAVMSSYS.PAR. The new values are also saved in SYS$SYSTEM:AUTOGEN.PAR.

The SETPARAMS phase is valid as a start phase and an end phase. SETPARAMS requires the SYSPRV and OPER privileges.

6.4.7 SHUTDOWN

SHUTDOWN shuts down the system and awaits a manual reboot. To use the new system parameter values generated in the SETPARAMS phase, specify either SHUTDOWN or REBOOT as the end phase. You can define the logical name AGEN$SHUTDOWN_TIME (using the DCL command DEFINE) to specify the number of minutes before shutdown occurs.

SHUTDOWN requires the SETPRV privilege.

6.4.8 REBOOT

REBOOT automatically shuts down and reboots the system, thus installing the new parameter values. To install the new system parameter values generated in the SETPARAMS phase, specify either SHUTDOWN or REBOOT as the end phase. You can define the logical name AGEN$SHUTDOWN_TIME (using the DCL command DEFINE) to specify the number of minutes before shutdown occurs.

REBOOT requires the SETPRV privilege.

6.4.9 HELP

HELP displays help information about AUTOGEN to the screen. The HELP phase is only valid as the start phase command line parameter. When you specify HELP for the start phase, the end phase and execution mode parameters are ignored.

6.5 Execution Modes

Specify an execution mode when you invoke AUTOGEN to control how AUTOGEN uses feedback. Table 6-4 lists the execution-mode options.

Table 6-5 lists the files AUTOGEN uses during each phase.

The AUTOGEN command procedure runs automatically when your system is installed or upgraded to set appropriate values for system parameters and sizes for system page, swap, and dump files.

Execute AUTOGEN to reset system parameter values and system file sizes. The new values and file sizes take effect the next time the system is booted.

Format

@SYS$UPDATE:AUTOGEN [start-phase] [end-phase] [execution-mode]

Parameters

start-phase

Specify the phase where AUTOGEN is to begin executing. Table 6-3 lists the options for the end-phase parameter.

The phase specified for start-phase must either precede or be identical to the phase specified for end-phase, according to the sequence shown in Table 6-3. If you do not supply an option for the start-phase parameter, enter a null argument (that is, "" ). If you do not specify a start phase, GENPARAMS is the default.

end-phase

Specify the phase where AUTOGEN is to complete executing. Table 6-3 lists the options for the end-phase parameter. If you do not specify an end phase, the end phase has the same value as the start phase by default.

execution-mode

Specify one of the following execution-mode options to control how AUTOGEN uses feedback:

• FEEDBACK
• NOFEEDBACK
• CHECK_FEEDBACK
• Blank

Table 6-4 describes each execution-mode option.

Description

To invoke AUTOGEN, use the following syntax to enter a command at the DCL command prompt:

$ @SYS$UPDATE:AUTOGEN [start-phase] [end-phase] [execution-mode]

You are returned to DCL level when the command has finished processing unless you specify SHUTDOWN or REBOOT as the end-phase parameter.

7.1 BACKUP Description

When you save files with BACKUP, it writes the files to a special file called a save set. Save sets are written in a format that only BACKUP can interpret. (A save set stored on a Files--11 disk is a standard OpenVMS file, however, and can be copied, renamed, deleted, or backed up. A save set stored on magnetic tape should only be processed with the BACKUP command; do not use the DCL command COPY to copy a magnetic tape save set to disk.)

Use BACKUP to perform the following tasks:

• Save disk files to a BACKUP save set.
• Restore files to disk from a BACKUP save set.
• Copy disk files to disk files.
• Compare disk files created by BACKUP or files in a BACKUP save set with disk files.
• List information about the files in a BACKUP save set.
• Create and list journal files that record the results of BACKUP save operations.
• Convert ODS-5 file names to ODS-2 file names.

For specific information about performing these tasks, refer to the HP OpenVMS System Manager's Manual.

Using BACKUP also eliminates disk fragmentation. Fragmentation can occur as you create and extend files on a disk. If the file system cannot store files in contiguous blocks, it stores them in noncontiguous pieces. Eventually, the disk can become severely fragmented and system performance suffers. To eliminate fragmentation, perform an image backup of the disk and restore the backup copy. When you restore the image backup, BACKUP places the files on the disk contiguously.

Besides backing up your own files, directories, and disks, remember to back up your OpenVMS system disk. Depending on the policy at your site, individuals may be responsible for backing up their system disks, or an operator or system manager may perform the backup (as would likely be the case in a large, clustered computer system).

The two ways to back up your system disk are:

• If you have access to the OpenVMS Alpha or VAX system CD-ROM, you can use a menu system supplied on the CD-ROM to back up your system disk.
• If you do not have access to the OpenVMS VAX system CD-ROM, you must use standalone BACKUP to back up your system disk (VAX only).

Refer to the HP OpenVMS System Manager's Manual for more information about standalone BACKUP and the menu-driven procedure.

Types of backup operations are:

• An image backup (also called a full backup) saves a copy of all the files on a disk (or volume) to a save set. The first backup that you do on a disk must be an image backup; you cannot perform an incremental backup first.
• An image restore initializes the output disk and restores an entire volume.
• An image copy operation initializes the output disk and copies an entire volume; the image backup is a logical duplicate of the contents of the disk.
• An image compare operation compares the contents of entire volumes.

  Note Because an image copy or backup operation processes all files on the input volume, you cannot specify file-selection qualifiers for these operations. You can, however, restore files and directories selectively from an image save set.

  
  If the output volume of an image operation is a disk, BACKUP stores all files on the output volume contiguously, eliminating disk fragmentation and creating contiguous free blocks of disk space.
• An incremental backup saves only those files that have been created or modified since the most recent backup that was performed using the /RECORD qualifier. (The /RECORD qualifier records the date and time that the files are backed up.)
• An incremental restore operation restores an incremental save set. Specify the command qualifier /INCREMENTAL in an incremental restore operation.
• A file operation processes individual files or directories.
• A selective operation process files or volumes selectively, according to criteria such as version number, file type, UIC, date and time of creation, expiration date, or modification date.
  Perform selective save operations by using wildcard characters and input file-selection qualifiers (for example, /BACKUP, /BEFORE, /BY_OWNER (use instead of /OWNER_UIC), /CREATED, /EXCLUDE, /EXPIRED, /MODIFIED, and /SINCE).
• A physical operation copies, saves, restores, or compares an entire volume in terms of logical blocks, ignoring any file structure.

BACKUP allocates virtual memory to hold copies of the index file and storage bitmaps. With larger bitmaps, the virtual memory requirement of this utility increases correspondingly. To use BACKUP on volumes with large bitmaps, you might need to increase your page file quota. On OpenVMS VAX systems, you might also need to increase the system parameter VIRTUALPAGECNT.

Sizes of virtual memory requirements for the bitmaps are VAX pages (or Alpha 512-byte pagelets) per block of bitmap. For the BACKUP utility, the virtual memory requirement for the bitmaps is equal to the sum of the sizes of all index file bitmaps on the volume set. (Note that this memory requirement is in addition to the BACKUP utility's substantial buffer pool.)

The following sections describe the BACKUP command line format.

7.2 BACKUP Command Line Format

To perform BACKUP operations, enter the DCL command BACKUP in the following format:

BACKUP evaluates the input and output specifiers to determine which type of operation to perform. BACKUP also uses the input specifier to locate the input and directs output to the output specifier.

7.3 BACKUP Input and Output Specifiers

BACKUP can process several different types of input and output. Depending on the type of operation being executed, input and output specifiers can be standard OpenVMS file specifications, BACKUP save-set specifications, or device specifications. Device specifications can refer to disk or magnetic tape volumes.

You can specify any valid OpenVMS file specification as BACKUP input or output specifiers; however, BACKUP does not allow node names in BACKUP file specifications. You can use wildcard characters, and you can list multiple file specifications as input to a single BACKUP operation.

A BACKUP save-set specification is the file specification of a BACKUP save set. When you use BACKUP to save files or volumes, BACKUP writes your files to a save set. You can specify the save set as input to other BACKUP operations. When specifying a save set, follow the rules for specifying a OpenVMS file. The OpenVMS User's Manual describes valid specifications for disk files; the HP OpenVMS System Manager's Manual explains the rules for specifying magnetic tape files. A save-set specification has no default file type, although you can use BCK or SAV.

The save-set name can be any valid OpenVMS file name and type. However, when you create a save set on magnetic tape, the save-set name has the following restrictions:

• The entire save-set name cannot exceed 17 characters, including the period delimiter.
• You cannot specify a version number.
• You cannot specify a directory name.

Device specifications used as BACKUP input or output specifiers follow the conventions for specifying devices outlined in the OpenVMS User's Manual.

By default, BACKUP treats an input or output specifier referring to a Files--11 disk as a file specification. Therefore, to identify a save set on a Files--11 volume, you must include the /SAVE_SET qualifier with the specifier (see /SAVE_SET). BACKUP treats input and output specifiers referring to magnetic tape as save sets.

Table 7-1 shows input and output specifiers for each type of BACKUP operation.

An element list is a list of arguments specified with a command or qualifier. The arguments, or elements, in the list are separated by commas. Element lists relating to input or output specifiers are allowed only in the following circumstances:

• If an input specifier refers to a Files--11 disk, you can construct lists from standard OpenVMS file specifications, as follows:

  $ BACKUP _From: DUA0:[DATA]A.DAT,B.DAT,[PROGRAMS]TEST.EXE _To: MSA0:TEST.SAV/LABEL=DLY101

• If an input specifier or an output specifier refers to a BACKUP save set on magnetic tape or sequential disk, you can specify more than one device name to be used in the operation. This allows you to process multivolume save sets efficiently by specifying the order in which devices will be used. The first volume is processed until it is full. The second (or subsequent) volume is processed while the media in the first (or previous) volume is being changed. However, the save-set name must appear with the first element in the list and must not appear in subsequent elements in the list.
  In the following example, BACKUP first saves data to a tape in drive MSA0, then to a tape in drive MSA1. When the tape in drive MSA1 is full, BACKUP saves data to a fresh tape in MSA0.

  $ BACKUP _From: DUA0:[DATA]*.*,DUA0:[PROGRAMS]*.* _To: MSA0:TEST.SAV,MSA1:/LABEL=WKLY01

• If you are performing an image operation on a volume set, you can specify element lists in the input and output specifiers. In the following example, BACKUP first restores the save set TEST.SAV from the tape in drive MSA0, and then continues to restore the save set from the tape in drive MSA1. BACKUP first restores this save set to DUA0. When DUA0 is full, BACKUP continues the restore operation to DUA1.

  $ BACKUP/IMAGE _From: MSA0:TEST.SAV,MSA1: _To: DUA0:[DATA...],DUA1:

You can also affect BACKUP operations by specifiying qualifiers. BACKUP has five types of qualifiers:

• Command qualifiers modify the default action of a BACKUP command. You can place command qualifiers anywhere in the command line. Command qualifiers act upon every file in the input or output specifier.
• Input file-selection qualifiers select files from the input specifier. Place them immediately after the input specifier.
• Input save-set qualifiers affect the way BACKUP handles an input save set during a restore or compare operation. Place them immediately after the input specifier.
• Output file qualifiers change the way output files are restored. Place them immediately after the output specifier.
• Output save-set qualifiers affect the way BACKUP processes an output save set during a save operation. Place them immediately after the output specifier.

It is important to understand the differences between the types of qualifiers. The position of qualifiers in the BACKUP command line affects the results of the command. Although command qualifiers can be placed anywhere in the command line, input- and output-specifier qualifiers are position-dependent. That is, input-specifier qualifiers must be placed immediately after the input specifier, and output-specifier qualifiers must be placed immediately after the output specifier.

Additionally, several BACKUP qualifiers are both input-specifier qualifiers and output-specifier qualfiers. To achieve the results you want from a BACKUP command, ensure that you place position-dependent qualifiers correctly. For example, use the /SAVE_SET qualifier as an output save-set qualifier in a BACKUP save operation and as an input save-set qualifier in a BACKUP restore operation.

Appendix G contains more information about valid combinations of BACKUP qualifiers.

7.3.3 Using Wildcard Characters with BACKUP

BACKUP allows you to use wildcard characters in file specifications to represent directories, file names, file types, and version numbers. Omitted file names, file types, or version numbers are assumed to be the asterisk wildcard character (*). For instance, if you omit the version number, BACKUP processes all versions. (For introductory information about wildcard characters, refer to the OpenVMS User's Manual.)

You can use any valid DCL wildcard character with input specifiers that are Files--11 media or with the /SELECT and /EXCLUDE qualifiers. Note, however, that the symbols denoting the latest versions of files (;) and relative versions of files (;-n) are processed as the asterisk wildcard character (;*) when they are used with the /EXCLUDE and /SELECT qualifiers.

You cannot use wildcard characters in BACKUP save-set specifications unless the save sets are input specifiers on tape.

Using Wildcard Characters to Represent Directories

The following table lists the types of directory wildcards allowed for output specifiers that are Files--11 media:

The following example uses the directory wildcard format [directory...] for both the input and the output specifiers:

$ BACKUP [OSCAR...] [JOE.RECEIVED...]

In this example, BACKUP creates a directory named [JOE.RECEIVED] (if it does not already exist) as well as subdirectories that correspond to the subdirectories of [OSCAR]. BACKUP copies all files from the directory [OSCAR] and its subdirectories to [JOE.RECEIVED] and its subdirectories. If [OSCAR] has 8 levels of directories, however, and files in it are ODS-2, BACKUP is unable to create a corresponding 9-level subdirectory to [JOE.RECEIVED]; the 8-level subdirectory to [OSCAR] is not copied. (This restriction does not apply to ODS-5 files.)

If you use the asterisk wildcard character (*) to represent subdirectories in the input specifier of a copy operation, BACKUP creates subdirectories to the directory specified in the output specifier that correspond to the subdirectories in the input specifier. BACKUP then copies all files from the lowest level subdirectory in the input specifier to the lowest level subdirectory in the output specifier. In the following example, the asterisk represents subdirectories named MONDAY and TUESDAY:

$ BACKUP [SAM.WORK.*.WEDNESDAY] [JAMES...]

In this example, BACKUP creates a subdirectory named [JAMES.MONDAY.TUESDAY.WEDNESDAY]. In doing so, BACKUP copies the file MONDAY.DIR to [JAMES], copies the file TUESDAY.DIR to [JAMES.MONDAY], and copies the file WEDNESDAY.DIR to [JAMES.MONDAY.TUESDAY]. Then BACKUP copies all files from [SAM.WORK.MONDAY.TUESDAY.WEDNESDAY] to [JAMES.MONDAY.TUESDAY.WEDNESDAY].

In a restore operation, the input specifier defaults to [*...] if the input save-set qualifier /SELECT is not used; this is important if you use the form [directory...] in the output specifier. The function of the wildcard [*...] is to carry over the entire directory name from the first level on and to place it before the ellipsis in the output specifier. Thus, if the save set in the following example contains the directory tree [SAVE...], the restored directory tree will be [WORK.SAVE...]:

$ BACKUP MTA0:SAVE.BCK [WORK...]

Note that the result will be the same, even if your output specifier has the same name as the directory in the input specifier, as shown in the following example:

$ BACKUP MTA0:SAVE.BCK [SAVE...]

The preceding command restores the directory tree [SAVE...] to a directory tree named [SAVE.SAVE...].

The following command restores the directory tree [SAVE...] to a directory tree named [WORK...]:

$ BACKUP MTA0:SAVE.BCK/SELECT=[SAVE...] [WORK...]

There are two ways to retain the original directory name when you restore files. You must either use the form [*...] for the output specifier, or you must specify the input save-set qualifier /SELECT. The following example uses the form [*...] in the output specifier to restore the directory tree [SAVE...] in save set SAVE.BCK to the directory tree [SAVE...]:

$ BACKUP MTA0:SAVE.BCK [*...]

The input save-set qualifier /SELECT causes only the ellipsis portion of the selected file specification to be carried over to the directory tree named in the output specifier [directory...]. The following command restores [SAVE...] to [SAVE...]:

$ BACKUP MTA0:SAVE.BCK/SELECT=[SAVE...] [SAVE...]

By duplicating files or volumes of files, the Backup utility (BACKUP) protects data from loss or corruption.

BACKUP is intended for use primarily by system managers and operators to protect public media. However, anyone can use BACKUP to make personal BACKUP copies and to transport files between OpenVMS systems.

The two ways to back up your system disk are:

• If you have access to the CD-ROM of the current version of OpenVMS Alpha or VAX, you can use a menu-driven procedure to back up your system disk.
• If you do not have access to the CD-ROM of the current version of OpenVMS Alpha or VAX, you must use standalone BACKUP to back up your system disk. Standalone BACKUP is a version of the Backup utility that is bootstrapped into main memory instead of running under the control of the OpenVMS VAX operating system. Standalone BACKUP uses a subset of BACKUP qualifiers to perform image and physical BACKUP operations.

Format

BACKUP input-specifier output-specifier

Parameters

input specifier

Specifies the input for the BACKUP operation. The input specifier can be a standard OpenVMS file specification, a BACKUP save-set specification, or a device name. If the input specifier is a save-set specification on disk, it must include the input save-set qualifier /SAVE_SET.

DECnet node names are allowed only in save-set specifications.

Wildcards are permitted in standard OpenVMS file specifications and in save-set specifications if they are on magnetic tape.

output specifier

Specifies the output for the BACKUP operation. The output specifier, like the input specifier, can be either a standard OpenVMS file specification, a BACKUP save-set specification, or a device name. If the output specifier is a save set on disk, it must include the output save-set qualifier /SAVE_SET.

DECnet node names are allowed only in save-set specifications.

You can use wildcard characters if the output specifier is a Files--11 volume. You cannot use wildcard characters if the output specifier is a BACKUP save set or a volume created by a BACKUP/PHYSICAL or BACKUP/IMAGE operation. Refer to Section 7.3.3 for restrictions on the use of wildcard characters in BACKUP commands.

Description

To invoke online BACKUP, enter an appropriate BACKUP command at the DCL prompt. For instructions on invoking standalone BACKUP, refer to the HP OpenVMS System Manager's Manual.

When you enter a BACKUP command, BACKUP evaluates the input and output specifier and qualifiers to determine the type of operation to perform. BACKUP uses the input specifier to locate the input to the utility and directs output to the output specifier, which can be a file or a save set on disk or a save set on magnetic tape.

After executing the command, BACKUP returns to DCL command level. If you want to halt the execution of a BACKUP command prematurely, press Ctrl/Y. If BACKUP is creating a file when you press Ctrl/Y, the file is closed immediately and only partially created.

You need the user privilege TMPMBX to send messages to operator terminals when using BACKUP in batch mode. If you are performing a save operation to a volume set of sequential disks, you must have the user privilege PHY_IO or LOG_IO to write to a continuation volume. The use of several BACKUP qualifiers also requires privileges; these are noted in the appropriate qualifier descriptions.

This section describes and provides examples of each BACKUP qualifier. Make sure that you understand how the position of BACKUP qualifiers affects BACKUP operations. See Section 7.2 for information about the BACKUP command line format. Table 7-2 summarizes the BACKUP qualifiers.

Command Qualifier

Specifies that the previous behavior of multiple processing of alias and primary file entries be maintained.

Description

The /ALIAS qualifier maintains the previous BACKUP behavior of treating alias file entries the same as primary file entries. Therefore, a primary file may be processed multiple times by BACKUP if one or more alias file entries reference the same primary file entry.

If you specify /NOALIAS, alias directory and file entries are ignored. Therefore, multiple processing of primary files may be avoided, which saves time and save-set file space. If a restore operation is performed using the /ALIAS qualifier but the save set was created by using the /NOALIAS qualifier, a message is displayed that the /ALIAS qualifier will be ignored.

Format

/ALIAS save-set-spec (default)

/NOALIAS

Command Qualifier

Allows operator or user intervention during a BACKUP operation if a magnetic tape mount request fails or if an operation requires another volume.

Format

/[NO]ASSIST input-specifier output-specifier

Description

The /ASSIST qualifier causes BACKUP to send messages to operator terminals when a failure occurs during a BACKUP mount request or when an operation requires another volume. BACKUP sends messages to operator terminals enabled to receive TAPES and CENTRAL messages. (See the description of the REPLY command in the HP OpenVMS DCL Dictionary for information about enabling and disabling operator terminals.) If a failure occurs, the operator can either abort the operation or correct the error condition and allow the operation to continue.

If no operator terminal is enabled to receive TAPES and CENTRAL messages and to respond to a mount assist request, a message is displayed informing the user of the situation. If a volume is placed in the requested drive, no additional operator response is necessary. Any operator reply to a mount request is written to SYS$OUTPUT. When BACKUP is run interactively, SYS$OUTPUT is the user's terminal. When BACKUP is run in batch mode, SYS$OUTPUT is the batch job log file.

If you specify /NOASSIST, mount messages appear on your terminal and are not sent to the operator.

The default is /ASSIST. The /NOASSIST qualifier has no effect if the logical name SYS$COMMAND points to a device that is not a terminal (as is the case when you run BACKUP in a batch job). Specifying /NOASSIST when BACKUP is run in batch mode has no effect.

Example

$ BACKUP/NOASSIST [PAYROLL]*.*;* MTA1:PAYROLL.BCK/LABEL=WKY101
      

This command mounts the volume labeled WKY101 on the MTA1 tape drive and copies all files in the [PAYROLL] directory to a save set named PAYROLL.BCK. The /NOASSIST qualifier directs BACKUP to send mount messages to your terminal rather than to the operator terminal. The WKY101 label indicates that WKY101 is a weekly BACKUP tape in group 1, volume number 01. (If the volume label of the tape is not WKY101, you can direct BACKUP to write the save set to the tape by choosing the OVERWRITE option at the BACKUP> prompt.)

Input File-Selection Qualifier

Selects files according to the BACKUP date written in the file header record by the BACKUP/RECORD command.

Format

input-specifier/BEFORE=time/BACKUP output-specifier

input-specifier/SINCE=time/BACKUP output-specifier

Description

The /BACKUP qualifier is valid with Files--11 Structure Levels 2 and 5 volumes only and must be used with either the /BEFORE or /SINCE qualifier. You cannot use /BACKUP with the /CREATED, /MODIFIED, or /EXPIRED qualifiers in an image operation or in a physical operation.

The /BACKUP qualifier selects files by comparing the date and time recorded in the BACKUP field of the file header record with the date and time specified with the /BEFORE or /SINCE qualifier. The date and time recorded in the file header record is the date and time the file was last saved or copied using the /RECORD command qualifier.

When you use /BACKUP with /BEFORE, files with a BACKUP date prior to the specified date or time are selected. Files with no BACKUP date (that is, /RECORD was not specified when the file was saved or copied) are also selected.

When you use /BACKUP with /SINCE, files with a BACKUP date equal to or later than the specified date or time are selected. Files with no BACKUP date (that is, /RECORD was not specified when the file was saved or copied) are not selected.

Examples

$ BACKUP/RECORD
_From: [PAYROLL]*.*;*/BEFORE=01-SEP-2002/BACKUP
_To: MTA1:SEP01.BCK
      

In this command, the /BACKUP qualifier combined with the /BEFORE qualifier saves all versions of all files in the directory [PAYROLL] that have a BACKUP date written before September 1, 2002. The command qualifier /RECORD writes the date and time of the save operation to the file header record of each saved file.

$ BACKUP/RECORD [ACCOUNTS...]/SINCE=YESTERDAY/BACKUP MTA1:ACC.BCK

      

In this command, the /BACKUP qualifier combined with the /SINCE qualifier saves all files in all subdirectories of [ACCOUNTS] that have a BACKUP date written since yesterday (24 hours before midnight last night). The command qualifier /RECORD writes the date and time of the save operation to the file header record of each saved file.

Input File-Selection Qualifier

Selects files dated earlier than the date and time you specify.

Format

input-specifier/BEFORE=time output-specifier

Description

The /BEFORE qualifier selects files by comparing the date and time in the specified field of each file header record with the date and time you specify in the command line. The following list shows the other input file-selection qualifiers (and their functions) that you can use with the /BEFORE qualifier. Use these other qualifiers only one at a time in your command line.

/BACKUP	Selects files last saved or copied by BACKUP/RECORD before the date specified. Also selects files with no BACKUP date.
/CREATED	Selects files created before the date specified.
/EXPIRED	Selects files that have expired as of the date specified.
/MODIFIED	Selects files last modified before the date specified. If you specify /BEFORE without another qualifier, /MODIFIED is used by default.

Specify the date and time as a delta time or as an absolute time using the format [dd-mmm-yyyy[:]][hh:mm:ss.cc]. You can also use one of the following reserved words to specify the date and time:

BACKUP	The BACKUP date of the file written by a previous BACKUP/RECORD operation (available only on Files--11 Structure Levels 2 or 5 volumes)
TODAY	The current day, month, and year at 00:00:00.0 o'clock
TOMORROW	24 hours after midnight last night
YESTERDAY	24 hours before midnight last night

The /BEFORE qualifier is not valid in incremental restore operations.

Example

$ BACKUP [POLICIES]*.*;*/BEFORE=TODAY/EXPIRED  DMA1:OLDPOL.BCK/SAVE_SET
      

This command saves all files in the directory [POLICIES] that have expiration dates preceding today's date.

Output Save-Set Qualifier

Specifies the output block size in bytes for data records in a BACKUP save set.

Format

input-specifier output-save-set-spec/BLOCK_SIZE=n

Description

You can specify a block size between 2048 and 65,535 bytes. BACKUP may adjust this value according to the constraints of the BACKUP format. Although BACKUP may adjust the block size you specify, it does not adjust the block size over the maximum of 65,535.

If you specify /BLOCK_SIZE in a magnetic tape save operation, BACKUP ignores any block size defined by the /BLOCK_SIZE qualifier to the DCL command MOUNT.

If the block size is set to a large value for a save set on magnetic tape, it is possible for the magnetic tape to run off its reel or for a large number of write errors to be logged. If this occurs, avoid using large block sizes. If the problem recurs with the same magnetic tape, avoid using that tape for future BACKUP operations.

The default block size for magnetic tape is 8192 bytes; the default for disk is 32,256 bytes.

Example

$ BACKUP/RECORD DRA2:[LEE...]/SINCE=BACKUP MTA0:SAVEWORK.BCK/BLOCK_SIZE=10000
      

This command saves a directory tree on DRA2 to a magnetic tape mounted on drive MTA0. The input file-selection qualifier /SINCE=BACKUP instructs BACKUP to process only those files in the specified directory tree that have been modified since the last BACKUP/RECORD operation. The output save-set qualifier /BLOCK_SIZE directs BACKUP to assign a block size of 10,240 (BACKUP rounds the specified block size of 10,000 up to the next multiple of 512).

Command Qualifier

Lists the file specification, size, and creation date for each file in the save set. (The size listed is the actual size of the file saved, rather than the number of blocks allocated to the file.) The /BRIEF qualifier is valid only with the /LIST qualifier and is the default format for BACKUP listings. Specify the /FULL qualifier to list the information in a format similar to that displayed by the DCL command DIRECTORY/FULL.

Format

/LIST/BRIEF save-set-spec

Example

$ BACKUP/LIST/BRIEF DBA2:[SAVE]23MAR02.BCK/SAVE_SET

Listing of save set(s)

Save set:          23MAR02.BCK
Written by:        MOROCI
UIC:               [000200,000200]
Date:              23-MAR-2002 14:18:16.00
Command:           BACKUP [SAVE] DBA2:[SAVE]23MAR02.BCK/SAVE_SET

Operating system:  OpenVMS Alpha Version 7.3-1

BACKUP version:    V7.3-1
CPU ID register:   08000000
Node name:         _SUZI::
Written on:        _DBA2:
Block size:        32,256
Group size:        10
Buffer count:      3

[SAVE]INFO.TXT;4                  5   4-FEB-2002 13:12
[SAVE]LAST.DAT;1                  1  18-JAN-2002 14:11
[SAVE]WORK.DAT;3                 33   1-JAN-2002 10:02

Total of 3 files, 39 blocks
End of save set

      

This command lists the BACKUP summary information and the file name, size, and creation date for each file in the save set. Note that the input save-set qualifier /SAVE_SET is required to identify the input specifier as a save set on a Files--11 medium.

Command Qualifier

This qualifier is obsolete. You can still specify the /BUFFER_COUNT qualifier, although it has no effect. (This ensures that command procedures containing this qualifier will still operate correctly.) HP recommends that you remove the /BUFFER_COUNT qualifier from command procedures.

Input File-Selection Qualifier

Selects files for processing according to the user identification code (UIC).

Format

input-specifier/BY_OWNER[=[uic]] output-specifier

Description

If you specify /BY_OWNER without a UIC, BACKUP selects all files whose UIC matches that of the current process.

Specify either a numeric UIC as octal numbers or an alphanumeric UIC in the form [g,m]. Wildcards are permitted. Note that the brackets are required.

[g,m]

g	An octal number in the range 0 to 37776 representing the group number or an alphanumeric group name
m	An octal number in the range 0 to 177776 representing the member number or an alphanumeric member name

If you do not specify /BY_OWNER, BACKUP processes all files specified by the input specifier.

Examples

$ BACKUP [SNOW...]/BY_OWNER MT$DRIVE:SNOW.BCK/LABEL=TAPE01
      

In this example, BACKUP mounts the tape with the label TAPE01 on drive MT$DRIVE and saves all files in the directory and subdirectories of [SNOW] with the UIC of the current default process to the save set SNOW.BCK.

$ BACKUP [SUNDANCE]/BY_OWNER=[727,46]  DBA1:STABLE.BCK/SAVE_SET
      

In this example, all files in the directory [SUNDANCE] with an owner UIC of [727,46] are saved to the sequential-disk save set STABLE.BCK on DBA1.

Output File Qualifier

Redefines the owner user identification code (UIC) for restored files.

Format

input-specifier output-specifier/BY_OWNER[=option]

Description

The following options are available:

DEFAULT	Sets the owner UIC to the user's current default UIC. This option is the default if you do not specify the /BY_OWNER qualifier, except in image and incremental restore operations, when ORIGINAL is the default option.
ORIGINAL	Retains the owner UIC of the file being restored. This option is the default if you specify the /BY_OWNER qualifier with no option. This option is also the default for incremental restore operations. To use this option, the UIC must be yours, or you must have the SYSPRV user privilege or be the owner of the output volume.
PARENT	Sets the owner UIC to the owner UIC of the directory to which the file is being restored or copied. To use this option, the parent UIC must be yours, or you must have the SYSPRV user privilege or be the owner of the output volume.
[uic]	Sets the owner UIC to the UIC specified. Use the [g,m] format (as described in the input file-selection qualifier /BY_OWNER). To use this option, the UIC must be yours, or you must have the SYSPRV user privilege or be the owner of the output volume.

In restore operations where the command qualifier /IMAGE or /INCREMENTAL is specified, the default is /BY_OWNER=ORIGINAL.

Example

$ BACKUP DBA2:ACCOUNTS.BCK/SAVE_SET
[CLEAVER...]/BY_OWNER=PARENT
      

In this example, the sequential-disk save set ACCOUNTS.BCK is restored to the directory tree [CLEAVER...], assigning each restored file the owner UIC of the [CLEAVER] directory.

Output Save-Set Qualifier

Specifies the owner user identification code (UIC) of the save set.

Format

input-specifier output-save-set-spec/BY_OWNER=uic

Description

If the /BY_OWNER qualifier is omitted, the UIC of the current process is used. To use this qualifier on Files--11 save sets, you need the user privilege SYSPRV, or the UIC must be your own.

Specify either a numeric UIC as octal numbers or an alphanumeric UIC in the form [g,m]. Wildcards are permitted. Note that the brackets are required.

[g,m]

g	An octal number in the range 0 to 37776 representing the group number or alphanumeric group name
m	An octal number in the range 0 to 177776 representing the member number or alphanumeric member name

Example

$
BACKUP [CLEAVER...] MFA2:ACCOUNTS.BCK/BY_OWNER=[301,310]/LABEL=TAPE01
      

In this example, BACKUP mounts the tape with the label TAPE01 on drive MFA2. Next, BACKUP saves the directory tree [CLEAVER...] to a save set named ACCOUNTS.BCK. The output save-set qualifier /BY_OWNER assigns an owner UIC of [301,310] to the save set.

Output Save-Set Qualifier

Places a comment in an output save set. If the comment string is longer than one word or if it contains nonalphanumeric characters, you must enclose it in quotation marks (" "). A DCL command can contain a maximum of 1024 characters.

Format

input-specifier output-save-set-spec /COMMENT=string

Example

$ BACKUP [REMARKS] DMA1:20JULREM.BCK/SAVE_SET -
_$ /COMMENT="Remote operations for July 20, 2002"
$ BACKUP/LIST DMA1:20JULREM.BCK/SAVE_SET
Listing of save set

Save set:          20JULREM.BCK
Written by:        WALRUS
UIC:               [360,054]
Date:              20-JUL-2002 15:22:06.62
Command:           BACKUP [REMARKS] DMA1:20JULREM.BCK/SAVE_SET/COMMENT=Remote
operations for July 20, 2002

Operating system:  OpenVMS Alpha Version V7.3-1

BACKUP version:    V7.3-1
CPU ID register:   0138084C
Node name:         _ABBEY::
Written on:        _ABBEY$DMA1:
Block size:        32256
Group size:        10
Buffer count:      3

[REMARKS]BAC.RES;1                                       2  20-JUL-2002 14:13
[REMARKS]COM.LIS;1                                       1  20-JUL-2002 14:04
[REMARKS]DTOP.DIR;1                                      1  20-JUL-2002 14:18
.
.
.
Total of 40 files, 535 blocks
End of save set

      

The first BACKUP command saves the directory [REMARKS] to a sequential-disk save set and records a comment. The BACKUP/LIST command displays the contents of the newly created save set. Note that the /SAVE_SET qualifier is required when creating a save set on disk.

Command Qualifier

Compares the save set, device, file, or files specified by the first parameter with the contents of the Files--11 device, file, or files specified by the second parameter and displays an error message if it finds a difference.

Format

/COMPARE file-spec file-spec

/COMPARE save-set-spec file-spec

/IMAGE/COMPARE device-spec device-spec

/IMAGE/COMPARE save-set-spec device-spec

/PHYSICAL/COMPARE device-spec device-spec

/PHYSICAL/COMPARE save-set-spec device-spec

Description

In a BACKUP compare operation, the first parameter can be a Files--11 file or a wildcard character representing a set of files, a BACKUP save set on disk or magnetic tape, a tape device, or a disk device. The second parameter must be a Files--11 disk file, a wildcard character representing a set of files or a Files--11 disk device, unless you specify the command qualifier /PHYSICAL. When you specify /PHYSICAL, and the first parameter specifies a disk device, both disks in the compare operation must be mounted with the /FOREIGN qualifier.

BACKUP displays the following error message if it encounters a difference between files it compares:

%BACKUP-E-VERIFYERR, verification error for ...

Use the /COMPARE qualifier to compare a save set with original files or to compare files or volumes copied using BACKUP with original files. Because BACKUP processes files by blocks, comparing files not produced by BACKUP is likely to cause mismatch errors in files that are apparently identical.

If you do not specify a version number with the file specification, the default is ;* (the asterisk wildcard character), which processes all versions of the file.

Both parameters in a compare operation are input specifiers.

If you are comparing two entire Files--11 volumes, use an image compare operation, as follows:

$ BACKUP/IMAGE/COMPARE DBA1: DBA2:

You cannot use the command qualifier /DELETE or /RECORD in compare operations.

Do not perform compare operations on files that were restored or copied using the output file qualifier /NEW_VERSION because this qualifier causes version numbers to change.

Examples

$ BACKUP/COMPARE JAZZ.DAT BLUES.DAT
      

This example compares two Files--11 files. Because no version number is specified, BACKUP compares all versions of each file.

$ BACKUP/COMPARE/IMAGE MTA0:SWING.BCK DBA2:
      

This example compares an image save set stored on magnetic tape and a Files--11 volume.

Input File-Selection Qualifier

Displays prompts on your terminal for confirmation before processing each file. If you want the file to be processed, enter Y or YES and press Return.

Format

input-specifier/CONFIRM output-specifier

Example

$ BACKUP *.LIS/CONFIRM/LOG  DLA2:LIST.BCK/SAVE_SET
DISK$DEFAULT:[WONDER]CRE.LIS;1, copy? (Y or N): Y
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]CRE.LIS;1
DISK$DEFAULT:[WONDER]CRETIME.LIS;1, copy? (Y or N): Y
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]CRETIME.LIS;1
DISK$DEFAULT:[WONDER]EXC.LIS;1, copy? (Y or N): Y
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]EXC.LIS;1
DISK$DEFAULT:[WONDER]REB.LIS;1, copy? (Y or N): N
DISK$DEFAULT:[WONDER]SETREB.LIS;1, copy? (Y or N): Y
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]SETREB.LIS;1
DISK$DEFAULT:[WONDER]VERS.LIS;1, copy? (Y or N): N
.
.
.
$
      

This command locates all files with a file type of .LIS and prompts for confirmation before saving each file to LIST.BCK on DLA2. The command qualifier /LOG displays information about each file as it is processed. Note that you must use the output save-set qualifier /SAVE_SET when creating a save set on disk.

Input File-Selection Qualifier

Converts ODS-5 file names to ODS-2 file names. To preserve the output volume as ODS-2, you must also use the /NOINIT qualifier.

Be aware that all ODS-5 file attributes are lost if you convert from an ODS-5 file name to an ODS-2 file name.

Format

input-specifier/CONVERT output-specifier

Example

$ BACKUP/LOG/CONVERT/IMAGE DKA500: DKA200:[000000]IMAGE.BCK/SAVE
      

The command in this example creates an ODS-2 image save set from an ODS-5 disk. The save set can be read by a system running a version of OpenVMS prior to Version 7.2.

Input Save-Set Qualifier

Specifies that the software cyclic redundancy check (CRC) is to be performed.

Format

input-save-set-spec/[NO]CRC output-specifier

Description

The default is /CRC. To disable CRC checking, specify /NOCRC; note that use of /NOCRC reduces processing time but increases the risk of data loss.

Example

$ BACKUP MTA2:988SAVE.BCK/NOCRC []
      

This command restores the save set 988SAVE.BCK to the current default directory, indicated by ([]); the input save-set qualifier /NOCRC disables CRC.

Output Save-Set Qualifier

Specifies whether the software cyclic redundancy check (CRC) is to be computed and stored in the data blocks of the output save set.

Format

input-specifier output-save-set-spec/[NO]CRC

Description

The default is /CRC. To disable checking, use /NOCRC; note that use of /NOCRC reduces processing time but increases the risk of data loss.

Example

$ BACKUP/RECORD []/SINCE=BACKUP MTA2:988SAVE.BCK/NOCRC
      

This command saves all files in the current default directory that have been created or modified since the last BACKUP/RECORD operation to the save set 988SAVE.BCK; the output save-set qualifier /NOCRC disables cyclic redundancy checking.

Input File-Selection Qualifier

Selects files according to the value of the creation date field in each file header record.

Format

input-specifier/BEFORE=time/CREATED output-specifier

input-specifier/SINCE=time/CREATED output-specifier

Description

You must use either the /BEFORE qualifier or the /SINCE qualifier with /CREATED. The date and time you specify with /BEFORE or /SINCE determine which files should be processed.

You cannot use /CREATED with the /BACKUP, /MODIFIED, or /EXPIRED qualifiers.

Example

$ BACKUP *.SDML/SINCE=YESTERDAY/CREATED DLA2:[SAVEDIR]/SAVE_SET
      

The command in this example saves all files with a file type of .SDML created since yesterday (24 hours before midnight last night).

Command Qualifier

Specifies that a BACKUP save or copy operation is to delete the selected input files from the input volume after all files have been successfully processed.

Format

/DELETE file-spec save-set-spec

Description

The /DELETE qualifier is valid only when used in a BACKUP save or copy operation. You must have sufficient privilege to delete files; if you do not, files protected against deletion are not deleted. If you use the command qualifier /VERIFY with /DELETE, files that fail verification are not deleted.

You cannot use /DELETE with the /PHYSICAL, /RECORD or /COMPARE command qualifiers.

Examples

$ BACKUP/DELETE BOP.DAT MTA0:BOP.BCK/LABEL=DANCE
      

In this example, the file BOP.DAT will be deleted after the save set BOP.BCK is successfully created on MTA0.

$ BACKUP/VERIFY/DELETE RAY.DAT,JOE.DAT,ELLA.DAT MTA0:OSCAR.BCK/LABEL=FRIEND
      

The BACKUP command deletes the selected list of files in this example after saving them to OSCAR.BCK on MTA0 and comparing the output save set with the input files. If BACKUP detects a difference between the contents of the output save set and the input file, the input file is not deleted.

Output Save-Set Qualifier

Specifies the recording density of the output magnetic tape. Use a value that is supported by the magnetic tape drive.

If you do not specify the /DENSITY qualifier, the default density is the current density of the magnetic tape drive. You must specify the output save-set qualifier /REWIND with /DENSITY.

Format

input-specifier output-save-set-spec/DENSITY=keyword

The following table shows shows the densities that are supported for tapes.

Note that tape density keywords cannot be abbreviated.

Description

The value that you specify must be supported by your magnetic tape hardware. If you omit this qualifier, the default density is the current density on the output tape drive.

The /DENSITY qualifier is incompatible with the output save-set qualifier /NOREWIND. You must specify the output save-set qualifier /REWIND to initialize the magnetic tape when using the /DENSITY qualifier. When you specify /DENSITY/REWIND, BACKUP rewinds the tape to the beginning-of-tape. Then BACKUP initializes the tape with the new density, removing access to all data that previously resided on the tape.

Example

$ BACKUP *.PAS MTA2:SAVEPAS.BCK/DENSITY=1600/REWIND/LABEL=PASCAL
      

The magnetic tape on drive MTA2: is initialized. All files with a file type of .PAS in the current default directory are saved to the save set SAVEPAS.BCK. The /DENSITY qualifier sets the recording density to 1600 bits/in.

Output Save-Set Qualifier

Depending on the other qualifiers you specify on the command line, the /EXACT_ORDER qualifier allows you to perform the following actions:

• Specify the exact order of tape volume labels that you want to use in a BACKUP operation.
• Preserve the existing volume label on a tape.
• Prevent previous volumes of a multivolume save operation from being overwritten.

Format

input-specifier output-save-set-spec/EXACT_ORDER

Description

The /EXACT_ORDER qualifier allows you to perform the following actions:

• Specify the exact order of tape volume labels that you want to use in a BACKUP operation. You must use the /LABEL=(label1,label2,...) qualifier to specify the order of the labels. BACKUP continues the operation as long as the label of the tape in the drive matches the corresponding label on the command line. If you do not specify enough labels on the command line to complete the operation, BACKUP prompts you to enter a label for the tape in the drive.
• Preserve the existing volume label on a tape. If you do not use the /LABEL qualifier on the command line and the tape has an ANSI label, BACKUP uses the existing label.
• Prevent previous volumes of a multivolume save operation from being overwritten. BACKUP keeps track of the volume labels you have already used in the operation. If you accidently mount one of the previous volumes, BACKUP displays the following error message:

  %BACKUP-W-MOUNTERR, volume 1 on MKB100: was not mounted because its label does not match the one requested Volume with label TAPE1 was already used in this save operation. Specify option (QUIT or NEW tape) BACKUP>

Note the following restrictions when you use the /EXACT_ORDER output qualifier:

• If you use the /EXACT_ORDER qualifier, you cannot specify a label longer than six characters on the command line. If you specify a label longer than six characters, BACKUP displays the following error message:

  %BACKUP-F-INVQUAVAL, value 'label_name' invalid for /LABEL qualifier

• You cannot use the /IGNORE=LABEL_PROCESSING qualifier with the /EXACT_ORDER qualifier.
• If you use the /LABEL qualifier with the /EXACT_ORDER qualifier, you cannot specify duplicate labels.

The default is /NOEXACT_ORDER.

Examples

$ BACKUP/IMAGE/RECORD/VERIFY/NOASSIST
_From: DKA100:
_To: MKB100:MAR11.SAV/LABEL=(TAPE1,TAPE2,TAPE3)/EXACT_ORDER
      

This example uses the /EXACT_ORDER qualifier to specify the exact order of labels for the BACKUP operation. Note that if you specify the /ASSIST qualifier, BACKUP would display messages on the operator terminal. BACKUP performs the following actions:

1. Compares the volume label of the tape in MKB100: with the first label that you specified on the command line (TAPE1). If the labels match exactly, BACKUP begins the save operation. If the labels do not match or if the tape does not have an ANSI label, BACKUP displays the following message:

   %BACKUP-W-MOUNTERR, volume 1 on MKB100: was not mounted because its label does not match the one requested %BACKUP-W-EXLABEER, volume label processing failed because volume TAPE4 is out of order, Volume label TAPE1 was expected. Specify option (QUIT, NEW tape, OVERWRITE tape, USE loaded tape) BACKUP> OVERWRITE

   
   Depending on the option you specify, you can quit the backup operation (QUIT), dismount the old tape and mount a new one (NEW), overwrite the label and the data on the tape (OVERWRITE), or write the data to the tape using the loaded tape's label (USE).
2. When the operation fills the first tape, it displays the following message:

   %BACKUP-I-RESUME, resuming operation on volume 2 %BACKUP-I-READYWRITE, mount volume TAPE2 on MKB100: for writing. Respond with YES when ready:

3. When you load the second tape and enter YES, BACKUP compares the label of the second tape with the second label you specified on the command line (TAPE2) just as it did in step 1a.
4. Assuming the volume labels match, BACKUP continues processing until it completes the operation or runs out of volume labels. If you do not specify enough labels on the command line to complete the operation, BACKUP prompts you to enter a label for the tape in the drive as follows:

   %BACKUP-W-MOUNTERR, volume 4 on MKB100: was not mounted because the label was not specified Specify EXACT_ORDER label (up to 6 characters) BACKUP>

   
   BACKUP then compares the label on the tape with label you specify as described previously.

$ BACKUP/IMAGE/RECORD/VERIFY/NOASSIST
_From: DKA100:[TEST]
_To: MKB100:MAR11.SAV/EXACT_ORDER
      

Because this example does not use the /LABEL qualifier, BACKUP uses the existing label on the tape. If the tape does not have an ANSI label, and it is the first tape in the operation, BACKUP displays the following error message:

%BACKUP-F-NOTANSI, tape is not valid ANSI format

If the tape does not have an ANSI label, and is not the first tape in the operation, BACKUP displays the following error message prompting you to specify a label:

%BACKUP-W-MOUNTERR, volume 2 on MKB100: was not mounted because the label was not specified Specify EXACT_ORDER label (up to 6 characters) BACKUP>

Note BACKUP checks to make sure you specify a valid label. If the label is not valid (for example, longer than six characters), BACKUP displays an error message. In previous versions of the OpenVMS operating system, BACKUP truncated long volume labels.

Input File-Selection Qualifier

Excludes files that otherwise meet the selection criteria for a save or copy operation. The excluded files are not processed.

Format

input-specifier/EXCLUDE=(file-spec[,...]) output-specifier

Description

If you specify more than one file, separate the file specifications with commas and enclose the list in parentheses. Do not use a device specification when defining the files to be excluded. You can use most standard wildcard characters, but you cannot use wildcard characters denoting latest versions of files (;) or relative versions of files (;-n).

Note that BACKUP does not apply temporary file specification defaults within the list. Each file specification independently takes its defaults from the file specification [000000...]*.*;*.

If you specify directory files (files with the file type .DIR), your command is processed but the directory files are not excluded (they are processed). BACKUP uses directory files to facilitate incremental restore operations.

You cannot use the /EXCLUDE qualifier in image restore operations.

Example

$ BACKUP
_From: DRA2:[CONTRACTS]/BEFORE=TODAY/EXCLUDE=(*.OBJ,*.MAI)
_To: MFA0:CONTRACT.BCK/LABEL=DLY102
      

All files in the directory [CONTRACTS] that have a modification date prior to today (the current day, month, and year at 00:00:00.0 o'clock) are saved to the save set CONTRACT.BCK on drive MFA0, except for those with a file type of .OBJ or .MAI.

Input File-Selection Qualifier

Selects files according to the value of the expiration date field in each file header record.

Format

input-specifier/BEFORE=time /EXPIRED output-specifier

input-specifier/SINCE=time /EXPIRED output-specifier

Description

You must use the input file-selection qualifier /BEFORE or /SINCE with /EXPIRED. The date and time you specify to /BEFORE or /SINCE determines which files are processed.

You cannot use /EXPIRED with the input file-selection qualifiers /BACKUP, /MODIFIED, or /CREATED.

Example

$ BACKUP [CONTRACTS]/BEFORE=TOMORROW/EXPIRED MTA1:30DEC.BCK/LABEL=WK04
      

This command saves all files in the directory [CONTRACTS] that have an expiration date prior to tomorrow (24 hours after midnight last night) to a save set named 30DEC.BCK.

Command Qualifier

Processes the input specifier using a fast file scan to reduce processing time. The input specifier must be a Files--11 disk.

Format

/FAST input-specifier output-specifier

Description

The fast file scan reads the index file on the Files--11 disk specified by the input specifier and creates a table of files that match the qualifiers you specified.

When you use the /FAST qualifier to save a disk, ALIAS directory trees are not processed. Only the primary files that the ALIAS points to are saved. Depending on the number of ALIAS directory specifications there are on the disk, this may increase performance by reducing the number of files BACKUP checks for processing. A message is displayed for each ALIAS directory or file that is not processed.

To perform a fast file scan, you need write access to the INDEXF.SYS file on the input medium, or the input medium must be write-locked. This requirement is necessary because BACKUP opens the index file to synchronize with the file system, whether or not any update is made.

A fast file scan is most useful when the input specifier includes most of the files on the volume, and file-selection qualifiers (such as those that pertain to date or owner) specify a relatively small set of the files named. Because image operations implicitly use the fast file scan, the /FAST qualifier is ignored if used with the command qualifier /IMAGE.

You cannot use /FAST in restore operations.

Example

$ BACKUP/FAST
_From: DBA1:[*...]/MODIFIED/SINCE=TODAY
_To: MTA0:13NOVBAK.BCK,MTA1:/LABEL=WK201
      

In this example, all files on the disk DBA1 that have been modified today are saved to a multireel tape save set named 13NOVBAK.BCK. The /FAST qualifier is used to reduce processing time.

Input File-Selection Qualifier

Specifies a file that contains a list of the files that will be selected when a save set is restored.

Format

input-specifier /FILES_SELECTED=file-spec output-specifier

Description

The /FILES_SELECTED qualifier allows you to specify a file that contains a list of the files that are to be selected when a save set is restored. You can use this qualifier in place of the /SELECT qualifier to select files to restore from a save set.

Do not use a device specification when you list the files to be selected. In the list of files, enter one OpenVMS file specification per line. You can use most standard wildcard characters, but you cannot use wildcard characters denoting the latest version of files (;) and relative versions of files (;-n).

Example

$ BACKUP INFO.BCK/SAVE_SET/FILES_SELECTED=RFILE.DAT []

      

The command in this example selects the files in RFILE.DAT and restores them to the current default directory. The RFILE.DAT file contains the following entries:

[INFO]RESTORE.COM [PAYROLL]BADGE.DAT EMPLOYEE.DAT

Command Qualifier

Lists the file information produced by the command qualifier /LIST in the format provided by the DCL command DIRECTORY/FULL.

Format

/LIST/FULL input-specifier [output-specifier]

Description

The /FULL qualifier is valid only with the command qualifier /LIST.

If you do not specify /FULL with /LIST, the /LIST qualifier uses the default command qualifier /BRIEF and lists only the file specification, size, and creation date of each file. When you specify /FULL, the list includes more information from the file header records, such as the BACKUP date, date of last modification, number of blocks allocated to the file, file protection and organization, and record attributes.

Example

$ BACKUP/LIST/FULL MTA1:ROCK.BCK
Listing of save set(s)
Save set:          ROCK.BCK
Written by:        RINGO
UIC:               [000200,000300]
Date:              20-AUG-2002 15:39:38.89
Command:           BACKUP [.STONES] MTA0:ROCK.BCK/LABEL=BACKUP

Operating system:  OpenVMS Alpha Version V7.3-1

BACKUP version:    V7.3-1
CPU ID register:   08000000
Node name:         _SUZI::
Written on:        _MTA0:
Block size:        8192
Group size:        10
Buffer count:      30

[RINGO.STONES]GRAPHITE.DAT;1
                  Size:       1/1         Created: 18-AUG-2002 14:10
                  Owner: [000200,000200]  Revised: 18-AUG-2002 14:10 (2)
                  File ID: (91,7,1)       Expires: [None specified]
                                          Backup:  [No backup done]
  File protection:    System:RWED, Owner:RWED, Group:RE, World:
  File organization:  Sequential
  File attributes:    Allocation = 1, Extend = 0
                      Global Buffer Count = 0
  Record format:      Variable length, maximum 255 bytes
  Record attributes:  Carriage return

[RINGO.STONES]GRANITE.DAT;1
                      Size:    1/1        Created: 18-AUG-2002 14:11
                      Owner: [000200,000200]  Revised: 18-AUG-2002 14:11 (2)
                      File ID: (92,9,1)       Expires: [None specified]
                                              Backup:  [No backup done]
  File protection:    System:RWED, Owner:RWED, Group:RE, World:
  File organization:  Sequential
  File attributes:    Allocation = 1, Extend = 0
                      Global Buffer Count = 0
  Record format:      Variable length, maximum 255 bytes
  Record attributes:  Carriage return
.
.
.
Total of 4 files, 16 blocks
End of save set

      

The command in this example lists the files in save set MTA1:ROCK.BCK in full format.

Output Save-Set Qualifier

Defines the number of blocks BACKUP places in each redundancy group.

Format

input-specifier output-save-set-spec/GROUP_SIZE=n

Description

BACKUP writes redundant information to output save sets to protect against data loss. Using the redundant information, BACKUP can correct one uncorrectable read error in each redundancy group. The /GROUP_SIZE qualifier specifies the number of output blocks written to each redundancy group. The value of n can be 0 to 100. The default value is 10.

If you define a value of 0 for /GROUP_SIZE, no redundancy groups are created for the save set.

Example

$ BACKUP/RECORD DBA1:[*...]/SINCE=BACKUP TAPE:SAVEWORK.BCK/GROUP_SIZE=5
      

This BACKUP command saves all files in the current default directory tree that have been modified since the last BACKUP/RECORD operation; the /GROUP_SIZE defines the redundancy group size as 5 blocks.

Input File-Selection Qualifier

Specifies that only the file headers of a file are to be saved in a BACKUP operation.

Format

input-specifier /HEADER_ONLY=option output-specifier

Description

The /HEADER_ONLY qualifier specifies that the Backup utility is to save only the file header of a shelved or a preshelved file in a BACKUP operation.

When a file is shelved, the data in the file is shelved, but the file header is retained. Users shelve files to save disk space. (In addition, users might preshelve files to save time by performing shelving operations ahead of time.)

In a BACKUP save operation, the default behavior is to unshelve files before backing them up. This brings back the file data online, so that, when the BACKUP operation is performed, the entire file is backed up (not just the file header). The only exception to the BACKUP default behavior is in operations that use the /PHYSICAL or /IMAGE qualifier. For those operations, the file remains in the file shelved state.

For more information about file shelving and preshelving, refer to Hierarchical Storage Management (HSM) documentation.

Use the following options with the /HEADER_ONLY qualifier:

Option	Description
SHELVED	Saves only the file header of a shelved file.
NOSHELVED	Saves both the file header and the file data of a shelved file. (This causes the file to be unshelved.)
PRESHELVED	Saves only the file header of a preshelved file.
NOPRESHELVE	Saves both the file header and the file data of a preshelved file.

Examples

$ BACKUP [INFO]/HEADER_ONLY=(SHELVED) MKA600:INFO.BCK/SAVE_SET
      

The command in this example saves all files in the directory [INFO] to a tape drive save set named INFO.BCK. The shelved files in [INFO] will not be unshelved. Only their file headers will be saved to save set INFO.BCK because the /HEADER_ONLY=(SHELVED) qualifier is specified.

$ BACKUP [INFO]/HEADER_ONLY=(SHELVED,PRESHELVED)
MKA600:INFO.BCK/SAVE_SET
      

This command saves all files in the directory [INFO] to a tape drive save set named INFO.BCK. The files saved from [INFO] will not be unshelved because the HEADER_ONLY=(SHELVED,PRESHELVED) qualifier is specified. The save set INFO.BCK will contain only the file headers of files that are shelved or preshelved.

$ BACKUP/IMAGE DUA0: MKA600:INFO.BCK/SAVE_SET
      

The command in this example saves all files on the disk DKA0:. Because the /IMAGE qualifier is specified, only the file headers of files that are shelved or preshelved are saved to INFO.BCK.

$ BACKUP [INFO] MKA600:INFO.BCK/SAVE_SET
      

The command in this example saves all files in the directory [INFO] to a tape drive save set named INFO.BCK. The files saved from [INFO] will be unshelved (the default). The save set INFO.BCK will contain both the file header and the data of files that are shelved or preshelved.

Command Qualifier

Specifies that a BACKUP save or copy operation will override restrictions placed on files or will not perform tape label processing checks.

Note File system interlocks are expressly designed to prevent data corruptions, and to allow applications to detect and report data access conflicts. Use of the INTERLOCK keyword overrides these file data integrity interlocks. The data that BACKUP subsequently transfers can then contain corrupted data for open files. Also, all cases in which these data corruptions can occur in the data that BACKUP transfers are not reliably reported to you; in other words, silent data corruptions are possible within the transferred data.

Format

/IGNORE= option input-specifier output-specifier

Description

The /IGNORE= qualifier has the following options:

ACCESSIBILITY	Processes files on a tape that is protected by a volume accessibility character, or on a tape created by HSC Backup. The option applies only to tapes. It affects the first tape mounted and all subsequent tapes in the save set.
INTERLOCK	Processes files that otherwise cannot be processed due to file access conflicts. Use this option to save or copy files currently open for writing. No synchronization is made with the process writing the file, so the file data that is copied might be inconsistent with the input file, depending on the circumstances (for example, if another user is editing the file, the contents might change). When a file open for writing is processed, BACKUP issues the following message: %BACKUP-W-ACCONFLICT, 'filename' is open for write by another user.
	The INTERLOCK option is especially useful if you have files that are open so much of the time that they might not otherwise be saved. The use of this option requires the user privilege SYSPRV, a system UIC, or ownership of the volume. See the Note before this table for more information about this keyword.
LABEL_PROCESSING	Saves or copies the contents of files to the specified magnetic tape volume regardless of the information contained in the volume header record. BACKUP does not verify the volume label or expiration date before writing information to the tape volume. Note that you cannot use this option with the /EXACT_ORDER qualifier.
NOBACKUP	Saves or copies both the file header record and the contents of files marked with the NOBACKUP flag by the /NOBACKUP qualifier of the DCL command SET FILE. If you do not specify this option, BACKUP saves only the file header record of files marked with the NOBACKUP flag.

Examples

$ BACKUP/IGNORE=INTERLOCK
_From: DUA0:[SUSAN...]
_To: MTA0:SONGBIRD.BCK/LABEL=TAPE01
      

This command saves an entire directory tree and the files in all subdirectories, including any files that are open.

$ BACKUP/IGNORE=LABEL_PROCESSING *.*;* MFA1:MYFILES.BCK/REWIND
      

This command rewinds the tape in drive MFA1 to the beginning-of-tape marker, initializes the tape, and creates a save set containing all files in the user's current directory. The command qualifier /IGNORE=LABEL_PROCESSING specifies that no tape label processing checks are done before BACKUP initializes the tape. When the tape is initialized, access to data that previously resided on the tape is lost.

$ INITIALIZE/LABEL=VOLUME_ACCESSIBILITY:"K" MUA1: 29JUN
$ BACKUP/IGNORE=(ACCESSIBILITY)
_From:  DUA0:[BOOKS...]
_To: MUA1:BACKUP.SAV /LABEL=29JUN
      

The INITIALIZE command in this example initializes the tape with an accessibility character (K) and a volume label (29JUN). The BACKUP command mounts the tape, regardless of the accessibility, and performs the BACKUP operation. For more information about tape protection, refer to the HP OpenVMS System Manager's Manual.

$ BACKUP/LOG/IMAGE/CONVERT DKA500:[000000]IMAGE.BCK/SAVE DKA200:/NOINIT
%BACKUP-I-ODS5CONV, structure level 5 files will be converted to structure
        level 2 on DKA200:
-BACKUP-I-ODS5LOSS, conversion may result in loss of structure level 5
        file attributes
%BACKUP-S-CREATED, created DKA200:[000000]000000.DIR;1
%BACKUP-S-CREATED, created DKA200:[000000]BACKUP.SYS;1
%BACKUP-S-CREATED, created DKA200:[000000]CONTIN.SYS;1
%BACKUP-S-CREATED, created DKA200:[000000]CORIMG.SYS;1
%BACKUP-S-CREATED, created DKA200:[000000]SECURITY.SYS;1
%BACKUP-S-CREATED, created MDA2:[000000]TEST_FILES.DIR;1
%BACKUP-S-CREATEDAS, created DKA200:[TEST_FILES]SUB^_^{DIR^}.DIR;1 as
        DKA200:[TEST_FILES]SUB$$DIR$.DIR;1
      

You can use commands like the ones in the example if you have an image backup of an ODS-5 disk, and you want to restore it to an ODS-2 disk.

In the command line in the example, IMAGE.BCK is the ODS-5 save set, and DKA200: is the ODS-2 disk. When you use this conversion method, you must preinitialize the output disk to ODS-2 and then include the /NOINIT qualifier in your command line.

Command Qualifier

Directs BACKUP to process an entire volume or volume set.

Format

/IMAGE input-specifier output-specifier

Description

To use the /IMAGE qualifier, you need write access to the volume index file (INDEXF.SYS) and the bit map file (BITMAP.SYS), or the input medium must be write-locked. BACKUP opens the index file to synchronize with the file system (no update is made). Finally, you must have read access to all files on the input medium.

You can receive a fatal error if you use /IMAGE with the /PHYSICAL qualifier.

When you use the /IMAGE qualifier to save to a disk, alias directory trees are not processed.

Note The input and output devices in an image operation must be different except in an image save operation when the output device is a Files--11 disk save set.

If the output volume is a disk, all files on the output volume are stored contiguously. Contiguous storage of files eliminates disk fragmentation and creates contiguous free blocks of disk space.

Because all files on the input volume are processed, you cannot use input file-selection qualifiers in image copy or save operations. You can, however, restore files and directories selectively from an image save set.

When performing image operations on volume sets (more than one volume), the number of volumes specified by the output specifier must be equal to the number of volumes in the input volume set.

In an image save or copy operation, BACKUP attempts to save or copy all files on the input disk volume including files marked for deletion and lost files (files without a directory entry). By default, a BACKUP image operation saves or copies the attributes but not the contents of files flagged as NOBACKUP.

Also by default, BACKUP does not save the attributes nor the contents of files open for write access by another user at the time of the image save operation. If you want these files to be included, specify the command qualifier /IGNORE in the BACKUP command line. The command qualifier /IGNORE=NOBACKUP directs BACKUP to save or copy files flagged as NOBACKUP. The command qualifier /IGNORE=INTERLOCK directs BACKUP to save or copy files open for write access by another user.

An image restore or copy operation initializes the output volume or volume set. The initialization data comes from the save-volume summary record of the input volume unless the command qualifier /NOINITIALIZE is specified. Specifying /NOINITIALIZE directs BACKUP to initialize the output volume using volume initialization data that already exists on the output volume.

In image restore and copy operations, every file is restored or copied. The output volume must be mounted using the /FOREIGN qualifier. The new volume is a functionally equivalent copy of the input volume; however, file placement will change. Files are stored contiguously on the output volume.

You cannot change the structure level of the output volume in an image restore or copy operation. A BACKUP operation to mixed tape and disk save sets, as shown in the following command, is unsupported:

$ BACKUP SYS$DISK:/IMAGE dka0:FUN,MKA0:/SAVE/REW

Examples

$ MOUNT/FOREIGN DMA1:
%MOUNT-I-MOUNTED, mounted on NODE$DMA1:
$ BACKUP/IMAGE/LOG DLA2: DMA1:
%BACKUP-S-CREATED, created DMA1:[000000]000000.DIR;1
%BACKUP-S-CREATED, created DMA1:[000000]BACKUP.SYS;1
%BACKUP-S-CREATED, created DMA1:[000000]CONTIN.SYS;1
%BACKUP-S-CREATED, created DMA1:[000000]CORIMG.SYS;1
%BACKUP-S-CREATED, created DMA1:[000000]ELLA.DIR;1
%BACKUP-S-CREATED, created DMA1:[ELLA]SCAT.DAT;1
%BACKUP-S-CREATED, created DMA1:[000000]JOE.DIR;1
%BACKUP-S-CREATED, created DMA1:[JOE]STRINGS.DAT;1
%BACKUP-S-CREATED, created DMA1:[000000]OSCAR.DIR;1
%BACKUP-S-CREATED, created DMA1:[OSCAR]KEYS.DAT;1
%BACKUP-S-CREATED, created DMA1:[000000]VOLSET.SYS;1
.
.
.
$
      

The MOUNT command prepares the target disk for the image copy operation. The command qualifier /LOG directs BACKUP to display information about each file copied on your terminal. The BACKUP command initializes DMA1 and copies the disk volume DLA2 to DMA1. All files on DMA1 are stored contiguously.

$ BACKUP/IMAGE DBA2: MTA0:ET.BCK,MTA1:
      

This command saves an entire disk volume to a multivolume save set named ET.BCK using two magnetic tape drives.

$ MOUNT/FOREIGN DBA1:
%MOUNT-I-MOUNTED, mounted on NODE$DBA1:
$ BACKUP/IMAGE WORKDISK DBA1:28SEP.BCK/SAVE_SET
      

The MOUNT command prepares the target disk for the image save operation. The BACKUP command performs an image save operation to a Files--11 save set named 28SEP.BCK.

Command Qualifier

Allows you to restore an incremental save set.

Format

/INCREMENTAL save-set-spec disk-device-name

Description

Use /INCREMENTAL only in restore operations that restore incremental save sets. When you use /INCREMENTAL, the output specifier must specify a device only; file specifications are not allowed. Also, input save-set qualifiers are not allowed in incremental restore operations.

You can create incremental save sets with the command qualifier /RECORD and the file-selection qualifier /SINCE=BACKUP or /SINCE=date. Most sites perform daily incremental save operations to keep copies of files created or modified that day, and periodic full backups to keep a copy of all files on the disk volume. (HP recommends that you use the command qualifier /IMAGE to perform full backups.)

If a disk volume is lost, corrupted, or destroyed, its contents can be recreated by performing the following tasks:

1. Restore the volume using the latest (most recent) image backup save set. (The saveset must have been created using the /IMAGE and /RECORD BACKUP command qualifiers.)
2. Restore any incremental save sets since the last full backup, in reverse chronological order, using the /INCREMENTAL qualifier.

After you restore the save sets in this order, the output disk volume contains the same files it contained when the most recent incremental save operation was performed.

When the /INCREMENTAL qualifier is used, the /BY_OWNER=ORIGINAL qualifier is assumed; therefore, specifying /BY_OWNER is unnecessary unless you want to change the original UICs. The /INCREMENTAL qualifier can be used only on Files--11 Structure Level 2 or 5 volumes.

You can receive a fatal error if you use the /PHYSICAL qualifier with /INCREMENTAL.

Example

If you have been performing a combination of full backups and incremental save operations on a public volume, and the public volume is lost, corrupted, or destroyed, use a procedure like the following one to create a new copy of the public volume. First, restore the volume from the latest full backup with an image restore operation.

The section "Formulating a Backup Strategy" in the BACKUP chapter of the HP OpenVMS System Manager's Manual discusses the importance of using the /IMAGE and /RECORD qualifiers the first time you back up a disk, before you perform incremental backups.

$ MOUNT/FOREIGN DRA0: %MOUNT-I-MOUNTED, mounted on _DRA0: $ BACKUP/IMAGE/RECORD MTA0:FULLJUN02,MTA1 DRA0: %BACKUP-I-RESUME, resuming operation on volume 2 %BACKUP-I-RESUME, resuming operation on volume 3 %BACKUP-I-RESUME, resuming operation on volume 4 . . . $ DISMOUNT/NOUNLOAD DRA0:

Next, mount the disk as a file-structured volume and restore the incremental save sets in reverse chronological order. Finally, restore the weekly incremental save sets. The /INCREMENTAL qualifier must be used where shown in the following example to obtain the correct results:

$ MOUNT DRA0: PUBLIC %MOUNT-I-MOUNTED, PUBLIC mounted on _DRA0: $ BACKUP/INCREMENTAL MTA0:INCD17JUN DRA0: $ BACKUP/INCREMENTAL MTA0:INCD16JUN DRA0: $ BACKUP/INCREMENTAL MTA0:INCD15JUN DRA0: $ BACKUP/INCREMENTAL MTA0:INCW14JUN DRA0: $ BACKUP/INCREMENTAL MTA0:INCW7JUN DRA0:

Note that BACKUP restores the volume correctly regardless of the order in which the incremental save sets are applied; using reverse chronological order is most efficient.

Command Qualifier

Initializes an output disk or tape volume, making its entire previous contents unavailable. (/REWIND performs the same function for output tapes.)

Format

/[NO]INITIALIZE input-specifier output-specifier

Description

The /[NO]INITIALIZE qualifier is valid only when used with the command qualifier /IMAGE during restore or copy operations or when saving files to a sequential-disk save set.

When used with the command qualifier /IMAGE in a restore or copy operation, the /INITIALIZE qualifier directs BACKUP to initialize the output volume using volume initialization data from the save-volume summary record on the input volume.

The /NOINITIALIZE qualifier directs BACKUP to reinitialize the output volume using the existing initialization data on that volume; the output volume must have been previously initialized as a Files--11 volume. When the output volume is initialized, existing data on the volume is lost. The structure level of the output volume must be the same as the structure level of the save set being restored.

For image restore and copy operations on Files--11 volumes, the default is /INITIALIZE.

If you use the /INITIALIZE qualifier when creating sequential-disk save sets, BACKUP initializes the first output volume in the sequential-disk save set, as well as subsequent volumes. By default, BACKUP does not initialize the first volume of a sequential-disk save set but does initialize subsequent volumes of a multivolume sequential-disk save set.

The BACKUP/IMAGE/INITIALIZE command sizes the storage bitmap to correspond to the entire physical volume. Beginning with OpenVMS Version 7.2, the file system also correctly handles a volume whose storage bitmap is smaller than required. The space on the volume available for allocation is the space the bitmap describes; as a result, if the bitmap is smaller than the volume requires, not all the volume is available for file allocation. A SHOW DEVICE /FULL command continues to display the actual physical volume size; however, the free blocks displayed are the number of blocks actually available for allocation.

Examples

$ BACKUP/IMAGE/NOINITIALIZE DBA0: DBA2:
      

This command causes the output volume DBA2 to be reinitialized using the volume initialization data that exists on DBA2. The contents of DBA0 are then copied to DBA2.

$ BACKUP/IMAGE/INITIALIZE DBA2:OLDFILES.BCK/SAVE_SET DBA6:
      

This command directs BACKUP to initialize the output volume DBA6 using volume initialization parameters in the save-volume summary record on DBA2. The image save set OLDFILES.BCK is then restored to DBA6.

Input Save-Set Qualifier

Directs BACKUP to treat the input-specifier as the file name of a list of files. This file specifies the input files for a BACKUP operation.

Format

input-specifier /INPUT_FILES output-specifier/SAVE_SET

Description

The /INPUT_FILES qualifier allows you to specify a list of files to be processed for input. The input-specifier is the name of a file that contains one standard OpenVMS file specification per line.

Example

$ BACKUP FILE.DAT/INPUT_FILES MKA600:INFO.BCK/SAVE_SET
      

The command in this example backs up the files listed in the FILE.DAT file to a tape drive save set named INFO.BCK. If the disk, directory, or file extension is not specified, the defaults are copied from the previous entry or from the default if this is the first entry. The FILE.DAT file contains the following entries:

$1$DKA0:[INFO]*.COM INFO.TEXT [PAYROLL]*.DAT

Command Qualifier

Directs BACKUP to process files in a manner suitable for data interchange (software distribution) by excluding information that would prevent other utilities or sites from reading the BACKUP save set.

The /INTERCHANGE qualifier implies /CONVERT when the input is an ODS-5 disk or file.

Format

/INTERCHANGE input-specifier output-specifier

Description

The effects of the /INTERCHANGE qualifier are as follows:

• Directories not selected as files are not copied.
• Access control lists are not copied.
• Block size on magnetic tape is limited to 8192 bytes.
• Normal error recovery is used to write magnetic tapes so that no bad records exist on the resulting magnetic tape.

Example

$ BACKUP/RECORD/INTERCHANGE [ACCOUNTS]/SINCE=BACKUP MFA0:SAVACC.BCK
      

The command in this example saves all files in the directory [ACCOUNTS] that have been modified since the last BACKUP/RECORD operation. The /INTERCHANGE qualifier ensures that the processed files are suitable for data interchange.

Command Qualifier

Specifies that a BACKUP save operation is to create a BACKUP journal file or append information to a BACKUP journal file. Lists the contents of a BACKUP journal file when combined with the command qualifier /LIST.

Format

/JOURNAL [=file-spec] input-specifier output-specifier

/JOURNAL [=file-spec]/LIST[=file-spec]

Description

A BACKUP journal file contains records of BACKUP save operations and the file specifications of saved files. Use the command qualifier /JOURNAL[=file-spec] in a BACKUP save operation to create a journal file.

If you do not include a file specification with the command qualifier /JOURNAL, the name of the BACKUP journal file defaults to SYS$DISK:[]BACKUP.BJL. You can specify another file name, however. (The file specification of a journal file cannot include a node name; the default file type for a journal file is .BJL.) If the specified journal file does not exist, it is created; if the journal file does exist, the new journal information is appended to the existing journal file.

Start a new version of a journal file by creating a zero-length file using the DCL command CREATE or a text editor.

To list the contents of a BACKUP journal file, use the /JOURNAL=[file-spec] qualifier with the /LIST qualifier, but do not specify an input or output specifier. By default, the list is displayed on SYS$OUTPUT, but it is written to an output file if you specify a file with /LIST.

When listing a journal file, you can use the file-selection qualifiers /BEFORE, /SINCE, and /EXCLUDE to search for specific files. (In this context, the /BEFORE and /SINCE qualifiers refer to the time when the save set was created, not the time when the files in the save set were created.) Also, by specifying a file in a multivolume save set, you can search the journal file to find which volume the file is in. You can then mount that volume and restore the file.

Journal files are not created for physical save operations (save operations performed with the command qualifier /PHYSICAL). You can receive a fatal error if you use the /PHYSICAL qualifier with /JOURNAL.

Examples

$ BACKUP/JOURNAL=LAR.BJL [LARRY]*.*;* MFA0:YET.BCK
      

This command saves all versions of all files in the directory [LARRY] to the save set YET.BCK on MFA0. The /JOURNAL qualifier creates a record of the saved files in a journal file named LAR.BJL in the current default directory.

$ BACKUP/LIST/JOURNAL=ARCH.BJL/SELECT=[SMITH.PROGS]/SINCE=5-OCT-2002
Listing of BACKUP journal
Journal file _DB1:[SYSMGR]:ARCH.BJL;1 ON 7-OCT-2002 00:45:43.01
Save set WKLY.BCK, created on 6-OCT-2002 00:01:34.54
Volume number 1, volume label WKL101

         [SMITH.PROGS]REMINDER.FOR;46
         [SMITH.PROGS]RUNTHIS.FOR;4
         [SMITH.PROGS]TIMER.PAS;5

.
.
.
      

This example displays all files in the directory [SMITH.PROGS] that were saved after October 5, 2002, and listed in the BACKUP journal file ARCH.BJL.

$ BACKUP/JOURNAL/LOG/IMAGE  DRA2: MTA0:3OCT.FUL
%BACKUP-S-COPIED, copied DRA2:[COLLINS]ALPHA.DAT;4
%BACKUP-S-COPIED, copied DRA2:[COLLINS]EDTINI.EDT;5
.
.
.
%BACKUP-I-RESUME, resuming operation on volume 2
%BACKUP-I-READYWRITE, mount volume 2 on _MTA0: for writing
Press return when ready: [Return]
%BACKUP-S-COPIED, copied DRA2:[LANE]MAIL.MAI;1
%BACKUP-S-COPIED, copied DRA2:[LANE]MEMO.RNO;5
.
.
.
$ BACKUP/JOURNAL/LIST
Listing of BACKUP journal
Journal file _DB2:[SYSMGR]BACKUP.BJL;1 on 3-OCT-2002 00:40:56.36
Save set 3OCT.FUL created on 3-OCT-2002 00:40:56.36
Volume number 1, volume label 3OCT01

         [COLLINS]ALPHA.DAT;4
         [COLLINS]EDTINI.EDT;5
         [COLLINS]LOGIN.COM;46
         [COLLINS]LOGIN.COM;45
         [COLLINS]MAIL.MAI;1
         [COLLINS.MAR]GETJPI.EXE;9
         [COLLINS.MAR]GETJPI.LIS;14
                   .
                   .
                   .
         [LANE]LES.MAI;1
                   .
                   .
                   .
Save set 3OCT.FUL created on 3-OCT-2002 00:40:56.36
Volume number 2, volume label 3OCT02

          [LANE]MAIL.MAI;1
          [LANE]MEMO.RNO;5
          [LANE]MEMO.RNO;4
                   .
                   .
                   .
          [WALTERS.VI]KD.RNO;52

End of BACKUP journal

      

This example shows how to create a BACKUP journal file and list the contents of the BACKUP journal file.

Output Save-Set Qualifier

Specifies the volume labels for the magnetic tapes to which the save set is written.

Format

input-specifier output-save-set-spec/LABEL=(string[,...])

Description

Use the /LABEL Qualifier to specify the one- to six-character volume labels for the magnetic tapes to which the save set is written.

You can specify either a single label or a list of labels with the /LABEL qualifier. If you do not specify the /LABEL qualifier, BACKUP uses the first six characters of the save-set name as the volume label of the first tape. If you specify a label that is longer than six characters, BACKUP truncates the label to six characters.

If the save set continues to another tape, and you did not specify a volume label for the tape, BACKUP uses the first four characters of the previous tape's volume label followed by the volume number of the tape. For example, if the first tape in a save set is labeled AAAABB, the second tape in a save set is labeled AAAA02, and the third tape is labeled AAAA03.

Before writing a save set to magnetic tape, BACKUP compares the label specified in the command line to the volume label of the tape. (If the tape has no volume label and you specified the output save-set qualifier /REWIND, BACKUP writes the label you specified to the volume header record of the tape.) If the volume label has fewer than six characters, BACKUP pads the volume label with the blank character to six characters.

The first four characters of the volume label must either exactly match the first four characters of the label specified in the BACKUP command line, or the first four characters of the volume label must end with one or more underscore characters. If the first four characters of the volume label end with one or more underscore characters, and the label specified in the command line matches the part of the volume label that appears before the underscore characters, BACKUP accepts the match. (For example, the volume label ABN_ matches the command line label ABN but does not match the command line label ABNE.) If either the fifth or the sixth character of the volume label is in the range 0 to 9, BACKUP does not compare these characters with corresponding characters in the label specified in the BACKUP command line. Otherwise, the fifth and sixth characters in the volume label must match the corresponding characters in the label specified in the BACKUP command line exactly.

The following table illustrates volume labels that match labels specified in the BACKUP command line:

Label Specified in the Command Line	Matching Volume Labels
MAR	MAR, MAR_, MAR_nn
MAR_	MAR_, MAR_nn
MARK	MARK, MARKnn
MARKER	MARKER, MARKnn

If the label you specify matches the tape's volume label, the BACKUP save operation proceeds. If you specify more than one label with the /LABEL qualifier, the BACKUP save operation succeeds if any of the labels you specify match the tape's volume label. For example, if the tape's volume label is MA1686, the save operation will succeed if you specify the following list of labels with the /LABEL qualifier:

/LABEL=(MA1684,MA1685,MA1686)

If the label you specified does not match the tape's volume label, BACKUP displays the following messages and prompt on your terminal if you specified the command qualifier /NOASSIST, or on the operator terminal if you did not specify /NOASSIST:

%BACKUP-W-MOUNTERR, volume 'number' on 'device' was not mounted because its label does not match the one requested Specify option (QUIT, NEW tape or OVERWRITE tape) BACKUP>

Specify QUIT to abort the BACKUP operation and unload the magnetic tape. Specify NEW to direct BACKUP to prompt for a new tape. Specify OVERWRITE to direct BACKUP to ignore the label mismatch, mount the tape, initialize the tape if you specified the output save-set qualifier /REWIND, and write the save set to the tape.

You can specify the command qualifier /IGNORE=LABEL_PROCESSING to prevent BACKUP from verifying the volume label of the tape. You can also use the /EXACT_ORDER qualifier to specify the exact order of tape volume labels that you want to use in a BACKUP operation.

Examples

$ BACKUP [PAYROLL] MTA0:30NOV.BCK/LABEL=PAY
      

This command causes BACKUP to check the volume label of the tape mounted on drive MTA0. If the volume label is PAY, BACKUP saves the directory [PAYROLL] to a save set named 30NOV.BCK.

$ BACKUP DDA1: MTA0:PLAYS.BCK,MTA1,MTA2/REWIND/LABEL=(ACT1,ACT2,ACT3)
      

This example assumes that the three tapes have no volume labels. This command saves all files on the disk named DDA1 to the save set PLAYS.BCK. The first tape in the save set is labeled ACT1, the second is labeled ACT2, and the third is labeled ACT3.

Command Qualifier

Lists information about a BACKUP save set and about the files in a save set. You can display the list on your terminal or write it to a file.

Format

/LIST [=file-spec] save-set-spec

Description

Use the /LIST qualifier by itself or in conjunction with any other operation (save, restore, copy, compare, or journal). If /LIST is specified by itself (not with a save, restore, copy, compare or journal operation), the input specifier must refer to a save set, and the output specifier must be omitted.

Before you can list the contents of a save set, the media containing the save set must be inserted into an appropriate drive. If the save set is stored on a disk, the disk must be mounted as a Files--11 volume or as a foreign volume. BACKUP mounts magnetic tapes automatically as part of the list operation.

By default, the list information is displayed on your terminal; however, you can specify a file to which the list information can be written.

When you use the /LIST qualifier with standalone BACKUP and you direct output to a file (/LIST=file-spec), the file specification must refer to either a terminal or a printer.

You can use either the command qualifier /BRIEF or /FULL with the /LIST qualifier. The /BRIEF qualifier directs BACKUP to list each file's size in blocks and its creation date. The /FULL qualifier directs BACKUP to list additional information about each file in the same format as the information provided by the DCL command DIRECTORY/FULL. The default is /BRIEF.

Do not use the command qualifier /LOG with /LIST when the output for /LIST is directed to the terminal; if you do, you will receive confusing output.

Example

$ BACKUP/LIST DBA2:[SAVE]23MAR02.BCK/SAVE_SET

Listing of save set(s)

Save set:          23MAR02.BCK
Written by:        MOROCI
UIC:               [000200,000200]
Date:              23-MAR-2002 14:18:16.00
Command:           BACKUP [SAVE] DBA2:[SAVE]23MAR00.BCK/SAVE_SET

Operating system:  OpenVMS Alpha Version V7.3-1

BACKUP version:    V7.3-1
CPU ID register:   08000000
Node name:         _SUZI::
Written on:        _DBA2:
Block size:        32,256
Group size:        10
Buffer count:      3

[SAVE]LAST.DAT;1                         1  18-JAN-2002 14:11
[SAVE]INFO.TXT;4                         5   4-FEB-2002 13:12
[SAVE]WORK.DAT;3                        33   1-JAN-2002 10:02

Total of 3 files, 39 blocks
End of save set

      

This command lists the BACKUP summary information and the file name, size, and creation date for each file in the save set. Note that the /SAVE_SET qualifier is required to identify the input specifier as a save set on a Files--11 disk.

Command Qualifier

Determines whether the file specification of each file processed is displayed on SYS$OUTPUT during the operation. The default is /NOLOG.

Format

/[NO]LOG input-specifier output-specifier

Example

$ BACKUP/LOG [SAVE]23MAR02.BCK/SAVE_SET DBA2:[PLI.WORK]
%BACKUP-S-CREATED, created DBA2:[PLI.WORK]ANOTHER.DAT;1
%BACKUP-S-CREATED, created DBA2:[PLI.WORK]LAST.DAT;1
%BACKUP-S-CREATED, created DBA2:[PLI.WORK]THAT.DAT;1
%BACKUP-S-CREATED, created DBA2:[PLI.WORK]THIS.DAT;2
.
.
.
      

In this example, the file specifications of the files restored to the directory named [PLI.WORK] on DBA2 are logged to SYS$OUTPUT.

Output Save-Set Qualifier

Controls whether data records are automatically compacted and blocked together. Data compaction and record blocking increase the amount of data that can be stored on a single tape cartridge.

The compaction ratio depends on the data and the tape drive you use. For more information, refer to the documentation supplied with your tape drive.

BACKUP allows you to specify different compaction settings on different save sets on a tape. However, not all tape drives support the use of more than one compaction setting on a tape. Whether mixed mode tapes are permitted depends on the model of the tape drive you use.

Format

input-specifier output-save-set-spec /MEDIA_FORMAT=[NO]COMPACTION

Description

The /MEDIA_FORMAT qualifier can only be used with tape drives that support data compaction.

On Alpha systems, you can use the /MEDIA_FORMAT=COMPACTION qualifier for hardware data compaction of SCSI tape drives.

Example

$ BACKUP WORK$:[TESTFILES...]*.*;*  MUA0:TEST.SAV -
_$/MEDIA_FORMAT=COMPACTION /REWIND
      

This command saves all files in the directory [TESTFILES] and its subdirectories in a save set named TEST.SAV using a TA90E tape drive. The /MEDIA_FORMAT=COMPACTION qualifier specifies that the tape drive automatically compacts and blocks together data records on the tape.

Input File-Selection Qualifier

Selects files according to the value of the modified date field (the date the file was last modified) in each file header record.

Format

input-specifier/BEFORE=time /MODIFIED output-specifier

input-specifier /SINCE=time /MODIFIED output-specifier

Description

You must use the /MODIFIED qualifier with either of the input file-selection qualifiers /BEFORE or /SINCE. The date and time you specify with /BEFORE or /SINCE determines which files are processed.

You cannot use /MODIFIED with the input file-selection qualifiers /BACKUP, /CREATED, or /EXPIRED.

Example

$ BACKUP [SUNDANCE...]/BEFORE=TODAY/MODIFIED MFA1:MOD.BCK
      

This command saves all files in the directory tree [SUNDANCE] whose modification dates precede today (00:00:00.0 o'clock of the current day, month, and year).

Output File Qualifier

Creates a new version of a file if a file with an identical specification already exists at the location to which the file is being restored or copied.

Format

input-specifier output-specifier/NEW_VERSION

Description

If BACKUP attempts to copy or restore a file when a file with an identical directory name, file name, type, and equal or higher version number already exists, a new file is created with the same name and type and a version number one higher than the highest existing version.

If you do not use /NEW_VERSION, /REPLACE, or /OVERLAY, and the version number of the file being restored is equal to or less than the version number of the existing file, BACKUP reports an error in copying or restoring the file.

Note that when copying or restoring files using the /NEW_VERSION qualifier, files are processed in decreasing version number order and are created in ascending order. The result is that the version numbers are inverted.

Because this qualifier causes version numbers to change, using it with the /VERIFY qualifier will cause unpredictable results. HP recommends that you do not use the /NEW_VERSION qualifier with the /VERIFY qualifier.

Example

$ BACKUP MTA1:NOV30REC.BCK/SELECT=*.DAT [RECORDS...]/NEW_VERSION
      

This example restores all files with the file type of .DAT from the magnetic tape save set NOV30REC.BCK to the directory [RECORDS]. The /NEW_VERSION qualifier instructs BACKUP to restore each file with the file type .DAT regardless of whether a file with the same file specification already exists.

Command Qualifier

Beginning with OpenVMS Version 7.2, on a save operation, /NOINCREMENTAL allows you to control the amount of file data that is saved. Use this qualifier only if you are sure that you want to save specific files and do not want to save all data.

In recent versions of OpenVMS, the /SINCE=BACKUP incremental save operation has been refined so that files that are saved are accurate and not redundant. As a result, the /NOINCREMENTAL and /SINCE=BACKUP qualifiers are not allowed together. This ensures an accurate /INCREMENTAL restore.

Format

/NOINCREMENTAL input-specifier output-specifier

Description

In OpenVMS Version 6.2 and prior versions, the system, by default, did not save files and subdirectories that were under directories that had been modified. In OpenVMS Versions 7.0 and 7.1, to ensure a successful restore, the system saved all files and subdirectories under directories that had been modified. This behavior, however, sometimes resulted in saving files and subdirectories that were not needed for later restore operations.

Example

$ BACKUP/ FAST/ NOINCREMENTAL /SINCE="3-MAY-2002" -
_$ MAC_DISK:[000000...]*.*;* -
_$ TAPE:MCDSK000503.BCK/ SAVE/ REWIND
      

The command in this example executes an incremental save BACKUP operation for an input volume; the command avoids saving all files under recently modified directories.

Output File Qualifier

Writes the input file over a file with an identical specification at the output location.

Format

input-specifier output-specifier/OVERLAY

Description

If BACKUP attempts to copy or restore a file when a file with an identical directory name, file name, type, and version number already exists, the new version of the file is written over the existing version. The file identification of the new version is the same as the file identification of the file that is overwritten.

The physical location of the file on disk does not change. If /OVERLAY is specified, and the new file is larger than the one already present, BACKUP allocates more blocks on the disk and extends the file.

When you do not use /OVERLAY, /REPLACE, or /NEW_VERSION, and the version number of the file being restored is identical to the version number of the existing file, BACKUP reports an error in copying or restoring the file.

Example

$ BACKUP DRA1:MAR30SAV.BCK/SAVE_SET [RECORDS...]/OVERLAY
      

The sequential-disk save set MAR30SAV.BCK is restored to the directory tree [RECORDS...]. If a file from the save set has a specification that is identical to a file that already exists in [RECORDS...], the /OVERLAY qualifier directs BACKUP to write over the existing version.

The /OWNER_UIC qualifier has been superseded by /BY_OWNER. HP recommends that you substitute /BY_OWNER for /OWNER_UIC in command procedures and operator instructions. See the description of /BY_OWNER for more information.

Command Qualifier

Specifies that a BACKUP operation is to ignore any file structure on the input volume and to process the volume in terms of logical blocks.

Format

/PHYSICAL input-specifier output-specifier

Description

In a physical operation, BACKUP saves, restores, copies, or compares the entire volume in terms of logical blocks.

The input and output specifiers for physical volumes must be device names, and they cannot be the same device. Also, the following qualifiers cause a fatal error if you specify any of them with the /PHYSICAL qualifier: /DELETE, /IMAGE, /INCREMENTAL, /JOURNAL, and /RECORD.

For physical copy operations between disks, the output disk must be the same type of device as the input disk; for example, a BACKUP/PHYSICAL operation cannot be performed between an RP05 input disk and an RP06 output disk. The output disk must not have a bad block in any location that corresponds to a good block on the input disk. (This restriction does not apply to RA or more recent disk architectures.)

For physical save operations between disks, the output disk must be the same type of disk as the input disk or a larger capacity disk. The output disk must not have a bad block in any location that corresponds to a good block on the input disk. (This restriction does not apply to RA or more recent disk architectures.)

For physical restore operations between disks, the output disk must be the same type of device as the disk from which the save set was created. The output disk must not have a bad block in any location that corresponds to a good block on the disk from which the save set was created. (This restriction does not apply to RA or more recent disk architectures.)

An output disk of a physical operation must be mounted using the DCL command MOUNT/FOREIGN. An input disk of a physical operation must either be mounted using the DCL command MOUNT/FOREIGN, or the user must have the user privilege LOG_IO or PHY_IO.

You can perform physical save and restore operations using magnetic tapes. BACKUP mounts magnetic tapes automatically as foreign devices.

A save set written using the /PHYSICAL qualifier can only be read as a physical save set; conversely, a file-structured save set can only be read with file-structured restore or compare operations.

Note BACKUP/PHYSICAL does not copy the first track (track 0) of RX01 and RX02 diskettes; HP does not support track 0.

Examples

$ MOUNT/FOREIGN DYA0:
$ MOUNT/FOREIGN DYA1:
$ BACKUP/PHYSICAL DYA0:  DYA1:
      

This example mounts RX02 diskettes in DYA0 and DYA1 as foreign devices and copies the contents of the diskette mounted in DYA0 to the diskette mounted in DYA1.

$ MOUNT/FOREIGN DBA1:
$ BACKUP/PHYSICAL MTA0:28SEP.BCK DBA1:
      

This command restores a physical save set named 28SEP.BCK to DBA1.

Output Save-Set Qualifier

When you create a save set on disk, this qualifier defines the protection to be applied to an output save set. When you create a save set on magnetic tape, this qualifier defines the protection to be applied to the magnetic tape volume. (All save sets created subsequently on the tape will receive this same protection until the tape is initialized.)

Format

input-specifier output-save-set-spec/PROTECTION[=(code)]

Description

Because the file system treats a BACKUP save set as a single file, it is crucial that you protect save sets adequately. If you do not specify adequate protection, anyone who has access to a save set can access any file in the save set.

The protection code indicates the type of access (read, write, execute, and delete) available to the four categories of users (system, owner, group, and world). For more information about specifying protection codes, refer to the OpenVMS User's Manual.

If the save set is written to either a Files--11 disk or a sequential disk and /PROTECTION is not specified, BACKUP applies the process default protection to the save set. If /PROTECTION is specified, any protection categories not specified default to your default process protection.

Protection information is written to the volume header record of a magnetic tape, and applies to all save sets stored on the tape. If you specify /PROTECTION, any protection categories that you do not specify default to your default process protection.

To initialize a magnetic tape with the correct protection, specify the output save-set qualifier /REWIND with the /PROTECTION qualifier. If you do not specify /REWIND with /PROTECTION, the protection information, if any, in the volume header record is not changed. However, specifying /PROTECTION without /REWIND ensures that continuation volumes receive the correct protection.

If the save set is written to magnetic tape and /PROTECTION is not specified, BACKUP applies no protection to the tape.

In order to initialize a magnetic tape volume that was previously initialized with the /PROTECTION qualifier, you must own the volume (your UIC matches the UIC of the volume) or have the VOLPRO privilege.

Examples

$ BACKUP
_From: [CLEAVER...]
_To: MFA2:ACCOUNTS.BCK/BY_OWNER=[301,310]/REWIND/LABEL=BANK01-
_$ /PROTECTION=(S:RWE,O:RWED,G:RE,W)
      

This command saves the directory tree [CLEAVER...] to a save set named ACCOUNTS.BCK on the magnetic tape labeled BANK01. The output save-set qualifier /REWIND directs BACKUP to rewind the tape and initialize it before performing the save operation. The output save-set qualifier /BY_OWNER assigns an owner UIC of [301,310] to the magnetic tape. The /PROTECTION qualifier assigns the owner of the magnetic tape read, write, execute, and delete access. SYSTEM users are assigned read, write, and execute access; GROUP users are assigned read and execute access; and WORLD users are assigned no access.

$ BACKUP/IMAGE
_From: DUA0:
_To: MFA2:DAILY.BCK/REWIND/LABEL=TAPE1-
_$ /PROTECTION=(S:RWED,O:RWED,G,W)
$ BACKUP/IMAGE DUA2: MFA2:DAILY2.BCK/PROTECTION=(S:RWED,O:RWED,G,W)
%BACKUP-I-RESUME, resuming operation on volume 2
%BACKUP-I-READYWRITE, mount volume 2 on _MFA2: for writing
Press return when ready: [Return]
      

This first BACKUP command creates an image backup of the disk DUA0 in a save set named DAILY.BCK on the magnetic tape labeled BANK01. The output save-set qualifier /REWIND directs BACKUP to rewind the tape and initialize it before performing the save operation. The /PROTECTION qualifier assigns the owner of the magnetic tape and SYSTEM users read, write, execute, and delete access; GROUP and WORLD users are assigned no access.

The second BACKUP command uses the same tape for an image backup of the disk DUA2. When the tape is full, BACKUP requests another volume. Because the /PROTECTION qualifier was specified with second BACKUP command, the continuation volume receives the desired protection.

Command Qualifier

Records the current date and time in the BACKUP date field of each file header record once a file is successfully saved or copied.

Format

/RECORD input-specifier output-specifier

Description

The /RECORD qualifier can be used only in save or copy operations on Files--11 Structure Level 2 or 5 volumes. To use the /RECORD qualifier on files, the user privilege SYSPRV is required.

When you use /RECORD in a copy or save operation, BACKUP writes the date and time that the copy or save set was created in the BACKUP date field of each file header record.

When you use /RECORD to perform incremental save operations on a disk volume, do not allow other users to use /RECORD in their BACKUP operations on the same disk volume. If other users specify /RECORD, the dates in the BACKUP date fields of file header records will change. This makes it impossible for you to save all files created or modified since you last performed a save operation.

If you use the command qualifier /VERIFY with /RECORD, files that fail verification are not recorded.

If /RECORD is not specified, the BACKUP date field of each processed file is not changed.

You cannot use the /RECORD qualifier with the command qualifiers /DELETE, /COMPARE, or /PHYSICAL.

Example

$ BACKUP/RECORD  DBA1:[000000...]/SINCE=BACKUP MTA0:13MAY.BCK
      

This command saves all files on DBA1 that have been created or modified since the last save operation and records the current date and time in each file header record.

Command Qualifier

Dismounts and unloads a tape after a BACKUP save operation writes a save set to the tape (and optionally verifies the saveset information on that tape).

Format

/RELEASE_TAPE input-specifier output-specifier

Description

By using the /RELEASE_TAPE qualifier in conjunction with either the /DELETE or /RECORD qualifiers, you can make a tape drive available for other operations before the BACKUP command completes. You can also use the /RELEASE_TAPE qualifier without the /DELETE or /RECORD qualifiers, in which case the /RELEASE_TAPE qualifier dismounts and unloads the tape in the drive after the BACKUP command completes.

You cannot use the /RECORD and /DELETE qualifiers in the same BACKUP command.

Examples

$ BACKUP/IMAGE/RECORD/RELEASE_TAPE DUA1: MUA0:BACK.BCK
      

The command in this example backs up the disk DUA1 to the save set BACK.BCK. By using the /RELEASE_TAPE and /RECORD qualifiers, BACKUP dismounts and unloads the tape in MUA0 (making it available for other operations) before it performs the action of the /RECORD qualifier.

$ ALLOCATE MUA0: TAPE
$ BACKUP/DELETE/RELEASE_TAPE/LOG DUA1:[MAIN...] MUA0:MAIN.BCK
.
.
.
$ DEALLOCATE TAPE
      

The commands in this example back up some directories on a disk named DUA1, and then delete the files that have been backed up. The /RELEASE_TAPE qualifier dismounts and unloads the tape (making it available for other operations) before the /DELETE qualifier performs its action. The tape remains allocated until you enter the DEALLOCATE command.

Output File Qualifier

Replaces a file on the output specifier with an identically named file from the input specifier.

Format

input-specifier output-specifier/REPLACE

Description

When you use /REPLACE in a copy or restore operation, and an identically named file exists in both the input and output specifiers, BACKUP performs the following tasks:

• Copies or restores a new version of the file with the same directory specification, file name, type, and version number
• Deletes the copy of the file that previously existed on the output disk

In this way, the previous copy of the file is replaced with the restored version. Note that the version number is not incremented because the old copy of the file is deleted. If you want to keep the versions from both the input and the output specifiers, use the output file qualifier /NEW_VERSION.

If you do not use /REPLACE, /OVERLAY, or /NEW_VERSION, and the version number of the file being restored is identical to the version number of the existing file, BACKUP reports an error and does not restore the file.

Example

$ BACKUP MUA0:SAVEWORK.BCK/SELECT=[LEE...] DUA0:[LEE...]/REPLACE
      

The command in this example restores the directory tree [LEE...] (and all files in the directory tree) from a magnetic tape save set to disk. The input save-set qualifier /SELECT specifies the directory tree to be selected from the save set. The output file qualifier /REPLACE instructs BACKUP to first create a new version of an input file if the output medium has a file with the same file specification, and then to delete the file that originally existed on the output medium.

Input Save-Set Qualifier

Rewinds the input tape reel to the beginning-of-tape marker before reading the input volume.

Format

input-save-set-spec/[NO]REWIND output-specifier

Description

The /[NO]REWIND qualifier is for magnetic tape volumes only.

The /REWIND qualifier directs BACKUP to rewind the input magnetic tape to the beginning-of-tape marker before reading the input volume. Then BACKUP locates the input save set. In this way, BACKUP can find the input save set if it is located before the current tape position.

The /NOREWIND qualifier indicates that BACKUP should not rewind the input volume before processing the command. Instead, BACKUP proceeds toward the logical end-of-tape (the end of the last save set stored on the tape). Therefore, if the specified save set is located before the current position of the tape, BACKUP is unable to find it.

The default is /NOREWIND. You must specify /REWIND to rewind the tape.

Example

$ BACKUP MFA1:CONTRACTS.BCK/REWIND DBA2:[*...]/BY_OWNER=ORIGINAL
      

In this example, the save set CONTRACTS.BCK is restored to the disk volume mounted on DBA2. The /REWIND qualifier rewinds the magnetic tape to the beginning-of-tape marker before reading the input volume to search for CONTRACTS.BCK. The output file qualifier /BY_OWNER restores the original owner UICs.

Output Save-Set Qualifier

Rewinds the output tape to the beginning-of-tape marker and initializes the output tape. The /NOREWIND qualifier causes the tape to wind forward to the logical end-of-tape (the end of the last save set stored on the tape) and to begin writing the save set there.

Format

input-specifier output-save-set-spec/[NO]REWIND

Description

The /[NO]REWIND qualifier is for magnetic tape volumes only.

If you specify /REWIND, BACKUP rewinds to the beginning of the magnetic tape and searches the volume header record for a volume label. If the volume header record contains no volume label, BACKUP writes the label specified in the BACKUP command to the volume header record, initializes the tape, and creates the save set on the tape.

If no label is specified explicitly in the command line, BACKUP uses the first six characters of the save-set name as the volume label of the first tape in a multivolume save set and the first four characters of the save-set name followed by the volume number of the tape as the volume label of subsequent tapes. You can also specify a label or list of labels explicitly with the /LABEL qualifier. If you do not specify enough labels with the /LABEL qualifier, BACKUP uses the first four characters of the final label in the list followed by the volume number of the tape as the volume label of subsequent tapes.

If BACKUP finds a volume label on the tape, it compares the volume label with the label you specified in the BACKUP command line (either explicitly with the /LABEL qualifier or implicitly through the save-set name) and ensures that the tape is expired.

If the volume label is fewer than six characters long, BACKUP pads the volume label with the blank character to six characters. The first four characters of the volume label must either match the first four characters of the label specified in the BACKUP command line exactly, or the first four characters of the volume label must end with one or more underscore characters. If the first four characters of the volume label end with one or more underscore characters, and the label specified in the command line matches the part of the volume label that appears before the underscore characters, BACKUP accepts the match. (For example, the volume label ABN_ matches the command line label ABN but does not match the command line label ABNE.) If either the fifth or sixth character of the volume label is in the range 0 to 9, BACKUP does not compare these characters with corresponding characters in the label specified in the BACKUP command line. Otherwise, the fifth and sixth characters in the volume label must match the corresponding characters in the label specified in the BACKUP command line exactly. The following table illustrates volume labels that match labels specified in the BACKUP command line:

Label Specified in the Command Line	Matching Volume Labels
MAR	MAR, MAR_, MAR_nn
MAR_	MAR_, MAR_nn
MARK	MARK, MARKnn
MARKER	MARKER, MARKnn

You can specify more than one label with the /LABEL qualifier. If any label specified in the BACKUP command line matches the volume label of the tape and the tape is expired, BACKUP overwrites the volume label of the tape with the same volume label.

By overwriting the tape's volume label, BACKUP initializes the tape, removing access to any data that previously resided on the tape and preparing the tape to receive new data. During the initialization process, BACKUP writes the values specified with the output save-set qualifiers /TAPE_EXPIRATION, /PROTECTION, and /BY_OWNER to the volume header record. (If these qualifiers are not specified, the default tape expiration date is today, the default protection is none, and the owner UIC of the tape is the UIC of the current process.) After initializing the tape, BACKUP writes the save set to the tape.

If the label in the BACKUP command line did not match the volume label of the tape, BACKUP displays the following message and prompt on your terminal if you specified the command qualifier /NOASSIST, or on the operator terminal if you did not specify /NOASSIST:

%BACKUP-W-MOUNTERR, volume 'number' on 'device' was not mounted because its label does not match the one requested Specify option (QUIT, NEW tape or OVERWRITE tape) BACKUP>

If you enter QUIT at the BACKUP> prompt, BACKUP aborts, unloads the magnetic tape, and issues the following message:

%BACKUP-F-ABORT, operator requested abort on fatal error

If you enter NEW at the BACKUP> prompt, BACKUP unloads the magnetic tape and issues the following prompt for a new tape:

%BACKUP-I-READYWRITE, mount volume 'volume-number' on _'device-name': for writing Enter "YES" when ready:

If you enter OVERWRITE at the BACKUP> prompt, BACKUP overwrites the old volume label with the new volume label. (OVERWRITE instructs BACKUP to ignore the fact that either the tape has not expired or that the labels do not match.) By overwriting the tape's volume label, BACKUP initializes the tape, removing access to any data that previously resided on the tape and preparing the tape to receive new data.

During the initialization process, BACKUP writes the values specified with the output save-set qualifiers /TAPE_EXPIRATION, /PROTECTION, and /BY_OWNER to the volume header record. After initializing the tape, BACKUP writes the save set to the tape.

If the tape is not expired, BACKUP displays the following message and prompt on your terminal if you specified the command qualifier /NOASSIST, or on the operator terminal if you did not specify /NOASSIST:

%BACKUP-W-MOUNTERR, volume 'number' on 'device' was not mounted because its expiration date is in the future Specify option (QUIT, NEW tape or OVERWRITE tape) BACKUP>

Always specify /REWIND when the output tape has a non-ANSI or non-ISO label or when the output tape has never been initialized.

The /NOREWIND qualifier directs BACKUP to compare the volume label of the tape with the label you specified in the BACKUP command before performing the save operation. You can specify a label explicitly with the /LABEL qualifier; otherwise, BACKUP uses the first six characters of the save-set name as the volume label. If the volume label does not match the label you specified, BACKUP displays the following message and prompt on your terminal if you specified the command qualifier /NOASSIST, or on the operator terminal if you did not specify /NOASSIST:

%BACKUP-W-MOUNTERR, volume 'number' on 'device' was not mounted because its label does not match the one requested Specify option (QUIT, NEW tape or OVERWRITE tape) BACKUP>

If you choose the OVERWRITE option, BACKUP ignores the fact that the volume labels do not match. If the labels match, or if you choose the OVERWRITE option, BACKUP winds the tape forward to the logical end-of-tape (the end of the last save set stored on the tape) and writes the save set to the tape. If the logical end-of-tape is also the physical end of the tape, BACKUP requests a new tape. Because BACKUP searches for the end of data on the tape, you cannot write a new save set to a tape if it ends with a save set that is continued onto another tape.

Although the /NOREWIND qualifier does not initialize the first tape in a multivolume save set, BACKUP initializes subsequent tapes in a multivolume save set. BACKUP ensures that the tape is expired and that the tape labels match before initializing subsequent volumes in a multivolume save set.

The default is /NOREWIND. You must specify /REWIND to rewind and initialize a magnetic tape volume.

Example

$ BACKUP
_From: *.PS
_To:
MTA0:DSRSAVE.BCK/REWIND/LABEL=DSR01/TAPE_EXPIRATION=29-JUN-2002
      

The command in this example initializes a new magnetic tape and writes the volume label DSR01 and a tape expiration date of June 29, 2002, to the tape's volume header record. Then this command saves all files in the current default directory with a file type of .PS to the magnetic tape save set named DSRSAVE.BCK.

Input Save-Set Qualifier

Directs BACKUP to treat the input file as a BACKUP save set. You must specify /SAVE_SET when the input specifier refers to a BACKUP save set on disk.

Format

input-save-set-spec/SAVE_SET output-specifier

Description

The /SAVE_SET qualifier allows you to refer to a BACKUP save set on a local Files--11 disk, a remote Files--11 disk, or a sequential disk. If you do not specify /SAVE_SET, an input specifier that refers to a disk is treated as a Files--11 file. An input specifier that refers to tape is always treated as a BACKUP save set.

Examples

$ BACKUP DBA2:[BACKUP]1212MAR3.BCK/SAVE_SET DBA1:[*...]
      

This command restores a save set named 1212MAR3.BCK from DBA2 to DBA1.

$ BACKUP/LIST DBA2:[SAVE]23MAR02.BCK/SAVE_SET
      

This command lists the BACKUP summary information and the file name, size, and creation date for each file in the save set named 23MAR02.BCK. The /SAVE_SET qualifier is required to identify the input specifier as a save set on a disk.

$ BACKUP/LOG DBA2:[SAVE]23MAR02.BCK/SAVE_SET DBA3:[PLI.WORK]
      

This command restores the directory that was listed in Example 2. File specifications are logged to SYS$OUTPUT as the files are restored.

Output Save-Set Qualifier

Directs BACKUP to treat the output file as a BACKUP save set. You must specify the /SAVE_SET qualifier when the output specifier refers to a BACKUP save set on disk.

Format

input-specifier output-save-set-spec/SAVE_SET

Description

The /SAVE_SET qualifier allows you to create a BACKUP save set on a local Files--11 disk, a remote Files--11 disk, or a sequential disk. If you do not specify /SAVE_SET, an output specifier that refers to disk is treated as a Files--11 file. An output specifier that refers to tape is always treated as a BACKUP save set.

Examples

$ BACKUP [HILL] DBA1:[BACKUP]SEP28.BCK/SAVE_SET
      

This command saves the directory [HILL] to a save set named SEP28.BCK on a Files--11 disk.

$ BACKUP DBA2:[PLI.WORK]*.*; [SAVE]23MAR02.BCK/SAVE_SET
      

This command saves the highest numbered version of each file in directory [PLI.WORK] in a save set named 23MAR02.BCK on the same disk.

$ BACKUP
_From: []
_To: MILO"FRANKIE THISISMINE"::DUA0:[FRANKIE]MYDIR.BCK/SAVE_SET
      

This command saves all files in the current default directory to a network save set named MYDIR.BCK on node MILO.

 $ MOUNT/FOREIGN DBA0:
$ BACKUP [SIMS] DBA0:SIMS.BCK/SAVE_SET
      

This command saves all files in the directory [SIMS] to a sequential-disk save set named SIMS.BCK.

Input Save-Set Qualifier

Selects the specified files for processing.

Format

input-save-set-spec/SELECT=(file-spec[,...]) output-specifier

Description

If you specify more than one file, separate the file specifications with commas and enclose the list in parentheses. Do not use a device specification when you define the files to be selected. You can use most standard wildcard characters, but you cannot use wildcard characters denoting latest version of files (;) and relative versions of files (;-n).

Note that BACKUP does not apply temporary file specification defaults within the list. Each file specification independently takes its defaults from the file specification [000000...]*.*;*.

Example

$ BACKUP DBA1:JUL20.BCK/SAVE_SET/SELECT=[SNOW]BALL.PAS [WINTER.GAME]BALL.PAS
      

This command selects a file named [SNOW]BALL.PAS from a sequential-disk save set and restores it to the directory [WINTER.GAME] on the current default device.

Input File-Selection Qualifier

Selects files dated equal to or later than the specified date and time.

Format

input-specifier/SINCE=time output-specifier

Description

The /SINCE qualifier selects files by comparing the date and time in the specified field of each file header record with the date and time you specify in the command line. The following table shows the input file-selection qualifiers you can use with /SINCE and their functions. Use only one of these qualifiers at a time in your command line.

Qualifier	Function
/BACKUP	Selects files last saved or copied by BACKUP/RECORD since the date specified. Also selects files with no BACKUP date.
/CREATED	Selects files created since the date specified.
/EXPIRED	Selects files that have expired since the date specified.
/MODIFIED	Selects files last modified since the date specified. If you specify /SINCE without another qualifier, /MODIFIED is used by default.

Specify the date and time as a delta time or as an absolute time using the format [dd-mmm-yyyy[:]][hh:mm:ss.cc]. You can also use one of the following reserved words to specify the date and time:

BACKUP	The BACKUP/RECORD operation (available only on Files--11 Structure Levels 2 and 5 volumes)
TODAY	The current day, month, and year at 00:00:00.0 o'clock
TOMORROW	24 hours after midnight last night
YESTERDAY	24 hours before midnight last night

Be sure to perform an image backup, using the BACKUP/IMAGE/RECORD command, before performing regular incremental backups. The image backup saves a copy of the entire disk and marks each file as having been saved. Regularly performed subsequent incremental backups assume an image backup was already performed and therefore will save new or modified files. If an image backup was not performed first, the incremental backups will save more files than may be necessary, in an attempt to ensure that an incremental restore will be successful.

Example

$ BACKUP [PLI.WORK]/SINCE=YESTERDAY/MODIFIED [PLI.SAV]
      

This command copies selected files in the directory [PLI.WORK] to the directory [PLI.SAV]. Only those files that have been modified since 24 hours preceding midnight last night are processed. Even though it is used in this example, the /MODIFIED qualifier is not required because its action is the default when the /SINCE qualifier is specified.

Output Save-Set Qualifier

Writes a file expiration date other than the current date to the file header label of the save set.

Format

input-specifier output-save-set-spec/TAPE_EXPIRATION[=date]

Description

When you specify the output save-set qualifier /REWIND during a save operation to magnetic tape, BACKUP checks that the expiration date of the first file on the tape has expired before initializing the tape. Initializing the tape removes access to data previously stored on the tape.

HP recommends that you specify an expiration date whenever you create a BACKUP save set on magnetic tape using /REWIND. Daily BACKUP tapes should expire in seven days, weekly BACKUP tapes should expire in one month, and monthly BACKUP tapes should expire in one year.

Specify the date in the following format:

dd:mmm:yyyy

where:

dd	is the date.
mmm	is a 3-letter abbreviation of the month.
yyyy	is the year.

BACKUP writes the expiration date into the file's HDR1 ANSI label on the tape. If you do not use the /TAPE_EXPIRATION qualifier, BACKUP uses today's date as the expiration date.

Example

$ BACKUP DBA1:
_To: MTA0:13SEPBAK.BCK/REWIND/TAPE_EXPIRATION=20-SEP-2002/LABEL=SEPW02
      

In this example, the save set file 13SEPBAK.BCK receives an expiration date of September 20, 2002. Becauses this command includes the /REWIND qualifier, 13NOVBAK.BCK is the first file on the tape and its expiration date indicates that the tape expires after seven days.

Command Qualifier

Controls whether a copy or restore operation truncates a sequential output file at the end-of-file (EOF) when creating it.

Format

/[NO]TRUNCATE input-specifier output-specifier

Description

By default, a copy or restore operation uses the allocation of the input file to determine the size of the output file. Specify /TRUNCATE if you want the output files to be truncated at the end-of-file (EOF).

Example

$ DIRECTORY/SIZE [FRANKIE]ORIGINAL.DAT
Directory DMA0:[FRANKIE]
ORIGINAL.DAT          35
Total of 1 file, 35 blocks
$ COPY ORIGINAL.DAT EXTENDED.DAT/ALLOCATION=500
$ BACKUP [FRANKIE]EXTENDED.DAT MFA0:20JUL.BCK/LABEL=WKLY03
$ BACKUP/TRUNCATE MFA0:20JUL.BCK/LABEL=WKLY03  DMA0:[FRANKIE]
      

This sequence of commands performs the following tasks:

• Determines that the file ORIGINAL.DAT is 35 blocks long.
• Copies ORIGINAL.DAT to EXTENDED.DAT, allocating 500 blocks for EXTENDED.DAT.
• Saves the file EXTENDED.DAT to a save set named 20JUL.BCK on MFA0. BACKUP writes the file allocation size in the file header record of the saved file but saves only 35 blocks in the save set.
• Restores the save set file on MFA0 to a volume mounted on DMA0 and truncates the output files at the EOF. The restored file is 35 blocks long.

Command Qualifier

Specifies that the contents of the output specifier be compared with the contents of the input specifier after a save, restore, or copy operation is completed.

Format

/VERIFY input-specifier output-specifier

Description

The /VERIFY qualifier is different from the command qualifier /COMPARE. Unlike the /VERIFY qualifier, the command qualifier /COMPARE cannot be used in a save, restore, copy, or list operation. The /VERIFY qualifier directs BACKUP to perform the copy, save, or restore operation first and then to perform the compare operation.

On file-structured copy operations, each file is compared after it is copied. On physical copy operations, the volume is compared after it is copied. For a save or restore operation, the verification is performed in a separate pass and is preceded by the following informational message:

%BACKUP-I-STARTVERIFY, starting verification pass

If a file does not compare successfully, BACKUP displays the following error message:

%BACKUP-E-VERIFYERR, verification error for block 'block-number' of 'disk:[directory]file_name.file_type;version_number'

The /VERIFY qualifier does not work on a restore or copy operation when the /NEW_VERSION output file qualifier is also used. Because the /NEW_VERSION qualifier reassigns output file versions, it is not possible to correctly associate the created output files with the input files from which they were copied.

Example

$ BACKUP/VERIFY/LOG *.LIS MFA0:LIST.BCK
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]CRE.LIS;1
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]CRETIME.LIS;1
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]EXC.LIS;1
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]NOREB.LIS;1
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]REB.LIS;1
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]SETREB.LIS;1
%BACKUP-S-COPIED, copied DISK$DEFAULT:[WONDER]VERS.LIS;1

%BACKUP-I-STARTVERIFY, starting verification pass
%BACKUP-S-COMPARED, compared DISK$DEFAULT:[WONDER]CRE.LIS;1
%BACKUP-S-COMPARED, compared DISK$DEFAULT:[WONDER]CRETIME.LIS;1
%BACKUP-S-COMPARED, compared DISK$DEFAULT:[WONDER]EXC.LIS;1
%BACKUP-S-COMPARED, compared DISK$DEFAULT:[WONDER]NOREB.LIS;1
%BACKUP-S-COMPARED, compared DISK$DEFAULT:[WONDER]REB.LIS;1
%BACKUP-S-COMPARED, compared DISK$DEFAULT:[WONDER]SETREB.LIS;1
%BACKUP-S-COMPARED, compared DISK$DEFAULT:[WONDER]VERS.LIS;1
      

This example creates a magnetic tape save set on MFA0 and starts the verification pass after the save operation is completed. The /LOG qualifier displays the file names as they are processed.

Command Qualifier

Indicates that a specific disk volume in a disk volume set is to be processed. The /VOLUME qualifier is valid only when used with the /IMAGE qualifier.

Format

/IMAGE/VOLUME= n input-specifier output-specifier

Description

The /VOLUME qualifier allows you to perform an image save, restore, or copy operation using one more disk drive than the number of disks in the input volume set. When you use /VOLUME, you must write-lock the entire input volume set.

When you perform an image copy or save operation with the /VOLUME qualifier, all disks in the input volume set must be mounted. Mount the volumes of the target volume set one at a time. Enter a separate BACKUP command for each disk in the input volume set. A save set created with the /VOLUME qualifier must be restored using the /VOLUME qualifier.

You can restore any image save set with the /VOLUME qualifier. All disks in the output volume set must be mounted. Mount the disks in the input volume set one at a time. You cannot use the command qualifier /NOINITIALIZE in the restore operation with the command qualifier /VOLUME.

In a compare operation that uses the /VOLUME qualifier to compare two disk volume sets, all disks in both volume sets must be mounted. In a selected-volume compare operation between a save set on tape and a disk volume set, all disks in the disk volume set must be mounted.

Example

$ BACKUP/IMAGE/VOLUME=3 DISK$PUBLIC DRA1:
      

This command creates a functionally equivalent copy of the third volume of a volume set named DISK$PUBLIC to DRA1. The disk mounted in DRA1 becomes the third volume of the image-copy volume set.

7.6 BACKUP Examples

Table 7-3 shows BACKUP command formats for save operations and some of the qualifiers you can use with a save operation.

Table 7-3 Save Operation Quick Reference

Command Action	Command Format and Example
Saves a file to a save set on magnetic tape	BACKUP file-spec save-set-specifier/LABEL=label $ BACKUP STRATDAT1.DAT MTA0:STRATDAT1.BCK/LABEL=TAPE01
Saves the most recent versions of files in a directory to magnetic tape	BACKUP [directory]*.*; save-set-specifier/LABEL=label $ BACKUP [LYKINS...]*.*; MTA0:1409MAR17.BCK/LABEL=WKY102
Saves a disk volume to a save set on magnetic tape	BACKUP/IMAGE ddcu: save-set-specifier/LABEL=label $ BACKUP/IMAGE DBA1: MTA0:000FEB4.BCK/LABEL=MTH101
Saves a disk volume to a multivolume save set on more than one magnetic tape drive	BACKUP/IMAGE ddcu: save-set-specifier,ddcu:.../LABEL=(label1,...) $ BACKUP/IMAGE DBA1: MTA0:17MAR.BCK,MTA1:/ - _$ LABEL=(WKY101,WKY102)
Saves a list of files to a save set on magnetic tape	BACKUP file-spec,file-spec,... save-set-specifier/LABEL=label $ BACKUP DBA1:[LYKINS...]*.PAS,DMA0:[DAKOTA...]*.PAS - _$ MTA0:PAS17MAR.BCK/LABEL=TAPE01
Saves a disk volume for incremental backups for the first time	BACKUP/RECORD/IMAGE/LOG ddcu: save-set-specifier/LABEL=label $ BACKUP/RECORD/IMAGE/LOG DBA1: MTA0:985FEB4.BCK/ - _$ LABEL=DLY101
Saves a disk volume for incremental backups (not the first time)	BACKUP/RECORD/FAST/LOG ddcu:[*...]/SINCE=BACKUP save-set-specifier/LABEL=label $ BACKUP/RECORD/FAST/LOG DBA1:[*...]/SINCE=BACKUP - _$ MTA0:988FEB4.BCK/LABEL=DLY101
Saves an unstructured disk volume	BACKUP/PHYSICAL ddcu: save-set-specifier/LABEL=label $ BACKUP/PHYSICAL DMA1: MTA0:985FEB4.BCK/LABEL=MTH101
Saves a directory to a save set on a Files--11 disk	BACKUP [directory] save-set-specifier/SAVE_SET $ BACKUP [LYKINS] DBA2:[BACKUP]1609FEB3.BCK/SAVE_SET
Saves a directory tree to a save set on magnetic tape	BACKUP [directory...] save-set-specifier/LABEL=label $ BACKUP [LYKINS...] MTA0:1612FEB3.BCK/LABEL=TAPE01
Saves a directory tree to a save set on magnetic tape and creates a listing file	BACKUP/LIST=file-spec [directory...] save-set-specifier/LABEL=label $ BACKUP/LIST=8SEP.LOG [LYKINS...] MTA0:8SEP.BCK/LABEL=WKL101
Saves a directory tree to a save set on magnetic tape using data compaction to increase the amount of data stored on a tape cartridge	BACKUP [directory...] save-set-specifier/MEDIA_FORMAT=COMPACTION $ BACKUP [TESTFILES...]*.*;* MUA0:TEST.SAV/MEDIA_FORMAT=COMPACTION/REWIND

Table 7-4 shows BACKUP command formats for restore operations and some of the qualifiers you can use with restore operations. In the examples in this table, it is assumed that save sets already exist on the magnetic tape and disk.

Table 7-4 Restore Operation Quick Reference

Command Action	Command Format and Example
Restores from save set on disk to Files--11 disk with original UICs	BACKUP save-set-specifier/SAVE_SET ddcu:[*...]/BY_OWNER=ORIGINAL $ BACKUP DBA2:[BACKUP]FEB2.BCK/SAVE_SET DBA1:[*...]- _$/BY_OWNER=ORIGINAL
Restores from a save set on magnetic tape to a Files--11 disk with original UICs	BACKUP save-set-specifier ddcu:[*...]/BY_OWNER=ORIGINAL $ BACKUP MTA0:1618FEB2.BCK DBA1:[*...]/BY_OWNER=ORIGINAL
Restores a selected file in a save set on magnetic tape to a Files--11 disk	BACKUP save-set-specifier/SELECT=file-spec file-spec $ BACKUP MTA0:FEB2.BCK/SELECT=[POUDRE]UPLIFT.PAS - _$ DBA1:[GEO.PAS]UPLIFT.PAS
Restores files with a specific UIC to a Files--11 disk	BACKUP save-set-specifier/BY_OWNER=[uic] file-spec $ BACKUP MTA0:1641FEB2.BCK/BY_OWNER=[360,052] - _$ DBA1:[LYKINS...]
Restores files to a Files--11 disk with a new UIC	BACKUP save-set-specifier file-spec/BY_OWNER=[uic] $ BACKUP MTA0:1641FEB2.BCK - _$ DBA1:[TESTS...]/BY_OWNER=[100,150]
Restores files to a Files--11 disk; if file exists, creates new version	BACKUP save-set-specifier file-spec/NEW_VERSION $ BACKUP MTA0:1641FEB2.BCK DBA1:[LYKINS...]/NEW_VERSION
Restores files to a Files--11 disk; if file exists, replaces with new version	BACKUP save-set-specifier file-spec/REPLACE $ BACKUP MTA0:1641FEB2.BCK DBA1:[LYKINS...]/REPLACE
Restores files to a Files--11 disk selecting certain files	BACKUP save-set-specifier/SELECT=file-spec file-spec $ BACKUP MTA0:1641FEB2.BCK/SELECT=[LYKINS.PAS] - _$ DBA1:[LYKINS...]
Restores a directory tree, placing files in a different subtree	BACKUP save-set-specifier/SELECT=[directory...] [directory2...] $ BACKUP MTA0:1641FEB2.BCK/SELECT=[FIELD...] - _$ DBA1:[LYKINS.NEWDATA...]
Restores a Files--11 volume from a physical save set	BACKUP/PHYSICAL save-set-specifier ddcu: $ BACKUP/PHYSICAL MTA0:26MAR.BCK DMA3:
Restores a Files--11 volume from an image save set	BACKUP/IMAGE save-set-specifier ddcu: $ BACKUP/IMAGE MTA0:17AUG.BCK DRA3:
Restores a Files--11 volume, maintaining the initialization parameters specified in the DCL command INITIALIZE	INITIALIZE ddcu: volume-name/new-parameters MOUNT/FOREIGN ddcu: BACKUP/IMAGE save-set-specifier ddcu:/NOINITIALIZE $ INITIALIZE DBA1: UTTLPACK/CLUSTER=5 $ MOUNT/FOREIGN DBA1: $ BACKUP/IMAGE MTA0:17AUG.BCK DBA1:/NOINITIALIZE

Table 7-5 shows BACKUP command formats for copy operations, including some of the qualifiers you can use with a copy operation.

Table 7-5 Copy Operation Quick Reference

Command Action	Command Format and Example
Copies a directory tree to another directory tree	BACKUP [directory...] [directory...] $ BACKUP [DAKOTA...] [SUNDANCE...]
Copies a file to another file	BACKUP file-spec file-spec $ BACKUP LOGIN.COM [.SAVE]OLDLOGIN.COM
Copies a disk volume to another disk volume	BACKUP/IMAGE ddcu: ddcu: $ BACKUP/IMAGE DBA1: DBA2:
Copies a disk volume to another disk volume using the /PHYSICAL qualifier	BACKUP/PHYSICAL ddcu: ddcu: $ BACKUP/PHYSICAL DYA1: DYA2:
Copies two disk volume sets using the /IMAGE qualifier	BACKUP/IMAGE volume-set-name ddcu:,ddcu: $ BACKUP/IMAGE USER$: DBA1:,DBA2:

Table 7-6 shows BACKUP command formats for compare operations, including some of the qualifiers you can use with a compare operation.

Table 7-6 Compare Operation Quick Reference

Command Action	Command Format and Example
Compares two Files--11 files	BACKUP/COMPARE file-spec file-spec $ BACKUP/COMPARE UPLIFT.EXE;3 UPLIFT.EXE;2
Compares a selected file from a save set and a Files--11 file	BACKUP/COMPARE save-set-specifier/select=file-spec file-spec $ BACKUP/COMPARE MTA0:FEB2.BCK/SELECT=[POUDRE]UPLIFT.PAS - _$ UPLIFT.PAS
Compares an image save set and Files--11 files	BACKUP/COMPARE/IMAGE save-set-specifier ddcu: $ BACKUP/COMPARE/IMAGE MTA0:12OCT.BCK DRA3:

Table 7-7 shows BACKUP command formats for a list operation, including some of the qualifiers you can use with a list operation.

Table 7-7 List Operation Quick Reference

Command Action	Command Format and Example
Lists the files in a save set at the terminal	BACKUP/LIST save-set-specifier $ BACKUP/LIST MTA0:1618FEB2.BCK
Lists the files in a save set, writes to a file	BACKUP/LIST=file-spec save-set-specifier $ BACKUP/LIST=NEWLIST.LIS MTA0:1618FEB2.BCK
Lists the files in a save set in full format	BACKUP/LIST/FULL save-set-specifier $ BACKUP/LIST/FULL MTA0:1618FEB2.BCK
Lists selected files in a journal file	BACKUP/LIST/JOURNAL=journal-name/selection-qualifiers $ BACKUP/LIST/JOURNAL=SYS$MANAGER:INCBACKUP - _$ /SELECT=[LYKINS.WORK...]/SINCE=1-JAN-2002